@lsctech/polaris 0.3.29 → 0.4.0

package/dist/cli/setup-interview/generate.js

@@ -0,0 +1,380 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSetupArtifacts = generateSetupArtifacts;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const adopt_approve_js_1 = require("../adopt-approve.js");
+const adopt_rules_js_1 = require("../adopt-rules.js");
+const adopt_smartdocs_js_1 = require("../adopt-smartdocs.js");
+const adopt_workspace_js_1 = require("../adopt-workspace.js");
+const index_js_1 = require("../../map/index.js");
+const store_js_1 = require("./store.js");
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function buildSetupConfig(existing, record, detectedProviders, detectedRepoAnalysis) {
+    const updated = {
+        ...existing,
+        version: typeof existing.version === "string" ? existing.version : "1.0",
+    };
+    const providers = {};
+    const existingProviders = asRecord(existing.providers);
+    if (detectedProviders.length > 0) {
+        providers.compactionProviders = detectedProviders;
+    }
+    else if (existingProviders.compactionProviders) {
+        providers.compactionProviders = existingProviders.compactionProviders;
+    }
+    if (detectedRepoAnalysis.length > 0) {
+        const existingRepoAnalysis = asRecord(existingProviders.repoAnalysis);
+        providers.repoAnalysis = { ...existingRepoAnalysis, preferred: detectedRepoAnalysis[0] };
+    }
+    else if (existingProviders.repoAnalysis) {
+        providers.repoAnalysis = existingProviders.repoAnalysis;
+    }
+    if (Object.keys(providers).length > 0) {
+        updated.providers = { ...existingProviders, ...providers };
+    }
+    const existingRepo = asRecord(existing.repo);
+    updated.repo = {
+        ...existingRepo,
+        sourceRoots: record.answers.source_roots,
+        docsRoots: record.answers.canonical_doc_folders,
+    };
+    const providersByRole = record.answers.providers_by_role;
+    if (providersByRole && Object.keys(providersByRole).length > 0) {
+        const existingExecution = asRecord(existing.execution);
+        const existingExecutionProviders = asRecord(existingExecution.providers);
+        const executionProviders = { ...existingExecutionProviders };
+        for (const [role, provider] of Object.entries(providersByRole)) {
+            executionProviders[role] = { command: provider };
+        }
+        updated.execution = {
+            ...existingExecution,
+            providers: executionProviders,
+        };
+    }
+    return updated;
+}
+function buildSetupInventory(record) {
+    const candidates = (record.answers.canonical_doc_folders ?? []).map((folder) => ({
+        path: folder,
+        kind: "doc",
+        suggested_destination: `smartdocs/raw/${folder}`,
+        confidence: 0.9,
+        has_frontmatter: false,
+        estimated_risk: "low",
+    }));
+    return {
+        scan_date: new Date().toISOString(),
+        repo_state: "new",
+        package_manager: null,
+        source_roots: record.answers.source_roots ?? [],
+        docs_roots: record.answers.canonical_doc_folders ?? [],
+        test_commands: [],
+        build_commands: [],
+        package_scripts: {},
+        generated_roots: [],
+        cache_roots: [],
+        fixture_roots: [],
+        agent_instruction_files: [],
+        existing_smartdocs_dirs: [],
+        architecture_notes: [record.answers.project_purpose ?? ""].filter(Boolean),
+        likely_canonical_folders: record.answers.canonical_doc_folders ?? [],
+        smartdocs_candidates: candidates,
+        ignore_candidates: record.answers.never_touch ?? [],
+    };
+}
+function* walkMarkdownFiles(dir, root) {
+    for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+        const full = (0, node_path_1.join)(dir, entry.name);
+        if (entry.isDirectory()) {
+            yield* walkMarkdownFiles(full, root);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            yield (0, node_path_1.relative)(root, full).replace(/\\/g, "/");
+        }
+    }
+}
+function scanCanonicalDocs(repoRoot, folders) {
+    const candidates = [];
+    for (const folder of folders) {
+        const absFolder = (0, node_path_1.join)(repoRoot, folder);
+        if (!(0, node_fs_1.existsSync)(absFolder))
+            continue;
+        for (const relPath of walkMarkdownFiles(absFolder, repoRoot)) {
+            candidates.push({
+                path: relPath,
+                kind: "doc",
+                suggested_destination: `smartdocs/raw/${relPath}`,
+                confidence: 0.9,
+                has_frontmatter: false,
+                estimated_risk: "low",
+            });
+        }
+    }
+    return candidates;
+}
+function buildSetupPlan(record, repoRoot, now) {
+    const candidates = scanCanonicalDocs(repoRoot, record.answers.canonical_doc_folders ?? []);
+    const steps = [];
+    let order = 1;
+    steps.push({
+        step_id: "setup-genesis",
+        order: order++,
+        phase: "A",
+        category: "scaffold",
+        action: "create",
+        dest_path: "GENESIS.md",
+        description: "Write initial project genesis from interview answers.",
+        destructive: false,
+        requires_approval: false,
+        estimated_risk: "low",
+        status: "pending",
+    });
+    steps.push({
+        step_id: "setup-config",
+        order: order++,
+        phase: "A",
+        category: "provider-config",
+        action: "modify",
+        dest_path: "polaris.config.json",
+        description: "Write polaris.config.json from interview answers and detected providers.",
+        destructive: true,
+        requires_approval: false,
+        estimated_risk: "low",
+        status: "pending",
+    });
+    steps.push({
+        step_id: "setup-rules",
+        order: order++,
+        phase: "A",
+        category: "scaffold",
+        action: "create",
+        dest_path: "POLARIS_RULES.md",
+        description: "Generate Polaris rules from interview answers.",
+        destructive: false,
+        requires_approval: false,
+        estimated_risk: "low",
+        status: "pending",
+    });
+    steps.push({
+        step_id: "setup-root-surfaces",
+        order: order++,
+        phase: "A",
+        category: "scaffold",
+        action: "create",
+        dest_path: "POLARIS.md, SUMMARY.md, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md",
+        description: "Create root route surfaces if missing.",
+        destructive: false,
+        requires_approval: false,
+        estimated_risk: "low",
+        status: "pending",
+    });
+    for (const candidate of candidates) {
+        steps.push({
+            step_id: `setup-smartdocs-migrate-${order.toString().padStart(3, "0")}`,
+            order: order++,
+            phase: "C",
+            category: "smartdocs-migrate",
+            action: "move",
+            source_path: candidate.path,
+            dest_path: candidate.suggested_destination,
+            description: `Move ${candidate.path} to ${candidate.suggested_destination}.`,
+            destructive: true,
+            requires_approval: true,
+            estimated_risk: "low",
+            status: "pending",
+        });
+    }
+    steps.push({
+        step_id: "setup-atlas-generate",
+        order: order++,
+        phase: "C",
+        category: "atlas-generate",
+        action: "modify",
+        dest_path: ".polaris/map/index.json",
+        description: "Run polaris map index to generate initial route atlas.",
+        destructive: true,
+        requires_approval: true,
+        estimated_risk: "medium",
+        status: "pending",
+    });
+    const filesToCreate = steps.filter((s) => s.action === "create").length;
+    const filesToMove = steps.filter((s) => s.action === "move").length;
+    const filesToModify = steps.filter((s) => s.action === "modify" || s.action === "append").length;
+    return {
+        plan_id: `setup-${now.toISOString().replaceAll(":", "-")}`,
+        generated_at: now.toISOString(),
+        repo_state: "new",
+        approved: false,
+        approved_at: null,
+        dry_run: false,
+        steps,
+        impact_summary: {
+            files_to_create: filesToCreate,
+            files_to_move: filesToMove,
+            files_to_modify: filesToModify,
+            instruction_files_affected: 0,
+            smartdocs_candidates_moved: candidates.length,
+            cognition_files_to_generate: 0,
+        },
+    };
+}
+function renderSetupPlanMarkdown(record, plan) {
+    const a = record.answers;
+    const scaffoldSteps = plan.steps.filter((s) => s.category === "scaffold" && s.action === "create");
+    const scaffoldPaths = scaffoldSteps.map((s) => s.dest_path).join(", ");
+    const lines = [
+        "# Setup Plan",
+        "",
+        `**Project purpose:** ${a.project_purpose ?? "(not specified)"}`,
+        "",
+        `**Source roots:** ${(a.source_roots ?? []).join(", ") || "(none)"}`,
+        "",
+        `**Languages / frameworks:** ${(a.languages ?? []).join(", ") || "(none)"}`,
+        "",
+        `**Canonical documentation folders:** ${(a.canonical_doc_folders ?? []).join(", ") || "(none)"}`,
+        "",
+        `**Never touch:** ${(a.never_touch ?? []).join(", ") || "(none)"}`,
+        "",
+        `**Providers by role:** ${Object.entries(a.providers_by_role ?? {}).map(([k, v]) => `${k}: ${v}`).join(", ") || "(none)"}`,
+        "",
+        "## Files to generate",
+        "",
+        `- GENESIS.md`,
+        `- polaris.config.json`,
+        `- POLARIS_RULES.md`,
+        ...scaffoldPaths.split(", ").map((p) => `- ${p.trim()}`),
+        "",
+        "## SmartDocs intake",
+        "",
+        `Markdown files in canonical documentation folders will be migrated to smartdocs/raw/ (${plan.impact_summary.smartdocs_candidates_moved} candidates).`,
+        "",
+        `**Operations:** ${plan.steps.length} steps (${plan.impact_summary.files_to_create} create, ${plan.impact_summary.files_to_move} move, ${plan.impact_summary.files_to_modify} modify).`,
+    ];
+    return lines.join("\n");
+}
+function buildGenesisContent(record) {
+    const a = record.answers;
+    return [
+        "# Genesis",
+        "",
+        "> Initial project genesis generated by Polaris setup.",
+        "",
+        "## Purpose",
+        "",
+        a.project_purpose ?? "",
+        "",
+        "## Source Roots",
+        "",
+        ...(a.source_roots ?? []).length > 0
+            ? (a.source_roots ?? []).map((root) => `- ${root}`)
+            : ["- (none)"],
+        "",
+        "## Languages / Frameworks",
+        "",
+        ...(a.languages ?? []).length > 0
+            ? (a.languages ?? []).map((lang) => `- ${lang}`)
+            : ["- (none)"],
+        "",
+        "## Canonical Documentation Folders",
+        "",
+        ...(a.canonical_doc_folders ?? []).length > 0
+            ? (a.canonical_doc_folders ?? []).map((folder) => `- ${folder}`)
+            : ["- (none)"],
+        "",
+        "## Governance",
+        "",
+        "- POLARIS_RULES.md — Polaris routing and governance rules",
+        "- POLARIS.md — operational guidance",
+        "- SUMMARY.md — informational context",
+        "",
+    ].join("\n");
+}
+function writeGenesis(repoRoot, record) {
+    const genesisPath = (0, node_path_1.join)(repoRoot, "GENESIS.md");
+    if ((0, node_fs_1.existsSync)(genesisPath))
+        return;
+    (0, node_fs_1.writeFileSync)(genesisPath, buildGenesisContent(record), "utf-8");
+}
+function writeSetupConfig(repoRoot, record, detectedProviders, detectedRepoAnalysis) {
+    const configPath = (0, node_path_1.join)(repoRoot, "polaris.config.json");
+    let existing = {};
+    if ((0, node_fs_1.existsSync)(configPath)) {
+        try {
+            existing = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const updated = buildSetupConfig(existing, record, detectedProviders, detectedRepoAnalysis);
+    (0, node_fs_1.writeFileSync)(configPath, `${JSON.stringify(updated, null, 2)}\n`, "utf-8");
+}
+/**
+ * Generate setup artifacts from a completed interview record.
+ *
+ * - Builds a preview plan from the interview answers.
+ * - In dry-run mode, prints the plan and returns without writing.
+ * - With --yes, bypasses the approval prompt.
+ * - Otherwise prompts the operator for approval.
+ * - On approval, writes GENESIS.md, polaris.config.json, POLARIS_RULES.md,
+ *   root route surfaces, migrates SmartDocs candidates, and runs the map index.
+ */
+async function generateSetupArtifacts(record, options = {}) {
+    const repoRoot = options.repoRoot ?? (0, node_path_1.resolve)(process.cwd());
+    const dryRun = options.dryRun ?? false;
+    const yes = options.yes ?? false;
+    const now = options.now ?? new Date();
+    const stdout = options.stdout ?? process.stdout;
+    const stdin = options.stdin ?? process.stdin;
+    const detectedProviders = options.detectedProviders ?? [];
+    const detectedRepoAnalysis = options.detectedRepoAnalysis ?? [];
+    const scaffoldFn = options.scaffoldRootSurfaces ?? adopt_workspace_js_1.scaffoldRootSurfaces;
+    const rulesFn = options.generatePolarisRules ?? adopt_rules_js_1.generatePolarisRules;
+    const migrateFn = options.migrateSmartDocs ?? adopt_smartdocs_js_1.migrateSmartDocs;
+    const mapFn = options.runMapIndex ?? index_js_1.runMapIndex;
+    const promptFn = options.promptApproval ?? adopt_approve_js_1.promptApproval;
+    const plan = buildSetupPlan(record, repoRoot, now);
+    const markdown = renderSetupPlanMarkdown(record, plan);
+    if (dryRun) {
+        stdout.write(`${markdown}\n\n`);
+        stdout.write("Setup dry run: no files written.\n");
+        return;
+    }
+    let approved = false;
+    if (yes) {
+        stdout.write(`${markdown}\n\n`);
+        stdout.write("Setup approval bypassed via --yes.\n");
+        approved = true;
+    }
+    else {
+        approved = await promptFn(plan, {
+            repoRoot,
+            stdin,
+            stdout,
+            now,
+            markdown,
+            persist: (_plan, root, approvalNow) => {
+                const approvedRecord = (0, store_js_1.markApproved)(record, approvalNow);
+                (0, store_js_1.saveInterview)(root, approvedRecord);
+            },
+        });
+    }
+    if (!approved) {
+        stdout.write("Setup aborted: explicit approval required.\n");
+        return;
+    }
+    writeGenesis(repoRoot, record);
+    writeSetupConfig(repoRoot, record, detectedProviders, detectedRepoAnalysis);
+    await rulesFn(repoRoot, buildSetupInventory(record), {
+        workspaceDir: (0, node_path_1.resolve)(__dirname, "../../workspace"),
+    });
+    scaffoldFn(repoRoot);
+    await migrateFn(plan, repoRoot);
+    mapFn(repoRoot, false, false, { seedCognition: false, skipThreshold: true });
+    stdout.write("Setup generation complete.\n");
+}

package/dist/cli/setup-interview/report.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCheckpointReport = buildCheckpointReport;
+exports.writeCheckpointReport = writeCheckpointReport;
+exports.printCheckpointReport = printCheckpointReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+function getGeneratedFiles(repoRoot) {
+    const files = [];
+    const candidates = [
+        "GENESIS.md",
+        "polaris.config.json",
+        "POLARIS_RULES.md",
+        "POLARIS.md",
+        "SUMMARY.md",
+        "CLAUDE.md",
+        "AGENTS.md",
+        ".github/copilot-instructions.md",
+        ".polaris/map/index.json",
+    ];
+    for (const file of candidates) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, file))) {
+            files.push(file);
+        }
+    }
+    // Check for SmartDocs migrated files
+    const smartdocsDir = (0, node_path_1.join)(repoRoot, "smartdocs", "raw");
+    if ((0, node_fs_1.existsSync)(smartdocsDir)) {
+        try {
+            const smartdocsFiles = (0, node_child_process_1.execFileSync)("find", ["smartdocs/raw", "-name", "*.md", "-type", "f"], {
+                cwd: repoRoot,
+                encoding: "utf-8",
+            })
+                .trim()
+                .split("\n")
+                .filter(Boolean);
+            files.push(...smartdocsFiles);
+        }
+        catch {
+            // find command failed, ignore
+        }
+    }
+    return files.sort();
+}
+function validateGeneratedFiles(repoRoot, files) {
+    const results = {};
+    for (const file of files) {
+        try {
+            const filePath = (0, node_path_1.join)(repoRoot, file);
+            const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+            if (content.trim().length === 0) {
+                results[file] = { passed: false, message: "File is empty" };
+            }
+            else {
+                results[file] = { passed: true };
+            }
+        }
+        catch (error) {
+            results[file] = {
+                passed: false,
+                message: error instanceof Error ? error.message : "Unknown error"
+            };
+        }
+    }
+    return results;
+}
+function buildNextSteps(record) {
+    const steps = [];
+    steps.push("Review generated files in your repository");
+    steps.push("Run `polaris status` to verify setup");
+    if (record.answers.canonical_doc_folders && record.answers.canonical_doc_folders.length > 0) {
+        steps.push("Check migrated documentation in smartdocs/raw/");
+    }
+    steps.push("Start using Polaris: run `polaris analyze` to explore your codebase");
+    return steps;
+}
+function buildCheckpointReport(options) {
+    const { repoRoot, record, now } = options;
+    const timestamp = (now ?? new Date()).toISOString();
+    const createdFiles = getGeneratedFiles(repoRoot);
+    const validationResults = validateGeneratedFiles(repoRoot, createdFiles);
+    const nextSteps = buildNextSteps(record);
+    return {
+        timestamp,
+        interviewStatus: record.status,
+        createdFiles,
+        validationResults,
+        nextSteps,
+    };
+}
+function writeCheckpointReport(repoRoot, report) {
+    // Safe timestamp: replace ":" with "-" and "." with "-"
+    // e.g. "2026-06-09T12:00:00.000Z" → "checkpoint-report-2026-06-09T12-00-00-000Z.json"
+    const safeTimestamp = report.timestamp.replace(/:/g, "-").replace(/\./g, "-");
+    const fileName = `checkpoint-report-${safeTimestamp}.json`;
+    const runsDir = (0, node_path_1.join)(repoRoot, ".polaris", "runs");
+    if (!(0, node_fs_1.existsSync)(runsDir)) {
+        (0, node_fs_1.mkdirSync)(runsDir, { recursive: true });
+    }
+    const reportPath = (0, node_path_1.join)(runsDir, fileName);
+    (0, node_fs_1.writeFileSync)(reportPath, JSON.stringify(report, null, 2), "utf-8");
+}
+function printCheckpointReport(report) {
+    // Print structured summary to stdout
+    console.log("Setup Checkpoint Report:");
+    console.log(`  Timestamp: ${report.timestamp}`);
+    console.log(`  Interview Status: ${report.interviewStatus}`);
+    console.log("");
+    console.log("Generated Files:");
+    if (report.createdFiles.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        for (const file of report.createdFiles) {
+            const validation = report.validationResults[file];
+            const status = validation.passed ? "✓" : "✗";
+            console.log(`  ${status} ${file}`);
+            if (validation.message) {
+                console.log(`    ${validation.message}`);
+            }
+        }
+    }
+    console.log("");
+    const failedValidations = Object.entries(report.validationResults).filter(([_, result]) => !result.passed);
+    if (failedValidations.length > 0) {
+        console.log("Validation Failures:");
+        for (const [file, result] of failedValidations) {
+            console.log(`  ${file}: ${result.message}`);
+        }
+        console.log("");
+    }
+    console.log("Next Steps:");
+    for (const step of report.nextSteps) {
+        console.log(`  • ${step}`);
+    }
+    console.log("");
+}

package/dist/cli/setup-interview/runner.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInterview = runInterview;
+const promises_1 = require("node:readline/promises");
+const store_js_1 = require("./store.js");
+const QUESTION_BANK = [
+    {
+        key: "project_purpose",
+        prompt: "What is the purpose of this project? (one sentence)",
+        parse: (raw) => raw.trim(),
+    },
+    {
+        key: "source_roots",
+        prompt: "Source root directories (comma-separated, e.g. src,lib):",
+        parse: (raw) => splitCsv(raw),
+    },
+    {
+        key: "languages",
+        prompt: "Primary languages/frameworks (comma-separated, e.g. typescript,react):",
+        parse: (raw) => splitCsv(raw),
+    },
+    {
+        key: "canonical_doc_folders",
+        prompt: "Canonical documentation folders (comma-separated, e.g. docs,smartdocs):",
+        parse: (raw) => splitCsv(raw),
+    },
+    {
+        key: "never_touch",
+        prompt: "Paths agents should never modify (comma-separated, or leave blank):",
+        parse: (raw) => splitCsv(raw),
+    },
+    {
+        key: "providers_by_role",
+        prompt: "Agent providers by role — format: role:provider,role:provider (or leave blank):",
+        parse: parseProvidersByRole,
+    },
+];
+function splitCsv(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function parseProvidersByRole(raw) {
+    const result = {};
+    for (const pair of raw.split(",")) {
+        const [role, provider] = pair.split(":").map((s) => s.trim());
+        if (role && provider) {
+            result[role] = provider;
+        }
+    }
+    return result;
+}
+/**
+ * Run the setup interview for an empty/new repo.
+ *
+ * - Loads or creates the persisted record.
+ * - Asks only unanswered questions (resume-safe).
+ * - Saves after every answer.
+ * - In non-interactive mode without stored answers, throws a clear error.
+ *
+ * Returns the final record (all questions answered) or throws.
+ */
+async function runInterview(repoRoot, opts = {}) {
+    const now = opts.now ?? new Date();
+    let record = (0, store_js_1.loadOrCreate)(repoRoot, now);
+    // Check whether the interview is already complete.
+    if ((0, store_js_1.nextUnansweredQuestion)(record) === null) {
+        return record;
+    }
+    // Non-interactive guard: if stdin is not a TTY and no readline override, refuse.
+    if (opts.nonInteractive || (!opts.rl && !process.stdin.isTTY)) {
+        throw new Error("polaris init: interview requires an interactive terminal.\n" +
+            "Provide answers via --resume with a stored interview file, or run interactively.");
+    }
+    const rl = opts.rl ??
+        (() => {
+            const iface = (0, promises_1.createInterface)({ input: process.stdin, output: process.stdout });
+            return {
+                question: (prompt) => iface.question(prompt),
+                close: () => iface.close(),
+            };
+        })();
+    try {
+        for (const q of QUESTION_BANK) {
+            if (record.answers[q.key] !== undefined) {
+                // Already answered — skip (resume path).
+                continue;
+            }
+            const raw = await rl.question(`\n${q.prompt}\n> `);
+            // Parse and apply — save immediately so a crash loses at most one answer.
+            const parsed = q.parse(raw);
+            record = {
+                ...record,
+                answers: { ...record.answers, [q.key]: parsed },
+                status: "answered",
+            };
+            (0, store_js_1.saveInterview)(repoRoot, record);
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return record;
+}

package/dist/cli/setup-interview/schema.js

@@ -0,0 +1,16 @@
+"use strict";
+/** Typed schema for .polaris/setup/interview.json */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInterviewRecord = createInterviewRecord;
+/** Create a fresh interview record (status: in-progress). */
+function createInterviewRecord(now = new Date()) {
+    return {
+        schema_version: "1.0",
+        mode: "init",
+        status: "in-progress",
+        started_at: now.toISOString(),
+        answers: {},
+        generation_plan: null,
+        approved_at: null,
+    };
+}