@joshski/dust 0.1.61 → 0.1.63

package/dist/artifacts/facts.d.ts

@@ -1,4 +1,4 @@
-import type { ReadableFileSystem } from '../cli/types';
+import type { ReadableFileSystem } from '../filesystem/types';
 export interface Fact {
     slug: string;
     title: string;

package/dist/artifacts/ideas.d.ts

@@ -1,4 +1,4 @@
-import type { ReadableFileSystem } from '../cli/types';
+import type { ReadableFileSystem } from '../filesystem/types';
 export interface IdeaOption {
     name: string;
     description: string;

package/dist/artifacts/index.d.ts

@@ -1,11 +1,12 @@
-import type { FileSystem, ReadableFileSystem } from '../cli/types';
+import type { FileSystem, ReadableFileSystem } from '../filesystem/types';
 import { type Fact } from './facts';
 import { type Idea, type IdeaOpenQuestion, type IdeaOption, parseOpenQuestions } from './ideas';
 import { type Principle } from './principles';
 import { type Task } from './tasks';
-import { type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, type OpenQuestionResponse, type ParsedCaptureIdeaTask, type WorkflowTaskMatch } from './workflow-tasks';
+import { CAPTURE_IDEA_PREFIX, type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, findAllCaptureIdeaTasks, type IdeaInProgress, type OpenQuestionResponse, type ParsedCaptureIdeaTask, type WorkflowTaskMatch } from './workflow-tasks';
 export type { CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, Fact, Idea, IdeaOpenQuestion, IdeaOption, OpenQuestionResponse, ParsedCaptureIdeaTask, Principle, Task, WorkflowTaskMatch, };
-export { parseOpenQuestions };
+export { CAPTURE_IDEA_PREFIX, findAllCaptureIdeaTasks, parseOpenQuestions };
+export type { IdeaInProgress };
 export interface ArtifactsRepository {
     parseIdea(options: {
         slug: string;

package/dist/artifacts/principles.d.ts

@@ -1,4 +1,4 @@
-import type { ReadableFileSystem } from '../cli/types';
+import type { ReadableFileSystem } from '../filesystem/types';
 export interface Principle {
     slug: string;
     title: string;

package/dist/artifacts/tasks.d.ts

@@ -1,4 +1,4 @@
-import type { ReadableFileSystem } from '../cli/types';
+import type { ReadableFileSystem } from '../filesystem/types';
 export interface Task {
     slug: string;
     title: string;

package/dist/artifacts/workflow-tasks.d.ts

@@ -1,4 +1,4 @@
-import type { FileSystem, ReadableFileSystem } from '../cli/types';
+import type { FileSystem, ReadableFileSystem } from '../filesystem/types';
 export declare const IDEA_TRANSITION_PREFIXES: string[];
 export declare const CAPTURE_IDEA_PREFIX = "Add Idea: ";
 export declare const BUILD_IDEA_PREFIX = "Build Idea: ";

package/dist/artifacts.js

@@ -273,6 +273,32 @@ async function parseTask(fileSystem, dustPath, slug) {
 // lib/artifacts/workflow-tasks.ts
 var CAPTURE_IDEA_PREFIX = "Add Idea: ";
 var BUILD_IDEA_PREFIX = "Build Idea: ";
+async function findAllCaptureIdeaTasks(fileSystem, dustPath) {
+  const tasksPath = `${dustPath}/tasks`;
+  if (!fileSystem.exists(tasksPath))
+    return [];
+  const files = await fileSystem.readdir(tasksPath);
+  const results = [];
+  for (const file of files.filter((f) => f.endsWith(".md")).sort()) {
+    const content = await fileSystem.readFile(`${tasksPath}/${file}`);
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    if (!titleMatch)
+      continue;
+    const title = titleMatch[1].trim();
+    if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
+      results.push({
+        taskSlug: file.replace(/\.md$/, ""),
+        ideaTitle: title.slice(CAPTURE_IDEA_PREFIX.length)
+      });
+    } else if (title.startsWith(BUILD_IDEA_PREFIX)) {
+      results.push({
+        taskSlug: file.replace(/\.md$/, ""),
+        ideaTitle: title.slice(BUILD_IDEA_PREFIX.length)
+      });
+    }
+  }
+  return results;
+}
 function titleToFilename(title) {
   return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
 }
@@ -594,6 +620,8 @@ function buildReadOnlyArtifactsRepository(fileSystem, dustPath) {
 }
 export {
   parseOpenQuestions,
+  findAllCaptureIdeaTasks,
   buildReadOnlyArtifactsRepository,
-  buildArtifactsRepository
+  buildArtifactsRepository,
+  CAPTURE_IDEA_PREFIX
 };

package/dist/audits/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Audits repository - programmatic access to audit templates.
+ *
+ * Audits are canned tasks that help maintain project health.
+ * Sources:
+ * 1. User-configured audits in .dust/config/audits/*.md (takes precedence)
+ * 2. Stock audits from lib/audits/stock-audits.ts
+ */
+import type { FileSystem } from '../filesystem/types';
+export { loadStockAudits } from './stock-audits';
+export interface Audit {
+    name: string;
+    title: string;
+    description: string;
+    template: string;
+    source: 'stock' | string;
+}
+export interface CreateAuditTaskResult {
+    filePath: string;
+    relativePath: string;
+}
+export interface AuditsRepository {
+    listAudits(): Promise<Audit[]>;
+    parseAudit(options: {
+        name: string;
+    }): Promise<Audit>;
+    createAuditTask(options: {
+        name: string;
+    }): Promise<CreateAuditTaskResult>;
+}
+/**
+ * Transforms audit template content for the task file.
+ * Changes the title from "# Original Title" to "# Audit: Original Title"
+ */
+export declare function transformAuditContent(content: string): string;
+export declare function buildAuditsRepository(fileSystem: FileSystem, dustPath: string): AuditsRepository;

package/dist/audits/stock-audits.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Stock audit templates as type-safe functions.
+ *
+ * Users can override any of these by placing a file with the same name
+ * in .dust/config/audits/.
+ */
+export interface StockAudit {
+    name: string;
+    description: string;
+    template: string;
+}
+export declare function loadStockAudits(): StockAudit[];

package/dist/audits.js

@@ -0,0 +1,459 @@
+// lib/audits/index.ts
+import { basename } from "node:path";
+
+// lib/markdown/markdown-utilities.ts
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+function extractOpeningSentence(content) {
+  const lines = content.split(`
+`);
+  let h1Index = -1;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].match(/^#\s+.+$/)) {
+      h1Index = i;
+      break;
+    }
+  }
+  if (h1Index === -1) {
+    return null;
+  }
+  let paragraphStart = -1;
+  for (let i = h1Index + 1;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line !== "") {
+      paragraphStart = i;
+      break;
+    }
+  }
+  if (paragraphStart === -1) {
+    return null;
+  }
+  const firstLine = lines[paragraphStart];
+  const trimmedFirstLine = firstLine.trim();
+  if (trimmedFirstLine.startsWith("#") || trimmedFirstLine.startsWith("-") || trimmedFirstLine.startsWith("*") || trimmedFirstLine.startsWith("+") || trimmedFirstLine.match(/^\d+\./) || trimmedFirstLine.startsWith("```") || trimmedFirstLine.startsWith(">")) {
+    return null;
+  }
+  let paragraph = "";
+  for (let i = paragraphStart;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "")
+      break;
+    if (line.startsWith("#") || line.startsWith("```") || line.startsWith(">")) {
+      break;
+    }
+    paragraph += (paragraph ? " " : "") + line;
+  }
+  const sentenceMatch = paragraph.match(/^(.+?[.?!])(?:\s|$)/);
+  if (!sentenceMatch) {
+    return null;
+  }
+  return sentenceMatch[1];
+}
+
+// lib/cli/dedent.ts
+function dedent(strings, ...values) {
+  const result = strings.reduce((acc, part, index) => acc + part + (values[index] ?? ""), "");
+  const lines = result.split(`
+`);
+  const indent = lines.filter((line) => line.trim()).reduce((min, line) => Math.min(min, line.match(/^\s*/)[0].length), Number.POSITIVE_INFINITY);
+  return lines.map((line) => line.slice(indent)).join(`
+`).trim();
+}
+
+// lib/audits/stock-audits.ts
+function agentDeveloperExperience() {
+  return dedent`
+    # Agent Developer Experience
+
+    Review the codebase to ensure agents have everything they need to operate effectively. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Context window efficiency** - Are files small and well-organized?
+    2. **Test coverage** - Can agents verify correctness through tests?
+    3. **Feedback loop speed** - How fast are checks and tests?
+    4. **Debugging tools** - Can agents diagnose issues without trial and error?
+    5. **Structured logging** - Is system behavior observable through logs?
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed file sizes and organization for context window fit
+    - [ ] Verified test coverage is sufficient for agent verification
+    - [ ] Measured feedback loop speed (time from change to check result)
+    - [ ] Confirmed debugging tools and structured logging are in place
+    - [ ] Proposed ideas for any improvements identified
+  `;
+}
+function deadCode() {
+  return dedent`
+    # Dead Code
+
+    Find and remove unused code to improve maintainability and reduce bundle size. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Unused exports** - Functions, classes, constants that are never imported
+    2. **Unreachable code** - Code after return statements, impossible conditions
+    3. **Orphaned files** - Files that are not imported anywhere
+    4. **Unused dependencies** - Packages in package.json not used in code
+    5. **Commented-out code** - Old code left in comments
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Ran static analysis tools to find unused exports
+    - [ ] Identified files with no incoming imports
+    - [ ] Listed unused dependencies
+    - [ ] Reviewed commented-out code blocks
+    - [ ] Created list of code safe to remove
+    - [ ] Verified removal won't break dynamic imports or reflection
+    - [ ] Proposed ideas for any dead code worth removing
+  `;
+}
+function factsVerification() {
+  return dedent`
+    # Facts Verification
+
+    Review \`.dust/facts/\` to ensure documented facts match current reality. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Accuracy** - Do documented facts reflect the current codebase?
+    2. **Completeness** - Are important implementation details documented?
+    3. **Staleness** - Have facts become outdated due to recent changes?
+    4. **Relevance** - Are all facts still useful for understanding the project?
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Read each fact file in \`.dust/facts/\`
+    - [ ] Verified each fact against current codebase
+    - [ ] Identified outdated or inaccurate facts
+    - [ ] Listed missing facts that would help agents
+    - [ ] Updated or removed stale facts
+    - [ ] Proposed ideas for any facts improvements needed
+  `;
+}
+function ideasFromCommits() {
+  return dedent`
+    # Ideas from Commits
+
+    Review recent commit history to identify follow-up improvement ideas. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues or opportunities you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Technical debt** - Did recent work introduce shortcuts?
+    2. **Incomplete work** - Are there TODO comments or partial implementations?
+    3. **Pattern opportunities** - Can recent changes be generalized?
+    4. **Test gaps** - Do recent changes have adequate test coverage?
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed commits from the last 20 commits
+    - [ ] Identified patterns or shortcuts worth addressing
+    - [ ] Listed TODO comments added in recent commits
+    - [ ] Noted areas where changes could be generalized
+    - [ ] Proposed follow-up ideas for any issues identified
+  `;
+}
+function ideasFromPrinciples() {
+  return dedent`
+    # Ideas from Principles
+
+    Review \`.dust/principles/\` to generate new improvement ideas. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues or opportunities you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Unmet principles** - Which principles lack supporting work?
+    2. **Gap analysis** - Where does the codebase fall short of principles?
+    3. **New opportunities** - What work would better achieve each principle?
+    4. **Principle alignment** - Are current tasks aligned with stated principles?
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Read each principle file in \`.dust/principles/\`
+    - [ ] Analyzed codebase for alignment with each principle
+    - [ ] Listed gaps between current state and principle intent
+    - [ ] Proposed new ideas for unmet or underserved principles
+  `;
+}
+function performanceReview() {
+  return dedent`
+    # Performance Review
+
+    Review the application for performance issues and optimization opportunities. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Startup time** - How fast does the application start?
+    2. **Command latency** - How responsive are CLI commands?
+    3. **Memory usage** - Is memory being used efficiently?
+    4. **Build performance** - How fast is the build process?
+    5. **Test speed** - Are tests running efficiently?
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Measured startup time for common commands
+    - [ ] Profiled memory usage during typical operations
+    - [ ] Identified slow commands or operations
+    - [ ] Listed optimization opportunities by impact
+    - [ ] Proposed ideas for any performance improvements identified
+  `;
+}
+function securityReview() {
+  return dedent`
+    # Security Review
+
+    Review the codebase for common security vulnerabilities and misconfigurations. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Hardcoded secrets** - API keys, passwords, tokens in source code
+    2. **Injection vulnerabilities** - SQL injection, command injection, XSS
+    3. **Authentication issues** - Weak password handling, missing auth checks
+    4. **Sensitive data exposure** - Logging sensitive data, insecure storage
+    5. **Dependency vulnerabilities** - Known CVEs in dependencies
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Searched for hardcoded secrets (API keys, passwords, tokens)
+    - [ ] Reviewed input validation and sanitization
+    - [ ] Checked authentication and authorization logic
+    - [ ] Verified sensitive data is not logged or exposed
+    - [ ] Ran dependency audit for known vulnerabilities
+    - [ ] Documented any findings with severity ratings
+    - [ ] Proposed ideas for any security issues found
+  `;
+}
+function staleIdeas() {
+  return dedent`
+    # Stale Ideas
+
+    Review \`.dust/ideas/\` to identify ideas that have become stale or irrelevant. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Age** - Ideas unchanged for many commits may need attention
+    2. **Relevance** - Has the project evolved past the idea?
+    3. **Actionability** - Can the idea be converted to a task?
+    4. **Duplication** - Are there overlapping or redundant ideas?
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Listed all ideas with their last modification date
+    - [ ] Identified ideas unchanged for 50+ commits
+    - [ ] Reviewed each stale idea for current relevance
+    - [ ] Promoted actionable ideas to tasks
+    - [ ] Deleted ideas that are no longer relevant
+  `;
+}
+function testCoverage() {
+  return dedent`
+    # Test Coverage
+
+    Identify untested code paths and areas that need additional test coverage. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Core business logic** - Functions that handle critical operations
+    2. **Edge cases** - Boundary conditions, error handling paths
+    3. **Integration points** - API endpoints, database operations
+    4. **User-facing features** - UI components, form validation
+    5. **Recent changes** - Code modified in the last few commits
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Identified modules with low or no test coverage
+    - [ ] Listed critical paths that lack tests
+    - [ ] Prioritized areas by risk and importance
+    - [ ] Proposed ideas for any test coverage gaps identified
+  `;
+}
+var stockAuditFunctions = {
+  "agent-developer-experience": agentDeveloperExperience,
+  "dead-code": deadCode,
+  "facts-verification": factsVerification,
+  "ideas-from-commits": ideasFromCommits,
+  "ideas-from-principles": ideasFromPrinciples,
+  "performance-review": performanceReview,
+  "security-review": securityReview,
+  "stale-ideas": staleIdeas,
+  "test-coverage": testCoverage
+};
+function loadStockAudits() {
+  return Object.entries(stockAuditFunctions).sort(([a], [b]) => a.localeCompare(b)).map(([name, render]) => {
+    const template = render();
+    const description = extractOpeningSentence(template);
+    return { name, description, template };
+  });
+}
+
+// lib/audits/index.ts
+function transformAuditContent(content) {
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  if (!titleMatch) {
+    return content;
+  }
+  const originalTitle = titleMatch[1];
+  return content.replace(/^#\s+.+$/m, `# Audit: ${originalTitle}`);
+}
+function buildAuditsRepository(fileSystem, dustPath) {
+  const userAuditsPath = `${dustPath}/config/audits`;
+  const tasksPath = `${dustPath}/tasks`;
+  async function loadAllAudits() {
+    const audits = new Map;
+    for (const stockAudit of loadStockAudits()) {
+      audits.set(stockAudit.name, {
+        name: stockAudit.name,
+        title: extractTitle(stockAudit.template),
+        description: stockAudit.description,
+        template: stockAudit.template,
+        source: "stock"
+      });
+    }
+    if (fileSystem.exists(userAuditsPath)) {
+      const files = await fileSystem.readdir(userAuditsPath);
+      const mdFiles = files.filter((f) => f.endsWith(".md")).sort();
+      for (const file of mdFiles) {
+        const name = basename(file, ".md");
+        const filePath = `${userAuditsPath}/${file}`;
+        const content = await fileSystem.readFile(filePath);
+        const title = extractTitle(content) || name;
+        const description = extractOpeningSentence(content) || "";
+        const relativePath = `.dust/config/audits/${file}`;
+        audits.set(name, {
+          name,
+          title,
+          description,
+          template: content,
+          source: relativePath
+        });
+      }
+    }
+    return audits;
+  }
+  return {
+    async listAudits() {
+      const auditsMap = await loadAllAudits();
+      return Array.from(auditsMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+    },
+    async parseAudit(options) {
+      const auditsMap = await loadAllAudits();
+      const audit = auditsMap.get(options.name);
+      if (!audit) {
+        throw new Error(`Audit not found: "${options.name}"`);
+      }
+      return audit;
+    },
+    async createAuditTask(options) {
+      const audit = await this.parseAudit(options);
+      const taskFilePath = `${tasksPath}/audit-${options.name}.md`;
+      const relativeTaskPath = `.dust/tasks/audit-${options.name}.md`;
+      if (fileSystem.exists(taskFilePath)) {
+        throw new Error(`Audit task already exists at ${relativeTaskPath}`);
+      }
+      const transformedContent = transformAuditContent(audit.template);
+      await fileSystem.mkdir(tasksPath, { recursive: true });
+      await fileSystem.writeFile(taskFilePath, transformedContent);
+      return {
+        filePath: taskFilePath,
+        relativePath: relativeTaskPath
+      };
+    }
+  };
+}
+export {
+  transformAuditContent,
+  loadStockAudits,
+  buildAuditsRepository
+};

package/dist/cli/dedent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Dedent tagged template literal helper
+ *
+ * Strips common leading whitespace from multi-line template literals,
+ * making it possible to write properly indented code while producing
+ * clean output.
+ */
+export declare function dedent(strings: TemplateStringsArray, ...values: unknown[]): string;

package/dist/cli/types.d.ts

@@ -1,6 +1,8 @@
 /**
  * Common types for CLI commands
  */
+import type { FileSystem, GlobScanner } from '../filesystem/types';
+export type { FileSystem, GlobScanner, ReadableFileSystem, WriteOptions, } from '../filesystem/types';
 export interface CommandContext {
     cwd: string;
     stdout: (message: string) => void;
@@ -10,27 +12,6 @@ export interface CommandContext {
 export interface CommandResult {
     exitCode: number;
 }
-export interface WriteOptions {
-    flag?: 'w' | 'wx';
-}
-export interface ReadableFileSystem {
-    exists: (path: string) => boolean;
-    readFile: (path: string) => Promise<string>;
-    readdir: (path: string) => Promise<string[]>;
-    isDirectory: (path: string) => boolean;
-}
-export interface FileSystem extends ReadableFileSystem {
-    writeFile: (path: string, content: string, options?: WriteOptions) => Promise<void>;
-    mkdir: (path: string, options?: {
-        recursive?: boolean;
-    }) => Promise<void>;
-    chmod: (path: string, mode: number) => Promise<void>;
-    getFileCreationTime: (path: string) => number;
-    rename: (oldPath: string, newPath: string) => Promise<void>;
-}
-export interface GlobScanner {
-    scan: (dir: string) => AsyncIterable<string>;
-}
 export interface CheckConfig {
     name: string;
     command: string;

package/dist/dust.js

@@ -274,6 +274,9 @@ async function loadSettings(cwd, fileSystem) {
   }
 }
 
+// lib/version.ts
+var DUST_VERSION = "0.1.63";
+
 // lib/cli/dedent.ts
 function dedent(strings, ...values) {
   const result = strings.reduce((acc, part, index) => acc + part + (values[index] ?? ""), "");
@@ -902,6 +905,16 @@ function loadStockAudits() {
   });
 }
 
+// lib/audits/index.ts
+function transformAuditContent(content) {
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  if (!titleMatch) {
+    return content;
+  }
+  const originalTitle = titleMatch[1];
+  return content.replace(/^#\s+.+$/m, `# Audit: ${originalTitle}`);
+}
+
 // lib/cli/colors.ts
 var ANSI_COLORS = {
   reset: "\x1B[0m",
@@ -936,14 +949,6 @@ function getColors() {
 }
 
 // lib/cli/commands/audit.ts
-function transformAuditContent(content) {
-  const titleMatch = content.match(/^#\s+(.+)$/m);
-  if (!titleMatch) {
-    return content;
-  }
-  const originalTitle = titleMatch[1];
-  return content.replace(/^#\s+.+$/m, `# Audit: ${originalTitle}`);
-}
 async function addAudit(auditName, dependencies) {
   const { context, fileSystem, settings } = dependencies;
   const dustPath = `${context.cwd}/.dust`;
@@ -1034,7 +1039,6 @@ import { accessSync, statSync } from "node:fs";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { createServer as httpCreateServer } from "node:http";
 import { homedir } from "node:os";
-import { join as join9 } from "node:path";
 
 // lib/bucket/auth.ts
 import { join as join4 } from "node:path";
@@ -1202,8 +1206,14 @@ function getLogLines(buffer) {
   return buffer.lines;
 }
 
+// lib/bucket/paths.ts
+import { join as join5 } from "node:path";
+function getReposDir(env, homeDir) {
+  return env.DUST_REPOS_DIR || join5(homeDir, ".dust", "repos");
+}
+
 // lib/bucket/repository.ts
-import { dirname as dirname3, join as join8 } from "node:path";
+import { dirname as dirname2 } from "node:path";
 
 // lib/claude/spawn-claude-code.ts
 import { spawn as nodeSpawn } from "node:child_process";
@@ -1622,7 +1632,7 @@ async function run(prompt, options = {}, dependencies = defaultRunnerDependencie
 }
 
 // lib/logging/index.ts
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 
 // lib/logging/match.ts
 function parsePatterns(debug) {
@@ -1706,8 +1716,8 @@ function createLoggingService() {
   return {
     enableFileLogs(scope, sinkForTesting) {
       const existing = process.env[DUST_LOG_FILE];
-      const logDir = process.env.DUST_LOG_DIR ?? join5(process.cwd(), "log");
-      const path = existing ?? join5(logDir, `${scope}.log`);
+      const logDir = process.env.DUST_LOG_DIR ?? join6(process.cwd(), "log");
+      const path = existing ?? join6(logDir, `${scope}.log`);
       if (!existing) {
         process.env[DUST_LOG_FILE] = path;
       }
@@ -1747,10 +1757,10 @@ var createLogger = defaultService.createLogger.bind(defaultService);
 var isEnabled = defaultService.isEnabled.bind(defaultService);
 
 // lib/bucket/repository-git.ts
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 function getRepoPath(repoName, reposDir) {
   const safeName = repoName.replace(/[^a-zA-Z0-9-_/]/g, "-");
-  return join6(reposDir, safeName);
+  return join7(reposDir, safeName);
 }
 async function cloneRepository(repository, targetPath, spawn, context) {
   return new Promise((resolve) => {
@@ -1818,10 +1828,7 @@ function formatAgentEvent(event) {
 
 // lib/cli/commands/loop.ts
 import { spawn as nodeSpawn2 } from "node:child_process";
-import { readFileSync } from "node:fs";
 import os from "node:os";
-import { dirname as dirname2, join as join7 } from "node:path";
-import { fileURLToPath } from "node:url";
 
 // lib/artifacts/workflow-tasks.ts
 var IDEA_TRANSITION_PREFIXES = [
@@ -1970,26 +1977,12 @@ async function next(dependencies) {
 }
 
 // lib/cli/commands/loop.ts
-var __dirname2 = dirname2(fileURLToPath(import.meta.url));
-function getDustVersion() {
-  const candidates = [
-    join7(__dirname2, "../../../package.json"),
-    join7(__dirname2, "../package.json")
-  ];
-  for (const candidate of candidates) {
-    try {
-      const packageJson = JSON.parse(readFileSync(candidate, "utf-8"));
-      return packageJson.version ?? "unknown";
-    } catch {}
-  }
-  return "unknown";
-}
 function getEnvironmentContext(cwd) {
   return {
     machineName: os.hostname(),
     cwd,
     platform: `${os.platform()} ${os.release()}`,
-    dustVersion: getDustVersion(),
+    dustVersion: DUST_VERSION,
     runtimeVersion: process.version
   };
 }
@@ -2098,7 +2091,7 @@ async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAg
   const { context } = dependencies;
   const { spawn, run: run2 } = loopDependencies;
   const agentName = loopDependencies.agentType === "codex" ? "Codex" : "Claude";
-  const { onRawEvent, hooksInstalled = false, signal } = options;
+  const { onRawEvent, hooksInstalled = false, signal, logger = log } = options;
   log("syncing with remote");
   onLoopEvent({ type: "loop.syncing" });
   const pullResult = await gitPull(context.cwd, spawn);
@@ -2199,7 +2192,7 @@ ${instructions}`;
     return "ran_claude";
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
-    log(`${agentName} error on task ${task.title ?? task.path}: ${errorMessage}`);
+    logger(`${agentName} error on task ${task.title ?? task.path}: ${errorMessage}`);
     context.stderr(`${agentName} exited with error: ${errorMessage}`);
     onAgentEvent?.({
       type: "agent-session-ended",
@@ -2475,7 +2468,7 @@ async function addRepository(repository, manager, repoDeps, context) {
   }
   log3(`adding repository ${repository.name}`);
   const repoPath = getRepoPath(repository.name, repoDeps.getReposDir());
-  await repoDeps.fileSystem.mkdir(dirname3(repoPath), { recursive: true });
+  await repoDeps.fileSystem.mkdir(dirname2(repoPath), { recursive: true });
   if (repoDeps.fileSystem.exists(repoPath)) {
     await removeRepository(repoPath, repoDeps.spawn, context);
   }
@@ -3056,11 +3049,11 @@ function defaultOpenBrowser(url) {
   const cmd = process.platform === "darwin" ? "open" : "xdg-open";
   nodeSpawn3(cmd, [url], { stdio: "ignore", detached: true }).unref();
 }
-function createDefaultBucketDependencies() {
-  const authFileSystem = {
+function createAuthFileSystem(dependencies) {
+  return {
     exists: (path) => {
       try {
-        accessSync(path);
+        dependencies.accessSync(path);
         return true;
       } catch {
         return false;
@@ -3068,19 +3061,31 @@ function createDefaultBucketDependencies() {
     },
     isDirectory: (path) => {
       try {
-        return statSync(path).isDirectory();
+        return dependencies.statSync(path).isDirectory();
       } catch {
         return false;
       }
     },
-    getFileCreationTime: (path) => statSync(path).birthtimeMs,
-    readFile: (path) => readFile(path, "utf8"),
-    writeFile: (path, content) => writeFile(path, content, "utf8"),
-    mkdir: (path, options) => mkdir(path, options).then(() => {}),
-    readdir: (path) => readdir(path),
-    chmod: (path, mode) => chmod(path, mode),
-    rename: (oldPath, newPath) => import("node:fs/promises").then((mod) => mod.rename(oldPath, newPath))
+    getFileCreationTime: (path) => dependencies.statSync(path).birthtimeMs,
+    readFile: (path) => dependencies.readFile(path, "utf8"),
+    writeFile: (path, content) => dependencies.writeFile(path, content, "utf8"),
+    mkdir: (path, options) => dependencies.mkdir(path, options).then(() => {}),
+    readdir: (path) => dependencies.readdir(path),
+    chmod: (path, mode) => dependencies.chmod(path, mode),
+    rename: (oldPath, newPath) => dependencies.rename(oldPath, newPath)
   };
+}
+function createDefaultBucketDependencies() {
+  const authFileSystem = createAuthFileSystem({
+    accessSync,
+    statSync,
+    readFile,
+    writeFile,
+    mkdir,
+    readdir,
+    chmod,
+    rename: (oldPath, newPath) => import("node:fs/promises").then((mod) => mod.rename(oldPath, newPath))
+  });
   return {
     spawn: nodeSpawn3,
     createWebSocket: defaultCreateWebSocket,
@@ -3091,7 +3096,7 @@ function createDefaultBucketDependencies() {
     writeStdout: defaultWriteStdout,
     isTTY: process.stdout.isTTY ?? false,
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    getReposDir: () => process.env.DUST_REPOS_DIR || join9(homedir(), ".dust", "repos"),
+    getReposDir: () => getReposDir(process.env, homedir()),
     auth: {
       createServer: defaultCreateServer,
       openBrowser: defaultOpenBrowser,
@@ -3517,7 +3522,7 @@ function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell, time
 }
 
 // lib/cli/commands/lint-markdown.ts
-import { join as join10 } from "node:path";
+import { join as join8 } from "node:path";
 
 // lib/lint/validators/content-validator.ts
 var REQUIRED_HEADINGS = [
@@ -3807,7 +3812,7 @@ function validateIdeaTransitionTitle(filePath, content, ideasPath, fileSystem) {
 }
 
 // lib/lint/validators/link-validator.ts
-import { dirname as dirname4, resolve } from "node:path";
+import { dirname as dirname3, resolve } from "node:path";
 var SEMANTIC_RULES = [
   {
     section: "## Principles",
@@ -3824,7 +3829,7 @@ function validateLinks(filePath, content, fileSystem) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname4(filePath);
+  const fileDir = dirname3(filePath);
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
     const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
@@ -3851,7 +3856,7 @@ function validateSemanticLinks(filePath, content) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname4(filePath);
+  const fileDir = dirname3(filePath);
   let currentSection = null;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
@@ -3902,7 +3907,7 @@ function validatePrincipleHierarchyLinks(filePath, content) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname4(filePath);
+  const fileDir = dirname3(filePath);
   let currentSection = null;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
@@ -3951,7 +3956,7 @@ function validatePrincipleHierarchyLinks(filePath, content) {
 }
 
 // lib/lint/validators/principle-hierarchy.ts
-import { dirname as dirname5, resolve as resolve2 } from "node:path";
+import { dirname as dirname4, resolve as resolve2 } from "node:path";
 var REQUIRED_PRINCIPLE_HEADINGS = ["## Parent Principle", "## Sub-Principles"];
 function validatePrincipleHierarchySections(filePath, content) {
   const violations = [];
@@ -3968,7 +3973,7 @@ function validatePrincipleHierarchySections(filePath, content) {
 function extractPrincipleRelationships(filePath, content) {
   const lines = content.split(`
 `);
-  const fileDir = dirname5(filePath);
+  const fileDir = dirname4(filePath);
   const parentPrinciples = [];
   const subPrinciples = [];
   let currentSection = null;
@@ -4089,7 +4094,7 @@ async function lintMarkdown(dependencies) {
   const violations = [];
   context.stdout("Validating directory structure...");
   violations.push(...await validateDirectoryStructure(dustPath, fileSystem, dependencies.settings.extraDirectories));
-  const settingsPath = join10(dustPath, "config", "settings.json");
+  const settingsPath = join8(dustPath, "config", "settings.json");
   if (fileSystem.exists(settingsPath)) {
     context.stdout("Validating settings.json...");
     try {
@@ -4419,7 +4424,7 @@ async function check(dependencies, shellRunner = defaultShellRunner) {
 function generateHelpText(settings) {
   const bin = settings.dustCommand;
   return dedent`
-    💨 dust - Flow state for AI coding agents.
+    ✨ dust - Flow state for AI coding agents.
 
     Usage: ${bin} <command> [options]
 
@@ -5243,6 +5248,9 @@ var COMMANDS = Object.keys(commandRegistry).filter((cmd) => !cmd.includes(" "));
 function isHelpRequest(command) {
   return !command || command === "help" || command === "--help" || command === "-h";
 }
+function isVersionRequest(command) {
+  return command === "--version" || command === "-v";
+}
 function isValidCommand(command) {
   return command in commandRegistry;
 }
@@ -5262,6 +5270,10 @@ async function main(options) {
   const { commandArguments, context, fileSystem, glob, directoryFileSorter } = options;
   const settings = await loadSettings(context.cwd, fileSystem);
   const helpText = generateHelpText(settings);
+  if (isVersionRequest(commandArguments[0])) {
+    context.stdout(DUST_VERSION);
+    return { exitCode: 0 };
+  }
   if (isHelpRequest(commandArguments[0])) {
     context.stdout(helpText);
     return { exitCode: 0 };
@@ -5350,4 +5362,4 @@ await wireEntry({ existsSync, statSync: statSync2, readFile: readFile2, writeFil
     process.stdout.write(message);
   },
   error: console.error
-});
+});

package/dist/filesystem/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Filesystem abstraction types used across the codebase.
+ */
+export interface WriteOptions {
+    flag?: 'w' | 'wx';
+}
+export interface ReadableFileSystem {
+    exists: (path: string) => boolean;
+    readFile: (path: string) => Promise<string>;
+    readdir: (path: string) => Promise<string[]>;
+    isDirectory: (path: string) => boolean;
+}
+export interface FileSystem extends ReadableFileSystem {
+    writeFile: (path: string, content: string, options?: WriteOptions) => Promise<void>;
+    mkdir: (path: string, options?: {
+        recursive?: boolean;
+    }) => Promise<void>;
+    chmod: (path: string, mode: number) => Promise<void>;
+    getFileCreationTime: (path: string) => number;
+    rename: (oldPath: string, newPath: string) => Promise<void>;
+}
+export interface GlobScanner {
+    scan: (dir: string) => AsyncIterable<string>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
@@ -22,6 +22,13 @@
       "import": "./dist/artifacts.js",
       "types": "./dist/artifacts/index.d.ts"
     },
+    "./audits": {
+      "import": "./dist/audits.js",
+      "types": "./dist/audits/index.d.ts"
+    },
+    "./filesystem": {
+      "types": "./dist/filesystem/types.d.ts"
+    },
     "./istanbul/minimal-reporter": "./lib/istanbul/minimal-reporter.cjs"
   },
   "files": [
@@ -42,7 +49,7 @@
   "author": "joshski",
   "license": "MIT",
   "scripts": {
-    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && bun build lib/logging/index.ts --target node --outfile dist/logging.js && bun build lib/agents/detection.ts --target node --outfile dist/agents.js && bun build lib/artifacts/index.ts --target node --outfile dist/artifacts.js && bunx tsc --project tsconfig.build.json",
+    "build": "bun run scripts/build.ts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "eval": "bun run ./evals/run.ts"