@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/core/onboarding/ensure-initialized.js

@@ -0,0 +1,133 @@
+/**
+ * Wave 6 UX (2026-05-27) — `ensureInitialized` helper.
+ *
+ * Auto-init pre-flight for every Pugi command. Before this helper landed,
+ * the only entry points that exercised the init flow were:
+ *
+ *   1. The explicit `pugi init` CLI subcommand.
+ *   2. The REPL's `/init` slash (β1a r1).
+ *   3. Engine commands (`pugi code`, `pugi build`, `pugi sync`) which
+ *      called the legacy `ensureInitialized` in `cli.ts` and threw
+ *      `Error('Run pugi init first')` if the operator ran them in a
+ *      directory without `.pugi/`.
+ *
+ * Read-only commands (`pugi explain`, `pugi review`, `pugi plan`,
+ * `pugi smoke`, `pugi chain new`, ...) silently no-op'd the `.pugi/`
+ * mirror inside the engine adapter, which made early dogfooding
+ * confusing — the operator saw a successful command but no session
+ * artifacts on disk and no idea why.
+ *
+ * Auto-init contract (matches CEO directive Wave 6, 2026-05-27):
+ *
+ *   - `.pugi/` already exists  → return `{ status: 'already' }` silently.
+ *   - Interactive TTY + no `.pugi/` → prompt
+ *     "No Pugi workspace found here. Initialize? (Y/n)".
+ *     Default Y. On Y: run `scaffoldPugiWorkspace`, return `{ status:
+ *     'initialized' }`. On n: return `{ status: 'declined' }` so the
+ *     caller can bail with a helpful message.
+ *   - Non-interactive (CI / pipe / --json / --no-tty) + no `.pugi/`:
+ *     default behaviour is conservative — return `{ status: 'declined',
+ *     reason: 'non_interactive' }`. The caller decides how to surface
+ *     this (engine commands bail with a clean error; read-only
+ *     commands MAY continue with degraded semantics).
+ *   - `--no-init` flag forces conservative posture even on interactive
+ *     terminals (operator wants to fail fast).
+ *
+ * Session cache: a command pre-flight that already prompted for and
+ * scaffolded `.pugi/` MUST NOT re-prompt for the same workspace in the
+ * same process. The cache key is the absolute workspace root path. The
+ * cache is process-local (Map) — it does not persist across `pugi`
+ * invocations (a second `pugi code` in the same shell starts fresh and
+ * re-checks the filesystem).
+ *
+ * This module is intentionally framework-free: no Ink, no React, no
+ * readline. The prompt reader is injected via the `prompt` callback so
+ * the spec can drive the helper deterministically and the CLI can
+ * forward to its existing stdin-reader (`readSingleChoice` in cli.ts).
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Process-local cache of workspaces that already passed the pre-flight
+ * gate. Keyed by absolute root path. The cache is intentionally
+ * additive-only — there is no eviction. A long-running REPL session
+ * stays in one workspace and we never want to re-prompt within it.
+ */
+const initialisedCache = new Set();
+/**
+ * Reset the cache. Exported for spec teardown — production callers
+ * never need this.
+ */
+export function resetInitializedCache() {
+    initialisedCache.clear();
+}
+/**
+ * Detect `.pugi/` at `root`. Pure filesystem read; swallows permission
+ * errors (returns false). Exported so the spec can assert the same
+ * detection the helper uses without re-implementing the check.
+ */
+export function hasPugiWorkspace(root) {
+    const path = resolve(root, '.pugi');
+    try {
+        if (!existsSync(path))
+            return false;
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Auto-init pre-flight. Idempotent and process-cache aware — calling
+ * twice in the same process for the same workspace returns `already`
+ * the second time even if the filesystem state changed underneath.
+ *
+ * Implementation notes:
+ *
+ *   - Returns `{ status: 'already' }` when `.pugi/` exists OR the cache
+ *     remembers this workspace. The cache short-circuit means a second
+ *     command in the same process never blocks on the prompt.
+ *   - Interactive + missing → prompt. The default answer (empty input
+ *     OR a leading `y` / `yes`) maps to scaffold. Anything else
+ *     (`n`, `no`, `cancel`, whitespace + non-y) maps to declined.
+ *   - Scaffolder failures propagate to the caller; the helper does
+ *     NOT swallow them because a failed scaffold means the operator's
+ *     command cannot continue anyway. Tests assert this.
+ */
+export async function ensureInitialized(opts) {
+    const root = resolve(opts.cwd ?? process.cwd());
+    if (initialisedCache.has(root)) {
+        return { status: 'already', root };
+    }
+    if (hasPugiWorkspace(root)) {
+        initialisedCache.add(root);
+        return { status: 'already', root };
+    }
+    if (opts.skip) {
+        return { status: 'declined', root, reason: 'disabled' };
+    }
+    if (!opts.interactive) {
+        return { status: 'declined', root, reason: 'non_interactive' };
+    }
+    if (!opts.prompt) {
+        // Defensive — an interactive caller forgot к wire the prompt
+        // reader. Treat the same as non-interactive rather than throwing
+        // so the surrounding command can degrade gracefully.
+        return { status: 'declined', root, reason: 'non_interactive' };
+    }
+    const write = opts.write ?? ((line) => process.stderr.write(line));
+    write(`No Pugi workspace found at ${root}.\n`);
+    const answer = (await opts.prompt('Initialize a new Pugi workspace here? (Y/n) ')).trim().toLowerCase();
+    // Default = yes (empty input OR leading 'y'). Anything else = no.
+    // Mirrors the gh CLI / claude code prompt convention where the upper-
+    // case option in `(Y/n)` is the default-on-Enter answer.
+    const acceptedShort = answer === '' || answer === 'y' || answer === 'yes';
+    if (!acceptedShort) {
+        write('Initialization declined.\n');
+        return { status: 'declined', root, reason: 'user_declined' };
+    }
+    await opts.scaffold({ cwd: root });
+    initialisedCache.add(root);
+    return { status: 'initialized', root };
+}
+//# sourceMappingURL=ensure-initialized.js.map

package/dist/core/onboarding/marker.js

@@ -0,0 +1,111 @@
+/**
+ * Leak L25 (2026-05-27) — Onboarding marker file.
+ *
+ * `~/.pugi/.onboarded` is a single, contentless marker. Its existence
+ * tells the bare-invocation hint check that the operator has already
+ * walked the `/onboarding` wizard at least once, so we no longer print
+ * the "Tip: run `pugi onboarding` to configure defaults" line on
+ * cold-start. The wizard re-runs cleanly — idempotency lives in the
+ * wizard itself, not in the marker.
+ *
+ * Why a marker file (and not just `~/.pugi/config.json`'s existence)?
+ *
+ *   - The config file is touched the moment ANY surface writes a
+ *     default — `pugi style terse --persist`, `pugi permissions ask`,
+ *     `pugi config set …`. Using "config exists" as the proxy for
+ *     "operator has onboarded" would silence the first-run hint for
+ *     operators who never saw the wizard.
+ *
+ *   - The marker is explicit: it is written ONLY by the wizard's exit
+ *     step (or `pugi onboarding --mark-only` for the upgrade-path
+ *     where we want to suppress the hint without forcing a re-walk).
+ *
+ *   - Removing the marker (`rm ~/.pugi/.onboarded`) re-arms the hint
+ *     without nuking the operator's accumulated config — useful for
+ *     QA, support flows, and demo-machine resets.
+ *
+ * Path resolution mirrors the L6/L18 convention: `PUGI_HOME` env wins,
+ * else `~/.pugi`. The marker is touched as an empty file (no JSON, no
+ * timestamp payload) — readers MUST treat existence as the only signal
+ * so a future change to mtime semantics does not break us.
+ *
+ * IO contract:
+ *   - `isOnboarded(env)` — pure read; never throws, returns false on
+ *     any fs error so a corrupted home dir cannot hide the hint.
+ *   - `markOnboarded(env)` — best-effort write; creates `<home>/.pugi/`
+ *     if missing, mode 0o600 on the marker so it never lands in a
+ *     world-readable backup.
+ *   - `clearOnboarded(env)` — best-effort delete; absent file is a
+ *     no-op (not an error). Used by `pugi onboarding --reset` and the
+ *     spec teardown.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/**
+ * Env override for `~/.pugi`. Same convention as L6 / L18 — spec
+ * fixtures point this at a temp dir so a real developer machine never
+ * lands a stray marker.
+ */
+export const PUGI_HOME_ENV = 'PUGI_HOME';
+/**
+ * Marker basename. Hidden (leading dot) so it does not clutter `ls`
+ * inside `~/.pugi/` next to `config.json` / `session.json`.
+ */
+const MARKER_BASENAME = '.onboarded';
+/**
+ * Resolve the absolute path to the onboarding marker. Exported for the
+ * spec; production callers go through `isOnboarded` / `markOnboarded`.
+ */
+export function onboardingMarkerPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, MARKER_BASENAME);
+}
+/**
+ * True when the marker exists. Pure read. Defensive: any fs error
+ * (race with deletion, permission flip) degrades to `false` — printing
+ * the hint twice is harmless, silently swallowing the wizard would
+ * surprise the operator.
+ */
+export function isOnboarded(env = process.env) {
+    try {
+        return existsSync(onboardingMarkerPath(env));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Touch the marker. Creates `<home>/.pugi/` if missing. Idempotent —
+ * re-touching an existing marker is a no-op for the consumer (the file
+ * was already there; the hint was already suppressed).
+ *
+ * Best-effort: a write failure is swallowed because the wizard already
+ * completed its real work (mode + style + telemetry were persisted).
+ * The worst case is a redundant hint on the next `pugi` invocation —
+ * preferable to crashing the freshly-completed wizard with a stat EIO.
+ */
+export function markOnboarded(env = process.env) {
+    const path = onboardingMarkerPath(env);
+    try {
+        mkdirSync(resolve(path, '..'), { recursive: true });
+        writeFileSync(path, '', { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // intentionally swallowed — see header
+    }
+}
+/**
+ * Remove the marker. Used by `pugi onboarding --reset` (and the spec
+ * teardown). Absent file is a no-op; any other fs error is swallowed
+ * so a permission glitch never leaks out of the reset surface.
+ */
+export function clearOnboarded(env = process.env) {
+    try {
+        rmSync(onboardingMarkerPath(env), { force: true });
+    }
+    catch {
+        // intentionally swallowed — see header
+    }
+}
+//# sourceMappingURL=marker.js.map

package/dist/core/onboarding/telemetry-state.js

@@ -0,0 +1,108 @@
+/**
+ * Leak L25 (2026-05-27) — Telemetry consent state.
+ *
+ * The onboarding wizard's Step 5 asks the operator for telemetry
+ * consent. We persist the verdict in the user-tier
+ * `~/.pugi/config.json::telemetry` field so a future REPL boot can
+ * read it without re-asking. Choices mirror `core/settings.ts`'s
+ * `privacy.telemetry` enum:
+ *
+ *   - `off`        — no telemetry of any kind (default).
+ *   - `anonymous`  — counts + error categories only, no payloads.
+ *   - `community`  — anonymous + opt-in skill/usage panels.
+ *
+ * This module is intentionally narrow: it only owns the `telemetry`
+ * key inside `~/.pugi/config.json`. The full settings parsing lives in
+ * `core/settings.ts` (workspace-tier `.pugi/settings.json`); we do NOT
+ * route through it here because:
+ *
+ *   1. The settings schema is workspace-scoped — its file path is
+ *      `<root>/.pugi/settings.json`, not `~/.pugi/config.json`.
+ *   2. The wizard records a user-level default that workspace settings
+ *      can later override. Mixing the two would conflate scope.
+ *   3. Read-modify-write on a partial JSON file is the same pattern
+ *      L6 / L18 use for adjacent keys — keeping it self-contained
+ *      preserves the "one module, one key" invariant.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { PUGI_HOME_ENV } from './marker.js';
+export const TELEMETRY_CHOICES = Object.freeze([
+    'off',
+    'anonymous',
+    'community',
+]);
+export const DEFAULT_TELEMETRY = 'off';
+/**
+ * Path to the user-tier config. Mirrors `userConfigPath()` from L18
+ * `output-style/state.ts` — duplicated here (not imported) to keep the
+ * marker + telemetry module self-contained. Any future drift between
+ * the two would surface a spec failure: both modules read the same
+ * file in the spec sandbox.
+ */
+export function telemetryConfigPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, 'config.json');
+}
+/**
+ * Type guard for arbitrary string input (CLI argv, config.json
+ * deserialisation). Returns false for any non-string or out-of-set
+ * value so a malformed config degrades to the default verdict.
+ */
+export function isTelemetryChoice(value) {
+    return (typeof value === 'string'
+        && TELEMETRY_CHOICES.includes(value));
+}
+/**
+ * Read the persisted telemetry verdict. Returns the default (`'off'`)
+ * when the file is absent, empty, malformed, or holds an unknown
+ * value. Never throws — the wizard re-asks every time it runs, so a
+ * defensive read is the right posture.
+ */
+export function readTelemetryChoice(io = {}) {
+    const config = readConfigFile(telemetryConfigPath(io.env ?? process.env));
+    return isTelemetryChoice(config.telemetry) ? config.telemetry : DEFAULT_TELEMETRY;
+}
+/**
+ * Persist the telemetry verdict. Read-modify-write preserves any
+ * neighbouring keys (`outputStyle`, `defaultPermissionMode`, …) the
+ * other tier-state modules own.
+ */
+export function writeTelemetryChoice(choice, io = {}) {
+    const path = telemetryConfigPath(io.env ?? process.env);
+    const config = readConfigFile(path);
+    config.telemetry = choice;
+    writeConfigFile(path, config);
+}
+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=telemetry-state.js.map

package/dist/core/output-style/presets.js

@@ -0,0 +1,176 @@
+/**
+ * Leak L18 (2026-05-27) — Output-style presets.
+ *
+ * Mirror of Claude Code's `/output-style` surface: a small closed set of
+ * named voice presets the operator can flip between at session start so
+ * the model's prose lands in the register they prefer. The preset
+ * compiles into an `<output-style>` rule block appended to the engine
+ * system prompt; tool-use / code-block formatting / file edits are NOT
+ * affected — the preset only steers prose register.
+ *
+ * Design contract:
+ *
+ *   - The catalogue is intentionally tiny (5 entries) so the operator
+ *     can hold the full surface in working memory. Adding entries means
+ *     adding a row in `OUTPUT_STYLES` plus a spec assertion; there is
+ *     no plugin surface today.
+ *
+ *   - `default` is the only preset that emits NO rule block. The
+ *     "current Pugi voice" already lives in the base engine prompt
+ *     (jargon ban, brand voice, terse register), so re-stating it
+ *     under `<output-style>` would double the model's instruction load
+ *     for the most-common case. Other presets emit the block.
+ *
+ *   - Rule-block prose stays terse and operator-grade (brandbook §08).
+ *     No friendly hedging, no AI-assistant framing. The bullets are
+ *     the model's contract; the section title carries the preset name
+ *     so the model can self-correct mid-turn if it drifts ("I am in
+ *     terse mode → drop articles").
+ *
+ *   - The Russian-formal preset uses вы-form explicitly. Russian/
+ *     Ukrainian chat is permitted by the base voice contract; this
+ *     preset hardens the register for B2B / enterprise demo flows
+ *     where ты-form reads as too casual.
+ *
+ *   - The Casual preset RELAXES the jargon ban — contractions, jokes,
+ *     informal phrasing are allowed. It does NOT lift the brand-voice
+ *     em-dash / emoji ban; those are typographic, not register, and
+ *     remain off across every preset.
+ *
+ * Test surface: `test/commands/output-style-presets.spec.ts` exercises
+ * the catalogue invariants (5 entries, unique slugs, every non-default
+ * preset emits a non-empty block, the block starts with the expected
+ * marker so the engine prompt appender can locate it for stripping).
+ */
+/**
+ * The closed list of preset slugs in catalogue order. Mirror used by
+ * the CLI surface (`/style` table, `pugi style --list`) so the
+ * operator sees presets in a stable order regardless of catalogue
+ * iteration order.
+ */
+export const OUTPUT_STYLE_SLUGS = Object.freeze([
+    'default',
+    'terse',
+    'explanatory',
+    'russian-formal',
+    'casual',
+]);
+/**
+ * Default slug used when no workspace-/user-level preference is set.
+ * Exported so `state.ts` and the CLI handler share one constant.
+ */
+export const DEFAULT_OUTPUT_STYLE = 'default';
+/**
+ * Catalogue keyed by slug. Frozen so callers cannot mutate the
+ * shared rows; the CLI handler returns slugs, not preset references,
+ * to keep the boundary clean.
+ */
+export const OUTPUT_STYLES = Object.freeze({
+    default: Object.freeze({
+        slug: 'default',
+        title: 'Default',
+        gloss: 'Current Pugi voice (no override). Base engine prompt rules apply unchanged.',
+        rules: Object.freeze([]),
+    }),
+    terse: Object.freeze({
+        slug: 'terse',
+        title: 'Terse',
+        gloss: 'Fragments, dropped articles, one short sentence per turn.',
+        rules: Object.freeze([
+            'Drop articles, fillers, hedging',
+            '1 short sentence per turn for prose answers',
+            'Code blocks unchanged — never abbreviate code',
+            'Quote errors verbatim with no paraphrase',
+        ]),
+    }),
+    explanatory: Object.freeze({
+        slug: 'explanatory',
+        title: 'Explanatory',
+        gloss: 'Verbose, walks reasoning step by step, links concepts.',
+        rules: Object.freeze([
+            'Explain reasoning, not just the conclusion',
+            'Cite relevant files + line numbers when grounding claims',
+            'Link adjacent concepts the operator may want to chase',
+            'Code blocks unchanged — annotate around, not inside',
+        ]),
+    }),
+    'russian-formal': Object.freeze({
+        slug: 'russian-formal',
+        title: 'Russian formal',
+        gloss: 'Russian вы-form, professional register, no slang.',
+        rules: Object.freeze([
+            'Pisat\' otvety po-russki (Russian prose; ASCII transliteration permitted in this rule block only)',
+            'Address the operator using вы-form, never ты',
+            'No slang, no contractions of Russian forms',
+            'Code blocks + identifiers stay in English unchanged',
+            'Error messages quoted verbatim in the original language',
+        ]),
+    }),
+    casual: Object.freeze({
+        slug: 'casual',
+        title: 'Casual',
+        gloss: 'Informal register, contractions OK, dry jokes welcome.',
+        rules: Object.freeze([
+            'Contractions allowed (it\'s, don\'t, you\'re)',
+            'Dry, deadpan jokes welcome when they do not displace signal',
+            'No em-dashes, no emoji — typographic rules unchanged',
+            'Stay terse — casual is register, not verbosity',
+        ]),
+    }),
+});
+/**
+ * Type-narrowing predicate. Used by the slash-command parser + state
+ * loader so an unknown string from operator input or a stale config
+ * file degrades to the default preset instead of crashing.
+ */
+export function isOutputStyleSlug(value) {
+    return (typeof value === 'string'
+        && OUTPUT_STYLE_SLUGS.includes(value));
+}
+/**
+ * Compile a preset into the `<output-style>` rule block injected at
+ * the tail of the engine system prompt.
+ *
+ * Returns empty string when the preset is `default` (or any preset
+ * with an empty rules array). Empty string is a load-bearing signal —
+ * the engine prompt appender uses it to skip injection entirely so
+ * the model sees a clean prompt for the default register.
+ *
+ * The block opens with `<output-style>` and closes with `</output-style>`
+ * (XML-shaped marker, matching the engine prompt's existing `<intent>`
+ * grammar). The `Active style:` line gives the model a self-correction
+ * anchor when it drifts mid-turn.
+ */
+export function compileStyleBlock(slug) {
+    const preset = OUTPUT_STYLES[slug];
+    if (preset.rules.length === 0)
+        return '';
+    const lines = [];
+    lines.push('<output-style>');
+    lines.push(`  Active style: ${preset.slug}`);
+    for (const rule of preset.rules) {
+        lines.push(`  - ${rule}`);
+    }
+    lines.push('</output-style>');
+    return lines.join('\n');
+}
+/**
+ * Render the preset catalogue as a plain-text table for the `/style`
+ * + `pugi style` surfaces. Marks the active slug with `*` so the
+ * operator can see at a glance which preset is in effect.
+ *
+ * Pure renderer (no fs, no env). Identical text is emitted from both
+ * the slash dispatcher and the top-level CLI command so operators
+ * trained on one surface read the same table on the other.
+ */
+export function renderStyleTable(active) {
+    const slugWidth = Math.max('NAME'.length, ...OUTPUT_STYLE_SLUGS.map((slug) => slug.length));
+    const header = `${'NAME'.padEnd(slugWidth)}  GLOSS`;
+    const rows = OUTPUT_STYLE_SLUGS.map((slug) => {
+        const preset = OUTPUT_STYLES[slug];
+        const marker = slug === active ? '*' : ' ';
+        return `${marker} ${slug.padEnd(slugWidth)}  ${preset.gloss}`;
+    });
+    return [header, ...rows].join('\n');
+}
+//# sourceMappingURL=presets.js.map