handyman-harness 3.0.0

package/dist/toolbox_review_notes_cli.js

@@ -0,0 +1,598 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+
+// src/toolbox_review_notes_cli.ts
+import { resolve as resolve3 } from "node:path";
+
+// ../packages/toolbox-core/dist/llm.js
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+var LlmError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "LlmError";
+    this.code = code;
+  }
+};
+var DEFAULT_MAX_TOKENS = 16e3;
+var OPENAI_MAX_TOKENS_CAP = 131072;
+var DRAFT_TIMEOUT_MS = 3e5;
+var HEALTH_TIMEOUT_MS = 1500;
+async function raiseHttp(res) {
+  const body = (await res.text().catch(() => "")).slice(0, 300);
+  let code = "provider_error";
+  if (res.status === 401) {
+    code = "unauthorized";
+  } else if (body.includes('"1113"')) {
+    code = "insufficient_balance";
+  }
+  throw new LlmError(code, `HTTP ${res.status}: ${body}`);
+}
+async function* sseData(body) {
+  if (!body) {
+    return;
+  }
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const chunk of body) {
+    buf += decoder.decode(chunk, { stream: true });
+    let idx = buf.indexOf("\n");
+    while (idx !== -1) {
+      const line = buf.slice(0, idx).trimEnd();
+      buf = buf.slice(idx + 1);
+      if (line.startsWith("data:")) {
+        yield line.slice(5).trim();
+      }
+      idx = buf.indexOf("\n");
+    }
+  }
+}
+function parseJson(payload) {
+  try {
+    const value = JSON.parse(payload);
+    return value && typeof value === "object" ? value : null;
+  } catch {
+    return null;
+  }
+}
+function anthropicProvider(options) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  return {
+    id: options.id,
+    model: options.model,
+    available: async () => options.apiKey.length > 0,
+    async draft(req, onDelta) {
+      const headers = {
+        "Content-Type": "application/json",
+        "anthropic-version": "2023-06-01"
+      };
+      if ((options.auth ?? "x-api-key") === "bearer") {
+        headers.Authorization = `Bearer ${options.apiKey}`;
+      } else {
+        headers["x-api-key"] = options.apiKey;
+      }
+      const model = req.model ?? options.model;
+      const res = await doFetch(`${base}/v1/messages`, {
+        method: "POST",
+        headers,
+        signal: AbortSignal.timeout(DRAFT_TIMEOUT_MS),
+        body: JSON.stringify({
+          model,
+          max_tokens: req.maxTokens ?? DEFAULT_MAX_TOKENS,
+          stream: true,
+          ...req.system ? { system: req.system } : {},
+          messages: [{ role: "user", content: req.prompt }]
+        })
+      });
+      if (!res.ok) {
+        await raiseHttp(res);
+      }
+      let text = "";
+      let stopReason = null;
+      for await (const payload of sseData(res.body)) {
+        const event = parseJson(payload);
+        if (!event) {
+          continue;
+        }
+        if (event.type === "content_block_delta") {
+          const delta = event.delta;
+          if (delta?.type === "text_delta" && typeof delta.text === "string") {
+            text += delta.text;
+            onDelta(delta.text);
+          }
+        } else if (event.type === "message_delta") {
+          const delta = event.delta;
+          if (typeof delta?.stop_reason === "string") {
+            stopReason = delta.stop_reason;
+          }
+        }
+      }
+      return { text, model, stopReason };
+    }
+  };
+}
+function openAiCompatProvider(options) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  return {
+    id: options.id,
+    model: options.model,
+    async available() {
+      if (!options.healthCheck) {
+        return (options.apiKey ?? "").length > 0;
+      }
+      try {
+        const res = await doFetch(`${base}/models`, {
+          signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+        });
+        return res.ok;
+      } catch {
+        return false;
+      }
+    },
+    async draft(req, onDelta) {
+      const headers = { "Content-Type": "application/json" };
+      if (options.apiKey) {
+        headers.Authorization = `Bearer ${options.apiKey}`;
+      }
+      const messages = [
+        ...req.system ? [{ role: "system", content: req.system }] : [],
+        { role: "user", content: req.prompt }
+      ];
+      const model = req.model ?? options.model;
+      const res = await doFetch(`${base}/chat/completions`, {
+        method: "POST",
+        headers,
+        signal: AbortSignal.timeout(DRAFT_TIMEOUT_MS),
+        body: JSON.stringify({
+          model,
+          messages,
+          stream: true,
+          max_tokens: Math.min(req.maxTokens ?? DEFAULT_MAX_TOKENS, OPENAI_MAX_TOKENS_CAP),
+          ...options.thinkingControl && !req.reasoning ? { thinking: { type: "disabled" } } : {}
+        })
+      });
+      if (!res.ok) {
+        await raiseHttp(res);
+      }
+      let text = "";
+      let stopReason = null;
+      for await (const payload of sseData(res.body)) {
+        if (payload === "[DONE]") {
+          continue;
+        }
+        const event = parseJson(payload);
+        const choice = event?.choices?.[0];
+        if (!choice) {
+          continue;
+        }
+        const delta = choice.delta;
+        if (typeof delta?.content === "string" && delta.content.length > 0) {
+          text += delta.content;
+          onDelta(delta.content);
+        }
+        if (typeof choice.finish_reason === "string") {
+          stopReason = choice.finish_reason;
+        }
+      }
+      return { text, model, stopReason };
+    }
+  };
+}
+var PROVIDER_REGISTRY = [
+  {
+    id: "zai",
+    apiKeyEnvKey: "Z_AI_API_KEY",
+    modelEnvKey: "Z_AI_MODEL",
+    defaultModel: "glm-5.2",
+    resolveVariant: (env) => env.Z_AI_API_MODE === "paas" ? {
+      adapter: "openai-compat",
+      baseUrl: "https://api.z.ai/api/paas/v4",
+      thinkingControl: true
+    } : {
+      adapter: "anthropic",
+      baseUrl: "https://api.z.ai/api/anthropic",
+      auth: "bearer"
+    }
+  },
+  {
+    id: "claude",
+    apiKeyEnvKey: "ANTHROPIC_API_KEY",
+    modelEnvKey: "ANTHROPIC_MODEL",
+    defaultModel: "claude-opus-4-8",
+    resolveVariant: () => ({
+      adapter: "anthropic",
+      baseUrl: "https://api.anthropic.com"
+    })
+  },
+  {
+    id: "ollama",
+    modelEnvKey: "OLLAMA_MODEL",
+    defaultModel: "llama3.2",
+    resolveVariant: (env) => ({
+      adapter: "openai-compat",
+      baseUrl: env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434/v1",
+      healthCheck: true
+    })
+  }
+];
+function buildProviders(env, fetchImpl) {
+  const providers = [];
+  for (const entry of PROVIDER_REGISTRY) {
+    const apiKey = entry.apiKeyEnvKey ? env[entry.apiKeyEnvKey] ?? "" : "";
+    if (entry.apiKeyEnvKey && !apiKey) {
+      continue;
+    }
+    const model = entry.modelEnvKey ? env[entry.modelEnvKey] ?? entry.defaultModel : entry.defaultModel;
+    const variant = entry.resolveVariant(env);
+    providers.push(variant.adapter === "anthropic" ? anthropicProvider({
+      id: entry.id,
+      model,
+      baseUrl: variant.baseUrl,
+      apiKey,
+      auth: variant.auth,
+      fetchImpl
+    }) : openAiCompatProvider({
+      id: entry.id,
+      model,
+      baseUrl: variant.baseUrl,
+      apiKey: apiKey || void 0,
+      thinkingControl: variant.thinkingControl,
+      healthCheck: variant.healthCheck,
+      fetchImpl
+    }));
+  }
+  return providers;
+}
+function loadDotEnv(root, env = process.env) {
+  let raw;
+  try {
+    raw = readFileSync(join(root, ".env"), "utf-8");
+  } catch {
+    return;
+  }
+  for (const line of raw.split("\n")) {
+    if (line.trimStart().startsWith("#")) {
+      continue;
+    }
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const key = match[1];
+    let value = match[2];
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (env[key] === void 0) {
+      env[key] = value;
+    }
+  }
+}
+
+// ../packages/toolbox-core/dist/workspace.js
+import { readFileSync as readFileSync2, statSync } from "node:fs";
+import { isAbsolute, join as join2 } from "node:path";
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function readJsonSwallow(path) {
+  try {
+    return JSON.parse(readFileSync2(path, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function usableWorkspaceValue(ws) {
+  return typeof ws === "string" && ws.length > 0;
+}
+function resolveAgainstRoot(root, ws) {
+  return isAbsolute(ws) ? ws : join2(root, ws);
+}
+function resolveWorkspace(root) {
+  const configPath = join2(root, "harness.config.json");
+  if (isFile(configPath)) {
+    const data = readJsonSwallow(configPath);
+    const ws = data && typeof data === "object" ? data.harness_workspace : void 0;
+    if (usableWorkspaceValue(ws)) {
+      return resolveAgainstRoot(root, ws);
+    }
+  }
+  const rootFeatureList = join2(root, "feature_list.json");
+  if (isFile(rootFeatureList)) {
+    const data = readJsonSwallow(rootFeatureList);
+    const config = data && typeof data === "object" ? data.config : void 0;
+    const ws = config && typeof config === "object" ? config.harness_workspace : void 0;
+    if (usableWorkspaceValue(ws)) {
+      return resolveAgainstRoot(root, ws);
+    }
+  }
+  if (isFile(join2(root, ".handyman", "feature_list.json"))) {
+    return join2(root, ".handyman");
+  }
+  return root;
+}
+
+// ../packages/toolbox-core/dist/state.js
+import { readdirSync, readFileSync as readFileSync4, statSync as statSync3 } from "node:fs";
+import { join as join4, resolve as resolve2, sep } from "node:path";
+
+// ../packages/toolbox-core/dist/registry.js
+import { mkdirSync, readFileSync as readFileSync3, statSync as statSync2, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as join3, resolve } from "node:path";
+function handymanRoot(cliOverride) {
+  if (cliOverride) {
+    return resolve(cliOverride.replace(/^~(?=$|\/)/, homedir()));
+  }
+  const env = process.env.HANDYMAN_ROOT;
+  if (env) {
+    return resolve(env.replace(/^~(?=$|\/)/, homedir()));
+  }
+  return join3(homedir(), "HANDYMAN");
+}
+function registryPath(hroot) {
+  return join3(hroot, "registry.json");
+}
+function loadRegistry(hroot) {
+  const empty = { version: 1, harnesses: [] };
+  const path = registryPath(hroot);
+  let raw;
+  try {
+    raw = readFileSync3(path, "utf-8");
+  } catch {
+    return [empty, null];
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return [empty, `registry does not parse: ${path}`];
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data) || !Array.isArray(data.harnesses)) {
+    return [empty, `registry has no 'harnesses' array: ${path}`];
+  }
+  const record = data;
+  const harnesses = record.harnesses.filter((e) => !!e && typeof e === "object" && !Array.isArray(e)).map((e) => ({
+    project_root: String(e.project_root ?? ""),
+    registered: String(e.registered ?? "")
+  }));
+  return [{ version: Number(record.version ?? 1), harnesses }, null];
+}
+
+// ../packages/toolbox-core/dist/state.js
+var INTAKE_MAX_BYTES = 256 * 1024;
+var CSP_HEADER = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'";
+var HTML_CSP_HEADER = CSP_HEADER.replace("img-src 'self' data:", "img-src 'self' data: https://picsum.photos");
+function readText(path) {
+  try {
+    return readFileSync4(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function isRegisteredRoot(hroot, root) {
+  const [registry] = loadRegistry(hroot);
+  return registry.harnesses.some((e) => e.project_root === root);
+}
+var MD_TOKEN_PATHS = {
+  current: (workspace) => join4(workspace, "progress", "current.md"),
+  history: (workspace) => join4(workspace, "progress", "history.md"),
+  index: (workspace) => join4(workspace, "index.md"),
+  checkpoints: (_workspace, root) => join4(root, "CHECKPOINTS.md")
+};
+var MD_TOKENS = Object.keys(MD_TOKEN_PATHS);
+
+// ../packages/toolbox-core/dist/reviewNotes.js
+import { execFileSync } from "node:child_process";
+import { join as join5 } from "node:path";
+var REVIEW_DIFF_MAX_CHARS = 6e4;
+function readImplReport(workspace, feature) {
+  return readText(join5(workspace, "backlog", `impl_${feature}.md`));
+}
+function readFeatureDiff(root, maxChars = REVIEW_DIFF_MAX_CHARS) {
+  let raw;
+  try {
+    raw = execFileSync("git", ["diff", "HEAD"], {
+      cwd: root,
+      encoding: "utf-8",
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return { diff: "", truncated: false };
+  }
+  if (raw.length <= maxChars) {
+    return { diff: raw, truncated: false };
+  }
+  return { diff: raw.slice(0, maxChars), truncated: true };
+}
+function composeReviewNotesSystem() {
+  return [
+    "Eres un asistente que prepara la revision de una feature en un harness Handyman.",
+    "Produces un CHECKLIST de revision en markdown: puntos criticos, invariantes en",
+    "riesgo y preguntas concretas que el reviewer debe verificar contra la evidencia.",
+    "",
+    "Reglas duras:",
+    "- Tu salida es un BORRADOR: el reviewer verifica TODO. Dilo en la primera linea.",
+    "- Escribes PREGUNTAS y PUNTOS A VERIFICAR, no conclusiones.",
+    "  Ej: '- invariante X respetada?', '- hay test que cubra el caso Y?'.",
+    "- NUNCA emites un veredicto: no escribas APPROVED ni CHANGES_REQUESTED ni",
+    "  equivalentes ('esta listo', 'se puede cerrar'). No es tu decision.",
+    "- NUNCA propongas un patch ni escribas codigo de reemplazo.",
+    "- Si el diff o el reporte no alcanzan para juzgar algo, dilo explicitamente",
+    "  ('no hay evidencia suficiente para X') en vez de suponer."
+  ].join("\n");
+}
+function composeReviewNotesPrompt(feature, implReport, diff, truncated) {
+  const parts = [`Feature bajo revision: ${feature}`, ""];
+  parts.push("---- reporte del implementer (backlog/impl_" + feature + ".md)");
+  parts.push(implReport ?? "(no hay reporte del implementer para esta feature)");
+  parts.push("");
+  parts.push("---- diff de trabajo (git diff HEAD)");
+  parts.push(diff.length > 0 ? diff : "(diff vacio o el root no es un repo git)");
+  if (truncated) {
+    parts.push("");
+    parts.push("[el diff fue truncado por tamano: senala que quedo sin revisar]");
+  }
+  return parts.join("\n");
+}
+function composeReviewNotesRequest(root, feature) {
+  const implReport = readImplReport(resolveWorkspace(root), feature);
+  const { diff, truncated } = readFeatureDiff(root);
+  return {
+    system: composeReviewNotesSystem(),
+    prompt: composeReviewNotesPrompt(feature, implReport, diff, truncated),
+    diffTruncated: truncated
+  };
+}
+async function relayReviewNotes(options) {
+  const { system, prompt, draft, diffTruncated, onDelta, onResult, onError } = options;
+  try {
+    const result = await draft({ prompt, system }, onDelta);
+    onResult({ checklist_md: result.text, model: result.model, diff_truncated: diffTruncated });
+  } catch (error) {
+    if (error instanceof LlmError) {
+      onError(error);
+      return;
+    }
+    onError(new LlmError("provider_error", error instanceof Error ? error.message : String(error)));
+  }
+}
+
+// ../packages/toolbox-core/dist/summary.js
+function resolveSummaryModel(bodyModel, providerId, env) {
+  return bodyModel ?? env.TOOLBOX_SUMMARY_MODEL ?? (providerId === "zai" && env.Z_AI_API_MODE === "paas" ? "glm-4.7-flash" : void 0);
+}
+
+// src/toolbox_review_notes_cli.ts
+var FEATURE_NAME = /^[A-Za-z0-9_-]+$/;
+var DEFAULT_PROVIDER = "zai";
+var REVIEW_NOTES_USAGE = "usage: toolbox.js review-notes --root PATH --feature NAME [--provider ID] [--model M] [--json]";
+function fail(message) {
+  process.stderr.write(`review-notes: ${message}
+`);
+  return 1;
+}
+function parseReviewNotesArgs(argv) {
+  const opts = {
+    root: "",
+    feature: "",
+    provider: DEFAULT_PROVIDER,
+    model: null,
+    json: false
+  };
+  const named = ["root", "feature", "provider", "model"];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      opts.json = true;
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      process.stdout.write(`${REVIEW_NOTES_USAGE}
+`);
+      return 0;
+    }
+    const key = named.find((n) => arg === `--${n}` || arg.startsWith(`--${n}=`));
+    if (key === void 0) {
+      process.stderr.write(`${REVIEW_NOTES_USAGE}
+review-notes: unknown argument: ${arg}
+`);
+      return 2;
+    }
+    let value;
+    if (arg.startsWith(`--${key}=`)) {
+      value = arg.slice(String(key).length + 3);
+    } else {
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        value = next;
+        i += 1;
+      }
+    }
+    if (value === void 0 || value === "") {
+      process.stderr.write(`${REVIEW_NOTES_USAGE}
+review-notes: --${key} expects a value
+`);
+      return 2;
+    }
+    opts[key] = value;
+  }
+  return opts;
+}
+async function reviewNotesMain(argv) {
+  const parsed = parseReviewNotesArgs(argv);
+  if (typeof parsed === "number") {
+    return parsed;
+  }
+  const { feature, provider: providerId, model, json } = parsed;
+  if (!parsed.root) {
+    return fail("--root is required");
+  }
+  const root = resolve3(parsed.root);
+  loadDotEnv(process.cwd());
+  const hroot = handymanRoot(null);
+  if (!isRegisteredRoot(hroot, root)) {
+    return fail(`root not registered: ${root} (register it with 'toolbox.js register')`);
+  }
+  if (!feature) {
+    return fail("--feature is required");
+  }
+  if (!FEATURE_NAME.test(feature)) {
+    return fail(`invalid feature name: ${feature}`);
+  }
+  const providers = buildProviders(process.env);
+  const provider = providers.find((p) => p.id === providerId);
+  if (!provider) {
+    const available = providers.map((p) => p.id).join(", ") || "(none configured)";
+    return fail(`unknown provider: ${providerId} (available: ${available})`);
+  }
+  const composed = composeReviewNotesRequest(root, feature);
+  const resolvedModel = resolveSummaryModel(model ?? void 0, providerId, process.env);
+  let exitCode = 0;
+  await relayReviewNotes({
+    system: composed.system,
+    prompt: composed.prompt,
+    diffTruncated: composed.diffTruncated,
+    draft: (r, onDelta) => provider.draft({ prompt: r.prompt, system: r.system, model: resolvedModel }, onDelta),
+    // Streaming text is the point of the non-JSON mode: the reviewer reads the
+    // checklist as it lands. Under --json the deltas are swallowed so stdout
+    // holds exactly one parseable object.
+    onDelta: (text) => {
+      if (!json) {
+        process.stdout.write(text);
+      }
+    },
+    onResult: (event) => {
+      if (json) {
+        process.stdout.write(`${JSON.stringify(event)}
+`);
+        return;
+      }
+      process.stdout.write("\n");
+      if (event.diff_truncated) {
+        process.stderr.write(
+          "NOTE: the diff was truncated by size; part of the change was not seen.\n"
+        );
+      }
+    },
+    onError: (error) => {
+      process.stderr.write(`review-notes: ${error.code}: ${error.message}
+`);
+      exitCode = 1;
+    }
+  });
+  return exitCode;
+}
+export {
+  REVIEW_NOTES_USAGE,
+  parseReviewNotesArgs,
+  reviewNotesMain
+};