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

package/dist/core/repl/workspace-context.js

@@ -1,206 +0,0 @@
-/**
- * Workspace context resolver — Sprint wave 4.
- *
- * Reads the operator's cwd and synthesises the workspace bundle the CLI
- * forwards to admin-api on POST /api/pugi/sessions. Pugi's prompt v1.1
- * consumes the bundle so "what repo is this?" / "а изучи репо…" answers
- * from the live cwd instead of bouncing back "репо не привязано" (CEO
- * dogfood).
- *
- * Three fields:
- *
- *  - `workspaceCwd`    — absolute path the CLI was launched from.
- *  - `workspaceSlug`   — a stable short identifier (slugForCwd).
- *  - `workspaceSummary` — first ~200 chars of `.pugi/PUGI.md` if the
- *                         repo has one, else the directory basename.
- *
- * The helper is pure-ish (reads the filesystem but does not mutate it)
- * so the production caller in `runtime/cli.ts` can call it eagerly at
- * REPL launch without touching the network. Tests pass an explicit cwd
- * + `fs` stub so the resolver stays deterministic.
- *
- * Failure mode: any FS error (permission denied, missing PUGI.md,
- * symlink loop) returns the basename fallback. The CLI never bubbles
- * the error to the operator — workspace context is a best-effort hint,
- * not a precondition for opening the session.
- */
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { basename, resolve as resolvePath } from 'node:path';
-import { slugForCwd } from './history.js';
-import { isBareMode } from '../bare-mode/index.js';
-/**
- * Workspace summary shown when the operator launched with `--bare` (or
- * `PUGI_BARE=1`). bare mode disables project auto-discovery
- * across the CLI, so we never read `.pugi/PUGI.md` and never advertise
- * a real workspace label to admin-api. Explicit string so the splash +
- * status bar agree, and so operators triaging "why is Pugi ignoring
- * my repo" see a clear cause.
- */
-export const BARE_MODE_WORKSPACE_LABEL = '(bare mode - auto-discovery disabled)';
-/** Cap on the PUGI.md head we forward. Mirrors the admin-api clamp. */
-const PUGI_MD_HEAD_LIMIT = 200;
-/**
- * Workspace label shown when the cwd has no project markers (no .git,
- * no package.json, no PUGI.md). Per CEO dogfood, the
- * previous behaviour leaked the parent directory basename (e.g.
- * `codeforge-io`) into the splash as if it were a real workspace,
- * confusing Pugi/Pugi about what repo she was looking at. The
- * unbound label is a single explicit string so the splash + status bar
- * read the same warning.
- */
-export const UNBOUND_WORKSPACE_LABEL = '(not bound - run /init OR cd into project)';
-/**
- * Resolve a `ReplWorkspaceContext` from the operator's working directory.
- * Returns a bundle with at least `workspaceCwd` + `workspaceSlug` +
- * `workspaceSummary` populated. The summary is the PUGI.md head when
- * available, else the directory basename.
- */
-export function resolveWorkspaceContext(cwd) {
-    const normalised = resolvePath(cwd);
-    const slug = slugForCwd(normalised);
-    // `--bare` short-circuits BEFORE any PUGI.md
-    // / project-marker reads so the resolver never advertises a real
-    // workspace summary to admin-api. The cwd + slug still travel for
-    // telemetry, but the model + Pugi treat the session as if launched
-    // from a fresh, unbound directory.
-    if (isBareMode()) {
-        return {
-            workspaceCwd: normalised,
-            workspaceSlug: slug,
-            workspaceSummary: BARE_MODE_WORKSPACE_LABEL,
-        };
-    }
-    // wave 5: when the cwd has no project markers, prefer the
-    // explicit "not bound" summary so admin-api's prompt builder knows
-    // not to fabricate a workspace context for Pugi/Pugi. The cwd +
-    // slug still travel so the server can record where the operator
-    // launched from for telemetry, but the summary no longer leaks a
-    // stray parent-dir basename as if it were a real workspace.
-    const summary = isBoundWorkspace(normalised)
-        ? (readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace')
-        : UNBOUND_WORKSPACE_LABEL;
-    return {
-        workspaceCwd: normalised,
-        workspaceSlug: slug,
-        workspaceSummary: summary,
-    };
-}
-/**
- * Project-marker probe used by the REPL splash + status bar to decide
- * whether the cwd is a real workspace or a stray parent dir the
- * operator wandered into. The probe is intentionally cheap — three
- * `existsSync` calls — and the order matches the brand convention:
- *
- *  1. `.git`             — any clone of a real repo
- *  2. `package.json`     — JS/TS workspace root
- *  3. `PUGI.md`          — a Pugi-initialised workspace (root or
- *                           `.pugi/PUGI.md`)
- *
- * Hitting any one of these counts the cwd as "bound" — the operator
- * intentionally landed in a project. Hitting none means they ran
- * `pugi` from `$HOME` or from the parent of a checkout; in that case
- * the splash surfaces an explicit "not bound" label instead of leaking
- * the parent-dir basename as if it were a workspace. The check
- * mirrors the the upstream tool "no CLAUDE.md → silent context" rule —
- * never fake-bind.
- */
-export function isBoundWorkspace(cwd) {
-    const normalised = resolvePath(cwd);
-    // Case-sensitive checks; the resolver lower-cases PUGI.md when it
-    // reads the head, but the existence probe stays strict so a stray
-    // `pugi.md` does not accidentally pass without `pugi init` having
-    // run.
-    if (existsSync(resolvePath(normalised, '.git')))
-        return true;
-    if (existsSync(resolvePath(normalised, 'package.json')))
-        return true;
-    if (existsSync(resolvePath(normalised, 'PUGI.md')))
-        return true;
-    if (existsSync(resolvePath(normalised, '.pugi', 'PUGI.md')))
-        return true;
-    return false;
-}
-/**
- * Resolve the workspace label shown on the splash + the REPL header.
- * When the cwd has project markers, returns the directory basename;
- * otherwise returns the explicit "not bound" warning so the operator
- * understands no real workspace was detected. The label is the only
- * string the splash and status bar agree on, so we centralise the
- * decision here instead of re-deriving in two places.
- *
- */
-export function resolveWorkspaceLabel(cwd) {
-    if (!isBoundWorkspace(cwd))
-        return UNBOUND_WORKSPACE_LABEL;
-    const normalised = resolvePath(cwd);
-    const segment = basename(normalised);
-    if (!segment || segment.length === 0)
-        return 'workspace';
-    return segment;
-}
-/**
- * Read the first ~200 chars of `.pugi/PUGI.md` if the file exists. The
- * project's own description is the highest-signal one-line summary we
- * can hand to Pugi — `pugi init` writes it on workspace creation, and
- * the operator may have edited it since.
- *
- * Returns null on any FS error so the caller falls back to the
- * basename. We never throw — workspace context is best-effort.
- */
-function readPugiSummary(cwd) {
-    const candidate = resolvePath(cwd, '.pugi', 'PUGI.md');
-    try {
-        if (!existsSync(candidate))
-            return null;
-        const st = statSync(candidate);
-        if (!st.isFile())
-            return null;
-        // Cap the read at 2 KB — even a malformed PUGI.md will not be
-        // bigger than that's worth on a one-line summary, and capping
-        // bounds the slice cost on a giant file.
-        const raw = readFileSync(candidate, 'utf8').slice(0, 2048);
-        return summariseMarkdown(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Reduce a PUGI.md head to one short summary line: strip the front-
- * matter and the leading H1 marker, take the first non-empty line,
- * cap at PUGI_MD_HEAD_LIMIT. Whitespace collapses to single spaces so
- * the summary survives the admin-api clamp without weird wrap.
- */
-export function summariseMarkdown(raw) {
-    if (!raw || raw.trim().length === 0)
-        return null;
-    const body = stripFrontmatter(raw);
-    const lines = body.split(/\r?\n/);
-    for (const line of lines) {
-        // Strip leading `#` markers + trim whitespace. A heading like
-        // "# My Project" becomes "My Project".
-        const stripped = line.replace(/^#+\s*/, '').trim();
-        if (stripped.length === 0)
-            continue;
-        const oneLine = stripped.replace(/\s+/g, ' ');
-        return oneLine.length > PUGI_MD_HEAD_LIMIT
-            ? oneLine.slice(0, PUGI_MD_HEAD_LIMIT)
-            : oneLine;
-    }
-    return null;
-}
-/**
- * Drop a YAML front-matter block (`---\n…\n---`) from the head of a
- * Markdown file. Pugi does not need to see the metadata; the prose body
- * carries the project description.
- */
-function stripFrontmatter(raw) {
-    if (!raw.startsWith('---'))
-        return raw;
-    const end = raw.indexOf('\n---', 3);
-    if (end === -1)
-        return raw;
-    const afterFrontmatter = raw.slice(end + 4);
-    return afterFrontmatter.replace(/^\r?\n/, '');
-}
-//# sourceMappingURL=workspace-context.js.map

package/dist/core/repo-map/build.js

@@ -1,125 +0,0 @@
-/**
- * Repo-map build orchestrator — .
- *
- * Single entry point that the CLI command + the engine boot path both
- * call. Wires the scanner → extractor → cache → formatter pipeline
- * together and surfaces a structured result the caller can render or
- * inject without knowing the inner module shapes.
- *
- * The orchestrator is split out от cache.ts and the command handler
- * so:
- *
- *  1. The CLI command + the engine system-prompt injector share one
- *     code path. Drift between the two would silently change what
- *     the model sees vs. what the operator sees.
- *
- *  2. The spec can exercise the full pipeline against a temp dir
- *     without mounting Ink or the engine.
- *
- * Pure-ish: reads from disk (the source files + the cache), but never
- * mutates anything outside `.pugi/repo-map.json` and never logs. The
- * caller decides whether к persist the cache (`writeCache: true`) or
- * к compute the map в-memory (`writeCache: false` — useful for
- * non-interactive `--json` invocations on read-only fs).
- */
-import { readFileSync } from 'node:fs';
-import { loadPugiIgnore } from '../context/pugiignore.js';
-import { defaultCachePath, diffCacheAgainstScan, mergeCache, readRepoMapCache, writeRepoMapCache, } from './cache.js';
-import { extractFromFile } from './extractor.js';
-import { scanRepoForMap } from './scanner.js';
-import { formatRepoMap } from './formatter.js';
-/**
- * Run the full pipeline. Returns a structured verdict; never throws.
- * The 'too-large' branch fires when the workspace exceeds the file
- * cap — callers surface a hint к the operator ("repo too large for
- * inline map — try .pugiignore") and skip injection.
- */
-export function buildRepoMap(options) {
-    const root = options.root;
-    const refresh = options.refresh === true;
-    const writeCache = options.writeCache !== false;
-    const cachePath = options.cachePath ?? defaultCachePath(root);
-    const readFile = options.readFile ?? ((path) => readFileSync(path, 'utf8'));
-    const ignore = loadPugiIgnore(root);
-    const scan = scanRepoForMap({ root, ignore });
-    if (!scan.ok) {
-        return {
-            ok: false,
-            root,
-            reason: scan.skipped.reason,
-            walked: scan.skipped.walked,
-        };
-    }
-    const prior = refresh ? null : readCacheOrNull(cachePath);
-    const diff = diffCacheAgainstScan(prior, scan.files);
-    const freshExtracts = new Map();
-    for (const file of diff.toRebuild) {
-        let source;
-        try {
-            source = readFile(file.absPath);
-        }
-        catch {
-            // File vanished или became unreadable mid-build — skip. The
-            // cache layer will just not have an entry for it; next refresh
-            // picks it up if it reappears.
-            continue;
-        }
-        freshExtracts.set(file.relPath, extractFromFile(file, source));
-    }
-    const cache = mergeCache({
-        root,
-        prior,
-        scanned: scan.files,
-        freshExtracts,
-    });
-    let cacheWritten = false;
-    if (writeCache) {
-        const writeResult = writeRepoMapCache(cachePath, cache);
-        cacheWritten = writeResult.ok;
-    }
-    // Surface the extracts в the same order the scanner produced (sorted
-    // by POSIX path) so callers iterating the result render deterministic
-    // output. The formatter does its own priority sort, so a different
-    // order here would only affect callers that iterate manually.
-    const extracts = [];
-    for (const file of scan.files) {
-        const entry = cache.entries[file.relPath];
-        if (entry)
-            extracts.push(entry.extract);
-    }
-    return {
-        ok: true,
-        root,
-        cache,
-        extracts,
-        scanStats: scan.stats,
-        diffStats: {
-            rebuilt: diff.toRebuild.length,
-            reused: diff.reuse.length,
-            dropped: diff.toDrop.length,
-        },
-        cachePath,
-        cacheWritten,
-    };
-}
-/**
- * Convenience wrapper: build + format в one call. The engine boot
- * path uses this so it does not have к know the formatter shape.
- */
-export function buildAndFormatRepoMap(options) {
-    const build = buildRepoMap(options);
-    if (!build.ok)
-        return { build };
-    const format = formatRepoMap(build.extracts, {
-        maxBytes: options.formatBytesCap,
-        omitHeader: options.omitHeader,
-    });
-    return { build, format };
-}
-function readCacheOrNull(path) {
-    const verdict = readRepoMapCache(path);
-    if (verdict.ok)
-        return verdict.cache;
-    return null;
-}
-//# sourceMappingURL=build.js.map

package/dist/core/repo-map/cache.js

@@ -1,185 +0,0 @@
-/**
- * Repo-map cache — .
- *
- * Persists the result of the scan + extract passes к
- * `.pugi/repo-map.json` so subsequent boots reuse the symbol table
- * without re-walking the workspace. The cache key is `(mtimeMs, size)`
- * per file, matching the heuristic used by Node's own native
- * `node:fs.statSync` cache and Git's index format. A file whose mtime
- * AND size match the cached entry is presumed unchanged; otherwise the
- * extractor re-runs against the fresh contents.
- *
- * Why not a content hash:
- *
- *  The file-cache module already hashes by content for the
- *  working-set heuristic, and the L28 use case is different — repo-
- *  map invalidation is "should we re-parse" not "is this content
- *  identical to the last cached version". A content-hash sweep would
- *  re-read every source file on every boot, defeating the purpose of
- *  a cache. mtime + size matches the cost profile (one stat call per
- *  file, no read) while catching every realistic edit pattern
- *  (editors universally update mtime; even `truncate` updates size).
- *
- * Why JSON not SQLite:
- *
- *  The index-store ships as a flat JSON blob and parses в <50 ms
- *  for typical repos (~2000 files); we match the format так the
- *  doctor probe + cabinet sync tools can read repo-map.json without
- *  spinning up a SQLite driver. The blob is gzip-friendly if a future
- *  sprint wants к ship it across the wire.
- *
- * Schema versioning: every cache entry carries `schemaVersion`. When
- * the extractor surface changes (new symbol kinds, new summary
- * format), bump the constant and existing caches are dropped on the
- * next boot — same pattern as the migration runner.
- *
- * Pure-ish surface: reads / writes use `node:fs` sync, no logging.
- * Errors are converted к structured results so the caller can decide
- * whether к surface them or fall back к a cold rebuild.
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-/**
- * Cache format version. Bump when:
- *  - `RepoMapSymbol` adds / renames a field
- *  - `RepoMapFileExtract` adds / renames a field
- *  - The mtime + size invalidation contract changes
- *
- * Old caches with a mismatched version are dropped on read.
- */
-export const REPO_MAP_CACHE_VERSION = 1;
-/**
- * Default location for the workspace cache file. Mirrors the rest of
- * the `.pugi/` convention: `<workspace>/.pugi/repo-map.json`.
- */
-export function defaultCachePath(workspaceRoot) {
-    return join(workspaceRoot, '.pugi', 'repo-map.json');
-}
-/**
- * Read the cache file from disk. Returns a structured verdict; never
- * throws. The 'missing' branch is the cold-boot happy path. The
- * 'parse-error' branch signals corruption — the caller drops the
- * cache and rebuilds. The 'version-mismatch' branch fires after an
- * extractor schema bump.
- */
-export function readRepoMapCache(path) {
-    if (!existsSync(path)) {
-        return { ok: false, reason: 'missing' };
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, 'utf8');
-    }
-    catch {
-        return { ok: false, reason: 'parse-error' };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return { ok: false, reason: 'parse-error' };
-    }
-    if (!isCacheShape(parsed)) {
-        return { ok: false, reason: 'parse-error' };
-    }
-    if (parsed.schemaVersion !== REPO_MAP_CACHE_VERSION) {
-        return { ok: false, reason: 'version-mismatch' };
-    }
-    return { ok: true, cache: parsed };
-}
-/**
- * Write the cache atomically (write-then-rename) so a concurrent
- * reader never sees a half-flushed JSON blob. Errors are surfaced as
- * a structured boolean so the caller can decide whether к escalate —
- * the engine boot path silently swallows write failures because
- * repo-map is a best-effort enrichment.
- */
-export function writeRepoMapCache(path, cache) {
-    try {
-        const dir = dirname(path);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        const body = JSON.stringify(cache, null, 2) + '\n';
-        const tmp = path + '.tmp';
-        writeFileSync(tmp, body, { encoding: 'utf8' });
-        // Atomic rename. `fs.renameSync` is atomic on POSIX + on NTFS when
-        // src + dst live on the same volume, which is always true for
-        // `.pugi/`-local writes.
-        renameSync(tmp, path);
-        return { ok: true };
-    }
-    catch (error) {
-        return {
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-        };
-    }
-}
-export function diffCacheAgainstScan(prior, scanned) {
-    const toRebuild = [];
-    const reuse = [];
-    const seen = new Set();
-    for (const file of scanned) {
-        seen.add(file.relPath);
-        const entry = prior?.entries[file.relPath];
-        if (!entry
-            || entry.mtimeMs !== file.mtimeMs
-            || entry.sizeBytes !== file.sizeBytes) {
-            toRebuild.push(file);
-        }
-        else {
-            reuse.push(file.relPath);
-        }
-    }
-    const toDrop = [];
-    if (prior) {
-        for (const key of Object.keys(prior.entries)) {
-            if (!seen.has(key))
-                toDrop.push(key);
-        }
-    }
-    return { toRebuild, toDrop, reuse };
-}
-/**
- * Stitch a fresh cache object together from the prior surviving
- * entries + the newly-extracted ones. Pure helper — the caller is
- * responsible for actually writing the result.
- */
-export function mergeCache(args) {
-    const { root, prior, scanned, freshExtracts } = args;
-    const entries = {};
-    for (const file of scanned) {
-        const fresh = freshExtracts.get(file.relPath);
-        if (fresh) {
-            entries[file.relPath] = {
-                mtimeMs: file.mtimeMs,
-                sizeBytes: file.sizeBytes,
-                extract: fresh,
-            };
-            continue;
-        }
-        const priorEntry = prior?.entries[file.relPath];
-        if (priorEntry) {
-            entries[file.relPath] = priorEntry;
-        }
-    }
-    return {
-        schemaVersion: REPO_MAP_CACHE_VERSION,
-        root,
-        builtAtMs: args.nowMs ?? Date.now(),
-        entries,
-    };
-}
-function isCacheShape(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const v = value;
-    return (typeof v.schemaVersion === 'number'
-        && typeof v.root === 'string'
-        && typeof v.builtAtMs === 'number'
-        && typeof v.entries === 'object'
-        && v.entries !== null);
-}
-//# sourceMappingURL=cache.js.map