@jaggerxtrm/specialists 2.1.9 → 2.1.11

package/README.md

@@ -193,6 +193,33 @@ Pre-script output is formatted as `<pre_flight_context>` XML and available in `t
 
 ---
 
+## CLI
+
+Once installed globally, the `specialists` command provides:
+
+| Command | Description |
+|---------|-------------|
+| `specialists install` | Full-stack installer: pi, beads, dolt, MCP registration, hooks, scaffold |
+| `specialists list` | List all discovered specialists with model, description, and scope |
+| `specialists version` | Print the installed package version |
+| `specialists` | Start the MCP server (called by Claude Code — not for direct use) |
+
+### specialists list
+
+```
+Specialists (9)
+
+  auto-remediation   google-gemini-cli/gemini-3-flash-preview  Autonomous self-healing workflow...  [project]
+  bug-hunt           anthropic/claude-sonnet-4-6               Autonomously investigates bugs...    [project]
+  codebase-explorer  google-gemini-cli/gemini-3-flash-preview  Explores codebase structure...       [project]
+  init-session       anthropic/claude-haiku-4-5                Gathers git/commit context...        [project]
+  overthinker        anthropic/claude-sonnet-4-6               Multi-phase deep reasoning...        [project]
+```
+
+Scopes: `[project]` = `./specialists/` (or `.claude/specialists/`), `[user]` = `~/.agents/specialists/`
+
+---
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -17490,11 +17490,6 @@ var init_schema = __esm(() => {
 });
 
 // src/specialist/loader.ts
-var exports_loader = {};
-__export(exports_loader, {
-  checkStaleness: () => checkStaleness,
-  SpecialistLoader: () => SpecialistLoader
-});
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -17592,11 +17587,331 @@ var init_loader = __esm(() => {
   init_schema();
 });
 
-// src/index.ts
+// src/cli/install.ts
+var exports_install = {};
+__export(exports_install, {
+  run: () => run
+});
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname as dirname2, join as join4 } from "node:path";
+async function run() {
+  const installerPath = join4(dirname2(fileURLToPath(import.meta.url)), "..", "..", "bin", "install.js");
+  execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
+}
+var init_install = () => {};
+
+// src/cli/version.ts
+var exports_version = {};
+__export(exports_version, {
+  run: () => run2
+});
 import { createRequire as createRequire2 } from "node:module";
+async function run2() {
+  const req = createRequire2(import.meta.url);
+  const pkg = req("../package.json");
+  console.log(`${pkg.name} v${pkg.version}`);
+}
+var init_version = () => {};
+
+// src/cli/list.ts
+var exports_list = {};
+__export(exports_list, {
+  run: () => run3,
+  parseArgs: () => parseArgs,
+  ArgParseError: () => ArgParseError
+});
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--category") {
+      const value = argv[++i];
+      if (!value || value.startsWith("--")) {
+        throw new ArgParseError("--category requires a value");
+      }
+      result.category = value;
+      continue;
+    }
+    if (token === "--scope") {
+      const value = argv[++i];
+      if (value !== "project" && value !== "user") {
+        throw new ArgParseError(`--scope must be "project" or "user", got: "${value ?? ""}"`);
+      }
+      result.scope = value;
+      continue;
+    }
+  }
+  return result;
+}
+async function run3() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(3));
+  } catch (err) {
+    if (err instanceof ArgParseError) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const loader = new SpecialistLoader;
+  let specialists = await loader.list(args.category);
+  if (args.scope) {
+    specialists = specialists.filter((s) => s.scope === args.scope);
+  }
+  if (specialists.length === 0) {
+    console.log("No specialists found.");
+    return;
+  }
+  const nameWidth = Math.max(...specialists.map((s) => s.name.length), 4);
+  const modelWidth = Math.max(...specialists.map((s) => s.model.length), 5);
+  console.log(`
+${bold(`Specialists (${specialists.length})`)}
+`);
+  for (const s of specialists) {
+    const name = cyan(s.name.padEnd(nameWidth));
+    const model = dim(s.model.padEnd(modelWidth));
+    const scopeTag = yellow(`[${s.scope}]`);
+    console.log(`  ${name}  ${model}  ${s.description}  ${scopeTag}`);
+  }
+  console.log();
+}
+var dim = (s) => `\x1B[2m${s}\x1B[0m`, bold = (s) => `\x1B[1m${s}\x1B[0m`, cyan = (s) => `\x1B[36m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, ArgParseError;
+var init_list = __esm(() => {
+  init_loader();
+  ArgParseError = class ArgParseError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ArgParseError";
+    }
+  };
+});
+
+// src/cli/init.ts
+var exports_init = {};
+__export(exports_init, {
+  run: () => run4
+});
+import { existsSync as existsSync3, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join as join5 } from "node:path";
+function ok(msg) {
+  console.log(`  ${green("✓")} ${msg}`);
+}
+function skip(msg) {
+  console.log(`  ${yellow2("○")} ${msg}`);
+}
+async function run4() {
+  const cwd = process.cwd();
+  console.log(`
+${bold2("specialists init")}
+`);
+  const specialistsDir = join5(cwd, "specialists");
+  if (existsSync3(specialistsDir)) {
+    skip("specialists/ already exists");
+  } else {
+    mkdirSync(specialistsDir, { recursive: true });
+    ok("created specialists/");
+  }
+  const agentsPath = join5(cwd, "AGENTS.md");
+  if (existsSync3(agentsPath)) {
+    const existing = readFileSync(agentsPath, "utf-8");
+    if (existing.includes(AGENTS_MARKER)) {
+      skip("AGENTS.md already has Specialists section");
+    } else {
+      writeFileSync(agentsPath, existing.trimEnd() + `
+
+` + AGENTS_BLOCK, "utf-8");
+      ok("appended Specialists section to AGENTS.md");
+    }
+  } else {
+    writeFileSync(agentsPath, AGENTS_BLOCK, "utf-8");
+    ok("created AGENTS.md with Specialists section");
+  }
+  console.log(`
+${bold2("Done!")}
+`);
+  console.log(`  ${dim2("Next steps:")}`);
+  console.log(`  1. Add your specialists to ${yellow2("specialists/")}`);
+  console.log(`  2. Run ${yellow2("specialists list")} to verify they are discovered`);
+  console.log(`  3. Restart Claude Code to pick up AGENTS.md changes
+`);
+}
+var bold2 = (s) => `\x1B[1m${s}\x1B[0m`, green = (s) => `\x1B[32m${s}\x1B[0m`, yellow2 = (s) => `\x1B[33m${s}\x1B[0m`, dim2 = (s) => `\x1B[2m${s}\x1B[0m`, AGENTS_BLOCK, AGENTS_MARKER = "## Specialists";
+var init_init = __esm(() => {
+  AGENTS_BLOCK = `
+## Specialists
+
+Call \`specialist_init\` at the start of every session to bootstrap context and
+see available specialists. Use \`use_specialist\` or \`start_specialist\` to
+delegate heavy tasks (code review, bug hunting, deep reasoning) to the right
+specialist without user intervention.
+`.trimStart();
+});
+
+// src/cli/edit.ts
+var exports_edit = {};
+__export(exports_edit, {
+  run: () => run5
+});
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+function parseArgs2(argv) {
+  const name = argv[0];
+  if (!name || name.startsWith("--")) {
+    console.error("Usage: specialists edit <name> --<field> <value> [--dry-run]");
+    console.error(`  Fields: ${Object.keys(FIELD_MAP).join(", ")}`);
+    process.exit(1);
+  }
+  let field;
+  let value;
+  let dryRun = false;
+  let scope;
+  for (let i = 1;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (token === "--scope") {
+      const v = argv[++i];
+      if (v !== "project" && v !== "user") {
+        console.error(`Error: --scope must be "project" or "user", got: "${v ?? ""}"`);
+        process.exit(1);
+      }
+      scope = v;
+      continue;
+    }
+    if (token.startsWith("--") && !field) {
+      field = token.slice(2);
+      value = argv[++i];
+      continue;
+    }
+  }
+  if (!field || !FIELD_MAP[field]) {
+    console.error(`Error: unknown or missing field. Valid fields: ${Object.keys(FIELD_MAP).join(", ")}`);
+    process.exit(1);
+  }
+  if (value === undefined || value === "") {
+    console.error(`Error: --${field} requires a value`);
+    process.exit(1);
+  }
+  if (field === "permission" && !VALID_PERMISSIONS.includes(value)) {
+    console.error(`Error: --permission must be one of: ${VALID_PERMISSIONS.join(", ")}`);
+    process.exit(1);
+  }
+  if (field === "timeout" && !/^\d+$/.test(value)) {
+    console.error("Error: --timeout must be a number (milliseconds)");
+    process.exit(1);
+  }
+  return { name, field, value, dryRun, scope };
+}
+function setIn(doc2, path, value) {
+  let node = doc2;
+  for (let i = 0;i < path.length - 1; i++) {
+    node = node.get(path[i], true);
+  }
+  const leaf = path[path.length - 1];
+  if (Array.isArray(value)) {
+    node.set(leaf, value);
+  } else {
+    node.set(leaf, value);
+  }
+}
+async function run5() {
+  const args = parseArgs2(process.argv.slice(3));
+  const { name, field, value, dryRun, scope } = args;
+  const loader = new SpecialistLoader;
+  const all = await loader.list();
+  const match = all.find((s) => s.name === name && (scope === undefined || s.scope === scope));
+  if (!match) {
+    const hint = scope ? ` (scope: ${scope})` : "";
+    console.error(`Error: specialist "${name}" not found${hint}`);
+    console.error(`  Run ${yellow3("specialists list")} to see available specialists`);
+    process.exit(1);
+  }
+  const raw = readFileSync2(match.filePath, "utf-8");
+  const doc2 = $parseDocument(raw);
+  const yamlPath = FIELD_MAP[field];
+  let typedValue = value;
+  if (field === "timeout") {
+    typedValue = parseInt(value, 10);
+  } else if (field === "tags") {
+    typedValue = value.split(",").map((t) => t.trim()).filter(Boolean);
+  }
+  setIn(doc2, yamlPath, typedValue);
+  const updated = doc2.toString();
+  if (dryRun) {
+    console.log(`
+${bold3(`[dry-run] ${match.filePath}`)}
+`);
+    console.log(dim3("--- current"));
+    console.log(dim3(`+++ updated`));
+    const oldLines = raw.split(`
+`);
+    const newLines = updated.split(`
+`);
+    newLines.forEach((line, i) => {
+      if (line !== oldLines[i]) {
+        if (oldLines[i] !== undefined)
+          console.log(dim3(`- ${oldLines[i]}`));
+        console.log(green2(`+ ${line}`));
+      }
+    });
+    console.log();
+    return;
+  }
+  writeFileSync2(match.filePath, updated, "utf-8");
+  const displayValue = field === "tags" ? `[${typedValue.join(", ")}]` : String(typedValue);
+  console.log(`${green2("✓")} ${bold3(name)}: ${yellow3(field)} = ${displayValue}` + dim3(` (${match.filePath})`));
+}
+var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`, yellow3 = (s) => `\x1B[33m${s}\x1B[0m`, dim3 = (s) => `\x1B[2m${s}\x1B[0m`, FIELD_MAP, VALID_PERMISSIONS;
+var init_edit = __esm(() => {
+  init_dist();
+  init_loader();
+  FIELD_MAP = {
+    model: ["specialist", "execution", "model"],
+    "fallback-model": ["specialist", "execution", "fallback_model"],
+    description: ["specialist", "metadata", "description"],
+    permission: ["specialist", "execution", "permission_required"],
+    timeout: ["specialist", "execution", "timeout_ms"],
+    tags: ["specialist", "metadata", "tags"]
+  };
+  VALID_PERMISSIONS = ["READ_ONLY", "LOW", "MEDIUM", "HIGH"];
+});
+
+// src/cli/help.ts
+var exports_help = {};
+__export(exports_help, {
+  run: () => run6
+});
+async function run6() {
+  const lines = [
+    "",
+    bold4("specialists <command>"),
+    "",
+    "Commands:",
+    ...COMMANDS.map(([cmd, desc]) => `  ${cmd.padEnd(COL_WIDTH)}    ${dim4(desc)}`),
+    "",
+    dim4("Run 'specialists <command> --help' for command-specific options."),
+    ""
+  ];
+  console.log(lines.join(`
+`));
+}
+var bold4 = (s) => `\x1B[1m${s}\x1B[0m`, dim4 = (s) => `\x1B[2m${s}\x1B[0m`, COMMANDS, COL_WIDTH;
+var init_help = __esm(() => {
+  COMMANDS = [
+    ["install", "Full-stack installer: pi, beads, dolt, MCP registration, hooks"],
+    ["list", "List available specialists with model and description"],
+    ["version", "Print installed version"],
+    ["init", "Initialize specialists in the current project"],
+    ["edit", "Edit a specialist field  (e.g. --model, --description)"],
+    ["run", "Run a specialist with a prompt"],
+    ["status", "Show system health (pi, beads, MCP)"],
+    ["help", "Show this help message"]
+  ];
+  COL_WIDTH = Math.max(...COMMANDS.map(([cmd]) => cmd.length));
+});
 
 // node_modules/zod/v4/core/core.js
 var NEVER2 = Object.freeze({
@@ -25880,51 +26195,37 @@ class SpecialistsServer {
 }
 
 // src/index.ts
-var __dirname2 = dirname2(fileURLToPath(import.meta.url));
 var sub = process.argv[2];
-var dim = (s) => `\x1B[2m${s}\x1B[0m`;
-var bold = (s) => `\x1B[1m${s}\x1B[0m`;
-var cyan = (s) => `\x1B[36m${s}\x1B[0m`;
-var yellow = (s) => `\x1B[33m${s}\x1B[0m`;
-async function run() {
+async function run7() {
   if (sub === "install") {
-    const installerPath = join4(__dirname2, "..", "bin", "install.js");
-    execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
-    return;
+    const { run: handler } = await Promise.resolve().then(() => (init_install(), exports_install));
+    return handler();
   }
   if (sub === "version") {
-    const req = createRequire2(import.meta.url);
-    const pkg = req("../package.json");
-    console.log(`${pkg.name} v${pkg.version}`);
-    return;
+    const { run: handler } = await Promise.resolve().then(() => (init_version(), exports_version));
+    return handler();
   }
   if (sub === "list") {
-    const { SpecialistLoader: SpecialistLoader2 } = await Promise.resolve().then(() => (init_loader(), exports_loader));
-    const loader = new SpecialistLoader2;
-    const specialists = await loader.list();
-    if (specialists.length === 0) {
-      console.log("No specialists found.");
-      return;
-    }
-    const nameWidth = Math.max(...specialists.map((s) => s.name.length), 4);
-    const modelWidth = Math.max(...specialists.map((s) => s.model.length), 5);
-    console.log(`
-${bold(`Specialists (${specialists.length})`)}
-`);
-    for (const s of specialists) {
-      const name = cyan(s.name.padEnd(nameWidth));
-      const model = dim(s.model.padEnd(modelWidth));
-      const scope = yellow(`[${s.scope}]`);
-      console.log(`  ${name}  ${model}  ${s.description}  ${scope}`);
-    }
-    console.log();
-    return;
+    const { run: handler } = await Promise.resolve().then(() => (init_list(), exports_list));
+    return handler();
+  }
+  if (sub === "init") {
+    const { run: handler } = await Promise.resolve().then(() => (init_init(), exports_init));
+    return handler();
+  }
+  if (sub === "edit") {
+    const { run: handler } = await Promise.resolve().then(() => (init_edit(), exports_edit));
+    return handler();
+  }
+  if (sub === "help" || sub === "--help" || sub === "-h") {
+    const { run: handler } = await Promise.resolve().then(() => (init_help(), exports_help));
+    return handler();
   }
   logger.info("Starting Specialists MCP Server...");
   const server = new SpecialistsServer;
   await server.start();
 }
-run().catch((error2) => {
+run7().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.9",
+  "version": "2.1.11",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",