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

package/dist/core/context/markdown-traverse.js

@@ -1,255 +0,0 @@
-/**
- * Per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md traverse-up
- * loader — β5a R4+P5.
- *
- * the upstream tool, peer CLI, and Gemini CLI all support a "walk up from
- * cwd to the workspace root, pick up agent-context markdown at every
- * level" pattern. Without this, a `pugi explain` invoked from
- * `apps/admin-api/` cannot see project-local conventions encoded in
- * `apps/admin-api/PUGI.md` (or the cross-CLI shim files) — the
- * existing `loadMarkdownContext` only reads files at `workspaceRoot`.
- *
- * The β5a quality gate (≥80% win-rate vs the upstream tool per CEO)
- * surfaces this gap repeatedly: monorepo-local conventions (NestJS
- * controller style, Prisma migration name format, cabinet brand voice
- * gates) live in per-app context files, and Pugi was blind to them
- * pre-β5a.
- *
- * Contract:
- *
- *  - Walk from `cwd` upward until we reach `workspaceRoot` OR cross
- *    the filesystem boundary. The workspace root file itself is
- *    loaded by the legacy `loadMarkdownContext` so we do NOT include
- *    it here (no double-load, no double-budget-charge).
- *
- *  - At each intermediate directory, look for the four canonical
- *    filenames: `PUGI.md` (native), `AGENTS.md` (cross-CLI shim),
- *    `CLAUDE.md` (the upstream tool compat), `GEMINI.md` (Gemini CLI compat).
- *
- *  - HTML comments stripped, identical to the legacy loader.
- *
- *  - `@import` expansion is intentionally NOT performed here — the
- *    per-dir surface is "drop a small file with the local
- *    conventions"; deep @import chains belong at workspace root.
- *    Keeping this surface flat means the per-dir budget cannot be
- *    blown out by a runaway @import in an unrelated subtree.
- *
- *  - Aggregate budget: `MAX_TRAVERSE_BYTES` across ALL files found
- *    in the walk. When exhausted, remaining files are skipped with
- *    a `budget_exhausted` warning. Default 32 KB — half the
- *    workspace-root budget, because per-dir files are meant to be
- *    terse delta conventions, not full project briefs.
- *
- *  - The walk is bounded: `MAX_TRAVERSE_DEPTH` levels above
- *    workspaceRoot are NEVER traversed (defense against being
- *    invoked from a malicious cwd outside the workspace; in
- *    practice cwd is always inside workspaceRoot but the symlink
- *    case demands belt + suspenders).
- *
- *  - Order returned: shallowest-first (workspace root would be
- *    first if included, then each level closer to cwd). Closest-
- *    to-cwd files are the most specific and the context builder
- *    emits them LAST so the model treats them as the highest-
- *    priority conventions.
- *
- * This module is pure: no logging, no network, no fs writes. Filesystem
- * reads only.
- */
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
-import { stripHtmlComments } from './markdown-loader.js';
-/**
- * Per-traverse total byte cap. Half the workspace-root budget — these
- * files are meant to be terse "in this subdir, do X". 32 KB still fits
- * ~8000 words of guidance.
- */
-export const MAX_TRAVERSE_BYTES = 32 * 1024;
-/**
- * Per-file byte cap. A single per-dir file should never dominate; the
- * 8 KB cap keeps any one level honest. Files larger than this are
- * loaded up to the cap and flagged truncated.
- */
-export const MAX_TRAVERSE_PER_FILE_BYTES = 8 * 1024;
-/**
- * Maximum number of parent directories above workspaceRoot we will
- * traverse. Zero in normal operation — cwd is always inside the
- * workspace; the cap exists so a misconfigured invocation never
- * walks the whole filesystem looking for AGENTS.md.
- */
-export const MAX_TRAVERSE_DEPTH = 0;
-/**
- * Filenames we look for at every level of the walk. The order here
- * also defines the per-directory load order: PUGI.md first (highest
- * trust), then cross-CLI compat shims. When the same directory has
- * multiple files (e.g. both PUGI.md AND CLAUDE.md), all are loaded
- * — operators sometimes keep both during a tool migration.
- */
-export const TRAVERSE_SOURCES = ['PUGI.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
-/**
- * Walk from `opts.cwd` upward toward `opts.workspaceRoot`, loading
- * every PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md we encounter at
- * intermediate levels. The workspace root itself is NOT loaded here
- * — `loadMarkdownContext(workspaceRoot)` owns that file.
- *
- * Returned `loaded` is sorted shallowest-first (closest-to-root) so
- * the caller can emit per-dir context in increasing specificity.
- *
- * Safety properties (proven by spec):
- *
- *  - Never reads outside the workspace tree (symlinks resolved via
- *    realpathSync; off-tree symlinks rejected as
- *    `import_escapes_workspace`).
- *  - Never reads more than `MAX_TRAVERSE_BYTES` total or more than
- *    `MAX_TRAVERSE_PER_FILE_BYTES` per file.
- *  - Never walks above the workspace root.
- *  - Never visits the workspace root itself (single source of truth
- *    for workspace-level docs stays with `loadMarkdownContext`).
- */
-export async function loadTraversedMarkdown(opts) {
-    const warnings = [];
-    const loaded = [];
-    let budgetRemaining = MAX_TRAVERSE_BYTES;
-    let absRoot;
-    let absCwd;
-    try {
-        absRoot = realpathSync(resolve(opts.workspaceRoot));
-        absCwd = realpathSync(resolve(opts.cwd));
-    }
-    catch (error) {
-        warnings.push({
-            kind: 'read_error',
-            message: `realpath failed for traverse anchor: ${error.message}`,
-        });
-        return { loaded, warnings, totalBytes: 0 };
-    }
-    // Containment guard: if cwd is not inside workspaceRoot, refuse
-    // to walk. Returning a clean empty result keeps the engine happy
-    // and surfaces nothing about the off-tree cwd to the model.
-    const relCwd = relative(absRoot, absCwd);
-    if (relCwd.startsWith('..') || isAbsolute(relCwd)) {
-        warnings.push({
-            kind: 'import_escapes_workspace',
-            message: `cwd is outside workspaceRoot; per-dir traverse skipped (cwd=${absCwd}, root=${absRoot})`,
-            path: absCwd,
-        });
-        return { loaded, warnings, totalBytes: 0 };
-    }
-    // Collect the walk: every directory from cwd UP TO (but not
-    // including) workspaceRoot.
-    const dirsToVisit = [];
-    let current = absCwd;
-    while (current !== absRoot) {
-        dirsToVisit.push(current);
-        const parent = dirname(current);
-        if (parent === current)
-            break; // hit filesystem root before workspaceRoot — defensive
-        current = parent;
-        if (dirsToVisit.length > 64)
-            break; // pathological depth, refuse
-    }
-    // Walk shallowest-first so we charge the budget in the order
-    // that matches what we return.
-    dirsToVisit.reverse();
-    for (const dir of dirsToVisit) {
-        if (budgetRemaining <= 0) {
-            warnings.push({
-                kind: 'budget_exhausted',
-                message: `per-dir traverse budget exhausted before reaching ${dir}`,
-                path: dir,
-            });
-            break;
-        }
-        for (const source of TRAVERSE_SOURCES) {
-            const candidate = resolve(dir, source);
-            if (!existsSync(candidate))
-                continue;
-            // Symlink guard: same realpath check as the workspace-root
-            // loader. A symlink inside the workspace that points outside
-            // the workspace must NOT be inlined.
-            let realCandidate;
-            try {
-                realCandidate = realpathSync(candidate);
-            }
-            catch (error) {
-                warnings.push({
-                    kind: 'read_error',
-                    message: `realpath failed for ${candidate}: ${error.message}`,
-                    path: candidate,
-                });
-                continue;
-            }
-            const realRel = relative(absRoot, realCandidate);
-            if (realRel.startsWith('..') || isAbsolute(realRel)) {
-                warnings.push({
-                    kind: 'import_escapes_workspace',
-                    message: `traverse file escapes workspace via symlink: ${candidate} -> ${realCandidate}`,
-                    path: candidate,
-                });
-                continue;
-            }
-            let raw;
-            let rawBytes;
-            try {
-                rawBytes = statSync(candidate).size;
-                raw = readFileSync(candidate, 'utf8');
-            }
-            catch (error) {
-                warnings.push({
-                    kind: 'read_error',
-                    message: `could not read ${candidate}: ${error.message}`,
-                    path: candidate,
-                });
-                continue;
-            }
-            const stripped = stripHtmlComments(raw);
-            // Per-file cap first, then global budget.
-            const perFileCap = Math.min(MAX_TRAVERSE_PER_FILE_BYTES, budgetRemaining);
-            let content = stripped;
-            let truncated = false;
-            let contentBytes = Buffer.byteLength(content, 'utf8');
-            if (contentBytes > perFileCap) {
-                // Codepoint-safe slice: convert byte cap to char cap by
-                // taking min(byte cap, char-length-up-to-cap). We accept
-                // mild over-trim for safety.
-                content = content.slice(0, perFileCap);
-                truncated = true;
-                contentBytes = Buffer.byteLength(content, 'utf8');
-            }
-            const distance = distanceSegments(absCwd, dir);
-            loaded.push({
-                source,
-                resolvedPath: candidate,
-                dir,
-                distanceFromCwd: distance,
-                rawBytes,
-                loadedBytes: contentBytes,
-                truncated,
-                content,
-            });
-            budgetRemaining -= contentBytes;
-            if (budgetRemaining <= 0)
-                break;
-        }
-    }
-    return {
-        loaded,
-        warnings,
-        totalBytes: MAX_TRAVERSE_BYTES - budgetRemaining,
-    };
-}
-/**
- * How many path segments separate `from` and `to`. Both must be
- * absolute. `to` is assumed to be an ancestor of (or equal to)
- * `from`; if not, returns -1 so callers can ignore the file.
- */
-function distanceSegments(from, to) {
-    if (from === to)
-        return 0;
-    const rel = relative(to, from);
-    if (rel.startsWith('..') || isAbsolute(rel))
-        return -1;
-    if (rel.length === 0)
-        return 0;
-    return rel.split(sep).length;
-}
-//# sourceMappingURL=markdown-traverse.js.map

package/dist/core/context/pugiignore.js

@@ -1,316 +0,0 @@
-/**
- * `.pugiignore` parser - Phase 1 (three-tier context).
- *
- * The CLI walks the workspace to build a repo skeleton and to feed the
- * chokidar watcher. Both passes need a single source of truth for which
- * paths are off-limits. `.pugiignore` extends (not replaces) `.gitignore`
- * with Pugi-specific defaults: secret files, large binaries, build
- * outputs, lockfiles.
- *
- * Design choices:
- *
- *  1. We layer four sources, last-write-wins per the .gitignore spec:
- *     (a) Built-in DEFAULT_IGNORE_PATTERNS - secret / binary / build
- *         paths every workspace should drop.
- *     (b) `~/.pugi/global.pugiignore` - operator-global overrides.
- *     (c) Repo `.gitignore` (when present) - so we don't re-walk
- *         node_modules / dist / etc.
- *     (d) Repo `.pugiignore` - workspace-local extensions.
- *
- *  2. The `ignore` npm package handles negation (`!path`) and nested
- *     directories correctly. Rolling a minimal glob matcher is doable
- *     but the test surface for gitignore semantics (esp. negation +
- *     ancestor matching) is wide enough that pulling the audited
- *     library is the safer call. It is already in the workspace via
- *     transitive deps; we add it as an explicit pugi-cli dep.
- *
- *  3. Privacy is defense-in-depth: even if the operator deletes the
- *     built-in defaults from their `.pugiignore`, we re-add the
- *     secret patterns at the END of the chain so a typo in user
- *     config cannot expose `.env` / `*.pem` / `*.key`. The user can
- *     explicitly negate (`!.env.example`) but cannot wipe the
- *     defense.
- *
- *  4. Paths are normalised to forward slashes (the `ignore` package
- *     requires POSIX-style separators even on Windows) and stripped
- *     of any leading workspace root so `isIgnored` answers in
- *     repo-relative terms.
- *
- * The API surface is minimal: `loadPugiIgnore(cwd)` returns a
- * `PugiIgnore` matcher with `isIgnored(absPath): boolean`. The matcher
- * is built once at session bootstrap and reused by the skeleton walker
- * and the chokidar watcher.
- */
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { relative, resolve, sep } from 'node:path';
-// The `ignore` package ships as CommonJS with `module.exports = factory`
-// plus a `.d.ts` that re-exports the factory as default. Under
-// `module: nodenext` TypeScript treats CJS default imports as the
-// `module.exports` shape, which for `ignore` IS the callable factory -
-// but only when we use the namespace-default dance below. A bare
-// `import ignore from 'ignore'` fails with "expression is not callable"
-// because TS resolves the import to the `typeof` shape rather than the
-// callable value.
-import * as ignoreModule from 'ignore';
-const ignoreFactory = ignoreModule.default
-    ?? ignoreModule;
-/**
- * Built-in patterns shipped with every Pugi workspace. The list is a
- * conservative union of three categories:
- *
- *  - **Secrets** (defense in depth): `.env*`, `*.pem`, `*.key`,
- *    `secrets/**`, `.netrc`, `id_rsa*`, `*.secret`, `credentials*`.
- *    These are re-applied at the END of the chain so user config
- *    cannot accidentally expose them.
- *
- *  - **Build outputs / caches**: `node_modules/`, `dist/`, `build/`,
- *    `.next/`, `.nuxt/`, `.svelte-kit/`, `coverage/`, `.nx/`, `.cache/`,
- *    `.turbo/`, `.parcel-cache/`, `out/`, `.output/`, `*.tsbuildinfo`.
- *
- *  - **Large binaries / data**: lockfiles (`*.lock`, `*-lock.json`,
- *    `*-lock.yaml`), images (`*.png`, `*.jpg`, `*.jpeg`, `*.gif`,
- *    `*.ico`), PDFs, videos, archives (`*.zip`, `*.tar`, `*.gz`),
- *    DB dumps (`*.sql`, `*.dump`), logs.
- *
- * The split between baseline patterns (applied first) and secret
- * patterns (applied last) matters: a user `.pugiignore` can `!`-negate
- * baseline entries (e.g. unignore a particular generated file under
- * `dist/`) but cannot reach the trailing secret block. The trailing
- * block is exported as `SECRET_IGNORE_PATTERNS` for tests.
- */
-export const BASELINE_IGNORE_PATTERNS = Object.freeze([
-    // VCS / Pugi state
-    '.git/',
-    '.pugi/',
-    '.hg/',
-    '.svn/',
-    // Build outputs / package manager caches
-    'node_modules/',
-    '.pnpm-store/',
-    'dist/',
-    'build/',
-    'out/',
-    '.output/',
-    '.next/',
-    '.nuxt/',
-    '.svelte-kit/',
-    '.astro/',
-    'coverage/',
-    '.nyc_output/',
-    '.nx/',
-    '.turbo/',
-    '.parcel-cache/',
-    '.cache/',
-    '.vercel/',
-    '.netlify/',
-    '*.tsbuildinfo',
-    // Lockfiles - rebuilds, never agent-relevant
-    '*.lock',
-    'package-lock.json',
-    'yarn.lock',
-    'pnpm-lock.yaml',
-    'bun.lockb',
-    'composer.lock',
-    'poetry.lock',
-    'Cargo.lock',
-    'Gemfile.lock',
-    // Logs
-    '*.log',
-    'logs/',
-    '.pm2/',
-    // Large binaries
-    '*.png',
-    '*.jpg',
-    '*.jpeg',
-    '*.gif',
-    '*.ico',
-    '*.webp',
-    '*.bmp',
-    '*.tiff',
-    '*.svg',
-    '*.pdf',
-    '*.mp3',
-    '*.mp4',
-    '*.mov',
-    '*.webm',
-    '*.zip',
-    '*.tar',
-    '*.tar.gz',
-    '*.tgz',
-    '*.gz',
-    '*.bz2',
-    '*.7z',
-    '*.rar',
-    '*.dmg',
-    '*.iso',
-    // DB dumps / fixtures
-    '*.sql',
-    '*.dump',
-    '*.sqlite',
-    '*.sqlite3',
-    '*.db',
-    // OS noise
-    '.DS_Store',
-    'Thumbs.db',
-]);
-/**
- * Secret patterns re-applied at the END of every layered chain. Even
- * if the operator deletes these from `.pugiignore` (or accidentally
- * negates them with `!.env`), the trailing block restores the gate.
- * This is defense-in-depth: the skeleton walker MUST NOT read
- * credentials into the agent context, period.
- */
-export const SECRET_IGNORE_PATTERNS = Object.freeze([
-    '.env',
-    '.env.*',
-    '*.pem',
-    '*.key',
-    '*.crt',
-    '*.cert',
-    // X.509 cert formats - `*.cer` is the PEM-style cert extension common
-    // on Windows / Java keystores, `*.der` is the binary DER-encoded form
-    // used by Java + .NET tooling. Both can carry private keys when
-    // bundled (PKCS#7 / PKCS#12) and the file extension alone does not
-    // tell us whether the bundle includes a key. Treat as secrets by
-    // default. triple-review P1 (PR).
-    '*.cer',
-    '*.der',
-    '*.p12',
-    '*.pfx',
-    '*.jks',
-    '*.keystore',
-    'secrets/**',
-    '.netrc',
-    'id_rsa',
-    'id_rsa.*',
-    'id_ed25519',
-    'id_ed25519.*',
-    '*.secret',
-    'credentials',
-    'credentials.json',
-    'service-account*.json',
-    '*.kdbx',
-    '.aws/',
-    '.ssh/',
-    '.gnupg/',
-]);
-/**
- * Where the operator's global ignore file lives. Mirrors the
- * `~/.gitignore_global` convention. We do NOT auto-create it; if it
- * exists, we load its non-empty / non-comment lines.
- */
-export function globalPugiIgnorePath(home = homedir()) {
-    return resolve(home, '.pugi', 'global.pugiignore');
-}
-/** Path to the workspace `.pugiignore`. */
-export function workspacePugiIgnorePath(cwd) {
-    return resolve(cwd, '.pugiignore');
-}
-/** Path to the workspace `.gitignore`. */
-export function workspaceGitIgnorePath(cwd) {
-    return resolve(cwd, '.gitignore');
-}
-/**
- * Load and compile the layered ignore matcher for `cwd`. The chain
- * is built in this exact order so later layers override earlier ones,
- * with the trailing secret block as the inviolable backstop:
- *
- *  1. BASELINE_IGNORE_PATTERNS (built-in defaults)
- *  2. ~/.pugi/global.pugiignore (operator global, optional)
- *  3. <cwd>/.gitignore         (workspace, optional)
- *  4. <cwd>/.pugiignore        (workspace, optional)
- *  5. SECRET_IGNORE_PATTERNS   (defense-in-depth backstop)
- *
- * Any FS error reading optional files is swallowed - workspace
- * context is best-effort and must never block the REPL bootstrap.
- */
-export function loadPugiIgnore(cwd, options = {}) {
-    const home = options.home ?? homedir();
-    const normalisedCwd = resolve(cwd);
-    const patterns = [];
-    patterns.push(...BASELINE_IGNORE_PATTERNS);
-    const globalPath = globalPugiIgnorePath(home);
-    const globalPatterns = readPatternFile(globalPath);
-    patterns.push(...globalPatterns);
-    const gitignorePath = workspaceGitIgnorePath(normalisedCwd);
-    const gitPatterns = readPatternFile(gitignorePath);
-    patterns.push(...gitPatterns);
-    const pugiIgnorePath = workspacePugiIgnorePath(normalisedCwd);
-    const pugiPatterns = readPatternFile(pugiIgnorePath);
-    patterns.push(...pugiPatterns);
-    // Secrets last so they cannot be silently negated by user config.
-    patterns.push(...SECRET_IGNORE_PATTERNS);
-    const matcher = ignoreFactory().add(patterns);
-    return {
-        cwd: normalisedCwd,
-        patterns: Object.freeze(patterns.slice()),
-        isIgnored(absPath, isDir) {
-            return isIgnoredImpl(matcher, normalisedCwd, absPath, isDir === true);
-        },
-    };
-}
-/**
- * Read a `.gitignore`-shaped file and return the non-comment / non-empty
- * lines. Returns `[]` on any FS error. Lines are returned verbatim - the
- * `ignore` library parses leading `!`, trailing `/`, and `**` correctly
- * on its own.
- */
-export function readPatternFile(path) {
-    try {
-        if (!existsSync(path))
-            return [];
-        const raw = readFileSync(path, 'utf8');
-        return parsePatternText(raw);
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Pure parser for a `.gitignore`-shaped string. Splits on newlines,
- * strips comment lines (`#`), trims whitespace, drops empty lines.
- * Exported for the test suite so the chain is exercisable without a
- * real filesystem.
- */
-export function parsePatternText(raw) {
-    const lines = raw.split(/\r?\n/);
-    const out = [];
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed.length === 0)
-            continue;
-        if (trimmed.startsWith('#'))
-            continue;
-        out.push(trimmed);
-    }
-    return out;
-}
-/**
- * Normalise an absolute path to a repo-relative POSIX path, then run
- * it through the `ignore` matcher. Inputs outside the workspace return
- * `false` - the matcher has no opinion about paths above its root.
- */
-function isIgnoredImpl(matcher, cwd, absPath, isDir) {
-    const normalisedAbs = resolve(absPath);
-    if (normalisedAbs === cwd)
-        return false;
-    const rel = relative(cwd, normalisedAbs);
-    // Paths above the workspace root come back as `..` or `../foo`.
-    // The matcher has no opinion about those; treat as not-ignored.
-    if (rel.length === 0)
-        return false;
-    if (rel.startsWith('..'))
-        return false;
-    // `ignore` requires POSIX-style separators on every platform.
-    const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
-    // Append a trailing slash for directories so gitignore-style
-    // dir patterns (`node_modules/`, `dist/`) match the dir itself,
-    // not just its children. Without this, `isIgnored('/abs/node_modules', true)`
-    // would return false because `ignore` only matches the child path
-    // shape for those patterns. See the spec for the failing case
-    // (skeleton walker descending into node_modules/).
-    const queryPath = isDir ? `${posixRel}/` : posixRel;
-    return matcher.ignores(queryPath);
-}
-//# sourceMappingURL=pugiignore.js.map