@lsctech/polaris 0.3.29 → 0.4.1

package/dist/agent-plugin/args.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSlashCommandArgs = validateSlashCommandArgs;
+/**
+ * Validate positional arguments against the command's declared arg spec.
+ *
+ * Rules:
+ * - `--help` / `-h` anywhere in argv returns a help request (no validation).
+ * - Required positional arguments must be present.
+ * - No more positional arguments than declared are accepted.
+ * - Empty strings are treated as a type mismatch.
+ */
+function validateSlashCommandArgs(command, argv = []) {
+    const help = argv.includes("--help") || argv.includes("-h");
+    if (help) {
+        return { ok: true, value: { command, positional: [], help: true } };
+    }
+    const positional = argv.filter((arg) => !arg.startsWith("-"));
+    const requiredCount = command.args.filter((arg) => arg.required).length;
+    const maxCount = command.args.length;
+    if (positional.length < requiredCount) {
+        return {
+            ok: false,
+            error: {
+                kind: "arity",
+                message: `/${command.name} requires ${requiredCount} positional argument(s) but received ${positional.length}.`,
+            },
+        };
+    }
+    if (positional.length > maxCount) {
+        return {
+            ok: false,
+            error: {
+                kind: "arity",
+                message: `/${command.name} accepts at most ${maxCount} positional argument(s) but received ${positional.length}.`,
+            },
+        };
+    }
+    for (const value of positional) {
+        if (value.trim() === "") {
+            return {
+                ok: false,
+                error: {
+                    kind: "type",
+                    message: `Arguments to /${command.name} must be non-empty strings.`,
+                },
+            };
+        }
+    }
+    // ponytail: support optional typed args (e.g. number, enum) when the manifest
+    // adds a `type` field; for now only string/empty-string checks are required.
+    if (hasTypedArgs(command.args)) {
+        for (let i = 0; i < positional.length; i++) {
+            const arg = command.args[i];
+            const value = positional[i];
+            if (arg.type && !validateArgType(value, arg.type)) {
+                return {
+                    ok: false,
+                    error: {
+                        kind: "type",
+                        message: `Argument \`${arg.name}\` for /${command.name} must be a valid ${arg.type}.`,
+                    },
+                };
+            }
+        }
+    }
+    return { ok: true, value: { command, positional, help: false } };
+}
+function hasTypedArgs(args) {
+    return args.some((arg) => arg.type !== undefined);
+}
+function validateArgType(value, type) {
+    if (type === "identifier") {
+        return /^[A-Za-z0-9_-]+$/.test(value);
+    }
+    return true;
+}

package/dist/agent-plugin/claude-generator.js

@@ -0,0 +1,158 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIM_VERSION = void 0;
+exports.generateClaudeShim = generateClaudeShim;
+exports.generateAllClaudeShims = generateAllClaudeShims;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commands_js_1 = require("./commands.js");
+/**
+ * Host-specific shim generator for Claude Code (.claude/commands/).
+ *
+ * Reads the neutral SLASH_COMMANDS manifest and writes one
+ * `.claude/commands/polaris-<verb>.md` file per verb.
+ *
+ * Skill-backed verbs route through the existing packet+chain path:
+ *   1. Read .polaris/skills/<skill>/SKILL.md
+ *   2. Run `polaris skill packet <skill>`
+ *   3. Execute the chain
+ *
+ * CLI-backed verbs delegate directly to the real CLI command.
+ *
+ * Version stamp: each shim carries a `<!-- polaris-shim-version: <version> -->` comment
+ * so the sync command (child 4) can detect drift.
+ */
+/** Version string baked into every generated shim. */
+exports.SHIM_VERSION = "1";
+/**
+ * Generate the markdown body for a Claude Code slash-command shim.
+ * Host specifics are isolated here; the manifest itself is neutral.
+ */
+function generateClaudeShim(command) {
+    const argUsage = command.args.length > 0
+        ? command.args.map((a) => (a.required ? `<${a.name}>` : `[${a.name}]`)).join(" ")
+        : "";
+    const usage = argUsage ? `/${command.name} ${argUsage}` : `/${command.name}`;
+    if (command.kind === "skill") {
+        const argLines = command.args.length > 0
+            ? command.args
+                .map((a) => `- \`${a.name}\`${a.required ? " (required)" : " (optional)"} — ${a.description}`)
+                .join("\n")
+            : "None.";
+        return `<!-- polaris-shim-version: ${exports.SHIM_VERSION} -->
+# /${command.name}
+
+${command.description}
+
+## Usage
+
+\`\`\`text
+${usage}
+\`\`\`
+
+## Arguments
+
+${argLines}
+
+## Routing
+
+This slash command is a shim around the **${command.skill}** Polaris skill packet.
+It does not implement a parallel runtime — it routes through the existing packet+chain path.
+
+See \`${command.routing}\` for the full routing protocol and skill directory resolution.
+
+## Execution
+
+1. Look up \`/${command.name}\` in \`${command.routing}\` to find the target skill directory.
+2. Read \`.polaris/skills/<target-skill>/SKILL.md\` — it is the authoritative instruction source.
+3. Run the skill bootloader:
+   \`\`\`bash
+   polaris skill packet ${command.skill}${command.args.length > 0 ? " $ARGUMENTS" : ""}
+   \`\`\`
+   Do not begin work until a packet is returned.
+   If no packet is produced, stop and report: **Polaris could not authorize this run.**
+4. Execute the chain as instructed in the packet.
+`;
+    }
+    // CLI-backed command
+    const argLines = command.args.length > 0
+        ? command.args
+            .map((a) => `- \`${a.name}\`${a.required ? " (required)" : " (optional)"} — ${a.description}`)
+            .join("\n")
+        : "None.";
+    return `<!-- polaris-shim-version: ${exports.SHIM_VERSION} -->
+# /${command.name}
+
+${command.description}
+
+## Usage
+
+\`\`\`text
+${usage}
+\`\`\`
+
+## Arguments
+
+${argLines}
+
+## Execution
+
+Run the following CLI command:
+
+\`\`\`bash
+${command.command}
+\`\`\`
+`;
+}
+/**
+ * Write all Claude Code shim files to `outDir` (default: `.claude/commands`).
+ * Creates the directory if it does not exist.
+ * Returns the list of files written.
+ */
+function generateAllClaudeShims(outDir = ".claude/commands") {
+    fs.mkdirSync(outDir, { recursive: true });
+    const written = [];
+    const seen = new Set();
+    for (const command of commands_js_1.SLASH_COMMANDS) {
+        if (seen.has(command.name))
+            continue;
+        seen.add(command.name);
+        const filePath = path.join(outDir, `${command.name}.md`);
+        fs.writeFileSync(filePath, generateClaudeShim(command), "utf8");
+        written.push(filePath);
+    }
+    return written;
+}

package/dist/agent-plugin/commands.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLASH_COMMAND_BY_NAME = exports.SLASH_COMMANDS = void 0;
+exports.resolveSlashCommand = resolveSlashCommand;
+exports.SLASH_COMMANDS = [
+    {
+        name: "polaris-run",
+        kind: "skill",
+        skill: "run",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [
+            {
+                name: "cluster_id",
+                required: true,
+                description: "Cluster ID to execute (e.g., POL-257)",
+            },
+        ],
+        description: "Execute a Polaris run cluster via the Foreman skill packet",
+    },
+    {
+        name: "polaris-analyze",
+        kind: "skill",
+        skill: "analyze",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [
+            {
+                name: "cluster_id",
+                required: true,
+                description: "Cluster ID to analyze (e.g., POL-257)",
+            },
+        ],
+        description: "Analyze a cluster and produce an implementation plan via the Analyst skill packet",
+    },
+    {
+        name: "polaris-init",
+        kind: "cli",
+        command: "polaris init",
+        args: [],
+        description: "Initialize a new Polaris workspace",
+    },
+    {
+        name: "polaris-adopt",
+        kind: "cli",
+        command: "polaris adopt",
+        args: [],
+        description: "Adopt Polaris into an existing repository",
+    },
+    {
+        name: "polaris-reconcile",
+        kind: "skill",
+        skill: "triage",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [
+            {
+                name: "target",
+                required: true,
+                description: "Reconciliation target (e.g., smartdocs or a cluster ID)",
+            },
+        ],
+        description: "Reconcile project cognition via the triage skill packet",
+    },
+    {
+        name: "polaris-status",
+        kind: "cli",
+        command: "polaris status",
+        args: [],
+        description: "Print the current Polaris loop run state summary",
+    },
+];
+exports.SLASH_COMMAND_BY_NAME = Object.fromEntries(exports.SLASH_COMMANDS.map((command) => [command.name, command]));
+function resolveSlashCommand(name) {
+    return exports.SLASH_COMMAND_BY_NAME[name];
+}

package/dist/agent-plugin/help.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUsage = generateUsage;
+exports.generateHelp = generateHelp;
+exports.generateErrorMessage = generateErrorMessage;
+exports.generateResponse = generateResponse;
+/**
+ * Help and error-message generation for slash-command invocations.
+ *
+ * Produces `--help`-style output directly from the neutral manifest so the
+ * same text can be used by any host shim. Error messages include the same
+ * help block so users see both the failure and the correct usage.
+ */
+/**
+ * Build a usage line from the command's arg spec.
+ * Required args are shown as `<name>`; optional as `[name]`.
+ */
+function generateUsage(command) {
+    const argUsage = command.args
+        .map((arg) => (arg.required ? `<${arg.name}>` : `[${arg.name}]`))
+        .join(" ");
+    return argUsage ? `/${command.name} ${argUsage}` : `/${command.name}`;
+}
+/**
+ * Generate `--help`-style output for a single manifest verb.
+ */
+function generateHelp(command) {
+    const argLines = command.args.length > 0
+        ? command.args
+            .map((arg) => `- \`${arg.name}\`${arg.required ? " (required)" : " (optional)"} — ${arg.description}`)
+            .join("\n")
+        : "None.";
+    return `/${command.name}
+
+${command.description}
+
+Usage:
+
+\`\`\`
+${generateUsage(command)}
+\`\`\`
+
+Arguments:
+
+${argLines}
+
+Use \`--help\` or \`-h\` to show this message.`;
+}
+/**
+ * Generate an error message that includes the command's help block.
+ */
+function generateErrorMessage(command, error) {
+    return `Error: ${error.message}
+
+${generateHelp(command)}`;
+}
+/**
+ * Convenience helper that returns the rendered message for a validation result.
+ * Returns `null` when the input is valid and no help/error text is needed.
+ */
+function generateResponse(command, result) {
+    if (!result.ok) {
+        return generateErrorMessage(command, result.error);
+    }
+    if (result.value.help) {
+        return generateHelp(command);
+    }
+    return null;
+}

package/dist/agent-plugin/sync.js

@@ -0,0 +1,108 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectShimDrift = detectShimDrift;
+exports.syncShims = syncShims;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commands_js_1 = require("./commands.js");
+const claude_generator_js_1 = require("./claude-generator.js");
+/**
+ * Workspace sync and versioning for generated agent-plugin shims.
+ *
+ * Responsibilities:
+ * 1. Detect drift between on-disk shims and the current SLASH_COMMANDS manifest
+ *    / ROUTING.md (stale version stamps, missing files, orphaned files).
+ * 2. Regenerate and re-stamp all shims when called.
+ * 3. Integrate with the asset-install path (called from adopt-assets.ts).
+ */
+/** Pattern used to read the version stamp from a shim file. */
+const VERSION_STAMP_RE = /<!--\s*polaris-shim-version:\s*(\S+)\s*-->/;
+/**
+ * Inspect `outDir` and return a drift report comparing on-disk shims against
+ * the current SLASH_COMMANDS manifest and SHIM_VERSION.
+ */
+function detectShimDrift(outDir = ".claude/commands") {
+    const stale = [];
+    const missing = [];
+    const orphaned = [];
+    const expectedNames = new Set(commands_js_1.SLASH_COMMANDS.map((c) => `${c.name}.md`));
+    // Check each manifest command against the on-disk file
+    for (const command of commands_js_1.SLASH_COMMANDS) {
+        const filePath = path.join(outDir, `${command.name}.md`);
+        if (!fs.existsSync(filePath)) {
+            missing.push(command.name);
+            continue;
+        }
+        const content = fs.readFileSync(filePath, "utf8");
+        const match = VERSION_STAMP_RE.exec(content);
+        if (!match || match[1] !== claude_generator_js_1.SHIM_VERSION) {
+            stale.push(command.name);
+        }
+    }
+    // Check for orphaned shim files (on disk but not in manifest)
+    if (fs.existsSync(outDir)) {
+        for (const entry of fs.readdirSync(outDir)) {
+            if (!entry.endsWith(".md"))
+                continue;
+            if (!expectedNames.has(entry)) {
+                orphaned.push(entry.replace(/\.md$/, ""));
+            }
+        }
+    }
+    return {
+        stale,
+        missing,
+        orphaned,
+        hasDrift: stale.length > 0 || missing.length > 0 || orphaned.length > 0,
+    };
+}
+/**
+ * Regenerate all shims and return what was written plus the prior drift state.
+ *
+ * This is the primary entry point for both `polaris agent-plugin sync` and
+ * the adopt-assets install step.
+ */
+function syncShims(outDir = ".claude/commands") {
+    const drift = detectShimDrift(outDir);
+    const written = (0, claude_generator_js_1.generateAllClaudeShims)(outDir);
+    for (const name of drift.orphaned) {
+        const orphanPath = path.join(outDir, `${name}.md`);
+        if (fs.existsSync(orphanPath)) {
+            fs.rmSync(orphanPath);
+        }
+    }
+    return { written, drift };
+}

package/dist/autoresearch/dev-gate.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Dev gate: autoresearch commands are only allowed inside a Polaris development context.
+ *
+ * "Polaris dev context" = the working directory or one of its ancestors contains a
+ * `package.json` whose `name` field equals `"@lsctech/polaris"`.
+ *
+ * This is intentionally narrow: it must match the monorepo where Polaris is developed,
+ * not arbitrary consumer repos that happen to depend on it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPolarisDevContext = isPolarisDevContext;
+exports.assertPolarisDevContext = assertPolarisDevContext;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function findPackageJson(startDir) {
+    let dir = (0, node_path_1.resolve)(startDir);
+    const root = (0, node_path_1.dirname)(dir); // stop at filesystem root
+    for (let i = 0; i < 20; i++) {
+        const candidate = (0, node_path_1.join)(dir, "package.json");
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir)
+            break; // reached root
+        dir = parent;
+    }
+    return null;
+}
+function isPolarisDevContext(startDir = process.cwd()) {
+    const pkgPath = findPackageJson(startDir);
+    if (!pkgPath)
+        return false;
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf-8"));
+        return pkg["name"] === "@lsctech/polaris";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Throws if not in a Polaris dev context.
+ * Call this at the start of any dev-gated command.
+ */
+function assertPolarisDevContext(startDir) {
+    if (!isPolarisDevContext(startDir)) {
+        throw new Error("polaris autoresearch score is a dev-only command and can only run inside the Polaris development repository.\n" +
+            "It is not available in consumer repos.");
+    }
+}