@lsctech/polaris 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ItIsYeBananaduck/Polaris/main/branding/assets/polaris-logo.png" alt="Polaris CLO" width="200" />
+</p>
+
+<h1 align="center">Polaris CLO</h1>
+<p align="center"><strong>Command Line Orchestrator</strong></p>
+<p align="center"><em>Navigate. Align. Orchestrate.</em></p>
+
+---
+
+Polaris is a taskchain orchestration framework for governed AI agent workflows. It dispatches, tracks, and finalizes implementation work across AI providers — keeping every run bounded, auditable, and connected to your issue tracker.
+
+## Install
+
+```bash
+npm install -g @lsctech/polaris
+```
+
+Requires **Node.js 22+**.
+
+## Quick Start
+
+```bash
+# Initialize Polaris in your repository
+polaris init --adopt
+
+# Check configuration
+polaris doctor
+
+# Start a governed run
+polaris run POL-123
+
+# Check status
+polaris status
+
+# Finalize completed work
+polaris finalize
+```
+
+## Configuration
+
+Polaris is configured via `polaris.config.json` at the repository root.
+
+```json
+{
+  "version": "1.0",
+  "repo": {
+    "name": "my-project",
+    "sourceRoots": ["src"]
+  },
+  "tracker": {
+    "adapter": "github",
+    "github": {
+      "enabled": true,
+      "owner": "my-org",
+      "repo": "my-project",
+      "labelPrefix": "status:"
+    }
+  }
+}
+```
+
+## Tracker Adapters
+
+| Adapter | Description |
+|---|---|
+| `github` | GitHub Issues — label-based lifecycle states, PAT auth |
+| `linear` | Linear — team/project scoped, API key auth |
+| `jira` | Jira Cloud — REST API v3, Basic auth |
+| `local` | Local file graph only, no external sync |
+
+Set credentials via environment variables:
+
+```bash
+export GITHUB_TOKEN=ghp_...
+export LINEAR_API_KEY=lin_api_...
+export JIRA_API_TOKEN=your_token
+```
+
+## Documentation
+
+- **[Setup Guide](docs/SETUP.md)** — Installation, tracker configuration, environment variables
+- **[Usage Guide](docs/USAGE.md)** — Daily workflow, commands, configuration reference, troubleshooting
+
+## License
+
+MIT — © LSC Technologies

package/dist/__mocks__/tool-server-linear.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcp_linear_save_issue = exports.mcp_linear_get_issue = exports.mcp_linear_get_issue_status = exports.mcp_linear_list_issues = exports.mcp_linear_list_projects = exports.mcp_linear_list_teams = void 0;
+/**
+ * Stub for @tool-server/linear used in test environments.
+ * The real module is an MCP runtime tool server — not an npm package.
+ * Tests that need specific behaviour should override with vi.mock().
+ */
+const mcp_linear_list_teams = async (..._args) => [];
+exports.mcp_linear_list_teams = mcp_linear_list_teams;
+const mcp_linear_list_projects = async (..._args) => [];
+exports.mcp_linear_list_projects = mcp_linear_list_projects;
+const mcp_linear_list_issues = async (..._args) => [];
+exports.mcp_linear_list_issues = mcp_linear_list_issues;
+const mcp_linear_get_issue_status = async (..._args) => [];
+exports.mcp_linear_get_issue_status = mcp_linear_get_issue_status;
+const mcp_linear_get_issue = async (..._args) => ({
+    id: 'stub-issue',
+    title: 'Stub Issue',
+    description: '',
+    state: { id: 'stub-state', name: 'Todo', type: 'unstarted' },
+    assignee: null,
+    createdAt: '2023-01-01T00:00:00.000Z',
+});
+exports.mcp_linear_get_issue = mcp_linear_get_issue;
+const mcp_linear_save_issue = async (..._args) => ({
+    id: 'stub-issue',
+    title: 'Stub Issue',
+    description: '',
+    state: { id: 'stub-state', name: 'Todo', type: 'unstarted' },
+    assignee: null,
+    createdAt: '2023-01-01T00:00:00.000Z',
+});
+exports.mcp_linear_save_issue = mcp_linear_save_issue;

package/dist/cli/adopt-approve.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistApprovedAdoptionPlan = persistApprovedAdoptionPlan;
+exports.logAdoptionApprovalTelemetry = logAdoptionApprovalTelemetry;
+exports.promptApproval = promptApproval;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:readline/promises");
+const adoption_plan_js_1 = require("./adoption-plan.js");
+function adoptionPlanJsonPath(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "adoption-plan.json");
+}
+function adoptionPlanMarkdownPath(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "adoption-plan.md");
+}
+function adoptionTelemetryPath(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "adoption-telemetry.jsonl");
+}
+function writeTelemetryEvent(repoRoot, event) {
+    const telemetryPath = adoptionTelemetryPath(repoRoot);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryPath), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryPath, `${JSON.stringify(event)}\n`, "utf-8");
+}
+function persistApprovedAdoptionPlan(plan, repoRoot = process.cwd(), now = new Date()) {
+    plan.approved = true;
+    plan.approved_at = plan.approved_at ?? now.toISOString();
+    const jsonPath = adoptionPlanJsonPath(repoRoot);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(jsonPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(jsonPath, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
+}
+function logAdoptionApprovalTelemetry(repoRoot, event) {
+    writeTelemetryEvent(repoRoot, event);
+}
+async function promptApproval(plan, options = {}) {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const stdout = options.stdout ?? process.stdout;
+    const stdin = options.stdin ?? process.stdin;
+    const markdownPath = adoptionPlanMarkdownPath(repoRoot);
+    const markdown = (0, node_fs_1.existsSync)(markdownPath)
+        ? (0, node_fs_1.readFileSync)(markdownPath, "utf-8")
+        : (0, adoption_plan_js_1.renderAdoptionPlanMarkdown)(plan);
+    stdout.write(`${markdown.replace(/\s*$/, "")}\n\n`);
+    const rl = (0, promises_1.createInterface)({
+        input: stdin,
+        output: stdout,
+    });
+    let response = "";
+    try {
+        response = await rl.question("Proceed with adoption? [y/N] ");
+    }
+    finally {
+        rl.close();
+    }
+    if (response.trim().toLowerCase() === "y") {
+        persistApprovedAdoptionPlan(plan, repoRoot, options.now ?? new Date());
+        return true;
+    }
+    stdout.write("Adoption aborted: explicit approval required.\n");
+    return false;
+}

package/dist/cli/adopt-cognition.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFolderCognition = generateFolderCognition;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const EXCLUDED_SEGMENTS = new Set(["node_modules", "dist", ".git"]);
+const SOURCE_FILE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".swift",
+    ".rb",
+    ".php",
+    ".c",
+    ".cc",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".cs",
+    ".scala",
+    ".sh",
+]);
+function toPosix(path) {
+    return path.replaceAll("\\", "/");
+}
+function normalizeFolder(path) {
+    const normalized = toPosix(path).replace(/^\.\//, "").replace(/\/+$/, "");
+    return normalized;
+}
+function toRootPrefix(path) {
+    const normalized = normalizeFolder(path);
+    return normalized.length > 0 ? `${normalized}/` : normalized;
+}
+function isUnderRoot(path, roots) {
+    const normalizedPath = normalizeFolder(path);
+    return roots
+        .map(toRootPrefix)
+        .filter((root) => root.length > 0)
+        .some((root) => normalizedPath === root.slice(0, -1) || normalizedPath.startsWith(root));
+}
+function hasExcludedSegments(path) {
+    const normalized = normalizeFolder(path);
+    if (normalized.startsWith(".polaris/runs/") || normalized === ".polaris/runs") {
+        return true;
+    }
+    if (normalized.startsWith(".polaris/bootstrap/") || normalized === ".polaris/bootstrap") {
+        return true;
+    }
+    return normalized.split("/").some((segment) => EXCLUDED_SEGMENTS.has(segment));
+}
+function isFolderEligible(path, inventory) {
+    const normalized = normalizeFolder(path);
+    if (normalized.length === 0)
+        return false;
+    if (normalized === "smartdocs" || normalized.startsWith("smartdocs/"))
+        return false;
+    if (isUnderRoot(normalized, inventory.generated_roots))
+        return false;
+    if (isUnderRoot(normalized, inventory.cache_roots))
+        return false;
+    if (isUnderRoot(normalized, inventory.fixture_roots))
+        return false;
+    if (hasExcludedSegments(normalized))
+        return false;
+    return true;
+}
+function countSourceFiles(dirPath, count = 0) {
+    if (count >= 3) {
+        return count;
+    }
+    let entries = [];
+    try {
+        entries = (0, node_fs_1.readdirSync)(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return count;
+    }
+    let sourceCount = count;
+    for (const entry of entries) {
+        const entryPath = (0, node_path_1.join)(dirPath, entry.name);
+        const normalized = toPosix(entryPath);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" ||
+                entry.name === "dist" ||
+                entry.name === ".git" ||
+                normalized.includes("/.polaris/runs/") ||
+                normalized.includes("/.polaris/bootstrap/")) {
+                continue;
+            }
+            sourceCount = countSourceFiles(entryPath, sourceCount);
+            if (sourceCount >= 3) {
+                return sourceCount;
+            }
+            continue;
+        }
+        if (entry.isFile()) {
+            const dotIndex = entry.name.lastIndexOf(".");
+            if (dotIndex > 0 && SOURCE_FILE_EXTENSIONS.has(entry.name.slice(dotIndex).toLowerCase())) {
+                sourceCount += 1;
+            }
+            if (sourceCount >= 3) {
+                return sourceCount;
+            }
+        }
+    }
+    return sourceCount;
+}
+function buildPolarisDraft(folder) {
+    const folderName = (0, node_path_1.basename)(folder);
+    return [
+        "<!-- polaris:draft -->",
+        `# ${folderName}`,
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        "## Purpose",
+        "",
+        "<!-- One paragraph describing what this folder does. -->",
+        "",
+        "**Domain:** unknown",
+        `**Route:** ${folder}`,
+        "**Taskchain:** unknown",
+        "",
+        "## What belongs here",
+        "",
+        "<!-- Describe the assets and responsibilities expected in this folder. -->",
+        "",
+        "## What does not belong here",
+        "",
+        "<!-- Describe content that should be routed elsewhere. -->",
+        "",
+    ].join("\n");
+}
+function buildSummaryDraft(folder) {
+    const folderName = (0, node_path_1.basename)(folder);
+    return [
+        "<!-- polaris:draft -->",
+        `# Summary — ${folderName}`,
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        `- Route: \`${folder}\``,
+        "- Canon status: draft",
+        "- Linked doctrine: `POLARIS.md`",
+        "",
+        "## Notes",
+        "",
+        "<!-- Add concise context, references, and ownership details for this folder. -->",
+        "",
+    ].join("\n");
+}
+function generateFolderCognition(plan, inventory) {
+    if (plan.dry_run) {
+        return Promise.resolve();
+    }
+    const repoRoot = (0, node_path_1.resolve)(process.cwd());
+    const folders = Array.from(new Set(inventory.likely_canonical_folders.map(normalizeFolder)));
+    for (const folder of folders) {
+        if (!isFolderEligible(folder, inventory)) {
+            continue;
+        }
+        const absoluteFolder = (0, node_path_1.join)(repoRoot, folder);
+        if (!(0, node_fs_1.existsSync)(absoluteFolder)) {
+            continue;
+        }
+        let folderStat;
+        try {
+            folderStat = (0, node_fs_1.statSync)(absoluteFolder);
+        }
+        catch {
+            continue;
+        }
+        if (!folderStat.isDirectory()) {
+            continue;
+        }
+        if (countSourceFiles(absoluteFolder) < 3) {
+            continue;
+        }
+        const polarisPath = (0, node_path_1.join)(absoluteFolder, "POLARIS.md");
+        if ((0, node_fs_1.existsSync)(polarisPath)) {
+            continue;
+        }
+        const summaryPath = (0, node_path_1.join)(absoluteFolder, "SUMMARY.md");
+        (0, node_fs_1.mkdirSync)(absoluteFolder, { recursive: true });
+        (0, node_fs_1.writeFileSync)(polarisPath, buildPolarisDraft(folder), "utf-8");
+        if (!(0, node_fs_1.existsSync)(summaryPath)) {
+            (0, node_fs_1.writeFileSync)(summaryPath, buildSummaryDraft(folder), "utf-8");
+        }
+    }
+    return Promise.resolve();
+}

package/dist/cli/adopt-instructions.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleInstructionFiles = handleInstructionFiles;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const DELEGATION_MARKERS = ["<!-- polaris:delegate", "POLARIS.md", "Polaris runtime"];
+function isSupportedInstructionPath(path) {
+    return (path === "CLAUDE.md" ||
+        path === "AGENTS.md" ||
+        path === ".github/copilot-instructions.md" ||
+        path === ".cursorrules" ||
+        path === ".aider.conf.yml" ||
+        path === "AIDER.md" ||
+        /^\.cursor\/rules\/.*\.md$/i.test(path) ||
+        /(^|\/)GEMINI\.md$/i.test(path));
+}
+function hasDoctrine(repoRoot) {
+    return ((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "POLARIS_RULES.md")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "POLARIS.md")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "active")));
+}
+function hasDelegationMarker(content) {
+    return DELEGATION_MARKERS.some((marker) => content.includes(marker));
+}
+function classifyInstruction(content, doctrineExists, _repoHints) {
+    if (hasDelegationMarker(content)) {
+        return { decision: "preserve", reason: "already contains Polaris delegation markers" };
+    }
+    if (!doctrineExists) {
+        return { decision: "preserve", reason: "no Polaris doctrine exists yet" };
+    }
+    // When POLARIS_RULES.md exists, all agent files become pointer-only.
+    // Substantive content is migrated to smartdocs/raw/migrated-instructions.
+    return { decision: "thin-adapter", reason: "POLARIS_RULES.md exists — convert to pointer" };
+}
+function toBackupFileName(sourcePath) {
+    const cleaned = sourcePath.replace(/^\.+\//, "").replaceAll("/", "__");
+    return cleaned.length > 0 ? cleaned : (0, node_path_1.basename)(sourcePath);
+}
+function reserveBackupPath(baseDirectory, sourcePath) {
+    const baseName = toBackupFileName(sourcePath);
+    let candidate = (0, node_path_1.join)(baseDirectory, baseName);
+    if (!(0, node_fs_1.existsSync)(candidate)) {
+        return candidate;
+    }
+    const dotIndex = baseName.lastIndexOf(".");
+    const stem = dotIndex > 0 ? baseName.slice(0, dotIndex) : baseName;
+    const ext = dotIndex > 0 ? baseName.slice(dotIndex) : "";
+    let index = 1;
+    while ((0, node_fs_1.existsSync)(candidate)) {
+        candidate = (0, node_path_1.join)(baseDirectory, `${stem}-${index}${ext}`);
+        index += 1;
+    }
+    return candidate;
+}
+function preserveOriginalContent(repoRoot, sourcePath, content) {
+    const archiveRoot = (0, node_path_1.join)(repoRoot, "smartdocs", "raw", "migrated-instructions");
+    (0, node_fs_1.mkdirSync)(archiveRoot, { recursive: true });
+    const backupPath = reserveBackupPath(archiveRoot, sourcePath);
+    (0, node_fs_1.writeFileSync)(backupPath, content, "utf-8");
+    const roundTrip = (0, node_fs_1.readFileSync)(backupPath, "utf-8");
+    if (roundTrip !== content) {
+        throw new Error(`Failed to preserve original instruction content for ${sourcePath}`);
+    }
+    return backupPath;
+}
+function buildThinAdapter(_sourcePath) {
+    return [
+        "# Polaris Managed Repository",
+        "",
+        "Read [POLARIS_RULES.md](POLARIS_RULES.md) before doing any work in this repository.",
+        "",
+    ].join("\n");
+}
+function appendInstructionProvenance(repoRoot, records) {
+    if (records.length === 0) {
+        return;
+    }
+    const provenancePath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-provenance.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, ".polaris"), { recursive: true });
+    let existing = {};
+    if ((0, node_fs_1.existsSync)(provenancePath)) {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(provenancePath, "utf-8"));
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const prior = Array.isArray(existing.instruction_file_actions)
+        ? existing.instruction_file_actions
+        : [];
+    const updated = {
+        ...existing,
+        updated_at: new Date().toISOString(),
+        instruction_file_actions: [...prior, ...records],
+    };
+    (0, node_fs_1.writeFileSync)(provenancePath, `${JSON.stringify(updated, null, 2)}\n`, "utf-8");
+}
+function handleInstructionFiles(plan, inventory) {
+    if (plan.dry_run) {
+        return Promise.resolve();
+    }
+    const repoRoot = (0, node_path_1.resolve)(process.cwd());
+    const doctrineExists = hasDoctrine(repoRoot);
+    const now = new Date().toISOString();
+    const candidates = Array.from(new Set(inventory.agent_instruction_files
+        .map((entry) => entry.path)
+        .filter((path) => isSupportedInstructionPath(path))));
+    const provenance = [];
+    for (const relativePath of candidates) {
+        const absolutePath = (0, node_path_1.join)(repoRoot, relativePath);
+        if (!(0, node_fs_1.existsSync)(absolutePath)) {
+            continue;
+        }
+        const originalContent = (0, node_fs_1.readFileSync)(absolutePath, "utf-8");
+        const { decision, reason } = classifyInstruction(originalContent, doctrineExists, []);
+        if (decision === "preserve") {
+            provenance.push({
+                source_path: relativePath,
+                decision,
+                reason,
+                backup_path: null,
+                timestamp: now,
+            });
+            continue;
+        }
+        const backupAbsolutePath = preserveOriginalContent(repoRoot, relativePath, originalContent);
+        (0, node_fs_1.writeFileSync)(absolutePath, buildThinAdapter(relativePath), "utf-8");
+        provenance.push({
+            source_path: relativePath,
+            decision,
+            reason,
+            backup_path: backupAbsolutePath.slice(repoRoot.length + 1).replaceAll("\\", "/"),
+            timestamp: now,
+        });
+    }
+    appendInstructionProvenance(repoRoot, provenance);
+    return Promise.resolve();
+}