@joshski/dust 0.1.62 → 0.1.64

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,4 +1,4 @@
-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';

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/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;