@spikedpunch/mast 0.1.0

package/dist/cli/docs-cmd.js

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { CLI_VERSION, PACKAGE_NAME } from './version.js';
+import { detectSkillTargets, installSkillInto } from './skill-install.js';
+import { resolveConfig } from '../store/config.js';
+/**
+ * `mast docs` and `mast skill` — documentation that is version-matched by construction.
+ *
+ * Both read files shipped inside the installed package rather than pointing at a
+ * website, so what a user (or an agent) reads is what their binary does. Looking up
+ * "which release am I on, and which docs go with it" is exactly the step this removes,
+ * and it is the step where a reader silently ends up on docs for a different version.
+ */
+export class DocsError extends Error {
+}
+// `dist/cli/` and `src/cli/` both sit two levels below the package root, so this
+// resolves identically under vitest and in the published tarball.
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const DOC_TOPICS = [
+    { name: 'readme', file: 'README.md', summary: 'Install, quick start, CLI and MCP tool reference' },
+    { name: 'spec', file: 'MAST_SPEC.md', summary: 'Full behavioural specification — schemas, tool contracts, invariants' },
+    { name: 'skill', file: 'assets/skill.md', summary: 'The instructions to paste into an agent prompt or skill file' },
+];
+export function readDoc(name) {
+    const topic = DOC_TOPICS.find((t) => t.name === name);
+    if (topic === undefined) {
+        throw new DocsError(`unknown docs topic "${name}"; available topics: ${DOC_TOPICS.map((t) => t.name).join(', ')}`);
+    }
+    try {
+        return readFileSync(join(PACKAGE_ROOT, topic.file), 'utf8');
+    }
+    catch {
+        throw new DocsError(`${topic.file} is missing from this installation of ${PACKAGE_NAME}@${CLI_VERSION}`);
+    }
+}
+export function listDocs() {
+    const width = Math.max(...DOC_TOPICS.map((t) => t.name.length));
+    return [
+        `${PACKAGE_NAME} ${CLI_VERSION} — documentation shipped with this build`,
+        '',
+        ...DOC_TOPICS.map((t) => `  ${t.name.padEnd(width)}  ${t.summary}`),
+        '',
+        'Read one with `mast docs <topic>`.',
+    ].join('\n');
+}
+export function registerDocsCommand(program) {
+    program
+        .command('docs [topic]')
+        .description('Print the documentation shipped with this build — no version lookup needed')
+        .action((topic) => {
+        try {
+            process.stdout.write((topic === undefined ? listDocs() : readDoc(topic)) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+export function registerSkillCommand(program) {
+    program
+        .command('skill [path]')
+        .description('Print the MAST instructions to copy into an agent prompt or skill file')
+        .option('--install', 'Splice the instructions into this project\'s existing agent config files')
+        .option('--dry-run', 'With --install, report what would change without writing')
+        .action((projectPath, opts) => {
+        try {
+            const skill = readDoc('skill');
+            if (opts.install !== true) {
+                process.stdout.write(skill + '\n');
+                return;
+            }
+            const root = resolveConfig({ projectRoot: projectPath }).resolved_project_root;
+            const targets = detectSkillTargets(root);
+            if (targets.length === 0) {
+                // Not an error: a project with no agent config is a normal state, and the
+                // remedy is a decision for the user, not a file this command invents.
+                process.stdout.write([`No agent config files found in ${root}.`, '',
+                    'Create one of these and re-run, or pipe the skill wherever you keep prompts:',
+                    '  CLAUDE.md  AGENTS.md  .cursorrules  .windsurfrules  .github/copilot-instructions.md', '',
+                    '  mast skill >> CLAUDE.md'].join('\n') + '\n');
+                return;
+            }
+            const dryRun = opts.dryRun === true;
+            for (const { target, changed } of installSkillInto(targets, skill, { dryRun })) {
+                const verb = !changed ? 'unchanged' : dryRun ? 'would update' : 'updated';
+                process.stdout.write(`  ${verb.padEnd(13)} ${target.file}  (${target.agent})\n`);
+            }
+            process.stdout.write(dryRun
+                ? '\nDry run — nothing written. Re-run without --dry-run to apply.\n'
+                : '\nThe block is marked; re-running after an upgrade replaces it rather than adding a second copy.\n');
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=docs-cmd.js.map

package/dist/cli/docs-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-cmd.js","sourceRoot":"","sources":["../../src/cli/docs-cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/index-cmd.d.ts

@@ -0,0 +1,72 @@
+import type { Command } from 'commander';
+import { type OpenDatabaseOptions } from '../graph/db.js';
+/**
+ * Whether to print the per-phase breakdown.
+ *
+ * Extracted rather than inlined in the action so the gate is testable without spawning the
+ * built CLI: a spawn-based test resolves against `dist/`, and a negative assertion
+ * ("stdout does not contain phases:") passes trivially when the spawn produces no output at
+ * all. That false green is the D8 failure mode in miniature.
+ *
+ * This is the first environment flag in the codebase and so sets the convention:
+ * `ENABLE_`-prefixed, and the value is the word `true` or `false`, never `1`/`0`. Compared
+ * case-insensitively after trimming, because env vars are typed by hand. Anything that is
+ * not `true` is off, so a typo fails closed rather than silently switching instrumentation
+ * on in an ordinary run.
+ */
+export declare function isPhaseTimingEnabled(flag: boolean | undefined, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Parse an operator-supplied MiB figure for the SQLite tuning flags.
+ *
+ * Commander yields raw strings, so this is a trust boundary (§3.2) — the value
+ * is validated here and the pragma layer downstream receives only numbers it
+ * can apply verbatim. Fractions are refused rather than truncated so that an
+ * arm's declared size and its applied size are always the same number; a silent
+ * truncation would put a measurement's own label out of step with what ran.
+ *
+ * Exported for direct testing: a spawn-based CLI test resolves against `dist/`
+ * and would grade a different binary than the one under review (the D8 failure
+ * mode), which is why `isPhaseTimingEnabled` above is exported for the same
+ * reason.
+ *
+ * @throws Error naming the flag and the rejected value, if it is not a
+ *   non-negative whole number.
+ */
+export declare function parseMebibytes(flag: string, raw: string): number;
+/**
+ * Whether to print the applied-pragma line.
+ *
+ * Emitted when the operator tuned something (they should see what actually took
+ * effect, not what they typed), and also under the phase-timing gate — which is
+ * what gives the A/B's *control* arm, which passes no tuning flag at all, a
+ * `pragmas:` line to be graded against. Without the second clause the one arm
+ * whose "un-pragma'd" claim carries the most weight would be the one arm with
+ * no evidence for it.
+ *
+ * Extracted for the same reason as {@link isPhaseTimingEnabled}: a spawn-based
+ * test resolves against `dist/`, where a negative assertion passes trivially on
+ * empty stdout.
+ */
+export declare function shouldPrintPragmas(phaseTimingEnabled: boolean, dbOptions: OpenDatabaseOptions): boolean;
+/**
+ * Whether this run skips the per-file FTS5 deletes — E1-FTS's arm G.
+ *
+ * The skip is only sound on a **cold** build, where those deletes match zero
+ * rows and the finished database is therefore identical to the control's. On an
+ * incremental run they are load-bearing: skipping them leaves the previous
+ * version's rows in `chunk_fts` / `identifier_fts` alongside the new ones while
+ * the ordinary tables replace correctly, so the index goes silently wrong — no
+ * error, no missing rows, just stale search hits.
+ *
+ * Refused here, at the trust boundary, rather than documented and hoped for.
+ * It **throws** instead of falling back to the safe path, because an operator
+ * who asked for arm G and quietly received arm A would collect a null and have
+ * no way to tell.
+ *
+ * Exported for direct testing, same reason as {@link parseMebibytes}.
+ *
+ * @throws Error naming both flags, if the skip is combined with `--incremental`.
+ */
+export declare function resolveSkipFtsDeletes(flag: boolean | undefined, incremental: boolean): boolean;
+export declare function registerIndexCommand(program: Command): void;
+//# sourceMappingURL=index-cmd.d.ts.map

package/dist/cli/index-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/index-cmd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAIxE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAShE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,OAAO,EAC3B,SAAS,EAAE,mBAAmB,GAC7B,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,WAAW,EAAE,OAAO,GACnB,OAAO,CAUT;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+M3D"}

package/dist/cli/index-cmd.js

@@ -0,0 +1,263 @@
+import { resolveConfig } from '../store/config.js';
+import { runIndex } from '../indexer/index.js';
+import { newWriteSpans } from '../graph/populate.js';
+import { openDatabase } from '../graph/db.js';
+import { SqliteChunkStore } from '../store/sqliteChunkStore.js';
+import { runCheckerPass } from '../graph/checker-resolver.js';
+/**
+ * Whether to print the per-phase breakdown.
+ *
+ * Extracted rather than inlined in the action so the gate is testable without spawning the
+ * built CLI: a spawn-based test resolves against `dist/`, and a negative assertion
+ * ("stdout does not contain phases:") passes trivially when the spawn produces no output at
+ * all. That false green is the D8 failure mode in miniature.
+ *
+ * This is the first environment flag in the codebase and so sets the convention:
+ * `ENABLE_`-prefixed, and the value is the word `true` or `false`, never `1`/`0`. Compared
+ * case-insensitively after trimming, because env vars are typed by hand. Anything that is
+ * not `true` is off, so a typo fails closed rather than silently switching instrumentation
+ * on in an ordinary run.
+ */
+export function isPhaseTimingEnabled(flag, env = process.env) {
+    if (flag === true)
+        return true;
+    return env.ENABLE_MAST_PHASE_TIMING?.trim().toLowerCase() === 'true';
+}
+/**
+ * Parse an operator-supplied MiB figure for the SQLite tuning flags.
+ *
+ * Commander yields raw strings, so this is a trust boundary (§3.2) — the value
+ * is validated here and the pragma layer downstream receives only numbers it
+ * can apply verbatim. Fractions are refused rather than truncated so that an
+ * arm's declared size and its applied size are always the same number; a silent
+ * truncation would put a measurement's own label out of step with what ran.
+ *
+ * Exported for direct testing: a spawn-based CLI test resolves against `dist/`
+ * and would grade a different binary than the one under review (the D8 failure
+ * mode), which is why `isPhaseTimingEnabled` above is exported for the same
+ * reason.
+ *
+ * @throws Error naming the flag and the rejected value, if it is not a
+ *   non-negative whole number.
+ */
+export function parseMebibytes(flag, raw) {
+    // Number('') is 0 — an empty value must be an error, not a silent zero.
+    const value = raw.trim() === '' ? Number.NaN : Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${flag} expects a non-negative whole number of MiB, received "${raw}"`);
+    }
+    return value;
+}
+/**
+ * Whether to print the applied-pragma line.
+ *
+ * Emitted when the operator tuned something (they should see what actually took
+ * effect, not what they typed), and also under the phase-timing gate — which is
+ * what gives the A/B's *control* arm, which passes no tuning flag at all, a
+ * `pragmas:` line to be graded against. Without the second clause the one arm
+ * whose "un-pragma'd" claim carries the most weight would be the one arm with
+ * no evidence for it.
+ *
+ * Extracted for the same reason as {@link isPhaseTimingEnabled}: a spawn-based
+ * test resolves against `dist/`, where a negative assertion passes trivially on
+ * empty stdout.
+ */
+export function shouldPrintPragmas(phaseTimingEnabled, dbOptions) {
+    return phaseTimingEnabled || Object.keys(dbOptions).length > 0;
+}
+/**
+ * Whether this run skips the per-file FTS5 deletes — E1-FTS's arm G.
+ *
+ * The skip is only sound on a **cold** build, where those deletes match zero
+ * rows and the finished database is therefore identical to the control's. On an
+ * incremental run they are load-bearing: skipping them leaves the previous
+ * version's rows in `chunk_fts` / `identifier_fts` alongside the new ones while
+ * the ordinary tables replace correctly, so the index goes silently wrong — no
+ * error, no missing rows, just stale search hits.
+ *
+ * Refused here, at the trust boundary, rather than documented and hoped for.
+ * It **throws** instead of falling back to the safe path, because an operator
+ * who asked for arm G and quietly received arm A would collect a null and have
+ * no way to tell.
+ *
+ * Exported for direct testing, same reason as {@link parseMebibytes}.
+ *
+ * @throws Error naming both flags, if the skip is combined with `--incremental`.
+ */
+export function resolveSkipFtsDeletes(flag, incremental) {
+    if (flag !== true)
+        return false;
+    if (incremental) {
+        throw new Error('--unsafe-skip-fts-deletes cannot be combined with --incremental: the FTS deletes are ' +
+            'only redundant on a cold build. On an incremental run they are what removes the ' +
+            'previous version\'s rows, and skipping them corrupts the index silently.');
+    }
+    return true;
+}
+export function registerIndexCommand(program) {
+    program
+        .command('index [path]')
+        .description('Build or update the index')
+        .option('--state-dir <dir>', 'State directory (resolved from config if omitted)')
+        .option('--incremental', 'Only reindex files changed since last index run')
+        .option('--show-progress', 'Print indexing progress to stderr')
+        .option('--checker', 'Opt-in TypeScript-checker pass (Stage 1.2): upgrade heuristic potential_matches into verified edges ' +
+        'or drop non-call-site/wrong-declaration noise. Holds one ts.Program at a time; can take tens of seconds ' +
+        'on a large monorepo — not part of the default index path (MAST_SPEC §10.3.2).')
+        .option('--phase-timing', 'Print a machine-readable per-phase breakdown of the index run (walk/parse/write/edges/finalise). ' +
+        'Also enabled by ENABLE_MAST_PHASE_TIMING=true. The timers themselves always run — this only ' +
+        'controls the output line — so enabling it costs nothing but a line of stdout.')
+        .option('--cache-size-mib <mib>', 'SQLite page-cache budget for this run, in MiB (PRAGMA cache_size). Diagnostic lever for the ' +
+        'E1-PHASE mechanism probe; omitted, SQLite\'s own default stands and nothing is set.')
+        .option('--mmap-size-mib <mib>', 'SQLite memory-map budget for this run, in MiB (PRAGMA mmap_size); 0 disables memory mapping. ' +
+        'Diagnostic lever for the E1-PHASE mechanism probe; omitted, SQLite\'s own default stands.')
+        .option('--unsafe-skip-fts-deletes', 'EVAL ONLY — skip the per-file FTS5 delete statements. Sound ONLY on a cold build, where they ' +
+        'match zero rows; on any other path this leaves stale FTS rows behind and corrupts the index ' +
+        'silently, so it is refused with --incremental. E1-FTS arm G.')
+        .action(async (projectPath, opts) => {
+        const config = resolveConfig({
+            projectRoot: projectPath,
+            stateDirOverride: opts.stateDir,
+        });
+        // Built with conditional spreads, not `{ cacheSizeKib: maybeUndefined }`:
+        // `exactOptionalPropertyTypes` distinguishes an absent property from one
+        // explicitly set to undefined, and the A/B's control arm depends on the
+        // property being genuinely absent.
+        const dbOptions = {
+            ...(opts.cacheSizeMib !== undefined
+                ? { cacheSizeKib: parseMebibytes('--cache-size-mib', opts.cacheSizeMib) * 1024 }
+                : {}),
+            ...(opts.mmapSizeMib !== undefined
+                ? { mmapSizeBytes: parseMebibytes('--mmap-size-mib', opts.mmapSizeMib) * 1024 * 1024 }
+                : {}),
+        };
+        const onProgress = opts.showProgress
+            ? (processed, total) => {
+                if (total === 0)
+                    return;
+                const pct = Math.round((processed / total) * 100);
+                const line = `  indexing ${processed}/${total} files (${pct}%)`;
+                // \r rewrites the line in place on a TTY; fall back to newlines otherwise.
+                process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+                if (processed === total && process.stderr.isTTY)
+                    process.stderr.write('\n');
+            }
+            : undefined;
+        const incremental = opts.incremental ?? false;
+        const skipFtsDeletes = resolveSkipFtsDeletes(opts.unsafeSkipFtsDeletes, incremental);
+        // Allocated only under the phase-timing gate, and passed only when
+        // allocated: `populateFile` reads no clock at all without an accumulator,
+        // so an ordinary `mast index` is untouched by this instrument.
+        const writeSpans = isPhaseTimingEnabled(opts.phaseTiming) ? newWriteSpans() : undefined;
+        if (skipFtsDeletes) {
+            // Loud on stderr as well as refused above: this run's database is a
+            // measurement artifact, and anyone reading the log later must be able
+            // to tell it apart from a production index.
+            process.stderr.write('[mast] WARN: --unsafe-skip-fts-deletes is set — FTS5 delete statements are being ' +
+                'skipped. This is an eval instrument (E1-FTS arm G) and is sound only because this ' +
+                'is a cold build. Do NOT reuse this index.\n');
+        }
+        const result = await runIndex(config, {
+            incremental,
+            onProgress,
+            dbOptions,
+            ...(writeSpans !== undefined ? { writeSpans } : {}),
+            ...(skipFtsDeletes ? { unsafeSkipFtsDeletes: true } : {}),
+        });
+        process.stdout.write(`files: ${result.filesIndexed} indexed, ${result.filesSkipped} skipped` +
+            `  chunks: +${result.chunksAdded} -${result.chunksRemoved}` +
+            `  duration: ${result.durationMs}ms` +
+            (result.parseErrors > 0 ? `  parse_errors: ${result.parseErrors}` : '') +
+            (result.writeErrors > 0 ? `  write_errors: ${result.writeErrors}` : '') +
+            (result.staleWriteRejections > 0 ? `  stale_write_rejections: ${result.staleWriteRejections}` : '') +
+            (result.miscasedImports.count > 0 ? `  miscased_imports: ${result.miscasedImports.count}` : '') +
+            '\n');
+        // A mis-cased import is a defect in the indexed repository, not in MAST:
+        // it compiles on APFS/NTFS and fails on a case-sensitive filesystem. MAST
+        // indexes it correctly regardless (the edge points at the on-disk file),
+        // so this is advisory and does not affect the exit code. stderr, because
+        // stdout carries the machine-readable summary above.
+        if (result.miscasedImports.count > 0) {
+            const { count, samples } = result.miscasedImports;
+            process.stderr.write(`warning: ${count} import${count === 1 ? '' : 's'} resolved only because this ` +
+                `filesystem ignores case; ${count === 1 ? 'it' : 'they'} will not resolve on a ` +
+                `case-sensitive one:\n` +
+                samples.map((m) => `  ${m.fromFile}: '${m.specifier}' -> ${m.onDiskPath}\n`).join('') +
+                (count > samples.length ? `  ... and ${count - samples.length} more\n` : ''));
+        }
+        // Machine-readable phase breakdown, opt-in. E1 measured a growth exponent of ~1.75
+        // from `duration` alone and could not say which phase carried it; the scaling harness
+        // parses this line to decompose the next ladder.
+        //
+        // Gated because it is instrumentation, not a user-facing summary, and an unconditional
+        // extra stdout line changes the CLI's output contract for everyone. The env var exists
+        // so a harness that spawns the shipped binary can enable it without every call site
+        // growing an argument — read HERE, at the CLI boundary, and never inside the indexer.
+        if (isPhaseTimingEnabled(opts.phaseTiming)) {
+            process.stdout.write(`phases: ${JSON.stringify(result.phaseMs)}\n`);
+        }
+        // The write phase's own decomposition (E1-FTS). A separate line from
+        // `phases:` on purpose — `phases:` is E1-PHASE's scored instrument and a
+        // finished record must not sit behind a moving definition, which is the
+        // same rule that gave E1-AB its own schedule module rather than an
+        // extension of E1's.
+        if (writeSpans !== undefined) {
+            process.stdout.write(`write_spans: ${JSON.stringify(writeSpans)}\n`);
+        }
+        // The pragmas SQLite reported for this run's own connection, not an echo
+        // of the flags. A flag that failed to reach the connection would make the
+        // A/B's two arms identical and produce a clean, credible-looking null —
+        // this line is what makes that failure visible instead.
+        if (shouldPrintPragmas(isPhaseTimingEnabled(opts.phaseTiming), dbOptions)) {
+            process.stdout.write(`pragmas: ${JSON.stringify(result.appliedPragmas)}\n`);
+        }
+        // Non-zero exit so CI/scripts catch a silently-amputated file — a
+        // chunk-store write failure must be impossible to miss, not just a
+        // console line a human happens to read (GITNEXUS_COMPARISON.md §16).
+        // `exitCode` (not `process.exit()`) lets stdout/stderr flush and any
+        // later steps in this action (Phase 2 embed, checker pass) still run.
+        if (result.writeErrors > 0)
+            process.exitCode = 1;
+        // Opt-in Stage 1.2 checker pass — runs after Phase 1 (parse/chunk/graph/
+        // FTS is all there is post-Stage-7.1) so it classifies against the
+        // freshest graph.db this invocation just wrote. Opens its own db handle
+        // (chunkStore wraps it, §15.1) and destroys it itself (runIndex already
+        // closed its own), matching the one-shot-process pattern this command
+        // already used for the now-removed Phase 2 embed step.
+        if (opts.checker) {
+            // Same tuning as the index run above: a flag that applied to one half
+            // of `mast index` and silently not the other would be a trap.
+            const db = openDatabase(config.resolved_state_dir, dbOptions);
+            const chunkStore = new SqliteChunkStore(db);
+            try {
+                const checkerResult = await runCheckerPass(db, chunkStore, config, {
+                    onProject: opts.showProgress
+                        ? (configDir, index, total) => {
+                            const line = `  checker ${index}/${total}: ${configDir}`;
+                            process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+                        }
+                        : undefined,
+                });
+                if (opts.showProgress && process.stderr.isTTY)
+                    process.stderr.write('\n');
+                // No silent caps: every project the pass skipped is named, not just counted.
+                for (const skip of checkerResult.projectsSkipped) {
+                    process.stderr.write(`[mast] checker: skipped ${skip.configDir} (${skip.reason})\n`);
+                }
+                process.stdout.write(`checker: ${checkerResult.projectsChecked} project(s) checked, ${checkerResult.projectsSkipped.length} skipped` +
+                    `  symbols_checked: ${checkerResult.symbolsChecked}` +
+                    `  outside_ts_scope: ${checkerResult.potentialSitesOutsideScope}\n` +
+                    `  edges_upgraded: ${checkerResult.edgesUpgraded}` +
+                    `  non_call_site: ${checkerResult.classifiedNonCallSite}` +
+                    `  different_declaration: ${checkerResult.classifiedDifferentDeclaration}` +
+                    `  unresolved: ${checkerResult.unresolved}\n` +
+                    `  duration: ${checkerResult.durationMs}ms` +
+                    `  peak_rss_mb: ${Math.round(checkerResult.peakRssBytes / (1024 * 1024))}\n`);
+            }
+            finally {
+                await db.destroy();
+            }
+        }
+    });
+}
+//# sourceMappingURL=index-cmd.js.map

package/dist/cli/index-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-cmd.js","sourceRoot":"","sources":["../../src/cli/index-cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { buildProgram } from './program.js';
+await buildProgram().parseAsync(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,YAAY,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/cli/init.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+/**
+ * Parses `mast init --extensions <ext,...>` into `resolveConfig`'s `extensions` override.
+ * Returns `undefined` when the flag is absent, so flag absence keeps `resolveConfig`'s
+ * default-priority behavior byte-identical (F9, Stage 3.5).
+ */
+export declare function parseExtensionsFlag(raw: string | undefined): readonly string[] | undefined;
+/**
+ * Parses `mast init --exclude <pattern,...>` into `resolveConfig`'s `excludePatterns` override.
+ * Returns `undefined` when the flag is absent, same rationale as `parseExtensionsFlag`.
+ */
+export declare function parseExcludeFlag(raw: string | undefined): readonly string[] | undefined;
+export declare function registerInitCommand(program: Command): void;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAG1F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAGvF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkC1D"}

package/dist/cli/init.js

@@ -0,0 +1,64 @@
+import { resolveConfig, writeStateConfig } from '../store/config.js';
+import { initLockMarkers } from '../store/lock.js';
+import { runIndex } from '../indexer/index.js';
+/** Splits a comma-separated CLI flag value, trimming entries and dropping empties. */
+function parseCommaSeparatedList(raw) {
+    return raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+/**
+ * Normalizes a user-supplied extension to the leading-dot form `MastConfig.file_extensions`
+ * expects (`indexer/walker.ts`'s `walkProject` builds glob patterns as `**\/*${ext}`) — both
+ * '.py' and 'py' are accepted on the CLI so users don't have to remember the internal form.
+ */
+function normalizeExtension(ext) {
+    return ext.startsWith('.') ? ext : `.${ext}`;
+}
+/**
+ * Parses `mast init --extensions <ext,...>` into `resolveConfig`'s `extensions` override.
+ * Returns `undefined` when the flag is absent, so flag absence keeps `resolveConfig`'s
+ * default-priority behavior byte-identical (F9, Stage 3.5).
+ */
+export function parseExtensionsFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    return parseCommaSeparatedList(raw).map(normalizeExtension);
+}
+/**
+ * Parses `mast init --exclude <pattern,...>` into `resolveConfig`'s `excludePatterns` override.
+ * Returns `undefined` when the flag is absent, same rationale as `parseExtensionsFlag`.
+ */
+export function parseExcludeFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    return parseCommaSeparatedList(raw);
+}
+export function registerInitCommand(program) {
+    program
+        .command('init [path]')
+        .description('Initialise mast for a project and run the initial index')
+        .option('--state-dir <dir>', 'Where to write index state (default: <path>/.mast)')
+        .option('--extensions <ext,...>', 'Comma-separated file extensions to index (default: .ts,.tsx,.js,.jsx)')
+        .option('--exclude <pattern,...>', 'Comma-separated glob patterns to exclude')
+        .option('--no-index', 'Create config only; skip initial indexing')
+        .action(async (projectPath, opts) => {
+        const config = resolveConfig({
+            projectRoot: projectPath,
+            stateDirOverride: opts.stateDir,
+            extensions: parseExtensionsFlag(opts.extensions),
+            excludePatterns: parseExcludeFlag(opts.exclude),
+        });
+        initLockMarkers(config.resolved_state_dir);
+        writeStateConfig(config.resolved_state_dir, config);
+        process.stdout.write(`Initialised ${config.resolved_state_dir}\n`);
+        if (opts.index) {
+            const result = await runIndex(config, { incremental: false });
+            process.stdout.write(`Indexed ${result.filesIndexed} files, ${result.chunksAdded} chunks in ${result.durationMs}ms` +
+                (result.parseErrors > 0 ? ` (${result.parseErrors} parse errors — check stderr)` : '') +
+                '\n');
+        }
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,sFAAsF;AACtF,SAAS,uBAAuB,CAAC,GAAW;IAC1C,OAAO,GAAG;SACP,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,GAAW;IACrC,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAuB;IACzD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAuB;IACtD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,aAAa,CAAC;SACtB,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,mBAAmB,EAAE,oDAAoD,CAAC;SACjF,MAAM,CAAC,wBAAwB,EAAE,uEAAuE,CAAC;SACzG,MAAM,CAAC,yBAAyB,EAAE,0CAA0C,CAAC;SAC7E,MAAM,CAAC,YAAY,EAAE,2CAA2C,CAAC;SACjE,MAAM,CAAC,KAAK,EAAE,WAA+B,EAAE,IAK/C,EAAE,EAAE;QACH,MAAM,MAAM,GAAG,aAAa,CAAC;YAC3B,WAAW,EAAE,WAAW;YACxB,gBAAgB,EAAE,IAAI,CAAC,QAAQ;YAC/B,UAAU,EAAE,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC;YAChD,eAAe,EAAE,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;SAChD,CAAC,CAAC;QAEH,eAAe,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC3C,gBAAgB,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;QACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,MAAM,CAAC,kBAAkB,IAAI,CAAC,CAAC;QAEnE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;YAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,WAAW,MAAM,CAAC,YAAY,WAAW,MAAM,CAAC,WAAW,cAAc,MAAM,CAAC,UAAU,IAAI;gBAC9F,CAAC,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,WAAW,+BAA+B,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtF,IAAI,CACL,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/install-hooks.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerInstallHooksCommand(program: Command): void;
+//# sourceMappingURL=install-hooks.d.ts.map

package/dist/cli/install-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-hooks.d.ts","sourceRoot":"","sources":["../../src/cli/install-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuBlE"}

package/dist/cli/install-hooks.js

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const HOOKS = [
+    {
+        name: 'post-commit',
+        body: '#!/bin/sh\nmast index --incremental\n',
+    },
+    {
+        name: 'post-checkout',
+        body: '#!/bin/sh\nmast index --incremental\n',
+    },
+];
+export function registerInstallHooksCommand(program) {
+    program
+        .command('install-hooks [path]')
+        .description('Install git hooks that keep the index fresh after commits and checkouts')
+        .action((projectPath) => {
+        const root = resolve(projectPath ?? process.cwd());
+        const hooksDir = join(root, '.git', 'hooks');
+        if (!existsSync(join(root, '.git'))) {
+            process.stderr.write(`mast: no .git directory found at ${root}\n`);
+            process.exit(1);
+        }
+        mkdirSync(hooksDir, { recursive: true });
+        for (const hook of HOOKS) {
+            const hookPath = join(hooksDir, hook.name);
+            writeFileSync(hookPath, hook.body, { encoding: 'utf-8' });
+            // Git requires hooks to be executable.
+            chmodSync(hookPath, 0o755);
+            process.stdout.write(`Installed ${hookPath}\n`);
+        }
+    });
+}
+//# sourceMappingURL=install-hooks.js.map

package/dist/cli/install-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-hooks.js","sourceRoot":"","sources":["../../src/cli/install-hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,KAAK,GAAkD;IAC3D;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,uCAAuC;KAC9C;IACD;QACE,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,uCAAuC;KAC9C;CACF,CAAC;AAEF,MAAM,UAAU,2BAA2B,CAAC,OAAgB;IAC1D,OAAO;SACJ,OAAO,CAAC,sBAAsB,CAAC;SAC/B,WAAW,CAAC,yEAAyE,CAAC;SACtF,MAAM,CAAC,CAAC,WAA+B,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAE7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;YACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,IAAI,IAAI,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAC1D,uCAAuC;YACvC,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,QAAQ,IAAI,CAAC,CAAC;QAClD,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/metrics-cmd.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerMetricsCommand(program: Command): void;
+//# sourceMappingURL=metrics-cmd.d.ts.map

package/dist/cli/metrics-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/metrics-cmd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4IzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgE7D"}