@lsctech/polaris 0.1.0

package/dist/cluster-state/store.test.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const store_1 = require("./store");
+const local_graph_1 = require("../tracker/local-graph");
+const test_clusters_json_1 = __importDefault(require("./fixtures/test-clusters.json"));
+vitest_1.vi.mock('fs', () => ({
+    promises: {
+        readFile: vitest_1.vi.fn(),
+        writeFile: vitest_1.vi.fn(),
+        rename: vitest_1.vi.fn(),
+    },
+}));
+vitest_1.vi.mock('../tracker/local-graph');
+const MOCK_CLUSTER_ID = 'POL-TEST-1';
+(0, vitest_1.describe)('Cluster State Store', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.resetAllMocks();
+    });
+    (0, vitest_1.describe)('readClusterState', () => {
+        (0, vitest_1.it)('should read and parse the cluster state file', async () => {
+            const mockState = {
+                schema_version: '1.0',
+                cluster_id: MOCK_CLUSTER_ID,
+                state_generation: 1,
+                child_states: [],
+                claim_metadata: {},
+                packet_pointers: {},
+                result_pointers: {},
+                validation_results: {},
+                commits: {},
+                blockers: [],
+            };
+            fs_1.promises.readFile.mockResolvedValue(JSON.stringify(mockState));
+            const state = await (0, store_1.readClusterState)(MOCK_CLUSTER_ID);
+            (0, vitest_1.expect)(state).toEqual(mockState);
+            (0, vitest_1.expect)(fs_1.promises.readFile).toHaveBeenCalledWith(vitest_1.expect.stringContaining('cluster-state.json'), 'utf-8');
+        });
+        (0, vitest_1.it)('should return null if the file does not exist', async () => {
+            const error = new Error('ENOENT: no such file or directory');
+            error.code = 'ENOENT';
+            fs_1.promises.readFile.mockRejectedValue(error);
+            const state = await (0, store_1.readClusterState)(MOCK_CLUSTER_ID);
+            (0, vitest_1.expect)(state).toBeNull();
+        });
+        (0, vitest_1.it)('should re-throw other errors', async () => {
+            const error = new Error('Read error');
+            fs_1.promises.readFile.mockRejectedValue(error);
+            await (0, vitest_1.expect)((0, store_1.readClusterState)(MOCK_CLUSTER_ID)).rejects.toThrow('Read error');
+        });
+    });
+    (0, vitest_1.describe)('writeClusterState', () => {
+        (0, vitest_1.it)('should write the cluster state atomically', async () => {
+            const newState = {
+                schema_version: '1.0',
+                cluster_id: MOCK_CLUSTER_ID,
+                state_generation: 2,
+                child_states: [],
+                claim_metadata: {},
+                packet_pointers: {},
+                result_pointers: {},
+                validation_results: {},
+                commits: {},
+                blockers: [],
+            };
+            // Mock existing state as null
+            fs_1.promises.readFile.mockResolvedValueOnce(null);
+            await (0, store_1.writeClusterState)(MOCK_CLUSTER_ID, newState);
+            const filePath = path.join(process.cwd(), '.polaris', 'clusters', MOCK_CLUSTER_ID, 'cluster-state.json');
+            (0, vitest_1.expect)(fs_1.promises.writeFile).toHaveBeenCalledWith(filePath + '.tmp', JSON.stringify(newState, null, 2));
+            (0, vitest_1.expect)(fs_1.promises.rename).toHaveBeenCalledWith(filePath + '.tmp', filePath);
+        });
+        (0, vitest_1.it)('should throw an error for a stale state generation', async () => {
+            const existingState = {
+                schema_version: '1.0',
+                cluster_id: MOCK_CLUSTER_ID,
+                state_generation: 2,
+                child_states: [],
+                claim_metadata: {},
+                packet_pointers: {},
+                result_pointers: {},
+                validation_results: {},
+                commits: {},
+                blockers: [],
+            };
+            const newState = { ...existingState, state_generation: 2 };
+            fs_1.promises.readFile.mockResolvedValue(JSON.stringify(existingState));
+            await (0, vitest_1.expect)((0, store_1.writeClusterState)(MOCK_CLUSTER_ID, newState)).rejects.toThrow('Stale state: state_generation is not greater than current state.');
+        });
+    });
+    (0, vitest_1.describe)('initializeClusterState', () => {
+        (0, vitest_1.it)('should initialize state from a LocalGraph', async () => {
+            const mockGraph = local_graph_1.LocalGraph.fromGraph(test_clusters_json_1.default);
+            vitest_1.vi.spyOn(local_graph_1.LocalGraph, 'load').mockResolvedValue(mockGraph);
+            // Mock writeClusterState to avoid its internal logic for this test
+            const writeSpy = vitest_1.vi.spyOn(fs_1.promises, 'writeFile');
+            const initialState = await (0, store_1.initializeClusterState)(MOCK_CLUSTER_ID);
+            (0, vitest_1.expect)(local_graph_1.LocalGraph.load).toHaveBeenCalledWith(MOCK_CLUSTER_ID);
+            (0, vitest_1.expect)(initialState.cluster_id).toBe(MOCK_CLUSTER_ID);
+            (0, vitest_1.expect)(initialState.state_generation).toBe(1);
+            (0, vitest_1.expect)(initialState.child_states).toHaveLength(2);
+            (0, vitest_1.expect)(initialState.child_states[0]).toEqual({ id: 'CHILD-1', status: 'open' });
+            (0, vitest_1.expect)(initialState.child_states[1]).toEqual({ id: 'CHILD-2', status: 'open' });
+            (0, vitest_1.expect)(writeSpy).toHaveBeenCalled();
+        });
+    });
+});

package/dist/cluster-state/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cognition/archive.js

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.archiveCognitionNotes = archiveCognitionNotes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const PENDING_PREFIX = ".polaris/cognition/pending/";
+const ARCHIVE_PREFIX = ".polaris/cognition/archive/";
+function normalizeRelativePath(filePath) {
+    return node_path_1.default.posix.normalize(filePath.replace(/\\/g, "/")).replace(/^\.\//, "");
+}
+function resolvePendingNotePath(repoRoot, notePath) {
+    const rawRelativePath = node_path_1.default.isAbsolute(notePath)
+        ? node_path_1.default.relative(repoRoot, notePath)
+        : notePath;
+    let normalized = normalizeRelativePath(rawRelativePath);
+    // Remove leading slashes
+    normalized = normalized.replace(/^\/+/, "");
+    // Use path.posix.normalize to collapse ".." and "."
+    normalized = node_path_1.default.posix.normalize(normalized);
+    // Validate: reject paths that escape the repository or are absolute
+    if (normalized.startsWith("../") || normalized.includes("/../") || normalized.startsWith("/")) {
+        throw new Error(`Invalid note path: path traversal or absolute path detected: ${notePath}`);
+    }
+    const pendingRelativePath = normalized.startsWith(PENDING_PREFIX)
+        ? normalized
+        : `${PENDING_PREFIX}${normalized}`;
+    const noteRelativePath = pendingRelativePath.slice(PENDING_PREFIX.length);
+    const folderName = node_path_1.default.posix.dirname(noteRelativePath);
+    const folder = folderName === "." ? "" : folderName;
+    const noteName = node_path_1.default.posix.basename(noteRelativePath);
+    const archiveRelativePath = `${ARCHIVE_PREFIX}${noteRelativePath}`;
+    return {
+        pendingRelativePath,
+        archiveRelativePath,
+        folder,
+        noteName,
+    };
+}
+function readIndex(indexPath) {
+    if (!(0, node_fs_1.existsSync)(indexPath)) {
+        return { entries: [] };
+    }
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(indexPath, "utf-8"));
+        if (Array.isArray(parsed.entries)) {
+            return { entries: parsed.entries };
+        }
+    }
+    catch {
+        // Fall through to reset malformed index files.
+    }
+    return { entries: [] };
+}
+function writeIndex(indexPath, entry) {
+    const index = readIndex(indexPath);
+    index.entries.push(entry);
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(indexPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(indexPath, JSON.stringify(index, null, 2) + "\n", "utf-8");
+}
+function buildArchivedResultPayload(options) {
+    return options.result ?? {
+        reconcile_id: options.reconcileId,
+        run_id: options.runId,
+        reconciled_at: options.reconciledAt ?? new Date().toISOString(),
+        notes_consumed: options.notesConsumed,
+        polaris_md_updated: options.polarisMdUpdated,
+        summary_md_updated: options.summaryMdUpdated,
+        status: options.status ?? "applied",
+    };
+}
+function archiveCognitionNotes(options) {
+    const archivedNotes = [];
+    const missingNotes = [];
+    const updatedIndexFiles = [];
+    const resultFiles = [];
+    const timestamp = options.reconciledAt ?? new Date().toISOString();
+    const groupedNotes = new Map();
+    const resolvedNotes = options.notesConsumed.map((notePath) => resolvePendingNotePath(options.repoRoot, notePath));
+    for (const note of resolvedNotes) {
+        const targetGroup = groupedNotes.get(note.folder) ?? [];
+        groupedNotes.set(note.folder, targetGroup);
+        const pendingAbsolutePath = node_path_1.default.join(options.repoRoot, note.pendingRelativePath);
+        const archiveAbsolutePath = node_path_1.default.join(options.repoRoot, note.archiveRelativePath);
+        (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(archiveAbsolutePath), { recursive: true });
+        if (options.status === "rejected") {
+            targetGroup.push(note.noteName);
+            continue;
+        }
+        if ((0, node_fs_1.existsSync)(pendingAbsolutePath)) {
+            (0, node_fs_1.renameSync)(pendingAbsolutePath, archiveAbsolutePath);
+            archivedNotes.push(note.archiveRelativePath);
+            targetGroup.push(note.noteName);
+            continue;
+        }
+        if ((0, node_fs_1.existsSync)(archiveAbsolutePath)) {
+            archivedNotes.push(note.archiveRelativePath);
+            targetGroup.push(note.noteName);
+            continue;
+        }
+        missingNotes.push(note.pendingRelativePath);
+    }
+    if (options.status === "rejected") {
+        for (const [folder, notesConsumed] of groupedNotes.entries()) {
+            if (notesConsumed.length === 0) {
+                continue;
+            }
+            const indexRelativePath = `${PENDING_PREFIX}${folder ? `${folder}/` : ""}cognition-index.json`;
+            writeIndex(node_path_1.default.join(options.repoRoot, indexRelativePath), {
+                event: "cognition-librarian-patch-rejected",
+                reconcile_id: options.reconcileId,
+                run_id: options.runId,
+                rejected_at: timestamp,
+                notes_consumed: notesConsumed,
+                polaris_md_updated: options.polarisMdUpdated,
+                summary_md_updated: options.summaryMdUpdated,
+                reason: options.rejectionReason,
+            });
+            updatedIndexFiles.push(indexRelativePath);
+        }
+        return {
+            archivedNotes,
+            missingNotes,
+            updatedIndexFiles,
+            resultFiles,
+        };
+    }
+    const archivedResultPayload = buildArchivedResultPayload(options);
+    for (const [folder, notesConsumed] of groupedNotes.entries()) {
+        if (notesConsumed.length === 0) {
+            continue;
+        }
+        const archiveFolderRelativePath = `${ARCHIVE_PREFIX}${folder ? `${folder}/` : ""}`;
+        const archiveFolderPath = node_path_1.default.join(options.repoRoot, archiveFolderRelativePath);
+        (0, node_fs_1.mkdirSync)(archiveFolderPath, { recursive: true });
+        const resultRelativePath = `${archiveFolderRelativePath}.reconcile-${options.reconcileId}.json`;
+        (0, node_fs_1.writeFileSync)(node_path_1.default.join(options.repoRoot, resultRelativePath), JSON.stringify(archivedResultPayload, null, 2) + "\n", "utf-8");
+        resultFiles.push(resultRelativePath);
+        const indexRelativePath = `${archiveFolderRelativePath}cognition-index.json`;
+        writeIndex(node_path_1.default.join(options.repoRoot, indexRelativePath), {
+            reconcile_id: options.reconcileId,
+            run_id: options.runId,
+            reconciled_at: timestamp,
+            notes_consumed: notesConsumed,
+            polaris_md_updated: options.polarisMdUpdated,
+            summary_md_updated: options.summaryMdUpdated,
+        });
+        updatedIndexFiles.push(indexRelativePath);
+    }
+    return {
+        archivedNotes,
+        missingNotes,
+        updatedIndexFiles,
+        resultFiles,
+    };
+}

package/dist/cognition/closeout-librarian-types.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Types and schema validator for the closeout-librarian role.
+ *
+ * The Closeout Librarian runs exactly once per completed cluster, after all
+ * children are done and before PR creation. It reconciles cluster work into
+ * project cognition (POLARIS.md, SUMMARY.md), ingests documentation, validates
+ * links, and commits all documentation changes as a single librarian commit.
+ *
+ * The Librarian may NOT modify implementation code, runtime state, dispatch
+ * workers, or create PRs.
+ *
+ * Spec: smartdocs/specs/active/closeout-librarian-spec.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCloseoutLibrarianPacket = validateCloseoutLibrarianPacket;
+exports.validateCloseoutLibrarianResult = validateCloseoutLibrarianResult;
+exports.checkLibrarianResultGate = checkLibrarianResultGate;
+/**
+ * Validate a CloseoutLibrarianPacket. Returns an array of error strings; empty means valid.
+ *
+ * Performs lightweight top-level checks only: object presence, required field types,
+ * enum values, and array presence. Does NOT validate nested element schemas (e.g.,
+ * individual child_summaries entries), string formats (e.g., ISO dates), or cross-field
+ * consistency. Further semantic validation is performed by the Foreman via
+ * checkLibrarianResultGate and other runtime-spec result checks before finalize.
+ */
+function validateCloseoutLibrarianPacket(value) {
+    const errors = [];
+    if (typeof value !== "object" || value === null) {
+        return ["CloseoutLibrarianPacket must be a JSON object"];
+    }
+    const p = value;
+    if (p["role"] !== "closeout-librarian") {
+        errors.push('role must be "closeout-librarian"');
+    }
+    if (p["schema_version"] !== "1.0") {
+        errors.push('schema_version must be "1.0"');
+    }
+    if (typeof p["run_id"] !== "string" || !p["run_id"]) {
+        errors.push("missing or empty run_id");
+    }
+    if (typeof p["dispatch_id"] !== "string" || !p["dispatch_id"]) {
+        errors.push("missing or empty dispatch_id");
+    }
+    if (typeof p["cluster_id"] !== "string" || !p["cluster_id"]) {
+        errors.push("missing or empty cluster_id");
+    }
+    if (!Array.isArray(p["completed_children"]) || p["completed_children"].length === 0) {
+        errors.push("completed_children must be a non-empty array");
+    }
+    if (!Array.isArray(p["child_summaries"])) {
+        errors.push("child_summaries must be an array");
+    }
+    if (!Array.isArray(p["affected_folders"])) {
+        errors.push("affected_folders must be an array");
+    }
+    if (!Array.isArray(p["polaris_md_paths"])) {
+        errors.push("polaris_md_paths must be an array");
+    }
+    if (typeof p["result_path"] !== "string" || !p["result_path"]) {
+        errors.push("missing or empty result_path");
+    }
+    if (!Array.isArray(p["prohibited_write_paths"])) {
+        errors.push("prohibited_write_paths must be an array");
+    }
+    if (!Array.isArray(p["allowed_write_paths"])) {
+        errors.push("allowed_write_paths must be an array");
+    }
+    return errors;
+}
+/**
+ * Validate a CloseoutLibrarianResult. Returns an array of error strings; empty means valid.
+ *
+ * Performs lightweight top-level checks only: object presence, required field types,
+ * enum values, and array presence. Does NOT validate nested element schemas, string
+ * formats (e.g., reconciled_at ISO date), or cross-field consistency (e.g., whether
+ * commit_sha matches files_committed). Further semantic validation is performed by the
+ * Foreman via checkLibrarianResultGate and other runtime-spec result checks before finalize.
+ */
+function validateCloseoutLibrarianResult(value) {
+    const errors = [];
+    if (typeof value !== "object" || value === null) {
+        return ["CloseoutLibrarianResult must be a JSON object"];
+    }
+    const r = value;
+    if (r["role"] !== "closeout-librarian") {
+        errors.push('role must be "closeout-librarian"');
+    }
+    if (r["schema_version"] !== "1.0") {
+        errors.push('schema_version must be "1.0"');
+    }
+    if (typeof r["run_id"] !== "string" || !r["run_id"]) {
+        errors.push("missing or empty run_id");
+    }
+    if (typeof r["dispatch_id"] !== "string" || !r["dispatch_id"]) {
+        errors.push("missing or empty dispatch_id");
+    }
+    if (typeof r["cluster_id"] !== "string" || !r["cluster_id"]) {
+        errors.push("missing or empty cluster_id");
+    }
+    const validStatuses = ["success", "partial", "blocked", "failure"];
+    if (!validStatuses.includes(r["status"])) {
+        errors.push(`status must be one of: ${validStatuses.join(", ")}`);
+    }
+    if (r["commit_sha"] !== null && typeof r["commit_sha"] !== "string") {
+        errors.push("commit_sha must be a string or null");
+    }
+    if (!Array.isArray(r["files_committed"])) {
+        errors.push("files_committed must be an array");
+    }
+    if (!Array.isArray(r["polaris_md_updates"])) {
+        errors.push("polaris_md_updates must be an array");
+    }
+    if (!Array.isArray(r["summary_md_updates"])) {
+        errors.push("summary_md_updates must be an array");
+    }
+    if (!Array.isArray(r["docs_ingested"])) {
+        errors.push("docs_ingested must be an array");
+    }
+    if (!Array.isArray(r["docs_archived"])) {
+        errors.push("docs_archived must be an array");
+    }
+    if (!Array.isArray(r["yaml_updates"])) {
+        errors.push("yaml_updates must be an array");
+    }
+    if (!Array.isArray(r["cognition_archived"])) {
+        errors.push("cognition_archived must be an array");
+    }
+    if (typeof r["link_validation"] !== "object" || r["link_validation"] === null) {
+        errors.push("link_validation must be an object");
+    }
+    if (!Array.isArray(r["blockers"])) {
+        errors.push("blockers must be an array");
+    }
+    if (typeof r["reconciled_at"] !== "string") {
+        errors.push("reconciled_at must be a string");
+    }
+    if (typeof r["evidence_summary"] !== "string") {
+        errors.push("evidence_summary must be a string");
+    }
+    return errors;
+}
+/**
+ * Determine whether a CloseoutLibrarianResult allows the Foreman to proceed to finalize.
+ * Returns null if finalize may proceed; returns a blocker description string if not.
+ */
+function checkLibrarianResultGate(result) {
+    if (result.status === "success" || result.status === "partial") {
+        return null;
+    }
+    if (result.status === "blocked") {
+        const blocking = result.blockers.filter((b) => b.resolution_required);
+        if (blocking.length === 0) {
+            throw new Error("Invalid result: status 'blocked' but no resolution_required blockers");
+        }
+        const desc = blocking.map((b) => b.description).join("; ");
+        return `Closeout Librarian blocked: ${desc}`;
+    }
+    return `Closeout Librarian failed: ${result.evidence_summary}`;
+}