@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

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

@@ -0,0 +1,107 @@
+/**
+ * — `--bare` mode predicate.
+ *
+ * Mirror of the upstream tool'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

package/dist/core/bash/redirect.js

@@ -0,0 +1,281 @@
+/**
+ * bash/redirect — stdout-redirect helper (Pugi backlog P2,
+ * Karpathy "log discipline" pattern).
+ *
+ * Long-running scripts (training loops, monorepo builds, agentic
+ * stdout dumps) routinely emit hundreds of MB of text. Feeding that
+ * back into the LLM's context window burns tokens for noise — the
+ * model only needs the path + the trailing N lines to know whether
+ * the run succeeded and, if it failed, where to start looking.
+ *
+ * The redirect pipeline:
+ *  1. Caller flips `redirect` on `BashToolInput` to opt in.
+ *  2. `resolveRedirectTarget` decides the on-disk path:
+ *       - default: .pugi/runs/<sessionId>/bash-<commandHash>.log
+ *       - override: workspace-relative path supplied by the caller
+ *     Concurrent calls with the same hash dedupe through the
+ *     filename's `tool-call-id` suffix so two parallel dispatches
+ *     never share a target file.
+ *  3. The bash tool spawns the child with stdio piped to a write
+ *     stream pointed at the resolved path (no in-memory buffering of
+ *     stdout/stderr beyond Node's internal pipe).
+ *  4. After the child exits, `readTail` reads the last N lines from
+ *     the log file and `buildRedirectEnvelope` constructs the
+ *     model-facing payload: empty stdout/stderr, populated logPath,
+ *     populated tail, `truncated: false`.
+ *
+ * Token-savings example (real-world ceiling):
+ *  100k-line `pnpm build` log = ~6.4 MB raw stdout.
+ *  - Without redirect: truncated to 32 KB head = ~8k tokens, and the
+ *    trailing error (where the bug actually lives) is invisible.
+ *  - With redirect: empty stdout + 20-line tail = ~400 tokens, plus
+ *    logPath the operator/agent can tail on demand.
+ *
+ * This module is intentionally framework-free — it only owns path
+ * resolution, file tail reading, and the envelope shape. The bash
+ * tool wires it into the spawn lifecycle.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+/**
+ * Default tail size when the caller does not pin one. Mirrors the
+ * Karpathy training-loop convention (`tail -n 20` for the last
+ * checkpoint window).
+ */
+export const REDIRECT_DEFAULT_TAIL_LINES = 20;
+/**
+ * Hard upper bound on tail size. The cap defends the context budget
+ * from a caller that flips redirect on but then asks for 100k tail
+ * lines — which would defeat the entire point of the redirect.
+ */
+export const REDIRECT_MAX_TAIL_LINES = 200;
+/**
+ * Deterministically hash a command string into a short hex prefix so
+ * the default log filename is predictable. Collisions are not a
+ * security concern (the file is workspace-scoped and the tool-call-id
+ * suffix disambiguates concurrent calls) so SHA-256 → 10 hex chars is
+ * the same compromise the agent-progress writer uses.
+ */
+export function hashCommand(command) {
+    return createHash('sha256').update(command).digest('hex').slice(0, 10);
+}
+/**
+ * Validate and clamp the caller-supplied tail size. Negative / zero /
+ * NaN / >max values fall back to the default rather than throwing —
+ * the bash tool is the wrong layer to refuse a dispatch over a tail
+ * sizing bug.
+ */
+export function normalizeTailLines(value) {
+    if (typeof value !== 'number' ||
+        !Number.isFinite(value) ||
+        value <= 0) {
+        return REDIRECT_DEFAULT_TAIL_LINES;
+    }
+    return Math.min(Math.floor(value), REDIRECT_MAX_TAIL_LINES);
+}
+/**
+ * Resolve the workspace-relative target the caller asked for (or the
+ * tool default) into an absolute path. Throws on traversal escapes
+ * (`..` out of workspace) and absolute-path overrides — those are the
+ * same anti-patterns the existing `resolveWorkspacePath` rejects, but
+ * reimplemented locally so this helper has no cross-module coupling.
+ */
+export function resolveRedirectTarget(opts) {
+    const { workspaceRoot, sessionId, toolCallId, command, override } = opts;
+    const hash = hashCommand(command);
+    // Concurrent calls with the same command hash get distinct files by
+    // suffixing the (unique) tool-call-id. The bash tool already
+    // allocates a fresh id per dispatch, so this is sufficient even
+    // when two REPL panes fire the identical command at the same
+    // millisecond.
+    const defaultRelative = join('.pugi', 'runs', sessionId, `bash-${hash}-${toolCallId}.log`);
+    const requested = override ?? defaultRelative;
+    if (isAbsolute(requested)) {
+        throw new Error(`redirect.path must be workspace-relative; got absolute path: ${requested}`);
+    }
+    const absolutePath = resolve(workspaceRoot, requested);
+    const rel = relative(workspaceRoot, absolutePath);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`redirect.path escapes workspace root: ${requested}`);
+    }
+    // Derive the directory the bash tool needs to mkdir before opening
+    // the write stream. We split on the trailing separator rather than
+    // calling `dirname` so the helper has zero `path` API drift across
+    // platforms.
+    const slashIndex = Math.max(absolutePath.lastIndexOf('/'), absolutePath.lastIndexOf('\\'));
+    const directory = slashIndex > 0
+        ? absolutePath.slice(0, slashIndex)
+        : workspaceRoot;
+    return {
+        absolutePath,
+        workspacePath: rel,
+        directory,
+    };
+}
+/**
+ * Ensure the redirect file is opened for write through a
+ * `tmp + rename` dance so a partial write (operator Ctrl+C, child
+ * crash mid-flush) never leaves a torn file at the target path.
+ *
+ * Returns the open file descriptor along with the temp path so the
+ * caller can rename-on-success and unlink-on-cancel.
+ *
+ * The temp path mirrors the existing `editTool`/`writeTool` pattern:
+ * append `.pugi-tmp-<ts>` to the final name. We use `openSync` (vs
+ * `createWriteStream`) so the bash tool can hand the fd directly to
+ * `spawn`'s `stdio` array.
+ */
+export function openRedirectFile(target) {
+    mkdirSync(target.directory, { recursive: true });
+    const tempPath = `${target.absolutePath}.pugi-tmp-${Date.now()}-${process.pid}`;
+    // mode 0o600 = rw for owner only — log files may contain secrets
+    // the child process leaked to stdout, so we lock them down by
+    // default. The bash tool can later promote them to 0o644 on a
+    // per-call basis when the operator opts in.
+    const fd = openSync(tempPath, 'w', 0o600);
+    return { fd, tempPath };
+}
+/**
+ * Finalise the temp file by renaming it onto `absolutePath` so the
+ * model-facing logPath always points at a complete file. Idempotent —
+ * the bash tool calls this on success AND on timeout/cancel so the
+ * partial log is preserved as a debugging artifact (the agent can
+ * still read the tail to see how far the run got).
+ */
+export function finaliseRedirectFile(target, tempPath) {
+    if (!existsSync(tempPath))
+        return;
+    renameSync(tempPath, target.absolutePath);
+}
+/**
+ * Best-effort cleanup of the temp file when the redirect path was
+ * never fully written (e.g. spawn never started). Swallows ENOENT so
+ * the cleanup is idempotent.
+ */
+export function cleanupRedirectTemp(tempPath) {
+    try {
+        if (existsSync(tempPath))
+            unlinkSync(tempPath);
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Read the last N lines of a file, without slurping the whole file
+ * into memory. We use a backwards-chunked read so even multi-GB logs
+ * stay bounded by the tail size.
+ *
+ * The implementation is intentionally simple — we read at most
+ * `maxBytes` (~64 KB by default) from the file tail because 200 lines
+ * of compiler output rarely exceed that. Long-line cases (one massive
+ * JSON blob on a single line) fall back to "whatever fits in maxBytes
+ * counts as the tail".
+ */
+export function readTail(path, lines, options = {}) {
+    if (!existsSync(path))
+        return '';
+    const maxBytes = options.maxBytes ?? 64 * 1024;
+    const stat = statSync(path);
+    if (stat.size === 0)
+        return '';
+    const readSize = Math.min(stat.size, maxBytes);
+    // `readFileSync` with an explicit byte slice is the simplest API
+    // available in node:fs without dropping to `read(fd, buf, ...)`.
+    // We read the trailing window of the file by opening it and
+    // seeking to `stat.size - readSize`.
+    const fd = openSync(path, 'r');
+    try {
+        const buf = Buffer.alloc(readSize);
+        const bytesRead = readFileSyncSlice(fd, buf, stat.size - readSize);
+        const trailing = buf.subarray(0, bytesRead).toString('utf8');
+        // The first line in the buffer may be a partial line if we did
+        // not seek to a line boundary. Drop it unless the buffer covers
+        // the whole file.
+        const startedFromHead = stat.size <= readSize;
+        const split = trailing.split('\n');
+        // Re-emit the tail; if we DID start mid-line, discard the
+        // partial-leading fragment.
+        const usable = startedFromHead ? split : split.slice(1);
+        // Trailing newline produces an empty string at the end of split;
+        // drop it so the line count matches operator expectation.
+        if (usable.length > 0 && usable[usable.length - 1] === '') {
+            usable.pop();
+        }
+        return usable.slice(-lines).join('\n');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Helper: read `buf.length` bytes from `fd` starting at `position`.
+ * Returns the actual number of bytes read.
+ *
+ * Loops over `readSync` so a short read on a large file (interruptible
+ * syscall, EAGAIN) still produces the full requested window. Bounded
+ * by `buf.length` so the helper cannot over-read past the caller's
+ * buffer regardless of how the kernel chunked the response.
+ */
+function readFileSyncSlice(fd, buf, position) {
+    let totalRead = 0;
+    while (totalRead < buf.length) {
+        const got = readSync(fd, buf, totalRead, buf.length - totalRead, position + totalRead);
+        if (got === 0)
+            break;
+        totalRead += got;
+    }
+    return totalRead;
+}
+/**
+ * Compose the model-facing envelope. The bash tool calls this once
+ * the child has exited and the log file has been renamed into place.
+ *
+ * `truncated` is hardwired to `false` because the redirect contract
+ * is "the full output is in the log, we hand you the path and a
+ * tail". The legacy stdout/stderr truncation marker (`(...truncated
+ * at N bytes)`) only fires in the buffered path that this redirect
+ * pipeline replaces — surfacing `truncated: true` for a redirect
+ * would mislead the model into thinking it lost data.
+ */
+export function buildRedirectEnvelope(opts) {
+    return {
+        stdout: '',
+        stderr: '',
+        exitCode: opts.exitCode,
+        logPath: opts.logPath,
+        tail: opts.tail,
+        truncated: false,
+    };
+}
+/**
+ * Convenience wrapper for the bash tool: given a completed spawn
+ * (exit code + finalised log path) and a caller-supplied
+ * `BashRedirectOptions`, build the envelope in one call. The bash
+ * tool keeps the spawn lifecycle (open fd, stream child's
+ * stdout/stderr to it, wait for close, rename) but delegates the
+ * tail-read + envelope assembly here so the test suite can exercise
+ * the helper without spinning up a child process.
+ */
+export function applyRedirect(opts) {
+    const tail = readTail(opts.target.absolutePath, opts.tailLines);
+    return buildRedirectEnvelope({
+        exitCode: opts.exitCode,
+        logPath: opts.target.workspacePath,
+        tail,
+    });
+}
+/**
+ * Internal helper used by the spec when it needs to seed a log file
+ * for the tail-reader. Exported so tests do not depend on the
+ * file-tools/write surface (which has its own permission gate).
+ */
+export function writeLogForTest(absolutePath, body) {
+    const slashIndex = Math.max(absolutePath.lastIndexOf('/'), absolutePath.lastIndexOf('\\'));
+    if (slashIndex > 0) {
+        mkdirSync(absolutePath.slice(0, slashIndex), { recursive: true });
+    }
+    writeFileSync(absolutePath, body, { encoding: 'utf8', mode: 0o600 });
+}
+//# sourceMappingURL=redirect.js.map