@orchestrator-claude/cli 3.17.0 → 3.18.0

package/dist/templates/base/claude/hooks/lib/api-client.ts

@@ -0,0 +1,293 @@
+/**
+ * api-client.ts — Shared API client for Orchestrator hooks (RFC-022 Phase 2)
+ * Replaces orch-helpers.sh: typed, async/await, zero `node -e` hacks.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Resolve paths relative to this file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..", "..", "..");
+const STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
+const JWT_CACHE = join(STATE_DIR, "jwt-token");
+const DEBUG_LOG = join(STATE_DIR, "hook-debug.log");
+
+// Ensure state dir exists
+mkdirSync(STATE_DIR, { recursive: true });
+
+// Config from env
+const API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+const AUTH_EMAIL =
+  process.env.ORCHESTRATOR_ADMIN_EMAIL ||
+  process.env.ORCHESTRATOR_AUTH_EMAIL ||
+  "admin@orchestrator.local";
+const AUTH_PASSWORD =
+  process.env.ORCHESTRATOR_ADMIN_PASSWORD ||
+  process.env.ORCHESTRATOR_AUTH_PASSWORD ||
+  "admin123";
+const PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+
+// --- Types ---
+
+export interface WorkflowStatus {
+  id: string;
+  type: string;
+  status: string;
+  currentPhase: string;
+  mode?: string;
+}
+
+export interface PendingAction {
+  hasAction: boolean;
+  pendingAction?: {
+    agent: string;
+    status: string;
+    prompt?: string;
+  };
+}
+
+export interface DetectResult {
+  workflowType: string;
+  confidence: number;
+  suggestedMode?: string;
+}
+
+// --- Logging ---
+
+export function log(prefix: string, msg: string): void {
+  const ts = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}\n`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+    // fail silently
+  }
+}
+
+// --- Auth ---
+
+function getCachedToken(): string | null {
+  try {
+    const stat = statSync(JWT_CACHE);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < 3_500_000) {
+      // ~58 min
+      return readFileSync(JWT_CACHE, "utf-8").trim();
+    }
+  } catch {
+    // no cache
+  }
+  return null;
+}
+
+async function login(): Promise<string | null> {
+  if (!PROJECT_ID) return null;
+
+  try {
+    const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Project-ID": PROJECT_ID,
+      },
+      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!resp.ok) return null;
+
+    const data = (await resp.json()) as Record<string, unknown>;
+    const token =
+      (data.accessToken as string) ||
+      ((data.data as Record<string, unknown>)?.accessToken as string) ||
+      "";
+    if (token) {
+      writeFileSync(JWT_CACHE, token);
+    }
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getToken(): Promise<string | null> {
+  return getCachedToken() || (await login());
+}
+
+// --- API Helpers ---
+
+async function apiGet<T>(path: string, token: string, timeoutMs = 5000): Promise<T | null> {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID,
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!resp.ok) return null;
+    return (await resp.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function apiPost<T>(
+  path: string,
+  token: string,
+  body: Record<string, unknown>,
+  timeoutMs = 5000
+): Promise<T | null> {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!resp.ok) return null;
+    return (await resp.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+// --- Workflow Queries ---
+
+export async function getActiveWorkflow(): Promise<WorkflowStatus | null> {
+  const token = await getToken();
+  if (!token) return null;
+
+  for (const status of ["in_progress", "awaiting_agent", "awaiting_approval"]) {
+    const resp = await apiGet<{ data?: WorkflowStatus[] }>(
+      `/api/v1/workflows?status=${status}&limit=1`,
+      token,
+      3000
+    );
+    const list = resp?.data || (Array.isArray(resp) ? (resp as WorkflowStatus[]) : null);
+    const wf = list?.[0];
+    if (wf?.id) return wf;
+  }
+  return null;
+}
+
+export async function getWorkflowStatus(workflowId: string): Promise<WorkflowStatus | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiGet(`/api/v1/workflows/${workflowId}/status`, token);
+}
+
+export async function getWorkflowMode(workflowId: string): Promise<string | null> {
+  const status = await getWorkflowStatus(workflowId);
+  return status?.mode || null;
+}
+
+export async function getNextAction(workflowId: string): Promise<PendingAction | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiGet(`/api/v1/workflows/${workflowId}/pending-action`, token);
+}
+
+export async function detectWorkflow(prompt: string): Promise<DetectResult | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiPost(`/api/v1/workflows/detect`, token, { prompt }, 3000);
+}
+
+// --- Invocation Tracking ---
+
+export async function startInvocation(
+  agentType: string,
+  workflowId: string,
+  phase: string
+): Promise<void> {
+  const token = await getToken();
+  if (!token) return;
+  await apiPost(`/api/v1/invocations/start`, token, {
+    agentType,
+    workflowId,
+    phase,
+    startedAt: new Date().toISOString(),
+  });
+}
+
+export async function registerCheckpoint(
+  workflowId: string,
+  description: string,
+  commitHash: string
+): Promise<void> {
+  const token = await getToken();
+  if (!token) return;
+  await apiPost(`/api/v1/checkpoints`, token, {
+    workflowId,
+    description,
+    commitHash,
+  });
+}
+
+// --- Stdin Helper ---
+
+export async function readStdin(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+// --- JSON Field Access ---
+
+export function getField(obj: Record<string, unknown>, path: string): string {
+  const parts = path.split(".");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current != null ? String(current) : "";
+}
+
+// --- Output Helpers ---
+
+export function outputPreToolUse(opts: {
+  decision: "allow" | "deny";
+  reason?: string;
+  context?: string;
+}): void {
+  const output: Record<string, unknown> = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: opts.decision,
+      ...(opts.reason && { permissionDecisionReason: opts.reason }),
+      ...(opts.context && { additionalContext: opts.context }),
+    },
+  };
+  console.log(JSON.stringify(output));
+}
+
+export function outputContext(hookEvent: string, context: string): void {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: hookEvent,
+        additionalContext: context,
+      },
+    })
+  );
+}
+
+export function outputBlock(reason: string): void {
+  console.log(JSON.stringify({ decision: "block", reason }));
+}

package/dist/templates/base/claude/hooks/lib/git-checkpoint.ts

@@ -0,0 +1,91 @@
+/**
+ * git-checkpoint.ts — Git checkpoint logic for Orchestrator hooks (RFC-022 Phase 2)
+ * Replaces post-phase-checkpoint.sh git logic.
+ */
+
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log, registerCheckpoint } from "./api-client.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..", "..", "..");
+const STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
+const LAST_PHASE_FILE = join(STATE_DIR, "last-checkpointed-phase");
+
+const PHASE_ORDER = ["research", "specify", "plan", "tasks", "implement", "validate"];
+
+/** Map from current phase to the phase that just completed */
+function getCompletedPhase(currentPhase: string): string | null {
+  const lower = currentPhase.toLowerCase();
+  const idx = PHASE_ORDER.indexOf(lower);
+  return idx > 0 ? PHASE_ORDER[idx - 1] : null;
+}
+
+function exec(cmd: string): string {
+  return execSync(cmd, { cwd: PROJECT_ROOT, encoding: "utf-8" }).trim();
+}
+
+/**
+ * Create a git checkpoint if the phase changed and there are staged changes.
+ * Returns the commit hash or null.
+ */
+export async function createCheckpointIfNeeded(
+  workflowId: string,
+  currentPhase: string
+): Promise<string | null> {
+  const completedPhase = getCompletedPhase(currentPhase);
+  if (!completedPhase) {
+    log("CHECKPOINT", `No completed phase from: ${currentPhase}`);
+    return null;
+  }
+
+  // Check if already checkpointed
+  let lastPhase = "";
+  try {
+    lastPhase = readFileSync(LAST_PHASE_FILE, "utf-8").trim();
+  } catch {
+    // no file
+  }
+  if (lastPhase === completedPhase) {
+    log("CHECKPOINT", `Already checkpointed: ${completedPhase}`);
+    return null;
+  }
+
+  try {
+    // Stage all changes
+    exec("git add -A");
+
+    // Check if there are staged changes
+    try {
+      exec("git diff --cached --quiet");
+      // No changes
+      log("CHECKPOINT", `No changes for phase: ${completedPhase}`);
+      writeFileSync(LAST_PHASE_FILE, completedPhase);
+      return null;
+    } catch {
+      // Has changes — good, proceed to commit
+    }
+
+    const commitMsg = `[orchestrator] ${completedPhase}: Auto-checkpoint after ${completedPhase} phase`;
+    exec(`git commit -m "${commitMsg}" --no-verify`);
+    const commitHash = exec("git rev-parse HEAD");
+
+    log("CHECKPOINT", `Created: phase=${completedPhase} commit=${commitHash}`);
+
+    // Register via API
+    await registerCheckpoint(
+      workflowId,
+      `Auto-checkpoint after ${completedPhase} phase`,
+      commitHash
+    );
+
+    writeFileSync(LAST_PHASE_FILE, completedPhase);
+    return commitHash;
+  } catch (err) {
+    log("CHECKPOINT", `Error: ${err}`);
+    return null;
+  }
+}

package/dist/templates/base/claude/hooks/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@orchestrator/hooks",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Orchestrator TypeScript hooks (RFC-022 Phase 2)",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  }
+}

package/dist/templates/base/claude/hooks/post-compact.ts

@@ -0,0 +1,44 @@
+/**
+ * post-compact.ts — PostCompact hook (RFC-022 Phase 2)
+ * NEW hook: re-injects workflow state after context compaction
+ * so Claude doesn't lose track of active workflow.
+ */
+
+import {
+  log,
+  getActiveWorkflow,
+  getNextAction,
+  outputContext,
+} from "./lib/api-client.js";
+
+const HOOK = "POST-COMPACT";
+
+async function main(): Promise<void> {
+  log(HOOK, "PostCompact hook triggered");
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, nothing to re-inject");
+    return;
+  }
+
+  const parts: string[] = [
+    `[ORCHESTRATOR] Context was compacted. Active workflow state:`,
+    `Workflow: ${workflow.id}`,
+    `Type: ${workflow.type}`,
+    `Phase: ${workflow.currentPhase}`,
+    `Status: ${workflow.status}`,
+  ];
+
+  const action = await getNextAction(workflow.id);
+  if (action?.hasAction && action.pendingAction) {
+    parts.push(`Next: invoke '${action.pendingAction.agent}' (${action.pendingAction.status})`);
+  }
+
+  parts.push("", "Remember: YOU are the orchestrator (RFC-022). Dispatch sub-agents directly via Agent tool.");
+
+  log(HOOK, `Re-injecting workflow state (wf=${workflow.id})`);
+  outputContext("PostCompact", parts.join("\n"));
+}
+
+main().catch(() => process.exit(0));

package/dist/templates/base/claude/hooks/session-start.ts

@@ -0,0 +1,97 @@
+/**
+ * session-start.ts — SessionStart hook (RFC-022 Phase 2)
+ * Replaces session-orchestrator.sh
+ * Injects workflow status context on session start.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  log,
+  getActiveWorkflow,
+  getNextAction,
+  outputContext,
+} from "./lib/api-client.js";
+
+const HOOK = "SESSION-START";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..", "..");
+
+/**
+ * Read BACKLOG.md to extract version and next work item.
+ * Returns structured summary for the greeting.
+ */
+function getBacklogSummary(): { version: string; next: string; status: string } {
+  try {
+    const backlogPath = join(PROJECT_ROOT, "project-guidelines", "BACKLOG.md");
+    const content = readFileSync(backlogPath, "utf-8");
+    const lines = content.split("\n").slice(0, 40);
+
+    // Extract version from "**Release Atual:** vX.Y.Z" or "Current Release: vX.Y.Z"
+    const versionLine = lines.find((l) => /release atual|current release/i.test(l));
+    const versionMatch = versionLine?.match(/v(\d+\.\d+\.\d+)/);
+    const version = versionMatch ? `v${versionMatch[1]}` : "v?.?.?";
+
+    // Extract pending status from "**Pendente:**" line (colon may be inside or outside bold)
+    const pendenteLine = lines.find((l) => /\*\*pendente/i.test(l));
+    const status = pendenteLine
+      ?.replace(/.*\*\*pendente:?\*\*:?\s*/i, "")
+      .replace(/\s*$/, "")
+      .slice(0, 80) || "";
+
+    // Extract next step from "**Proximo passo:**" or "**Next:**" line
+    const nextLine = lines.find((l) => /\*\*proximo passo/i.test(l) || /\*\*next/i.test(l));
+    const next = nextLine
+      ?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, "")
+      .replace(/\s*$/, "")
+      .slice(0, 120) || "see BACKLOG.md";
+
+    log(HOOK, `BACKLOG parsed: version=${version} next=${next.slice(0, 50)}`);
+    return { version, next, status };
+  } catch (err) {
+    log(HOOK, `BACKLOG read failed: ${err}`);
+    return { version: "v?.?.?", next: "see BACKLOG.md", status: "" };
+  }
+}
+
+async function main(): Promise<void> {
+  log(HOOK, "SessionStart hook triggered");
+
+  const backlog = getBacklogSummary();
+  const workflow = await getActiveWorkflow();
+
+  if (!workflow) {
+    log(HOOK, "No active workflow, injecting greeting data");
+    outputContext(
+      "SessionStart",
+      [
+        `[ORCHESTRATOR-DATA] version=${backlog.version} | workflow=none | next=${backlog.next}`,
+        `[ORCHESTRATOR] Greet the user via AskUserQuestion using the data above (CLAUDE.md Rule #1).`,
+        "Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.",
+        "Invoke /orchestrator skill only when the user chooses to start a workflow.",
+      ].join("\n")
+    );
+    return;
+  }
+
+  // Active workflow — inject state + backlog
+  const action = await getNextAction(workflow.id);
+  const actionHint = action?.hasAction && action.pendingAction
+    ? ` | pending=${action.pendingAction.agent} (${action.pendingAction.status})`
+    : "";
+
+  log(HOOK, `Injecting workflow context (wf=${workflow.id} phase=${workflow.currentPhase})`);
+  outputContext(
+    "SessionStart",
+    [
+      `[ORCHESTRATOR-DATA] version=${backlog.version} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}`,
+      `[ORCHESTRATOR] Active workflow detected. Greet the user via AskUserQuestion showing workflow state (CLAUDE.md Rule #1).`,
+      "Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.",
+      "Invoke /orchestrator skill when the user chooses to continue the workflow.",
+    ].join("\n")
+  );
+}
+
+main().catch(() => process.exit(0));

package/dist/templates/base/claude/hooks/subagent-start.ts

@@ -0,0 +1,50 @@
+/**
+ * subagent-start.ts — SubagentStart hook (RFC-022 Phase 2)
+ * Replaces track-agent-invocation.sh start
+ * Registers agent invocation via REST API.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  startInvocation,
+} from "./lib/api-client.js";
+
+const HOOK = "SUBAGENT-START";
+
+const PHASE_MAP: Record<string, string> = {
+  specifier: "specify",
+  planner: "plan",
+  "task-generator": "tasks",
+  implementer: "implement",
+  researcher: "research",
+  reviewer: "review",
+};
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  log(HOOK, `SubagentStart triggered`);
+
+  const agentType =
+    getField(stdin, "tool_input.subagent_type") ||
+    getField(stdin, "subagent_type") ||
+    getField(stdin, "tool_input.type") ||
+    "unknown";
+
+  const phase = PHASE_MAP[agentType] || agentType;
+
+  log(HOOK, `agent=${agentType} phase=${phase}`);
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, skipping");
+    return;
+  }
+
+  await startInvocation(agentType, workflow.id, phase);
+  log(HOOK, `START: agent=${agentType} phase=${phase} workflow=${workflow.id}`);
+}
+
+main().catch(() => process.exit(0));

package/dist/templates/base/claude/hooks/subagent-stop.ts

@@ -0,0 +1,57 @@
+/**
+ * subagent-stop.ts — SubagentStop unified handler (RFC-022 Phase 2)
+ * Replaces 3 chained bash hooks:
+ *   1. track-agent-invocation.sh complete
+ *   2. ping-pong-enforcer.sh (ELIMINATED — main conversation is orchestrator)
+ *   3. post-phase-checkpoint.sh
+ *
+ * Single handler, single auth, sequential logic.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  outputContext,
+} from "./lib/api-client.js";
+import { createCheckpointIfNeeded } from "./lib/git-checkpoint.js";
+
+const HOOK = "SUBAGENT-STOP";
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  log(HOOK, "SubagentStop triggered");
+
+  const agentType =
+    getField(stdin, "agent_type") ||
+    getField(stdin, "tool_input.subagent_type") ||
+    "unknown";
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, skipping");
+    return;
+  }
+
+  log(HOOK, `agent=${agentType} workflow=${workflow.id} phase=${workflow.currentPhase}`);
+
+  // 1. Invocation tracking — agent self-reports via MCP; this is safety net
+  log(HOOK, `COMPLETE: agent=${agentType} (safety net — agent self-reports via MCP)`);
+
+  // 2. Git checkpoint if phase changed
+  const commitHash = await createCheckpointIfNeeded(workflow.id, workflow.currentPhase);
+
+  // 3. Guide main conversation — NO ping-pong, main IS the orchestrator
+  const parts: string[] = [`[ORCHESTRATOR] Agent '${agentType}' completed for workflow ${workflow.id}.`];
+
+  if (commitHash) {
+    parts.push(`Checkpoint: ${commitHash}.`);
+  }
+
+  parts.push("Proceed to gate check via AskUserQuestion before advancing phase.");
+
+  outputContext("SubagentStop", parts.join(" "));
+}
+
+main().catch(() => process.exit(0));

package/dist/templates/base/claude/hooks/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": false,
+    "sourceMap": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["*.ts", "lib/*.ts"]
+}