@jjlabsio/claude-crew 0.1.33 → 0.1.35

package/scripts/crew-agent-runner.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+import { build } from "./lib/build.mjs";
+import { loadContracts } from "./lib/contracts.mjs";
+import {
+  loadCatalog,
+  loadProjectConfig,
+  loadUserConfig
+} from "./lib/config.mjs";
+import { parseArgv } from "./lib/cli.mjs";
+import {
+  dispatch,
+  DispatchError,
+  formatDispatchProviderGuardMessage
+} from "./lib/dispatch.mjs";
+import { installHooks } from "./lib/installHooks.mjs";
+import { prepareDispatch } from "./lib/prepare.mjs";
+import { renderFollowup } from "./lib/renderFollowup.mjs";
+import { renderPrompt } from "./lib/render.mjs";
+import { resolveRole } from "./lib/resolve.mjs";
+import { validate } from "./lib/validate.mjs";
+
+async function main(argv) {
+  const { positional, flags } = parseArgv(argv);
+  const command = positional[0];
+
+  if (positional.length !== 1) {
+    usage();
+    return 2;
+  }
+
+  if (command === "render") {
+    return renderCommand(flags);
+  }
+
+  if (command === "prepare") {
+    return prepareCommand(flags);
+  }
+
+  if (command === "dispatch") {
+    return dispatchCommand(flags);
+  }
+
+  if (command === "render-followup") {
+    return renderFollowupCommand(flags);
+  }
+
+  if (command === "build") {
+    return buildCommand(flags);
+  }
+
+  if (command === "validate") {
+    return validateCommand(flags);
+  }
+
+  if (command === "install-hooks") {
+    return installHooksCommand(flags);
+  }
+
+  if (command !== "resolve") {
+    usage();
+    return 2;
+  }
+
+  if (typeof flags.role !== "string" || flags.role.length === 0) {
+    console.error("Missing required --role <name>");
+    return 1;
+  }
+
+  try {
+    const value = resolveRole({
+      role: flags.role,
+      catalog: loadCatalog(),
+      userConfig: loadUserConfig(),
+      projectConfig: loadProjectConfig(),
+      contracts: loadContracts()
+    });
+
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatTable(value));
+    }
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function prepareCommand(flags) {
+  if (typeof flags.role !== "string" || flags.role.length === 0) {
+    console.error("Missing required --role <name>");
+    return 1;
+  }
+
+  if (
+    typeof flags["request-file"] !== "string" ||
+    flags["request-file"].length === 0
+  ) {
+    console.error("Missing required --request-file <path>");
+    return 1;
+  }
+
+  try {
+    const contracts = loadContracts();
+    const resolved = resolveRole({
+      role: flags.role,
+      catalog: loadCatalog(),
+      userConfig: loadUserConfig(),
+      projectConfig: loadProjectConfig(),
+      contracts
+    });
+    const request = JSON.parse(readFileSync(flags["request-file"], "utf8"));
+    const prepared = prepareDispatch({
+      role: flags.role,
+      requestFile: flags["request-file"],
+      request,
+      resolved
+    });
+
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(prepared, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatPrepared(prepared));
+    }
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+async function installHooksCommand(flags) {
+  if (
+    flags.root !== undefined &&
+    (typeof flags.root !== "string" || flags.root.length === 0)
+  ) {
+    console.error("Missing value for --root <path>");
+    return 1;
+  }
+
+  try {
+    await installHooks({ root: flags.root ?? process.cwd() });
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+async function buildCommand(flags) {
+  if (
+    flags.root !== undefined &&
+    (typeof flags.root !== "string" || flags.root.length === 0)
+  ) {
+    console.error("Missing value for --root <path>");
+    return 1;
+  }
+
+  try {
+    await build({ root: flags.root ?? process.cwd() });
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+async function validateCommand(flags) {
+  if (
+    flags.root !== undefined &&
+    (typeof flags.root !== "string" || flags.root.length === 0)
+  ) {
+    console.error("Missing value for --root <path>");
+    return 1;
+  }
+
+  try {
+    const result = await validate({ root: flags.root ?? process.cwd() });
+    if (result.ok) {
+      process.stdout.write("OK\n");
+      return 0;
+    }
+
+    for (const error of result.errors) {
+      console.error(error);
+    }
+    return 1;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function renderFollowupCommand(flags) {
+  if (
+    typeof flags["previous-result"] !== "string" ||
+    flags["previous-result"].length === 0
+  ) {
+    console.error("Missing required --previous-result <file>");
+    return 1;
+  }
+
+  if (
+    typeof flags["new-input"] !== "string" ||
+    flags["new-input"].length === 0
+  ) {
+    console.error("Missing required --new-input <file>");
+    return 1;
+  }
+
+  try {
+    const previousResult = JSON.parse(
+      readFileSync(flags["previous-result"], "utf8")
+    );
+    const newInput = readFileSync(flags["new-input"], "utf8");
+    process.stdout.write(renderFollowup({ previousResult, newInput }));
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+async function dispatchCommand(flags) {
+  if (typeof flags.role !== "string" || flags.role.length === 0) {
+    console.error("Missing required --role <name>");
+    return 1;
+  }
+
+  if (
+    typeof flags["request-file"] !== "string" ||
+    flags["request-file"].length === 0
+  ) {
+    console.error("Missing required --request-file <path>");
+    return 1;
+  }
+
+  if (
+    flags["resume-handle"] !== undefined &&
+    (typeof flags["resume-handle"] !== "string" ||
+      flags["resume-handle"].length === 0)
+  ) {
+    console.error("Missing value for --resume-handle <thread-id>");
+    return 1;
+  }
+
+  try {
+    const contracts = loadContracts();
+    const resolved = resolveRole({
+      role: flags.role,
+      catalog: loadCatalog(),
+      userConfig: loadUserConfig(),
+      projectConfig: loadProjectConfig(),
+      contracts
+    });
+    if (resolved.provider !== "codex") {
+      console.error(
+        formatDispatchProviderGuardMessage(flags.role, resolved.provider)
+      );
+      return 2;
+    }
+    const request = JSON.parse(readFileSync(flags["request-file"], "utf8"));
+
+    const agentResult = await dispatch({
+      role: flags.role,
+      request,
+      resolved,
+      contract: resolved.contract,
+      resumeHandle: flags["resume-handle"]
+    });
+
+    writeDispatchResult(agentResult, flags);
+    if (agentResult.status === "failed") {
+      console.error("Companion returned failed AgentResult.");
+      return 1;
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof DispatchError && error.agentResult) {
+      writeDispatchResult(error.agentResult, flags);
+    }
+    console.error(error.message);
+    return error instanceof DispatchError ? error.exitCode : 1;
+  }
+}
+
+function renderCommand(flags) {
+  if (typeof flags.role !== "string" || flags.role.length === 0) {
+    console.error("Missing required --role <name>");
+    return 1;
+  }
+
+  if (
+    typeof flags["request-file"] !== "string" ||
+    flags["request-file"].length === 0
+  ) {
+    console.error("Missing required --request-file <path>");
+    return 1;
+  }
+
+  try {
+    const contracts = loadContracts();
+    const contract = findContract(flags.role, contracts);
+    if (!contract) {
+      throw new Error(`Unknown role: ${flags.role}`);
+    }
+
+    const request = JSON.parse(readFileSync(flags["request-file"], "utf8"));
+    process.stdout.write(
+      renderPrompt({
+        role: flags.role,
+        request,
+        contract
+      })
+    );
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function formatTable(value) {
+  const rows = [
+    ["role", value.role],
+    ["provider", value.provider],
+    ["model", value.model],
+    ["reasoning", value.reasoning ?? ""],
+    ["codex_sandbox", value.codex_sandbox],
+    ["dispatch.path", value.dispatch.path],
+    ["dispatch.write", String(value.dispatch.write)]
+  ];
+
+  const keyWidth = Math.max(...rows.map(([key]) => key.length));
+  return `${rows
+    .map(([key, val]) => `${key.padEnd(keyWidth)}  ${val}`)
+    .join("\n")}\n`;
+}
+
+function formatPrepared(value) {
+  if (value.action === "dispatch") {
+    return `${value.command.join(" ")}\n`;
+  }
+
+  return value.prompt;
+}
+
+function findContract(role, contracts) {
+  return contracts.roles.find((contract) => contract.role === role);
+}
+
+function writeDispatchResult(agentResult, flags) {
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(agentResult, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`${agentResult.summary ?? agentResult.status}\n`);
+}
+
+function usage() {
+  console.error("Usage: crew-agent-runner resolve --role <name> [--json]");
+  console.error("       crew-agent-runner build [--root <path>]");
+  console.error("       crew-agent-runner validate [--root <path>]");
+  console.error("       crew-agent-runner install-hooks [--root <path>]");
+  console.error(
+    "       crew-agent-runner prepare --role <name> --request-file <path> [--json]"
+  );
+  console.error("       crew-agent-runner render --role <name> --request-file <path>");
+  console.error(
+    "       crew-agent-runner render-followup --previous-result <file> --new-input <file>"
+  );
+  console.error(
+    "       crew-agent-runner dispatch --role <name> --request-file <path> [--json] [--resume-handle <thread-id>]"
+  );
+}
+
+const exitCode = await main(process.argv.slice(2));
+process.exitCode = exitCode;

package/scripts/lib/build.mjs

@@ -0,0 +1,213 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { loadContracts } from "./contracts.mjs";
+
+const DEFAULT_CONTRACTS_PATH = "data/agent-contracts.json";
+const FALLBACK_CONTRACTS_PATH = "contracts.json";
+const DEFAULT_CATALOG_PATH = "data/provider-catalog.json";
+const FALLBACK_CATALOG_PATH = "provider-catalog.json";
+const DEFAULT_INSTRUCTIONS_DIR = "data/agent-instructions";
+const FALLBACK_INSTRUCTIONS_DIR = "instructions";
+const DEFAULT_PLUGIN_PATH = ".claude-plugin/plugin.json";
+const FALLBACK_PLUGIN_PATH = "plugin.json";
+
+export async function build({ root = process.cwd() } = {}) {
+  const inputs = resolveBuildInputs(resolve(root));
+  const contracts = loadContracts(inputs.contractsPath);
+
+  await warnOrphanInstructions({
+    instructionsDir: inputs.instructionsDir,
+    contracts
+  });
+
+  const derived = await deriveBuildOutput({
+    root,
+    contracts,
+    instructionsDir: inputs.instructionsDir,
+    pluginPath: inputs.pluginPath
+  });
+
+  const agentsDir = join(inputs.projectRoot, "agents");
+  await mkdir(agentsDir, { recursive: true });
+
+  for (const [role, content] of derived.agents.entries()) {
+    await writeFile(join(agentsDir, `${role}.md`), content, "utf8");
+  }
+
+  await writeFile(inputs.pluginPath, derived.pluginJson, "utf8");
+}
+
+export async function deriveBuildOutput({
+  root = process.cwd(),
+  contracts,
+  instructionsDir,
+  pluginPath
+} = {}) {
+  const inputs = resolveBuildInputs(resolve(root));
+  const resolvedContracts =
+    contracts ?? loadContracts(inputs.contractsPath);
+  const resolvedInstructionsDir = instructionsDir ?? inputs.instructionsDir;
+  const resolvedPluginPath = pluginPath ?? inputs.pluginPath;
+
+  const instructionsByRole = new Map();
+  const missingInstructions = [];
+  for (const contract of resolvedContracts.roles) {
+    const role = contract.role;
+    const instructionPath = join(resolvedInstructionsDir, `${role}.md`);
+    if (!existsSync(instructionPath)) {
+      missingInstructions.push(role);
+      continue;
+    }
+
+    instructionsByRole.set(role, await readFile(instructionPath, "utf8"));
+  }
+
+  if (missingInstructions.length > 0) {
+    throw new Error(
+      `Missing agent instructions: ${missingInstructions.join(", ")}`
+    );
+  }
+
+  const agents = new Map();
+  for (const contract of resolvedContracts.roles) {
+    const role = contract.role;
+
+    const model = contract.claudeSubagent?.model;
+    if (typeof model !== "string" || model.length === 0) {
+      throw new Error(`Missing Claude subagent model for role: ${role}`);
+    }
+
+    const agent = renderAgent({
+      contract,
+      model,
+      instructions: instructionsByRole.get(role)
+    });
+    agents.set(role, agent);
+  }
+
+  const plugin = JSON.parse(await readFile(resolvedPluginPath, "utf8"));
+  plugin.agents = resolvedContracts.roles.map(
+    (contract) => `./agents/${contract.role}.md`
+  );
+
+  return {
+    agents,
+    pluginJson: `${JSON.stringify(plugin, null, 2)}\n`
+  };
+}
+
+export function serializeFrontmatter({ name, model, description, tools }) {
+  return [
+    "---",
+    `name: ${name}`,
+    `model: ${model}`,
+    `description: ${description}`,
+    `tools: [${tools.join(", ")}]`,
+    "---"
+  ].join("\n");
+}
+
+function renderAgent({ contract, model, instructions }) {
+  const frontmatter = serializeFrontmatter({
+    name: contract.role,
+    model,
+    description: contract.claudeSubagent.description,
+    tools: contract.claudeSubagent.tools
+  });
+  const body = [renderCapability(contract), normalizeBlockBody(instructions)]
+    .filter(Boolean)
+    .join("\n\n");
+
+  return `${frontmatter}\n\n${body}\n`;
+}
+
+function renderCapability(contract) {
+  const tools = Array.isArray(contract.claudeSubagent?.tools)
+    ? contract.claudeSubagent.tools
+    : [];
+  const outputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+
+  return [
+    "## Capability",
+    `workspaceAccess: ${contract.capabilities?.workspaceAccess ?? "unknown"}`,
+    `canAskUser: ${String(tools.includes("AskUserQuestion"))}`,
+    `canRequestAgent: ${String(tools.includes("Agent"))}`,
+    `canUseShell: ${String(tools.includes("Bash"))}`,
+    `canWriteCrewFiles: ${String(canWriteCrewFiles(outputs))}`
+  ].join("\n");
+}
+
+async function warnOrphanInstructions({ instructionsDir, contracts }) {
+  const roles = new Set(contracts.roles.map((contract) => contract.role));
+  const entries = await readdir(instructionsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+
+    const role = entry.name.slice(0, -".md".length);
+    if (!roles.has(role)) {
+      console.error(`Warning: instruction file has no contract role: ${role}`);
+    }
+  }
+}
+
+function resolveInput(root, primary, fallback) {
+  const primaryPath = join(root, primary);
+  if (existsSync(primaryPath)) {
+    return primaryPath;
+  }
+
+  const fallbackPath = join(root, fallback);
+  if (existsSync(fallbackPath)) {
+    return fallbackPath;
+  }
+
+  return primaryPath;
+}
+
+export function resolveBuildInputs(root = process.cwd()) {
+  const projectRoot = resolve(root);
+  return {
+    projectRoot,
+    contractsPath: resolveInput(
+      projectRoot,
+      DEFAULT_CONTRACTS_PATH,
+      FALLBACK_CONTRACTS_PATH
+    ),
+    catalogPath: resolveInput(
+      projectRoot,
+      DEFAULT_CATALOG_PATH,
+      FALLBACK_CATALOG_PATH
+    ),
+    instructionsDir: resolveInput(
+      projectRoot,
+      DEFAULT_INSTRUCTIONS_DIR,
+      FALLBACK_INSTRUCTIONS_DIR
+    ),
+    pluginPath: resolveInput(
+      projectRoot,
+      DEFAULT_PLUGIN_PATH,
+      FALLBACK_PLUGIN_PATH
+    )
+  };
+}
+
+function normalizeBlockBody(body) {
+  return String(body)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n+$/g, "");
+}
+
+function canWriteCrewFiles(outputs) {
+  return outputs.some((output) => {
+    return (
+      output?.type === "artifact" &&
+      typeof output.target === "string" &&
+      output.target.startsWith(".crew/")
+    );
+  });
+}

package/scripts/lib/cli.mjs

@@ -0,0 +1,30 @@
+export function parseArgv(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (!arg.startsWith("--") || arg === "--") {
+      positional.push(arg);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    if (key.length === 0) {
+      positional.push(arg);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+
+    flags[key] = next;
+    index += 1;
+  }
+
+  return { positional, flags };
+}

package/scripts/lib/config.mjs

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { pluginPath } from "./pluginRoot.mjs";
+
+export function loadCatalog(filePath) {
+  return readJson(
+    filePath === undefined
+      ? pluginPath("data", "provider-catalog.json")
+      : resolve(process.cwd(), filePath),
+    true
+  );
+}
+
+export function loadUserConfig(filePath = join(homedir(), ".claude", "crew", "config.json")) {
+  return readJson(filePath, true);
+}
+
+export function loadProjectConfig(projectRoot = process.cwd()) {
+  return readJson(join(projectRoot, ".crew", "config.json"), true);
+}
+
+function readJson(filePath, allowMissing) {
+  if (!existsSync(filePath)) {
+    if (allowMissing) {
+      return {};
+    }
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}