@pugi/cli 0.1.0-beta.14 → 0.1.0-beta.15

package/bin/run.js

@@ -1,2 +1,34 @@
 #!/usr/bin/env node
-import '../dist/index.js';
+// 2026-05-27 — silence the noisy `node:sqlite` ExperimentalWarning.
+// Node 22.x prints a multi-line warning the first time any consumer
+// imports `node:sqlite` (see core/repl/store/session-store.ts). CEO has
+// pinged this surface twice now ("(node:XXXXX) ExperimentalWarning:
+// SQLite is an experimental feature and might change at any time" +
+// trace-warnings hint). Hiding it cleanly requires a tap on
+// process.emitWarning BEFORE any module loads the sqlite binding —
+// hence wiring it here in the binary entry, not deep inside the CLI.
+//
+// We allowlist only the exact sqlite warning + leave every other
+// runtime warning (deprecation, security, custom code paths) intact.
+// Operator can still re-enable the noise by exporting
+// PUGI_SHOW_EXPERIMENTAL_WARNINGS=1 — useful when debugging a node
+// version bump that might surface a new experimental flag we should
+// notice.
+if (!process.env.PUGI_SHOW_EXPERIMENTAL_WARNINGS) {
+  const originalEmit = process.emit;
+  process.emit = function patchedEmit(name, ...args) {
+    if (name === 'warning') {
+      const w = args[0];
+      const isSqliteExperimental =
+        w &&
+        typeof w === 'object' &&
+        w.name === 'ExperimentalWarning' &&
+        typeof w.message === 'string' &&
+        /SQLite is an experimental feature/i.test(w.message);
+      if (isSqliteExperimental) return false;
+    }
+    return originalEmit.call(this, name, ...args);
+  };
+}
+
+import('../dist/index.js');

package/dist/runtime/cli.js

@@ -832,7 +832,176 @@ async function version(_args, flags, _session) {
     };
     writeOutput(flags, payload, `pugi ${payload.version}`);
 }
-async function help(_args, flags, _session) {
+/**
+ * Per-command help bodies (task #100). When the operator types
+ * `pugi <cmd> --help` the dispatcher routes here with `args = [cmd]`.
+ * If we have a focused body for that command, print it instead of the
+ * global summary. Falls back to the global summary so unknown / new
+ * commands still get a useful response.
+ *
+ * Source of truth for each entry: the comment block at the top of the
+ * command's implementation module + any flags the command declares.
+ * Keep entries short — operators want the one-liner of intent + the
+ * 2-5 most useful flags, not a tutorial. The global help still has the
+ * full per-section reference; the per-command body is the "tell me
+ * how to use this NOW" surface.
+ */
+const COMMAND_HELP_BODIES = {
+    init: [
+        'pugi init — bootstrap a new Pugi workspace in the current directory.',
+        '',
+        'Creates .pugi/{PUGI.md, mcp.json, index.json, artifacts/, sessions/} and',
+        'seeds the 6 default skills. Idempotent — running again only fills gaps.',
+        '',
+        'Flags:',
+        '  --no-defaults     Skip the bundled default-skills install.',
+        '',
+        'Env:',
+        '  PUGI_INIT_NO_DEFAULTS=1   Same as --no-defaults.',
+    ],
+    explain: [
+        'pugi explain "<question>" — read-only Q&A about the workspace.',
+        '',
+        'Calls the engine loop in explain mode (budget: 5 calls / 20k tokens).',
+        'No file writes; safe to run against unfamiliar code.',
+        '',
+        'Examples:',
+        '  pugi explain "what does this package.json define?"',
+        '  pugi explain "trace the auth flow in src/auth/"',
+    ],
+    code: [
+        'pugi code "<brief>" — engineering-mode write loop (30k token budget).',
+        '',
+        'Writes files in the current workspace. Use --no-tty in CI / pipes.',
+    ],
+    fix: [
+        'pugi fix "<brief>" — minimal-diff bugfix loop (30k token budget).',
+        '',
+        'Same as `pugi code` but the prompt biases toward the smallest patch',
+        'that closes the brief — refuses scope creep / refactor invitations.',
+    ],
+    build: [
+        'pugi build "<brief>" — feature-build loop (200k token budget).',
+        '',
+        'Multi-turn engineering with plan-review checkpoints. Pairs with',
+        'pugi plan --decompose <idea> when the brief is bigger than one PR.',
+    ],
+    plan: [
+        'pugi plan --decompose <idea> — split an idea into 3-7 components.',
+        '',
+        'Writes .pugi/plan/<session-id>/splits/NN-<name>/spec.md plus',
+        'manifest.md with the dependency DAG. Pass each split to `pugi build`.',
+    ],
+    review: [
+        'pugi review — code review surfaces.',
+        '',
+        '  --triple                3-model consensus via Anvil paid fleet.',
+        '  --triple --commit <SHA> Review a specific commit (vs origin/main).',
+        '  --consensus             Customer-facing consensus review (codex + claude + deepseek).',
+        '                          Optional: --commit <sha> | --pr <num> | --branch <name>.',
+        '',
+        'Exit codes: 0 PASS · 1 WARN · 2 BLOCK · 5 auth_missing · 7 rate_limited.',
+    ],
+    privacy: [
+        'pugi privacy — privacy-mode operations.',
+        '',
+        '  show                    Display effective mode + source.',
+        '  set <mode>              Local-only legacy values (local-only|metadata|full).',
+        '',
+        'For tenant-scoped server-side modes (strict|balanced|permissive), use:',
+        '  pugi config get privacy',
+        '  pugi config set privacy=<mode>',
+    ],
+    config: [
+        'pugi config — read / write CLI + tenant configuration.',
+        '',
+        '  get <key>                                       Local config value.',
+        '  get privacy                                     Tenant privacy snapshot (admin-api).',
+        '  get routing                                     Effective routing table.',
+        '  set <key>=<value>                               Local config write.',
+        '  set privacy=<mode>                              Flip tenant privacy (strict|balanced|permissive).',
+        '  set routing.<tag>.<budget>=<model>              Override one routing lane.',
+        '  unset routing.<tag>.<budget>                    Revert a routing override.',
+        '  mcp trust|deny|list <name>                      MCP server trust + visibility.',
+    ],
+    sync: [
+        'pugi sync — explicit-continuation handoff bundle upload.',
+        '',
+        '  --dry-run               Print the bundle plan without uploading.',
+        '  --privacy <mode>        Override per-bundle privacy posture.',
+    ],
+    whoami: [
+        'pugi whoami — show the active credential + JWT principal + plan tier.',
+        '',
+        'Reads from ~/.pugi/credentials.json. No network call unless --remote.',
+    ],
+    login: [
+        'pugi login — authenticate against an api.pugi.io endpoint.',
+        '',
+        'Interactive picker by default (browser OAuth / PAT / env). Non-interactive:',
+        '  --provider device                                Device-flow OAuth.',
+        '  --provider token --token <jwt>                   Pass a JWT directly.',
+        '  --provider env --env PUGI_API_KEY                Read from an env var.',
+    ],
+    accounts: [
+        'pugi accounts — manage stored credentials across endpoints.',
+        '',
+        '  list                    Every account + its endpoint + active flag.',
+        '  switch <label>          Re-point the active account.',
+        '  remove <label>          Delete a stored credential.',
+    ],
+    jobs: [
+        'pugi jobs — list, tail, or kill background dispatch jobs.',
+        '',
+        '  list                    All jobs in the registry.',
+        '  tail <id>               Stream output from one job.',
+        '  kill <id>               Cancel a running job.',
+    ],
+    delegate: [
+        'pugi delegate <slug> "<brief>" — dispatch a brief to one specialist persona.',
+        '',
+        'Slugs (Tier 1 alpha 7.5): dev qa pm devops researcher analyst designer',
+        'frontend architect. `pugi roster` lists the live set.',
+    ],
+    roster: [
+        'pugi roster — list the live Tier 1 personas + roles.',
+    ],
+    doctor: [
+        'pugi doctor — diagnose CLI + workspace + adapter capabilities.',
+        '',
+        'Prints CLI version, Node version, workspace state (.pugi presence,',
+        'event log, settings), permission mode, and the capability matrix per',
+        'engine adapter. Safe to run anywhere; no network calls.',
+    ],
+    ask: [
+        'pugi ask "<question>" — surface a yes/no question modal locally.',
+        '',
+        'Useful in shell scripts that need a human-confirm before a destructive',
+        'step. Exits 0 on yes, 1 on no, 2 on cancel.',
+    ],
+    deploy: [
+        'pugi deploy — trigger a vendor deployment from the bound Git source.',
+        '',
+        '  --target vercel <vercelProject> --project <id>   Vercel deploy.',
+        '  --target render <renderService> --project <id>   Render deploy (Sprint 2 stub).',
+        '  --status <id>                                    Vendor-agnostic status snapshot.',
+        '  --logs <id> [--tail]                             Build-log tail.',
+        '',
+        'Optional: --target-env production|preview, --ref <ref>, --integration <id>.',
+    ],
+};
+async function help(args, flags, _session) {
+    // 2026-05-27 task #100: per-command help bodies. When dispatcher
+    // routed `pugi <cmd> --help` here it passes `args = [cmd]`; if we
+    // have a focused body, print that. Falls through to the global
+    // summary on unknown / new commands so the dispatcher's redirect
+    // never produces a worse-than-baseline response.
+    const requested = args[0];
+    if (requested && COMMAND_HELP_BODIES[requested]) {
+        const body = COMMAND_HELP_BODIES[requested];
+        writeOutput(flags, { command: requested, lines: body }, body.join('\n'));
+        return;
+    }
     const commands = Object.keys(handlers).sort();
     writeOutput(flags, { commands }, [
         'Pugi CLI',

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.14');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.15');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.15",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -48,13 +48,13 @@
     "ink": "^5.0.1",
     "linkedom": "^0.18.12",
     "react": "^18.3.1",
-    "tar": "^6.2.1",
+    "tar": "^7.5.11",
     "tinyglobby": "^0.2.16",
     "turndown": "^7.2.4",
     "undici": "^8.3.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.14"
+    "@pugi/sdk": "0.1.0-beta.15"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",