@joshski/dust 0.1.1 → 0.1.2

package/dist/dust.js

@@ -2,11 +2,81 @@
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 
+// lib/cli/templates.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var templatesDir = join(__dirname2, "../templates");
+function loadTemplate(name, variables = {}) {
+  const templatePath = join(templatesDir, `${name}.txt`);
+  let content = readFileSync(templatePath, "utf-8");
+  for (const [key, value] of Object.entries(variables)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+  return content;
+}
+
+// lib/cli/agent.ts
+var AGENT_SUBCOMMANDS = [
+  "work",
+  "tasks",
+  "goals",
+  "ideas",
+  "help"
+];
+function generateAgentGreeting(settings) {
+  return loadTemplate("agent-greeting", { bin: settings.binaryPath });
+}
+function generateWorkInstructions(settings) {
+  return loadTemplate("agent-work", { bin: settings.binaryPath });
+}
+function generateTasksInstructions(settings) {
+  return loadTemplate("agent-tasks", { bin: settings.binaryPath });
+}
+function generateGoalsInstructions(settings) {
+  return loadTemplate("agent-goals", { bin: settings.binaryPath });
+}
+function generateIdeasInstructions(settings) {
+  return loadTemplate("agent-ideas", { bin: settings.binaryPath });
+}
+function generateAgentHelp(settings) {
+  return loadTemplate("agent-help", { bin: settings.binaryPath });
+}
+async function agent(ctx, args, settings) {
+  const subcommand = args[0];
+  if (!subcommand) {
+    ctx.stdout(generateAgentGreeting(settings));
+    return { exitCode: 0 };
+  }
+  switch (subcommand) {
+    case "work":
+      ctx.stdout(generateWorkInstructions(settings));
+      return { exitCode: 0 };
+    case "tasks":
+      ctx.stdout(generateTasksInstructions(settings));
+      return { exitCode: 0 };
+    case "goals":
+      ctx.stdout(generateGoalsInstructions(settings));
+      return { exitCode: 0 };
+    case "ideas":
+      ctx.stdout(generateIdeasInstructions(settings));
+      return { exitCode: 0 };
+    case "help":
+      ctx.stdout(generateAgentHelp(settings));
+      return { exitCode: 0 };
+    default:
+      ctx.stderr(`Unknown subcommand: ${subcommand}`);
+      ctx.stderr(`Available: ${AGENT_SUBCOMMANDS.join(", ")}`);
+      return { exitCode: 1 };
+  }
+}
+
 // lib/cli/check.ts
 import { spawn } from "node:child_process";
 
 // lib/cli/validate.ts
-import { dirname, resolve } from "node:path";
+import { dirname as dirname2, resolve } from "node:path";
 var REQUIRED_HEADINGS = ["## Goals", "## Blocked by", "## Definition of done"];
 var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
 function validateFilename(filePath) {
@@ -36,7 +106,7 @@ function validateLinks(filePath, content, fs) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname(filePath);
+  const fileDir = dirname2(filePath);
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
     const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
@@ -59,6 +129,69 @@ function validateLinks(filePath, content, fs) {
   }
   return violations;
 }
+var SEMANTIC_RULES = [
+  {
+    section: "## Goals",
+    requiredPath: "/.dust/goals/",
+    description: "goal"
+  },
+  {
+    section: "## Blocked by",
+    requiredPath: "/.dust/tasks/",
+    description: "task"
+  }
+];
+function validateSemanticLinks(filePath, content) {
+  const violations = [];
+  const lines = content.split(`
+`);
+  const fileDir = dirname2(filePath);
+  let currentSection = null;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      currentSection = line;
+      continue;
+    }
+    const rule = SEMANTIC_RULES.find((r) => r.section === currentSection);
+    if (!rule)
+      continue;
+    const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let match = linkPattern.exec(line);
+    while (match) {
+      const linkTarget = match[2];
+      if (linkTarget.startsWith("#")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${rule.section}" must point to a ${rule.description} file, not an anchor: "${linkTarget}"`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${rule.section}" must point to a ${rule.description} file, not an external URL: "${linkTarget}"`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      const targetPath = linkTarget.split("#")[0];
+      const resolvedPath = resolve(fileDir, targetPath);
+      if (!resolvedPath.includes(rule.requiredPath)) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${rule.section}" must point to a ${rule.description} file: "${linkTarget}"`,
+          line: i + 1
+        });
+      }
+      match = linkPattern.exec(line);
+    }
+  }
+  return violations;
+}
 async function validate(ctx, fs, _args, glob) {
   const dustPath = `${ctx.cwd}/.dust`;
   if (!fs.exists(dustPath)) {
@@ -88,6 +221,7 @@ async function validate(ctx, fs, _args, glob) {
         violations.push(filenameViolation);
       }
       violations.push(...validateTaskHeadings(filePath, content));
+      violations.push(...validateSemanticLinks(filePath, content));
     }
   }
   if (violations.length === 0) {
@@ -308,12 +442,12 @@ async function prompt(ctx, fs, args) {
 }
 
 // lib/cli/settings.ts
-import { join } from "node:path";
+import { join as join2 } from "node:path";
 var DEFAULT_SETTINGS = {
   binaryPath: "dust"
 };
 async function loadSettings(cwd, fs) {
-  const settingsPath = join(cwd, ".dust", "config", "settings.json");
+  const settingsPath = join2(cwd, ".dust", "config", "settings.json");
   if (!fs.exists(settingsPath)) {
     return DEFAULT_SETTINGS;
   }
@@ -337,92 +471,11 @@ var COMMANDS = [
   "list",
   "next",
   "check",
+  "agent",
   "help"
 ];
 function generateHelpText(settings) {
-  const bin = settings.binaryPath;
-  return `dust - A lightweight planning system for human-AI collaboration
-
-Usage: ${bin} <command> [options]
-
-Commands:
-  init              Initialize a new Dust repository
-  prompt <name>     Output a prompt by name (e.g., ${bin} prompt work)
-  validate          Run validation checks on .dust/ files
-  list [type]       List items (tasks, ideas, goals, facts)
-  next              Show tasks ready to work on (not blocked)
-  check             Run project-defined quality gate hook
-  help              Show this help message
-
-Examples:
-  ${bin} init
-  ${bin} prompt work
-  ${bin} validate
-  ${bin} list tasks
-  ${bin} list
-  ${bin} next
-  ${bin} check
-
----
-
-## Agent Guide
-
-This section provides comprehensive guidance for AI agents working with dust.
-
-### Directory Structure
-
-The \`.dust/\` directory contains all planning artifacts:
-
-- **\`.dust/goals/\`** - Mission statements and guiding principles
-- **\`.dust/ideas/\`** - Future feature notes and proposals (intentionally vague)
-- **\`.dust/tasks/\`** - Detailed work plans with dependencies and definitions of done
-- **\`.dust/facts/\`** - Documentation of current system state and architecture
-- **\`.dust/hooks/\`** - Executable scripts for quality gates (e.g., \`check\` hook)
-
-All files are markdown with slug-style names (lowercase, hyphens, no spaces).
-
-### Working on Tasks
-
-**Run \`${bin} check\` before starting work** to verify the project is in a good state before making changes.
-
-Run \`${bin} next\` to find tasks ready to work on. Each task file contains:
-
-- \`## Goals\` - Links to goals this task supports
-- \`## Blocked by\` - Tasks that must complete first (empty or "(none)" means ready)
-- \`## Definition of done\` - Criteria for completion
-
-A task is **unblocked** when its "Blocked by" section is empty, says "(none)", or all referenced task files have been deleted.
-
-### Completing a Task
-
-**Run \`${bin} check\` before committing** to ensure all quality gates pass.
-
-When finishing a task, create a single atomic commit that includes:
-
-1. All implementation changes
-2. Deletion of the completed task file
-3. Updates to any facts that changed
-4. Deletion of any ideas that were fully realized
-5. Updates to any tasks that referenced this one in their "Blocked by" sections
-
-### Common Workflows
-
-- **"Work on the next task"** - Run \`${bin} next\`, pick a task, implement it
-- **"Work on task X"** - Implement \`.dust/tasks/X.md\` directly
-- **"Convert idea Y to tasks"** - Break down \`.dust/ideas/Y.md\` into tasks
-- **"Validate facts"** - Check \`.dust/facts/\` for accuracy against the codebase
-
-### Configuring Agent Files
-
-Projects using dust should add a minimal pointer to their agent configuration files (CLAUDE.md, AGENTS.md, etc.):
-
-\`\`\`markdown
-This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
-Always run \`dust help\` when you start working in this repository.
-\`\`\`
-
-This approach keeps agent instructions minimal, ensures agents get current documentation, and reduces maintenance burden.
-`;
+  return loadTemplate("help", { bin: settings.binaryPath });
 }
 var HELP_TEXT = generateHelpText({ binaryPath: "dust" });
 function isHelpRequest(command) {
@@ -445,6 +498,8 @@ async function runCommand(command, commandArgs, ctx, fs, glob, settings) {
       return next(ctx, fs, commandArgs);
     case "check":
       return check(ctx, fs, commandArgs, defaultProcessRunner, glob);
+    case "agent":
+      return agent(ctx, commandArgs, settings);
     case "help":
       ctx.stdout(generateHelpText(settings));
       return { exitCode: 0 };

package/package.json

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