@lsctech/polaris 0.3.21 → 0.3.23

package/dist/workspace/workspace/.polaris/skills/polaris-tools/README.md

@@ -1,63 +0,0 @@
-# polaris-tools skill
-
-Codex skill that exposes compact, read-only Polaris status helpers without dumping large state into chat context.
-
-## Installation prerequisite
-
-The Polaris CLI must be installed and resolvable before this skill will work.
-
-### Option A — link from the repo (development)
-
-```bash
-# From the Polaris repo root:
-npm run build
-npm link
-```
-
-After `npm link`, `polaris` is available globally on your `PATH`.
-
-### Option B — install globally
-
-```bash
-npm install -g polaris
-```
-
-### Verify
-
-```bash
-npm run polaris -- --version
-```
-
-If the binary is not found, the skill will attempt `npx --no-install polaris` as a fallback. If that also fails, the tool returns a clear error with install instructions.
-
-## Available tools
-
-| Tool | CLI equivalent | Description |
-|------|---------------|-------------|
-| `polaris_status` | `polaris status --json` | Compact current run summary (no full state dump) |
-| `polaris_loop_status` | `polaris loop status --json` | Compact loop subsystem summary (no full state dump) |
-
-`polaris_run` and `polaris_loop_continue` are recognized only as operator-only legacy names and return an error without invoking the CLI. The public CLI does not expose `polaris run`, and `polaris loop continue` is mutating: it checkpoints state and writes a bootstrap packet.
-
-The MCP safety model exposes `polaris_loop_continue_dry_run` and `polaris_loop_continue_confirmed` as a separate approval-envelope flow. This helper does not wrap continuation unless a true non-mutating CLI dry-run is added.
-
-`polaris finalize` remains manual/operator-only. Do not expose finalize as a normal tool until a confirmed finalize approval flow exists.
-
-## Usage from Codex
-
-Invoke the helper script from the repo root:
-
-```bash
-node .polaris/skills/polaris-tools/tools.js polaris_status
-node .polaris/skills/polaris-tools/tools.js polaris_loop_status
-```
-
-All tools return compact JSON on stdout. On error, exit code is non-zero and the JSON contains an `error` field.
-
-## Output contract
-
-Tools return only a compact JSON summary. They never dump the full `current-state.json` or worker transcript into chat. Text summaries are truncated to 600 characters.
-
-## Security note
-
-All CLI arguments are passed as explicit argument arrays via `spawnSync` — no shell string interpolation is used.

package/dist/workspace/workspace/.polaris/skills/polaris-tools/SKILL.md

@@ -1,94 +0,0 @@
----
-name: polaris-tools
-description: Exposes compact read-only Polaris status helpers. Direct run, ungated loop continuation, and finalize remain operator-only.
-role: foreman
-role_file: .polaris/roles/foreman.md
----
-
-## Command entrypoints
-
-This skill is the target for the following user commands:
-
-- `polaris-status`
-- `run polaris-status`
-
-When any of these commands are issued, load this skill packet **first** before any other action.
-See `.polaris/skills/ROUTING.md` for the full routing protocol.
-
----
-
-# polaris-tools
-
-Use this skill when the user wants to inspect Polaris run state without dumping large artifacts:
-- `polaris status --json` / compact current-state summary → `polaris_status`
-- `polaris loop status --json` / compact current-state summary → `polaris_loop_status`
-
-Do not use this skill as a casual mutation surface. `polaris_run` and `polaris_loop_continue` are operator-only legacy names in the helper and return an error without invoking the CLI. Finalize is manual/operator-only until a confirmed finalize approval flow exists.
-
-## Prerequisites
-
-The Polaris CLI must be installed before using this skill. See `README.md` for installation steps.
-
-## Tool behaviours
-
-### polaris_status()
-
-Attempts `polaris status --json`. If the CLI is not available, reads and summarises
-`.taskchain_artifacts/polaris-run/current-state.json` compactly. Returns:
-```json
-{
-  "tool": "polaris_status",
-  "run_id": "...",
-  "cluster_id": "...",
-  "status": "...",
-  "active_child": null,
-  "next_open_child": "...",
-  "completed_children": [...],
-  "open_children": [...],
-  "updated_at": "..."
-}
-```
-
-### polaris_loop_status()
-
-Attempts `polaris loop status --json`. If the CLI is not available, reads and summarises
-`.taskchain_artifacts/polaris-run/current-state.json` compactly. Returns the same compact shape with `"tool": "polaris_loop_status"`.
-
-### Operator-only names
-
-`polaris_run(issue_id)` and `polaris_loop_continue(provider?)` are not exposed as casual helpers. They return:
-```json
-{"tool":"polaris_loop_continue","error":"operator_only","message":"..."}
-```
-
-The MCP safety model has a separate `polaris_loop_continue_dry_run` / `polaris_loop_continue_confirmed` approval-envelope flow. This helper does not wrap continuation unless a true non-mutating CLI dry-run is added.
-
-Never dump the full state file into chat.
-
-## How to invoke
-
-Run the helper script from the repo root:
-
-```
-node .polaris/skills/polaris-tools/tools.js <tool> [args...]
-```
-
-Examples:
-```
-node .polaris/skills/polaris-tools/tools.js polaris_status
-node .polaris/skills/polaris-tools/tools.js polaris_loop_status
-```
-
-The script prints compact JSON to stdout and exits 0 on success, non-zero on error.
-
-## Discovery order for the Polaris binary
-
-1. `polaris` on `PATH` (installed via `npm link` or `npm install -g`)
-2. `npx --no-install polaris` (project-local install)
-3. Error emitted clearly if neither resolves
-
-## Error format
-
-```json
-{"error":"polaris binary not found. Install via: npm link (from repo root) or npm install -g polaris","tool":"<tool>"}
-```

package/dist/workspace/workspace/.polaris/skills/polaris-tools/tools.js

@@ -1,191 +0,0 @@
-#!/usr/bin/env node
-/**
- * polaris-tools — Codex plugin skill helper
- *
- * Exposes compact read-only helpers backed by local Polaris CLI invocation.
- * Prints compact JSON to stdout. Never dumps full state files.
- *
- * Usage:
- *   node tools.js polaris_status
- *   node tools.js polaris_loop_status
- */
-
-'use strict';
-
-const { spawnSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-// ── binary resolution ──────────────────────────────────────────────────────
-
-/**
- * Returns { cmd, args } for the polaris binary, or null if not found.
- * Uses spawnSync with argument arrays — no shell interpolation.
- */
-function findPolaris() {
-  // 1. polaris on PATH
-  const probe = spawnSync('polaris', ['--version'], { stdio: 'pipe', timeout: 5_000 });
-  if (probe.status === 0 && !probe.error) return { cmd: 'polaris', args: [] };
-
-  // 2. npx polaris (project-local, no network fetch)
-  const npxProbe = spawnSync('npx', ['--no-install', 'polaris', '--version'], {
-    stdio: 'pipe',
-    timeout: 10_000,
-  });
-  if (npxProbe.status === 0) return { cmd: 'npx', args: ['--no-install', 'polaris'] };
-
-  return null;
-}
-
-function binaryError(tool) {
-  return {
-    error:
-      'polaris binary not found. Install via: npm link (from repo root) or npm install -g polaris',
-    tool,
-  };
-}
-
-// ── compact runner ─────────────────────────────────────────────────────────
-
-/**
- * Runs a command safely using spawnSync with an explicit args array.
- * @param {string} cmd
- * @param {string[]} args
- */
-function runSafe(cmd, args) {
-  const result = spawnSync(cmd, args, {
-    stdio: 'pipe',
-    timeout: 120_000,
-    encoding: 'utf8',
-  });
-  return {
-    exit_code: result.status ?? 1,
-    stdout: (result.stdout || '').trim(),
-    stderr: (result.stderr || '').trim(),
-  };
-}
-
-function truncate(str, max = 300) {
-  if (!str || str.length <= max) return str;
-  return str.slice(0, max) + ' ...(truncated)';
-}
-
-// ── tools ──────────────────────────────────────────────────────────────────
-
-function printJson(value, exitCode = 0) {
-  console.log(JSON.stringify(value));
-  process.exit(exitCode);
-}
-
-function operatorOnly(tool, cliEquivalent) {
-  printJson(
-    {
-      tool,
-      error: 'operator_only',
-      message:
-        `${cliEquivalent} is mutating or deferred and is not exposed as a casual Codex plugin helper. Use the governed operator workflow with an explicit approval boundary.`,
-    },
-    1
-  );
-}
-
-function compactState(tool, state) {
-  return {
-    tool,
-    run_id: state.run_id,
-    cluster_id: state.cluster_id,
-    status: state.status,
-    active_child: state.active_child || null,
-    next_open_child: state.next_open_child ?? null,
-    completed_children: Array.isArray(state.completed_children) ? state.completed_children : [],
-    open_children: Array.isArray(state.open_children) ? state.open_children : [],
-    updated_at: state.updated_at,
-  };
-}
-
-function compactCliStatus(tool, exit_code, stdout, stderr) {
-  if (exit_code !== 0) {
-    return {
-      tool,
-      exit_code,
-      error: 'polaris status command failed',
-      summary: truncate(stderr || stdout, 600),
-    };
-  }
-
-  try {
-    return {
-      ...compactState(tool, JSON.parse(stdout)),
-      exit_code,
-    };
-  } catch {
-    return { tool, exit_code, summary: truncate(stdout || stderr, 600) };
-  }
-}
-
-function statusFromStateFile(tool) {
-  const stateFile = path.join(
-    process.cwd(),
-    '.taskchain_artifacts',
-    'polaris-run',
-    'current-state.json'
-  );
-  if (!fs.existsSync(stateFile)) return null;
-
-  try {
-    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-    return compactState(tool, state);
-  } catch (e) {
-    return {
-      tool,
-      error: `Failed to parse current-state.json: ${e.message}`,
-    };
-  }
-}
-
-function polarisStatus(tool, cliArgs) {
-  const bin = findPolaris();
-
-  if (bin) {
-    const { exit_code, stdout, stderr } = runSafe(bin.cmd, [...bin.args, ...cliArgs]);
-    const result = compactCliStatus(tool, exit_code, stdout, stderr);
-    printJson(result, exit_code === 0 ? 0 : 1);
-  }
-
-  const fallback = statusFromStateFile(tool);
-  if (fallback) {
-    printJson(fallback, fallback.error ? 1 : 0);
-  }
-
-  printJson(binaryError(tool), 1);
-}
-
-function unknownTool(tool) {
-  console.log(
-    JSON.stringify({
-      error: `Unknown tool: "${tool}". Valid tools: polaris_status, polaris_loop_status. Operator-only legacy names: polaris_run, polaris_loop_continue`,
-    })
-  );
-  process.exit(1);
-}
-
-// ── dispatch ───────────────────────────────────────────────────────────────
-
-const [, , tool, ...rest] = process.argv;
-
-switch (tool) {
-  case 'polaris_run':
-    operatorOnly('polaris_run', 'polaris run <issue_id>');
-    break;
-  case 'polaris_loop_continue':
-    operatorOnly('polaris_loop_continue', 'polaris loop continue');
-    break;
-  case 'polaris_status':
-    polarisStatus('polaris_status', ['status', '--json']);
-    break;
-  case 'polaris_loop_status':
-    polarisStatus('polaris_loop_status', ['loop', 'status', '--json']);
-    break;
-  default:
-    unknownTool(tool);
-}