@tritard/waterbrother 0.5.0

package/src/config.js

@@ -0,0 +1,216 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { normalizeAutonomyMode, normalizeExperienceMode } from "./modes.js";
+
+const CONFIG_DIR = path.join(os.homedir(), ".waterbrother");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+const PROJECT_CONFIG_DIRNAME = ".waterbrother";
+const PROJECT_CONFIG_FILENAME = "config.json";
+const DEFAULT_APPROVAL_POLICY = {
+  autoApprovePaths: ["src/**", "app/**", "lib/**", "tests/**", "test/**", "docs/**", "public/**"],
+  askPaths: ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "bun.lock", "tsconfig.json", ".env*", "**/migrations/**", "**/.github/**", "vercel.json", "Dockerfile", "docker-compose*.yml"],
+  denyPaths: [".git/**"],
+  allowShellCommands: ["git status", "git diff", "git rev-parse", "git branch", "git log", "pwd", "ls", "rg", "cat", "npm test", "npm run test", "npm run lint", "npm run typecheck", "pnpm test", "pnpm lint", "pnpm typecheck", "yarn test", "yarn lint", "yarn typecheck", "bun test", "bun run lint", "bun run typecheck"],
+  askShellCommands: ["npm install", "pnpm install", "yarn install", "bun install"],
+  denyShellPatterns: ["(^|\\s)rm\\s+-rf\\s+(/|~|\\.)", "git\\s+reset\\s+--hard", "curl[^\\n|]*\\|\\s*(sh|bash)", "wget[^\\n|]*\\|\\s*(sh|bash)"]
+};
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => String(item || '').trim()).filter(Boolean);
+}
+
+function normalizeApprovalPolicy(policy = {}) {
+  const source = policy && typeof policy === "object" ? policy : {};
+  return {
+    autoApprovePaths: asStringArray(source.autoApprovePaths !== undefined ? source.autoApprovePaths : DEFAULT_APPROVAL_POLICY.autoApprovePaths),
+    askPaths: asStringArray(source.askPaths !== undefined ? source.askPaths : DEFAULT_APPROVAL_POLICY.askPaths),
+    denyPaths: asStringArray(source.denyPaths !== undefined ? source.denyPaths : DEFAULT_APPROVAL_POLICY.denyPaths),
+    allowShellCommands: asStringArray(source.allowShellCommands !== undefined ? source.allowShellCommands : DEFAULT_APPROVAL_POLICY.allowShellCommands),
+    askShellCommands: asStringArray(source.askShellCommands !== undefined ? source.askShellCommands : DEFAULT_APPROVAL_POLICY.askShellCommands),
+    denyShellPatterns: asStringArray(source.denyShellPatterns !== undefined ? source.denyShellPatterns : DEFAULT_APPROVAL_POLICY.denyShellPatterns)
+  };
+}
+
+function normalizeVerification(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    commands: asStringArray(source.commands),
+    timeoutMs: Number.isFinite(Number(source.timeoutMs)) ? Math.max(1000, Math.floor(Number(source.timeoutMs))) : 180000
+  };
+}
+
+function normalizeReviewer(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  const thresholdRaw = String(source.blockOn || "none").trim().toLowerCase();
+  return {
+    enabled: source.enabled !== undefined ? Boolean(source.enabled) : true,
+    model: String(source.model || "").trim(),
+    maxDiffChars: Number.isFinite(Number(source.maxDiffChars)) ? Math.max(2000, Math.floor(Number(source.maxDiffChars))) : 24000,
+    blockOn: ["none", "block", "caution"].includes(thresholdRaw) ? thresholdRaw : "none"
+  };
+}
+
+function normalizeTaskDefaults(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    branchPrefix: String(source.branchPrefix || "wb/").trim(),
+    autoSuggestContract: source.autoSuggestContract !== false,
+    requireDecisionBeforeBuild: source.requireDecisionBeforeBuild !== false
+  };
+}
+
+function normalizeImpact(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    enabled: source.enabled !== undefined ? Boolean(source.enabled) : true,
+    maxRelated: Number.isFinite(Number(source.maxRelated)) ? Math.max(4, Math.min(30, Math.floor(Number(source.maxRelated)))) : 10,
+    maxTests: Number.isFinite(Number(source.maxTests)) ? Math.max(2, Math.min(20, Math.floor(Number(source.maxTests)))) : 6
+  };
+}
+
+async function readJsonFile(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+
+function mergeConfigLayers(userConfig = {}, projectConfig = {}) {
+  const mergedMcpServers = {
+    ...(userConfig.mcpServers && typeof userConfig.mcpServers === "object" ? userConfig.mcpServers : {}),
+    ...(projectConfig.mcpServers && typeof projectConfig.mcpServers === "object" ? projectConfig.mcpServers : {})
+  };
+
+  return {
+    ...userConfig,
+    ...projectConfig,
+    ...(Object.keys(mergedMcpServers).length > 0 ? { mcpServers: mergedMcpServers } : {})
+  };
+}
+
+export function getProjectConfigDir(cwd) {
+  return path.join(cwd, PROJECT_CONFIG_DIRNAME);
+}
+
+export function getProjectConfigPath(cwd) {
+  return path.join(getProjectConfigDir(cwd), PROJECT_CONFIG_FILENAME);
+}
+
+export async function ensureConfigDir(scope = "user", cwd = process.cwd()) {
+  if (scope === "project") {
+    await fs.mkdir(getProjectConfigDir(cwd), { recursive: true });
+    return;
+  }
+
+  await fs.mkdir(CONFIG_DIR, { recursive: true });
+}
+
+export async function loadUserConfig() {
+  return readJsonFile(CONFIG_FILE);
+}
+
+export async function loadProjectConfig(cwd) {
+  if (!cwd) return {};
+  return readJsonFile(getProjectConfigPath(cwd));
+}
+
+export async function loadConfigLayers(cwd = process.cwd()) {
+  const [userConfig, projectConfig] = await Promise.all([loadUserConfig(), loadProjectConfig(cwd)]);
+  return {
+    userConfig,
+    projectConfig,
+    config: mergeConfigLayers(userConfig, projectConfig)
+  };
+}
+
+export async function loadConfig(cwd = process.cwd()) {
+  const layers = await loadConfigLayers(cwd);
+  return layers.config;
+}
+
+export async function saveConfig(config, { scope = "user", cwd = process.cwd() } = {}) {
+  const filePath = scope === "project" ? getProjectConfigPath(cwd) : CONFIG_FILE;
+  await ensureConfigDir(scope, cwd);
+  await fs.writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+export function resolveRuntimeConfig(config, overrides = {}) {
+  const baseUrl =
+    overrides.baseUrl ||
+    process.env.XAI_BASE_URL ||
+    process.env.GROK_BASE_URL ||
+    config.baseUrl ||
+    "https://api.x.ai/v1";
+
+  const apiKey =
+    overrides.apiKey ||
+    process.env.XAI_API_KEY ||
+    process.env.GROK_API_KEY ||
+    config.apiKey ||
+    "";
+
+  const model =
+    overrides.model ||
+    process.env.XAI_MODEL ||
+    process.env.GROK_MODEL ||
+    config.model ||
+    "grok-code-fast-1";
+
+  return {
+    baseUrl,
+    apiKey,
+    model,
+    approvalMode: overrides.approvalMode || config.approvalMode || "on-request",
+    traceMode: overrides.traceMode || config.traceMode || "on",
+    receiptMode: overrides.receiptMode || config.receiptMode || "auto",
+    autoCompactThreshold:
+      overrides.autoCompactThreshold !== undefined
+        ? overrides.autoCompactThreshold
+        : config.autoCompactThreshold !== undefined
+          ? config.autoCompactThreshold
+          : 0.9,
+    agentProfile: overrides.agentProfile || config.agentProfile || "coder",
+    designModel: overrides.designModel || config.designModel || "grok-4.20-multi-agent-beta-0309",
+    requireTurnContracts:
+      overrides.requireTurnContracts !== undefined
+        ? Boolean(overrides.requireTurnContracts)
+        : config.requireTurnContracts !== undefined
+          ? Boolean(config.requireTurnContracts)
+          : true,
+    approvalPolicy: normalizeApprovalPolicy(overrides.approvalPolicy !== undefined ? overrides.approvalPolicy : config.approvalPolicy),
+    verification: normalizeVerification(overrides.verification !== undefined ? overrides.verification : config.verification),
+    reviewer: normalizeReviewer(overrides.reviewer !== undefined ? overrides.reviewer : config.reviewer),
+    impact: normalizeImpact(overrides.impact !== undefined ? overrides.impact : config.impact),
+    experienceMode: normalizeExperienceMode(overrides.experienceMode !== undefined ? overrides.experienceMode : config.experienceMode || "standard"),
+    autonomyMode: normalizeAutonomyMode(overrides.autonomyMode !== undefined ? overrides.autonomyMode : config.autonomyMode || "scoped"),
+    panelEnabled:
+      overrides.panelEnabled !== undefined
+        ? Boolean(overrides.panelEnabled)
+        : config.panelEnabled !== undefined
+          ? Boolean(config.panelEnabled)
+          : true,
+    decisionModel: overrides.decisionModel || config.decisionModel || "",
+    taskDefaults: normalizeTaskDefaults(
+      overrides.taskDefaults !== undefined ? overrides.taskDefaults : config.taskDefaults
+    ),
+    profiles: config.profiles && typeof config.profiles === "object" ? config.profiles : {},
+    onboardingCompleted: Boolean(config.onboardingCompleted),
+    mcpServers:
+      overrides.mcpServers && typeof overrides.mcpServers === "object"
+        ? overrides.mcpServers
+        : config.mcpServers && typeof config.mcpServers === "object"
+          ? config.mcpServers
+          : {}
+  };
+}
+
+export function getConfigPath({ scope = "user", cwd = process.cwd() } = {}) {
+  return scope === "project" ? getProjectConfigPath(cwd) : CONFIG_FILE;
+}

package/src/decider.js

@@ -0,0 +1,131 @@
+import { createJsonCompletion } from "./grok-client.js";
+
+const DECISION_SYSTEM_PROMPT = `You are a senior software architect helping a developer choose an implementation strategy.
+
+You will be given a task goal and optionally some project context. Your job is to:
+1. Analyze the goal and propose 2-4 concrete implementation options
+2. Each option should have a clear scope (file paths, commands)
+3. Recommend one option with a rationale
+4. Flag open risks
+
+Respond with ONLY a JSON object matching this schema:
+{
+  "goal": "one-line restatement of the goal",
+  "options": [
+    {
+      "id": "minimal|strategic|exploratory|custom_id",
+      "title": "Short title",
+      "summary": "One paragraph explaining the approach",
+      "pros": ["..."],
+      "cons": ["..."],
+      "risk": "low|medium|high",
+      "fileCount": 4,
+      "scope": {
+        "paths": ["src/auth/**", "tests/auth/**"],
+        "commands": ["npm test -- auth"]
+      }
+    }
+  ],
+  "recommendation": "option_id",
+  "rationale": "Why this option fits best given current constraints",
+  "openRisks": ["risk description"]
+}
+
+Rules:
+- Always include at least a "minimal" option
+- Be concrete about file paths and commands — guess from the goal if needed
+- Keep summaries factual, not promotional
+- If you cannot determine scope, say so in openRisks
+- Do not include markdown, code fences, or explanatory text outside the JSON`;
+
+function buildDecisionPrompt({ goal, memory, taskName }) {
+  const parts = [`Goal: ${goal}`];
+  if (taskName) parts.push(`Task: ${taskName}`);
+  if (memory) parts.push(`Project context (WATERBROTHER.md):\n${memory}`);
+  parts.push("Propose implementation options as JSON.");
+  return parts.join("\n\n");
+}
+
+export function normalizeDecision(decision) {
+  if (!decision || typeof decision !== "object") return null;
+  const options = Array.isArray(decision.options) ? decision.options : [];
+  return {
+    goal: String(decision.goal || "").trim(),
+    options: options.map((opt) => ({
+      id: String(opt.id || "unknown").trim(),
+      title: String(opt.title || "").trim(),
+      summary: String(opt.summary || "").trim(),
+      pros: Array.isArray(opt.pros) ? opt.pros.map(String) : [],
+      cons: Array.isArray(opt.cons) ? opt.cons.map(String) : [],
+      risk: ["low", "medium", "high"].includes(opt.risk) ? opt.risk : "medium",
+      fileCount: Number.isFinite(Number(opt.fileCount)) ? Math.max(0, Math.floor(Number(opt.fileCount))) : null,
+      scope: opt.scope && typeof opt.scope === "object"
+        ? {
+            paths: Array.isArray(opt.scope.paths) ? opt.scope.paths.map(String) : [],
+            commands: Array.isArray(opt.scope.commands) ? opt.scope.commands.map(String) : []
+          }
+        : { paths: [], commands: [] }
+    })),
+    recommendation: String(decision.recommendation || "").trim(),
+    rationale: String(decision.rationale || "").trim(),
+    openRisks: Array.isArray(decision.openRisks) ? decision.openRisks.map(String) : []
+  };
+}
+
+export async function runDecisionPass({
+  apiKey,
+  baseUrl,
+  model,
+  goal,
+  taskName,
+  memory,
+  signal
+}) {
+  if (!goal) throw new Error("goal is required for /decide");
+
+  const messages = [
+    { role: "system", content: DECISION_SYSTEM_PROMPT },
+    { role: "user", content: buildDecisionPrompt({ goal, memory, taskName }) }
+  ];
+
+  const completion = await createJsonCompletion({
+    apiKey,
+    baseUrl,
+    model,
+    messages,
+    temperature: 0.3,
+    signal
+  });
+
+  const decision = normalizeDecision(completion.json);
+  if (!decision || decision.options.length === 0) {
+    throw new Error("Decision pass returned no options");
+  }
+
+  return {
+    decision,
+    usage: completion.usage || null
+  };
+}
+
+export function formatDecisionForDisplay(decision) {
+  if (!decision) return "No decision available.";
+  const lines = [];
+  lines.push(`Goal: ${decision.goal}`);
+  lines.push("");
+  for (const opt of decision.options) {
+    const rec = opt.id === decision.recommendation ? " (recommended)" : "";
+    lines.push(`Option: ${opt.id} — ${opt.title}${rec}`);
+    lines.push(`  ${opt.summary}`);
+    if (opt.fileCount != null) lines.push(`  Files: ~${opt.fileCount}`);
+    lines.push(`  Risk: ${opt.risk}`);
+    if (opt.pros.length > 0) lines.push(`  Pros: ${opt.pros.join(", ")}`);
+    if (opt.cons.length > 0) lines.push(`  Cons: ${opt.cons.join(", ")}`);
+    if (opt.scope.paths.length > 0) lines.push(`  Scope: ${opt.scope.paths.join(", ")}`);
+    if (opt.scope.commands.length > 0) lines.push(`  Commands: ${opt.scope.commands.join(", ")}`);
+    lines.push("");
+  }
+  if (decision.rationale) lines.push(`Rationale: ${decision.rationale}`);
+  if (decision.openRisks.length > 0) lines.push(`Open risks: ${decision.openRisks.join("; ")}`);
+  return lines.join("\n");
+}

package/src/grok-client.js

@@ -0,0 +1,268 @@
+function trimTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+function buildChatPayload({ model, messages, tools, temperature }) {
+  const payload = {
+    model,
+    messages,
+    temperature
+  };
+
+  if (tools && tools.length > 0) {
+    payload.tools = tools;
+    payload.tool_choice = "auto";
+  }
+
+  return payload;
+}
+
+function appendToolCallDelta(message, deltaToolCall) {
+  if (!deltaToolCall || typeof deltaToolCall !== "object") return;
+  const index = Number.isInteger(deltaToolCall.index) ? deltaToolCall.index : 0;
+  if (!Array.isArray(message.tool_calls)) message.tool_calls = [];
+  if (!message.tool_calls[index]) {
+    message.tool_calls[index] = {
+      id: deltaToolCall.id || null,
+      type: "function",
+      function: {
+        name: "",
+        arguments: ""
+      }
+    };
+  }
+
+  const target = message.tool_calls[index];
+  if (deltaToolCall.id) target.id = deltaToolCall.id;
+  if (deltaToolCall.type) target.type = deltaToolCall.type;
+  if (deltaToolCall.function?.name) target.function.name += deltaToolCall.function.name;
+  if (deltaToolCall.function?.arguments) target.function.arguments += deltaToolCall.function.arguments;
+}
+
+async function requestJson({ apiKey, baseUrl, endpoint, method = "GET", payload, signal }) {
+  if (!apiKey) {
+    throw new Error("Missing API key. Set XAI_API_KEY or run: waterbrother config set apiKey <key>");
+  }
+
+  const response = await fetch(`${trimTrailingSlash(baseUrl)}${endpoint}`, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`
+    },
+    body: payload ? JSON.stringify(payload) : undefined,
+    signal
+  });
+
+  const bodyText = await response.text();
+  let body;
+  try {
+    body = JSON.parse(bodyText);
+  } catch {
+    body = null;
+  }
+
+  if (!response.ok) {
+    const details = body ? JSON.stringify(body, null, 2) : bodyText;
+    throw new Error(`Grok API error (${response.status}): ${details}`);
+  }
+
+  return body;
+}
+
+export async function createChatCompletion({
+  apiKey,
+  baseUrl,
+  model,
+  messages,
+  tools,
+  temperature = 0.2,
+  signal
+}) {
+  const payload = buildChatPayload({ model, messages, tools, temperature });
+
+  const body = await requestJson({
+    apiKey,
+    baseUrl,
+    endpoint: "/chat/completions",
+    method: "POST",
+    payload,
+    signal
+  });
+
+  const message = body?.choices?.[0]?.message;
+  if (!message) {
+    throw new Error(`Unexpected Grok API response: ${JSON.stringify(body)}`);
+  }
+
+  return {
+    id: body.id,
+    usage: body.usage,
+    message
+  };
+}
+
+export async function createChatCompletionStream({
+  apiKey,
+  baseUrl,
+  model,
+  messages,
+  tools,
+  temperature = 0.2,
+  signal,
+  onDelta
+}) {
+  if (!apiKey) {
+    throw new Error("Missing API key. Set XAI_API_KEY or run: waterbrother config set apiKey <key>");
+  }
+
+  const payload = {
+    ...buildChatPayload({ model, messages, tools, temperature }),
+    stream: true
+  };
+
+  const response = await fetch(`${trimTrailingSlash(baseUrl)}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify(payload),
+    signal
+  });
+
+  if (!response.ok) {
+    const bodyText = await response.text();
+    throw new Error(`Grok API error (${response.status}): ${bodyText}`);
+  }
+  if (!response.body) {
+    throw new Error("Grok API stream error: response body missing");
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const message = { role: "assistant", content: "" };
+  let usage = null;
+  let id = null;
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      while (true) {
+        const splitAt = buffer.indexOf("\n\n");
+        if (splitAt === -1) break;
+        const eventBlock = buffer.slice(0, splitAt);
+        buffer = buffer.slice(splitAt + 2);
+
+        const lines = eventBlock
+          .split("\n")
+          .map((line) => line.trim())
+          .filter((line) => line.startsWith("data:"));
+
+        for (const line of lines) {
+          const data = line.slice(5).trim();
+          if (!data) continue;
+          if (data === "[DONE]") {
+            continue;
+          }
+
+          let parsed;
+          try {
+            parsed = JSON.parse(data);
+          } catch {
+            continue;
+          }
+
+          id = parsed.id || id;
+          usage = parsed.usage || usage;
+          const delta = parsed?.choices?.[0]?.delta;
+          if (!delta) continue;
+
+          if (typeof delta.content === "string" && delta.content.length > 0) {
+            message.content += delta.content;
+            if (onDelta) onDelta(delta.content);
+          }
+
+          if (Array.isArray(delta.tool_calls)) {
+            for (const deltaToolCall of delta.tool_calls) {
+              appendToolCallDelta(message, deltaToolCall);
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return {
+    id,
+    usage,
+    message
+  };
+}
+
+function extractJson(text) {
+  const raw = String(text || "").trim();
+  // Try raw parse first
+  try { return JSON.parse(raw); } catch {}
+  // Try markdown-fenced JSON
+  const fenced = raw.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+  if (fenced) {
+    try { return JSON.parse(fenced[1].trim()); } catch {}
+  }
+  // Try first { ... } block
+  const braceStart = raw.indexOf("{");
+  const braceEnd = raw.lastIndexOf("}");
+  if (braceStart !== -1 && braceEnd > braceStart) {
+    try { return JSON.parse(raw.slice(braceStart, braceEnd + 1)); } catch {}
+  }
+  return null;
+}
+
+export async function createJsonCompletion({
+  apiKey,
+  baseUrl,
+  model,
+  messages,
+  temperature = 0.2,
+  signal
+}) {
+  const completion = await createChatCompletion({
+    apiKey,
+    baseUrl,
+    model,
+    messages,
+    temperature,
+    signal
+  });
+
+  const content = String(completion?.message?.content || "").trim();
+  const parsed = extractJson(content);
+  if (!parsed) {
+    const error = new Error(`Failed to parse JSON from model response`);
+    error.rawContent = content;
+    throw error;
+  }
+  return { ...completion, json: parsed };
+}
+
+export async function listModels({ apiKey, baseUrl }) {
+  const body = await requestJson({
+    apiKey,
+    baseUrl,
+    endpoint: "/models",
+    method: "GET"
+  });
+
+  const models = Array.isArray(body?.data) ? body.data : [];
+  return models.map((item) => ({
+    id: item.id,
+    created: item.created,
+    owned_by: item.owned_by
+  }));
+}