@nimbus-sh/cli 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @nimbus-sh/cli
+
+CLI for Nimbus: scaffolding, token mint/verify, session helpers, and runtime
+cache operations.
+
+## Install
+
+```bash
+npx @nimbus-sh/cli --help
+npx @nimbus-sh/cli init my-app
+npx create-nimbus-app my-app
+```
+
+From this repository:
+
+```bash
+bun packages/cli/src/bin.ts --help
+bun packages/cli/src/bin.ts init my-app
+bun packages/cli/src/scaffold-bin.ts my-app
+```
+
+## Verbs
+
+### `nimbus init [directory]`
+
+Scaffolds a Nimbus-powered Workers project. `.` uses the current directory.
+
+```bash
+nimbus init my-nimbus
+cd my-nimbus
+npm install
+wrangler secret put JWT_SECRET
+wrangler deploy
+```
+
+### `create-nimbus-app <name>`
+
+Scaffolds a new Nimbus-powered Workers project.
+
+```bash
+create-nimbus-app my-nimbus
+cd my-nimbus
+npm install
+wrangler secret put JWT_SECRET
+wrangler deploy
+```
+
+Flags:
+
+| Flag | Default | What |
+|---|---|---|
+| `--name <wrangler-name>` | project name | Becomes the deployed Worker name. |
+| `--template <name>` | `worker-only` | Only `worker-only` ships in v0.1. |
+| `--force` | off | Overwrite existing directory. |
+
+### `nimbus token mint`
+
+```bash
+JWT_SECRET=<hex> nimbus token mint --tenant acme --sub alice [--ttl 3600]
+# Prints the JWT to stdout. Pipe with `> /tmp/jwt` or `| pbcopy`.
+```
+
+Flags:
+
+| Flag | What |
+|---|---|
+| `--tenant <id>` (required) | Sets `tn` claim. |
+| `--sub <id>` | Sets `sub` claim. |
+| `--ttl <sec>` | Token lifetime in seconds. Default 3600 (1h), max 2,592,000 (30d). |
+| `--scopes <a,b>` | Comma-separated capability scopes. |
+| `--sid <id>` | Pin token to a specific session ID. |
+
+### `nimbus token verify <token>`
+
+```bash
+JWT_SECRET=<hex> nimbus token verify eyJhbGciOi...
+# Prints the verified claims as JSON.
+```
+
+Exit codes: 0 success, 65 token-validation failure, 78 env missing.
+
+### `nimbus runtime sync`
+
+Uploads runtime blobs/manifests and updates the runtime catalog through the
+public CLI wrapper. This is the user-facing path for Python, Ruby, and clang
+runtime cache operations.
+
+```bash
+CLOUDFLARE_ACCOUNT_ID=<id> nimbus runtime sync --bucket nimbus-runtime-cache-public clang
+CLOUDFLARE_ACCOUNT_ID=<id> nimbus runtime sync --bucket nimbus-runtime-cache-public python
+CLOUDFLARE_ACCOUNT_ID=<id> nimbus runtime sync --bucket nimbus-runtime-cache-public ruby
+```
+
+Runtime versions default to the shipped catalog versions
+(`clang@binji-2020`, `python@0.29.4`, `ruby@3.3.4`) unless explicitly
+overridden as `name@version`.
+
+### `nimbus runtime list`
+
+```bash
+nimbus runtime list
+# JSON catalog: [{name, version, size_mb, license}, ...]
+```
+
+### `nimbus session new`
+
+```bash
+NIMBUS_ENDPOINT=https://my-nimbus.workers.dev nimbus session new
+# {"sessionId":"pretty-otter-1234","url":"https://.../s/pretty-otter-1234/"}
+```
+
+## Programmatic use
+
+Every verb is also exported as a function:
+
+```ts
+import { mintToken, syncRuntimes, scaffold } from '@nimbus-sh/cli';
+```
+
+`mintToken(argv)` and friends return a Promise<number> (process exit
+code). Stdout / stderr write directly via `process.stdout`/`process.stderr`.
+
+## Engines
+
+Requires Node >= 20 (for native `fetch`, `crypto.subtle`, etc.).
+
+MIT.

package/dist/bin.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * bin/nimbus — Multi-verb CLI dispatcher.
+ *
+ * Usage:
+ *   nimbus token mint  --tenant acme --sub alice [--ttl 3600]
+ *   nimbus token verify <token>
+ *   nimbus runtime sync                 # upload runtime blobs/catalog through CLI wrapper
+ *   nimbus runtime list                 # show staged runtimes
+ *   nimbus session new                  # mint a session via /new
+ *   nimbus --version
+ *   nimbus --help
+ *
+ * Design notes:
+ *   - Zero dependencies on commander/yargs. The verb table is ~50 LOC.
+ *     This keeps the install footprint tiny (matters for `npx`).
+ *   - Every verb writes JSON to stdout on success (machine-parseable),
+ *     a human-readable summary line to stderr, and exits 0. Failures
+ *     emit JSON `{ error, code }` + exit code from CLI_EXIT_CODES.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/bin.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * bin/nimbus — Multi-verb CLI dispatcher.
+ *
+ * Usage:
+ *   nimbus token mint  --tenant acme --sub alice [--ttl 3600]
+ *   nimbus token verify <token>
+ *   nimbus runtime sync                 # upload runtime blobs/catalog through CLI wrapper
+ *   nimbus runtime list                 # show staged runtimes
+ *   nimbus session new                  # mint a session via /new
+ *   nimbus --version
+ *   nimbus --help
+ *
+ * Design notes:
+ *   - Zero dependencies on commander/yargs. The verb table is ~50 LOC.
+ *     This keeps the install footprint tiny (matters for `npx`).
+ *   - Every verb writes JSON to stdout on success (machine-parseable),
+ *     a human-readable summary line to stderr, and exits 0. Failures
+ *     emit JSON `{ error, code }` + exit code from CLI_EXIT_CODES.
+ */
+import { mintToken, verifyTokenCmd } from './commands/token.js';
+import { syncRuntimes, listRuntimes } from './commands/runtime-sync.js';
+import { newSession } from './commands/session.js';
+import { CLI_VERSION } from './version.js';
+const verbs = {
+    token: {
+        mint: mintToken,
+        verify: verifyTokenCmd,
+    },
+    runtime: {
+        sync: syncRuntimes,
+        list: listRuntimes,
+    },
+    session: {
+        new: newSession,
+    },
+};
+async function main(argv) {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        printHelp();
+        return 0;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        process.stdout.write(`${CLI_VERSION}\n`);
+        return 0;
+    }
+    if (argv[0] === 'init') {
+        const { scaffold } = await import('./commands/scaffold.js');
+        return scaffold(argv.slice(1).length > 0 ? argv.slice(1) : ['.']);
+    }
+    const [namespace, verb, ...rest] = argv;
+    if (!verbs[namespace] || !verbs[namespace][verb]) {
+        process.stderr.write(`nimbus: unknown command \`${namespace} ${verb || ''}\`. Try \`nimbus --help\`.\n`);
+        return 64;
+    }
+    return verbs[namespace][verb](rest);
+}
+function printHelp() {
+    process.stdout.write(`nimbus ${CLI_VERSION}
+
+Usage:
+  nimbus token mint   --tenant <t> [--sub <s>] [--ttl <sec>] [--scopes <a,b>]
+  nimbus token verify <token>
+  nimbus runtime sync [--bucket <name>] [runtime[@version]...]
+  nimbus runtime list
+  nimbus session new [--endpoint <url>]
+  nimbus init [directory]
+
+For embedder scaffolding:
+  create-nimbus-app <project-name>
+
+Env:
+  JWT_SECRET        Shared secret for HS256 (required for token mint/verify).
+  NIMBUS_ENDPOINT   Base URL for session new. Defaults to localhost:8787.
+  CLOUDFLARE_ACCOUNT_ID  Required for runtime sync.
+`);
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`nimbus: ${err?.stack || err}\n`);
+    process.exit(70);
+});

package/dist/commands/runtime-sync.d.ts

@@ -0,0 +1,31 @@
+/**
+ * cli/commands/runtime-sync — Re-runs the runtime-bundle pipeline that
+ * populates an R2 bucket with the clang / python / ruby blobs.
+ *
+ * Two modes:
+ *   - Default (no --bucket): syncs the canonical Nimbus-operated bucket
+ *     `nimbus-runtime-cache-public` for the catalog the project ships
+ *     today. This is what we run; embedders typically don't need it.
+ *   - `--bucket <name>`: BYOA mode. Runtime names may be positional
+ *     (`nimbus runtime sync python clang`) or comma-separated via
+ *     `--runtimes python,clang`.
+ *
+ * Implementation: shells out to wrangler r2 object put for each blob
+ * listed in `@nimbus-sh/worker`'s bundled `scripts/bundle-runtime.mjs`.
+ * The actual fetch+verify+upload work lives in that script; this CLI
+ * is a thin proxy.
+ */
+/**
+ * Sync runtime blobs to an R2 bucket via the bundled
+ * `bundle-runtime.mjs` script.
+ *
+ * @example
+ * ```bash
+ * # BYOA mode — sync into your own bucket.
+ * CLOUDFLARE_ACCOUNT_ID=… nimbus runtime sync --bucket my-runtime-cache python
+ * ```
+ */
+export declare function syncRuntimes(args: string[]): Promise<number>;
+/** `nimbus runtime list` — print the catalog the SDK ships against. */
+export declare function listRuntimes(_args: string[]): Promise<number>;
+//# sourceMappingURL=runtime-sync.d.ts.map

package/dist/commands/runtime-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-sync.d.ts","sourceRoot":"","sources":["../../src/commands/runtime-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsClE;AAED,uEAAuE;AACvE,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAUnE"}

package/dist/commands/runtime-sync.js

@@ -0,0 +1,140 @@
+/**
+ * cli/commands/runtime-sync — Re-runs the runtime-bundle pipeline that
+ * populates an R2 bucket with the clang / python / ruby blobs.
+ *
+ * Two modes:
+ *   - Default (no --bucket): syncs the canonical Nimbus-operated bucket
+ *     `nimbus-runtime-cache-public` for the catalog the project ships
+ *     today. This is what we run; embedders typically don't need it.
+ *   - `--bucket <name>`: BYOA mode. Runtime names may be positional
+ *     (`nimbus runtime sync python clang`) or comma-separated via
+ *     `--runtimes python,clang`.
+ *
+ * Implementation: shells out to wrangler r2 object put for each blob
+ * listed in `@nimbus-sh/worker`'s bundled `scripts/bundle-runtime.mjs`.
+ * The actual fetch+verify+upload work lives in that script; this CLI
+ * is a thin proxy.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const nodeRequire = createRequire(import.meta.url);
+const DEFAULT_RUNTIME_VERSIONS = {
+    clang: 'binji-2020',
+    python: '0.29.4',
+    ruby: '3.3.4',
+};
+/**
+ * Sync runtime blobs to an R2 bucket via the bundled
+ * `bundle-runtime.mjs` script.
+ *
+ * @example
+ * ```bash
+ * # BYOA mode — sync into your own bucket.
+ * CLOUDFLARE_ACCOUNT_ID=… nimbus runtime sync --bucket my-runtime-cache python
+ * ```
+ */
+export async function syncRuntimes(args) {
+    const parsed = parseFlags(args);
+    const bucket = parsed.bucket ?? 'nimbus-runtime-cache-public';
+    const runtimes = parsed.runtimes.length > 0
+        ? parsed.runtimes
+        : ['clang', 'python', 'ruby'];
+    if (!process.env.CLOUDFLARE_ACCOUNT_ID) {
+        process.stderr.write('nimbus runtime sync: CLOUDFLARE_ACCOUNT_ID env var required\n');
+        return 78;
+    }
+    // Locate the bundle-runtime.mjs script in `@nimbus-sh/worker`. When
+    // installed via npm, resolve via require; in workspace dogfood, use
+    // a relative path.
+    const scriptPath = resolveBundleRuntimeScript();
+    if (!scriptPath) {
+        process.stderr.write('nimbus runtime sync: cannot locate @nimbus-sh/worker/scripts/bundle-runtime.mjs\n');
+        return 70;
+    }
+    process.stderr.write(`nimbus: syncing runtimes [${runtimes.join(', ')}] → r2://${bucket}\n`);
+    for (const rt of runtimes) {
+        const [name, explicitVersion] = rt.split('@');
+        const version = explicitVersion || DEFAULT_RUNTIME_VERSIONS[name];
+        if (!version) {
+            process.stderr.write(`nimbus runtime sync: unknown runtime "${rt}" (use name@version)\n`);
+            return 64;
+        }
+        const code = await runOne(scriptPath, [name, version, '--bucket', bucket]);
+        if (code !== 0) {
+            process.stderr.write(`nimbus runtime sync: ${rt} failed (exit ${code})\n`);
+            return code;
+        }
+    }
+    process.stdout.write(JSON.stringify({ ok: true, bucket, runtimes }) + '\n');
+    return 0;
+}
+/** `nimbus runtime list` — print the catalog the SDK ships against. */
+export async function listRuntimes(_args) {
+    // v0.1: print the static known-list. v0.2 will fetch the live
+    // catalog.json from R2.
+    const catalog = [
+        { name: 'clang', version: 'binji-2020', size_mb: 9, license: 'Apache-2.0-LLVM' },
+        { name: 'python', version: 'pyodide-0.29.4', size_mb: 10, license: 'MPL-2.0' },
+        { name: 'ruby', version: 'ruby.wasm-2.9.4', size_mb: 25, license: 'BSD-2-Clause' },
+    ];
+    process.stdout.write(JSON.stringify(catalog, null, 2) + '\n');
+    return 0;
+}
+// ── helpers ──────────────────────────────────────────────────────────
+function resolveBundleRuntimeScript() {
+    // 1. Try resolving via the @nimbus-sh/worker package (npm-installed).
+    try {
+        const packageJson = nodeRequire.resolve('@nimbus-sh/worker/package.json');
+        const script = join(dirname(packageJson), 'scripts', 'bundle-runtime.mjs');
+        if (existsSync(script))
+            return script;
+    }
+    catch {
+        // fallthrough
+    }
+    // 2. Workspace dogfood — relative path inside the monorepo.
+    try {
+        const wsUrl = new URL('../../../worker/scripts/bundle-runtime.mjs', import.meta.url);
+        const script = fileURLToPath(wsUrl);
+        return existsSync(script) ? script : null;
+    }
+    catch {
+        return null;
+    }
+}
+function runOne(scriptPath, args) {
+    return new Promise((resolveExit) => {
+        const child = spawn('node', [scriptPath, ...args], {
+            stdio: 'inherit',
+            env: process.env,
+        });
+        child.on('exit', (code) => resolveExit(code ?? 1));
+        child.on('error', (e) => {
+            process.stderr.write(`spawn error: ${e.message}\n`);
+            resolveExit(70);
+        });
+    });
+}
+function parseFlags(args) {
+    const out = { runtimes: [] };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--bucket') {
+            out.bucket = args[i + 1] ?? '';
+            i++;
+            continue;
+        }
+        if (a === '--runtimes') {
+            out.runtimes.push(...(args[i + 1] ?? '').split(',').map((s) => s.trim()).filter(Boolean));
+            i++;
+            continue;
+        }
+        if (a.startsWith('--'))
+            continue;
+        out.runtimes.push(a);
+    }
+    return out;
+}

package/dist/commands/scaffold.d.ts

@@ -0,0 +1,27 @@
+/**
+ * cli/commands/scaffold — `create-nimbus-app <project-name>`.
+ *
+ * v0.1 ships a single template: `worker-only`. The scaffolder writes:
+ *
+ *   <project>/
+ *   ├── package.json       — deps: @nimbus-sh/worker, @nimbus-sh/sdk
+ *   ├── wrangler.jsonc     — the canonical 28-LOC embedder snippet
+ *   ├── src/
+ *   │   └── index.ts       — 6 LOC default-export
+ *   ├── README.md          — install + deploy instructions
+ *   └── .gitignore         — node_modules, .wrangler
+ *
+ * The scaffolder does NOT call `wrangler login`, `wrangler secret put`,
+ * or `wrangler deploy` — those are interactive and operator-owned. We
+ * print the exact commands to run as a "next steps" trailer.
+ */
+/**
+ * Scaffold a new Nimbus project at the given directory.
+ *
+ * @param args Argv: `[project-name, ...flags]`. Flags:
+ *               `--template worker-only` (default)
+ *               `--name <wrangler-name>` (default: project-name)
+ *               `--force` overwrite existing files.
+ */
+export declare function scaffold(args: string[]): Promise<number>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/commands/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/commands/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkE9D"}

package/dist/commands/scaffold.js

@@ -0,0 +1,290 @@
+/**
+ * cli/commands/scaffold — `create-nimbus-app <project-name>`.
+ *
+ * v0.1 ships a single template: `worker-only`. The scaffolder writes:
+ *
+ *   <project>/
+ *   ├── package.json       — deps: @nimbus-sh/worker, @nimbus-sh/sdk
+ *   ├── wrangler.jsonc     — the canonical 28-LOC embedder snippet
+ *   ├── src/
+ *   │   └── index.ts       — 6 LOC default-export
+ *   ├── README.md          — install + deploy instructions
+ *   └── .gitignore         — node_modules, .wrangler
+ *
+ * The scaffolder does NOT call `wrangler login`, `wrangler secret put`,
+ * or `wrangler deploy` — those are interactive and operator-owned. We
+ * print the exact commands to run as a "next steps" trailer.
+ */
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+/**
+ * Scaffold a new Nimbus project at the given directory.
+ *
+ * @param args Argv: `[project-name, ...flags]`. Flags:
+ *               `--template worker-only` (default)
+ *               `--name <wrangler-name>` (default: project-name)
+ *               `--force` overwrite existing files.
+ */
+export async function scaffold(args) {
+    const rawProjectName = args[0];
+    const projectName = rawProjectName === '.'
+        ? basename(process.cwd())
+        : rawProjectName;
+    if (!projectName || projectName.startsWith('-')) {
+        process.stderr.write('create-nimbus-app: <project-name> required\n');
+        process.stderr.write('Usage: create-nimbus-app my-app [--name my-worker] [--force]\n');
+        return 64;
+    }
+    const parsed = parseFlags(args.slice(1));
+    const wranglerName = parsed['--name'] || projectName;
+    const force = '--force' in parsed;
+    const template = parsed['--template'] || 'worker-only';
+    if (template !== 'worker-only') {
+        process.stderr.write(`create-nimbus-app: unknown template "${template}". Only "worker-only" ships in v0.1.\n`);
+        return 64;
+    }
+    const target = rawProjectName === '.'
+        ? process.cwd()
+        : resolve(process.cwd(), projectName);
+    if (existsSync(target) && !force) {
+        process.stderr.write(`create-nimbus-app: directory exists: ${target} (use --force to overwrite)\n`);
+        return 73;
+    }
+    mkdirSync(target, { recursive: true });
+    mkdirSync(join(target, 'src'), { recursive: true });
+    writeFileSync(join(target, 'package.json'), renderPackageJson(projectName));
+    writeFileSync(join(target, 'wrangler.jsonc'), renderWranglerJsonc(wranglerName));
+    writeFileSync(join(target, 'src', 'index.ts'), renderIndexTs());
+    writeFileSync(join(target, 'README.md'), renderReadme(projectName, wranglerName));
+    writeFileSync(join(target, '.gitignore'), '.wrangler\nnode_modules\ndist\n');
+    writeFileSync(join(target, 'tsconfig.json'), renderTsconfig());
+    // Stdout — JSON for machine, friendly stderr for humans.
+    process.stdout.write(JSON.stringify({
+        ok: true,
+        path: target,
+        nextSteps: [
+            `cd ${projectName}`,
+            'npm install',
+            'npx wrangler secret put JWT_SECRET',
+            'npx wrangler deploy',
+        ],
+    }) + '\n');
+    process.stderr.write(`
+✨ Scaffolded ${projectName} at ${target}
+
+Next steps:
+  cd ${projectName}
+  npm install
+  npx wrangler secret put JWT_SECRET       # paste a 32+ char hex secret
+  npx wrangler deploy
+
+Deploy will provision the DO + R2 buckets on first run. Visit the
+returned URL and hit "Launch" to mint a session.
+
+Docs: https://github.com/AshishKumar4/Nimbus#readme
+`);
+    return 0;
+}
+// ── template renderers ──────────────────────────────────────────────
+function renderPackageJson(name) {
+    return JSON.stringify({
+        name,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        scripts: {
+            dev: 'wrangler dev --ip 0.0.0.0 --port 8787',
+            deploy: 'wrangler deploy',
+            typecheck: 'tsc --noEmit',
+        },
+        dependencies: {
+            '@nimbus-sh/worker': '^0.1.0',
+            '@nimbus-sh/sdk': '^0.1.0',
+        },
+        devDependencies: {
+            '@cloudflare/workers-types': '^4.20250327.0',
+            typescript: '^5.7.0',
+            wrangler: '^4.0.0',
+        },
+    }, null, 2) + '\n';
+}
+function renderWranglerJsonc(name) {
+    return `{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "${name}",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-04-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "placement": { "mode": "smart" },
+
+  "assets": {
+    "directory": "node_modules/@nimbus-sh/worker/public",
+    "binding": "ASSETS",
+    "run_worker_first": ["/s/*", "/new"]
+  },
+
+  // The Node-compat shims isomorphic-git + the npm installer need. Do
+  // not omit any of these — \`git clone\` will fail at runtime if any
+  // are missing.
+  "alias": {
+    "@lifo-sh/ui": "./node_modules/@nimbus-sh/worker/dist/stubs/lifo-ui.js",
+    "clean-git-ref": "clean-git-ref/lib/index.js",
+    "is-git-ref-name-valid": "is-git-ref-name-valid/index.js",
+    "crc-32": "crc-32",
+    "sha.js": "sha.js",
+    "pako": "pako",
+    "pify": "pify",
+    "diff": "diff",
+    "diff3": "diff3",
+    "ignore": "ignore",
+    "readable-stream": "readable-stream",
+    "simple-get": "simple-get",
+    "minimisted": "minimisted"
+  },
+
+  "durable_objects": {
+    "bindings": [{ "name": "NIMBUS_SESSION", "class_name": "NimbusSession" }]
+  },
+  "migrations": [
+    { "tag": "nimbus-v1", "new_sqlite_classes": ["NimbusSession"] }
+  ],
+
+  "worker_loaders": [{ "binding": "LOADER" }],
+
+  "r2_buckets": [
+    { "binding": "NPM_TARBALL_CACHE",    "bucket_name": "${name}-npm-cache" },
+    { "binding": "NPM_PACKUMENT_CACHE",  "bucket_name": "${name}-npm-packument-cache" },
+    { "binding": "NIMBUS_RUNTIME_CACHE", "bucket_name": "nimbus-runtime-cache-public" }
+  ]
+}
+`;
+}
+function renderIndexTs() {
+    return `import {
+  NimbusSession,
+  SupervisorRPC,
+  NimbusAssetsRPC,
+  NimbusLoaderRPC,
+  NimbusLoadedWorker,
+  NimbusLoadedEntrypoint,
+  NimbusDurableObjectNamespace,
+  NimbusDOStub,
+  CirrusHmrRPC,
+  createNimbusHandler,
+} from '@nimbus-sh/worker';
+
+// Re-export the DO class + every RPC class so wrangler's
+// \`durable_objects.bindings[].class_name\` lookup + \`enable_ctx_exports\`
+// auto-populate loopback bindings (env.SUPERVISOR, etc.).
+export {
+  NimbusSession,
+  SupervisorRPC,
+  NimbusAssetsRPC,
+  NimbusLoaderRPC,
+  NimbusLoadedWorker,
+  NimbusLoadedEntrypoint,
+  NimbusDurableObjectNamespace,
+  NimbusDOStub,
+  CirrusHmrRPC,
+};
+
+export default createNimbusHandler();
+`;
+}
+function renderTsconfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'ES2022',
+            moduleResolution: 'bundler',
+            lib: ['ES2022'],
+            types: ['@cloudflare/workers-types'],
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+        },
+        include: ['src/**/*.ts'],
+    }, null, 2) + '\n';
+}
+function renderReadme(name, wranglerName) {
+    return `# ${name}
+
+A Nimbus-powered Cloudflare Worker.
+
+## Setup
+
+\`\`\`bash
+npm install
+npx wrangler secret put JWT_SECRET      # paste a 32+ char hex secret
+npx wrangler deploy
+\`\`\`
+
+Then visit the URL wrangler prints. Click "Launch" to mint a session.
+
+## Custom auth
+
+By default tokens are enforced (\`JWT_SECRET\` set). To mint:
+
+\`\`\`bash
+JWT_SECRET=<your-secret> npx @nimbus-sh/cli token mint --tenant acme --sub alice
+\`\`\`
+
+Embed in a React app:
+
+\`\`\`tsx
+import { NimbusTerminal } from '@nimbus-sh/react';
+
+<NimbusTerminal
+  endpoint="https://${wranglerName}.your-account.workers.dev"
+  token={jwt}
+  tenant="acme"
+  sub="alice"
+/>
+\`\`\`
+
+## Customize
+
+Edit \`src/index.ts\`:
+
+\`\`\`ts
+import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+
+export { NimbusSession };
+
+export default createNimbusHandler({
+  hooks: {
+    onSessionStart: ({ sessionId, tenantSegment }) => {
+      console.log(\`session \${sessionId} for \${tenantSegment}\`);
+    },
+  },
+  routes: async (req, env) => {
+    if (new URL(req.url).pathname === '/api/auth/mint') {
+      const { tenant, sub } = await req.json();
+      const token = await issueNimbusToken(env, { tn: tenant, sub });
+      return Response.json({ token });
+    }
+    return null;
+  },
+});
+\`\`\`
+
+Docs: https://github.com/AshishKumar4/Nimbus
+`;
+}
+function parseFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith('--'))
+            continue;
+        if (args[i + 1] && !args[i + 1].startsWith('--')) {
+            out[a] = args[i + 1];
+            i++;
+        }
+        else {
+            out[a] = '';
+        }
+    }
+    return out;
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,6 @@
+/**
+ * cli/commands/session — `nimbus session new` — mint a session via POST /new.
+ */
+/** Mint a fresh session and print its attach URL. */
+export declare function newSession(args: string[]): Promise<number>;
+//# sourceMappingURL=session.d.ts.map

package/dist/commands/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/commands/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qDAAqD;AACrD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BhE"}

package/dist/commands/session.js

@@ -0,0 +1,45 @@
+/**
+ * cli/commands/session — `nimbus session new` — mint a session via POST /new.
+ */
+/** Mint a fresh session and print its attach URL. */
+export async function newSession(args) {
+    const parsed = parseFlags(args);
+    const endpoint = parsed['--endpoint']
+        ?? process.env.NIMBUS_ENDPOINT
+        ?? 'http://127.0.0.1:8787';
+    try {
+        const r = await fetch(`${endpoint.replace(/\/+$/, '')}/new`, {
+            method: 'POST',
+            redirect: 'manual',
+        });
+        const loc = r.headers.get('Location');
+        if (!loc) {
+            process.stderr.write(`nimbus session new: POST /new returned no Location (status ${r.status})\n`);
+            return 70;
+        }
+        const m = loc.match(/\/s\/([^/]+)/);
+        if (!m) {
+            process.stderr.write(`nimbus session new: unexpected Location: ${loc}\n`);
+            return 70;
+        }
+        const sessionId = m[1];
+        const url = `${endpoint.replace(/\/+$/, '')}/s/${sessionId}/`;
+        process.stdout.write(JSON.stringify({ sessionId, url }) + '\n');
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`nimbus session new: ${e?.message || e}\n`);
+        return 70;
+    }
+}
+function parseFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith('--'))
+            continue;
+        out[a] = args[i + 1] ?? '';
+        i++;
+    }
+    return out;
+}

package/dist/commands/token.d.ts

@@ -0,0 +1,25 @@
+/**
+ * cli/commands/token — `nimbus token mint` + `nimbus token verify`.
+ *
+ * Both verbs require `JWT_SECRET` in env. Mint writes the JWT to stdout
+ * (so `nimbus token mint --tenant acme > /tmp/jwt` works in scripts);
+ * verify parses a token from argv and prints the claims as JSON.
+ */
+/**
+ * Programmatic interface for token mint. Used by `bin.ts` and exported
+ * from `@nimbus-sh/cli` so embedder scripts can call it directly.
+ *
+ * @example
+ * ```ts
+ * import { mintToken } from '@nimbus-sh/cli';
+ * const code = await mintToken(['--tenant', 'acme', '--sub', 'alice']);
+ * ```
+ *
+ * @param args Raw CLI args (after the `token mint` prefix).
+ * @returns Process exit code (0 success, non-zero per
+ *          `CLI_EXIT_CODES` semantics).
+ */
+export declare function mintToken(args: string[]): Promise<number>;
+/** `nimbus token verify <token>` — verify + print claims as JSON. */
+export declare function verifyTokenCmd(args: string[]): Promise<number>;
+//# sourceMappingURL=token.d.ts.map

package/dist/commands/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/commands/token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B/D;AAED,qEAAqE;AACrE,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBpE"}

package/dist/commands/token.js

@@ -0,0 +1,105 @@
+/**
+ * cli/commands/token — `nimbus token mint` + `nimbus token verify`.
+ *
+ * Both verbs require `JWT_SECRET` in env. Mint writes the JWT to stdout
+ * (so `nimbus token mint --tenant acme > /tmp/jwt` works in scripts);
+ * verify parses a token from argv and prints the claims as JSON.
+ */
+import { issueNimbusToken, verifyNimbusToken } from '@nimbus-sh/sdk/token';
+import { NimbusAuthError } from '@nimbus-sh/sdk/errors';
+/**
+ * Programmatic interface for token mint. Used by `bin.ts` and exported
+ * from `@nimbus-sh/cli` so embedder scripts can call it directly.
+ *
+ * @example
+ * ```ts
+ * import { mintToken } from '@nimbus-sh/cli';
+ * const code = await mintToken(['--tenant', 'acme', '--sub', 'alice']);
+ * ```
+ *
+ * @param args Raw CLI args (after the `token mint` prefix).
+ * @returns Process exit code (0 success, non-zero per
+ *          `CLI_EXIT_CODES` semantics).
+ */
+export async function mintToken(args) {
+    const parsed = parseArgs(args, ['--tenant', '--sub', '--ttl', '--scopes', '--sid']);
+    const tn = parsed['--tenant'];
+    const sub = parsed['--sub'];
+    const ttlSec = parsed['--ttl'] ? Number(parsed['--ttl']) : undefined;
+    const scopes = parsed['--scopes'] ? parsed['--scopes'].split(',').map((s) => s.trim()) : undefined;
+    const sid = parsed['--sid'];
+    if (!tn) {
+        process.stderr.write('nimbus token mint: --tenant required\n');
+        return 64;
+    }
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        process.stderr.write('nimbus token mint: JWT_SECRET env var required\n');
+        return 78;
+    }
+    try {
+        const token = await issueNimbusToken({ JWT_SECRET: secret }, { tn, sub, scopes, sid }, ttlSec !== undefined ? { ttlMs: ttlSec * 1000 } : {});
+        process.stdout.write(`${token}\n`);
+        return 0;
+    }
+    catch (e) {
+        return reportError(e);
+    }
+}
+/** `nimbus token verify <token>` — verify + print claims as JSON. */
+export async function verifyTokenCmd(args) {
+    const token = args[0];
+    if (!token) {
+        process.stderr.write('nimbus token verify: <token> argument required\n');
+        return 64;
+    }
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        process.stderr.write('nimbus token verify: JWT_SECRET env var required\n');
+        return 78;
+    }
+    try {
+        const verified = await verifyNimbusToken({ JWT_SECRET: secret }, token);
+        process.stdout.write(`${JSON.stringify(verified, null, 2)}\n`);
+        return 0;
+    }
+    catch (e) {
+        return reportError(e);
+    }
+}
+/** Map a NimbusAuthError or unknown error to a JSON stderr report. */
+function reportError(e) {
+    if (e instanceof NimbusAuthError) {
+        process.stderr.write(`${JSON.stringify({ error: e.message, code: e.code })}\n`);
+        return e.httpStatus >= 500 ? 70 : 65;
+    }
+    process.stderr.write(`${JSON.stringify({ error: String(e?.message ?? e), code: 'E_UNKNOWN' })}\n`);
+    return 70;
+}
+/**
+ * Mini argv parser. Long flags only (`--key value` or `--key=value`).
+ * Returns a record of seen flags. Unknown flags are silently dropped
+ * (matches Unix tradition).
+ */
+function parseArgs(args, known) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith('--'))
+            continue;
+        const eq = a.indexOf('=');
+        let key, val;
+        if (eq >= 0) {
+            key = a.slice(0, eq);
+            val = a.slice(eq + 1);
+        }
+        else {
+            key = a;
+            val = args[i + 1] ?? '';
+            i++;
+        }
+        if (known.includes(key))
+            out[key] = val;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @nimbus-sh/cli — Programmatic surface.
+ *
+ * The CLI's `bin` entries (`nimbus`, `create-nimbus-app`) call these
+ * functions. Embedders building custom dev tooling can import them
+ * directly:
+ *
+ * ```ts
+ * import { mintToken, syncRuntimes } from '@nimbus-sh/cli';
+ * ```
+ */
+export { mintToken } from './commands/token.js';
+export { syncRuntimes } from './commands/runtime-sync.js';
+export { scaffold } from './commands/scaffold.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @nimbus-sh/cli — Programmatic surface.
+ *
+ * The CLI's `bin` entries (`nimbus`, `create-nimbus-app`) call these
+ * functions. Embedders building custom dev tooling can import them
+ * directly:
+ *
+ * ```ts
+ * import { mintToken, syncRuntimes } from '@nimbus-sh/cli';
+ * ```
+ */
+export { mintToken } from './commands/token.js';
+export { syncRuntimes } from './commands/runtime-sync.js';
+export { scaffold } from './commands/scaffold.js';

package/dist/scaffold-bin.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * bin/create-nimbus-app — scaffolder entry.
+ *
+ * Thin wrapper around `scaffold()` in commands/scaffold.ts. Exists as a
+ * separate bin so the eventual npm artifact can support
+ * `create-nimbus-app` without verb routing.
+ */
+export {};
+//# sourceMappingURL=scaffold-bin.d.ts.map

package/dist/scaffold-bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-bin.d.ts","sourceRoot":"","sources":["../src/scaffold-bin.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}

package/dist/scaffold-bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * bin/create-nimbus-app — scaffolder entry.
+ *
+ * Thin wrapper around `scaffold()` in commands/scaffold.ts. Exists as a
+ * separate bin so the eventual npm artifact can support
+ * `create-nimbus-app` without verb routing.
+ */
+import { scaffold } from './commands/scaffold.js';
+scaffold(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`create-nimbus-app: ${err?.stack || err}\n`);
+    process.exit(70);
+});

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hardcoded version constant. Updated by release tooling. We avoid
+ * `require('./package.json')` because that breaks under bun's
+ * single-file binary mode.
+ */
+export declare const CLI_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,6 @@
+/**
+ * Hardcoded version constant. Updated by release tooling. We avoid
+ * `require('./package.json')` because that breaks under bun's
+ * single-file binary mode.
+ */
+export const CLI_VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nimbus-sh/cli",
+  "version": "0.1.0",
+  "description": "Nimbus CLI — `create-nimbus-app` scaffolder + `token mint` + `runtime sync`.",
+  "homepage": "https://github.com/AshishKumar4/Nimbus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AshishKumar4/Nimbus.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/AshishKumar4/Nimbus/issues",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nimbus": "./dist/bin.js",
+    "create-nimbus-app": "./dist/scaffold-bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "workspace": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src && chmod +x dist/bin.js dist/scaffold-bin.js",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@nimbus-sh/sdk": "^0.1.0",
+    "@nimbus-sh/worker": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}