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

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

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

@@ -0,0 +1,185 @@
+/**
+ * Leak L18 (2026-05-27) — Output-style state persistence.
+ *
+ * Two-tier storage:
+ *
+ *   1. **Workspace** — `<workspaceRoot>/.pugi/config.json`. Set by
+ *      `/style <name>` from inside the REPL or `pugi style <name>`
+ *      without `--persist`. Overrides the user default for the
+ *      current workspace only. Survives sessions because the same
+ *      `.pugi/` survives sessions.
+ *
+ *   2. **User default** — `~/.pugi/config.json` (PUGI_HOME-aware).
+ *      Set by `pugi style <name> --persist` or
+ *      `/style <name> --persist`. Applies to every workspace that
+ *      has no workspace-level override.
+ *
+ * Precedence (highest → lowest):
+ *
+ *   workspace value > user value > DEFAULT_OUTPUT_STYLE ('default')
+ *
+ * Both files live under the same `pugi-config-v1` JSON envelope as
+ * other settings (permissionMode, privacy, model, preferredEndpoint).
+ * The schema is intentionally NOT shared with `runtime/commands/config.ts`'s
+ * strict Zod schema — `outputStyle` is read/written ONLY through this
+ * module so `pugi config set outputStyle=…` is NOT a supported path
+ * (it would silently bypass the slug validator). Operators get a
+ * single surface: `/style` + `pugi style`.
+ *
+ * File layout (one config.json, multiple keys; this module owns the
+ * `outputStyle` key only):
+ *
+ *   {
+ *     "permissionMode": "ask",
+ *     "outputStyle": "terse",
+ *     ...
+ *   }
+ *
+ * The reader tolerates:
+ *   - missing file (returns the default slug),
+ *   - empty file (returns the default slug),
+ *   - malformed JSON (returns the default slug — DO NOT crash REPL
+ *     boot because of a hand-edited config),
+ *   - unknown slug (returns the default slug + emits no error; the
+ *     operator can `/style` to see the table and re-set).
+ *
+ * The writer is a read-modify-write to preserve neighbouring keys
+ * (permissionMode etc.) — overwriting the whole file would clobber
+ * the other tier's settings.
+ *
+ * Test surface: `test/commands/output-style-state.spec.ts` exercises
+ * precedence, malformed-config tolerance, persistence across reads,
+ * the `--persist` (user-default) path, and reset semantics.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { DEFAULT_OUTPUT_STYLE, isOutputStyleSlug, } from './presets.js';
+/**
+ * Env override for `~/.pugi` so the spec can sandbox both tiers
+ * without touching the developer's real config. Matches the existing
+ * `runtime/commands/config.ts` convention.
+ */
+export const PUGI_HOME_ENV = 'PUGI_HOME';
+/**
+ * Resolve the active output style for the workspace, applying the
+ * precedence ladder (workspace > user > default).
+ *
+ * Pure read. Never writes, never throws — every IO failure degrades
+ * to the default slug. The function returns the source label too so
+ * the CLI surface can show the operator where the value came from.
+ */
+export function resolveOutputStyle(io) {
+    const workspaceSlug = readSlugFromFile(workspaceConfigPath(io.workspaceRoot));
+    if (workspaceSlug)
+        return { slug: workspaceSlug, source: 'workspace' };
+    const userSlug = readSlugFromFile(userConfigPath(io.env ?? process.env));
+    if (userSlug)
+        return { slug: userSlug, source: 'user' };
+    return { slug: DEFAULT_OUTPUT_STYLE, source: 'default' };
+}
+/**
+ * Write `slug` to the workspace tier. Creates `<workspaceRoot>/.pugi/`
+ * if missing. Preserves neighbouring config keys via read-modify-write.
+ */
+export function setWorkspaceOutputStyle(slug, io) {
+    writeSlugToFile(workspaceConfigPath(io.workspaceRoot), slug);
+}
+/**
+ * Write `slug` to the user tier (`~/.pugi/config.json`).
+ *
+ * Mirrors the workspace writer's read-modify-write so the user's
+ * `permissionMode` / `privacy` / `model` keys survive a style flip.
+ */
+export function setUserOutputStyle(slug, io) {
+    writeSlugToFile(userConfigPath(io.env ?? process.env), slug);
+}
+/**
+ * Clear the workspace tier's `outputStyle` key. The user tier (and
+ * therefore the eventual resolved style) is left untouched.
+ *
+ * Used by `/style --reset` so the operator can revert a workspace
+ * override without nuking the rest of their workspace config.
+ */
+export function clearWorkspaceOutputStyle(io) {
+    clearSlugInFile(workspaceConfigPath(io.workspaceRoot));
+}
+/**
+ * Clear the user tier's `outputStyle` key. Lower-blast-radius reset
+ * for operators who want every workspace to fall back to `default`
+ * unless an explicit workspace value is set.
+ */
+export function clearUserOutputStyle(io) {
+    clearSlugInFile(userConfigPath(io.env ?? process.env));
+}
+/**
+ * Workspace config path. Exported for the spec; production callers
+ * should use the `setWorkspace…` / `resolveOutputStyle` helpers.
+ */
+export function workspaceConfigPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.pugi', 'config.json');
+}
+/**
+ * User config path resolved against `PUGI_HOME` (or `~/.pugi`).
+ * Exported for the spec.
+ */
+export function userConfigPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, 'config.json');
+}
+/**
+ * Read + parse a config file. Returns an empty object on any IO or
+ * parse error. Caller-provided JSON must be a plain object; arrays /
+ * scalars / null are treated as "no config" so a hand-edited file
+ * never crashes the REPL.
+ */
+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 });
+    // 0o600 mirrors `runtime/commands/config.ts` — the config file may
+    // hold `preferredEndpoint` URLs that should not be world-readable.
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+function readSlugFromFile(path) {
+    const config = readConfigFile(path);
+    const candidate = config.outputStyle;
+    return isOutputStyleSlug(candidate) ? candidate : null;
+}
+function writeSlugToFile(path, slug) {
+    const config = readConfigFile(path);
+    config.outputStyle = slug;
+    writeConfigFile(path, config);
+}
+function clearSlugInFile(path) {
+    const config = readConfigFile(path);
+    if (!('outputStyle' in config))
+        return;
+    delete config.outputStyle;
+    writeConfigFile(path, config);
+}
+//# sourceMappingURL=state.js.map

package/dist/core/permissions/index.js

@@ -14,5 +14,5 @@
 export { DEFAULT_PERMISSION_MODE, PERMISSION_MODE_GLOSS, PERMISSION_MODES, isPermissionMode, parsePermissionMode, toLegacyMode, } from './mode.js';
 export { getToolClass, listBuiltInToolClasses, } from './tool-class.js';
 export { ASK_OPTIONS, PermissionDenied, applyAskAnswer, createAskAlwaysCache, gate, } from './gate.js';
-export { getCurrentMode, getGlobalDefaultMode, globalConfigPath, resolveMode, sessionStatePath, setCurrentMode, setGlobalDefaultMode, } from './state.js';
+export { getCurrentMode, getGlobalDefaultMode, getPreviousMode, globalConfigPath, resolveMode, sessionStatePath, setCurrentMode, setGlobalDefaultMode, setPreviousMode, } from './state.js';
 //# sourceMappingURL=index.js.map

package/dist/core/permissions/state.js

@@ -27,6 +27,13 @@ const permissionModeEnum = z.enum(['plan', 'ask', 'allow', 'bypass']);
 const sessionStateSchema = z
     .object({
     permissionMode: permissionModeEnum.optional(),
+    /**
+     * Leak L7: snapshot of the mode that was active immediately BEFORE
+     * the operator typed `/plan` (or `/plan <prompt>`). `/plan --back`
+     * pops this snapshot and restores it. Cleared after a successful
+     * pop so a second `/plan --back` does not double-revert.
+     */
+    previousPermissionMode: permissionModeEnum.optional(),
 })
     .partial()
     .passthrough();
@@ -90,6 +97,54 @@ export function setCurrentMode(workspaceRoot, mode) {
     writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
     renameSync(tmpPath, path);
 }
+/**
+ * Leak L7 — read the snapshot of the mode that was active before the
+ * most-recent `/plan` (or `pugi plan`) entry. Returns null when the
+ * file is absent OR the field is unset. Same defensive behaviour as
+ * `getCurrentMode`: a malformed session file never breaks the slash
+ * command — the worst case is `/plan --back` reports "no previous
+ * mode to restore" and the operator picks the target mode explicitly.
+ */
+export function getPreviousMode(workspaceRoot) {
+    const path = sessionStatePath(workspaceRoot);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = sessionStateSchema.parse(JSON.parse(raw));
+        return isPermissionMode(parsed.previousPermissionMode)
+            ? parsed.previousPermissionMode
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Leak L7 — record the mode that was active immediately before the
+ * operator switched to plan. The runtime calls this AT `/plan` entry
+ * with the current mode (whatever `resolveMode` returned). Atomic
+ * tmp+rename keeps the snapshot consistent if the process is killed
+ * mid-write. Pass `null` to clear the snapshot (used after a
+ * successful `/plan --back` so a second `--back` does not loop).
+ */
+export function setPreviousMode(workspaceRoot, mode) {
+    const path = sessionStatePath(workspaceRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path)
+        ? safeParseObject(readFileSync(path, 'utf8'))
+        : {};
+    const next = { ...existing };
+    if (mode === null) {
+        delete next.previousPermissionMode;
+    }
+    else {
+        next.previousPermissionMode = mode;
+    }
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmpPath, path);
+}
 /**
  * Read `~/.pugi/config.json::defaultPermissionMode`. Returns null when
  * the file is absent / the field is unset; same defensive behaviour

package/dist/core/pugi-md/context-injector.js

@@ -0,0 +1,76 @@
+/**
+ * Aggregate byte cap on the full rendered block. 96 KB = 3 files at
+ * the per-file cap, which is enough for cwd + parent + homedir while
+ * leaving plenty of prompt budget for the rest of the system prompt.
+ * Anything beyond is replaced with a truncation marker.
+ */
+export const MAX_INJECT_BYTES = 96 * 1024;
+/**
+ * Marker line emitted when the aggregate cap is hit. Visible to the
+ * model so it knows ambient context was clipped; visible to the
+ * operator via the doctor probe so they can decide whether to trim
+ * their `PUGI.md` hierarchy.
+ */
+export const TRUNCATION_MARKER = '<ambient-context-truncated reason="aggregate-cap" />';
+/**
+ * Render a HierarchyFile array into the system-prompt block. Returns
+ * `''` when `files` is empty. Each file becomes one
+ * `<ambient-context source="..." level="...">...</ambient-context>`
+ * stanza separated by a single newline.
+ *
+ * Determinism: same input always produces byte-identical output.
+ */
+export function renderAmbientContext(files) {
+    if (files.length === 0)
+        return '';
+    const stanzas = [];
+    let bytes = 0;
+    let truncated = false;
+    for (const file of files) {
+        const stanza = renderStanza(file);
+        const stanzaBytes = Buffer.byteLength(stanza, 'utf8') + 1; // newline join cost
+        if (bytes + stanzaBytes > MAX_INJECT_BYTES) {
+            truncated = true;
+            break;
+        }
+        stanzas.push(stanza);
+        bytes += stanzaBytes;
+    }
+    if (truncated)
+        stanzas.push(TRUNCATION_MARKER);
+    return stanzas.join('\n');
+}
+/**
+ * Build a single `<ambient-context>` stanza for one HierarchyFile.
+ * The `source` attribute carries the absolute path (after realpath)
+ * so the model can cite which file a piece of guidance came from
+ * when it explains its decisions to the operator.
+ */
+function renderStanza(file) {
+    const sourceAttr = escapeAttr(file.path);
+    const levelAttr = String(file.level);
+    // No trailing newline inside `content` — the join adds one between
+    // stanzas. Trimming the file's trailing whitespace keeps the tag
+    // close to the content for readability when an engineer dumps the
+    // assembled prompt for debugging.
+    const trimmed = file.content.replace(/\s+$/g, '');
+    return [
+        `<ambient-context source="${sourceAttr}" level="${levelAttr}">`,
+        trimmed,
+        `</ambient-context>`,
+    ].join('\n');
+}
+/**
+ * Escape an XML attribute value. We expect operator-controlled paths
+ * (not adversarial input) but `&`, `"` and `<` are still possible in
+ * symlinked / unicode paths so we escape them defensively. The model
+ * has been trained to read this attribute as opaque metadata.
+ */
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=context-injector.js.map