@pugi/cli 0.1.0-beta.22 → 0.1.0-beta.23

package/dist/core/vim/state.js

@@ -0,0 +1,92 @@
+/**
+ * Leak L26 (2026-05-27) — Vim mode preference persistence.
+ *
+ * Single-tier storage (user-only, `~/.pugi/config.json`):
+ *
+ *   `{ ..., "vimMode": true }`
+ *
+ * The leak research shows Claude Code persists `/vim` as a user-level
+ * preference (not per-workspace) — vim-style editing is a body-memory
+ * trait of the operator, not a per-repo concern. We match that.
+ *
+ * Reader tolerances mirror `core/output-style/state.ts`:
+ *   - missing file        → returns `false` (vim mode off, the default)
+ *   - empty file          → returns `false`
+ *   - malformed JSON      → returns `false` (REPL must not crash on a
+ *                            hand-edited config)
+ *   - non-boolean         → returns `false`
+ *
+ * Writer is a read-modify-write — neighbouring keys (`outputStyle`,
+ * `permissionMode`, …) survive a vim-mode flip.
+ *
+ * File mode 0o600 mirrors `core/output-style/state.ts` so the same
+ * config does not silently downgrade its permission bits depending on
+ * which helper last touched it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+/**
+ * Env override for `~/.pugi`. Re-uses the same `PUGI_HOME` knob as
+ * the output-style helpers so test sandboxes are uniform.
+ */
+export const PUGI_HOME_ENV = 'PUGI_HOME';
+/** Default when the file is missing / malformed / does not set the key. */
+export const VIM_MODE_DEFAULT = false;
+/**
+ * Read the persisted vim-mode preference. Pure read, never throws —
+ * every IO failure path degrades to `VIM_MODE_DEFAULT`.
+ */
+export function resolveVimMode(io = {}) {
+    const config = readConfigFile(userConfigPath(io.env ?? process.env));
+    return typeof config.vimMode === 'boolean' ? config.vimMode : VIM_MODE_DEFAULT;
+}
+/**
+ * Write the vim-mode preference. Read-modify-write so neighbouring
+ * config keys survive (`outputStyle`, `permissionMode`, …).
+ */
+export function setVimMode(value, io = {}) {
+    const path = userConfigPath(io.env ?? process.env);
+    const config = readConfigFile(path);
+    config.vimMode = value;
+    writeConfigFile(path, config);
+}
+/**
+ * Path resolver exported for the spec; production callers should use
+ * `resolveVimMode` / `setVimMode`.
+ */
+export function userConfigPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, 'config.json');
+}
+function readConfigFile(path) {
+    if (!existsSync(path))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim().length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+function writeConfigFile(path, config) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+//# sourceMappingURL=state.js.map

package/dist/runtime/cli.js

@@ -22,17 +22,21 @@ import { PUGI_TAGLINE } from '@pugi/personas';
 import { resolveRoster, renderRosterTable } from './commands/roster.js';
 import { runDelegateCommand } from './commands/delegate.js';
 import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
+import { resolveAndValidateEnvLogin, } from '../core/auth/env-provider.js';
 import { runDeployCommand } from '../commands/deploy.js';
 import { runJobsCommand } from '../commands/jobs.js';
 import { runConfigCommand } from './commands/config.js';
 import { runStyleCommand } from './commands/style.js';
+import { runThemeCommand } from './commands/theme.js';
 import { runOnboardingCommand } from './commands/onboarding.js';
+import { runVimCommand } from './commands/vim.js';
 import { isOnboarded } from '../core/onboarding/marker.js';
 import { runPrivacyCommand } from './commands/privacy.js';
 import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
 import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
 import { runStickersCommand } from './commands/stickers.js';
+import { runReleaseNotesCommand, defaultReleaseNotesHome, } from './commands/release-notes.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runCompactCommand } from './commands/compact.js';
 import { runBudgetCommand } from './commands/budget.js';
@@ -104,6 +108,12 @@ const handlers = {
     plan: dispatchPlan,
     'plan-review': dispatchPlanReview,
     privacy: dispatchPrivacy,
+    // L24 (2026-05-27): `pugi release-notes` shows the bundled CHANGELOG
+    // diff between the operator's last-seen version + installed version.
+    // The slash counterpart `/release-notes` shares this handler via the
+    // shared `runReleaseNotesCommand` runner.
+    'release-notes': releaseNotes,
+    releaseNotes,
     // PAVF-7 (2026-05-27): `pugi report --from-error` captures the
     // most-recent failed session as a redacted bundle so operators can
     // file clean bug reports without manual log-grepping.
@@ -122,11 +132,19 @@ const handlers = {
     feedback: dispatchFeedback,
     sync,
     style: dispatchStyle,
+    // Leak L30 (2026-05-27): `pugi theme` flips the local TUI color
+    // palette (orthogonal to `pugi style` — that one steers engine
+    // prose register). 4 presets: default / dark / light / colorblind.
+    theme: dispatchTheme,
     // Leak L25 (2026-05-27): `pugi onboarding` walks the new operator
     // through auth / mode / style / MCP / telemetry. Idempotent;
     // `--reset` clears the marker file so the bare-invocation hint
     // re-arms without nuking persisted defaults.
     onboarding: dispatchOnboarding,
+    // Leak L26 (2026-05-27): `pugi vim` toggles vim-style modal editing
+    // in the REPL input buffer. Bare invocation toggles, `on`/`off`
+    // sets explicitly; preference persists in ~/.pugi/config.json.
+    vim: dispatchVim,
     undo: dispatchUndo,
     compact: dispatchCompact,
     // L19 (2026-05-27): `pugi usage` is an alias of `pugi cost` — same
@@ -330,6 +348,29 @@ async function dispatchStyle(args, flags, _session) {
     if (rc !== 0)
         process.exitCode = rc;
 }
+/**
+ * Leak L30 (2026-05-27) — `pugi theme` top-level dispatcher.
+ *
+ * Forwards to the shared `runThemeCommand` runner. The REPL `/theme`
+ * slash uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy mirrors `dispatchStyle`:
+ *   - 0 — show / switch / reset / list happy paths
+ *   - 1 — unknown preset slug
+ *   - 2 — conflicting flags (`--reset` + positional / `--reset --persist`)
+ *
+ * The runner returns the code; we attach it to `process.exitCode` so
+ * subsequent dispatch wrappers do not clobber it on success.
+ */
+async function dispatchTheme(args, flags, _session) {
+    const rc = await runThemeCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 /**
  * Leak L25 (2026-05-27) — `pugi onboarding` top-level dispatcher.
  *
@@ -360,6 +401,25 @@ async function dispatchOnboarding(args, flags, _session) {
     if (rc !== 0)
         process.exitCode = rc;
 }
+/**
+ * Leak L26 (2026-05-27) — `pugi vim` top-level dispatcher.
+ *
+ * Forwards to the shared `runVimCommand` runner. The REPL `/vim` slash
+ * uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy:
+ *   - 0 — show / enable / disable / toggle happy paths
+ *   - 2 — unknown subcommand (e.g. `pugi vim chaos`) or too many args
+ */
+async function dispatchVim(args, flags, _session) {
+    const rc = await runVimCommand(args, {
+        env: process.env,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 /**
  * PAVF-7 (2026-05-27): `pugi report --from-error` — bundle the most-
  * recent failed session into a redacted local report so operators can
@@ -924,6 +984,10 @@ function parseArgs(argv) {
         // interactive surface keeps its boxed renderer; opt-in via flag
         // for pipe / script use.
         asciiOnly: false,
+        // Leak L24 — `--reset` for `pugi release-notes`. Default off so a
+        // bare invocation only surfaces new sections. Opt-in to force the
+        // full bundled changelog к re-render (clears the on-disk marker).
+        reset: false,
     };
     const args = [];
     // Leak L22: scan for `--bare` BEFORE the early-return short-circuits
@@ -1010,6 +1074,14 @@ function parseArgs(argv) {
             // through to runStickersCommand without per-command argv slicing.
             flags.asciiOnly = true;
         }
+        else if (arg === '--reset') {
+            // Leak L24 — `pugi release-notes --reset` clears the on-disk
+            // `~/.pugi/.last-seen-version` marker so the full bundled
+            // changelog re-renders. Parsed globally for symmetry with the
+            // rest of the flag grammar; `runReleaseNotesCommand` is the
+            // single consumer today.
+            flags.reset = true;
+        }
         else if (arg === '--decompose') {
             // α6.8 EXTEND PR1: plan-only flag. Other engine commands ignore
             // it. Parsed globally for symmetry with the rest of the flag
@@ -1368,7 +1440,8 @@ const COMMAND_HELP_BODIES = {
         '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.',
+        '  --provider env                                   Read PUGI_API_KEY (or --key) + verify via /api/pugi/health.',
+        '  --provider env --key <value> --skip-validate    Explicit key, no probe (CI bootstrap).',
     ],
     accounts: [
         'pugi accounts — manage stored credentials across endpoints.',
@@ -1456,6 +1529,19 @@ const COMMAND_HELP_BODIES = {
         '',
         'Also available as /feedback from inside the REPL.',
     ],
+    'release-notes': [
+        'pugi release-notes — show what changed since you last upgraded.',
+        '',
+        'Reads the bundled CHANGELOG.md, slices to sections strictly newer than',
+        '~/.pugi/.last-seen-version, renders Markdown to stdout, then bumps the',
+        'last-seen marker to the installed CLI version. Re-running is a no-op',
+        'until you upgrade again.',
+        '',
+        '  --json                  Emit a structured envelope (sections + meta).',
+        '  --reset                 Clear last-seen marker; re-render every section.',
+        '',
+        'Also available as /release-notes from inside the REPL.',
+    ],
     deploy: [
         'pugi deploy — trigger a vendor deployment from the bound Git source.',
         '',
@@ -1686,6 +1772,31 @@ async function dispatchFeedback(_args, flags, _session) {
     });
     writeOutput(flags, { ok: true, result }, renderFeedbackToast(result));
 }
+/**
+ * `pugi release-notes` — Leak L24 (2026-05-27). Diff between the
+ * last-seen + installed CLI versions, rendered from the bundled
+ * `apps/pugi-cli/CHANGELOG.md`. Bumps `~/.pugi/.last-seen-version`
+ * to the installed version on every successful render so the next
+ * invocation is a no-op until the operator upgrades again.
+ *
+ * The handler stays thin: parser, slicer, and state I/O all live in
+ * `core/release-notes/`. This wrapper just hands ambient state to
+ * `runReleaseNotesCommand` so `--json` keeps producing the same
+ * envelope from both the top-level shell + the in-REPL `/release-notes`
+ * slash dispatcher.
+ *
+ * Always exits 0 — the command is informational, never a gate. Read
+ * failures, missing CHANGELOG, and write failures all degrade to a
+ * structured envelope with a human-readable footer.
+ */
+async function releaseNotes(_args, flags, _session) {
+    runReleaseNotesCommand({
+        home: defaultReleaseNotesHome(),
+        json: flags.json,
+        reset: flags.reset,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * Programmatic init scaffolder. Idempotent — every helper call is a
  * `*_IfMissing` write, so re-running over an existing .pugi/ workspace
@@ -4229,7 +4340,7 @@ async function login(args, flags, _session) {
     if (args.includes('--help') || args.includes('-h')) {
         writeOutput(flags, {
             command: 'login',
-            usage: 'pugi login [--provider device|token|env] [--token <PAT>] [--token-stdin] [--label <name>] [--api-url <url>]',
+            usage: 'pugi login [--provider device|token|env] [--token <PAT>] [--token-stdin] [--key <value>] [--skip-validate] [--label <name>] [--api-url <url>]',
         }, [
             'Usage: pugi login [options]',
             '',
@@ -4241,19 +4352,27 @@ async function login(args, flags, _session) {
             'Non-interactive options:',
             '  --provider device   Run the device-flow login (recommended).',
             '  --provider token    Store an API key passed via --token / --token-stdin / PUGI_LOGIN_TOKEN.',
-            '  --provider env      Promote PUGI_API_KEY from the environment into the store.',
+            '  --provider env      Read PUGI_API_KEY (or --key) and verify it via /api/pugi/health.',
             '  --token <PAT>       Inline API key (visible in `ps`).',
             '  --token-stdin       Read API key from stdin (gh-CLI style).',
+            '  --key <value>       Explicit key for --provider env; beats PUGI_API_KEY.',
+            '  --skip-validate     Skip the /api/pugi/health probe for --provider env (CI bootstrap).',
             '  --label <name>      Short label surfaced in `pugi accounts list`.',
             '  --api-url <url>     Override the Anvil endpoint (self-hosted).',
             '  --no-device-flow    Refuse the device flow; fail fast in CI without a token.',
             '',
+            'Environment variables:',
+            '  PUGI_API_KEY        Read by --provider env. Pass --key to override.',
+            '  PUGI_LOGIN_TOKEN    Read by --provider token in non-interactive shells.',
+            '  PUGI_API_URL        Override the Anvil endpoint (same as --api-url).',
+            '',
             'Examples:',
             '  pugi login                                  # interactive picker on a TTY',
             '  pugi login --provider device                # explicit browser OAuth',
             '  pugi login --provider token --token sk-xx   # paste in a key',
             '  echo $TOKEN | pugi login --provider token --token-stdin',
-            '  PUGI_API_KEY=sk-xx pugi login --provider env',
+            '  PUGI_API_KEY=pugi_xxx pugi login --provider env',
+            '  pugi login --provider env --key pugi_xxx    # explicit key beats env',
         ].join('\n'));
         return;
     }
@@ -4276,6 +4395,11 @@ async function login(args, flags, _session) {
     const apiUrlOverride = extractApiUrlFlag(args);
     const labelFlag = extractLabelFlag(args);
     const provider = parseProviderFlag(args);
+    // Leak L35 (2026-05-27): `--key` is the explicit-arg path for
+    // `--provider env`; `--skip-validate` bypasses the /api/pugi/health
+    // probe (CI bootstrap before the network is up).
+    const envExplicitKey = extractKeyFlag(args);
+    const envSkipValidate = args.includes('--skip-validate');
     const apiUrl = normalizeApiUrl(apiUrlOverride ?? process.env.PUGI_API_URL ?? DEFAULT_API_URL);
     // Path 1: explicit --provider trumps everything else.
     if (provider) {
@@ -4286,6 +4410,8 @@ async function login(args, flags, _session) {
             explicitToken: tokenFromArgs,
             tokenStdinFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -4333,6 +4459,8 @@ async function login(args, flags, _session) {
             flags,
             label: labelFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -4551,16 +4679,28 @@ async function dispatchLoginProvider(provider, ctx) {
             return;
         }
         case 'env': {
-            const envKey = process.env.PUGI_API_KEY;
-            if (!envKey) {
-                throw new Error('pugi login --provider env requires PUGI_API_KEY to be exported in the current shell.');
+            // Leak L35 (2026-05-27): resolve the env / --key candidate,
+            // run the local format check, then probe `/api/pugi/health`
+            // BEFORE persisting. A bad token never lands on disk so the
+            // next `pugi <anything>` does not silently 401 against the
+            // cabinet. `--skip-validate` opts out for CI bootstrap.
+            const resolved = await resolveAndValidateEnvLogin({
+                apiUrl: ctx.apiUrl,
+                explicitKey: ctx.envExplicitKey,
+                env: process.env,
+                skipValidate: ctx.envSkipValidate ?? false,
+            });
+            if (resolved.kind !== 'ok') {
+                reportEnvLoginFailure(resolved, ctx.flags);
+                return;
             }
             storeAndAnnounceToken({
                 apiUrl: ctx.apiUrl,
-                apiKey: envKey,
+                apiKey: resolved.token,
                 label: ctx.label,
                 source: 'env',
                 flags: ctx.flags,
+                validatedLatencyMs: resolved.latencyMs > 0 ? resolved.latencyMs : undefined,
             });
             return;
         }
@@ -4579,6 +4719,15 @@ function storeAndAnnounceToken(input) {
         label: input.label,
         source: input.source,
     });
+    const textLines = [
+        `Pugi logged in for ${record.apiUrl}`,
+        `Method: ${input.source}${record.label ? ` (${record.label})` : ''}`,
+        `Token: ${maskApiKey(record.apiKey)}`,
+    ];
+    if (typeof input.validatedLatencyMs === 'number') {
+        textLines.push(`Verified via /api/pugi/health in ${input.validatedLatencyMs}ms`);
+    }
+    textLines.push('Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.');
     writeOutput(input.flags, {
         status: 'logged_in',
         apiUrl: record.apiUrl,
@@ -4586,12 +4735,55 @@ function storeAndAnnounceToken(input) {
         label: record.label ?? null,
         createdAt: record.createdAt,
         source: input.source,
-    }, [
-        `Pugi logged in for ${record.apiUrl}`,
-        `Method: ${input.source}${record.label ? ` (${record.label})` : ''}`,
-        `Token: ${maskApiKey(record.apiKey)}`,
-        'Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.',
-    ].join('\n'));
+        ...(typeof input.validatedLatencyMs === 'number'
+            ? { validatedLatencyMs: input.validatedLatencyMs }
+            : {}),
+    }, textLines.join('\n'));
+}
+/**
+ * Render a typed `EnvLoginFailure` from `resolveAndValidateEnvLogin`
+ * onto the surrounding CLI surface. Maps the failure kind to:
+ *   - an exit code (1 by default; 2 for invalid format so a CI step
+ *     can disambiguate "missing key" vs "key shape wrong" without
+ *     parsing stderr; 4 for network / server errors so retry logic
+ *     can distinguish transient failures from credential failures)
+ *   - a structured JSON payload for `--json` consumers
+ *   - a human-readable stderr line for the interactive path
+ *
+ * The token itself is never echoed — only the validator's own message
+ * (which the env-provider module composed without the secret in it).
+ */
+function reportEnvLoginFailure(failure, flags) {
+    const exitCode = (() => {
+        switch (failure.kind) {
+            case 'missing':
+                return 1;
+            case 'invalid-format':
+                return 2;
+            case 'unauthorized':
+                return 3;
+            case 'network-error':
+            case 'server-error':
+                return 4;
+            case 'unexpected-status':
+                return 5;
+            default: {
+                const exhaustive = failure;
+                return Number(exhaustive) || 1;
+            }
+        }
+    })();
+    const payload = {
+        status: 'login_failed',
+        kind: failure.kind,
+        message: failure.message,
+    };
+    if ('status' in failure)
+        payload.httpStatus = failure.status;
+    if ('cause' in failure && failure.cause)
+        payload.cause = failure.cause;
+    writeOutput(flags, payload, failure.message);
+    process.exitCode = exitCode;
 }
 /**
  * OAuth 2.0 Device Authorization Grant client (RFC 8628). Renders
@@ -5347,6 +5539,17 @@ function extractApiUrlFlag(args) {
 function extractLabelFlag(args) {
     return extractNamedFlagValue(args, 'label');
 }
+/**
+ * `pugi login --provider env --key <value>` — explicit key arg that
+ * beats `PUGI_API_KEY` env. Same precedence rule as `gh auth login
+ * --with-token`, `aws configure set`, and `pugi config`: the most
+ * specific operator intent (a typed flag) overrides the ambient
+ * environment so an operator can override a stale `PUGI_API_KEY`
+ * from their shell rc without unsetting it first.
+ */
+function extractKeyFlag(args) {
+    return extractNamedFlagValue(args, 'key');
+}
 /**
  * `pugi jobs` — surface the persistent JobRegistry on the CLI.
  * Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J). Subcommand parsing

package/dist/runtime/commands/doctor.js

@@ -50,6 +50,7 @@ import { probeConfig } from '../../core/diagnostics/probes/config.js';
 import { probeSession } from '../../core/diagnostics/probes/session.js';
 import { probeDenialTracking } from '../../core/diagnostics/probes/denial-tracking.js';
 import { probeBareMode } from '../../core/diagnostics/probes/bare-mode.js';
+import { probePugiMdHierarchy } from '../../core/diagnostics/probes/pugi-md.js';
 /**
  * Default API URL when no PUGI_API_URL env override is set. Mirrors
  * the constant in `core/credentials.ts` (kept local to avoid an
@@ -214,6 +215,18 @@ export function buildDefaultProbes(ctx, options = {}) {
             name: 'BARE MODE',
             run: async () => probeBareMode({ env: ctx.env }),
         },
+        // Leak L32 (2026-05-27): PUGI.md HIERARCHY row. Reports how many
+        // ambient `PUGI.md` / `CLAUDE.md` files the cwd → homedir walk
+        // discovered, and the closest path. `skipped` when bare mode is
+        // active (walk disabled) or zero files found.
+        {
+            name: 'PUGI.md HIERARCHY',
+            run: async () => probePugiMdHierarchy({
+                cwd: ctx.cwd,
+                homedir: ctx.home,
+                env: ctx.env,
+            }),
+        },
     ];
     return probes;
 }