First working draft of build automation for libraries!

- README improveements
  * copy edits
  * coalesce directory layout docs into a table
- build.yml takes ref instead of branch
- setup action shares common setup routines
- scripts contain a `"release"` script instead of `"tag"`, which simply dispatches release.yml

pkgs/create-neon/data/templates/README.md.hbs

@@ -16,11 +16,11 @@ To run the build, run:
 $ npm run build
 ```
 
-This command uses the [@neon-rs/cli](https://github.com/neon-rs/cli) utility to assemble the binary Node addon from the output of `cargo`.
+This command uses the [@neon-rs/cli](https://www.npmjs.com/package/@neon-rs/cli) utility to assemble the binary Node addon from the output of `cargo`.
 
 ## Exploring {{package.name}}
 
-After building {{package.name}}, you can explore its exports at the Node REPL:
+After building {{package.name}}, you can explore its exports at the Node console:
 
 ```sh
 $ npm run build
@@ -34,12 +34,12 @@ $ node
 In the project directory, you can run:
 
 {{#unless packageSpec.library}}
-### `npm install`
+#### `npm install`
 
 Installs the project, including running `npm run build`.
 
 {{/unless}}
-### `npm run build`
+#### `npm run build`
 
 Builds the Node addon (`index.node`) from source, generating a release build with `cargo --release`.
 
@@ -57,7 +57,7 @@ Similar to `npm run build` but generates a debug build with `cargo`.
 
 Similar to `npm run build` but uses [cross-rs](https://github.com/cross-rs/cross) to cross-compile for another platform. Use the [`CARGO_BUILD_TARGET`](https://doc.rust-lang.org/cargo/reference/config.html#buildtarget) environment variable to select the build target.
 
-### `npm test`
+#### `npm test`
 
 Runs the unit tests by calling `cargo test`. You can learn more about [adding tests to your Rust code](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) from the [Rust book](https://doc.rust-lang.org/book/).
 
@@ -86,68 +86,32 @@ The directory structure of this project is:
 └── target/
 ```
 
-### Cargo.toml
-
-The Cargo [manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html), which informs the `cargo` command.
-
-### README.md
-
-This file.
-
+| Entry          | Purpose                                                                                                                                  |
+|----------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| `Cargo.toml`   | The Cargo [manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html), which informs the `cargo` command.                   |
+| `README.md`    | This file.                                                                                                                               |
 {{#if packageSpec}}
-### lib/
-
 {{#eq packageSpec.library.lang compare="ts"}}
-The directory containing the generated output from [tsc](https://typescriptlang.org).
-
-### ts/
-
-The directory containing the TypeScript source files.
-
-### ts/index.mts
-
-Entry point for when this library is loaded via [ESM `import`](https://nodejs.org/api/esm.html#modules-ecmascript-modules) syntax.
-
-### ts/index.cts
-
-Entry point for when this library is loaded via [CJS `require`](https://nodejs.org/api/modules.html#requireid).
-
+| `lib`          | The directory containing the generated output from [tsc](https://typescriptlang.org).                                                    |
+| `ts`           | The directory containing the TypeScript source files.                                                                                    |
+| `ts/index.mts` | Entry point for when this library is loaded via [ESM `import`](https://nodejs.org/api/esm.html#modules-ecmascript-modules) syntax.       |
+| `ts/index.cts` | Entry point for when this library is loaded via [CJS `require`](https://nodejs.org/api/modules.html#requireid).                          |
 {{else}}
-The directory containing the JavaScript source files.
-
+| `lib`          | The directory containing The directory containing the JavaScript source files.                                                           |
 {{/eq}}
-### platforms/
-
-The directory containing distributions of the binary addon backend for each platform supported by this library.
-
+| `platforms`    | The directory containing distributions of the binary addon backend for each platform supported by this library.                          |
 {{else}}
-### index.node
-
-The binary module (aka Node addon) generated by building the project. This is the main module for this package, as dictated by the `"main"` key in `package.json`.
-
-Under the hood, a [Node addon](https://nodejs.org/api/addons.html) is a [dynamically-linked shared object](https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries). The `"build"` script produces this file by copying it from within the `target/` directory, which is where the Rust build produces the shared object.
-
+| `index.node`   | The main module, a [Node addon](https://nodejs.org/api/addons.html) generated by the build and pointed to by `"main"` in `package.json`. |
 {{/if}}
-### package.json
-
-The npm [manifest file](https://docs.npmjs.com/cli/v7/configuring-npm/package-json), which informs the `npm` command.
-
-### src/
-
-The directory tree containing the Rust source code for the project.
-
-### src/lib.rs
-
-The Rust library's main module.
-
-### target/
-
-Binary artifacts generated by the Rust build.
+| `package.json` | The npm [manifest file](https://docs.npmjs.com/cli/v7/configuring-npm/package-json), which informs the `npm` command.                    |
+| `src`          | The directory tree containing the Rust source code for the project.                                                                      |
+| `src/lib.rs`   | The Rust library's main module.                                                                                                          |
+| `target`       | Binary artifacts generated by the Rust build.                                                                                            |
 
 ## Learn More
 
-To learn more about Neon, see the [Neon documentation](https://neon-bindings.com).
-
-To learn more about Rust, see the [Rust documentation](https://www.rust-lang.org).
+Learn more about:
 
-To learn more about Node, see the [Node documentation](https://nodejs.org).
+- [Neon](https://neon-bindings.com).
+- [Rust](https://www.rust-lang.org).
+- [Node](https://nodejs.org).

pkgs/create-neon/data/templates/ci/github/.env.hbs

@@ -1,4 +1,5 @@
 NODE_VERSION=18.x
 NPM_REGISTRY=https://registry.npmjs.org
+RUST_VERSION=stable
 ACTIONS_USER=github-actions
 [email protected]

pkgs/create-neon/data/templates/ci/github/build.yml.hbs

@@ -3,11 +3,10 @@ name: Build
 on:
   workflow_call:
     inputs:
-      branch:
-        description: 'Branch to check out'
-        required: false
+      ref:
+        description: 'The branch, tag, or SHA to check out'
+        required: true
         type: string
-        default: {{#$}} github.event.repository.default_branch {{/$}}
       update-version:
         description: 'Update version before building?'
         required: false
@@ -23,6 +22,11 @@ on:
         required: false
         type: boolean
         default: false
+      tag:
+        description: 'The release tag (ignored if github-release is false)'
+        required: false
+        type: string
+        default: ''
 
 jobs:
   matrix:
@@ -34,33 +38,15 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@{{versions.actions.checkout}}
         with:
-          token: {{#$}} secrets.TAG_TOKEN || github.token {{/$}}
-          ref: {{#$}} inputs.branch {{/$}}
-      - name: Set Environment Variables
-        uses: falti/dotenv-action@{{versions.actions.dotenv}}
-        with:
-          path: ./.github/workflows/.env
-          export-variables: true
-          keys-case: bypass
-      - name: Install Node
-        uses: actions/setup-node@{{versions.actions.setupNode}}
+          ref: {{#$}} inputs.ref {{/$}}
+      - name: Setup Neon Environment
+        uses: ./.github/actions/setup
         with:
-          node-version: {{#$}} env.NODE_VERSION {{/$}}
-          registry-url: {{#$}} env.NPM_REGISTRY {{/$}}
-          cache: npm
-      - name: Install Dependencies
-        shell: bash
-        run: npm ci
-      - name: Install cargo-messages
-        shell: bash
-        run: npm ci
-        working-directory: ./pkgs/cargo-messages
+          use-rust: false
       - name: Look Up Matrix Data
         id: matrixData
         shell: bash
-        run: |
-          echo "json=$(node ../../dist/cli ci github | jq -rc)" >> "$GITHUB_OUTPUT"
-        working-directory: ./pkgs/cargo-messages
+        run: echo "json=$(npx neon ci github | jq -rc)" >> "$GITHUB_OUTPUT"
       - name: Compute Matrix
         id: matrix
         uses: actions/github-script@{{versions.actions.githubScript}}
@@ -91,34 +77,64 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@{{versions.actions.checkout}}
         with:
+          ref: {{#$}} inputs.ref {{/$}}
           fetch-depth: 0
-      - name: Set Environment Variables
-        uses: falti/dotenv-action@{{versions.actions.dotenv}}
+      - name: Setup Neon Environment
+        id: neon
+        uses: ./.github/actions/setup
         with:
-          path: ./.github/workflows/.env
-          export-variables: true
-          keys-case: bypass
-      - name: Diagnostics
-        shell: bash
-        run: git log -10
-      - name: Install Dependencies
-        shell: bash
-        run: npm ci
+          use-cross: {{#$}} matrix.cfg.script == 'cross' {{/$}}
+          platform: {{#$}} matrix.cfg.platform {{/$}}
+          workspace: ./pkgs/cargo-messages
       - name: Update Version
         if: {{#$}} inputs.update-version {{/$}}
         shell: bash
         run: |
           git config --global user.name $ACTIONS_USER
           git config --global user.email $ACTIONS_EMAIL
           npm version {{#$}} inputs.version {{/$}} -m "v%s"
-      - name: Check Versions
-        shell: bash
-        run: ./test/lint/check-versions.sh
       - name: Build
-        uses: neon-actions/build@{{versions.actions.neonBuild}}
+        shell: bash
+        env:
+          CARGO_BUILD_TARGET: {{#$}} steps.neon.outputs.target {{/$}}
+          NEON_BUILD_PLATFORM: {{#$}} matrix.cfg.platform {{/$}}
+        run: npm run ${{ matrix.cfg.script }}
+      - name: Pack
+        id: pack
+        shell: bash
+        run: |
+          mkdir -p dist
+          echo filename=$(basename $(npm pack ./platforms/{{#$}} matrix.cfg.platform {{/$}} --pack-destination=./dist --json | jq -r '.[0].filename')) >> $GITHUB_OUTPUT
+      - name: Release
+        if: {{#$}} inputs.github-release {{/$}}
+        uses: softprops/action-gh-release@{{versions.actions.ghRelease}}
         with:
-          working-directory: ./pkgs/cargo-messages
-          node-version: {{#$}} env.NODE_VERSION {{/$}}
-          use-cross: {{#$}} !!matrix.cfg.cross {{/$}}
-          platform: {{#$}} matrix.cfg.platform {{/$}}
-          github-release: {{#$}} inputs.github-release {{/$}}
+          files: ./dist/{{#$}} steps.build.outputs.filename {{/$}}
+          tag_name: {{#$}} inputs.tag {{/$}}
+
+  main:
+    name: Main
+    needs: [matrix]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@{{versions.actions.checkout}}
+        with:
+          ref: {{#$}} inputs.ref {{/$}}
+          fetch-depth: 0
+      - name: Setup Neon Environment
+        uses: ./.github/actions/setup
+        with:
+          use-rust: false
+      - name: Pack
+        id: pack
+        shell: bash
+        run: |
+          mkdir -p dist
+          echo "filename=$(npm pack --pack-destination=./dist)" >> $GITHUB_OUTPUT
+      - name: Release
+        if: {{#$}} inputs.github-release {{/$}}
+        uses: softprops/action-gh-release@{{versions.actions.ghRelease}}
+        with:
+          files: ./dist/{{#$}} steps.build.outputs.filename {{/$}}
+          tag_name: {{#$}} inputs.tag {{/$}}

pkgs/create-neon/data/templates/ci/github/manifest/scripts.json.hbs

@@ -1,5 +1,4 @@
 {
-  "tag": "npm version -m 'v%s'",
-  "posttag": "git push --follow-tags",
+  "release": "gh workflow run release.yml -f dryrun=false -f version=patch",
   "dryrun": "gh workflow run publish.yml -f dryrun=true"
 }