@jaybeeuu/agent-cortex 2.1.0 → 2.2.0

package/lib/cli.mjs

@@ -1,9 +1,28 @@
+/**
+ * Result of parsing the CLI argv. Every branch returns `command`; the rest are
+ * populated only for the commands that accept them.
+ * @typedef {object} ParsedArgs
+ * @property {"help" | "version" | "install" | "migrate" | "unknown"} command
+ * @property {string | null} [harness]
+ * @property {string} [name]
+ * @property {string} [optionError]
+ * @property {boolean} [dryRun]
+ * @property {string} [output]
+ * @property {string} [pluginRoot]
+ * @property {boolean} [requireRegister]
+ * @property {boolean} [apply]
+ * @property {string} [dir]
+ */
+
+/** @typedef {{ key: string, boolean?: boolean }} OptionSpec */
+
 const SUPPORTED_HARNESSES = ["claude", "pi"];
 
 // Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
 // the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
 // malformed options surface as `optionError` on the parsed result; the CLI
 // prints them and exits 1.
+/** @type {Record<string, OptionSpec>} */
 const INSTALL_OPTIONS = {
   "--dry-run": { key: "dryRun", boolean: true },
   "--output": { key: "output" },
@@ -11,11 +30,22 @@ const INSTALL_OPTIONS = {
   "--require-register": { key: "requireRegister", boolean: true },
 };
 
+/**
+ * Parse the CLI argv.
+ * @param {string[]} argv
+ * @returns {ParsedArgs}
+ */
 export function parseArgs(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     return { command: "help" };
   }
 
+  // Like `--help`, the version flags are only recognised as the first argument,
+  // so they never shadow a command's own options.
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    return { command: "version" };
+  }
+
   const [command, ...rest] = argv;
 
   if (command === "install") {
@@ -26,6 +56,7 @@ export function parseArgs(argv) {
       i = 1;
     }
 
+    /** @type {Record<string, string | true>} */
     const options = {};
     for (; i < rest.length; i++) {
       const arg = rest[i];
@@ -57,9 +88,54 @@ export function parseArgs(argv) {
     return { command: "install", harness, ...options };
   }
 
+  if (command === "migrate") {
+    // Dry run is the default, so `--apply` is the only state-changing flag;
+    // `--dry-run` stays accepted for scripts that pass it explicitly. `--dir`
+    // points the ideas step at a workspace that keeps its idea files elsewhere.
+    let sawApply = false;
+    let sawDryRun = false;
+    /** @type {string | undefined} */
+    let dir;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--help" || arg === "-h") return { command: "help" };
+      if (arg === "--apply") {
+        sawApply = true;
+        continue;
+      }
+      if (arg === "--dry-run") {
+        sawDryRun = true;
+        continue;
+      }
+      // Support both `--dir=<path>` and `--dir <path>`, like install's `--output`.
+      const inlineDir = arg.startsWith("--dir=") ? arg.slice("--dir=".length) : null;
+      if (inlineDir !== null && inlineDir !== "") {
+        dir = inlineDir;
+        continue;
+      }
+      if (arg === "--dir" || inlineDir !== null) {
+        const value = rest[i + 1];
+        if (inlineDir !== null || value == null || value.startsWith("--")) {
+          return { command: "migrate", optionError: `Missing value for "--dir". Run "agent-cortex --help" for usage.` };
+        }
+        dir = value;
+        i += 1;
+        continue;
+      }
+      return { command: "migrate", optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+    }
+    if (sawApply && sawDryRun) {
+      return { command: "migrate", optionError: '"--apply" and "--dry-run" are mutually exclusive.' };
+    }
+    return dir === undefined ? { command: "migrate", apply: sawApply } : { command: "migrate", apply: sawApply, dir };
+  }
+
   return { command: "unknown", name: command };
 }
 
+/**
+ * @returns {string}
+ */
 export function buildHelpText() {
   return `Usage: agent-cortex <command> [options]
 
@@ -125,11 +201,24 @@ Commands:
                                               cannot register the staged package
                                               (missing from PATH); default warns and
                                               prints the manual commands
-  --help, -h          Show this help text`;
+  migrate             Migrate the current beads workspace to the latest
+                      agent-cortex migration version, applying versioned steps
+                      in order (repo-agnostic — works in any beads workspace)
+                      Options:
+                        (no option)     Dry run — print the pending plan, write nothing
+                        --apply         Apply every pending step, verifying each
+                        --dir <path>    Read idea files from <path> instead of
+                                        docs/ideas (step v2's source)
+  --help, -h          Show this help text
+  --version, -V       Print the package version`;
 }
 
+/**
+ * @param {string | null | undefined} harness
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
 export function validateHarness(harness) {
-  if (harness === null) {
+  if (harness === null || harness === undefined) {
     return {
       ok: false,
       error: `Missing harness argument. Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -13,12 +13,35 @@
   "bin": {
     "agent-cortex": "./bin/agent-cortex.mjs"
   },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "skills/",
+    "agents/",
+    "extensions/*.ts",
+    "extensions/lib/",
+    "extensions/*/*.ts",
+    "extensions/*/*.md",
+    "extensions/*/package.json",
+    "extensions/*/agents/",
+    "extensions/*/prompts/",
+    "hooks/",
+    "claude/",
+    "claude-extras/",
+    "token-map.json",
+    "token-map.README.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
+    "@types/node": "^22.20.1",
     "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
     "yaml": "^2.0.0"
   },
   "pi": {
@@ -39,10 +62,11 @@
     "check:sync": "node scripts/check-no-sync.mjs",
     "check:skills": "node scripts/check-skill-frontmatter.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
-    "typecheck": "pnpm -r typecheck",
+    "typecheck": "tsc --noEmit -p tsconfig.json && pnpm -r typecheck",
+    "verify": "pnpm typecheck && pnpm test",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
+    "publish-package": "pnpm verify && TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "publish-noop": "echo 'No publish: the merged PR carries the no-publish label.'",
     "release": "changeset publish"
   }

package/scripts/check-changeset.mjs

@@ -10,6 +10,10 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+/**
+ * @param {string} raw
+ * @returns {string[]}
+ */
 function readLabels(raw) {
   try {
     return JSON.parse(raw);

package/scripts/check-no-sync.mjs

@@ -14,7 +14,11 @@ const SELF = "scripts/check-no-sync.mjs";
 
 const SYNC_CALL = /\b\w*Sync\s*\(/;
 
-/** Recursively collect files under dir, skipping this script and node_modules. */
+/**
+ * Recursively collect files under dir, skipping this script and node_modules.
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
 async function collect(dir) {
   const out = [];
   const entries = await readdir(dir, { withFileTypes: true });

package/scripts/lib/compose-agent.mjs

@@ -32,7 +32,49 @@
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
-/** True when a path exists (stat succeeds). */
+/** @typedef {{ base: string, relative: string }} PathSpec */
+
+/**
+ * Parsed token-map.json. `tools` maps a canonical tool key to its per-harness
+ * name (null = the harness has no equivalent); `paths` maps a path key to its
+ * per-harness spec (a literal string, or a {base, relative} pair resolved
+ * recursively through the same table).
+ * @typedef {object} TokenMap
+ * @property {number} [version]
+ * @property {Record<string, Record<string, string | null>>} tools
+ * @property {Record<string, Record<string, string | PathSpec>>} paths
+ */
+
+/**
+ * Options shared by the composer entry points.
+ * @typedef {object} ComposeOptions
+ * @property {boolean} [dropNullTools]
+ * @property {string} [pluginRoot]
+ * @property {boolean} [resolveRelativePaths]
+ * @property {(message: string) => void} [warn]
+ * @property {string} [context]
+ */
+
+/**
+ * Parsed and schema-checked harness frontmatter.json.
+ * @typedef {object} AgentFrontmatter
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} tools
+ * @property {string} [model]
+ * @property {string} [argumentHint]
+ */
+
+/**
+ * A composed agent: its frontmatter plus the substituted body.
+ * @typedef {AgentFrontmatter & { body: string }} ComposedAgent
+ */
+
+/**
+ * True when a path exists (stat succeeds).
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
 async function pathExists(p) {
   try {
     await stat(p);
@@ -47,6 +89,7 @@ async function pathExists(p) {
 const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
 const PATH_RE = /\{\{PATH:([^}]+)\}\}/g;
 
+/** @returns {void} */
 function noop() {}
 
 /**
@@ -62,8 +105,8 @@ function noop() {}
  *
  * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
  * @param {string} harness  Harness id: "claude" | "pi"
- * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
- * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
+ * @param {TokenMap} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {ComposeOptions} [options]  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
  * @returns {string}
  */
 export function substituteTokens(content, harness, tokenMap, options = {}) {
@@ -100,7 +143,8 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  * @param {string} root    Package root (contains agents/ and token-map.json)
  * @param {string} name    Agent directory name (e.g. "ralph", "plan")
  * @param {string} harness Harness id: "claude" | "pi"
- * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
+ * @param {ComposeOptions} [options]
+ * @returns {Promise<ComposedAgent>}
  */
 export async function composeAgent(root, name, harness, options = {}) {
   const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
@@ -144,14 +188,21 @@ export async function composeAgent(root, name, harness, options = {}) {
 const REQUIRED_FIELDS = ["name", "description", "tools"];
 const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
 
-/** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
+/**
+ * Parse and schema-check a harness frontmatter.json (strict, per agents/README.md).
+ * @param {string} path
+ * @param {string} name
+ * @param {string} harness
+ * @returns {Promise<AgentFrontmatter>}
+ */
 async function parseFrontmatter(path, name, harness) {
   const raw = await readFile(path, "utf-8");
+  /** @type {Record<string, unknown>} */
   let fm;
   try {
     fm = JSON.parse(raw);
   } catch (err) {
-    throw new Error(`agent "${name}": invalid JSON in ${path}: ${err.message}`);
+    throw new Error(`agent "${name}": invalid JSON in ${path}: ${/** @type {Error} */ (err).message}`);
   }
   if (typeof fm !== "object" || fm === null) {
     throw new Error(`agent "${name}": ${path} must be a JSON object`);
@@ -188,6 +239,11 @@ async function parseFrontmatter(path, name, harness) {
  * With the installer options (`pluginRoot`, `resolveRelativePaths`) the
  * plugin_root base and bare relative paths resolve against the actual install
  * layout instead.
+ * @param {string} arg
+ * @param {string} harness
+ * @param {TokenMap} tokenMap
+ * @param {ComposeOptions} [opts]
+ * @returns {string}
  */
 function resolvePath(arg, harness, tokenMap, opts = {}) {
   const entry = tokenMap.paths?.[arg];
@@ -217,9 +273,9 @@ function resolvePath(arg, harness, tokenMap, opts = {}) {
  * translation in extensions/agent-modes/discover.ts.
  *
  * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
- * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {TokenMap} tokenMap Parsed token-map.json (from loadTokenMap)
  * @param {string} harness  Harness id: "claude" | "pi"
- * @param {object} options  { warn }
+ * @param {ComposeOptions} [options]  { warn }
  * @returns {string[]}
  */
 export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}) {
@@ -242,7 +298,11 @@ export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}
 
 // ─── Token map ───────────────────────────────────────────────────────────────
 
-/** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
+/**
+ * Load token-map.json from the package root; missing/incomplete maps hard-fail.
+ * @param {string} root
+ * @returns {Promise<TokenMap>}
+ */
 export async function loadTokenMap(root) {
   const path = join(root, "token-map.json");
   let raw;

package/scripts/lib/fs.mjs

@@ -12,7 +12,11 @@
 
 import { stat } from "node:fs/promises";
 
-/** True when `p` exists and is a regular file; false on any error. */
+/**
+ * True when `p` exists and is a regular file; false on any error.
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
 export async function isFile(p) {
   try {
     return (await stat(p)).isFile();
@@ -21,7 +25,11 @@ export async function isFile(p) {
   }
 }
 
-/** True when `p` exists and is a directory; false on any error. */
+/**
+ * True when `p` exists and is a directory; false on any error.
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
 export async function isDirectory(p) {
   try {
     return (await stat(p)).isDirectory();