@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

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

@@ -0,0 +1,108 @@
+/**
+ * — 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 @@
+/**
+ * — Output-style presets.
+ *
+ * Mirror of the upstream tool'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 @@
+/**
+ * — 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