@joshski/dust 0.1.13 → 0.1.15

package/README.md

@@ -2,7 +2,7 @@
 
 **Flow state for AI coding agents.**
 
-Dust provides a CLI that agents use to systematically blitz through your work queue.
+Dust provides a CLI that agents use to systematically blaze through your backlog.
 
 [![CI](https://github.com/joshski/dust/actions/workflows/ci.yml/badge.svg)](https://github.com/joshski/dust/actions/workflows/ci.yml)
 

package/dist/dust.js

@@ -97,6 +97,20 @@ function loadTemplate(name, variables = {}) {
   return content;
 }
 
+// lib/agents/detection.ts
+function detectAgent(env = process.env) {
+  if (env.CLAUDECODE) {
+    if (env.CLAUDE_CODE_ENTRYPOINT === "remote") {
+      return { type: "claude-code-web", name: "Claude Code Web" };
+    }
+    return { type: "claude-code", name: "Claude Code" };
+  }
+  if (env.CODEX_HOME) {
+    return { type: "codex", name: "Codex" };
+  }
+  return { type: "unknown", name: "Agent" };
+}
+
 // lib/git/hooks.ts
 import { join as join3 } from "node:path";
 var DUST_HOOK_START = "# BEGIN DUST HOOK";
@@ -220,25 +234,13 @@ ${newHookContent}
 }
 
 // lib/cli/commands/agent-shared.ts
-function detectAgent(env = process.env) {
-  if (env.CLAUDECODE) {
-    if (env.CLAUDE_CODE_ENTRYPOINT === "remote") {
-      return "Claude Code Web";
-    }
-    return "Claude Code";
-  }
-  if (env.CODEX_HOME) {
-    return "Codex";
-  }
-  return "Agent";
-}
 function templateVariables(settings, hooksInstalled, env = process.env) {
-  const agentName = detectAgent(env);
+  const agent = detectAgent(env);
   return {
     bin: settings.dustCommand,
-    agentName,
+    agentName: agent.name,
     hooksInstalled: hooksInstalled ? "true" : "false",
-    isClaudeCodeWeb: agentName === "Claude Code Web" ? "true" : ""
+    isClaudeCodeWeb: agent.type === "claude-code-web" ? "true" : ""
   };
 }
 async function manageGitHooks(dependencies) {
@@ -330,6 +332,7 @@ function extractOpeningSentence(content) {
 var REQUIRED_HEADINGS = ["## Goals", "## Blocked by", "## Definition of done"];
 var REQUIRED_GOAL_HEADINGS = ["## Parent Goal", "## Sub-Goals"];
 var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
+var MAX_OPENING_SENTENCE_LENGTH = 150;
 function validateFilename(filePath) {
   const parts = filePath.split("/");
   const filename = parts[parts.length - 1];
@@ -370,6 +373,19 @@ function validateOpeningSentence(filePath, content) {
   }
   return null;
 }
+function validateOpeningSentenceLength(filePath, content) {
+  const openingSentence = extractOpeningSentence(content);
+  if (!openingSentence) {
+    return null;
+  }
+  if (openingSentence.length > MAX_OPENING_SENTENCE_LENGTH) {
+    return {
+      file: filePath,
+      message: `Opening sentence is ${openingSentence.length} characters (max ${MAX_OPENING_SENTENCE_LENGTH}). Split into multiple sentences; only the first sentence is checked.`
+    };
+  }
+  return null;
+}
 function validateTaskHeadings(filePath, content) {
   const violations = [];
   for (const heading of REQUIRED_HEADINGS) {
@@ -662,6 +678,10 @@ async function lintMarkdown(dependencies) {
       if (openingSentenceViolation) {
         violations.push(openingSentenceViolation);
       }
+      const openingSentenceLengthViolation = validateOpeningSentenceLength(filePath, content);
+      if (openingSentenceLengthViolation) {
+        violations.push(openingSentenceLengthViolation);
+      }
       const titleFilenameViolation = validateTitleFilenameMatch(filePath, content);
       if (titleFilenameViolation) {
         violations.push(titleFilenameViolation);
@@ -1101,7 +1121,8 @@ async function* spawnClaudeCode(prompt, options = {}, dependencies = defaultDepe
     model,
     systemPrompt,
     sessionId,
-    dangerouslySkipPermissions
+    dangerouslySkipPermissions,
+    env
   } = options;
   const claudeArguments = [
     "-p",
@@ -1131,7 +1152,8 @@ async function* spawnClaudeCode(prompt, options = {}, dependencies = defaultDepe
   }
   const proc = dependencies.spawn("claude", claudeArguments, {
     cwd,
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, ...env }
   });
   if (!proc.stdout) {
     throw new Error("Failed to get stdout from claude process");
@@ -1202,7 +1224,216 @@ function* parseRawEvent(raw) {
   }
 }
 
+// lib/claude/tool-formatters.ts
+var DIVIDER = "────────────────────────────────";
+function formatWrite(input) {
+  const filePath = input.file_path;
+  const content = input.content;
+  const others = getUnrecognizedArgs(input, ["file_path", "content"]);
+  const lines = [];
+  lines.push(`\uD83D\uDD27 Write: ${filePath ?? "(unknown)"}`);
+  lines.push(DIVIDER);
+  if (content !== undefined) {
+    for (const line of content.split(`
+`)) {
+      lines.push(line);
+    }
+  }
+  lines.push(DIVIDER);
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatEdit(input) {
+  const filePath = input.file_path;
+  const oldString = input.old_string;
+  const newString = input.new_string;
+  const others = getUnrecognizedArgs(input, [
+    "file_path",
+    "old_string",
+    "new_string",
+    "replace_all"
+  ]);
+  const lines = [];
+  lines.push(`\uD83D\uDD27 Edit: ${filePath ?? "(unknown)"}`);
+  lines.push("Replace:");
+  lines.push(DIVIDER);
+  if (oldString !== undefined) {
+    for (const line of oldString.split(`
+`)) {
+      lines.push(line);
+    }
+  }
+  lines.push(DIVIDER);
+  lines.push("With:");
+  lines.push(DIVIDER);
+  if (newString !== undefined) {
+    for (const line of newString.split(`
+`)) {
+      lines.push(line);
+    }
+  }
+  lines.push(DIVIDER);
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatRead(input) {
+  const filePath = input.file_path;
+  const offset = input.offset;
+  const limit = input.limit;
+  const others = getUnrecognizedArgs(input, ["file_path", "offset", "limit"]);
+  const lines = [];
+  let lineRange = "";
+  if (offset !== undefined || limit !== undefined) {
+    const start = offset ?? 1;
+    const end = limit !== undefined ? start + limit - 1 : undefined;
+    lineRange = end !== undefined ? ` (lines ${start}-${end})` : ` (from line ${start})`;
+  }
+  lines.push(`\uD83D\uDD27 Read: ${filePath ?? "(unknown)"}${lineRange}`);
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatBash(input) {
+  const command = input.command;
+  const description = input.description;
+  const others = getUnrecognizedArgs(input, [
+    "command",
+    "description",
+    "timeout",
+    "run_in_background",
+    "dangerouslyDisableSandbox",
+    "_simulatedSedEdit"
+  ]);
+  const lines = [];
+  const header = description ?? "Run command";
+  lines.push(`\uD83D\uDD27 Bash: ${header}`);
+  if (command !== undefined) {
+    lines.push(`$ ${command}`);
+  }
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatTodoWrite(input) {
+  const todos = input.todos;
+  const others = getUnrecognizedArgs(input, ["todos"]);
+  const lines = [];
+  const count = todos?.length ?? 0;
+  lines.push(`\uD83D\uDD27 TodoWrite: ${count} item${count === 1 ? "" : "s"}`);
+  if (todos) {
+    for (const todo of todos) {
+      const icon = todo.status === "completed" ? "☑" : "☐";
+      lines.push(`${icon} ${todo.content}`);
+    }
+  }
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatGrep(input) {
+  const pattern = input.pattern;
+  const path = input.path;
+  const glob = input.glob;
+  const type = input.type;
+  const others = getUnrecognizedArgs(input, [
+    "pattern",
+    "path",
+    "glob",
+    "type",
+    "output_mode",
+    "context",
+    "-A",
+    "-B",
+    "-C",
+    "-i",
+    "-n",
+    "head_limit",
+    "offset",
+    "multiline"
+  ]);
+  const lines = [];
+  const location = path ?? ".";
+  let filter = "";
+  if (glob) {
+    filter = ` (${glob})`;
+  } else if (type) {
+    filter = ` (type: ${type})`;
+  }
+  lines.push(`\uD83D\uDD27 Grep: "${pattern ?? ""}" in ${location}${filter}`);
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatGlob(input) {
+  const pattern = input.pattern;
+  const path = input.path;
+  const others = getUnrecognizedArgs(input, ["pattern", "path"]);
+  const lines = [];
+  const location = path ?? ".";
+  lines.push(`\uD83D\uDD27 Glob: ${pattern ?? ""} in ${location}`);
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatTask(input) {
+  const description = input.description;
+  const subagentType = input.subagent_type;
+  const prompt = input.prompt;
+  const others = getUnrecognizedArgs(input, [
+    "description",
+    "subagent_type",
+    "prompt",
+    "model",
+    "max_turns",
+    "resume",
+    "run_in_background"
+  ]);
+  const lines = [];
+  const header = description ?? subagentType ?? "task";
+  lines.push(`\uD83D\uDD27 Task: ${header}`);
+  if (prompt !== undefined) {
+    const truncated = prompt.length > 100 ? `${prompt.slice(0, 100)}...` : prompt;
+    lines.push(`"${truncated}"`);
+  }
+  appendOtherArgs(lines, others);
+  return lines;
+}
+function formatFallback(name, input) {
+  const lines = [];
+  lines.push(`\uD83D\uDD27 Tool: ${name}`);
+  lines.push(`Input: ${JSON.stringify(input, null, 2)}`);
+  return lines;
+}
+var formatters = {
+  Write: formatWrite,
+  Edit: formatEdit,
+  Read: formatRead,
+  Bash: formatBash,
+  TodoWrite: formatTodoWrite,
+  Grep: formatGrep,
+  Glob: formatGlob,
+  Task: formatTask
+};
+function formatToolUse(name, input) {
+  const formatter = formatters[name];
+  if (formatter) {
+    return formatter(input);
+  }
+  return formatFallback(name, input);
+}
+function getUnrecognizedArgs(input, knownKeys) {
+  const others = {};
+  for (const key of Object.keys(input)) {
+    if (!knownKeys.includes(key)) {
+      others[key] = input[key];
+    }
+  }
+  return others;
+}
+function appendOtherArgs(lines, others) {
+  if (Object.keys(others).length > 0) {
+    lines.push("");
+    lines.push(`(Other arguments: ${JSON.stringify(others)})`);
+  }
+}
+
 // lib/claude/streamer.ts
+var DIVIDER2 = "────────────────────────────────";
 async function streamEvents(events, sink) {
   let hadTextOutput = false;
   for await (const raw of events) {
@@ -1226,12 +1457,15 @@ function processEvent(event, sink, state) {
         sink.line("");
         sink.line("");
       }
-      sink.line(`\uD83D\uDD27 Tool: ${event.name}`);
-      sink.line(`   Input: ${JSON.stringify(event.input, null, 2).replace(/\n/g, `
-   `)}`);
+      for (const line of formatToolUse(event.name, event.input)) {
+        sink.line(line);
+      }
       break;
     case "tool_result":
-      sink.line(`✅ Result (${event.content.length} chars)`);
+      sink.line("Result:");
+      sink.line(DIVIDER2);
+      sink.line(event.content);
+      sink.line(DIVIDER2);
       sink.line("");
       break;
     case "result":
@@ -1331,11 +1565,71 @@ async function next(dependencies) {
 }
 
 // lib/cli/commands/loop.ts
+function formatEvent(event) {
+  switch (event.type) {
+    case "loop.warning":
+      return "⚠️  WARNING: This command skips all permission checks. Only use in a sandbox environment!";
+    case "loop.started":
+      return `\uD83D\uDD04 Starting dust loop claude (max ${event.maxIterations} iterations)...`;
+    case "loop.syncing":
+      return "\uD83D\uDD04 Syncing with remote...";
+    case "loop.sync_skipped":
+      return `Note: git pull skipped (${event.reason})`;
+    case "loop.checking_tasks":
+      return "\uD83D\uDD0D Checking for available tasks...";
+    case "loop.no_tasks":
+      return "\uD83D\uDCA4 No tasks available. Sleeping...";
+    case "loop.tasks_found":
+      return "✨ Found task(s). \uD83E\uDD16 Starting Claude...";
+    case "claude.started":
+      return "\uD83E\uDD16 Claude session started";
+    case "claude.ended":
+      return event.success ? "\uD83E\uDD16 Claude session ended (success)" : `\uD83E\uDD16 Claude session ended (error: ${event.error})`;
+    case "loop.iteration_complete":
+      return `\uD83D\uDCCB Completed iteration ${event.iteration}/${event.maxIterations}`;
+    case "loop.ended":
+      return `\uD83C\uDFC1 Reached max iterations (${event.maxIterations}). Exiting.`;
+  }
+}
+async function defaultPostEvent(url, payload) {
+  await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+}
 function createDefaultDependencies() {
   return {
     spawn: nodeSpawn2,
     run,
-    sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms))
+    sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
+    postEvent: defaultPostEvent
+  };
+}
+function createEventPoster(eventsUrl, sessionId, postEvent, onError) {
+  let sequence = 0;
+  let currentAgentSessionId;
+  return (event) => {
+    if (!eventsUrl)
+      return;
+    sequence++;
+    if (event.type === "claude.started") {
+      currentAgentSessionId = crypto.randomUUID();
+    }
+    const payload = {
+      sequence,
+      timestamp: new Date().toISOString(),
+      sessionId,
+      event
+    };
+    if (event.type.startsWith("claude.") && currentAgentSessionId) {
+      payload.agentSessionId = currentAgentSessionId;
+      payload.agentType = "claude";
+    }
+    postEvent(eventsUrl, payload).catch(onError);
+    if (event.type === "claude.ended") {
+      currentAgentSessionId = undefined;
+    }
   };
 }
 var SLEEP_INTERVAL_MS = 30000;
@@ -1373,35 +1667,61 @@ async function hasAvailableTasks(dependencies) {
   await next({ ...dependencies, context: captureContext });
   return hasOutput;
 }
-async function runOneIteration(dependencies, loopDependencies) {
+async function runOneIteration(dependencies, loopDependencies, emit) {
   const { context } = dependencies;
   const { spawn: spawn2, run: run2 } = loopDependencies;
-  context.stdout("\uD83D\uDD04 Syncing with remote...");
+  emit({ type: "loop.syncing" });
   const pullResult = await gitPull(context.cwd, spawn2);
   if (!pullResult.success) {
-    context.stdout(`Note: git pull skipped (${pullResult.message})`);
+    emit({
+      type: "loop.sync_skipped",
+      reason: pullResult.message ?? "unknown error"
+    });
+    emit({ type: "claude.started" });
+    const prompt = `git pull failed with the following error:
+
+${pullResult.message}
+
+Please resolve this issue. Common approaches:
+1. If there are merge conflicts, resolve them
+2. If local commits need to be rebased, use git rebase
+3. After resolving, commit any changes and push to remote
+
+Make sure the repository is in a clean state and synced with remote before finishing.`;
+    try {
+      await run2(prompt, {
+        cwd: context.cwd,
+        dangerouslySkipPermissions: true,
+        env: { DUST_UNATTENDED: "1" }
+      });
+      emit({ type: "claude.ended", success: true });
+      return "resolved_pull_conflict";
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      context.stderr(`Claude failed to resolve git pull conflict: ${errorMessage}`);
+      emit({ type: "claude.ended", success: false, error: errorMessage });
+    }
   }
-  context.stdout("\uD83D\uDD0D Checking for available tasks...");
+  emit({ type: "loop.checking_tasks" });
   const hasTasks = await hasAvailableTasks(dependencies);
   if (!hasTasks) {
-    context.stdout("\uD83D\uDCA4 No tasks available. Sleeping...");
-    context.stdout("");
+    emit({ type: "loop.no_tasks" });
     return "no_tasks";
   }
-  context.stdout("✨ Found task(s). \uD83E\uDD16 Starting Claude...");
-  context.stdout("");
+  emit({ type: "loop.tasks_found" });
+  emit({ type: "claude.started" });
   try {
-    await run2("go", { cwd: context.cwd, dangerouslySkipPermissions: true });
-    context.stdout("");
-    context.stdout("✅ Claude session complete. Continuing loop...");
-    context.stdout("");
+    await run2("go", {
+      cwd: context.cwd,
+      dangerouslySkipPermissions: true,
+      env: { DUST_UNATTENDED: "1" }
+    });
+    emit({ type: "claude.ended", success: true });
     return "ran_claude";
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    context.stderr(`Claude exited with error: ${message}`);
-    context.stdout("");
-    context.stdout("✅ Claude session complete. Continuing loop...");
-    context.stdout("");
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    context.stderr(`Claude exited with error: ${errorMessage}`);
+    emit({ type: "claude.ended", success: false, error: errorMessage });
     return "claude_error";
   }
 }
@@ -1416,25 +1736,38 @@ function parseMaxIterations(commandArguments) {
   return parsed;
 }
 async function loopClaude(dependencies, loopDependencies = createDefaultDependencies()) {
-  const { context } = dependencies;
+  const { context, settings } = dependencies;
+  const { postEvent } = loopDependencies;
   const maxIterations = parseMaxIterations(dependencies.arguments);
-  context.stdout("⚠️  WARNING: This command skips all permission checks. Only use in a sandbox environment!");
-  context.stdout("");
-  context.stdout(`\uD83D\uDD04 Starting dust loop claude (max ${maxIterations} iterations)...`);
+  const eventsUrl = settings.eventsUrl;
+  const sessionId = crypto.randomUUID();
+  const postTypedEvent = createEventPoster(eventsUrl, sessionId, postEvent, (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    context.stderr(`Event POST failed: ${message}`);
+  });
+  const emit = (event) => {
+    context.stdout(formatEvent(event));
+    postTypedEvent(event);
+  };
+  emit({ type: "loop.warning" });
+  emit({ type: "loop.started", maxIterations });
   context.stdout("   Press Ctrl+C to stop");
   context.stdout("");
   let completedIterations = 0;
   while (completedIterations < maxIterations) {
-    const result = await runOneIteration(dependencies, loopDependencies);
+    const result = await runOneIteration(dependencies, loopDependencies, emit);
     if (result === "no_tasks") {
       await loopDependencies.sleep(SLEEP_INTERVAL_MS);
     } else {
       completedIterations++;
-      context.stdout(`\uD83D\uDCCB Completed iteration ${completedIterations}/${maxIterations}`);
-      context.stdout("");
+      emit({
+        type: "loop.iteration_complete",
+        iteration: completedIterations,
+        maxIterations
+      });
     }
   }
-  context.stdout(`\uD83C\uDFC1 Reached max iterations (${maxIterations}). Exiting.`);
+  emit({ type: "loop.ended", maxIterations });
   return { exitCode: 0 };
 }
 
@@ -1535,12 +1868,50 @@ async function getChangesFromRemote(cwd, gitRunner) {
   }
   return parseGitDiffNameStatus(diffResult.output);
 }
-async function prePush(dependencies, gitRunner = defaultGitRunner) {
+async function getUncommittedFiles(cwd, gitRunner) {
+  const result = await gitRunner.run(["status", "--porcelain"], cwd);
+  if (result.exitCode !== 0 || !result.output.trim()) {
+    return [];
+  }
+  const files = [];
+  const lines = result.output.split(`
+`).filter((line) => line.length > 0);
+  for (const line of lines) {
+    if (line.length > 3) {
+      const path = line.substring(3);
+      const arrowIndex = path.indexOf(" -> ");
+      if (arrowIndex !== -1) {
+        files.push(path.substring(arrowIndex + 4));
+      } else {
+        files.push(path);
+      }
+    }
+  }
+  return files;
+}
+async function prePush(dependencies, gitRunner = defaultGitRunner, env = process.env) {
   const { context } = dependencies;
+  if (env.DUST_UNATTENDED) {
+    const uncommittedFiles = await getUncommittedFiles(context.cwd, gitRunner);
+    if (uncommittedFiles.length > 0) {
+      context.stderr("");
+      context.stderr("⚠️  Push blocked: uncommitted changes detected in unattended mode.");
+      context.stderr("");
+      context.stderr("You are running in unattended mode (DUST_UNATTENDED=1) and have uncommitted files:");
+      for (const file of uncommittedFiles) {
+        context.stderr(`  → ${file}`);
+      }
+      context.stderr("");
+      context.stderr("Commit or discard these changes before pushing to avoid broken builds.");
+      context.stderr("");
+      return { exitCode: 1 };
+    }
+  }
   const changes = await getChangesFromRemote(context.cwd, gitRunner);
   if (changes.length > 0) {
     const analysis = analyzeChangesForTaskOnlyPattern(changes);
-    if (analysis.isTaskOnly) {
+    const agent2 = detectAgent(env);
+    if (analysis.isTaskOnly && agent2.type === "claude-code-web") {
       context.stderr("");
       context.stderr("⚠️  Task-only commit detected! You added a task but did not implement it.");
       context.stderr("");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.13",
-  "description": "A lightweight planning system for human-AI collaboration",
+  "version": "0.1.15",
+  "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
     "dust": "./dist/dust.js"