legacymaxxing 0.1.0

package/dist/commands.js

@@ -0,0 +1,469 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ToolError, errMessage } from "./errors.js";
+import { PHASE_NAMES, PHASES, isPhaseName } from "./phases.js";
+import { configRecordSchema, phaseRecordSchema, projectRecordSchema, } from "./types.js";
+import { isDirectory, pathExists, readJson, writeJson } from "./fs.js";
+import { claim, listLocks, lockPath, phaseRecordPath, release, runRecordPath } from "./state.js";
+import { partitionArtifacts, providerByName } from "./provider.js";
+import { runDetectors } from "./detectors/index.js";
+import { buildPrompt } from "./prompts.js";
+import { assertCleanWorktree, headSha, isGitRepo } from "./git.js";
+const exec = promisify(execFile);
+const STATE_EXCLUDE = [".legacymaxxing", "analysis"];
+const MAX_SCAN_FILES = 5000;
+// ---- small flag helpers -----------------------------------------------------
+function flagStr(flags, key) {
+    const value = flags[key];
+    return typeof value === "string" ? value : null;
+}
+function flagBool(flags, key) {
+    return flags[key] === true || flags[key] === "true";
+}
+function requireStr(value, name, usage) {
+    if (!value)
+        throw new ToolError(`missing ${name} (${usage})`, 2, "invalid-usage");
+    return value;
+}
+function parsePhaseArg(flags) {
+    const raw = flagStr(flags, "phase");
+    if (raw && isPhaseName(raw))
+        return raw;
+    throw new ToolError(`unknown phase: ${raw ?? "(none)"} — one of: ${PHASE_NAMES.join(", ")}`, 2, "invalid-usage");
+}
+function progress(ctx, message) {
+    if (!ctx.options.quiet)
+        process.stderr.write(`${message}\n`);
+}
+// ---- state loaders ----------------------------------------------------------
+async function readProject(ctx) {
+    if (!(await pathExists(ctx.paths.project))) {
+        throw new ToolError("not initialized; run `legacymaxxing init` first", 2, "invalid-usage");
+    }
+    return readJson(ctx.paths.project, projectRecordSchema);
+}
+async function readConfig(ctx) {
+    if (!(await pathExists(ctx.paths.config))) {
+        throw new ToolError("not initialized; run `legacymaxxing init` first", 2, "invalid-usage");
+    }
+    return readJson(ctx.paths.config, configRecordSchema);
+}
+async function resolveSystem(ctx, flags) {
+    const project = await readProject(ctx);
+    const requested = ctx.options.system ?? flagStr(flags, "system");
+    let entry = requested
+        ? project.systems.find((s) => s.name === requested)
+        : project.systems.length === 1
+            ? project.systems[0]
+            : undefined;
+    if (requested && !entry) {
+        throw new ToolError(`unknown system: ${requested}`, 2, "invalid-usage");
+    }
+    if (!entry) {
+        const names = project.systems.map((s) => s.name).join(", ") || "none";
+        throw new ToolError(`--system required (registered: ${names})`, 2, "invalid-usage");
+    }
+    return { system: entry.name, legacyPath: entry.legacyPath, baseSha: entry.baseSha };
+}
+async function loadPhase(ctx, system, phase) {
+    const path = phaseRecordPath(ctx.paths.stateDir, system, phase);
+    if (!(await pathExists(path)))
+        return null;
+    return readJson(path, phaseRecordSchema);
+}
+async function savePhase(ctx, record) {
+    await writeJson(phaseRecordPath(ctx.paths.stateDir, record.system, record.phase), record);
+}
+// ---- phase machine helpers --------------------------------------------------
+async function isPhaseDone(ctx, system, phase) {
+    const record = await loadPhase(ctx, system, phase);
+    return record?.status === "validated" || record?.status === "gate-approved";
+}
+async function isGateApproved(ctx, system, phase) {
+    const record = await loadPhase(ctx, system, phase);
+    return record?.gate?.decision === "approve";
+}
+async function blockers(ctx, system, phase) {
+    const spec = PHASES[phase];
+    const out = [];
+    for (const dep of spec.dependsOn) {
+        if (!(await isPhaseDone(ctx, system, dep)))
+            out.push(`${dep} not done`);
+    }
+    for (const gated of spec.requiresApprovedGate) {
+        if (!(await isGateApproved(ctx, system, gated)))
+            out.push(`${gated} gate not approved`);
+    }
+    return out;
+}
+function makeRunId(system, phase, baseSha, startedAt) {
+    const hash = createHash("sha256")
+        .update(`${system}|${phase}|${baseSha ?? ""}|${startedAt}`)
+        .digest("hex")
+        .slice(0, 8);
+    return `${system}-${phase}-${hash}`;
+}
+async function assemblePrompt(ctx, resolved, phase, module, vision) {
+    const legacyAbs = resolve(ctx.options.root, resolved.legacyPath);
+    const seeds = await runDetectors(legacyAbs, { maxFiles: MAX_SCAN_FILES });
+    return buildPrompt({ system: resolved.system, legacyPath: resolved.legacyPath, seeds, module, vision }, phase);
+}
+async function validateArtifactShape(abs, kind) {
+    if (kind === "dir")
+        return isDirectory(abs);
+    let content;
+    try {
+        content = await readFile(abs, "utf8");
+    }
+    catch {
+        return false;
+    }
+    if (content.trim().length === 0)
+        return false;
+    if (kind === "json") {
+        try {
+            JSON.parse(content);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+async function validateArtifacts(ctx, system, phase, module) {
+    const out = [];
+    for (const spec of PHASES[phase].artifacts) {
+        const rel = spec.path(system, module);
+        const abs = resolve(ctx.options.root, rel);
+        const present = await pathExists(abs);
+        const valid = present ? await validateArtifactShape(abs, spec.kind) : false;
+        out.push({ path: rel, kind: spec.kind, present, valid });
+    }
+    return out;
+}
+function allRequiredValid(phase, artifacts) {
+    return PHASES[phase].artifacts.every((spec, index) => !spec.required || (artifacts[index]?.valid ?? false));
+}
+// ---- commands ---------------------------------------------------------------
+export async function initCommand(ctx, flags) {
+    const system = requireStr(ctx.options.system ?? flagStr(flags, "system"), "system", "--system <name>");
+    const legacyPath = requireStr(flagStr(flags, "legacy"), "legacy", "--legacy <path>");
+    const force = flagBool(flags, "force");
+    const provider = ctx.options.provider ?? "codex";
+    if ((await pathExists(ctx.paths.config)) && !force) {
+        throw new ToolError("already initialized (use --force to overwrite config)", 2, "invalid-usage");
+    }
+    const config = { schemaVersion: 1, provider, model: ctx.options.model };
+    await writeJson(ctx.paths.config, config);
+    const baseSha = (await isGitRepo(ctx.options.root)) ? await headSha(ctx.options.root) : null;
+    const now = new Date().toISOString();
+    const project = (await pathExists(ctx.paths.project))
+        ? await readJson(ctx.paths.project, projectRecordSchema)
+        : { schemaVersion: 1, systems: [] };
+    const systems = project.systems.filter((s) => s.name !== system);
+    systems.push({ name: system, legacyPath, baseSha, createdAt: now });
+    await writeJson(ctx.paths.project, { schemaVersion: 1, systems });
+    return { stateDir: ctx.paths.stateDir, system, legacyPath, baseSha, provider };
+}
+export async function statusCommand(ctx, flags) {
+    const { system } = await resolveSystem(ctx, flags);
+    const phases = [];
+    for (const phase of PHASE_NAMES) {
+        const record = await loadPhase(ctx, system, phase);
+        phases.push({
+            phase,
+            mutating: PHASES[phase].mutating,
+            gated: PHASES[phase].gated,
+            status: record?.status ?? "pending",
+            gate: record?.gate?.decision ?? null,
+            artifacts: record?.artifacts ?? [],
+            blockedBy: await blockers(ctx, system, phase),
+        });
+    }
+    return { system, phases };
+}
+export async function nextCommand(ctx, flags) {
+    const resolved = await resolveSystem(ctx, flags);
+    const module = flagStr(flags, "module");
+    const vision = flagStr(flags, "vision");
+    for (const phase of PHASE_NAMES) {
+        const record = await loadPhase(ctx, resolved.system, phase);
+        const status = record?.status ?? "pending";
+        if (status === "validated" || status === "gate-approved")
+            continue;
+        if (PHASES[phase].gated && (status === "produced" || status === "gate-rejected")) {
+            return {
+                phase,
+                mutating: PHASES[phase].mutating,
+                blockedBy: [
+                    `awaiting human gate decision (legacymaxxing gate ${phase} --approve|--reject)`,
+                ],
+                prompt: null,
+            };
+        }
+        const blocked = await blockers(ctx, resolved.system, phase);
+        if (blocked.length > 0)
+            continue;
+        const prompt = await assemblePrompt(ctx, resolved, phase, module, vision);
+        return { phase, mutating: PHASES[phase].mutating, blockedBy: [], prompt };
+    }
+    return { phase: null, mutating: false, blockedBy: [], prompt: null, message: "all phases done" };
+}
+export async function runCommand(ctx, flags) {
+    const phase = parsePhaseArg(flags);
+    const resolved = await resolveSystem(ctx, flags);
+    const config = await readConfig(ctx);
+    const spec = PHASES[phase];
+    const blocked = await blockers(ctx, resolved.system, phase);
+    if (blocked.length > 0) {
+        throw new ToolError(`phase ${phase} blocked: ${blocked.join("; ")}`, 6, "validation-failed");
+    }
+    const module = flagStr(flags, "module");
+    const vision = flagStr(flags, "vision");
+    if (spec.needsModule && !module) {
+        throw new ToolError(`phase ${phase} requires --module <name>`, 2, "invalid-usage");
+    }
+    if (spec.needsVision && !vision) {
+        throw new ToolError(`phase ${phase} requires --vision <text>`, 2, "invalid-usage");
+    }
+    if (spec.mutating) {
+        if (!flagBool(flags, "apply") && !flagBool(flags, "yes")) {
+            throw new ToolError(`mutating phase ${phase} requires --apply`, 2, "invalid-usage");
+        }
+        await assertCleanWorktree(ctx.options.root, STATE_EXCLUDE);
+    }
+    const providerName = ctx.options.provider ?? config.provider;
+    const provider = providerByName(providerName);
+    const model = ctx.options.model ?? config.model;
+    const startedAt = new Date().toISOString();
+    const runId = makeRunId(resolved.system, phase, resolved.baseSha, startedAt);
+    const lock = lockPath(ctx.paths.stateDir, resolved.system, phase);
+    await claim(lock, runId);
+    try {
+        progress(ctx, `running ${phase} on ${resolved.system} via ${providerName}`);
+        const prompt = await assemblePrompt(ctx, resolved, phase, module, vision);
+        const raw = await provider.runPhase({
+            root: ctx.options.root,
+            system: resolved.system,
+            phase,
+            prompt,
+            mutating: spec.mutating,
+            module,
+            vision,
+            options: { model, noInput: ctx.options.noInput },
+        });
+        const { output, dropped } = partitionArtifacts(raw, `${phase} output`);
+        if (spec.mutating && resolved.baseSha) {
+            const head = await headSha(ctx.options.root);
+            if (head && head !== resolved.baseSha) {
+                progress(ctx, `note: HEAD moved since plan time (${resolved.baseSha} → ${head})`);
+            }
+        }
+        const artifacts = await validateArtifacts(ctx, resolved.system, phase, module);
+        const ok = allRequiredValid(phase, artifacts);
+        const status = ok ? (spec.gated ? "produced" : "validated") : "failed";
+        const now = new Date().toISOString();
+        const existing = await loadPhase(ctx, resolved.system, phase);
+        const record = {
+            schemaVersion: 1,
+            system: resolved.system,
+            phase,
+            status,
+            artifacts,
+            runId,
+            baseSha: resolved.baseSha,
+            gate: existing?.gate ?? null,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        };
+        await savePhase(ctx, record);
+        const run = {
+            schemaVersion: 1,
+            runId,
+            system: resolved.system,
+            phase,
+            provider: providerName,
+            model,
+            mutating: spec.mutating,
+            startedAt,
+            finishedAt: now,
+            status: ok ? "ok" : "failed",
+            droppedArtifacts: dropped,
+            summary: output.summary,
+        };
+        await writeJson(runRecordPath(ctx.paths.stateDir, runId), run);
+        if (!ok) {
+            throw new ToolError(`phase ${phase} produced incomplete artifacts: ${artifacts
+                .filter((a) => !a.valid)
+                .map((a) => a.path)
+                .join(", ")}`, 6, "validation-failed");
+        }
+        return { phase, status, system: resolved.system, artifacts, runId, dropped };
+    }
+    finally {
+        await release(lock);
+    }
+}
+export async function loopCommand(ctx, flags) {
+    const resolved = await resolveSystem(ctx, flags);
+    const until = flagStr(flags, "until");
+    const ran = [];
+    for (const phase of PHASE_NAMES) {
+        if (PHASES[phase].mutating)
+            break; // loop never runs a mutating phase
+        const record = await loadPhase(ctx, resolved.system, phase);
+        const status = record?.status ?? "pending";
+        if (status === "validated" || status === "gate-approved") {
+            if (until === phase)
+                break;
+            continue;
+        }
+        if (PHASES[phase].gated && (status === "produced" || status === "gate-rejected")) {
+            return { ran, blockedAt: phase, gate: "awaiting decision" };
+        }
+        const blocked = await blockers(ctx, resolved.system, phase);
+        if (blocked.length > 0)
+            return { ran, blockedAt: phase, blockedBy: blocked };
+        await runCommand(ctx, { phase, system: resolved.system });
+        ran.push(phase);
+        if (PHASES[phase].gated)
+            return { ran, blockedAt: phase, gate: "awaiting decision" };
+        if (until === phase)
+            break;
+    }
+    return { ran, blockedAt: null };
+}
+export async function gateCommand(ctx, flags) {
+    const phase = parsePhaseArg(flags);
+    if (!PHASES[phase].gated) {
+        throw new ToolError(`phase ${phase} has no gate`, 2, "invalid-usage");
+    }
+    const { system: sys } = await resolveSystem(ctx, flags);
+    const approve = flagBool(flags, "approve");
+    const reject = flagBool(flags, "reject");
+    if (approve === reject) {
+        throw new ToolError("gate requires exactly one of --approve | --reject", 2, "invalid-usage");
+    }
+    const record = await loadPhase(ctx, sys, phase);
+    if (!record)
+        throw new ToolError(`phase ${phase} has not been run yet`, 2, "invalid-usage");
+    if (!["produced", "gate-approved", "gate-rejected"].includes(record.status)) {
+        throw new ToolError(`phase ${phase} is not awaiting a gate (status: ${record.status})`, 6, "validation-failed");
+    }
+    const now = new Date().toISOString();
+    const decision = approve ? "approve" : "reject";
+    await savePhase(ctx, {
+        ...record,
+        status: approve ? "gate-approved" : "gate-rejected",
+        gate: { decision, note: flagStr(flags, "note"), decidedAt: now },
+        updatedAt: now,
+    });
+    return { phase, system: sys, decision, decidedAt: now };
+}
+export async function reportCommand(ctx, flags) {
+    const { system: sys } = await resolveSystem(ctx, flags);
+    const rows = [];
+    for (const phase of PHASE_NAMES) {
+        const record = await loadPhase(ctx, sys, phase);
+        rows.push({
+            phase,
+            status: record?.status ?? "pending",
+            gate: record?.gate?.decision ?? null,
+            artifacts: record?.artifacts ?? [],
+        });
+    }
+    return { system: sys, phases: rows, markdown: renderReport(sys, rows) };
+}
+export async function revalidateCommand(ctx, flags) {
+    const phase = parsePhaseArg(flags);
+    const { system: sys } = await resolveSystem(ctx, flags);
+    const record = await loadPhase(ctx, sys, phase);
+    if (!record)
+        throw new ToolError(`phase ${phase} has not been run yet`, 2, "invalid-usage");
+    const artifacts = [];
+    for (const artifact of record.artifacts) {
+        const abs = resolve(ctx.options.root, artifact.path);
+        const present = await pathExists(abs);
+        const valid = present ? await validateArtifactShape(abs, artifact.kind) : false;
+        artifacts.push({ path: artifact.path, kind: artifact.kind, present, valid });
+    }
+    const ok = allRequiredValid(phase, artifacts);
+    const status = ok
+        ? PHASES[phase].gated
+            ? record.gate?.decision === "approve"
+                ? "gate-approved"
+                : "produced"
+            : "validated"
+        : "failed";
+    await savePhase(ctx, { ...record, artifacts, status, updatedAt: new Date().toISOString() });
+    return { phase, system: sys, status, artifacts };
+}
+export async function doctorCommand(ctx, _flags) {
+    const checks = [];
+    let providerName = ctx.options.provider ?? "codex";
+    try {
+        providerName = ctx.options.provider ?? (await readConfig(ctx)).provider;
+    }
+    catch {
+        // not initialized yet — fall back to default/flag provider
+    }
+    try {
+        const detail = await providerByName(providerName).check(ctx.options.root);
+        checks.push({ name: `provider:${providerName}`, ok: true, detail });
+    }
+    catch (error) {
+        checks.push({ name: `provider:${providerName}`, ok: false, detail: errMessage(error) });
+    }
+    for (const tool of ["scc", "cloc", "lizard"]) {
+        const ok = await hasBinary(tool);
+        checks.push({ name: `tool:${tool}`, ok, detail: ok ? "present" : "missing (optional)" });
+    }
+    const stateOk = await pathExists(ctx.paths.config);
+    checks.push({ name: "state", ok: stateOk, detail: ctx.paths.stateDir });
+    const ready = checks
+        .filter((c) => c.name.startsWith("provider:") || c.name === "state")
+        .every((c) => c.ok);
+    return { ready, checks, markdown: renderDoctor(ready, checks) };
+}
+export async function cleanLocksCommand(ctx, _flags) {
+    const locks = await listLocks(ctx.paths.stateDir);
+    for (const name of locks) {
+        await release(resolve(ctx.paths.locks, name));
+    }
+    return { removed: locks.length, locks };
+}
+function renderReport(system, rows) {
+    const lines = [
+        `# legacymaxxing report — ${system}`,
+        "",
+        "| phase | status | gate | artifacts (valid/total) |",
+        "| --- | --- | --- | --- |",
+    ];
+    for (const row of rows) {
+        const valid = row.artifacts.filter((a) => a.valid).length;
+        lines.push(`| ${row.phase} | ${row.status} | ${row.gate ?? "-"} | ${valid}/${row.artifacts.length} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderDoctor(ready, checks) {
+    const lines = [`# legacymaxxing doctor — ${ready ? "ready" : "not ready"}`, ""];
+    for (const check of checks) {
+        lines.push(`- [${check.ok ? "x" : " "}] ${check.name}: ${check.detail}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+async function hasBinary(name) {
+    try {
+        await exec(name, ["--version"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,25 @@
+import { type StatePaths } from "./state.js";
+export type Flags = Record<string, string | boolean>;
+export type GlobalOptions = {
+    root: string;
+    stateDir: string;
+    config: string | null;
+    system: string | null;
+    provider: string | null;
+    model: string | null;
+    json: boolean;
+    plain: boolean;
+    quiet: boolean;
+    verbose: boolean;
+    debug: boolean;
+    noColor: boolean;
+    noInput: boolean;
+};
+export type Context = {
+    options: GlobalOptions;
+    paths: StatePaths;
+    isTty: boolean;
+};
+/** Precedence: flags > env (LEGACYMAXXING_*) > defaults. */
+export declare function resolveGlobalOptions(flags: Flags, env: NodeJS.ProcessEnv): GlobalOptions;
+export declare function makeContext(options: GlobalOptions): Context;

package/dist/context.js

@@ -0,0 +1,36 @@
+import { join, resolve } from "node:path";
+import { statePaths } from "./state.js";
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function asBool(value) {
+    return value === true || value === "true";
+}
+/** Precedence: flags > env (LEGACYMAXXING_*) > defaults. */
+export function resolveGlobalOptions(flags, env) {
+    const root = resolve(asString(flags["root"]) ?? env["LEGACYMAXXING_ROOT"] ?? process.cwd());
+    const stateDir = resolve(asString(flags["stateDir"]) ?? env["LEGACYMAXXING_STATE_DIR"] ?? join(root, ".legacymaxxing"));
+    return {
+        root,
+        stateDir,
+        config: asString(flags["config"]),
+        system: asString(flags["system"]),
+        provider: asString(flags["provider"]) ?? env["LEGACYMAXXING_PROVIDER"] ?? null,
+        model: asString(flags["model"]) ?? env["LEGACYMAXXING_MODEL"] ?? null,
+        json: asBool(flags["json"]),
+        plain: asBool(flags["plain"]),
+        quiet: asBool(flags["quiet"]),
+        verbose: asBool(flags["verbose"]),
+        debug: asBool(flags["debug"]),
+        noColor: asBool(flags["noColor"]),
+        noInput: asBool(flags["noInput"]),
+    };
+}
+export function makeContext(options) {
+    const paths = statePaths(options.stateDir);
+    return {
+        options,
+        paths: options.config ? { ...paths, config: resolve(options.config) } : paths,
+        isTty: Boolean(process.stdout.isTTY),
+    };
+}

package/dist/detectors/extension.d.ts

@@ -0,0 +1,3 @@
+import type { StackDetector } from "./types.js";
+/** Cheapest possible language signal: count files by extension. */
+export declare const extensionDetector: StackDetector;

package/dist/detectors/extension.js

@@ -0,0 +1,72 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+const EXT_LANG = {
+    ".cbl": "cobol",
+    ".cob": "cobol",
+    ".cpy": "cobol",
+    ".java": "java",
+    ".jsp": "java",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".ts": "typescript",
+    ".py": "python",
+    ".rb": "ruby",
+    ".php": "php",
+    ".go": "go",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".cs": "csharp",
+    ".pl": "perl",
+    ".pas": "pascal",
+    ".f": "fortran",
+    ".for": "fortran",
+};
+async function walk(dir, budget, out) {
+    if (budget.left <= 0)
+        return;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (budget.left <= 0)
+            return;
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(full, budget, out);
+        }
+        else {
+            out.push(entry.name);
+            budget.left -= 1;
+        }
+    }
+}
+/** Cheapest possible language signal: count files by extension. */
+export const extensionDetector = {
+    name: "extension",
+    detect: async (root, ctx) => {
+        const files = [];
+        await walk(root, { left: ctx.maxFiles }, files);
+        const counts = new Map();
+        for (const file of files) {
+            const dot = file.lastIndexOf(".");
+            if (dot < 0)
+                continue;
+            const language = EXT_LANG[file.slice(dot).toLowerCase()];
+            if (!language)
+                continue;
+            counts.set(language, (counts.get(language) ?? 0) + 1);
+        }
+        return [...counts.entries()].map(([language, n]) => ({
+            language,
+            files: n,
+            markers: ["extension"],
+        }));
+    },
+};

package/dist/detectors/index.d.ts

@@ -0,0 +1,5 @@
+import type { DetectCtx, StackDetector, StackSeed } from "./types.js";
+/** Register breadth here. Each detector runs in parallel; seeds are deduped by language. */
+export declare const detectors: StackDetector[];
+export declare function dedupeSeeds(seeds: StackSeed[]): StackSeed[];
+export declare function runDetectors(root: string, ctx: DetectCtx): Promise<StackSeed[]>;

package/dist/detectors/index.js

@@ -0,0 +1,28 @@
+import { extensionDetector } from "./extension.js";
+/** Register breadth here. Each detector runs in parallel; seeds are deduped by language. */
+export const detectors = [extensionDetector];
+export function dedupeSeeds(seeds) {
+    const byLanguage = new Map();
+    for (const seed of seeds) {
+        const existing = byLanguage.get(seed.language);
+        if (existing) {
+            existing.files += seed.files;
+            for (const marker of seed.markers) {
+                if (!existing.markers.includes(marker))
+                    existing.markers.push(marker);
+            }
+        }
+        else {
+            byLanguage.set(seed.language, {
+                language: seed.language,
+                files: seed.files,
+                markers: [...seed.markers],
+            });
+        }
+    }
+    return [...byLanguage.values()].toSorted((a, b) => b.files - a.files || a.language.localeCompare(b.language));
+}
+export async function runDetectors(root, ctx) {
+    const all = (await Promise.all(detectors.map((detector) => detector.detect(root, ctx)))).flat();
+    return dedupeSeeds(all);
+}

package/dist/detectors/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The breadth axis for the swarm. A StackDetector contributes deterministic
+ * "what languages/stacks are in this legacy tree" seeds to the phase prompts —
+ * no network, no model. Adding COBOL/Java specificity is one new file + one
+ * array entry in index.ts; the core never changes.
+ */
+export type StackSeed = {
+    language: string;
+    files: number;
+    markers: string[];
+};
+export type DetectCtx = {
+    /** Cap the walk so a huge legacy tree can't stall the deterministic pre-step. */
+    maxFiles: number;
+};
+export type StackDetector = {
+    name: string;
+    detect(root: string, ctx: DetectCtx): Promise<StackSeed[]>;
+};

package/dist/detectors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed error: a stable string `code` (asserted in tests) plus a numeric
+ * `exitCode` (what the OS sees). Conversion to a process exit happens ONLY at the
+ * top-level catch in cli.ts. Reserved exit codes:
+ *   1 runtime · 2 invalid usage/preconditions · 3 dirty worktree ·
+ *   4 provider auth/config · 5 provider quota · 6 validation/gate failed ·
+ *   7 lock conflict / external-CLI failure · 8 malformed model output.
+ */
+export declare class ToolError extends Error {
+    readonly exitCode: number;
+    readonly code: string;
+    constructor(message: string, exitCode?: number, code?: string);
+}
+export declare function errMessage(error: unknown): string;