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

package/dist/core/auto-update/state.js

@@ -0,0 +1,235 @@
+/**
+ * Leak L27 (2026-05-27) — Auto-update channel + last-check persistence.
+ *
+ * Two pieces of disk state are managed here:
+ *
+ *   1. **Channel selection** — `~/.pugi/config.json::updateChannel`.
+ *      Persisted across sessions so `pugi update` keeps polling the
+ *      same track the operator opted into via `pugi update --channel
+ *      <name>`. Mirrors the read/write pattern used by
+ *      `core/permissions/state.ts::getGlobalDefaultMode` (passthrough
+ *      schema, atomic tmp+rename, defensive parse).
+ *
+ *   2. **Last-check timestamp** — `~/.pugi/.last-update-check` (ISO
+ *      string, single-line). Read by the cold-start banner gate so
+ *      operators only see the "update available" hint once per
+ *      `UPDATE_CHECK_INTERVAL_HOURS` (default 24h). Living on its own
+ *      file (NOT a JSON object inside config.json) is intentional:
+ *      the timestamp is a hot path — every CLI invocation touches it —
+ *      and a single-line read+write is materially faster than the
+ *      JSON parse + serialise of the broader config doc, with no
+ *      schema coupling cost.
+ *
+ * Module contract:
+ *
+ *   - Every file path resolver accepts a `homeDir` override so the
+ *     test suite can drive the module through a per-test mkdtemp
+ *     directory without polluting the real `~/.pugi/`.
+ *
+ *   - Parse / read helpers NEVER throw on a malformed file. A
+ *     corrupted JSON blob, a missing field, or an unreadable file all
+ *     collapse to "no persisted value" so the next layer (the CLI
+ *     flag or the hard default `beta`) takes over. A future-self
+ *     debugging an update flow against a corrupt config never has the
+ *     CLI crash on them.
+ *
+ *   - Write helpers use the atomic tmp+rename idiom so a kill mid-
+ *     write never produces a half-flushed JSON document. The
+ *     timestamp file is small enough that POSIX `rename` is itself
+ *     atomic in practice, but we keep the idiom uniform with the
+ *     config write so reviewers do not have to context-switch.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, dirname } from 'node:path';
+import { z } from 'zod';
+import { DEFAULT_UPDATE_CHANNEL, UPDATE_CHANNELS, } from './channels.js';
+/**
+ * Default rate-limit window between registry probes. Operators see the
+ * cold-start banner at most once per window. Override per call via
+ * `shouldCheckForUpdate({ intervalHours })` — the cron-style scheduler
+ * passes 0 to force a check on every invocation, the doctor probe
+ * passes 24 to match the operator-visible cadence.
+ */
+export const UPDATE_CHECK_INTERVAL_HOURS = 24;
+/** Filename of the per-user channel + misc config. Mirrors L6 / L25. */
+const CONFIG_FILE = '.pugi/config.json';
+/** Filename of the standalone last-check ISO timestamp. */
+const LAST_CHECK_FILE = '.pugi/.last-update-check';
+/**
+ * Zod schema for the channel slice of `~/.pugi/config.json`. The
+ * passthrough lets sibling skills (L6 `defaultPermissionMode`, L25
+ * onboarding marker, etc.) coexist in the same JSON document without
+ * dropping their fields on a channel write.
+ */
+const channelConfigSchema = z
+    .object({
+    updateChannel: z.enum(['stable', 'beta', 'canary']).optional(),
+})
+    .partial()
+    .passthrough();
+/**
+ * Resolve the absolute path of the per-user config file. Defaults to
+ * the real home dir, but every caller in the spec passes an explicit
+ * tmpdir so the persisted writes never escape the test sandbox.
+ */
+export function configPath(homeDir = homedir()) {
+    return resolve(homeDir, CONFIG_FILE);
+}
+/**
+ * Resolve the absolute path of the single-line last-check file.
+ */
+export function lastCheckPath(homeDir = homedir()) {
+    return resolve(homeDir, LAST_CHECK_FILE);
+}
+/**
+ * Read the persisted channel selection. Returns `null` when the
+ * config file is absent, the field is unset, or the file is unparse-
+ * able. The caller layers in the CLI flag + the hard default
+ * `DEFAULT_UPDATE_CHANNEL`.
+ *
+ * Defensive parse is intentional — a half-written config from a
+ * crashed session should never block `pugi update` from finishing the
+ * channel switch.
+ */
+export function getUpdateChannel(homeDir = homedir()) {
+    const path = configPath(homeDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = channelConfigSchema.parse(JSON.parse(raw));
+        return parsed.updateChannel ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the effective channel for an invocation. Resolution order:
+ *
+ *   1. `cliFlag` (when provided + parses to a known channel).
+ *   2. `~/.pugi/config.json::updateChannel`.
+ *   3. `DEFAULT_UPDATE_CHANNEL` (currently `beta`).
+ *
+ * An invalid `cliFlag` (e.g. `--channel yolo`) falls through to the
+ * next layer rather than crashing — the dispatcher already validates
+ * the flag up front and surfaces a deterministic error for unknown
+ * names. This helper exists for code paths (the doctor probe, the
+ * cold-start banner) where no CLI flag is in play and a silent fall-
+ * through is the correct behaviour.
+ */
+export function resolveEffectiveChannel(options = {}) {
+    const cli = options.cliFlag;
+    if (cli && typeof cli === 'string') {
+        const trimmed = cli.trim().toLowerCase();
+        for (const channel of UPDATE_CHANNELS) {
+            if (channel === trimmed)
+                return channel;
+        }
+    }
+    const persisted = getUpdateChannel(options.homeDir ?? homedir());
+    if (persisted)
+        return persisted;
+    return DEFAULT_UPDATE_CHANNEL;
+}
+/**
+ * Persist the channel to `~/.pugi/config.json::updateChannel`. Creates
+ * `~/.pugi/` when missing; preserves any unrelated keys in the file
+ * (passthrough schema). Atomic tmp+rename so a kill mid-write never
+ * leaves the config half-flushed.
+ */
+export function setUpdateChannel(channel, homeDir = homedir()) {
+    const path = configPath(homeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path)
+        ? safeParseObject(readFileSync(path, 'utf8'))
+        : {};
+    const next = { ...existing, updateChannel: channel };
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmpPath, path);
+}
+/**
+ * Read the ISO timestamp of the most recent registry probe. Returns
+ * `null` when the file is absent or the contents do not parse as a
+ * valid Date. The caller treats `null` as "never checked" and runs an
+ * immediate probe.
+ */
+export function readLastCheckedAt(homeDir = homedir()) {
+    const path = lastCheckPath(homeDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        if (raw.length === 0)
+            return null;
+        const ts = Date.parse(raw);
+        if (!Number.isFinite(ts))
+            return null;
+        return new Date(ts);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the timestamp of the most recent registry probe. Atomic
+ * tmp+rename for the same reasons as `setUpdateChannel` — the file is
+ * small but we keep the idiom uniform.
+ */
+export function writeLastCheckedAt(when, homeDir = homedir()) {
+    const path = lastCheckPath(homeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${when.toISOString()}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmpPath, path);
+}
+/**
+ * Decide whether the cold-start hint should run a fresh registry
+ * probe. Returns true when the last probe was more than
+ * `intervalHours` ago OR the timestamp file is missing entirely.
+ *
+ * Pass `intervalHours = 0` to force a probe on every call (used by
+ * the `pugi update --check` JSON surface where the operator is
+ * explicitly asking for a fresh result).
+ */
+export function shouldCheckForUpdate(options = {}) {
+    const now = options.now ? options.now() : Date.now();
+    const intervalHours = options.intervalHours ?? UPDATE_CHECK_INTERVAL_HOURS;
+    if (intervalHours <= 0)
+        return true;
+    const last = readLastCheckedAt(options.homeDir ?? homedir());
+    if (!last)
+        return true;
+    const ageMs = now - last.getTime();
+    const windowMs = intervalHours * 60 * 60 * 1_000;
+    return ageMs >= windowMs;
+}
+/**
+ * Defensive helper — parse JSON to an object; non-object payloads
+ * (top-level array, primitive) collapse to an empty object so the
+ * channel-write merge does not surface a TypeError. Mirrors the
+ * `safeParseObject` in `core/permissions/state.ts` — duplicating the
+ * 10 lines is cheaper than threading a shared util module through
+ * two unrelated leak surfaces.
+ */
+function safeParseObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/core/bare-mode/index.js

@@ -0,0 +1,107 @@
+/**
+ * Leak L22 (2026-05-27) — `--bare` mode predicate.
+ *
+ * Mirror of Claude Code's `--bare` flag: when active the CLI behaves
+ * like a plain LLM frontend with NO project auto-discovery. Useful for:
+ *
+ *   - headless scripting where the operator wants deterministic, repo-
+ *     independent behavior (`pugi --bare --print "..."`),
+ *   - dropping into a workspace without auto-creating `.pugi/`,
+ *   - REPL sessions that should NOT inject ambient `PUGI.md` / `CLAUDE.md`
+ *     into the model prompt,
+ *   - support / triage flows where the engineer needs the CLI to act
+ *     like a fresh install regardless of where it's invoked.
+ *
+ * Discovery surfaces gated by `isBareMode()`:
+ *
+ *   1. `PUGI.md` / `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` parent-dir
+ *      walk-up (`loadTraversedMarkdown` in `core/context/markdown-traverse.ts`).
+ *   2. Workspace-root markdown context (`loadMarkdownContext` consumers).
+ *   3. Auto-init `.pugi/` scaffold on REPL boot in untouched dirs.
+ *   4. Persona / skill auto-load from `.pugi/skills/`.
+ *   5. Workspace summary (`readPugiSummary`) read on REPL session start.
+ *
+ * Activation precedence — the bare bit is "sticky" once set so any
+ * subprocess the CLI spawns inherits it without re-passing the flag:
+ *
+ *   1. Top-level `--bare` arg parsed by `parseArgs` in `runtime/cli.ts`.
+ *      The parser sets `process.env.PUGI_BARE='1'` BEFORE the dispatch
+ *      flows so callsites checking the env see the activated state.
+ *   2. `PUGI_BARE=1` env var (any value matching `/^(1|true|yes|on)$/i`).
+ *   3. Default: bare mode OFF — full auto-discovery as before.
+ *
+ * This mirrors the existing `PUGI_SKIP_SPLASH` / `PUGI_NO_AUTO_INIT`
+ * env-flag pattern so the bare module fits the rest of the runtime
+ * configuration grammar without inventing a new wire.
+ *
+ * Test surface: `apps/pugi-cli/test/bare-mode.spec.ts` exercises the
+ * env precedence, value parsing, and the explicit-set / clear helpers.
+ */
+/**
+ * Env var consulted by `isBareMode()`. Kept as an export so the spec
+ * + the runtime CLI can use the same constant — no string-typing of
+ * the wire name across modules.
+ */
+export const PUGI_BARE_ENV = 'PUGI_BARE';
+/**
+ * Truthy values recognised on the `PUGI_BARE` env. Anything else
+ * (empty string, `0`, `false`, `no`, `off`, `disabled`, undefined) is
+ * treated as bare-mode OFF. The list is intentionally short — the
+ * value is set by the CLI parser and is not customer-typed prose, so
+ * we do not need a permissive boolean coercion.
+ */
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+/**
+ * Return true when bare mode is active for the current process. Reads
+ * `process.env[PUGI_BARE_ENV]` and applies the truthy-value match.
+ *
+ * Safe to call from any module (no FS, no side-effects). The runtime
+ * cost is a single env-var lookup + lower-case + set membership, so
+ * gating hot-path callsites with `if (isBareMode()) return ...` adds
+ * effectively zero overhead in the default (non-bare) case.
+ */
+export function isBareMode(env = process.env) {
+    const raw = env[PUGI_BARE_ENV];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return false;
+    return TRUTHY.has(raw.toLowerCase());
+}
+/**
+ * Explicitly activate bare mode for the current process. Called by
+ * `parseArgs` in `runtime/cli.ts` when `--bare` is seen on the command
+ * line so downstream modules (engine, REPL bootstrap, doctor probe)
+ * see a consistent activated state via `isBareMode()` regardless of
+ * whether the operator set the env var manually or used the flag.
+ *
+ * Subprocess inheritance is the reason we mutate `process.env` rather
+ * than threading a `bare: boolean` field through every call signature
+ * — every Node child_process spawn inherits `process.env` by default,
+ * so the bare bit propagates to MCP servers / hook scripts / git
+ * subprocesses without ceremony.
+ */
+export function setBareMode(env = process.env) {
+    env[PUGI_BARE_ENV] = '1';
+}
+/**
+ * Clear bare mode for the current process. Provided primarily for the
+ * spec so adjacent tests do not leak state between cases. Production
+ * code does NOT call this — bare mode is a one-shot per process.
+ */
+export function clearBareMode(env = process.env) {
+    delete env[PUGI_BARE_ENV];
+}
+/**
+ * Human-readable one-line banner printed by the dispatcher when bare
+ * mode is active and the invocation is NOT JSON-only. Kept as a single
+ * constant so the spec can assert the exact wording and downstream
+ * tools (status bars, doctor row, REPL header) stay in lockstep.
+ */
+export const BARE_MODE_BANNER = 'Pugi --bare mode: project auto-discovery disabled.';
+/**
+ * Short label rendered inside the `pugi doctor` table when bare mode
+ * is active. The doctor probe surfaces `BARE MODE` as a separate row
+ * so operators triaging "why is Pugi ignoring my PUGI.md" see the
+ * cause without grep'ing the env.
+ */
+export const BARE_MODE_DOCTOR_LABEL = 'BARE MODE';
+//# sourceMappingURL=index.js.map