@wrongstack/tools 0.313.0 → 0.313.1

package/dist/chunk-KXNDHMUB.js

@@ -0,0 +1,366 @@
+import {
+  todoTool
+} from "./chunk-J4SRJKBW.js";
+import {
+  projectSessionPlanToKanban
+} from "./chunk-QNJ7AQ4B.js";
+
+// src/plan.ts
+import { randomUUID } from "node:crypto";
+import {
+  addPlanItem,
+  clearPlan,
+  deriveTodosFromPlanItem,
+  formatPlan,
+  getPlanTemplate,
+  mutatePlan,
+  mutateTasks,
+  removePlanItem,
+  setPlanItemStatus
+} from "@wrongstack/core/storage";
+import { formatTaskList } from "@wrongstack/core/utils";
+var planTool = {
+  name: "plan",
+  category: "Session",
+  description: 'Manage a session-persistent strategic plan. The plan is written to disk and survives conversation resumptions within the same session, but is isolated to this session \u2014 other sessions have their own separate plans. Unlike todos (which are per-turn and lost on restart), a plan tracks high-level progress across multiple turns. Use this to outline big-picture work, then promote concrete items into the todo list when ready to execute. By default plans are isolated to this session; use `scope: "project"` to store the plan in a shared project-level file visible to all sessions.',
+  usageHint: 'RECOMMENDED FOR COMPLEX, MULTI-PHASE WORK:\n\n- Start by creating a high-level plan with `action: "add"` or using templates (`template_use`).\n- Use `action: "status"` with `open`, `in_progress`, or `done` for exact status changes.\n- Use `promote` to turn a plan item into actionable todos.\n- Use `taskify` to convert a plan item into a structured task (with type/priority/deps).\n- Unfinished plan items cannot be removed or cleared; complete them first.\n- Keep plans at the "why and what" level, and todos at the "how and next step" level.\n- Common templates: "new-feature", "bug-fix", "refactor", "release", "security-audit".\n\nThis tool is excellent for maintaining long-term direction across many turns within a session. Plans survive resume but are not shared across separate sessions.\nUse `scope: "project"` to use a shared project-level plan file.',
+  permission: "confirm",
+  // WS-046: gives permission decisions something to key on.
+  // The action performed; plan has no single file or path subject.
+  subjectKey: "action",
+  mutating: true,
+  capabilities: ["fs.write"],
+  icon: "plan",
+  timeoutMs: 3e4,
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: [
+          "show",
+          "add",
+          "status",
+          "start",
+          "done",
+          "remove",
+          "promote",
+          "template_use",
+          "clear",
+          "taskify"
+        ],
+        description: "The operation to perform on the plan board."
+      },
+      title: {
+        type: "string",
+        description: "Title of the plan item. Required for action=add."
+      },
+      details: {
+        type: "string",
+        description: "Additional details or description for a new plan item (action=add)."
+      },
+      target: {
+        type: "string",
+        description: "Identifier for the target plan item (id, 1-based index, or partial title). Required for most actions except add/show/clear."
+      },
+      status: {
+        type: "string",
+        enum: ["open", "in_progress", "done"],
+        description: "Exact plan item status for action=status."
+      },
+      subtasks: {
+        type: "array",
+        items: { type: "string" },
+        description: "List of subtask titles. Used with promote to break a plan item into multiple todos."
+      },
+      template: {
+        type: "string",
+        description: "Template identifier when using action=template_use. Common values: new-feature, bug-fix, refactor, release, security-audit."
+      },
+      scope: {
+        type: "string",
+        enum: ["session", "project"],
+        description: 'Storage scope: "session" (default, isolated to this session) or "project" (shared across all sessions for this project).'
+      }
+    },
+    required: ["action"]
+  },
+  async execute(input, ctx) {
+    const sessionPlanPath = ctx.meta["plan.path"];
+    let planPath;
+    if (input.scope === "project") {
+      if (typeof sessionPlanPath === "string") {
+        const lastSep = Math.max(
+          sessionPlanPath.lastIndexOf("/"),
+          sessionPlanPath.lastIndexOf("\\")
+        );
+        if (lastSep < 0) {
+          return {
+            ok: false,
+            message: `Cannot derive the project-scoped plan path: session plan path "${sessionPlanPath}" has no directory component.`,
+            plan: "",
+            count: 0,
+            open: 0
+          };
+        }
+        planPath = sessionPlanPath.slice(0, lastSep + 1) + "backlog.plan.json";
+      }
+    } else {
+      planPath = sessionPlanPath;
+    }
+    if (typeof planPath !== "string" || !planPath) {
+      return {
+        ok: false,
+        message: "Plan storage path is not configured for this session.",
+        plan: "",
+        count: 0,
+        open: 0
+      };
+    }
+    const sessionId = ctx.session?.id ?? "unknown";
+    let early = null;
+    const taskifyMeta = { title: "", details: "" };
+    let didTaskify = false;
+    let todosToReplace = null;
+    let plan;
+    try {
+      plan = await mutatePlan(planPath, sessionId, async (p) => {
+        switch (input.action) {
+          case "show":
+            break;
+          case "add": {
+            const title = input.title?.trim();
+            if (!title) {
+              early = mkResult(p, false, "add requires `title`.");
+              return p;
+            }
+            const { plan: updated } = addPlanItem(p, title, input.details?.trim() || void 0);
+            return updated;
+          }
+          case "start":
+          case "done": {
+            if (!input.target) {
+              early = mkResult(
+                p,
+                false,
+                `${input.action} requires \`target\` (id|index|substring).`
+              );
+              return p;
+            }
+            const next = setPlanItemStatus(
+              p,
+              input.target,
+              input.action === "start" ? "in_progress" : "done"
+            );
+            if (next === p) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            return next;
+          }
+          case "status": {
+            if (!input.target || !input.status) {
+              early = mkResult(
+                p,
+                false,
+                "status requires `target` (id|index|substring) and `status`."
+              );
+              return p;
+            }
+            const next = setPlanItemStatus(p, input.target, input.status);
+            if (next === p) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            return next;
+          }
+          case "remove": {
+            if (!input.target) {
+              early = mkResult(p, false, "remove requires `target` (id|index|substring).");
+              return p;
+            }
+            const next = removePlanItem(p, input.target);
+            if (next === p) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            const nextIds = new Set(next.items.map((item) => item.id));
+            const removed = p.items.find((item) => !nextIds.has(item.id));
+            if (removed?.status !== "done") {
+              early = mkResult(
+                p,
+                false,
+                `Plan item "${removed?.title ?? input.target}" is not done and cannot be removed. Complete it first.`
+              );
+              return p;
+            }
+            return next;
+          }
+          case "promote": {
+            if (!input.target) {
+              early = mkResult(
+                p,
+                false,
+                `${input.action} requires \`target\` (id|index|substring).`
+              );
+              return p;
+            }
+            const derived = deriveTodosFromPlanItem(p, input.target, input.subtasks);
+            if (!derived) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            todosToReplace = derived.todos;
+            early = mkResult(
+              derived.plan,
+              true,
+              `${input.action} ok \u2014 ${derived.todos.length} todo(s) created.`,
+              derived.todos
+            );
+            return derived.plan;
+          }
+          case "template_use": {
+            const templateName = input.template?.trim();
+            if (!templateName) {
+              early = mkResult(p, false, "template_use requires `template` name.");
+              return p;
+            }
+            const template = getPlanTemplate(templateName);
+            if (!template) {
+              early = mkResult(p, false, `Unknown template "${templateName}".`);
+              return p;
+            }
+            let updated = p;
+            for (const item of template.items) {
+              ({ plan: updated } = addPlanItem(updated, item.title, item.details));
+            }
+            early = mkResult(
+              updated,
+              true,
+              `Applied template "${template.name}" \u2014 ${template.items.length} items added.`
+            );
+            return updated;
+          }
+          case "clear":
+            if (p.items.some((item) => item.status !== "done")) {
+              early = mkResult(
+                p,
+                false,
+                "Plan contains unfinished items and cannot be cleared. Complete them first."
+              );
+              return p;
+            }
+            return clearPlan(p);
+          case "taskify": {
+            if (!input.target) {
+              early = mkResult(
+                p,
+                false,
+                "taskify requires `target` (plan item id|index|substring)."
+              );
+              return p;
+            }
+            let itemIdx = -1;
+            const asNum = Number.parseInt(input.target, 10);
+            if (!Number.isNaN(asNum) && asNum >= 1 && asNum <= p.items.length) {
+              itemIdx = asNum - 1;
+            } else {
+              itemIdx = p.items.findIndex((it) => it.id === input.target);
+              if (itemIdx === -1) {
+                const lower = input.target.toLowerCase();
+                itemIdx = p.items.findIndex((it) => it.title.toLowerCase().includes(lower));
+              }
+            }
+            if (itemIdx === -1 || !p.items[itemIdx]) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            const item = p.items[itemIdx];
+            taskifyMeta.title = item.title;
+            taskifyMeta.details = item.details ?? "";
+            didTaskify = true;
+            break;
+          }
+          default:
+            early = mkResult(p, false, `Unknown action "${input.action}".`);
+            return p;
+        }
+        return p;
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        message: `Plan change not saved \u2014 ${err instanceof Error ? err.message : String(err)}`,
+        plan: "",
+        count: 0,
+        open: 0
+      };
+    }
+    ctx.meta["plan.path.resolved"] = planPath;
+    await projectSessionPlanToKanban(ctx.projectRoot, plan.items, sessionId);
+    if (todosToReplace) {
+      await todoTool.execute({ todos: todosToReplace }, ctx, {
+        signal: AbortSignal.timeout(3e4)
+      });
+    }
+    if (early) return early;
+    if (didTaskify) {
+      const taskPathRaw = ctx.meta["task.path"];
+      if (typeof taskPathRaw !== "string" || !taskPathRaw) {
+        return mkResult(plan, false, "Task storage path not configured \u2014 cannot taskify.");
+      }
+      let taskPath = taskPathRaw;
+      if (input.scope === "project") {
+        const lastSep = Math.max(taskPath.lastIndexOf("/"), taskPath.lastIndexOf("\\"));
+        taskPath = lastSep >= 0 ? taskPath.slice(0, lastSep + 1) + "backlog.tasks.json" : "backlog.tasks.json";
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      try {
+        const taskFile = await mutateTasks(taskPath, sessionId, (f) => {
+          f.tasks.push({
+            id: `task_${randomUUID()}`,
+            title: taskifyMeta.title,
+            description: taskifyMeta.details || void 0,
+            type: "feature",
+            priority: "medium",
+            status: "pending",
+            createdAt: now,
+            updatedAt: now
+          });
+          return f;
+        });
+        ctx.meta["task.path.resolved"] = taskPath;
+        return mkResult(
+          plan,
+          true,
+          `taskify ok \u2014 added "${taskifyMeta.title}" to tasks.
+${formatTaskList(taskFile.tasks)}`
+        );
+      } catch (err) {
+        return mkResult(
+          plan,
+          false,
+          `taskify: task not saved \u2014 ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    return mkResult(plan, true, `Plan ${input.action} ok.`);
+  }
+};
+function mkResult(plan, ok, message, todos) {
+  const open = plan.items.filter((i) => i.status !== "done").length;
+  const result = {
+    ok,
+    message,
+    plan: formatPlan(plan),
+    count: plan.items.length,
+    open
+  };
+  if (todos !== void 0) result.todos = todos;
+  return result;
+}
+
+export {
+  planTool
+};
+//# sourceMappingURL=chunk-KXNDHMUB.js.map

package/dist/chunk-LIJQMYYX.js

@@ -0,0 +1,59 @@
+// src/codebase-index/gitignore.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { compileGlob } from "@wrongstack/core/utils";
+function globBody(glob) {
+  return compileGlob(glob).source.replace(/^\^/, "").replace(/\$$/, "");
+}
+function compileGitignore(lines) {
+  const rules = [];
+  for (const raw of lines) {
+    let line = raw.replace(/\r$/, "");
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    line = line.trim();
+    let negated = false;
+    if (line.startsWith("!")) {
+      negated = true;
+      line = line.slice(1);
+    }
+    let dirOnly = false;
+    if (line.endsWith("/")) {
+      dirOnly = true;
+      line = line.slice(0, -1);
+    }
+    if (!line) continue;
+    const anchored = line.startsWith("/") || line.includes("/");
+    if (line.startsWith("/")) line = line.slice(1);
+    const body = globBody(line);
+    const prefix = anchored ? "^" : "(?:^|.*/)";
+    rules.push({
+      eqOrUnder: new RegExp(`${prefix}${body}(?:/.*)?$`),
+      under: new RegExp(`${prefix}${body}/.*$`),
+      negated,
+      dirOnly
+    });
+  }
+  return (relPath, isDir) => {
+    const p = relPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    let ignored = false;
+    for (const r of rules) {
+      const re = r.dirOnly && !isDir ? r.under : r.eqOrUnder;
+      if (re.test(p)) ignored = !r.negated;
+    }
+    return ignored;
+  };
+}
+async function loadGitignoreMatcher(projectRoot) {
+  let lines = [];
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, ".gitignore"), "utf8");
+    lines = raw.split("\n");
+  } catch {
+  }
+  return compileGitignore(lines);
+}
+
+export {
+  loadGitignoreMatcher
+};
+//# sourceMappingURL=chunk-LIJQMYYX.js.map

package/dist/chunk-MAN26PZ5.js

@@ -0,0 +1,260 @@
+import {
+  createOutputSpool,
+  spoolNote
+} from "./chunk-2TFQDEPU.js";
+import {
+  getProcessRegistry,
+  redactCommand
+} from "./chunk-3PVYQFRQ.js";
+import {
+  buildWin32CmdShimInvocation,
+  resolveWin32Command
+} from "./chunk-V43EQ6VR.js";
+
+// src/_spawn-stream.ts
+import { spawn } from "node:child_process";
+import {
+  emitProcessCompleted,
+  emitProcessOutput,
+  emitProcessStarted
+} from "@wrongstack/core/observability";
+import { buildChildEnv } from "@wrongstack/core/utils";
+var isWin = process.platform === "win32";
+async function* spawnStream(opts) {
+  const max = opts.maxBytes ?? 999999999;
+  const flushAt = opts.flushBytes ?? 4 * 1024;
+  const maxQueue = opts.maxQueueSize ?? 500;
+  const maxQueueBytes = opts.maxQueueBytes ?? 1024 * 1024;
+  let stdout = "";
+  let stderr = "";
+  let stdoutRetainedBytes = 0;
+  let stderrRetainedBytes = 0;
+  let pending = "";
+  let error;
+  const spool = createOutputSpool({ tool: opts.cmd, thresholdBytes: max });
+  const resolved = resolveWin32Command(opts.cmd);
+  const needsShell = isWin && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
+  const shim = needsShell ? buildWin32CmdShimInvocation(resolved, opts.args) : null;
+  const cmd = shim?.command ?? resolved;
+  const args = shim?.args ?? opts.args;
+  const child = spawn(cmd, args, {
+    cwd: opts.cwd,
+    env: buildChildEnv(),
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    ...isWin ? {} : { signal: opts.signal },
+    ...shim ? { windowsVerbatimArguments: shim.windowsVerbatimArguments } : {}
+  });
+  const registry = getProcessRegistry();
+  const pid = child.pid;
+  const processStartedAt = Date.now();
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let telemetryCompleted = false;
+  emitProcessStarted({
+    ...pid !== void 0 ? { pid } : {},
+    parentPid: process.pid,
+    command: redactCommand(`${opts.cmd} ${opts.args.join(" ")}`),
+    args: redactCommand(opts.args.join(" ")).split(" ").filter(Boolean),
+    cwd: opts.cwd,
+    background: false,
+    startedAt: new Date(processStartedAt).toISOString()
+  });
+  if (typeof pid === "number") {
+    registry.register({
+      pid,
+      name: opts.cmd,
+      command: redactCommand(`${opts.cmd} ${opts.args.join(" ")}`),
+      startedAt: Date.now(),
+      child
+    });
+  }
+  const queue = [];
+  let queuedBytes = 0;
+  let waiter;
+  let paused = false;
+  const wake = () => {
+    if (waiter) {
+      const w = waiter;
+      waiter = void 0;
+      w();
+    }
+  };
+  const resume = () => {
+    if (paused && queue.length <= Math.floor(maxQueue / 2) && queuedBytes <= Math.floor(maxQueueBytes / 2)) {
+      paused = false;
+      child.stdout?.resume();
+      child.stderr?.resume();
+    }
+  };
+  const onOut = (c) => {
+    const s = c.toString();
+    stdoutBytes += c.byteLength;
+    emitProcessOutput({ pid, stream: "stdout", chunk: c });
+    if (stdoutRetainedBytes < max) {
+      const retained = utf8Prefix(s, max - stdoutRetainedBytes);
+      stdout += retained;
+      stdoutRetainedBytes += Buffer.byteLength(retained, "utf8");
+    }
+    spool.write(s);
+    queue.push({ kind: "out", data: s, bytes: c.byteLength });
+    queuedBytes += c.byteLength;
+    wake();
+    if (!paused && (queue.length >= maxQueue || queuedBytes >= maxQueueBytes)) {
+      paused = true;
+      child.stdout?.pause();
+      child.stderr?.pause();
+    }
+  };
+  const onErr = (c) => {
+    const s = c.toString();
+    stderrBytes += c.byteLength;
+    emitProcessOutput({ pid, stream: "stderr", chunk: c });
+    if (stderrRetainedBytes < max) {
+      const retained = utf8Prefix(s, max - stderrRetainedBytes);
+      stderr += retained;
+      stderrRetainedBytes += Buffer.byteLength(retained, "utf8");
+    }
+    spool.write(s);
+    queue.push({ kind: "err", data: s, bytes: c.byteLength });
+    queuedBytes += c.byteLength;
+    wake();
+    if (!paused && (queue.length >= maxQueue || queuedBytes >= maxQueueBytes)) {
+      paused = true;
+      child.stdout?.pause();
+      child.stderr?.pause();
+    }
+  };
+  child.stdout?.on("data", onOut);
+  child.stderr?.on("data", onErr);
+  child.on("error", (e) => {
+    error = e.message;
+    const bytes = Buffer.byteLength(e.message, "utf8");
+    queue.push({ kind: "error", data: e.message, bytes });
+    queuedBytes += bytes;
+    wake();
+  });
+  const completeTelemetry = (code, signal, timedOut = false) => {
+    if (telemetryCompleted) return;
+    telemetryCompleted = true;
+    emitProcessCompleted({
+      ...pid !== void 0 ? { pid } : {},
+      exitCode: code,
+      ...signal ? { signal } : {},
+      durationMs: Date.now() - processStartedAt,
+      stdoutBytes,
+      stderrBytes,
+      timedOut,
+      endedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  child.on("close", (code, signal) => {
+    if (typeof pid === "number") registry.unregister(pid);
+    const exitCode2 = code ?? (signal ? 1 : 0);
+    completeTelemetry(exitCode2, signal ?? void 0);
+    queue.push({
+      kind: "close",
+      data: "",
+      bytes: 0,
+      code: exitCode2,
+      ...signal ? { signal } : {}
+    });
+    wake();
+  });
+  const onAbort = () => {
+    if (typeof pid === "number") {
+      registry.kill(pid, { force: true });
+    } else {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+    }
+    queue.push({ kind: "close", data: "", bytes: 0, code: 124 });
+    completeTelemetry(124, "SIGKILL", true);
+    wake();
+  };
+  if (isWin) {
+    if (opts.signal.aborted) onAbort();
+    else opts.signal.addEventListener("abort", onAbort, { once: true });
+  }
+  let exitCode = 0;
+  let spawnFailed = false;
+  try {
+    for (; ; ) {
+      while (queue.length === 0) {
+        await new Promise((resolve) => {
+          waiter = resolve;
+        });
+      }
+      const chunk = queue.shift();
+      queuedBytes -= chunk.bytes;
+      resume();
+      if (chunk.kind === "close") {
+        if (!spawnFailed) exitCode = chunk.code ?? 0;
+        break;
+      }
+      if (chunk.kind === "error") {
+        spawnFailed = true;
+        exitCode = 1;
+        continue;
+      }
+      pending += chunk.data;
+      if (pending.length >= flushAt) {
+        yield { type: "partial_output", text: pending };
+        pending = "";
+      }
+    }
+    if (pending.length > 0) {
+      yield { type: "partial_output", text: pending };
+    }
+    const spooled = spool.finalize();
+    return {
+      // The marker rides on stdout's tail so every consumer's head+tail
+      // normalization keeps it without per-tool changes.
+      stdout: spooled ? stdout + spoolNote(spooled) : stdout,
+      stderr,
+      exitCode,
+      truncated: stdoutBytes > stdoutRetainedBytes || stderrBytes > stderrRetainedBytes,
+      error,
+      spoolPath: spooled?.path,
+      spoolBytes: spooled?.bytes
+    };
+  } finally {
+    spool.finalize();
+    if (isWin) opts.signal.removeEventListener("abort", onAbort);
+    child.stdout?.off("data", onOut);
+    child.stderr?.off("data", onErr);
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    if (child.exitCode === null && !child.killed) {
+      if (typeof pid === "number") {
+        registry.kill(pid, { force: true });
+      } else {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }
+    }
+  }
+}
+function utf8Prefix(text, maxBytes) {
+  if (maxBytes <= 0) return "";
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(text.slice(0, mid), "utf8") <= maxBytes) low = mid;
+    else high = mid - 1;
+  }
+  let end = low;
+  if (end > 0 && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+  return text.slice(0, end);
+}
+
+export {
+  spawnStream
+};
+//# sourceMappingURL=chunk-MAN26PZ5.js.map