@lsctech/polaris 0.1.0

package/dist/cli/graph.js

@@ -0,0 +1,358 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGraphCommand = createGraphCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const commander_1 = require("commander");
+const loader_js_1 = require("../config/loader.js");
+const pipeline_js_1 = require("../graph/parser/pipeline.js");
+const index_js_1 = require("../graph/query/index.js");
+const index_js_2 = require("../graph/resolver/index.js");
+const adapter_js_1 = require("../graph/store/adapter.js");
+function createGraphCommand(options) {
+    const graphCommand = new commander_1.Command("graph")
+        .description("Build and inspect the repository function graph")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    graphCommand.action(() => failMissingSubcommand(graphCommand, "polaris graph"));
+    graphCommand
+        .command("build")
+        .description("Build graph artifacts from configured source roots")
+        .option("-r, --repo-root <path>", "Repository root", options.repoRoot)
+        .option("--dry-run", "Print the build plan and skip writes")
+        .option("--json", "Emit JSON output")
+        .action(async (commandOptions) => {
+        const repoRoot = (0, node_path_1.resolve)(commandOptions.repoRoot ?? options.repoRoot);
+        const dryRun = commandOptions.dryRun ?? false;
+        const json = commandOptions.json ?? false;
+        const plan = createBuildPlan(repoRoot);
+        if (dryRun) {
+            const output = {
+                mode: "dry-run",
+                ...plan,
+            };
+            if (json) {
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                printBuildPlan(output);
+            }
+            return;
+        }
+        const store = new adapter_js_1.GraphStoreAdapter({
+            repoRoot,
+            graphOutputPath: plan.outputPathRelative,
+            dbPath: plan.dbPathRelative,
+        });
+        try {
+            store.open();
+            const extraction = await (0, pipeline_js_1.runExtractionPipeline)(plan.sourceFiles, {
+                graphStore: store,
+                logger: { warn: (message) => process.stderr.write(`${message}\n`) },
+            });
+            const resolver = (0, index_js_2.runGraphResolver)({ graphStore: store });
+            const output = {
+                mode: "build",
+                outputPath: plan.outputPathAbsolute,
+                dbPath: plan.dbPathAbsolute,
+                sourceRoots: plan.sourceRootsAbsolute,
+                sourceFileCount: plan.sourceFiles.length,
+                extraction,
+                resolver,
+            };
+            if (json) {
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                printBuildSummary(output);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`graph build failed: ${message}\n`);
+            process.exit(1);
+        }
+        finally {
+            store.close();
+        }
+    });
+    graphCommand
+        .command("query <symbol>")
+        .description("Lookup a symbol and print callers/callees")
+        .option("-r, --repo-root <path>", "Repository root", options.repoRoot)
+        .option("--file <path>", "Optional file path filter for symbol lookup")
+        .option("--json", "Emit JSON output")
+        .option("--dry-run", "Print the query plan and skip execution")
+        .action((symbol, commandOptions) => {
+        const repoRoot = (0, node_path_1.resolve)(commandOptions.repoRoot ?? options.repoRoot);
+        const plan = createBuildPlan(repoRoot);
+        const fileFilter = commandOptions.file ? (0, node_path_1.resolve)(repoRoot, commandOptions.file) : undefined;
+        const json = commandOptions.json ?? false;
+        const dryRun = commandOptions.dryRun ?? false;
+        if (dryRun) {
+            const output = {
+                mode: "dry-run",
+                command: "query",
+                symbol,
+                file: fileFilter ?? null,
+                outputPath: plan.outputPathAbsolute,
+                dbPath: plan.dbPathAbsolute,
+            };
+            if (json) {
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                printDryRunPlan(output);
+            }
+            return;
+        }
+        const store = new adapter_js_1.GraphStoreAdapter({
+            repoRoot,
+            graphOutputPath: plan.outputPathRelative,
+            dbPath: plan.dbPathRelative,
+        });
+        try {
+            store.open();
+            (0, index_js_1.configureGraphQuery)({ graphStore: store });
+            const target = (0, index_js_1.lookupSymbol)(symbol, fileFilter);
+            if (!target) {
+                process.stderr.write(`symbol not found: ${symbol}\n`);
+                process.exit(1);
+            }
+            const output = {
+                symbol: target,
+                callers: (0, index_js_1.getCallers)(target.id),
+                callees: (0, index_js_1.getCallees)(target.id),
+                outputPath: plan.outputPathAbsolute,
+                dbPath: plan.dbPathAbsolute,
+            };
+            if (json) {
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                printQueryTable(output.symbol, output.callers, output.callees);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`graph query failed: ${message}\n`);
+            process.exit(1);
+        }
+        finally {
+            (0, index_js_1.configureGraphQuery)({ graphStore: null });
+            store.close();
+        }
+    });
+    graphCommand
+        .command("impact <symbol>")
+        .description("Compute transitively impacted files for a symbol")
+        .option("-r, --repo-root <path>", "Repository root", options.repoRoot)
+        .option("--file <path>", "Optional file path filter for symbol lookup")
+        .option("--json", "Emit JSON output")
+        .option("--dry-run", "Print the impact plan and skip execution")
+        .action((symbol, commandOptions) => {
+        const repoRoot = (0, node_path_1.resolve)(commandOptions.repoRoot ?? options.repoRoot);
+        const plan = createBuildPlan(repoRoot);
+        const fileFilter = commandOptions.file ? (0, node_path_1.resolve)(repoRoot, commandOptions.file) : undefined;
+        const json = commandOptions.json ?? false;
+        const dryRun = commandOptions.dryRun ?? false;
+        if (dryRun) {
+            const output = {
+                mode: "dry-run",
+                command: "impact",
+                symbol,
+                file: fileFilter ?? null,
+                outputPath: plan.outputPathAbsolute,
+                dbPath: plan.dbPathAbsolute,
+            };
+            if (json) {
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                printDryRunPlan(output);
+            }
+            return;
+        }
+        const store = new adapter_js_1.GraphStoreAdapter({
+            repoRoot,
+            graphOutputPath: plan.outputPathRelative,
+            dbPath: plan.dbPathRelative,
+        });
+        try {
+            store.open();
+            (0, index_js_1.configureGraphQuery)({ graphStore: store });
+            const target = (0, index_js_1.lookupSymbol)(symbol, fileFilter);
+            if (!target) {
+                process.stderr.write(`symbol not found: ${symbol}\n`);
+                process.exit(1);
+            }
+            const files = (0, index_js_1.getImpactedFiles)(target.id);
+            const output = {
+                symbol: target,
+                impactedFiles: files,
+                outputPath: plan.outputPathAbsolute,
+                dbPath: plan.dbPathAbsolute,
+            };
+            if (json) {
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                printImpactTable(output.symbol, output.impactedFiles);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`graph impact failed: ${message}\n`);
+            process.exit(1);
+        }
+        finally {
+            (0, index_js_1.configureGraphQuery)({ graphStore: null });
+            store.close();
+        }
+    });
+    return graphCommand;
+}
+function createBuildPlan(repoRoot) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPathRelative = config.graph.outputPath ?? ".polaris/graph";
+    const outputPathAbsolute = (0, node_path_1.resolve)(repoRoot, outputPathRelative);
+    const dbPathRelative = (0, node_path_1.join)(outputPathRelative, "graph.sqlite");
+    const dbPathAbsolute = (0, node_path_1.resolve)(repoRoot, dbPathRelative);
+    const sourceRoots = (config.repo.sourceRoots ?? ["src"])
+        .filter((root) => typeof root === "string" && root.length > 0)
+        .map((root) => (0, node_path_1.resolve)(repoRoot, root));
+    const sourceFiles = collectSourceFiles(sourceRoots);
+    return {
+        outputPathRelative,
+        outputPathAbsolute,
+        dbPathRelative,
+        dbPathAbsolute,
+        sourceRootsAbsolute: sourceRoots,
+        sourceFiles,
+    };
+}
+function collectSourceFiles(sourceRoots) {
+    const files = [];
+    for (const root of sourceRoots) {
+        if (!(0, node_fs_1.existsSync)(root)) {
+            continue;
+        }
+        for (const filePath of walkDirectory(root)) {
+            files.push(filePath);
+        }
+    }
+    return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));
+}
+function* walkDirectory(root, visited = new Set()) {
+    const realRoot = (0, node_fs_1.realpathSync)(root);
+    if (visited.has(realRoot))
+        return;
+    visited.add(realRoot);
+    const entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = (0, node_path_1.join)(root, entry.name);
+        if (entry.isDirectory()) {
+            yield* walkDirectory(fullPath, visited);
+            continue;
+        }
+        yield fullPath;
+    }
+}
+function failMissingSubcommand(command, commandName) {
+    const unknownSubcommand = command.args[0];
+    const message = unknownSubcommand
+        ? `error: unknown command '${unknownSubcommand}' for '${commandName}'. Run '${commandName} --help'.`
+        : `error: missing command for '${commandName}'. Run '${commandName} --help'.`;
+    command.error(message, {
+        code: "commander.missingCommand",
+        exitCode: 1,
+    });
+}
+function printBuildPlan(plan) {
+    console.log("graph build plan (dry-run)");
+    console.log(`output path: ${plan.outputPathAbsolute}`);
+    console.log(`db path: ${plan.dbPathAbsolute}`);
+    console.log(`source roots: ${plan.sourceRootsAbsolute.length}`);
+    for (const root of plan.sourceRootsAbsolute) {
+        console.log(`  - ${root}`);
+    }
+    console.log(`source files: ${plan.sourceFiles.length}`);
+}
+function printBuildSummary(output) {
+    console.log("graph build complete");
+    console.log(`output path: ${output.outputPath}`);
+    console.log(`db path: ${output.dbPath}`);
+    console.log(`source roots: ${output.sourceRoots.length}`);
+    console.log(`source files: ${output.sourceFileCount}`);
+    console.log(`extraction: processed=${output.extraction.processedFiles} succeeded=${output.extraction.succeededFiles} failed=${output.extraction.failedFiles}`);
+    console.log(`resolver: imports=${output.resolver.importsEdges} calls=${output.resolver.callsEdges} defined-in=${output.resolver.definedInEdges} unresolved-imports=${output.resolver.unresolvedImports} unresolved-calls=${output.resolver.unresolvedCalls}`);
+    printCapabilityReport(output.extraction.capability);
+}
+function printCapabilityReport(report) {
+    const rows = Object.entries(report.coverage).sort(([left], [right]) => left.localeCompare(right));
+    const languageWidth = Math.max("Language".length, ...rows.map(([language]) => language.length));
+    const filesWidth = Math.max("Files".length, ...rows.map(([, entry]) => String(entry.filesDiscovered).length), String(rows.reduce((total, [, entry]) => total + entry.filesDiscovered, 0)).length);
+    const symbolWidth = Math.max("Symbol-Level".length, ...rows.map(([, entry]) => String(entry.filesSymbolLevel).length), String(rows.reduce((total, [, entry]) => total + entry.filesSymbolLevel, 0)).length);
+    const fileWidth = Math.max("File-Level".length, ...rows.map(([, entry]) => String(entry.filesFileLevel).length), String(rows.reduce((total, [, entry]) => total + entry.filesFileLevel, 0)).length);
+    const failedWidth = Math.max("Failed".length, ...rows.map(([, entry]) => String(entry.filesFailed).length), String(rows.reduce((total, [, entry]) => total + entry.filesFailed, 0)).length);
+    const totalFiles = rows.reduce((total, [, entry]) => total + entry.filesDiscovered, 0);
+    const totalSymbolLevel = rows.reduce((total, [, entry]) => total + entry.filesSymbolLevel, 0);
+    const totalFileLevel = rows.reduce((total, [, entry]) => total + entry.filesFileLevel, 0);
+    const totalFailed = rows.reduce((total, [, entry]) => total + entry.filesFailed, 0);
+    console.log("");
+    console.log("Graph Build - Coverage Report");
+    console.log("-".repeat(languageWidth + filesWidth + symbolWidth + fileWidth + failedWidth + 16));
+    console.log(`${"Language".padEnd(languageWidth)}  ${"Files".padStart(filesWidth)}  ${"Symbol-Level".padStart(symbolWidth)}  ${"File-Level".padStart(fileWidth)}  ${"Failed".padStart(failedWidth)}`);
+    for (const [language, entry] of rows) {
+        console.log(`${language.padEnd(languageWidth)}  ${String(entry.filesDiscovered).padStart(filesWidth)}  ${String(entry.filesSymbolLevel).padStart(symbolWidth)}  ${String(entry.filesFileLevel).padStart(fileWidth)}  ${String(entry.filesFailed).padStart(failedWidth)}`);
+    }
+    console.log("-".repeat(languageWidth + filesWidth + symbolWidth + fileWidth + failedWidth + 16));
+    console.log(`${"Total".padEnd(languageWidth)}  ${String(totalFiles).padStart(filesWidth)}  ${String(totalSymbolLevel).padStart(symbolWidth)}  ${String(totalFileLevel).padStart(fileWidth)}  ${String(totalFailed).padStart(failedWidth)}`);
+    console.log(`Symbol-level coverage: ${report.symbolLevelPercent.toFixed(1)}%`);
+    console.log(`Total file coverage: ${report.totalCoveragePercent.toFixed(1)}%`);
+}
+function printDryRunPlan(plan) {
+    console.log(`graph ${plan.command} plan (dry-run)`);
+    console.log(`symbol: ${plan.symbol}`);
+    if (plan.file) {
+        console.log(`file filter: ${plan.file}`);
+    }
+    console.log(`output path: ${plan.outputPath}`);
+    console.log(`db path: ${plan.dbPath}`);
+}
+function printQueryTable(symbol, callers, callees) {
+    console.log(`symbol: ${symbol.name} (${symbol.kind})`);
+    console.log(`id: ${symbol.id}`);
+    console.log(`file: ${symbol.filePath}`);
+    if (symbol.signature) {
+        console.log(`signature: ${symbol.signature}`);
+    }
+    console.log("");
+    printSymbolRows("callers", callers);
+    console.log("");
+    printSymbolRows("callees", callees);
+}
+function printImpactTable(symbol, impactedFiles) {
+    console.log(`symbol: ${symbol.name} (${symbol.kind})`);
+    console.log(`id: ${symbol.id}`);
+    console.log(`file: ${symbol.filePath}`);
+    console.log("");
+    console.log(`impacted files (${impactedFiles.length})`);
+    if (impactedFiles.length === 0) {
+        console.log("  none");
+        return;
+    }
+    for (const file of impactedFiles) {
+        console.log(`  ${file.path} (${file.language})`);
+    }
+}
+function printSymbolRows(title, symbols) {
+    console.log(`${title} (${symbols.length})`);
+    if (symbols.length === 0) {
+        console.log("  none");
+        return;
+    }
+    for (const symbol of symbols) {
+        console.log(`  ${symbol.name.padEnd(24)} ${symbol.kind.padEnd(10)} ${symbol.filePath}`);
+    }
+}

package/dist/cli/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPolarisCommand = createPolarisCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const commander_1 = require("commander");
+const version_js_1 = require("./version.js");
+const branding_js_1 = require("./branding.js");
+const index_js_1 = require("../loop/index.js");
+const status_js_1 = require("../loop/status.js");
+const index_js_2 = require("../map/index.js");
+const index_js_3 = require("../finalize/index.js");
+const index_js_4 = require("../finalize/index.js");
+const index_js_5 = require("../runs/index.js");
+const init_js_1 = require("./init.js");
+const index_js_6 = require("../smartdocs-engine/index.js");
+const show_js_1 = require("../config/show.js");
+const cli_subtask_bridge_js_1 = require("../loop/adapters/cli-subtask-bridge.js");
+const finalize_evidence_js_1 = require("../loop/finalize-evidence.js");
+const tracker_js_1 = require("./tracker.js");
+const worker_js_1 = require("./worker.js");
+const graph_js_1 = require("./graph.js");
+const index_js_7 = require("../skill-packet/index.js");
+const librarian_js_1 = require("./librarian.js");
+const medic_js_1 = require("./medic.js");
+const welfare_js_1 = require("../map/welfare.js");
+function resolveStateFile(repoRoot, explicit) {
+    if (explicit)
+        return (0, node_path_1.resolve)(explicit);
+    const taskchainPath = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+    const polarisPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "current-state.json");
+    if ((0, node_fs_1.existsSync)(taskchainPath))
+        return taskchainPath;
+    if ((0, node_fs_1.existsSync)(polarisPath))
+        return polarisPath;
+    return taskchainPath;
+}
+function createPolarisCommand(options = {}) {
+    const repoRoot = options.repoRoot ?? (0, node_path_1.resolve)(process.cwd());
+    (0, cli_subtask_bridge_js_1.installCliSubtaskBridge)(repoRoot);
+    const statusHandler = options.runLoopStatus ?? status_js_1.runLoopStatus;
+    const finalizeHandler = options.runFinalize ?? (async (finalizeOptions) => {
+        (0, finalize_evidence_js_1.assertFinalizeEvidenceOrThrow)(finalizeOptions.repoRoot, finalizeOptions.stateFile);
+        await (0, index_js_4.runFinalize)(finalizeOptions);
+    });
+    const program = new commander_1.Command("polaris")
+        .description("Polaris taskchain operator CLI")
+        .version((0, version_js_1.getVersion)())
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    program.addHelpText("before", (0, branding_js_1.getBanner)());
+    program
+        .command("status")
+        .description("safe/read-only: print current loop run state summary")
+        .option("--state-file <path>", "Override path to current-state.json")
+        .option("--json", "Emit JSON output instead of human-readable text")
+        .action((commandOptions) => {
+        statusHandler({
+            repoRoot,
+            stateFile: resolveStateFile(repoRoot, commandOptions.stateFile),
+            json: commandOptions.json,
+        });
+    });
+    program.addCommand((0, index_js_1.createLoopCommand)({
+        repoRoot,
+        runLoopStatus: statusHandler,
+        runLoopContinue: options.runLoopContinue,
+    }));
+    program.addCommand((0, index_js_2.createMapCommand)({
+        repoRoot,
+        runMapQuery: options.runMapQuery,
+    }));
+    program.addCommand((0, index_js_3.createFinalizeCommand)({
+        repoRoot,
+        runFinalize: finalizeHandler,
+    }));
+    program.addCommand((0, index_js_5.createRunsCommand)({ repoRoot }));
+    program.addCommand((0, init_js_1.createInitCommand)({
+        repoRoot,
+        detectProviders: undefined,
+    }));
+    program.addCommand((0, index_js_6.createDocsCommand)({ repoRoot }));
+    program.addCommand((0, index_js_6.createDoctrineCommand)());
+    program.addCommand((0, show_js_1.createConfigCommand)({
+        repoRoot,
+        runConfigShow: options.runConfigShow,
+        runConfigDoctor: options.runConfigDoctor,
+    }));
+    program.addCommand((0, tracker_js_1.createTrackerCommand)({
+        repoRoot,
+    }));
+    program.addCommand((0, worker_js_1.createWorkerCommand)({
+        repoRoot,
+    }));
+    program.addCommand((0, graph_js_1.createGraphCommand)({
+        repoRoot,
+    }));
+    program.addCommand((0, index_js_7.createSkillCommand)({
+        repoRoot,
+    }));
+    program.addCommand((0, librarian_js_1.createLibrarianCommand)({
+        repoRoot,
+    }));
+    program.addCommand((0, medic_js_1.createMedicCommand)({
+        repoRoot,
+    }));
+    program
+        .command("welfare-check")
+        .description("safe/read-only: run route welfare checks and report per-route health")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--route <path>", "Scope to a single route domain")
+        .action((options) => {
+        const report = (0, welfare_js_1.runWelfareCheck)(options.repoRoot, options.route);
+        (0, welfare_js_1.printWelfareCheckReport)(report);
+        if (report.needsReview > 0) {
+            process.exit(1);
+        }
+    });
+    return program;
+}
+if (require.main === module) {
+    createPolarisCommand().parseAsync(process.argv).catch((err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/cli/index.test.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_path_1 = require("node:path");
+const index_js_1 = require("./index.js");
+function configureForTest(program, output) {
+    program.exitOverride();
+    program.configureOutput({
+        writeOut: (value) => {
+            output.stdout += value;
+        },
+        writeErr: (value) => {
+            output.stderr += value;
+        },
+    });
+    for (const command of program.commands) {
+        configureForTest(command, output);
+    }
+}
+async function runCommand(argv) {
+    const output = { stdout: "", stderr: "" };
+    let exitCode = 0;
+    const status = vitest_1.vi.fn();
+    const continueLoop = vitest_1.vi.fn();
+    const queryMap = vitest_1.vi.fn();
+    const finalize = vitest_1.vi.fn();
+    const configShow = vitest_1.vi.fn();
+    const program = (0, index_js_1.createPolarisCommand)({
+        repoRoot: "/repo",
+        runLoopStatus: status,
+        runLoopContinue: continueLoop,
+        runMapQuery: queryMap,
+        runFinalize: finalize,
+        runConfigShow: configShow,
+    });
+    configureForTest(program, output);
+    try {
+        await program.parseAsync(["node", "polaris", ...argv], { from: "node" });
+    }
+    catch (error) {
+        if (error instanceof Error && "exitCode" in error) {
+            exitCode = Number(error.exitCode);
+        }
+        else {
+            throw error;
+        }
+    }
+    return { ...output, exitCode, status, continueLoop, queryMap, finalize, configShow };
+}
+(0, vitest_1.describe)("polaris public CLI", () => {
+    (0, vitest_1.it)("prints root help through Commander", async () => {
+        const result = await runCommand(["--help"]);
+        (0, vitest_1.expect)(result.stdout).toContain("Usage: polaris");
+        (0, vitest_1.expect)(result.stdout).toContain("status");
+        (0, vitest_1.expect)(result.stdout).toContain("loop");
+        (0, vitest_1.expect)(result.stdout).toContain("map");
+        (0, vitest_1.expect)(result.stdout).toContain("finalize");
+        (0, vitest_1.expect)(result.stdout).toContain("docs");
+        (0, vitest_1.expect)(result.stdout).toContain("doctrine");
+        (0, vitest_1.expect)(result.stdout).toContain("safe/read-only");
+        (0, vitest_1.expect)(result.stdout).toContain("config");
+    });
+    (0, vitest_1.it)("exposes docs ingest command with expected flags", async () => {
+        const result = await runCommand(["docs", "ingest", "--help"]);
+        (0, vitest_1.expect)(result.exitCode).toBe(0);
+        (0, vitest_1.expect)(result.stdout).toContain("Usage: polaris docs ingest");
+        (0, vitest_1.expect)(result.stdout).toContain("--file");
+        (0, vitest_1.expect)(result.stdout).toContain("--batch");
+        (0, vitest_1.expect)(result.stdout).toContain("--dry-run");
+        (0, vitest_1.expect)(result.stdout).toContain("smartdocs/docs");
+    });
+    vitest_1.it.each(["draft", "promote", "deprecate"])("exposes doctrine %s command through the public entrypoint", async (subcommand) => {
+        const result = await runCommand(["doctrine", subcommand, "--help"]);
+        (0, vitest_1.expect)(result.exitCode).toBe(0);
+        (0, vitest_1.expect)(result.stderr).not.toContain("unknown command");
+        (0, vitest_1.expect)(result.stdout).toContain(`Usage: polaris doctrine ${subcommand}`);
+    });
+    (0, vitest_1.it)("prints the package version", async () => {
+        const result = await runCommand(["--version"]);
+        (0, vitest_1.expect)(result.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+    });
+    (0, vitest_1.it)("keeps status as a top-level alias for loop status", async () => {
+        const result = await runCommand(["status", "--json"]);
+        (0, vitest_1.expect)(result.status).toHaveBeenCalledWith({
+            repoRoot: "/repo",
+            stateFile: (0, node_path_1.join)("/repo", ".taskchain_artifacts", "polaris-run", "current-state.json"),
+            json: true,
+        });
+    });
+    (0, vitest_1.it)("routes loop status through the loop command", async () => {
+        const result = await runCommand(["loop", "status", "--json"]);
+        (0, vitest_1.expect)(result.status).toHaveBeenCalledWith({
+            repoRoot: "/repo",
+            stateFile: (0, node_path_1.join)("/repo", ".taskchain_artifacts", "polaris-run", "current-state.json"),
+            json: true,
+        });
+    });
+    (0, vitest_1.it)("routes map query through the public entrypoint", async () => {
+        const result = await runCommand(["map", "query", "src/cli/index.ts"]);
+        (0, vitest_1.expect)(result.queryMap).toHaveBeenCalledWith("/repo", "src/cli/index.ts", undefined, undefined, false, false);
+    });
+    (0, vitest_1.it)("exposes finalize run help", async () => {
+        const result = await runCommand(["finalize", "run", "--help"]);
+        (0, vitest_1.expect)(result.stdout).toContain("Usage: polaris finalize run");
+        (0, vitest_1.expect)(result.stdout).toContain("--dry-run");
+        (0, vitest_1.expect)(result.stdout).toContain("--skip-delivery");
+    });
+    (0, vitest_1.it)("prints config help without failing", async () => {
+        const result = await runCommand(["config"]);
+        (0, vitest_1.expect)(result.exitCode).toBe(0);
+        (0, vitest_1.expect)(result.stdout).toContain("Usage: polaris config");
+        (0, vitest_1.expect)(result.stdout).toContain("show");
+        (0, vitest_1.expect)(result.stderr).not.toContain("deferred");
+    });
+    (0, vitest_1.it)("routes config show through the public entrypoint", async () => {
+        const result = await runCommand(["config", "show"]);
+        (0, vitest_1.expect)(result.exitCode).toBe(0);
+        (0, vitest_1.expect)(result.configShow).toHaveBeenCalledWith({
+            repoRoot: "/repo",
+        });
+    });
+    (0, vitest_1.it)("marks safe previews and mutating commands in subsystem help", async () => {
+        const loop = await runCommand(["loop", "--help"]);
+        const map = await runCommand(["map", "--help"]);
+        const finalize = await runCommand(["finalize", "--help"]);
+        (0, vitest_1.expect)(loop.exitCode).toBe(0);
+        (0, vitest_1.expect)(loop.stdout).toContain("status");
+        (0, vitest_1.expect)(loop.stdout).toContain("safe/read-only");
+        (0, vitest_1.expect)(loop.stdout).toContain("continue");
+        (0, vitest_1.expect)(loop.stdout).toContain("mutating");
+        (0, vitest_1.expect)(loop.stdout).toContain("not a smoke test");
+        (0, vitest_1.expect)(map.exitCode).toBe(0);
+        (0, vitest_1.expect)(map.stdout).toContain("--dry-run");
+        (0, vitest_1.expect)(map.stdout).toContain("non-mutating preview");
+        (0, vitest_1.expect)(finalize.exitCode).toBe(0);
+        (0, vitest_1.expect)(finalize.stdout).toContain("manual/operator-triggered");
+        (0, vitest_1.expect)(finalize.stdout).toContain("performs delivery");
+        (0, vitest_1.expect)(finalize.stdout).toContain("--dry-run");
+        (0, vitest_1.expect)(finalize.stdout).toContain("--skip-delivery");
+    });
+    (0, vitest_1.it)("fails unknown commands with actionable help", async () => {
+        const result = await runCommand(["not-a-command"]);
+        (0, vitest_1.expect)(result.exitCode).toBeGreaterThan(0);
+        (0, vitest_1.expect)(result.stderr).toContain("unknown command");
+        (0, vitest_1.expect)(result.stderr).toContain("Usage: polaris");
+        (0, vitest_1.expect)(result.stderr).toContain("Commands:");
+    });
+    (0, vitest_1.it)("fails missing subsystem subcommands with actionable help", async () => {
+        const result = await runCommand(["loop"]);
+        (0, vitest_1.expect)(result.exitCode).toBeGreaterThan(0);
+        (0, vitest_1.expect)(result.stderr).toContain("missing command");
+        (0, vitest_1.expect)(result.stderr).toContain("Usage: polaris loop");
+        (0, vitest_1.expect)(result.stderr).toContain("Commands:");
+    });
+    (0, vitest_1.it)("fails unknown subsystem subcommands with actionable help", async () => {
+        const result = await runCommand(["loop", "not-a-subcommand"]);
+        (0, vitest_1.expect)(result.exitCode).toBeGreaterThan(0);
+        (0, vitest_1.expect)(result.stderr).toContain("unknown command 'not-a-subcommand'");
+        (0, vitest_1.expect)(result.stderr).toContain("Usage: polaris loop");
+        (0, vitest_1.expect)(result.stderr).toContain("Commands:");
+    });
+});