@lsctech/polaris 0.4.4 → 0.4.6

package/dist/smartdocs-engine/seed-instructions.js

@@ -4,15 +4,20 @@ exports.DRAFT_MARKER = void 0;
 exports.hasDraftMarker = hasDraftMarker;
 exports.generateDraft = generateDraft;
 exports.generateSummaryDraft = generateSummaryDraft;
+exports.generateBundleRootIndex = generateBundleRootIndex;
+exports.generateDirectoryIndex = generateDirectoryIndex;
 exports.seedInstructions = seedInstructions;
 exports.seedSummary = seedSummary;
 exports.seedInstructionsAll = seedInstructionsAll;
 exports.seedSummaryAll = seedSummaryAll;
+exports.seedIndex = seedIndex;
+exports.seedIndexAll = seedIndexAll;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const loader_js_1 = require("../config/loader.js");
 const atlas_js_1 = require("../map/atlas.js");
 const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
+const doctrine_js_1 = require("./doctrine.js");
 exports.DRAFT_MARKER = "<!-- polaris:draft -->";
 function hasDraftMarker(filePath) {
     try {
@@ -176,6 +181,136 @@ function generateSummaryDraft(targetDir, repoRoot, _allRoutes) {
     ];
     return lines.join("\n");
 }
+const RESERVED_INDEX_NAMES = new Set(["index.md", "POLARIS.md", "SUMMARY.md", "log.md"]);
+function isReservedIndexName(name) {
+    return RESERVED_INDEX_NAMES.has(name);
+}
+function listConceptFiles(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".md") && !isReservedIndexName(e.name))
+            .map((e) => (0, node_path_1.join)(dir, e.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function conceptLabel(filePath) {
+    try {
+        const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+        const fm = (0, doctrine_js_1.parseFrontMatter)(content);
+        const base = (0, node_path_1.basename)(filePath);
+        return fm.description || fm.title || base.replace(/\.md$/, "");
+    }
+    catch {
+        return (0, node_path_1.basename)(filePath).replace(/\.md$/, "");
+    }
+}
+function collectSmartDocsDirs(dir, root, result = []) {
+    try {
+        const rel = (0, node_path_1.relative)(root, dir).replace(/\\/g, "/");
+        if (rel.split("/").some((s) => s === "raw" || s.startsWith("."))) {
+            return result;
+        }
+        result.push(rel);
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith(".") || entry.name === "raw")
+                continue;
+            const full = (0, node_path_1.join)(dir, entry.name);
+            collectSmartDocsDirs(full, root, result);
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return result;
+}
+function generateBundleRootIndex(repoRoot, allRoutes) {
+    const lines = [
+        "---",
+        "okf_version: \"0.1\"",
+        "---",
+        "",
+        exports.DRAFT_MARKER,
+        "# SmartDocs — Polaris Cognition Bundle",
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        "## Governance",
+        "",
+    ];
+    const doctrineDir = (0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "active");
+    const doctrineFiles = listConceptFiles(doctrineDir);
+    if (doctrineFiles.length > 0) {
+        for (const file of doctrineFiles) {
+            const relPath = (0, node_path_1.relative)((0, node_path_1.join)(repoRoot, "smartdocs"), file).replace(/\\/g, "/");
+            lines.push(`- [${conceptLabel(file)}](${relPath})`);
+        }
+    }
+    else {
+        lines.push("- [Doctrine — Active](doctrine/active/)");
+    }
+    lines.push("");
+    lines.push("## Specs", "");
+    const specsDir = (0, node_path_1.join)(repoRoot, "smartdocs", "specs", "active");
+    const specsFiles = listConceptFiles(specsDir);
+    if (specsFiles.length > 0) {
+        for (const file of specsFiles) {
+            const relPath = (0, node_path_1.relative)((0, node_path_1.join)(repoRoot, "smartdocs"), file).replace(/\\/g, "/");
+            lines.push(`- [${conceptLabel(file)}](${relPath})`);
+        }
+    }
+    else {
+        lines.push("- [Specs — Active](specs/active/)");
+    }
+    lines.push("");
+    lines.push("## Routes", "");
+    const instructionFiles = [
+        ...new Set(Object.values(allRoutes).map((e) => e.instructionFile).filter(Boolean)),
+    ].sort();
+    if (instructionFiles.length > 0) {
+        for (const file of instructionFiles) {
+            lines.push(`- [${file}](../${file})`);
+        }
+    }
+    else {
+        lines.push("<!-- Route POLARIS.md files will be listed here from atlas signals. -->");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function generateDirectoryIndex(targetDir, repoRoot) {
+    const absDir = (0, node_path_1.resolve)(repoRoot, targetDir);
+    const dirLabel = (0, node_path_1.basename)(absDir) || "SmartDocs";
+    const files = listConceptFiles(absDir);
+    const lines = [
+        "---",
+        "okf_version: \"0.1\"",
+        "---",
+        "",
+        exports.DRAFT_MARKER,
+        `# ${dirLabel}`,
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        "## Concepts",
+        "",
+    ];
+    if (files.length > 0) {
+        for (const file of files) {
+            const relPath = (0, node_path_1.relative)(absDir, file).replace(/\\/g, "/");
+            lines.push(`- [${conceptLabel(file)}](${relPath})`);
+        }
+    }
+    else {
+        lines.push("<!-- No concept files in this directory yet. -->");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
 function seedInstructions(targetPath, repoRoot, opts = {}) {
     const absTarget = (0, node_path_1.resolve)(repoRoot, targetPath);
     // Path traversal check: ensure absTarget is within repoRoot
@@ -333,3 +468,78 @@ function seedSummaryAll(repoRoot, opts = {}) {
     }
     return { written, skippedExists, skippedDraft, skippedIneligible, skippedRoot };
 }
+function seedIndex(targetPath, repoRoot, opts = {}) {
+    const absTarget = (0, node_path_1.resolve)(repoRoot, targetPath);
+    const relCheck = (0, node_path_1.relative)(repoRoot, absTarget);
+    if (relCheck.startsWith("..") || relCheck.startsWith("/")) {
+        throw new Error(`Path traversal detected: target path is outside repo root`);
+    }
+    // Reject targets outside smartdocs/
+    const relTarget = relCheck.replace(/\\/g, "/");
+    if (!relTarget.startsWith("smartdocs/") && relTarget !== "smartdocs") {
+        throw new Error(`seedIndex only writes index.md under smartdocs/; rejecting target: ${relTarget}`);
+    }
+    const outFile = (0, node_path_1.join)(absTarget, "index.md");
+    if ((0, node_fs_1.existsSync)(outFile)) {
+        if (hasDraftMarker(outFile)) {
+            return "skipped-draft";
+        }
+        return "skipped-exists";
+    }
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const atlasPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const allRoutes = {
+        ...(0, atlas_js_1.readFileRoutes)(atlasPath),
+        ...(0, atlas_js_1.readNeedsReview)(atlasPath),
+    };
+    const isBundleRoot = relTarget === "smartdocs";
+    const content = isBundleRoot
+        ? generateBundleRootIndex(repoRoot, allRoutes)
+        : generateDirectoryIndex(relTarget, repoRoot);
+    if (!opts.dryRun) {
+        (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+    }
+    return "written";
+}
+function seedIndexAll(repoRoot, opts = {}) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const atlasPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const allRoutes = {
+        ...(0, atlas_js_1.readFileRoutes)(atlasPath),
+        ...(0, atlas_js_1.readNeedsReview)(atlasPath),
+    };
+    const smartdocsRoot = (0, node_path_1.resolve)(repoRoot, "smartdocs");
+    if (!(0, node_fs_1.existsSync)(smartdocsRoot)) {
+        return { written: [], skippedExists: [], skippedDraft: [], skippedIneligible: [] };
+    }
+    const dirs = collectSmartDocsDirs(smartdocsRoot, repoRoot);
+    const smartdocsRel = "smartdocs";
+    if (!dirs.includes(smartdocsRel)) {
+        dirs.unshift(smartdocsRel);
+    }
+    const written = [];
+    const skippedExists = [];
+    const skippedDraft = [];
+    for (const relDir of dirs) {
+        const absDir = (0, node_path_1.resolve)(repoRoot, relDir);
+        const outFile = (0, node_path_1.join)(absDir, "index.md");
+        if ((0, node_fs_1.existsSync)(outFile)) {
+            if (hasDraftMarker(outFile)) {
+                skippedDraft.push(relDir);
+            }
+            else {
+                skippedExists.push(relDir);
+            }
+            continue;
+        }
+        const isBundleRoot = relDir === "smartdocs";
+        const content = isBundleRoot
+            ? generateBundleRootIndex(repoRoot, allRoutes)
+            : generateDirectoryIndex(relDir, repoRoot);
+        if (!opts.dryRun) {
+            (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+        }
+        written.push(relDir);
+    }
+    return { written, skippedExists, skippedDraft, skippedIneligible: [] };
+}

package/dist/tracker/adapters/linear/index.js

@@ -190,6 +190,36 @@ class LinearGraphqlClient {
       `, { id });
         return data.issue;
     }
+    async getIssueStateOptions(id) {
+        const data = await this.graphql(`
+        query PolarisLinearIssueStateOptions($id: String!) {
+          issue(id: $id) {
+            state { id }
+            team {
+              states(first: 250) {
+                nodes { id name type }
+              }
+            }
+          }
+        }
+      `, { id });
+        if (!data.issue)
+            return null;
+        return {
+            currentStateId: data.issue.state?.id ?? null,
+            states: data.issue.team?.states?.nodes ?? [],
+        };
+    }
+    async updateIssueState(id, stateId) {
+        const data = await this.graphql(`
+        mutation PolarisLinearIssueUpdateState($id: String!, $stateId: String!) {
+          issueUpdate(id: $id, input: { stateId: $stateId }) {
+            success
+          }
+        }
+      `, { id, stateId });
+        return data.issueUpdate.success;
+    }
 }
 /**
  * Implements the Linear direct adapter for synchronizing issues.
@@ -530,7 +560,7 @@ class LinearAdapter {
      * @param evidence - Optional evidence for the transition (e.g., commit hash).
      * @returns A lifecycle transition result indicating success, skip, or failure.
      */
-    async transitionLifecycleState(taskId, lifecycleState, evidence) {
+    async transitionLifecycleState(taskId, lifecycleState, _evidence) {
         if (lifecycleState === "no_status_change") {
             return {
                 applied: false,
@@ -538,17 +568,82 @@ class LinearAdapter {
                 skipReason: "Lifecycle state is 'no_status_change', skipping transition",
             };
         }
-        // Linear requires team-specific state IDs for state transitions.
-        // This implementation is a placeholder - full implementation would need:
-        // 1. Fetch available states for the issue's team
-        // 2. Map normalized lifecycle state to a specific Linear state ID
-        // 3. Use GraphQL mutation to update the issue state
-        console.warn(`LinearAdapter: transitionLifecycleState not fully implemented. Would transition ${taskId} to ${lifecycleState}.`);
-        return {
-            applied: false,
-            skipped: true,
-            skipReason: "Lifecycle state transitions are not yet implemented for Linear adapter",
+        let stateOptions;
+        try {
+            stateOptions = await this.linearClient.getIssueStateOptions(taskId);
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: `Failed to fetch Linear workflow states for ${taskId}: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (!stateOptions) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `Linear issue '${taskId}' not found`,
+            };
+        }
+        const targetState = this.resolveWorkflowState(stateOptions.states, lifecycleState);
+        if (!targetState) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `No Linear workflow state on this issue's team maps to lifecycle state '${lifecycleState}'`,
+            };
+        }
+        if (targetState.id === stateOptions.currentStateId) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `Issue is already in target state '${targetState.name}'`,
+            };
+        }
+        try {
+            const success = await this.linearClient.updateIssueState(taskId, targetState.id);
+            if (!success) {
+                return {
+                    applied: false,
+                    skipped: false,
+                    error: `Linear issueUpdate mutation for ${taskId} returned success: false`,
+                };
+            }
+            return { applied: true, skipped: false };
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * Picks the Linear workflow state that best matches a normalized lifecycle state.
+     *
+     * Prefers exact `type` alignment (Linear's own backlog/unstarted/started/completed/canceled
+     * classification) so custom state names don't need to match `mapNativeStatus`'s heuristics;
+     * falls back to the first state whose name heuristically maps to the target state.
+     */
+    resolveWorkflowState(states, lifecycleState) {
+        const typeCandidates = {
+            backlog: ["backlog", "unstarted"],
+            in_progress: ["started"],
+            in_review: ["started"],
+            done: ["completed"],
+            blocked: ["started"],
+            cancelled: ["canceled", "cancelled"],
         };
+        const byHeuristic = states.filter((s) => this.mapNativeStatus(s.name).lifecycleState === lifecycleState);
+        if (byHeuristic.length === 1)
+            return byHeuristic[0];
+        const wantedTypes = typeCandidates[lifecycleState] ?? [];
+        const byType = (byHeuristic.length > 0 ? byHeuristic : states).filter((s) => wantedTypes.includes(s.type));
+        if (byType.length > 0)
+            return byType[0];
+        return byHeuristic[0] ?? null;
     }
     /**
      * Adds a comment to a Linear issue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",