@joshski/dust 0.1.65 → 0.1.68

package/README.md

@@ -15,6 +15,16 @@ npx dust init
 
 This creates a [.dust](./.dust/facts/dust-directory-structure.md) directory and adds an [instruction](./.dust/facts/agents-md-instruction.md) to your `AGENTS.md` file.
 
+## Adding Tasks
+
+Use your AI coding CLI (Claude Code, Codex, etc.) to add and refine tasks:
+
+```bash
+claude "add a task to refactor the auth module"
+```
+
+Ideas (`.dust/ideas/`) are backlog items you may or may not do later. Tasks (`.dust/tasks/`) are ready to work on now. Both are markdown files that agents and humans can read and edit.
+
 ## Running Agents
 
 Start an agent on a single task:

package/dist/artifacts.js

@@ -302,19 +302,53 @@ async function findAllCaptureIdeaTasks(fileSystem, dustPath) {
 function titleToFilename(title) {
   return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
 }
-var WORKFLOW_TASK_TYPES = [
-  { type: "refine", prefix: "Refine Idea: " },
-  { type: "decompose-idea", prefix: "Decompose Idea: " },
-  { type: "shelve", prefix: "Shelve Idea: " }
+var WORKFLOW_SECTION_HEADINGS = [
+  { type: "refine", heading: "Refines Idea" },
+  { type: "decompose-idea", heading: "Decomposes Idea" },
+  { type: "shelve", heading: "Shelves Idea" }
 ];
+function extractIdeaSlugFromSection(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  let inSection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inSection = line.trimEnd() === `## ${sectionHeading}`;
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.startsWith("# "))
+      break;
+    const linkMatch = line.match(MARKDOWN_LINK_PATTERN);
+    if (linkMatch) {
+      const target = linkMatch[2];
+      const slugMatch = target.match(/([^/]+)\.md$/);
+      if (slugMatch) {
+        return slugMatch[1];
+      }
+    }
+  }
+  return null;
+}
 async function findWorkflowTaskForIdea(fileSystem, dustPath, ideaSlug) {
-  const ideaTitle = await readIdeaTitle(fileSystem, dustPath, ideaSlug);
-  for (const { type, prefix } of WORKFLOW_TASK_TYPES) {
-    const filename = titleToFilename(`${prefix}${ideaTitle}`);
-    const filePath = `${dustPath}/tasks/${filename}`;
-    if (fileSystem.exists(filePath)) {
-      const taskSlug = filename.replace(/\.md$/, "");
-      return { type, ideaSlug, taskSlug };
+  const ideaPath = `${dustPath}/ideas/${ideaSlug}.md`;
+  if (!fileSystem.exists(ideaPath)) {
+    throw new Error(`Idea not found: "${ideaSlug}" (expected file at ${ideaPath})`);
+  }
+  const tasksPath = `${dustPath}/tasks`;
+  if (!fileSystem.exists(tasksPath)) {
+    return null;
+  }
+  const files = await fileSystem.readdir(tasksPath);
+  for (const file of files.filter((f) => f.endsWith(".md")).sort()) {
+    const content = await fileSystem.readFile(`${tasksPath}/${file}`);
+    for (const { type, heading } of WORKFLOW_SECTION_HEADINGS) {
+      const linkedSlug = extractIdeaSlugFromSection(content, heading);
+      if (linkedSlug === ideaSlug) {
+        const taskSlug = file.replace(/\.md$/, "");
+        return { type, ideaSlug, taskSlug };
+      }
     }
   }
   return null;
@@ -342,18 +376,26 @@ ${sections.join(`
 `)}
 `;
 }
-function renderTask(title, openingSentence, definitionOfDone, options) {
+function renderIdeaSection(ideaSection) {
+  return `## ${ideaSection.heading}
+
+- [${ideaSection.ideaTitle}](../ideas/${ideaSection.ideaSlug}.md)
+`;
+}
+function renderTask(title, openingSentence, definitionOfDone, ideaSection, options) {
   const descriptionParagraph = options?.description !== undefined ? `
 ${options.description}
 ` : "";
   const resolvedSection = options?.resolvedQuestions && options.resolvedQuestions.length > 0 ? `
 ${renderResolvedQuestions(options.resolvedQuestions)}
 ` : "";
+  const ideaSectionContent = `
+${renderIdeaSection(ideaSection)}
+`;
   return `# ${title}
 
 ${openingSentence}
-${descriptionParagraph}${resolvedSection}
-## Blocked By
+${descriptionParagraph}${resolvedSection}${ideaSectionContent}## Blocked By
 
 (none)
 
@@ -363,13 +405,17 @@ ${definitionOfDone.map((item) => `- [ ] ${item}`).join(`
 `)}
 `;
 }
-async function createIdeaTask(fileSystem, dustPath, prefix, ideaSlug, openingSentenceTemplate, definitionOfDone, taskOptions) {
+async function createIdeaTask(fileSystem, dustPath, prefix, ideaSlug, openingSentenceTemplate, definitionOfDone, ideaSectionHeading, taskOptions) {
   const ideaTitle = await readIdeaTitle(fileSystem, dustPath, ideaSlug);
   const taskTitle = `${prefix}${ideaTitle}`;
   const filename = titleToFilename(taskTitle);
   const filePath = `${dustPath}/tasks/${filename}`;
   const openingSentence = openingSentenceTemplate(ideaTitle);
-  const content = renderTask(taskTitle, openingSentence, definitionOfDone, taskOptions);
+  const ideaSection = { heading: ideaSectionHeading, ideaTitle, ideaSlug };
+  const content = renderTask(taskTitle, openingSentence, definitionOfDone, ideaSection, {
+    description: taskOptions?.description,
+    resolvedQuestions: taskOptions?.resolvedQuestions
+  });
   await fileSystem.writeFile(filePath, content);
   return { filePath };
 }
@@ -379,20 +425,20 @@ async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description)
     "Open questions are added for any ambiguous or underspecified aspects",
     "Open questions follow the required heading format and focus on high-value decisions",
     "Idea file is updated with findings"
-  ], { description });
+  ], "Refines Idea", { description });
 }
 async function decomposeIdea(fileSystem, dustPath, options) {
   return createIdeaTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks that each deliver a thin but complete vertical slice of working software -- a path through the system that can be tested end-to-end -- rather than component-oriented tasks (like "add schema" or "build endpoint") that only work once all tasks are done. Split the idea into multiple tasks if it covers more than one logical change. Review \`.dust/principles/\` to link relevant principles and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
     "One or more new tasks are created in .dust/tasks/",
     "Task's Principles section links to relevant principles from .dust/principles/",
     "The original idea is deleted or updated to reflect remaining scope"
-  ], {
+  ], "Decomposes Idea", {
     description: options.description,
     resolvedQuestions: options.openQuestionResponses
   });
 }
 async function createShelveIdeaTask(fileSystem, dustPath, ideaSlug, description) {
-  return createIdeaTask(fileSystem, dustPath, "Shelve Idea: ", ideaSlug, (ideaTitle) => `Archive this idea and remove it from the active backlog. See [${ideaTitle}](../ideas/${ideaSlug}.md).`, ["Idea file is deleted", "Rationale is recorded in the commit message"], { description });
+  return createIdeaTask(fileSystem, dustPath, "Shelve Idea: ", ideaSlug, (ideaTitle) => `Archive this idea and remove it from the active backlog. See [${ideaTitle}](../ideas/${ideaSlug}.md).`, ["Idea file is deleted", "Rationale is recorded in the commit message"], "Shelves Idea", { description });
 }
 async function createCaptureIdeaTask(fileSystem, dustPath, options) {
   const { title, description, buildItNow } = options;
@@ -408,7 +454,7 @@ async function createCaptureIdeaTask(fileSystem, dustPath, options) {
     const filePath2 = `${dustPath}/tasks/${filename2}`;
     const content2 = `# ${taskTitle2}
 
-Research this idea thoroughly, then create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context. Each task should deliver a thin but complete vertical slice of working software.
+Research this idea briefly. If confident the implementation is straightforward (clear scope, minimal risk, no open questions), implement directly and commit. Otherwise, create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context.
 
 ## Idea Description
 
@@ -420,9 +466,9 @@ ${description}
 
 ## Definition of Done
 
-- [ ] One or more new tasks are created in \`.dust/tasks/\`
-- [ ] Tasks link to relevant principles from \`.dust/principles/\`
-- [ ] Tasks are narrowly scoped vertical slices
+- [ ] Idea is implemented directly OR one or more new tasks are created in \`.dust/tasks/\`
+- [ ] If tasks were created, they link to relevant principles from \`.dust/principles/\`
+- [ ] Changes are committed with a clear commit message
 `;
     await fileSystem.writeFile(filePath2, content2);
     return { filePath: filePath2 };

package/dist/audits/index.d.ts

@@ -33,4 +33,9 @@ export interface AuditsRepository {
  * Changes the title from "# Original Title" to "# Audit: Original Title"
  */
 export declare function transformAuditContent(content: string): string;
+/**
+ * Injects an Ad-hoc Scope section after the opening description, before ## Scope.
+ * The ad-hoc details are passed through without validation.
+ */
+export declare function injectAdHocScope(content: string, adHocDetails: string): string;
 export declare function buildAuditsRepository(fileSystem: FileSystem, dustPath: string): AuditsRepository;

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

@@ -4,9 +4,10 @@
  * Users can override any of these by placing a file with the same name
  * in .dust/config/audits/.
  */
-export interface StockAudit {
+interface StockAudit {
     name: string;
     description: string;
     template: string;
 }
 export declare function loadStockAudits(): StockAudit[];
+export {};

package/dist/audits.js

@@ -64,6 +64,102 @@ function dedent(strings, ...values) {
 
 // lib/audits/stock-audits.ts
 var ideasHint = "Review existing ideas in `./.dust/ideas/` to understand what has been proposed or considered historically, then create new idea files in `./.dust/ideas/` for any issues you identify, avoiding duplication.";
+function dataAccessReview() {
+  return dedent`
+    # Data Access Review
+
+    Review data access patterns for performance issues and optimization opportunities.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **N+1 query patterns** - Loops that make individual data requests instead of batching
+    2. **Missing indexes** - Database schema files lacking indexes on frequently queried columns
+    3. **Inefficient data loading** - Over-fetching (loading more data than needed) or under-fetching (requiring multiple round trips)
+    4. **Caching opportunities** - Repeated lookups that could benefit from memoization or caching
+    5. **Batch processing** - Sequential operations that could be parallelized or batched
+    6. **Connection management** - Connection pooling configuration and resource cleanup
+
+    ## Analysis Steps
+
+    1. Search for loops containing data access calls (API requests, database queries, file reads)
+    2. Review database schema or migration files for index definitions
+    3. Identify functions that make multiple related data requests
+    4. Look for repeated identical lookups within the same request lifecycle
+    5. Check for proper resource cleanup (connection closing, stream ending)
+
+    ## Applicability
+
+    This audit applies to codebases that interact with:
+    - Databases (SQL, NoSQL, ORM queries)
+    - External APIs (REST, GraphQL, gRPC)
+    - File systems (reading/writing files)
+    - Caches (Redis, Memcached, in-memory)
+
+    If none of these apply, document that finding and skip the detailed analysis.
+
+    ## Principles
+
+    - [Decoupled Code](../principles/decoupled-code.md) - Data access should be isolated for testability
+    - [Fast Feedback](../principles/fast-feedback.md) - Efficient data access enables faster feedback loops
+    - [Maintainable Codebase](../principles/maintainable-codebase.md) - Good data patterns improve maintainability
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Searched for N+1 query patterns (loops with data access)
+    - [ ] Reviewed database schemas for missing indexes (if applicable)
+    - [ ] Identified over-fetching or under-fetching patterns
+    - [ ] Found repeated lookups that could be cached
+    - [ ] Checked for sequential operations that could be batched
+    - [ ] Verified connection/resource cleanup is handled properly
+    - [ ] Proposed ideas for any data access improvements identified
+  `;
+}
+function coverageExclusions() {
+  return dedent`
+    # Coverage Exclusions
+
+    Review coverage exclusion configuration to identify opportunities for removal through refactoring.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Current exclusions** - Review all exclusions in \`vitest.config.ts\` or equivalent
+    2. **Justification** - Is each exclusion still necessary?
+    3. **Tooling limitations** - Can workarounds be found for coverage tool issues?
+    4. **Decoupling opportunities** - Can excluded code be restructured to enable testing?
+    5. **Entry point patterns** - Can hard-to-test entry points be decoupled from logic?
+
+    ## Principles
+
+    - [Decoupled Code](../principles/decoupled-code.md)
+    - [Unit Test Coverage](../principles/unit-test-coverage.md)
+    - [Comprehensive Test Coverage](../principles/comprehensive-test-coverage.md)
+    - [Make Changes with Confidence](../principles/make-changes-with-confidence.md)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Identified all coverage exclusions in the project
+    - [ ] Documented the reason each exclusion exists
+    - [ ] Evaluated whether each exclusion is still necessary
+    - [ ] Identified exclusions that could be removed through decoupling
+    - [ ] Proposed ideas for refactoring where feasible
+  `;
+}
 function componentReuse() {
   return dedent`
     # Component Reuse
@@ -274,6 +370,56 @@ function ideasFromPrinciples() {
     - [ ] Proposed new ideas for unmet or underserved principles
   `;
 }
+function refactoringOpportunities() {
+  return dedent`
+    # Refactoring Opportunities
+
+    Analyze recent commits to identify code needing structural improvements.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Analyze commits since the last refactoring-opportunities audit (check \`.dust/done/\` for previous runs). Focus on these signals:
+
+    1. **File churn** - Files modified frequently across multiple commits may have unclear responsibilities or be accumulating technical debt
+    2. **Size growth** - Files that have grown significantly may benefit from decomposition
+    3. **Commit message patterns** - Look for messages containing "fix", "workaround", "temporary", "hack", or "TODO" that indicate shortcuts taken
+
+    ## Analysis Steps
+
+    1. Run \`git log --since="<last-audit-date>" --name-only --pretty=format:"COMMIT:%s"\` to get commits with their messages and changed files
+    2. Count file modification frequency to identify high-churn files
+    3. Check current sizes of frequently-modified files with \`wc -l\`
+    4. Review commit messages for patterns suggesting technical debt
+
+    ## Output
+
+    For each refactoring opportunity identified, provide:
+    - **File path** - The specific file needing attention
+    - **Signal** - What triggered this recommendation (churn, size, commit pattern)
+    - **Specific suggestion** - A concrete refactoring action (e.g., "Extract the validation logic into a separate module", not just "consider refactoring")
+
+    ## Principles
+
+    - [Boy Scout Rule](../principles/boy-scout-rule.md) - Leave code better than found, but capture large cleanups as separate tasks
+    - [Make the Change Easy](../principles/make-the-change-easy.md) - Refactor until the change becomes straightforward
+    - [Make Changes with Confidence](../principles/make-changes-with-confidence.md) - Tests and checks enable safe refactoring
+    - [Reasonably DRY](../principles/reasonably-dry.md) - Extract only when duplication represents the same concept
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Identified high-churn files (modified in 3+ commits since last audit)
+    - [ ] Flagged files exceeding 300 lines that grew significantly
+    - [ ] Noted commits with concerning message patterns
+    - [ ] Provided specific refactoring suggestions for each opportunity
+    - [ ] Created ideas for any substantial refactoring work identified
+  `;
+}
 function performanceReview() {
   return dedent`
     # Performance Review
@@ -414,17 +560,129 @@ function testCoverage() {
     - [ ] Proposed ideas for any test coverage gaps identified
   `;
 }
+function errorHandling() {
+  return dedent`
+    # Error Handling
+
+    Review error handling patterns for consistency and agent-friendliness.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Silently swallowed errors** - Empty catch blocks, \`.catch(() => {})\`, errors caught but not logged or re-thrown
+    2. **Missing error context** - Errors converted to booleans or generic messages that lose details
+    3. **Fire-and-forget promises** - Promises without \`.catch()\` or \`await\` that may fail silently
+    4. **Non-actionable error messages** - Error messages that say what went wrong but not how to fix it
+    5. **Inconsistent error recovery** - Similar error scenarios handled differently across the codebase
+
+    ## Analysis Steps
+
+    1. Search for empty catch blocks: \`catch {}\`, \`catch () {}\`, \`.catch(() => {})\`
+    2. Look for patterns that discard error details: \`catch { return false }\`, \`catch { return null }\`
+    3. Find promises without error handling: unassigned or not-awaited promises
+    4. Review error messages in \`throw\` statements and \`context.stderr()\` calls for actionability
+    5. Compare error handling patterns across similar operations for consistency
+
+    ## Output
+
+    For each error handling issue identified, provide:
+    - **Location** - File path and line number
+    - **Pattern** - Which category of issue (swallowed, missing context, fire-and-forget, etc.)
+    - **Impact** - What failures could go unnoticed or be hard to debug
+    - **Suggestion** - Specific fix (add logging, propagate error, add recovery guidance)
+
+    ## Principles
+
+    - [Actionable Errors](../principles/actionable-errors.md) - Error messages should tell you what to do next
+    - [Debugging Tooling](../principles/debugging-tooling.md) - Agents need readable, structured error output
+    - [Stop the Line](../principles/stop-the-line.md) - Problems should be fixed at source, not hidden
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Searched for empty catch blocks and silent error swallowing
+    - [ ] Identified patterns that discard error details
+    - [ ] Found fire-and-forget promises without error handling
+    - [ ] Reviewed error messages for actionability
+    - [ ] Compared error handling consistency across similar operations
+    - [ ] Proposed ideas for any error handling improvements identified
+  `;
+}
+function ubiquitousLanguage() {
+  return dedent`
+    # Ubiquitous Language
+
+    Verify terminology consistency across code, documentation, and user interface.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Terminology drift** - Do recent changes introduce terms that deviate from established vocabulary?
+    2. **Code-to-docs alignment** - Are variables, functions, and types named consistently with documentation?
+    3. **User interface consistency** - Do UI labels and messages match the terms used in code and docs?
+    4. **Glossary adherence** - If a glossary exists, is it being followed?
+    5. **Acronym and abbreviation usage** - Are shortened forms used consistently?
+
+    ## Analysis Steps
+
+    1. Identify key domain terms from documentation, README, or existing glossary
+    2. Review recent commits for new terminology or naming choices
+    3. Compare code identifiers against documented terminology
+    4. Check user-facing strings for consistency with technical naming
+    5. Flag deviations where the same concept uses different names
+
+    ## Output
+
+    For each terminology issue identified, provide:
+    - **Term in question** - The inconsistent or unclear term
+    - **Where found** - File paths and locations where the term appears
+    - **Recommended action** - Standardize on existing term, or propose a new canonical name
+
+    ## Principles
+
+    - [Naming Matters](../principles/naming-matters.md) - Good naming reduces waste by eliminating confusion
+    - [Consistent Naming](../principles/consistent-naming.md) - Names should follow established conventions
+    - [Clarity Over Brevity](../principles/clarity-over-brevity.md) - Names should be descriptive and self-documenting
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Identified key domain terms from project documentation
+    - [ ] Reviewed recent commits for terminology consistency
+    - [ ] Compared code naming against documentation vocabulary
+    - [ ] Checked user-facing text for alignment with code terms
+    - [ ] Documented any terminology drift or inconsistencies found
+    - [ ] Proposed ideas for standardizing inconsistent terminology
+  `;
+}
 var stockAuditFunctions = {
   "agent-developer-experience": agentDeveloperExperience,
   "component-reuse": componentReuse,
+  "coverage-exclusions": coverageExclusions,
+  "data-access-review": dataAccessReview,
   "dead-code": deadCode,
+  "error-handling": errorHandling,
   "facts-verification": factsVerification,
   "ideas-from-commits": ideasFromCommits,
   "ideas-from-principles": ideasFromPrinciples,
   "performance-review": performanceReview,
+  "refactoring-opportunities": refactoringOpportunities,
   "security-review": securityReview,
   "stale-ideas": staleIdeas,
-  "test-coverage": testCoverage
+  "test-coverage": testCoverage,
+  "ubiquitous-language": ubiquitousLanguage
 };
 function loadStockAudits() {
   return Object.entries(stockAuditFunctions).sort(([a], [b]) => a.localeCompare(b)).map(([name, render]) => {
@@ -443,6 +701,24 @@ function transformAuditContent(content) {
   const originalTitle = titleMatch[1];
   return content.replace(/^#\s+.+$/m, `# Audit: ${originalTitle}`);
 }
+function injectAdHocScope(content, adHocDetails) {
+  const scopeMatch = content.match(/\n## Scope\n/);
+  if (scopeMatch?.index !== undefined) {
+    const insertIndex = scopeMatch.index;
+    const adHocSection = `
+## Ad-hoc Scope
+
+${adHocDetails}
+`;
+    return content.slice(0, insertIndex) + adHocSection + content.slice(insertIndex);
+  }
+  return `${content}
+
+## Ad-hoc Scope
+
+${adHocDetails}
+`;
+}
 function buildAuditsRepository(fileSystem, dustPath) {
   const userAuditsPath = `${dustPath}/config/audits`;
   const tasksPath = `${dustPath}/tasks`;
@@ -511,5 +787,6 @@ function buildAuditsRepository(fileSystem, dustPath) {
 export {
   transformAuditContent,
   loadStockAudits,
+  injectAdHocScope,
   buildAuditsRepository
 };

package/dist/bucket/events.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Bucket event types and WebSocket event sending.
+ *
+ * BucketEvent types are local-only (UI lifecycle). Wire events use
+ * EventMessage from agent-events.ts and are sent via createEventMessageSender.
+ */
+import type { EventMessage } from '../agent-events';
+export declare const WS_OPEN = 1;
+export declare const WS_CLOSED = 3;
+export interface WebSocketLike {
+    onopen: (() => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((error: Error) => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    close: () => void;
+    send: (data: string) => void;
+    readyState: number;
+}
+interface BucketConnectedEvent {
+    type: 'bucket.connected';
+}
+interface BucketDisconnectedEvent {
+    type: 'bucket.disconnected';
+    code: number;
+    reason: string;
+}
+export interface BucketRepositoryAddedEvent {
+    type: 'bucket.repository_added';
+    repository: string;
+}
+export interface BucketRepositoryRemovedEvent {
+    type: 'bucket.repository_removed';
+    repository: string;
+}
+export interface BucketErrorEvent {
+    type: 'bucket.error';
+    repository?: string;
+    error: string;
+}
+export type BucketEvent = BucketConnectedEvent | BucketDisconnectedEvent | BucketRepositoryAddedEvent | BucketRepositoryRemovedEvent | BucketErrorEvent;
+export type BucketEmitFn = (event: BucketEvent) => void;
+export type SendEventFn = (msg: EventMessage) => void;
+export declare function formatBucketEvent(event: BucketEvent): string;
+export declare function createEventMessageSender(getWebSocket: () => WebSocketLike | null): SendEventFn;
+export {};

package/dist/bucket/log-buffer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Ring buffer for capturing subprocess output in dust bucket.
+ *
+ * Each repository has its own log buffer with a fixed maximum size.
+ * When the buffer exceeds the limit, it trims to the target size.
+ */
+export interface LogLine {
+    text: string;
+    stream: 'stdout' | 'stderr';
+    timestamp: number;
+}
+export interface LogBuffer {
+    lines: LogLine[];
+    maxLines: number;
+    trimToLines: number;
+}
+/**
+ * Create a new log buffer with default settings.
+ */
+export declare function createLogBuffer(maxLines?: number, trimToLines?: number): LogBuffer;
+/**
+ * Append a log line to the buffer, trimming if necessary.
+ */
+export declare function appendLogLine(buffer: LogBuffer, line: LogLine): void;
+/**
+ * Create a log line from raw output.
+ */
+export declare function createLogLine(text: string, stream: 'stdout' | 'stderr', timestamp?: number): LogLine;
+/**
+ * Get all lines from the buffer.
+ */
+export declare function getLogLines(buffer: LogBuffer): readonly LogLine[];
+/**
+ * Get the most recent N lines from the buffer.
+ */
+export declare function getRecentLines(buffer: LogBuffer, count: number): LogLine[];
+/**
+ * Clear all lines from the buffer.
+ */
+export declare function clearLogBuffer(buffer: LogBuffer): void;

package/dist/bucket/paths.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Path utilities for dust bucket operations.
+ *
+ * Pure functions that compute paths from explicit parameters,
+ * following the "functional core, imperative shell" pattern.
+ */
+/**
+ * Environment variables used by getReposDir.
+ * Includes an index signature for compatibility with process.env.
+ */
+interface ReposDirEnv {
+    DUST_REPOS_DIR?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Compute the repositories directory path.
+ *
+ * If DUST_REPOS_DIR is set in the environment, returns that value.
+ * Otherwise, returns the default path: ~/.dust/repos
+ *
+ * @param env - Environment variables object
+ * @param homeDir - User's home directory path
+ * @returns The resolved repositories directory path
+ */
+export declare function getReposDir(env: ReposDirEnv, homeDir: string): string;
+export {};

package/dist/bucket/repository-git.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Git operations for dust bucket repository management.
+ *
+ * Handles cloning, removing, and path resolution for repositories.
+ */
+import type { spawn as nodeSpawn } from 'node:child_process';
+import type { CommandDependencies } from '../cli/types';
+/**
+ * Get the directory path for a repository.
+ */
+export declare function getRepoPath(repoName: string, reposDir: string): string;
+/**
+ * Clone a repository to a temporary directory.
+ */
+export declare function cloneRepository(repository: {
+    name: string;
+    gitUrl: string;
+}, targetPath: string, spawn: typeof nodeSpawn, context: CommandDependencies['context']): Promise<boolean>;
+/**
+ * Remove a repository directory.
+ */
+export declare function removeRepository(path: string, spawn: typeof nodeSpawn, context: CommandDependencies['context']): Promise<boolean>;