@joshski/dust 0.1.7 → 0.1.8

package/README.md

@@ -1,23 +1,25 @@
 # Dust
 
-A lightweight planning system and work tracker optimised for humans working with AI agents.
+A lightweight workflow tool for humans working with AI agents.
 
 [![CI](https://github.com/joshski/dust/actions/workflows/ci.yml/badge.svg)](https://github.com/joshski/dust/actions/workflows/ci.yml)
 
+## Why Would I Use This?
+
+Use this to plan a series of tasks that coding agents can perform autonomously.
+
 ## Getting Started
 
-Install dust:
+Install dust using your package manager of choice (`npm` and `bun` officially supported for now):
 
 ```bash
-npm install -g @joshski/dust
+npm install @joshski/dust
 ```
 
 Initialize dust in your repository:
 
 ```bash
 npx dust init
-# or
-bunx dust init
 ```
 
 ## How It Works
@@ -39,3 +41,54 @@ These files are used to facilitate exploration and management of AI agent workfl
 Progress is tracked via changes to markdown files in the `.dust/` directory. The four directories together (`goals/`, `ideas/`, `tasks/`, `facts/`) act as a kanban system for managing work.
 
 The `tasks/` directory acts as a work queue. When a task is completed, the commit typically includes both the code changes and the deletion of the task file—removing work from the queue for subsequent agents.
+
+Humans primarily interact with `dust` using their AI coding agent of choice, e.g.
+
+```
+> claude "implement the next task"
+> claude "get to work!"
+> codex "add task: coverage reporting"
+> codex "goal: cross-platform compatibility"
+```
+
+Agents discover everything they need to know to interpret human prompts using the `dust` CLI.
+
+## Agent CLI
+
+The `dust` CLI is intended to be used primarily by agents, not by humans (except for the `init` command, as mentioned above).
+
+Don't let that stop you:
+
+```bash
+npx dust help
+```
+
+## AGENTS.md
+
+Add a line like this to your `AGENTS.md` or `CLAUDE.md` file:
+
+```markdown
+Always immediately run `npx dust agent` when you start working in this repository.
+```
+
+In fact, you might find it effective to use that as the _only_ line in those files. Essential documentation should be discoverable by agents exploring your `./.dust` directory.
+
+## Configuration
+
+Configure hooks into your tools in `./.dust/config/settings.json` e.g.
+
+```json
+{
+  "dustCommand": "bunx dust",
+  "checks": [
+    { "name": "lint", "command": "bunx biome check ." },
+    { "name": "build", "command": "bun run build" },
+    { "name": "tests", "command": "bun run test:coverage" },
+    { "name": "typecheck", "command": "bunx tsc --noEmit lib/**/*.ts" }
+  ]
+}
+```
+
+The `dust check` command will run all of the configured checks in parallel and produce a very terse (context window-friendly) output unless one or more of the checks fail.
+
+Agents are instructed to run `dust check` before and after any changes, as a way of keeping them on track. It's more important that these commands are comprehensive, than they are fast.

package/dist/dust.js

@@ -18,7 +18,7 @@ function loadTemplate(name, variables = {}) {
   return content;
 }
 
-// lib/cli/agent.ts
+// lib/cli/commands/agent.ts
 var AGENT_SUBCOMMANDS = [
   "work",
   "tasks",
@@ -26,45 +26,32 @@ var AGENT_SUBCOMMANDS = [
   "ideas",
   "help"
 ];
-function generateAgentGreeting(settings) {
-  return loadTemplate("agent-greeting", { bin: settings.dustCommand });
+function templateVariables(settings) {
+  return { bin: settings.dustCommand };
 }
-function generateWorkInstructions(settings) {
-  return loadTemplate("agent-work", { bin: settings.dustCommand });
-}
-function generateTasksInstructions(settings) {
-  return loadTemplate("agent-tasks", { bin: settings.dustCommand });
-}
-function generateGoalsInstructions(settings) {
-  return loadTemplate("agent-goals", { bin: settings.dustCommand });
-}
-function generateIdeasInstructions(settings) {
-  return loadTemplate("agent-ideas", { bin: settings.dustCommand });
-}
-function generateAgentHelp(settings) {
-  return loadTemplate("agent-help", { bin: settings.dustCommand });
-}
-async function agent(ctx, args, settings) {
+async function agent(deps) {
+  const { arguments: args, context: ctx, settings } = deps;
   const subcommand = args[0];
+  const vars = templateVariables(settings);
   if (!subcommand) {
-    ctx.stdout(generateAgentGreeting(settings));
+    ctx.stdout(loadTemplate("agent-greeting", vars));
     return { exitCode: 0 };
   }
   switch (subcommand) {
     case "work":
-      ctx.stdout(generateWorkInstructions(settings));
+      ctx.stdout(loadTemplate("agent-work", vars));
       return { exitCode: 0 };
     case "tasks":
-      ctx.stdout(generateTasksInstructions(settings));
+      ctx.stdout(loadTemplate("agent-tasks", vars));
       return { exitCode: 0 };
     case "goals":
-      ctx.stdout(generateGoalsInstructions(settings));
+      ctx.stdout(loadTemplate("agent-goals", vars));
       return { exitCode: 0 };
     case "ideas":
-      ctx.stdout(generateIdeasInstructions(settings));
+      ctx.stdout(loadTemplate("agent-ideas", vars));
       return { exitCode: 0 };
     case "help":
-      ctx.stdout(generateAgentHelp(settings));
+      ctx.stdout(loadTemplate("agent-help", vars));
       return { exitCode: 0 };
     default:
       ctx.stderr(`Unknown subcommand: ${subcommand}`);
@@ -73,59 +60,20 @@ async function agent(ctx, args, settings) {
   }
 }
 
-// lib/cli/check.ts
+// lib/cli/commands/check.ts
 import { spawn } from "node:child_process";
 
-// lib/cli/settings.ts
-import { join as join2 } from "node:path";
-var DEFAULT_SETTINGS = {
-  dustCommand: "npx dust"
-};
-function detectDustCommand(cwd, fs) {
-  if (fs.exists(join2(cwd, "bun.lockb"))) {
-    return "bunx dust";
-  }
-  if (fs.exists(join2(cwd, "pnpm-lock.yaml"))) {
-    return "pnpx dust";
-  }
-  if (fs.exists(join2(cwd, "package-lock.json"))) {
-    return "npx dust";
-  }
-  if (process.env.BUN_INSTALL) {
-    return "bunx dust";
-  }
-  return "npx dust";
-}
-async function loadSettings(cwd, fs) {
-  const settingsPath = join2(cwd, ".dust", "config", "settings.json");
-  if (!fs.exists(settingsPath)) {
-    return {
-      dustCommand: detectDustCommand(cwd, fs)
-    };
-  }
-  try {
-    const content = await fs.readFile(settingsPath);
-    const parsed = JSON.parse(content);
-    if (!parsed.dustCommand) {
-      return {
-        ...DEFAULT_SETTINGS,
-        ...parsed,
-        dustCommand: detectDustCommand(cwd, fs)
-      };
-    }
-    return {
-      ...DEFAULT_SETTINGS,
-      ...parsed
-    };
-  } catch {
-    return {
-      dustCommand: detectDustCommand(cwd, fs)
-    };
-  }
+// lib/cli/commands/validate.ts
+import { dirname as dirname2, resolve } from "node:path";
+
+// lib/cli/markdown-utilities.ts
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
 }
+var MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/;
 
-// lib/cli/validate.ts
-import { dirname as dirname2, resolve } from "node:path";
+// lib/cli/commands/validate.ts
 var REQUIRED_HEADINGS = ["## Goals", "## Blocked by", "## Definition of done"];
 var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
 function validateFilename(filePath) {
@@ -158,7 +106,7 @@ function validateLinks(filePath, content, fs) {
   const fileDir = dirname2(filePath);
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
-    const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
     let match = linkPattern.exec(line);
     while (match) {
       const linkTarget = match[2];
@@ -205,7 +153,7 @@ function validateSemanticLinks(filePath, content) {
     const rule = SEMANTIC_RULES.find((r) => r.section === currentSection);
     if (!rule)
       continue;
-    const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
     let match = linkPattern.exec(line);
     while (match) {
       const linkTarget = match[2];
@@ -241,7 +189,8 @@ function validateSemanticLinks(filePath, content) {
   }
   return violations;
 }
-async function validate(ctx, fs, _args, glob) {
+async function validate(deps) {
+  const { context: ctx, fileSystem: fs, globScanner: glob } = deps;
   const dustPath = `${ctx.cwd}/.dust`;
   if (!fs.exists(dustPath)) {
     ctx.stderr("Error: .dust directory not found");
@@ -287,7 +236,7 @@ async function validate(ctx, fs, _args, glob) {
   return { exitCode: 1 };
 }
 
-// lib/cli/check.ts
+// lib/cli/commands/check.ts
 function createBufferedRunner(spawnFn) {
   return {
     run: (command, cwd) => {
@@ -323,14 +272,18 @@ async function runConfiguredChecks(checks, cwd, runner) {
   });
   return Promise.all(promises);
 }
-async function runValidationCheck(ctx, fs, glob) {
+async function runValidationCheck(deps) {
   const outputLines = [];
   const bufferedCtx = {
-    cwd: ctx.cwd,
+    cwd: deps.context.cwd,
     stdout: (msg) => outputLines.push(msg),
     stderr: (msg) => outputLines.push(msg)
   };
-  const result = await validate(bufferedCtx, fs, [], glob);
+  const result = await validate({
+    ...deps,
+    context: bufferedCtx,
+    arguments: []
+  });
   return {
     name: "validate",
     command: "dust validate",
@@ -361,8 +314,8 @@ function displayResults(results, ctx) {
   ctx.stdout(`${passed.length}/${results.length} checks passed`);
   return failed.length > 0 ? 1 : 0;
 }
-async function check(ctx, fs, _args, glob, bufferedRunner = defaultBufferedRunner) {
-  const settings = await loadSettings(ctx.cwd, fs);
+async function check(deps, bufferedRunner = defaultBufferedRunner) {
+  const { context: ctx, fileSystem: fs, settings } = deps;
   if (!settings.checks || settings.checks.length === 0) {
     ctx.stderr("Error: No checks configured in .dust/config/settings.json");
     ctx.stderr("");
@@ -376,8 +329,9 @@ async function check(ctx, fs, _args, glob, bufferedRunner = defaultBufferedRunne
     return { exitCode: 1 };
   }
   const checkPromises = [];
-  if (glob) {
-    checkPromises.push(runValidationCheck(ctx, fs, glob));
+  const dustPath = `${ctx.cwd}/.dust`;
+  if (fs.exists(dustPath)) {
+    checkPromises.push(runValidationCheck(deps));
   }
   checkPromises.push(runConfiguredChecks(settings.checks, ctx.cwd, bufferedRunner));
   const promiseResults = await Promise.all(checkPromises);
@@ -393,13 +347,74 @@ async function check(ctx, fs, _args, glob, bufferedRunner = defaultBufferedRunne
   return { exitCode };
 }
 
-// lib/cli/init.ts
-var DUST_DIRECTORIES = ["goals", "ideas", "tasks", "facts"];
+// lib/cli/settings.ts
+import { join as join2 } from "node:path";
+var DEFAULT_SETTINGS = {
+  dustCommand: "npx dust"
+};
+function detectDustCommand(cwd, fs) {
+  if (fs.exists(join2(cwd, "bun.lockb"))) {
+    return "bunx dust";
+  }
+  if (fs.exists(join2(cwd, "pnpm-lock.yaml"))) {
+    return "pnpx dust";
+  }
+  if (fs.exists(join2(cwd, "package-lock.json"))) {
+    return "npx dust";
+  }
+  if (process.env.BUN_INSTALL) {
+    return "bunx dust";
+  }
+  return "npx dust";
+}
+async function loadSettings(cwd, fs) {
+  const settingsPath = join2(cwd, ".dust", "config", "settings.json");
+  if (!fs.exists(settingsPath)) {
+    return {
+      dustCommand: detectDustCommand(cwd, fs)
+    };
+  }
+  try {
+    const content = await fs.readFile(settingsPath);
+    const parsed = JSON.parse(content);
+    if (!parsed.dustCommand) {
+      return {
+        ...DEFAULT_SETTINGS,
+        ...parsed,
+        dustCommand: detectDustCommand(cwd, fs)
+      };
+    }
+    return {
+      ...DEFAULT_SETTINGS,
+      ...parsed
+    };
+  } catch {
+    return {
+      dustCommand: detectDustCommand(cwd, fs)
+    };
+  }
+}
+
+// lib/cli/commands/init.ts
+var DUST_DIRECTORIES = ["goals", "ideas", "tasks", "facts", "config"];
+function generateSettings(cwd, fs) {
+  const dustCommand = detectDustCommand(cwd, fs);
+  const checks = [];
+  if (fs.exists(`${cwd}/bun.lockb`)) {
+    checks.push({ name: "test", command: "bun test" });
+  } else if (fs.exists(`${cwd}/pnpm-lock.yaml`)) {
+    checks.push({ name: "test", command: "pnpm test" });
+  } else if (fs.exists(`${cwd}/package-lock.json`) || fs.exists(`${cwd}/package.json`)) {
+    checks.push({ name: "test", command: "npm test" });
+  }
+  return { dustCommand, checks };
+}
 var USE_DUST_FACT = `# Use dust for planning
 
 This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
 `;
-async function init(ctx, fs, _args) {
+async function init(deps) {
+  const { context: ctx, fileSystem: fs } = deps;
   const dustPath = `${ctx.cwd}/.dust`;
   const dustCommand = detectDustCommand(ctx.cwd, fs);
   const agentInstruction = `Always immediately run \`${dustCommand} agent\` when you start working in this repository.`;
@@ -411,9 +426,13 @@ async function init(ctx, fs, _args) {
       await fs.mkdir(`${dustPath}/${dir}`, { recursive: true });
     }
     await fs.writeFile(`${dustPath}/facts/use-dust-for-planning.md`, USE_DUST_FACT);
+    const settings = generateSettings(ctx.cwd, fs);
+    await fs.writeFile(`${dustPath}/config/settings.json`, `${JSON.stringify(settings, null, 2)}
+`);
     ctx.stdout("Initialized Dust repository in .dust/");
     ctx.stdout(`Created directories: ${DUST_DIRECTORIES.join(", ")}`);
     ctx.stdout("Created initial fact: .dust/facts/use-dust-for-planning.md");
+    ctx.stdout("Created settings: .dust/config/settings.json");
   }
   const claudeMdPath = `${ctx.cwd}/CLAUDE.md`;
   if (fs.exists(claudeMdPath)) {
@@ -431,16 +450,23 @@ async function init(ctx, fs, _args) {
     await fs.writeFile(agentsMdPath, agentsContent);
     ctx.stdout("Created AGENTS.md with agent instructions");
   }
+  const runner = dustCommand.split(" ")[0];
+  ctx.stdout("");
+  ctx.stdout("Commit the changes if you are happy, then get planning!");
+  ctx.stdout("");
+  ctx.stdout("If this is a new repository, you can start adding ideas or tasks right away:");
+  ctx.stdout(`> ${runner} claude "Idea: friendly UI for non-technical users"`);
+  ctx.stdout(`> ${runner} codex "Task: set up code coverage"`);
+  ctx.stdout("");
+  ctx.stdout("If this is an existing codebase, you might want to backfill goals and facts:");
+  ctx.stdout(`> ${runner} claude "Add goals and facts based on the code in this repository"`);
   return { exitCode: 0 };
 }
 
-// lib/cli/list.ts
+// lib/cli/commands/list.ts
 var VALID_TYPES = ["tasks", "ideas", "goals", "facts"];
-function extractTitle(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : null;
-}
-async function list(ctx, fs, args) {
+async function list(deps) {
+  const { arguments: args, context: ctx, fileSystem: fs } = deps;
   const dustPath = `${ctx.cwd}/.dust`;
   if (!fs.exists(dustPath)) {
     ctx.stderr("Error: .dust directory not found");
@@ -480,11 +506,7 @@ async function list(ctx, fs, args) {
   return { exitCode: 0 };
 }
 
-// lib/cli/next.ts
-function extractTitle2(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : null;
-}
+// lib/cli/commands/next.ts
 function extractBlockedBy(content) {
   const blockedByMatch = content.match(/^## Blocked by\s*\n([\s\S]*?)(?=\n## |\n*$)/m);
   if (!blockedByMatch) {
@@ -503,7 +525,8 @@ function extractBlockedBy(content) {
   }
   return blockers;
 }
-async function next(ctx, fs, _args) {
+async function next(deps) {
+  const { context: ctx, fileSystem: fs } = deps;
   const dustPath = `${ctx.cwd}/.dust`;
   if (!fs.exists(dustPath)) {
     ctx.stderr("Error: .dust directory not found");
@@ -527,9 +550,9 @@ async function next(ctx, fs, _args) {
     const blockers = extractBlockedBy(content);
     const hasIncompleteBlocker = blockers.some((blocker) => existingTasks.has(blocker));
     if (!hasIncompleteBlocker) {
-      const title = extractTitle2(content);
-      const name = file.replace(/\.md$/, "");
-      unblockedTasks.push({ name, title });
+      const title = extractTitle(content);
+      const relativePath = `.dust/tasks/${file}`;
+      unblockedTasks.push({ path: relativePath, title });
     }
   }
   if (unblockedTasks.length === 0) {
@@ -538,9 +561,9 @@ async function next(ctx, fs, _args) {
   ctx.stdout("Next tasks:");
   for (const task of unblockedTasks) {
     if (task.title) {
-      ctx.stdout(`  ${task.name} - ${task.title}`);
+      ctx.stdout(`  ${task.path} - ${task.title}`);
     } else {
-      ctx.stdout(`  ${task.name}`);
+      ctx.stdout(`  ${task.path}`);
     }
   }
   return { exitCode: 0 };
@@ -566,22 +589,22 @@ function isHelpRequest(command) {
 function isValidCommand(command) {
   return COMMANDS.includes(command);
 }
-async function runCommand(command, commandArgs, ctx, fs, glob, settings) {
+async function runCommand(command, deps) {
   switch (command) {
     case "init":
-      return init(ctx, fs, commandArgs);
+      return init(deps);
     case "validate":
-      return validate(ctx, fs, commandArgs, glob);
+      return validate(deps);
     case "list":
-      return list(ctx, fs, commandArgs);
+      return list(deps);
     case "next":
-      return next(ctx, fs, commandArgs);
+      return next(deps);
     case "check":
-      return check(ctx, fs, commandArgs, glob);
+      return check(deps);
     case "agent":
-      return agent(ctx, commandArgs, settings);
+      return agent(deps);
     case "help":
-      ctx.stdout(generateHelpText(settings));
+      deps.context.stdout(generateHelpText(deps.settings));
       return { exitCode: 0 };
   }
 }
@@ -600,7 +623,14 @@ async function main(options) {
     ctx.stderr(`Run '${settings.dustCommand} help' for available commands`);
     return { exitCode: 1 };
   }
-  return runCommand(command, commandArgs, ctx, fs, glob, settings);
+  const deps = {
+    arguments: commandArgs,
+    context: ctx,
+    fileSystem: fs,
+    globScanner: glob,
+    settings
+  };
+  return runCommand(command, deps);
 }
 
 // lib/cli/entry.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "A lightweight planning system for human-AI collaboration",
   "type": "module",
   "bin": {

package/templates/agent-greeting.txt

@@ -1,4 +1,4 @@
-Hello Claude, welcome to dust!
+Hello Agent, welcome to dust!
 
 Your goal today is to make ONE SMALL CHANGE and then commit and push your changes.