@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

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

@@ -1,133 +0,0 @@
-/**
- * UX — `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 ):
- *
- *  - `.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 / the upstream 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

@@ -1,111 +0,0 @@
-/**
- * — 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

@@ -1,108 +0,0 @@
-/**
- * — 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

@@ -1,176 +0,0 @@
-/**
- * — 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