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

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

@@ -1,185 +0,0 @@
-/**
- * — 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/path-security.js

@@ -1,345 +0,0 @@
-/**
- * Path-security gate for Pugi CLI file operations.
- *
- * The original `resolveWorkspacePath` (preserved below) is the read-path
- * gate: it stops relative-path traversal, URL-encoded traversal, and
- * symlink escapes at the leaf. It is kept as the existing call surface
- * for `read` and other non-mutating tools.
- *
- * `assertSafeWritePath` is a stricter, write-only gate ported from
- * external's Rust `path_guard.rs` (Apache-2.0). It adds:
- *
- *  1. `..` segment rejection BEFORE any filesystem touch.
- *  2. Walk-up canonicalize: finds the deepest existing ancestor,
- *     canonicalizes it (resolving every symlink in the existing
- *     prefix), then reattaches the non-existent tail. This closes
- *     the "parent's parent is a symlink" bypass that catches naive
- *     canonicalize-the-parent implementations.
- *  3. Leaf-symlink reject: refuse to write through a symlink even
- *     when the file already exists. Covers dangling symlinks too.
- *  4. Fail-CLOSED on empty allowed roots: an empty PUGI_ALLOWED_ROOTS
- *     means "no writes anywhere" rather than "writes allowed
- *     everywhere".
- *  5. Containment check against canonicalized allowed roots.
- *  6. Denylist of system, credential, and shell-init paths even
- *     when they sit inside an allowed root (defense in depth — a
- *     misconfigured root pointing at `$HOME` still cannot clobber
- *     `~/.ssh/id_ed25519`).
- *
- * ---
- * Portions of `assertSafeWritePath` and `canonicalizeWithWalkUp` are
- * derived from external `kei-mcp/src/handlers/safe_tools/
- * path_guard.rs` (Apache-2.0). See `licenses/EXTERNAL-LICENSE-NOTICE.md`
- * at the repo root for attribution and the full upstream license
- * reference.
- */
-import { existsSync, lstatSync, realpathSync, } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, relative, resolve, sep, } from 'node:path';
-/**
- * Resolve and validate that an inputPath stays within the workspace.
- *
- * Defends against:
- *  1. relative-path traversal (`../etc/passwd`)
- *  2. URL-encoded traversal (`..%2Fetc%2Fpasswd`)
- *  3. symlink escapes at the target itself (`alias-link -> /etc/passwd`)
- *
- * The previous implementation also resolved the parent's realpath and
- * compared to the workspace root. That broke `pugi explain .` on macOS
- * where the workspace is under a symlinked prefix (`/tmp` → `/private/tmp`)
- * because the parent's realpath legitimately sits one level above the
- * workspace. The fix: compute the target's realpath (or the literal
- * resolved path when the target does not yet exist) and require that to
- * stay inside the workspace's realpath. Parent-chain symlinks that
- * actually escape will fail this check; benign system symlinks above
- * the workspace will not.
- *
- * Throws when the resolved path is outside the workspace. Returns the
- * literal absolute path on disk (suitable for `readFileSync` /
- * `writeFileSync`).
- */
-export function resolveWorkspacePath(root, inputPath) {
-    const decoded = decodeURIComponent(inputPath);
-    const target = resolve(root, decoded);
-    const realRoot = realpathSync.native(root);
-    let realTarget;
-    try {
-        realTarget = realpathSync.native(target);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== 'ENOENT' && code !== 'ENOTDIR')
-            throw error;
-        // Target does not exist yet (write/create). Anchor against the
-        // parent's realpath so the new file we are about to create stays
-        // inside the workspace.
-        let realParent;
-        try {
-            realParent = realpathSync.native(resolve(target, '..'));
-        }
-        catch (parentError) {
-            const parentCode = parentError.code;
-            if (parentCode !== 'ENOENT' && parentCode !== 'ENOTDIR')
-                throw parentError;
-            throw new Error(`Path escapes workspace (missing parent): ${inputPath}`);
-        }
-        realTarget = resolve(realParent, basename(target));
-    }
-    if (!isInsideWorkspace(realTarget, realRoot)) {
-        throw new Error(`Path escapes workspace: ${inputPath}`);
-    }
-    return target;
-}
-function isInsideWorkspace(child, workspaceRoot) {
-    if (child === workspaceRoot)
-        return true;
-    const rel = relative(workspaceRoot, child);
-    return Boolean(rel) && !rel.startsWith('..') && rel !== '..';
-}
-/**
- * Apply the strict write-path guard. Returns the canonical
- * absolute path on success, throws on rejection.
- *
- * Use this for any operation that mutates the filesystem (`write`,
- * `edit`, atomic-rename targets). The error message is safe to surface
- * to the operator — it never echoes filesystem secrets.
- */
-export function assertSafeWritePath(inputPath, options = {}) {
-    if (typeof inputPath !== 'string' || inputPath.length === 0) {
-        throw new Error('file_path: empty');
-    }
-    if (inputPath.includes('\0')) {
-        throw new Error('file_path: null byte rejected');
-    }
-    // step: reject `..` segments before any FS work. We split on
-    // both `/` and the platform separator so a Windows-style `..\foo`
-    // input cannot smuggle a traversal through on macOS test paths.
-    const decoded = decodeURIComponent(inputPath);
-    const segments = decoded.split(/[/\\]/);
-    if (segments.some((seg) => seg === '..')) {
-        throw new Error(`file_path: '..' segment not allowed in ${inputPath}`);
-    }
-    // step: refuse to write through a symlink leaf. We must
-    // check the LITERAL input path (pre-canonicalize) because `realpath`
-    // unconditionally resolves symlinks — so by the time we have the
-    // canonical path the symlink fingerprint is already gone. `lstatSync`
-    // does NOT follow symlinks, which is exactly what we need.
-    const cwdRoot = options.root ?? process.cwd();
-    const literalAbsolute = isAbsolute(decoded) ? decoded : resolve(cwdRoot, decoded);
-    try {
-        const meta = lstatSync(literalAbsolute);
-        if (meta.isSymbolicLink()) {
-            throw new Error(`file_path: leaf is a symlink (refusing to follow): ${literalAbsolute}`);
-        }
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== 'ENOENT' && code !== 'ENOTDIR')
-            throw error;
-        // ENOENT/ENOTDIR is fine — the leaf simply does not exist yet
-        // (write-create path). The walk-up canonicalize below handles it.
-    }
-    const canonical = canonicalizeWithWalkUp(decoded, cwdRoot);
-    // step: fail-CLOSED on empty allowed roots.
-    const roots = computeAllowedRoots(options);
-    if (roots.length === 0) {
-        throw new Error("file_path: allowed_roots is empty — refusing all writes " +
-            '(set PUGI_ALLOWED_ROOTS to a non-empty value or run from a real cwd)');
-    }
-    // step: containment check against canonicalized allowed
-    // roots. Each root is normalized to end in `sep` so `/tmp/wsX` does
-    // not accidentally pass containment for `/tmp/ws`.
-    const inAllowedRoot = roots.some((r) => isContainedIn(canonical, r));
-    if (!inAllowedRoot) {
-        throw new Error(`file_path: outside allowed roots ${JSON.stringify(roots)}: ${canonical}`);
-    }
-    // step: denylist. Applied AFTER containment so a
-    // misconfigured root pointing at `/` or `$HOME` still cannot clobber
-    // sensitive files. We canonicalize HOME so a $HOME that lives under
-    // a symlinked prefix (macOS /var → /private/var, Linux /home →
-    // /usr/home on some FreeBSD-style mounts) still matches the
-    // canonical write target.
-    assertNotDenylisted(canonical, canonicalizeHomeDir(options.homeDir ?? homedir()));
-    return canonical;
-}
-function canonicalizeHomeDir(raw) {
-    if (!raw)
-        return raw;
-    try {
-        return realpathSync.native(raw);
-    }
-    catch {
-        return raw;
-    }
-}
-/**
- * Ported from an external utility. Finds the deepest
- * existing ancestor, canonicalizes it (resolving every symlink in the
- * existing prefix), then reattaches the non-existent tail components.
- *
- * This closes the "parent's parent is a symlink" bypass where naive
- * implementations canonicalize only the immediate parent.
- */
-export function canonicalizeWithWalkUp(inputPath, cwd) {
-    const absolute = isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath);
-    let current = absolute;
-    const tail = [];
-    // Hard cap on walk-up iterations — defense against pathological
-    // inputs that somehow evade `dirname` termination.
-    const maxIterations = 4096;
-    let iterations = 0;
-    while (true) {
-        iterations += 1;
-        if (iterations > maxIterations) {
-            throw new Error(`file_path: walk-up exceeded ${maxIterations} iterations: ${absolute}`);
-        }
-        if (existsSync(current)) {
-            let canonicalExisting;
-            try {
-                canonicalExisting = realpathSync.native(current);
-            }
-            catch (error) {
-                throw new Error(`file_path: canonicalize ${current}: ${error.message}`);
-            }
-            // Reattach tail in original order (we pushed leaf-first).
-            let result = canonicalExisting;
-            for (let i = tail.length - 1; i >= 0; i -= 1) {
-                result = resolve(result, tail[i]);
-            }
-            return result;
-        }
-        const name = basename(current);
-        const parent = dirname(current);
-        if (!name || parent === current) {
-            throw new Error(`file_path: walked to root without finding existing dir: ${absolute}`);
-        }
-        tail.push(name);
-        current = parent;
-    }
-}
-function computeAllowedRoots(options) {
-    const envValue = options.allowedRootsEnv ?? process.env.PUGI_ALLOWED_ROOTS;
-    if (envValue !== undefined) {
-        return envValue
-            .split(':')
-            .filter((s) => s.length > 0)
-            .map(canonicalizeRoot)
-            .filter((s) => s !== null);
-    }
-    // No env override: implicit root is the caller-supplied cwd (defaults
-    // to `process.cwd()`).
-    const cwd = options.root ?? process.cwd();
-    const canon = canonicalizeRoot(cwd);
-    return canon ? [canon] : [];
-}
-function canonicalizeRoot(raw) {
-    if (!raw)
-        return null;
-    let canon;
-    try {
-        canon = realpathSync.native(raw);
-    }
-    catch {
-        canon = resolve(raw);
-    }
-    if (!canon)
-        return null;
-    return canon.endsWith(sep) ? canon : canon + sep;
-}
-function isContainedIn(canonicalChild, rootWithSep) {
-    const rootNoSep = rootWithSep.endsWith(sep)
-        ? rootWithSep.slice(0, -1)
-        : rootWithSep;
-    if (canonicalChild === rootNoSep)
-        return true;
-    return canonicalChild.startsWith(rootWithSep);
-}
-function assertNotDenylisted(canonical, homeDir) {
-    // System paths — match as prefix-with-separator so `/etc-fake/` is
-    // not denied while `/etc/passwd` is.
-    const systemDenyPrefixes = [
-        '/etc/',
-        '/usr/',
-        '/System/',
-        '/Library/Application Support/',
-        '/var/db/',
-        '/var/log/',
-        '/var/root/',
-        '/private/etc/',
-        '/private/usr/',
-        '/private/var/db/',
-        '/private/var/log/',
-        '/private/var/root/',
-        '/root/',
-        '/bin/',
-        '/sbin/',
-    ];
-    for (const prefix of systemDenyPrefixes) {
-        if (canonical.startsWith(prefix)) {
-            throw new Error(`file_path: denied (system dir): ${canonical}`);
-        }
-    }
-    if (!homeDir)
-        return;
-    // Credential and substrate directories.
-    const homeDirSecrets = [
-        '.ssh/',
-        '.aws/',
-        '.gnupg/',
-        '.config/gcloud/',
-        '.kube/',
-        '.docker/',
-        '.claude/',
-        '.grok/',
-        '.gemini/',
-        '.copilot/',
-        '.kimi/',
-        '.pugi/credentials/',
-    ];
-    for (const secret of homeDirSecrets) {
-        const full = joinHome(homeDir, secret);
-        if (canonical.startsWith(full)) {
-            throw new Error(`file_path: denied (secret/substrate dir): ${canonical}`);
-        }
-    }
-    // Credential files (exact match).
-    const homeFileSecrets = [
-        '.npmrc',
-        '.cargo/credentials',
-        '.cargo/credentials.toml',
-        '.docker/config.json',
-        '.netrc',
-        '.pgpass',
-    ];
-    for (const secret of homeFileSecrets) {
-        const full = joinHome(homeDir, secret);
-        if (canonical === full) {
-            throw new Error(`file_path: denied (credential file): ${canonical}`);
-        }
-    }
-    // Shell-init files (exact match).
-    const initFiles = [
-        '.zshrc',
-        '.bashrc',
-        '.profile',
-        '.bash_profile',
-        '.zprofile',
-        '.zshenv',
-        '.bash_login',
-        '.bash_logout',
-        '.inputrc',
-        '.gitconfig',
-        '.config/fish/config.fish',
-    ];
-    for (const file of initFiles) {
-        const full = joinHome(homeDir, file);
-        if (canonical === full) {
-            throw new Error(`file_path: denied (shell-init file): ${canonical}`);
-        }
-    }
-}
-function joinHome(homeDir, rest) {
-    const trimmedHome = homeDir.endsWith(sep) ? homeDir.slice(0, -1) : homeDir;
-    return `${trimmedHome}${sep}${rest}`;
-}
-//# sourceMappingURL=path-security.js.map