@1agh/maude 0.23.0 → 0.24.0

package/cli/commands/help.mjs

@@ -19,6 +19,16 @@ COMMANDS
         against the flow plugin's config.schema.json. Values that parse as
         JSON (numbers, booleans, arrays, objects) are stored typed.
 
+  cache get <layer> <key> [--ttl-ms N]
+  cache put <layer> <key> [file] [--meta JSON]
+  cache list | stats | inspect <layer> [key] | clear [layer]
+        Inspect and manage the sidecar cache (.ai/cache/, Phase C / DDR-061)
+        that reuses expensive cross-session work (domain research, codebase
+        scans, design-context parsing, security reviews). 'get'/'put' are the
+        programmatic surface plugin commands call (maude on PATH is the reachable
+        contract — see DDR-061); 'list' shows layers + sizes; 'stats' shows
+        hit-rate; 'inspect' pretty-prints entries; 'clear' wipes a layer or all.
+
   design serve [--port N] [--root PATH]
         Start the design plugin's dev server in the current repo. Equivalent
         to invoking 'claude-design-server'. Forwards all remaining args.
@@ -31,6 +41,20 @@ COMMANDS
         full discovery. --no-discovery uses Recommended defaults; --discovery-
         payload reads pre-computed answers from JSON.
 
+  design <screenshot|server-up|prep|slug|bootstrap-check|runtime-health
+          |smoke|canvas-edit|handoff|asset-sweep|visual-sanity> [args]
+        Dispatch to the dev-server's bundled bash helper of the same name.
+        maude resolves it from its own package root and sets CLAUDE_PLUGIN_ROOT
+        for the child; stdout/stderr/exit-code pass straight through. This is
+        the contract plugin markdown uses instead of a raw bin path (DDR-062).
+        See 'maude design help' for usage.
+
+  scenario-report <run-dir> [--out <path>]
+        Deterministically generate the mechanical sections of a cross-platform
+        scenario report.md (TL;DR, counter-delta parity, per-step pivot, path
+        listing) from a scenario run directory. The LLM authors only the prose
+        sections. Used by /flow:scenario + the scenario-runner agent (DDR-061).
+
   hub serve [--port N] [--data PATH] [--secret HEX] [--insecure-http] [--dev]
         Start the self-hostable Yjs sync hub (Phase 9). Defaults to port 1234,
         data dir ./data. --dev mints a mau_dev_<hex> token + prints the
@@ -43,6 +67,11 @@ COMMANDS
   hub status [URL] [--json]
         Probe a hub's /health endpoint. URL defaults to http://localhost:1234.
 
+  preflight --plugin <design|flow> [--json|--shell-export|--warn-only] [--cache PATH]
+        Run a plugin's dependency health check (the engine behind 'doctor').
+        Plugin bin scripts + hooks call this via PATH instead of a relative
+        cli/lib path that the marketplace never copies beside a plugin (DDR-061).
+
   doctor [--plugin <name>] [--fix] [--json]
         Unified workspace health check. Reports missing dependencies, config
         schema errors, stack drift, and missing quality-gate declarations in
@@ -57,8 +86,13 @@ EXAMPLES
   maude init --name acme-app
   maude config set platforms '["web-desktop","web-mobile"]'
   maude config get motion.complex
+  maude cache list
+  maude cache clear research/domain
   maude design serve --port 4399
   maude design init --no-discovery --name acme-app
+  maude design slug "Some Canvas Name"
+  maude design smoke --changed-only
+  maude scenario-report .ai/device/scenario-runs/signup/2026-05-29-1200
   maude hub serve --dev
   maude hub token generate --label alice
   maude hub status http://localhost:1234

package/cli/commands/hub.mjs

@@ -1,16 +1,16 @@
 // maude hub — self-hostable Yjs sync hub control plane.
 //
-// Phase 9 Task 2 (minimal subset): serve + token generate + status.
-// Token rotate, deploy fly|docker land in subsequent slices.
+// Phase 9 Task 2 + Task 7: serve + token generate|rotate + status + deploy.
 // See .ai/plans/phase-9-self-hosted-hub-file-sync.md.
 
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import { parseArgs } from '../lib/argv.mjs';
 
-const SUBCOMMANDS = new Set(['serve', 'token', 'status', 'help']);
+const SUBCOMMANDS = new Set(['serve', 'token', 'status', 'deploy', 'help']);
 
 export async function run({ args, pkgRoot }) {
   const { positional } = parseArgs(args);
@@ -28,50 +28,80 @@ export async function run({ args, pkgRoot }) {
   if (sub === 'serve') return runServe({ args, pkgRoot });
   if (sub === 'token') return runToken({ args, pkgRoot });
   if (sub === 'status') return runStatus({ args });
+  if (sub === 'deploy') return runDeploy({ args, pkgRoot });
 }
 
 function usage() {
-  return `maude hub <serve|token|status> [options]
+  return `maude hub <serve|token|status|deploy> [options]
 
   serve [--port N] [--data PATH] [--secret HEX] [--insecure-http] [--dev]
         Start the self-hostable Yjs sync hub in the current process tree.
         --port           listen port (default 1234, env PORT)
-        --data           hub.db + tokens.json dir (default ./data, env DATA_DIR)
+        --data           hub.db + tokens.db dir (default ./data, env DATA_DIR)
         --secret         HUB_SECRET escape-hatch token (env HUB_SECRET).
                          If unset on an empty hub, a one-time bootstrap link is
                          printed to logs — open it in a browser to claim admin.
         --insecure-http  cosmetic log-only flag for non-TLS dev
         --dev            generate a one-shot mau_dev_<hex> token, print the
                          connect command, then run the hub. Convenience for
-                         contributor onboarding — drops tokens.json on exit
-                         is NOT performed (tokens persist; clean by hand).
+                         contributor onboarding — token persists in tokens.db
+                         after exit (clean the --data dir by hand to reset).
 
         On boot the hub prints its /admin URL. The admin UI generates invite
         tokens, lists peers, and rotates tokens without shelling into the host.
 
-  token generate --label NAME [--data PATH] [--dev]
-        Generate a new mau_<32hex> token and append it to
-        <data>/tokens.json with the given label. Prints the raw token ONCE,
+  token generate --label NAME [--data PATH] [--dev] [--scope SCOPE]
+        Generate a new mau_<32hex> token and store it (HMAC-hashed) in
+        <data>/tokens.db with the given label. Prints the raw token ONCE,
         plus the ready-to-paste 'maude design link' connect command.
 
         --dev produces a mau_dev_<hex> token (convention only — same auth).
+        --scope '*' mints a hub-wide token (authorizes any canvas). Omitted →
+                 the scope defaults to the label (DDR-053). Canvas sync uses a
+                 flat per-canvas slug as the documentName, so a label-scoped
+                 token will NOT authorize a real canvas — pass --scope '*' for
+                 a peer that syncs canvases (this is what /admin invites do).
 
         Equivalent to the "Generate invite" button in the /admin UI — use
         whichever is more convenient for the deploy.
 
+  token rotate --label NAME [--data PATH]
+        Invalidate the named token and mint a fresh value with the same label
+        + scope. Prints the new raw token ONCE. New connections with the OLD
+        token are rejected immediately; ALREADY-CONNECTED peers stay until they
+        reconnect — use the /admin UI "Rotate" button (kicks live sessions) or
+        restart the hub to force-disconnect them now.
+
   status [URL] [--json]
         HTTP GET <url>/health, print uptime/version/token-count/peers. URL
         defaults to http://localhost:1234. --json emits the raw response.
 
+  deploy <fly|docker> [--name NAME] [--region CODE] [--tag TAG] [--out DIR] [--force]
+        Emit the deploy templates for the chosen target into the current
+        directory (or --out DIR) with placeholders substituted, then print the
+        exact commands to run next. Does NOT execute fly/docker for you —
+        review the emitted files first, then run the printed command.
+
+        fly     → fly.toml (+ reuses plugins/design/hub/Dockerfile).
+                  --name   app name (default maude-hub-<rand>)
+                  --region Fly region code (default iad)
+        docker  → docker-compose.yml + Caddyfile (universal — Lightsail, EC2,
+                  Hetzner, DigitalOcean, Coolify, home server).
+                  --tag    ghcr.io/1agh/maude-hub image tag (default latest)
+
 NOTES
-  Local dev only in v1.1 Task 2 slice — production-install packaging
-  (adding plugins/design/hub to package.json:files + dep hoisting) lands
-  in a follow-up slice. For now, run inside a 'maude' source checkout.
+  serve / token / deploy run inside a 'maude' source checkout (they read the
+  bundled hub workspace at plugins/design/hub). Production hubs run the
+  published Docker image (ghcr.io/1agh/maude-hub) — see 'maude hub deploy'.
+  status works from anywhere (plain HTTP GET against /health).
 
 EXAMPLES
   maude hub serve --port 4400
   maude hub token generate --label alice
+  maude hub token rotate --label alice
   maude hub status http://localhost:4400
+  maude hub deploy fly --name maude-hub-acme --region fra
+  maude hub deploy docker --tag latest --out ./deploy
 
   # Recommended flow on a fresh deploy:
   #   1. maude hub serve            → copy bootstrap link from logs
@@ -106,11 +136,12 @@ async function runServe({ args, pkgRoot }) {
 
   if (flags.dev) {
     const dataDir = env.DATA_DIR ?? resolve(process.cwd(), 'data');
+    if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
     const { addToken } = await import(resolveHubModule(hubRoot, 'src/tokens.mjs'));
     const port = env.PORT ?? '1234';
     const record = addToken(dataDir, { label: 'dev', dev: true });
     process.stdout.write(
-      `[hub] --dev token written to ${dataDir}/tokens.json:\n      label: ${record.label}\n      value: ${record.value}\n\n      Connect from a peer:\n        maude design link http://localhost:${port} --token=${record.value}\n\n`
+      `[hub] --dev token written to ${dataDir}/tokens.db:\n      label: ${record.label}\n      value: ${record.value}\n\n      Connect from a peer:\n        maude design link http://localhost:${port} --token=${record.value}\n\n`
     );
   }
 
@@ -132,10 +163,9 @@ async function runToken({ args, pkgRoot }) {
   const tail = args.slice(args.indexOf('token') + 1);
   const op = tail[0];
 
-  if (op !== 'generate') {
+  if (op !== 'generate' && op !== 'rotate') {
     process.stderr.write(
-      `maude hub token: only "generate" is supported in v1.1 Task 2 slice.\n` +
-        `"rotate" lands in a follow-up. Use "generate" with --label to mint a new token.\n`
+      `maude hub token: unknown op "${op ?? ''}". Use "generate" or "rotate" with --label.\n`
     );
     process.exit(2);
   }
@@ -143,21 +173,56 @@ async function runToken({ args, pkgRoot }) {
   const { flags } = parseArgs(tail.slice(1), { booleans: ['dev'] });
   const label = flags.label;
   if (!label || typeof label !== 'string') {
-    process.stderr.write('maude hub token generate: --label <name> is required.\n');
+    process.stderr.write(`maude hub token ${op}: --label <name> is required.\n`);
     process.exit(2);
   }
   const dataDir = flags.data ? resolve(String(flags.data)) : resolve(process.cwd(), 'data');
 
   const hubRoot = findHubRoot(pkgRoot);
   if (!hubRoot) {
-    process.stderr.write('maude hub token generate: hub workspace not found.\n');
+    process.stderr.write(`maude hub token ${op}: hub workspace not found.\n`);
     process.exit(1);
   }
-  const { addToken } = await import(resolveHubModule(hubRoot, 'src/tokens.mjs'));
-  const record = addToken(dataDir, { label, dev: !!flags.dev });
+  const { addToken, rotateToken } = await import(resolveHubModule(hubRoot, 'src/tokens.mjs'));
+
+  // better-sqlite3 won't create the parent dir; the running hub does this in
+  // createHub, but a CLI generate against a fresh --data path must too.
+  if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
+
+  let record;
+  if (op === 'rotate') {
+    try {
+      record = rotateToken(dataDir, label);
+    } catch (err) {
+      process.stderr.write(`maude hub token rotate: ${err.message}\n`);
+      process.exit(1);
+    }
+  } else {
+    // --scope '*' mints a hub-wide token (authorizes any documentName); an
+    // explicit value scopes it to that prefix. Omitted → addToken defaults the
+    // scope to the label (DDR-053 §3). NOTE: canvas sync uses flat per-canvas
+    // slugs as the documentName, so a label-scoped token does NOT authorize a
+    // canvas unless its label equals the slug — pass --scope '*' for sync use.
+    const scope = typeof flags.scope === 'string' ? flags.scope : undefined;
+    record = addToken(dataDir, {
+      label,
+      dev: !!flags.dev,
+      ...(scope !== undefined ? { scope } : {}),
+    });
+  }
 
+  const verb = op === 'rotate' ? 'rotated' : 'written';
+  const liveNote =
+    op === 'rotate'
+      ? 'Old token is rejected on new connections immediately. Already-connected\npeers persist until they reconnect — use the /admin UI "Rotate" button (kicks\nlive sessions) or restart the hub to force-disconnect them now.\n'
+      : 'Restart the hub if it is already running for the new token to take effect.\n';
+  const shownScope = record.scope ?? '*';
+  const scopeNote =
+    shownScope === '*'
+      ? 'hub-wide — authorizes any canvas'
+      : `only authorizes documentName "${shownScope}" or "${shownScope}/…" — canvas sync uses flat slugs, so pass --scope '*' for whole-hub sync`;
   process.stdout.write(
-    `[hub] token written to ${dataDir}/tokens.json:\n  label:      ${record.label}\n  value:      ${record.value}\n  created:    ${new Date(record.createdAt).toISOString()}\n\nConnect from a peer (replace HOST):\n  maude design link https://HOST --token=${record.value}\n\nRestart the hub if it is already running for the new token to take effect.\n`
+    `[hub] token ${verb} in ${dataDir}/tokens.db:\n  label:      ${record.label}\n  value:      ${record.value}\n  scope:      ${shownScope} (${scopeNote})\n  created:    ${new Date(record.createdAt).toISOString()}\n\nConnect from a peer (replace HOST):\n  maude design link https://HOST --token=${record.value}\n\n${liveNote}`
   );
 }
 
@@ -194,17 +259,177 @@ async function runStatus({ args }) {
   }
 
   const uptimeS = Math.round((payload.uptimeMs ?? 0) / 1000);
+  // `dataDir` is omitted from the unauthenticated /health payload (it's a
+  // server filesystem path — recon over-share). Only print it if present.
+  const dataDirLine = payload.dataDir ? `  dataDir:    ${payload.dataDir}\n` : '';
   process.stdout.write(
-    `Maude Hub @ ${url}\n` +
-      `  ok:         ${payload.ok}\n` +
-      `  version:    ${payload.version}\n` +
-      `  uptime:     ${formatDuration(uptimeS)}\n` +
-      `  port:       ${payload.port}\n` +
-      `  dataDir:    ${payload.dataDir}\n` +
-      `  tokens:     ${payload.tokenCount} (mode: ${payload.authMode})\n`
+    `Maude Hub @ ${url}
+  ok:         ${payload.ok}
+  version:    ${payload.version}
+  uptime:     ${formatDuration(uptimeS)}
+  port:       ${payload.port}
+${dataDirLine}  tokens:     ${payload.tokenCount} (mode: ${payload.authMode})
+`
   );
 }
 
+// ---------------------------------------------------------------- deploy
+
+const VALID_TARGETS = new Set(['fly', 'docker']);
+// Fly app names: lowercase alnum + hyphen, must start/end alnum.
+const FLY_NAME_REGEX = /^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/;
+const REGION_REGEX = /^[a-z]{3}$/;
+const IMAGE_TAG_REGEX = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
+
+function runDeploy({ args, pkgRoot }) {
+  const tail = args.slice(args.indexOf('deploy') + 1);
+  const { flags, positional } = parseArgs(tail, { booleans: ['force'] });
+  const target = positional[0];
+
+  if (!target || !VALID_TARGETS.has(target)) {
+    process.stderr.write(
+      `maude hub deploy: target must be one of ${[...VALID_TARGETS].join(' | ')} (got "${target ?? ''}").\n`
+    );
+    process.exit(2);
+  }
+
+  const hubRoot = findHubRoot(pkgRoot);
+  if (!hubRoot) {
+    process.stderr.write(
+      'maude hub deploy: hub workspace not found.\n\n' +
+        'Deploy templates ship in the maude source tree. Run inside a checkout,\n' +
+        'or clone https://github.com/1aGh/maude and run from there.\n'
+    );
+    process.exit(1);
+  }
+
+  const outDir = flags.out ? resolve(String(flags.out)) : process.cwd();
+
+  if (target === 'fly') return deployFly({ hubRoot, outDir, flags });
+  return deployDocker({ hubRoot, outDir, flags });
+}
+
+function deployFly({ hubRoot, outDir, flags }) {
+  const appName = flags.name ? String(flags.name) : `maude-hub-${randHex(4)}`;
+  if (!FLY_NAME_REGEX.test(appName)) {
+    process.stderr.write(
+      `maude hub deploy fly: invalid --name "${appName}" (lowercase alphanumeric + hyphen, 2-63 chars).\n`
+    );
+    process.exit(2);
+  }
+  const region = flags.region ? String(flags.region) : 'iad';
+  if (!REGION_REGEX.test(region)) {
+    process.stderr.write(
+      `maude hub deploy fly: invalid --region "${region}" (3-letter Fly code, e.g. iad, fra, nrt).\n`
+    );
+    process.exit(2);
+  }
+
+  const flyToml = renderTemplate(hubRoot, 'fly.toml.template', {
+    APP_NAME: appName,
+    REGION: region,
+  });
+  const flyOut = resolve(outDir, 'fly.toml');
+  guardOverwrite(flyOut, flags.force, 'fly.toml');
+  writeFileSync(flyOut, flyToml, 'utf8');
+
+  // The Dockerfile is referenced by fly.toml [build]; copy it alongside so a
+  // `fly deploy` from outDir finds it (Fly builds remotely from the context).
+  const dockerfileSrc = resolve(hubRoot, 'Dockerfile');
+  const dockerfileOut = resolve(outDir, 'Dockerfile');
+  if (existsSync(dockerfileSrc) && (flags.force || !existsSync(dockerfileOut))) {
+    copyFileSync(dockerfileSrc, dockerfileOut);
+  }
+
+  process.stdout.write(
+    `[hub deploy fly] wrote:
+  ${flyOut}
+  ${dockerfileOut} (copied)
+
+App:    ${appName}
+Region: ${region}
+URL:    https://${appName}.fly.dev
+
+Next steps (review fly.toml first, then run):
+  fly launch --copy-config --no-deploy --name ${appName} --region ${region}
+  fly volumes create maude_hub_data --region ${region} --size 3 --yes
+  fly deploy
+
+After deploy, the boot logs print a single-use /admin bootstrap link.
+Open it → "Generate invite" → copy the \`maude design link …\` command.
+Hub auth uses the token store; HUB_SECRET stays unset unless you want a
+headless escape hatch (\`fly secrets set HUB_SECRET=$(openssl rand -hex 32)\`).
+`
+  );
+}
+
+function deployDocker({ hubRoot, outDir, flags }) {
+  const tag = flags.tag ? String(flags.tag) : 'latest';
+  if (!IMAGE_TAG_REGEX.test(tag)) {
+    process.stderr.write(`maude hub deploy docker: invalid --tag "${tag}".\n`);
+    process.exit(2);
+  }
+
+  const compose = renderTemplate(hubRoot, 'docker-compose.yml.template', { IMAGE_TAG: tag });
+  const composeOut = resolve(outDir, 'docker-compose.yml');
+  guardOverwrite(composeOut, flags.force, 'docker-compose.yml');
+  writeFileSync(composeOut, compose, 'utf8');
+
+  // Caddyfile uses {$ENV} runtime substitution — no placeholders to render.
+  const caddySrc = resolve(hubRoot, 'Caddyfile.template');
+  const caddyOut = resolve(outDir, 'Caddyfile');
+  guardOverwrite(caddyOut, flags.force, 'Caddyfile');
+  copyFileSync(caddySrc, caddyOut);
+
+  process.stdout.write(
+    `[hub deploy docker] wrote:
+  ${composeOut}
+  ${caddyOut}
+
+Image: ghcr.io/1agh/maude-hub:${tag}
+
+Next steps (point DNS at this box, then run):
+  cat > .env <<EOF
+  HUB_SECRET=$(openssl rand -hex 32)
+  PUBLIC_DOMAIN=maude-hub.example.com
+  ACME_EMAIL=you@example.com
+  EOF
+  docker compose up -d
+  docker compose logs hub          # copy the single-use /admin bootstrap link
+
+Caddy fetches a Let's Encrypt cert for PUBLIC_DOMAIN automatically and
+proxies WSS to the hub. Works on Lightsail, EC2, Hetzner, DigitalOcean,
+Coolify, or a home server. See the hub-deploy docs for per-provider notes.
+`
+  );
+}
+
+function renderTemplate(hubRoot, name, vars) {
+  const path = resolve(hubRoot, name);
+  if (!existsSync(path)) {
+    process.stderr.write(`maude hub deploy: template not found: ${path}\n`);
+    process.exit(1);
+  }
+  let out = readFileSync(path, 'utf8');
+  for (const [key, value] of Object.entries(vars)) {
+    out = out.replaceAll(`{{${key}}}`, value);
+  }
+  return out;
+}
+
+function guardOverwrite(path, force, label) {
+  if (existsSync(path) && !force) {
+    process.stderr.write(
+      `maude hub deploy: ${label} already exists at ${path}. Pass --force to overwrite.\n`
+    );
+    process.exit(1);
+  }
+}
+
+function randHex(bytes) {
+  return randomBytes(bytes).toString('hex');
+}
+
 // ---------------------------------------------------------------- helpers
 
 function findHubRoot(pkgRoot) {

package/cli/commands/hub.test.mjs

@@ -3,7 +3,7 @@
 
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { test } from 'node:test';
@@ -32,8 +32,10 @@ function withDataDir(fn) {
 test('hub help prints subcommand summary on stdout', () => {
   const res = runCli(['hub', 'help']);
   assert.equal(res.status, 0, res.stderr);
-  assert.match(res.stdout, /maude hub <serve\|token\|status>/);
+  assert.match(res.stdout, /maude hub <serve\|token\|status\|deploy>/);
   assert.match(res.stdout, /token generate --label NAME/);
+  assert.match(res.stdout, /token rotate --label NAME/);
+  assert.match(res.stdout, /deploy <fly\|docker>/);
 });
 
 test('hub token generate without --label exits 2', () => {
@@ -75,6 +77,128 @@ test('hub token generate --dev uses mau_dev_ prefix', () => {
   });
 });
 
+test("hub token generate --scope '*' mints a hub-wide (wildcard) token", () => {
+  withDataDir((dataDir) => {
+    // Array-arg spawn (no shell) → '*' is passed literally, not glob-expanded.
+    const res = runCli([
+      'hub',
+      'token',
+      'generate',
+      '--label',
+      'peer',
+      '--scope',
+      '*',
+      '--data',
+      dataDir,
+    ]);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /scope:\s+\*/);
+    const { tokens } = readTokens(dataDir);
+    assert.equal(tokens.length, 1);
+    // Wildcard is stored as NULL and surfaced as '*' — authorizes any documentName.
+    assert.equal(tokens[0].scope, '*');
+  });
+});
+
+test('hub token generate --scope <value> binds the token to that documentName prefix', () => {
+  withDataDir((dataDir) => {
+    const res = runCli([
+      'hub',
+      'token',
+      'generate',
+      '--label',
+      'peer',
+      '--scope',
+      'team-x',
+      '--data',
+      dataDir,
+    ]);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /scope:\s+team-x/);
+    assert.equal(readTokens(dataDir).tokens[0].scope, 'team-x');
+  });
+});
+
+test('hub token generate without --scope defaults the scope to the label (DDR-053)', () => {
+  withDataDir((dataDir) => {
+    runCli(['hub', 'token', 'generate', '--label', 'alice', '--data', dataDir]);
+    assert.equal(readTokens(dataDir).tokens[0].scope, 'alice');
+  });
+});
+
+test('hub token rotate mints a fresh value for an existing label', () => {
+  withDataDir((dataDir) => {
+    const gen = runCli(['hub', 'token', 'generate', '--label', 'alice', '--data', dataDir]);
+    const firstValue = /value:\s+(mau_[0-9a-f]{32})/.exec(gen.stdout)?.[1];
+    assert.ok(firstValue, 'generate printed a value');
+
+    const rot = runCli(['hub', 'token', 'rotate', '--label', 'alice', '--data', dataDir]);
+    assert.equal(rot.status, 0, rot.stderr);
+    const rotatedValue = /value:\s+(mau_[0-9a-f]{32})/.exec(rot.stdout)?.[1];
+    assert.ok(rotatedValue, 'rotate printed a value');
+    assert.notEqual(rotatedValue, firstValue, 'rotate changed the value');
+    assert.match(rot.stdout, /rotated in/);
+    // Still exactly one token under that label.
+    assert.equal(readTokens(dataDir).tokens.length, 1);
+  });
+});
+
+test('hub token rotate on a missing label exits 1', () => {
+  withDataDir((dataDir) => {
+    const res = runCli(['hub', 'token', 'rotate', '--label', 'ghost', '--data', dataDir]);
+    assert.equal(res.status, 1);
+    assert.match(res.stderr, /no token with label "ghost"/);
+  });
+});
+
+test('hub deploy fly emits fly.toml + Dockerfile with substituted placeholders', () => {
+  withDataDir((outDir) => {
+    const res = runCli([
+      'hub',
+      'deploy',
+      'fly',
+      '--name',
+      'maude-hub-test',
+      '--region',
+      'fra',
+      '--out',
+      outDir,
+    ]);
+    assert.equal(res.status, 0, res.stderr);
+    const flyToml = readFileSync(join(outDir, 'fly.toml'), 'utf8');
+    assert.match(flyToml, /app = "maude-hub-test"/);
+    assert.match(flyToml, /primary_region = "fra"/);
+    assert.doesNotMatch(flyToml, /\{\{/, 'no unsubstituted placeholders');
+    assert.ok(existsSync(join(outDir, 'Dockerfile')), 'Dockerfile copied alongside');
+  });
+});
+
+test('hub deploy docker emits compose + Caddyfile with the image tag', () => {
+  withDataDir((outDir) => {
+    const res = runCli(['hub', 'deploy', 'docker', '--tag', 'v9.9.9', '--out', outDir]);
+    assert.equal(res.status, 0, res.stderr);
+    const compose = readFileSync(join(outDir, 'docker-compose.yml'), 'utf8');
+    assert.match(compose, /ghcr\.io\/1agh\/maude-hub:v9\.9\.9/);
+    assert.doesNotMatch(compose, /\{\{/, 'no unsubstituted placeholders');
+    assert.ok(existsSync(join(outDir, 'Caddyfile')), 'Caddyfile emitted');
+  });
+});
+
+test('hub deploy refuses to overwrite without --force', () => {
+  withDataDir((outDir) => {
+    runCli(['hub', 'deploy', 'docker', '--out', outDir]);
+    const res = runCli(['hub', 'deploy', 'docker', '--out', outDir]);
+    assert.equal(res.status, 1);
+    assert.match(res.stderr, /already exists.*--force/s);
+  });
+});
+
+test('hub deploy with an unknown target exits 2', () => {
+  const res = runCli(['hub', 'deploy', 'kubernetes']);
+  assert.equal(res.status, 2);
+  assert.match(res.stderr, /target must be one of/);
+});
+
 test('hub status against an unreachable URL exits 1 with diagnostic', () => {
   const res = runCli(['hub', 'status', 'http://127.0.0.1:1']);
   assert.equal(res.status, 1);

package/cli/commands/init.mjs

@@ -74,6 +74,9 @@ export async function run({ args, pkgRoot }) {
   const result = await copyTree(skeleton, aiDir, {
     force: !!flags.force,
     dryRun: !!flags['dry-run'],
+    // npm strips `.gitignore` from published tarballs, so the cache-ignore
+    // template ships as `gitignore` and is renamed to `.gitignore` on copy.
+    rename: (name) => (name === 'gitignore' ? '.gitignore' : name),
     transformMatch: (p) => TEMPLATED.some((t) => p.endsWith(t)),
     transform: ({ srcPath, contents }) => {
       let out = contents.replaceAll(PLACEHOLDER, projectName);

package/cli/commands/preflight.mjs

@@ -0,0 +1,11 @@
+import { runPreflight } from '../lib/preflight.mjs';
+
+// `maude preflight --plugin <design|flow> [--json|--shell-export|--warn-only|--quiet] [--cache PATH]`
+// Thin command over cli/lib/preflight.mjs. Plugin bin scripts + hooks call this
+// instead of shelling to a relative `$PKG_ROOT/cli/lib/preflight.mjs` — in a
+// marketplace install the plugin is copied alone (no sibling cli/), so the
+// only reachable entry is the on-PATH `maude` binary. See DDR-061.
+
+export async function run({ args, pkgRoot }) {
+  return runPreflight({ args, pkgRoot });
+}

package/cli/commands/preflight.test.mjs

@@ -0,0 +1,46 @@
+// `maude preflight` resolves the plugin manifest from the maude PACKAGE root,
+// never the caller's cwd. This is the DDR-061 regression: in a marketplace
+// install the plugin is copied alone (no sibling cli/), and bin scripts reach
+// the check through the on-PATH `maude` binary — invoked from an arbitrary
+// target-repo cwd. Spawning from a temp cwd that has no `plugins/` proves the
+// resolution doesn't depend on cwd.
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+
+function runFromTmp(args) {
+  const cwd = mkdtempSync(join(tmpdir(), 'maude-preflight-'));
+  try {
+    return spawnSync(process.execPath, [BIN, 'preflight', ...args], { cwd, encoding: 'utf8' });
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+test('preflight resolves the manifest from pkgRoot, not cwd (marketplace-layout regression)', () => {
+  // cwd has no plugins/ — if resolution used cwd this would error "manifest not found".
+  const res = runFromTmp(['--plugin', 'design', '--shell-export']);
+  assert.equal(res.status === 0 || res.status === 1, true, res.stderr); // 0/1 = ran; 2 = bad args
+  assert.match(res.stdout, /DEPS_PLUGIN="design"/);
+});
+
+test('preflight --json emits a structured envelope for the named plugin', () => {
+  const res = runFromTmp(['--plugin', 'flow', '--json']);
+  const env = JSON.parse(res.stdout);
+  assert.equal(env.plugin, 'flow');
+  assert.ok(Array.isArray(env.results));
+  assert.ok(env.summary && typeof env.summary.total === 'number');
+});
+
+test('preflight without --plugin exits 2', () => {
+  const res = runFromTmp([]);
+  assert.equal(res.status, 2);
+  assert.match(res.stderr, /--plugin/);
+});