@lsctech/polaris 0.1.0

package/dist/map/validate.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMapValidate = runMapValidate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const loader_js_1 = require("../config/loader.js");
+const defaults_js_1 = require("../ignore/defaults.js");
+const atlas_js_1 = require("./atlas.js");
+const SECRET_REGEXES = defaults_js_1.SECRET_PATTERNS.map((p) => new RegExp("^" + p.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$"));
+function isSecretPath(filePath) {
+    const parts = filePath.split("/");
+    const base = parts[parts.length - 1];
+    return SECRET_REGEXES.some((re) => re.test(base) || re.test(filePath));
+}
+function daysSince(iso) {
+    const then = new Date(iso).getTime();
+    return (Date.now() - then) / (1000 * 60 * 60 * 24);
+}
+function runMapValidate(repoRoot, staleThresholdDays, fixPath) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const confidenceThreshold = config.map.confidenceThreshold ?? 0.75;
+    const graphOutputPath = (config.graph?.outputPath ?? ".polaris/graph")
+        .replace(/\\/g, "/")
+        .replace(/\/+$/, "");
+    const isGraphArtifactPath = (filePath) => filePath === graphOutputPath || filePath.startsWith(`${graphOutputPath}/`);
+    const routes = (0, atlas_js_1.readFileRoutes)(outputPath);
+    const needsReview = (0, atlas_js_1.readNeedsReview)(outputPath);
+    const exemptions = (0, atlas_js_1.readExemptions)(outputPath);
+    // --fix: show current entry and remove if file is missing
+    if (fixPath) {
+        const entry = routes[fixPath] ?? needsReview[fixPath];
+        if (entry) {
+            console.log(`Current entry for ${fixPath}:`);
+            console.log(JSON.stringify(entry, null, 2));
+            if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, fixPath))) {
+                if (routes[fixPath]) {
+                    const updated = { ...routes };
+                    delete updated[fixPath];
+                    (0, atlas_js_1.writeFileRoutes)(outputPath, updated);
+                    console.log(`Removed missing entry from routes: ${fixPath}`);
+                }
+                else if (needsReview[fixPath]) {
+                    const updated = { ...needsReview };
+                    delete updated[fixPath];
+                    (0, atlas_js_1.writeNeedsReview)(outputPath, updated);
+                    console.log(`Removed missing entry from needs-review: ${fixPath}`);
+                }
+            }
+        }
+        else {
+            console.log(`No entry found for: ${fixPath}`);
+        }
+        return { hasError: false, indexed: 0, stale: [], missing: [], sensitive: [], conflicted: [], needsReviewCount: 0, coveragePct: 0, invalidRoleOwner: [], identityIncomplete: [] };
+    }
+    const stale = [];
+    const missing = [];
+    const sensitive = [];
+    const conflicted = [];
+    const invalidRoleOwner = [];
+    const identityIncomplete = [];
+    // Route conflict detection: route → set of domains seen
+    const routeToDomains = new Map();
+    const routeToFiles = new Map();
+    // Combine routes and needsReview for validation checks
+    const allEntries = [...Object.entries(routes), ...Object.entries(needsReview)];
+    for (const [filePath, entry] of allEntries) {
+        // Graph output artifacts are generated runtime data and exempt from atlas validation.
+        if (isGraphArtifactPath(filePath)) {
+            continue;
+        }
+        // 2. Missing source files
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, filePath))) {
+            missing.push(filePath);
+            continue;
+        }
+        // 1. Stale entries
+        if (daysSince(entry.last_updated) > staleThresholdDays) {
+            stale.push(filePath);
+        }
+        // 4. Sensitive pattern matches in atlas
+        if (isSecretPath(filePath)) {
+            sensitive.push(filePath);
+        }
+        // 6. role_owner validation: present and a known value
+        if (entry.role_owner !== undefined && !atlas_js_1.VALID_ROLE_OWNERS.includes(entry.role_owner)) {
+            invalidRoleOwner.push(filePath);
+        }
+        // 7. identity completeness: instructionFile and role_owner are required
+        if (entry.instructionFile === undefined || entry.role_owner === undefined) {
+            identityIncomplete.push(filePath);
+        }
+        // 5. Conflicted routes: same route claimed by different domains
+        const domains = routeToDomains.get(entry.route) ?? new Set();
+        domains.add(entry.domain);
+        routeToDomains.set(entry.route, domains);
+        const files = routeToFiles.get(entry.route) ?? [];
+        files.push(filePath);
+        routeToFiles.set(entry.route, files);
+    }
+    for (const [route, domains] of routeToDomains) {
+        if (domains.size > 1) {
+            conflicted.push(...(routeToFiles.get(route) ?? []));
+        }
+    }
+    // 3. Low-confidence (needs-review count)
+    const needsReviewCount = Object.keys(needsReview).filter((filePath) => !isGraphArtifactPath(filePath)).length;
+    // Coverage: indexed / (indexed + needs-review + tracked-not-indexed)
+    // Only count non-graph routes for indexedCount, excluding missing files.
+    const indexedCount = Object.keys(routes).filter((filePath) => !isGraphArtifactPath(filePath)).length
+        - missing.filter((filePath) => routes[filePath] && !isGraphArtifactPath(filePath)).length;
+    const trackedCount = Object.keys(exemptions).filter((filePath) => !isGraphArtifactPath(filePath)).length;
+    const total = indexedCount + needsReviewCount + trackedCount;
+    const coveragePct = total > 0 ? Math.round((indexedCount / total) * 100 * 10) / 10 : 0;
+    // Output
+    const successMark = "✓";
+    const okMark = "✓";
+    const warnMark = "⚠";
+    const errMark = "✗";
+    console.log(`${okMark} ${indexedCount} indexed files validated`);
+    if (stale.length > 0) {
+        console.log(`${warnMark} ${stale.length} stale entries (older than ${staleThresholdDays}d): ${stale.slice(0, 3).join(", ")}${stale.length > 3 ? "..." : ""}`);
+    }
+    for (const f of missing) {
+        console.log(`${errMark} 1 missing source file: ${f} (was indexed, file deleted)`);
+    }
+    if (sensitive.length > 0) {
+        console.log(`${errMark} HIGH: ${sensitive.length} sensitive file(s) in atlas: ${sensitive.join(", ")}`);
+    }
+    else {
+        console.log(`${successMark} HIGH: 0 sensitive files in atlas`);
+    }
+    if (needsReviewCount > 0) {
+        console.log(`${warnMark} ${needsReviewCount} files in needs-review queue`);
+    }
+    if (conflicted.length > 0) {
+        console.log(`${warnMark} ${conflicted.length} conflicted route entries: ${conflicted.slice(0, 3).join(", ")}${conflicted.length > 3 ? "..." : ""}`);
+    }
+    if (invalidRoleOwner.length > 0) {
+        console.log(`${errMark} ${invalidRoleOwner.length} entries with invalid role_owner value: ${invalidRoleOwner.slice(0, 3).join(", ")}${invalidRoleOwner.length > 3 ? "..." : ""}`);
+    }
+    if (identityIncomplete.length > 0) {
+        console.log(`${warnMark} ${identityIncomplete.length} routes missing identity fields (instructionFile or role_owner): ${identityIncomplete.slice(0, 3).join(", ")}${identityIncomplete.length > 3 ? "..." : ""}`);
+    }
+    // Low-confidence entries warning
+    const lowConfidence = Object.entries(routes).filter(([filePath, e]) => !isGraphArtifactPath(filePath) && e.confidence < confidenceThreshold);
+    if (lowConfidence.length > 0) {
+        console.log(`${warnMark} ${lowConfidence.length} indexed entries below confidence threshold`);
+    }
+    console.log(`\nCoverage: ${coveragePct}% (${indexedCount} / ${total} non-ignored files)`);
+    const hasError = missing.length > 0 || sensitive.length > 0 || invalidRoleOwner.length > 0;
+    return { hasError, indexed: indexedCount, stale, missing, sensitive, conflicted, needsReviewCount, coveragePct, invalidRoleOwner, identityIncomplete };
+}

package/dist/map/validate.test.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Tests for map validation including role_owner field (POL-231).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const validate_js_1 = require("./validate.js");
+function makeTestDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-validate-test-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function writeRoutes(dir, routes) {
+    const mapDir = (0, node_path_1.join)(dir, ".polaris", "map");
+    (0, node_fs_1.mkdirSync)(mapDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(mapDir, "file-routes.json"), JSON.stringify(routes), "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(mapDir, "needs-review.json"), JSON.stringify({}), "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(mapDir, "exemptions.json"), JSON.stringify({}), "utf-8");
+}
+function makeEntry(overrides = {}) {
+    return {
+        domain: "cli",
+        route: "src/cli",
+        taskchain: "polaris-cli",
+        confidence: 0.9,
+        classification: "indexed",
+        last_updated: new Date().toISOString(),
+        updated_by: "test",
+        tags: ["cli"],
+        ...overrides,
+    };
+}
+(0, vitest_1.describe)("runMapValidate role_owner validation", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => {
+        testDir = makeTestDir();
+    });
+    (0, vitest_1.afterEach)(() => {
+        (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)("passes validation when role_owner is a valid value", () => {
+        const entryPath = (0, node_path_1.join)(testDir, "src/cli/index.ts");
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src/cli"), { recursive: true });
+        (0, node_fs_1.writeFileSync)(entryPath, "");
+        writeRoutes(testDir, {
+            "src/cli/index.ts": makeEntry({ role_owner: "worker" }),
+        });
+        const result = (0, validate_js_1.runMapValidate)(testDir, 9999);
+        (0, vitest_1.expect)(result.invalidRoleOwner).toHaveLength(0);
+        (0, vitest_1.expect)(result.hasError).toBe(false);
+    });
+    (0, vitest_1.it)("fails validation when role_owner is an unknown value", () => {
+        const entryPath = (0, node_path_1.join)(testDir, "src/cli/index.ts");
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src/cli"), { recursive: true });
+        (0, node_fs_1.writeFileSync)(entryPath, "");
+        writeRoutes(testDir, {
+            "src/cli/index.ts": makeEntry({ role_owner: "unknown-role" }),
+        });
+        const result = (0, validate_js_1.runMapValidate)(testDir, 9999);
+        (0, vitest_1.expect)(result.invalidRoleOwner).toContain("src/cli/index.ts");
+        (0, vitest_1.expect)(result.hasError).toBe(true);
+    });
+    (0, vitest_1.it)("passes validation when role_owner is absent (optional field)", () => {
+        const entryPath = (0, node_path_1.join)(testDir, "src/cli/index.ts");
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src/cli"), { recursive: true });
+        (0, node_fs_1.writeFileSync)(entryPath, "");
+        writeRoutes(testDir, {
+            "src/cli/index.ts": makeEntry(), // no role_owner
+        });
+        const result = (0, validate_js_1.runMapValidate)(testDir, 9999);
+        (0, vitest_1.expect)(result.invalidRoleOwner).toHaveLength(0);
+    });
+    (0, vitest_1.it)("accepts all valid role_owner values", () => {
+        const validRoles = ["worker", "foreman", "analyst", "librarian", "any"];
+        for (const role of validRoles) {
+            const entryPath = (0, node_path_1.join)(testDir, "src/cli/index.ts");
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src/cli"), { recursive: true });
+            (0, node_fs_1.writeFileSync)(entryPath, "");
+            writeRoutes(testDir, {
+                "src/cli/index.ts": makeEntry({ role_owner: role }),
+            });
+            const result = (0, validate_js_1.runMapValidate)(testDir, 9999);
+            (0, vitest_1.expect)(result.invalidRoleOwner).toHaveLength(0);
+            (0, vitest_1.expect)(result.hasError).toBe(false);
+        }
+    });
+});

package/dist/map/welfare.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWelfareCheck = runWelfareCheck;
+exports.printWelfareCheckReport = printWelfareCheckReport;
+const node_path_1 = require("node:path");
+const loader_js_1 = require("../config/loader.js");
+const atlas_js_1 = require("./atlas.js");
+function daysSince(iso) {
+    const then = new Date(iso).getTime();
+    return (Date.now() - then) / (1000 * 60 * 60 * 24);
+}
+function isIdentityComplete(entry) {
+    return entry.instructionFile !== undefined && entry.role_owner !== undefined;
+}
+function assessRouteHealth(entry, staleThresholdDays) {
+    const daysSinceUpdate = daysSince(entry.last_updated);
+    const identityComplete = isIdentityComplete(entry);
+    if (daysSinceUpdate > staleThresholdDays) {
+        return "stale";
+    }
+    if (!identityComplete) {
+        return "known-issues";
+    }
+    return "healthy";
+}
+function determineActionRequired(identityComplete, healthState) {
+    if (identityComplete && healthState === "healthy") {
+        return "none";
+    }
+    // Note: !identityComplete && healthState === "healthy" is unreachable because
+    // assessRouteHealth returns "known-issues" whenever identityComplete is false
+    if (identityComplete && healthState !== "healthy") {
+        return "review-health";
+    }
+    return "review-both";
+}
+function runWelfareCheck(repoRoot, routePath) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const staleThresholdDays = 30;
+    const routes = (0, atlas_js_1.readFileRoutes)(outputPath);
+    const results = [];
+    for (const [filePath, entry] of Object.entries(routes)) {
+        if (routePath && !filePath.startsWith(routePath)) {
+            continue;
+        }
+        const identityComplete = isIdentityComplete(entry);
+        const healthState = assessRouteHealth(entry, staleThresholdDays);
+        const actionRequired = determineActionRequired(identityComplete, healthState);
+        results.push({
+            route: filePath,
+            identityComplete,
+            healthState,
+            actionRequired,
+        });
+    }
+    const healthyRoutes = results.filter((r) => r.actionRequired === "none").length;
+    const needsReview = results.filter((r) => r.actionRequired !== "none").length;
+    return {
+        routes: results,
+        totalRoutes: results.length,
+        healthyRoutes,
+        needsReview,
+    };
+}
+function printWelfareCheckReport(report) {
+    console.log(`Route Welfare Check Report`);
+    console.log(`========================`);
+    console.log(`Total routes: ${report.totalRoutes}`);
+    console.log(`Healthy: ${report.healthyRoutes}`);
+    console.log(`Needs review: ${report.needsReview}`);
+    console.log();
+    if (report.routes.length === 0) {
+        console.log("No routes found.");
+        return;
+    }
+    for (const result of report.routes) {
+        const identityStatus = result.identityComplete ? "✓" : "✗";
+        const actionSymbol = result.actionRequired === "none" ? "✓" : "⚠";
+        console.log(`${actionSymbol} ${result.route}`);
+        console.log(`   Identity complete: ${identityStatus}`);
+        console.log(`   Health state: ${result.healthState}`);
+        console.log(`   Action required: ${result.actionRequired}`);
+        console.log();
+    }
+}

package/dist/mcp/lib/invoke.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvokeError = void 0;
+exports.invokePolarisJson = invokePolarisJson;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+class InvokeError extends Error {
+    stderr;
+    constructor(message, stderr) {
+        super(message);
+        this.stderr = stderr;
+        this.name = "InvokeError";
+    }
+}
+exports.InvokeError = InvokeError;
+function invokePolarisJson(repoRoot, args) {
+    const result = (0, node_child_process_1.spawnSync)(process.execPath, [(0, node_path_1.join)("dist", "cli", "index.js"), ...args], {
+        cwd: repoRoot,
+        encoding: "utf-8",
+        timeout: 10_000,
+        shell: false,
+    });
+    if (result.error) {
+        throw new InvokeError(`Subprocess error: ${result.error.message}`, "");
+    }
+    if (result.status !== 0) {
+        throw new InvokeError(`polaris exited with status ${result.status ?? "null"}`, result.stderr ?? "");
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new InvokeError("Failed to parse subprocess JSON output", result.stderr ?? "");
+    }
+}

package/dist/mcp/lib/redact.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+const SENSITIVE_PATTERN = /secret|token|key|password|credential/i;
+const MAX_ARRAY_LENGTH = 50;
+function redact(value) {
+    if (Array.isArray(value)) {
+        const truncated = value.slice(0, MAX_ARRAY_LENGTH).map(redact);
+        return truncated;
+    }
+    if (value !== null && typeof value === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (SENSITIVE_PATTERN.test(k)) {
+                result[k] = "[redacted]";
+            }
+            else {
+                result[k] = redact(v);
+            }
+        }
+        return result;
+    }
+    return value;
+}

package/dist/mcp/lib/redact.test.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Unit tests for src/mcp/lib/redact.ts
+ *
+ * Covers:
+ * - strips keys matching sensitive pattern (secret, token, key, password, credential, API_KEY, etc.)
+ * - does NOT strip non-sensitive keys
+ * - recursively redacts nested objects
+ * - truncates arrays > 50 items to 50
+ * - returns non-sensitive primitives unchanged
+ * - replaces sensitive key values with "[redacted]"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const redact_js_1 = require("./redact.js");
+(0, vitest_1.describe)("redact()", () => {
+    (0, vitest_1.it)("replaces values of sensitive keys with [redacted]", () => {
+        const result = (0, redact_js_1.redact)({ secret: "mysecret", label: "visible" });
+        (0, vitest_1.expect)(result["secret"]).toBe("[redacted]");
+        (0, vitest_1.expect)(result["label"]).toBe("visible");
+    });
+    (0, vitest_1.it)("redacts keys matching: token", () => {
+        const result = (0, redact_js_1.redact)({ token: "abc123" });
+        (0, vitest_1.expect)(result["token"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("redacts keys matching: key", () => {
+        const result = (0, redact_js_1.redact)({ key: "somevalue" });
+        (0, vitest_1.expect)(result["key"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("redacts keys matching: password", () => {
+        const result = (0, redact_js_1.redact)({ password: "hunter2" });
+        (0, vitest_1.expect)(result["password"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("redacts keys matching: credential", () => {
+        const result = (0, redact_js_1.redact)({ credential: "credvalue" });
+        (0, vitest_1.expect)(result["credential"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("redacts keys matching: API_KEY (case-insensitive)", () => {
+        const result = (0, redact_js_1.redact)({ API_KEY: "myapikey" });
+        (0, vitest_1.expect)(result["API_KEY"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("redacts keys matching: secretValue (substring match)", () => {
+        const result = (0, redact_js_1.redact)({ secretValue: "hidden" });
+        (0, vitest_1.expect)(result["secretValue"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("redacts keys matching: accessToken (substring match)", () => {
+        const result = (0, redact_js_1.redact)({ accessToken: "tok_abc" });
+        (0, vitest_1.expect)(result["accessToken"]).toBe("[redacted]");
+    });
+    (0, vitest_1.it)("does NOT redact non-sensitive keys", () => {
+        const result = (0, redact_js_1.redact)({
+            name: "Alice",
+            status: "active",
+            count: 42,
+            enabled: true,
+        });
+        (0, vitest_1.expect)(result["name"]).toBe("Alice");
+        (0, vitest_1.expect)(result["status"]).toBe("active");
+        (0, vitest_1.expect)(result["count"]).toBe(42);
+        (0, vitest_1.expect)(result["enabled"]).toBe(true);
+    });
+    (0, vitest_1.it)("recursively redacts nested objects", () => {
+        const input = {
+            outer: "visible",
+            nested: {
+                token: "should-be-redacted",
+                label: "still-visible",
+                deeper: {
+                    password: "also-redacted",
+                    info: "public",
+                },
+            },
+        };
+        const result = (0, redact_js_1.redact)(input);
+        (0, vitest_1.expect)(result.outer).toBe("visible");
+        (0, vitest_1.expect)(result.nested.token).toBe("[redacted]");
+        (0, vitest_1.expect)(result.nested.label).toBe("still-visible");
+        (0, vitest_1.expect)(result.nested.deeper.password).toBe("[redacted]");
+        (0, vitest_1.expect)(result.nested.deeper.info).toBe("public");
+    });
+    (0, vitest_1.it)("truncates arrays longer than 50 items to 50 items", () => {
+        const bigArray = Array.from({ length: 100 }, (_, i) => i);
+        const result = (0, redact_js_1.redact)(bigArray);
+        (0, vitest_1.expect)(result).toHaveLength(50);
+        (0, vitest_1.expect)(result[0]).toBe(0);
+        (0, vitest_1.expect)(result[49]).toBe(49);
+    });
+    (0, vitest_1.it)("does not truncate arrays with 50 or fewer items", () => {
+        const arr = Array.from({ length: 50 }, (_, i) => i);
+        const result = (0, redact_js_1.redact)(arr);
+        (0, vitest_1.expect)(result).toHaveLength(50);
+    });
+    (0, vitest_1.it)("recursively redacts items within arrays", () => {
+        const arr = [{ token: "secret-tok" }, { label: "visible" }];
+        const result = (0, redact_js_1.redact)(arr);
+        (0, vitest_1.expect)(result[0]?.["token"]).toBe("[redacted]");
+        (0, vitest_1.expect)(result[1]?.["label"]).toBe("visible");
+    });
+    (0, vitest_1.it)("returns primitive numbers unchanged", () => {
+        (0, vitest_1.expect)((0, redact_js_1.redact)(42)).toBe(42);
+    });
+    (0, vitest_1.it)("returns primitive strings unchanged", () => {
+        (0, vitest_1.expect)((0, redact_js_1.redact)("hello")).toBe("hello");
+    });
+    (0, vitest_1.it)("returns booleans unchanged", () => {
+        (0, vitest_1.expect)((0, redact_js_1.redact)(true)).toBe(true);
+        (0, vitest_1.expect)((0, redact_js_1.redact)(false)).toBe(false);
+    });
+    (0, vitest_1.it)("returns null unchanged", () => {
+        (0, vitest_1.expect)((0, redact_js_1.redact)(null)).toBeNull();
+    });
+});

package/dist/mcp/lib/root.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRepoRoot = resolveRepoRoot;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function hasPackageJson(dir) {
+    const pkgPath = (0, node_path_1.join)(dir, "package.json");
+    if (!(0, node_fs_1.existsSync)(pkgPath))
+        return false;
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf-8"));
+        return pkg.name === "polaris";
+    }
+    catch {
+        return false;
+    }
+}
+function walkUp(startDir) {
+    let current = (0, node_path_1.resolve)(startDir);
+    for (let i = 0; i < 20; i++) {
+        if (hasPackageJson(current))
+            return current;
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}
+function resolveRepoRoot() {
+    if (process.env["POLARIS_ROOT"]) {
+        return (0, node_path_1.resolve)(process.env["POLARIS_ROOT"]);
+    }
+    const fromCwd = walkUp(process.cwd());
+    if (fromCwd)
+        return fromCwd;
+    const fromModule = walkUp((0, node_path_1.dirname)(__filename));
+    if (fromModule)
+        return fromModule;
+    throw new Error("Cannot locate Polaris repo root. Set POLARIS_ROOT env var or run from within the repo.");
+}

package/dist/mcp/lib/root.test.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Unit tests for src/mcp/lib/root.ts
+ *
+ * Covers:
+ * - returns POLARIS_ROOT env var (resolve()d) when set
+ * - walks up from cwd and finds repo root when package.json has name=polaris
+ * - throws when no root found and POLARIS_ROOT not set
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+// Keep a reference to the original env and cwd
+const originalEnv = process.env["POLARIS_ROOT"];
+const originalCwd = process.cwd();
+function makeTempDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-root-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+(0, vitest_1.describe)("resolveRepoRoot()", () => {
+    let tempDir;
+    (0, vitest_1.beforeEach)(() => {
+        tempDir = makeTempDir();
+        // Ensure POLARIS_ROOT is unset before each test (restored per-test)
+        delete process.env["POLARIS_ROOT"];
+    });
+    (0, vitest_1.afterEach)(() => {
+        // Restore POLARIS_ROOT to whatever it was originally
+        if (originalEnv !== undefined) {
+            process.env["POLARIS_ROOT"] = originalEnv;
+        }
+        else {
+            delete process.env["POLARIS_ROOT"];
+        }
+        // Restore cwd
+        process.chdir(originalCwd);
+        (0, node_fs_1.rmSync)(tempDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)("returns the resolved POLARIS_ROOT env var when set", async () => {
+        process.env["POLARIS_ROOT"] = tempDir;
+        // Dynamic import so we get a fresh call each time (module is already cached,
+        // but the function re-reads process.env at call time)
+        const { resolveRepoRoot } = await import("./root.js");
+        const result = resolveRepoRoot();
+        // Compare real paths to handle macOS symlinked temp directories
+        (0, vitest_1.expect)((0, node_fs_1.realpathSync)(result)).toBe((0, node_fs_1.realpathSync)((0, node_path_1.resolve)(tempDir)));
+    });
+    (0, vitest_1.it)("resolves a relative POLARIS_ROOT path to an absolute path", async () => {
+        // Create a real directory for relative path test (realpathSync requires path to exist)
+        const relativeDir = (0, node_path_1.join)(tempDir, "relative-path");
+        (0, node_fs_1.mkdirSync)(relativeDir, { recursive: true });
+        // Change to tempDir so relative path resolves correctly
+        process.chdir(tempDir);
+        process.env["POLARIS_ROOT"] = "./relative-path";
+        const { resolveRepoRoot } = await import("./root.js");
+        const result = resolveRepoRoot();
+        // Compare real paths to handle macOS symlinked temp directories
+        (0, vitest_1.expect)((0, node_fs_1.realpathSync)(result)).toBe((0, node_fs_1.realpathSync)(relativeDir));
+    });
+    (0, vitest_1.it)("walks up from cwd and finds the repo root when package.json has name=polaris", async () => {
+        // Write a valid polaris package.json into tempDir
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(tempDir, "package.json"), JSON.stringify({ name: "polaris" }));
+        // Create a subdirectory and chdir into it so walkUp must climb to tempDir
+        const subDir = (0, node_path_1.join)(tempDir, "sub", "deep");
+        (0, node_fs_1.mkdirSync)(subDir, { recursive: true });
+        process.chdir(subDir);
+        delete process.env["POLARIS_ROOT"];
+        const { resolveRepoRoot } = await import("./root.js");
+        const result = resolveRepoRoot();
+        // Compare real paths to handle macOS symlinked temp directories
+        (0, vitest_1.expect)((0, node_fs_1.realpathSync)(result)).toBe((0, node_fs_1.realpathSync)(tempDir));
+    });
+    (0, vitest_1.it)("throws when no polaris root can be found and POLARIS_ROOT is not set", async () => {
+        // tempDir has no package.json with name=polaris; chdir into it
+        process.chdir(tempDir);
+        delete process.env["POLARIS_ROOT"];
+        const { resolveRepoRoot } = await import("./root.js");
+        // The function walks up until it hits the filesystem root and throws
+        // NOTE: this may succeed if a parent directory happens to contain a polaris package.json;
+        // we accept that edge case by checking it either returns a string or throws the expected error.
+        try {
+            const result = resolveRepoRoot();
+            // If it didn't throw, it must have found a root — just verify it's a string
+            (0, vitest_1.expect)(typeof result).toBe("string");
+        }
+        catch (err) {
+            (0, vitest_1.expect)(err).toBeInstanceOf(Error);
+            (0, vitest_1.expect)(err.message).toMatch(/Cannot locate Polaris repo root/);
+        }
+    });
+    (0, vitest_1.it)("throws with helpful message mentioning POLARIS_ROOT env var", async () => {
+        // Use a deeply nested temp dir with no package.json to force failure
+        // We mock cwd to a path that has no polaris root
+        const isolatedDir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `isolated-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        (0, node_fs_1.mkdirSync)(isolatedDir, { recursive: true });
+        process.chdir(isolatedDir);
+        delete process.env["POLARIS_ROOT"];
+        const { resolveRepoRoot } = await import("./root.js");
+        try {
+            resolveRepoRoot();
+            // If it finds something (because a parent has polaris package.json), that's also OK
+        }
+        catch (err) {
+            (0, vitest_1.expect)(err).toBeInstanceOf(Error);
+            (0, vitest_1.expect)(err.message).toContain("POLARIS_ROOT");
+        }
+        finally {
+            (0, node_fs_1.rmSync)(isolatedDir, { recursive: true, force: true });
+        }
+    });
+});