fix: make source build and keygen cross-platform

.github/workflows/ci.yml

@@ -24,3 +24,20 @@ jobs:
         run: npm test
       - name: Build (all workspaces)
         run: npm run build
+
+  build-windows:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install
+        run: npm ci
+      - name: Build (all workspaces)
+        run: npm run build
+      - name: Smoke-test CLI bundle
+        run: node packages/cli/dist/altweb.mjs --help

CONTRIBUTING.md

@@ -30,12 +30,16 @@ guarantees, so contributions are reviewed strictly. Honest expectations below.
 ## Developing
 
 ```bash
-npm install          # workspaces: packages/core, packages/cli, packages/mcp, apps/editor, site
+npm install          # workspaces: packages/core, packages/cli, packages/mcp, apps/editor
 npm test             # core + mcp + editor suites
 npm run typecheck    # tsc across all packages
-npm run build        # CLI + MCP bundles, editor, site
+npm run build        # CLI + MCP bundles and editor
+npm run dev          # editor development server
 ```
 
+The documentation site is a separate npm project. Use `npm install --prefix
+site`, followed by `npm run dev --prefix site` or `npm run build --prefix site`.
+
 ## Licensing of contributions
 
 ALTWEB is dual-licensed: **AGPL-3.0-or-later** publicly, with commercial

README.md

@@ -40,7 +40,8 @@ agent asks for context ──► altweb-context ──► verify signature + tru
 
 ## Quickstart
 
-Both tools are on npm — nothing to clone:
+Both tools are on npm — nothing to clone. Run these commands outside a source
+checkout (inside this repository, npm resolves the local workspace package):
 
 ```bash
 # create your signing identity (deterministic from a passphrase; only the
@@ -64,6 +65,34 @@ claude mcp add altweb-context -- npx -y altweb-context
 (From source: `npm install && npm run build`, then use the bundles under
 `packages/*/dist/`.)
 
+## Running from source
+
+Node.js 20 or newer is required. From the repository root:
+
+```bash
+npm install
+npm run build
+
+# Create and save an identity with the locally built CLI
+npm run keygen
+
+# Start the editor in development mode
+npm run dev
+```
+
+The editor prints its local URL (normally `http://localhost:5173`). The CLI can
+be invoked as `node packages/cli/dist/altweb.mjs <command>`. Do not use `npx
+altweb` inside the checkout: npm may select the local workspace package, whose
+executable does not exist until it has been built.
+
+The documentation site is intentionally a separate npm project rather than a
+workspace. To run it locally:
+
+```bash
+npm install --prefix site
+npm run dev --prefix site
+```
+
 Trust a signer by adding its **full public key** to `~/.altweb/trusted-keys.json`
 (the `UNTRUSTED_KEY` refusal message hands you the ready-made entry; the short
 fingerprint is a human label, not the trust anchor):

package.json

@@ -19,6 +19,8 @@
     "apps/*"
   ],
   "scripts": {
+    "dev": "npm run dev -w @altweb/editor",
+    "keygen": "npm run build -w altweb && node packages/cli/dist/altweb.mjs keygen --save",
     "test": "npm run test:run -w @altweb/core && npm run test:run -w altweb-context && npm run test:run -w @altweb/editor",
     "test:run": "npm run test:run -w @altweb/core && npm run test:run -w altweb-context && npm run test:run -w @altweb/editor",
     "typecheck": "npm run typecheck --workspaces --if-present",

packages/cli/README.md

@@ -10,6 +10,11 @@ MCP loader: [`altweb-context`](https://www.npmjs.com/package/altweb-context)
 
 ## Quick start
 
+These `npx` commands install the published package. From a source checkout,
+first run `npm install && npm run build`, then replace `npx altweb` with
+`node packages/cli/dist/altweb.mjs` (from the repository root). For the saved
+key-generation flow, `npm run keygen` is also available at the repository root.
+
 ```bash
 # verify a capsule — file, #hash URL, or raw hash; fully offline, no network
 npx altweb verify page.altweb.html

packages/cli/package.json

@@ -35,7 +35,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/altweb.mjs --external:jsdom --banner:js='#!/usr/bin/env node'",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/altweb.mjs --external:jsdom --banner:js=\"#!/usr/bin/env node\"",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },

packages/mcp/package.json

@@ -36,7 +36,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/altweb-context.mjs --external:jsdom --banner:js='#!/usr/bin/env node'",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/altweb-context.mjs --external:jsdom --banner:js=\"#!/usr/bin/env node\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:run": "vitest run",