ci: main tests itself, deploys itself, and publishes the CLI

The deploy was a script somebody remembered to run. It stays that script —
docs/DEPLOYMENT.md still explains it step by step and it still works by hand —
but main now runs it, after the checks the README asks for.

Both jobs sit in one workflow deliberately. Forgejo Actions cannot make one
workflow wait on another, so a deploy in a file of its own would start beside
the tests rather than after them, and an unattended deploy that does not wait
for its tests is worse than no pipeline at all.

The CLI is mirrored rather than moved. It lives beside the API because it
mirrors that API's upload-path rules, its error wording and its endpoint
shapes: a change to the contract and the change to the client belong in one
commit, tested together. A submodule would split that into a two-repository
dance for what is one change. So the public GitHub repository is a derived
copy, force-pushed from a subtree split, and nothing is merged into it by hand.

GitHub builds the CLI on Linux and Windows, on the oldest Node it claims to
support and the newest — its path handling is the part most likely to break,
and testing both from both is not the same as running on both. Publishing is
on a release, never a merge: npm will not let a version be replaced or a name
reused, so it should happen because somebody decided to release.

Nothing here can run yet. It needs a runner registered and its secrets added,
both written down in the runbook; until then the jobs fail on their first step
and name what is missing, rather than skipping quietly and looking like they
worked.

Author: JKamsker

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# Builds and tests the CLI on the platforms it claims to run on.
+#
+# This repository is a mirror — the CLI is developed in the private monorepo
+# beside the API it speaks to, and pushed here by that repository's pipeline.
+# The checks still belong here: this is the tree people read, fork and install
+# from, and a public package that does not build is a public package nobody
+# trusts.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      # The CLI is cross-platform by design and its path handling is the part
+      # most likely to break — %APPDATA% against XDG, backslashes against
+      # forward slashes. Both are tested from both, but running on both is what
+      # actually proves it.
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        # 20 is the floor the package declares; 24 is what a fresh npx picks.
+        node: ['20', '24']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      # No runtime dependencies, so this only fetches TypeScript and the types.
+      - run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build and test
+        run: npm test
+
+      # Proves the thing npx would actually run does run, on both platforms.
+      - name: The binary starts
+        run: node dist/index.js --version

.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+# Publishes the CLI to npm.
+#
+# Deliberately not on every push to main. npm will not let a version be
+# replaced or a name be reused, so publishing is the one step here that cannot
+# be taken back — it should happen because somebody decided to release, not
+# because somebody merged.
+#
+# Cut a GitHub release whose tag is the version ("v0.2.0") and this runs.
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      dryRun:
+        description: 'Pack and check without publishing.'
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+  # Lets npm record where the package was built from, which is what makes the
+  # "Provenance" badge on the package page mean anything.
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+
+      - run: npm ci
+
+      # Never publish something that was not tested, even though CI already ran
+      # on this commit: a release can be cut from any commit, including one CI
+      # never saw.
+      - name: Build and test
+        run: npm test
+
+      # A tag that disagrees with package.json publishes a version nobody asked
+      # for, under a name the release notes do not match.
+      - name: The tag and package.json agree
+        if: github.event_name == 'release'
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          packaged="$(node -p "require('./package.json').version")"
+          if [ "$tag" != "$packaged" ]; then
+            echo "Release tag is $tag but package.json says $packaged."
+            exit 1
+          fi
+          echo "Publishing $packaged."
+
+      - name: What would be published
+        run: npm pack --dry-run
+
+      - name: Publish
+        if: github.event_name == 'release' || inputs.dryRun == false
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "$NODE_AUTH_TOKEN" ]; then
+            echo "Cannot publish: no NPM_TOKEN in this repository's Actions secrets."
+            exit 1
+          fi
+          # --access public because the package is scoped, and a scoped package
+          # is private by default however public the repository is.
+          npm publish --access public --provenance