@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/core/repl/tool-route.js

@@ -0,0 +1,382 @@
+/**
+ * PUGI-538b () — `<pugi-tool-route>` envelope parser.
+ *
+ * The admin-api Pugi coordinator persona emits an
+ * `<pugi-tool-route command="code|fix|build" persona="<slug>" brief="…"/>`
+ * envelope on her turn when the operator's brief requires workspace
+ * tool use (write/edit/read a file, run a script, install a package,
+ * build, test). The CLI consumer parses the envelope, strips it from
+ * operator-visible detail, and routes the brief through the local
+ * `NativePugiEngineAdapter` → `runEngineLoop` → `POST /api/pugi/engine`
+ * flow that already drives `pugi code/fix/build` end-to-end with real
+ * tool calls and atomic file writes.
+ *
+ * Without this envelope the REPL chat path is a single-shot text
+ * streamer: customer says "make tic-tac-toe", Pugi responds with a
+ * bash heredoc dump as prose, no file is written.  (PUGI-538a)
+ * lays out the architecture; this parser is the CLI half of the bridge.
+ *
+ * # Grammar (self-closing form is preferred; paired form also accepted)
+ *
+ *   <pugi-tool-route command="code" persona="dev" brief="One sentence…"/>
+ *   <pugi-tool-route command="fix"  persona="dev" brief="…"></pugi-tool-route>
+ *
+ * Attributes:
+ *   - command  (required) — exactly one of `code`, `fix`, `build`.
+ *   - persona  (optional) — Tier-1 persona slug hint; defaults to `dev`
+ *              when omitted. The value `main` is rejected (the REPL
+ *              coordinator IS Pugi already, routing back to herself
+ *              would not change behaviour).
+ *   - brief    (required) — single-sentence operational brief,
+ *              <= 400 chars after entity decoding.
+ *
+ * # Why a hand-rolled parser, not a generic XML library
+ *
+ * Same rationale as `ask.ts`: generic XML libraries (sax,
+ * fast-xml-parser, xmldoc) carry a large attack surface (external
+ * entity expansion, recursive blowup on malformed input, sloppy
+ * attribute handling) and require ~50 KB of runtime dependency. The
+ * persona-side grammar here is one tag with a closed three-attribute
+ * set, so a bounded tokenizer is both safer and smaller. The defences
+ * mirror ask.ts: closed entity allowlist, control-char strip, refusal
+ * on raw `&` outside `&amp;` / `&lt;` / `&gt;` / `&quot;` / `&apos;`,
+ * refusal on nested tags inside attribute blob, hard span cap.
+ *
+ * # Buffering across streaming chunks
+ *
+ * The session calls `extractToolRouteTags(buffer)` on the accumulated
+ * `agent.step.detail` body. If the close tag (or self-close `/>`) has
+ * not arrived yet, the parser returns `{ tags: [], pendingOpenTag: true }`
+ * and the session waits for more chunks. This mirrors the
+ * `extractAskTags` / `extractPlanReviewTags` shape so `session.ts`
+ * routes the three envelope families through one buffer-and-strip
+ * machinery.
+ */
+/* ------------------------------------------------------------------ */
+/* Bounded constants                                                  */
+/* ------------------------------------------------------------------ */
+/** Hard cap on the brief length after entity decoding. */
+export const TOOL_ROUTE_MAX_BRIEF_LEN = 400;
+/** Hard cap on the persona slug length. */
+export const TOOL_ROUTE_MAX_PERSONA_LEN = 32;
+/** Hard cap on the entire tag span. Long enough for full attrs + a
+ * worst-case 400-char brief plus closing form; defends against runaway
+ * payloads. */
+const TAG_MAX_SPAN_BYTES = 4 * 1024;
+/** Tag families exhaustively enumerated for the closed-attribute gate. */
+const ALLOWED_ATTRS = new Set([
+    'command',
+    'persona',
+    'brief',
+]);
+/** Accepted `command` literals — locked to the engine adapter contract. */
+const ALLOWED_COMMANDS = new Set(['code', 'fix', 'build']);
+/** Refused personas. `main` would route Pugi back to herself; the engine
+ * adapter rejects the slug anyway, so we filter at parse time for clarity. */
+const REFUSED_PERSONAS = new Set(['main', 'pugi']);
+/** Default persona slug when the attribute is omitted. Matches the
+ * ENVELOPES_BODY prompt copy ("Defaults to 'dev' when omitted"). */
+const DEFAULT_PERSONA = 'dev';
+/* ------------------------------------------------------------------ */
+/* Public extraction API                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Find every well-formed `<pugi-tool-route>` envelope in `body`.
+ * Malformed envelopes are dropped and surfaced via `hadMalformedTag`
+ * so the session can log a warning. Streaming-incomplete envelopes
+ * (open observed, close/self-close not yet arrived) are withheld from
+ * `cleaned` so the raw envelope cannot leak into the transcript if the
+ * stream pauses mid-tag.
+ */
+export function extractToolRouteTags(body) {
+    const tags = [];
+    const segments = [];
+    let cursor = 0;
+    let pendingOpenTag = false;
+    let hadMalformedTag = false;
+    // Hard cap on tags per buffer so a hostile (or accidental) flood
+    // does not pin the parser. 16 is generous — a real session never
+    // has more than one envelope queued per turn.
+    const MAX_TAGS_PER_BUFFER = 16;
+    // Belt-and-braces safety counter — the body length bounds the
+    // iteration count strictly, but a pathological input could otherwise
+    // loop until the per-buffer cap fires.
+    let safetyIterations = body.length + 16;
+    const OPEN_PREFIX = '<pugi-tool-route';
+    const PAIR_CLOSE = '</pugi-tool-route>';
+    while (cursor < body.length && tags.length < MAX_TAGS_PER_BUFFER) {
+        if (safetyIterations-- <= 0)
+            break;
+        const openIndex = body.indexOf(OPEN_PREFIX, cursor);
+        if (openIndex === -1) {
+            // No more envelopes. Flush the rest of the body as cleaned prose.
+            segments.push(body.slice(cursor));
+            cursor = body.length;
+            break;
+        }
+        // Push everything before the opening tag as cleaned prose.
+        segments.push(body.slice(cursor, openIndex));
+        // Locate the end of the opening tag. The envelope may be self-
+        // closing (`/>`) or paired (`>` then `</pugi-tool-route>`).
+        // Search for the FIRST unquoted `>` after the OPEN_PREFIX position
+        // so a quoted attribute value with an embedded `>` (escaped as
+        // `&gt;` per the grammar; raw `>` is rejected below) cannot
+        // confuse the boundary scan.
+        const openEnd = findUnquotedGt(body, openIndex + OPEN_PREFIX.length);
+        if (openEnd === -1) {
+            // Open seen, no terminator yet. Withhold from `cleaned` so the
+            // raw envelope cannot leak. Same posture as ask.ts.
+            pendingOpenTag = true;
+            cursor = body.length;
+            break;
+        }
+        const selfClosed = body[openEnd - 1] === '/';
+        let tagEnd;
+        if (selfClosed) {
+            tagEnd = openEnd + 1; // include the closing `>`
+        }
+        else {
+            // Paired form — look for `</pugi-tool-route>`.
+            const closeAt = body.indexOf(PAIR_CLOSE, openEnd + 1);
+            if (closeAt === -1) {
+                pendingOpenTag = true;
+                cursor = body.length;
+                break;
+            }
+            tagEnd = closeAt + PAIR_CLOSE.length;
+        }
+        const span = body.slice(openIndex, tagEnd);
+        if (span.length > TAG_MAX_SPAN_BYTES) {
+            hadMalformedTag = true;
+            cursor = tagEnd;
+            continue;
+        }
+        // Reject nested envelopes — the generic "find next close" would
+        // otherwise pair an outer open with an inner close.
+        const innerOpen = span.indexOf(OPEN_PREFIX, OPEN_PREFIX.length);
+        if (innerOpen !== -1) {
+            hadMalformedTag = true;
+            cursor = tagEnd;
+            continue;
+        }
+        // Slice the attribute blob between OPEN_PREFIX and the closing
+        // `>` (excluding the trailing `/` on the self-closed form).
+        const attrBlobEnd = selfClosed ? openEnd - 1 : openEnd;
+        const attrBlob = body.slice(openIndex + OPEN_PREFIX.length, attrBlobEnd);
+        const parsed = parseToolRouteInner(attrBlob, {
+            start: openIndex,
+            end: tagEnd,
+        });
+        if (parsed === null) {
+            hadMalformedTag = true;
+            cursor = tagEnd;
+            continue;
+        }
+        tags.push(parsed);
+        cursor = tagEnd;
+    }
+    return {
+        tags,
+        cleaned: segments.join('').replace(/\s+\n/g, '\n').trimEnd(),
+        pendingOpenTag,
+        hadMalformedTag,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Inner parser                                                       */
+/* ------------------------------------------------------------------ */
+function parseToolRouteInner(attrBlob, span) {
+    // Reject CDATA, comments, processing instructions, DOCTYPE inside
+    // the attribute blob — none of those appear in the legal grammar.
+    if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(attrBlob))
+        return null;
+    // Reject raw `&` not in a known entity (decoded entities are allowed
+    // via decodeEntities below).
+    if (containsRawAmpersand(attrBlob))
+        return null;
+    // Reject raw `<` / `>` inside the attribute blob — they should always
+    // be escaped as `&lt;` / `&gt;`. The presence of a raw bracket is a
+    // sign of either accidental sloppy output or an injection attempt.
+    if (/[<>]/.test(attrBlob))
+        return null;
+    const attrs = parseAttrBlob(attrBlob);
+    if (attrs === null)
+        return null;
+    // Closed-attribute gate — refuse anything outside the allowlist.
+    for (const key of Object.keys(attrs)) {
+        if (!ALLOWED_ATTRS.has(key))
+            return null;
+    }
+    const command = attrs['command'];
+    if (typeof command !== 'string' || command.length === 0)
+        return null;
+    if (!ALLOWED_COMMANDS.has(command))
+        return null;
+    const briefRaw = attrs['brief'];
+    if (typeof briefRaw !== 'string')
+        return null;
+    const brief = briefRaw.trim();
+    if (brief.length === 0 || brief.length > TOOL_ROUTE_MAX_BRIEF_LEN)
+        return null;
+    // Persona is optional → default to `dev`. Any explicit non-empty
+    // value runs through the slug shape check + refused-persona gate.
+    const personaRaw = attrs['persona'];
+    let persona = DEFAULT_PERSONA;
+    if (typeof personaRaw === 'string' && personaRaw.length > 0) {
+        const trimmed = personaRaw.trim();
+        if (trimmed.length === 0 || trimmed.length > TOOL_ROUTE_MAX_PERSONA_LEN)
+            return null;
+        // Slug shape: lowercase ASCII letters + digits + hyphens, must
+        // start with a letter. Same shape as the `<pugi-delegate>` slug
+        // gate in admin-api so a future engine adapter can reuse the slug
+        // verbatim without re-validating.
+        if (!/^[a-z][a-z0-9-]*$/.test(trimmed))
+            return null;
+        if (REFUSED_PERSONAS.has(trimmed))
+            return null;
+        persona = trimmed;
+    }
+    const signature = signatureForToolRoute(command, persona, brief);
+    return {
+        command: command,
+        persona,
+        brief,
+        signature,
+        start: span.start,
+        end: span.end,
+    };
+}
+/**
+ * Parse `key="value"` / `key='value'` pairs out of an attribute blob.
+ * Returns null on any malformed attribute (unterminated quote, raw
+ * entity outside the allowlist, etc). Mirrors the bounded tokenizer
+ * in ask.ts so the parsing posture is uniform across envelope families.
+ */
+function parseAttrBlob(blob) {
+    const trimmed = blob.trim();
+    if (trimmed.length === 0)
+        return {};
+    const result = {};
+    let cursor = 0;
+    const maxIterations = trimmed.length + 4;
+    let iterations = 0;
+    while (cursor < trimmed.length && iterations++ < maxIterations) {
+        while (cursor < trimmed.length && /\s/.test(trimmed[cursor] ?? ''))
+            cursor += 1;
+        if (cursor >= trimmed.length)
+            break;
+        const nameStart = cursor;
+        // Attribute names are lowercase letters; allow `-` for consistency
+        // with the rest of the persona grammar even though our allowlist is
+        // hyphen-free. Mismatch is caught by the ALLOWED_ATTRS gate.
+        while (cursor < trimmed.length &&
+            /[a-z-]/.test(trimmed[cursor] ?? '')) {
+            cursor += 1;
+        }
+        if (cursor === nameStart)
+            return null;
+        const name = trimmed.slice(nameStart, cursor);
+        if (trimmed[cursor] !== '=')
+            return null;
+        cursor += 1;
+        const quote = trimmed[cursor];
+        if (quote !== '"' && quote !== "'")
+            return null;
+        cursor += 1;
+        const valueStart = cursor;
+        const valueEnd = trimmed.indexOf(quote, valueStart);
+        if (valueEnd === -1)
+            return null;
+        const rawValue = trimmed.slice(valueStart, valueEnd);
+        // Raw `&` outside a known entity is malformed; raw angle brackets
+        // are forbidden inside quoted values (must be escaped). The closed
+        // entity allowlist + control-char strip mirrors ask.ts.
+        if (containsRawAmpersand(rawValue))
+            return null;
+        if (/[<>]/.test(rawValue))
+            return null;
+        result[name] = stripControlChars(decodeEntities(rawValue));
+        cursor = valueEnd + 1;
+    }
+    return result;
+}
+/* ------------------------------------------------------------------ */
+/* Streaming helper — find an unquoted `>` after `from`               */
+/* ------------------------------------------------------------------ */
+/**
+ * Walk `body` from index `from` looking for the first `>` that is NOT
+ * inside a quoted attribute value. Returns the index of the `>` or -1
+ * when no such position is found.
+ *
+ * Quote tracking is necessary because a `brief="…contains > as &gt;…"`
+ * value should never confuse the boundary scan. The grammar already
+ * forbids raw `>` inside quoted values (escape as `&gt;`) — this is
+ * belt-and-braces against a sloppy model emission.
+ */
+function findUnquotedGt(body, from) {
+    let quote = null;
+    for (let i = from; i < body.length; i += 1) {
+        const ch = body[i];
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '>')
+            return i;
+    }
+    return -1;
+}
+/* ------------------------------------------------------------------ */
+/* Entity decoding + amp safety + control strip                       */
+/* ------------------------------------------------------------------ */
+const ENTITY_MAP = Object.freeze({
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+});
+function decodeEntities(input) {
+    return input.replace(/&([a-z]+);/g, (whole, name) => {
+        const decoded = ENTITY_MAP[name];
+        return decoded === undefined ? whole : decoded;
+    });
+}
+function stripControlChars(input) {
+    // eslint-disable-next-line no-control-regex -- deliberately matching control range
+    return input.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\x80-\x9f]/g, '');
+}
+function containsRawAmpersand(input) {
+    for (let i = 0; i < input.length; i += 1) {
+        if (input[i] !== '&')
+            continue;
+        const semi = input.indexOf(';', i + 1);
+        if (semi === -1)
+            return true;
+        const name = input.slice(i + 1, semi);
+        if (!Object.prototype.hasOwnProperty.call(ENTITY_MAP, name))
+            return true;
+        i = semi;
+    }
+    return false;
+}
+/* ------------------------------------------------------------------ */
+/* Signature                                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Stable dedupe signature for a tool-route tag. Exported so future
+ * synthesisers (slash command, local fallback) can produce signatures
+ * that collision-match parser-produced ones — without a single source
+ * of truth a local synth could share a signature with a persona-emitted
+ * envelope and the rolling-seen set would suppress one of them.
+ */
+export function signatureForToolRoute(command, persona, brief) {
+    const raw = `${command}::${persona.toLowerCase()}::${brief.trim().toLowerCase()}`;
+    return Buffer.from(raw, 'utf8').toString('base64');
+}
+//# sourceMappingURL=tool-route.js.map

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

@@ -1,18 +1,18 @@
 /**
- * Workspace context resolver — Sprint α6.14 wave 4.
+ * 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. Mira's prompt v1.1
+ * 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 2026-05-25).
+ * 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.
+ *  - `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
@@ -27,16 +27,26 @@
 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 2026-05-25 dogfood, the
+ * 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 Mira/Pugi about what repo she was looking at. The
+ * 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. (α6.14.2 wave 5.)
+ * read the same warning.
  */
 export const UNBOUND_WORKSPACE_LABEL = '(not bound - run /init OR cd into project)';
 /**
@@ -48,9 +58,21 @@ export const UNBOUND_WORKSPACE_LABEL = '(not bound - run /init OR cd into projec
 export function resolveWorkspaceContext(cwd) {
     const normalised = resolvePath(cwd);
     const slug = slugForCwd(normalised);
-    // α6.14.2 wave 5: when the cwd has no project markers, prefer the
+    // `--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 Mira/Pugi. The cwd +
+    // 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.
@@ -69,18 +91,18 @@ export function resolveWorkspaceContext(cwd) {
  * 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`)
+ *  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 Claude Code "no CLAUDE.md → silent context" rule —
- * never fake-bind. (α6.14.2 wave 5 — CEO dogfood fix.)
+ * mirrors the the upstream tool "no CLAUDE.md → silent context" rule —
+ * never fake-bind.
  */
 export function isBoundWorkspace(cwd) {
     const normalised = resolvePath(cwd);
@@ -105,7 +127,7 @@ export function isBoundWorkspace(cwd) {
  * 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.
- * (α6.14.2 wave 5.)
+ *
  */
 export function resolveWorkspaceLabel(cwd) {
     if (!isBoundWorkspace(cwd))
@@ -119,7 +141,7 @@ export function resolveWorkspaceLabel(cwd) {
 /**
  * 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 Mira — `pugi init` writes it on workspace creation, and
+ * 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
@@ -169,7 +191,7 @@ export function summariseMarkdown(raw) {
 }
 /**
  * Drop a YAML front-matter block (`---\n…\n---`) from the head of a
- * Markdown file. Mira does not need to see the metadata; the prose body
+ * Markdown file. Pugi does not need to see the metadata; the prose body
  * carries the project description.
  */
 function stripFrontmatter(raw) {

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

@@ -0,0 +1,125 @@
+/**
+ * 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