@joshski/dust 0.1.110 → 0.1.112

package/README.md

@@ -47,3 +47,7 @@ Details live in the [.dust/facts](./.dust/facts) directory:
 - [Directory Structure](./.dust/facts/dust-directory-structure.md) — how `.dust/` is organized
 - [Configuration](./.dust/facts/configuration-system.md) — settings and quality checks
 - [CLI Commands](./.dust/facts/unified-cli.md) — full command reference
+
+## Dust Bucket Worker
+
+The `dust bucket worker` command runs a background worker that syncs agent sessions to [dustbucket.com](https://dustbucket.com). This requires a dustbucket.com account (currently in private alpha, invite only).

package/dist/artifacts/facts.d.ts

@@ -1,9 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Fact {
-    slug: string;
-    title: string;
-    content: string;
-}
+import type { Fact } from './types';
+export type { Fact };
 /**
  * Parses a fact markdown file into a structured Fact object.
  */

package/dist/artifacts/ideas.d.ts

@@ -1,19 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface IdeaOption {
-    name: string;
-    description: string;
-}
-export interface IdeaOpenQuestion {
-    question: string;
-    options: IdeaOption[];
-}
-export interface Idea {
-    slug: string;
-    title: string;
-    openingSentence: string | null;
-    content: string;
-    openQuestions: IdeaOpenQuestion[];
-}
+import type { Idea, IdeaOpenQuestion, IdeaOption } from './types';
+export type { Idea, IdeaOpenQuestion, IdeaOption };
 export interface ParsedIdeaContent {
     title: string | null;
     body: string;

package/dist/artifacts/index.d.ts

@@ -6,21 +6,11 @@ import { type Principle } from './principles';
 import { type Task } from './tasks';
 import { type ParsedArtifact, type ParsedMarkdownLink, type ParsedSection, parseArtifact } from './parsed-artifact';
 import { type AllWorkflowTasks, CAPTURE_IDEA_PREFIX, type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, findAllWorkflowTasks, type IdeaInProgress, type OpenQuestionResponse, type ParsedCaptureIdeaTask, parseResolvedQuestions, type TaskType, type WorkflowTaskMatch } from './workflow-tasks';
+import type { ArtifactType, ReadOnlyArtifactsRepository } from './types';
+export type { ArtifactType, ReadOnlyArtifactsRepository, RepositoryPrincipleNode, TaskGraph, TaskGraphNode, } from './types';
 export type { AllWorkflowTasks, CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, Fact, Idea, IdeaOpenQuestion, IdeaOption, OpenQuestionResponse, ParsedArtifact, ParsedCaptureIdeaTask, ParsedIdeaContent, ParsedMarkdownLink, ParsedSection, Principle, Task, TaskType, WorkflowTaskMatch, };
-export interface TaskGraphNode {
-    task: Task;
-    workflowType: TaskType | null;
-}
-export interface TaskGraph {
-    nodes: TaskGraphNode[];
-    edges: Array<{
-        from: string;
-        to: string;
-    }>;
-}
 export { CAPTURE_IDEA_PREFIX, extractTitle, findAllWorkflowTasks, ideaContentToMarkdown, parseArtifact, parseIdeaContent, parseOpenQuestions, parseResolvedQuestions, };
 export type { IdeaInProgress };
-export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
 export declare const ARTIFACT_TYPES: ArtifactType[];
 export declare const DUST_PATH_PREFIX = ".dust/";
 /**
@@ -32,32 +22,6 @@ export declare function parseArtifactPath(path: string): {
     type: ArtifactType;
     slug: string;
 } | null;
-export interface ReadOnlyArtifactsRepository {
-    artifactPath(type: ArtifactType, slug: string): string;
-    parseIdea(options: {
-        slug: string;
-    }): Promise<Idea>;
-    listIdeas(): Promise<string[]>;
-    parsePrinciple(options: {
-        slug: string;
-    }): Promise<Principle>;
-    listPrinciples(): Promise<string[]>;
-    parseFact(options: {
-        slug: string;
-    }): Promise<Fact>;
-    listFacts(): Promise<string[]>;
-    parseTask(options: {
-        slug: string;
-    }): Promise<Task>;
-    listTasks(): Promise<string[]>;
-    findWorkflowTaskForIdea(options: {
-        ideaSlug: string;
-    }): Promise<WorkflowTaskMatch | null>;
-    parseCaptureIdeaTask(options: {
-        taskSlug: string;
-    }): Promise<ParsedCaptureIdeaTask | null>;
-    buildTaskGraph(): Promise<TaskGraph>;
-}
 export interface ArtifactsRepository extends ReadOnlyArtifactsRepository {
     createRefineIdeaTask(options: {
         ideaSlug: string;

package/dist/artifacts/principles.d.ts

@@ -1,11 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Principle {
-    slug: string;
-    title: string;
-    content: string;
-    parentPrinciple: string | null;
-    subPrinciples: string[];
-}
+import type { Principle } from './types';
+export type { Principle };
 /**
  * Parses a principle markdown file into a structured Principle object.
  */

package/dist/artifacts/repository-principle-hierarchy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Repository Principle Hierarchy API
+ *
+ * Provides pure functional access to build hierarchical trees of principles
+ * from a repository's .dust/principles/ directory.
+ */
+import type { ReadOnlyArtifactsRepository, RepositoryPrincipleNode } from './types';
+/**
+ * Builds a hierarchy tree of repository principles from .dust/principles/.
+ * Returns root nodes (principles with no parent or filtered parent).
+ * Children are sorted alphabetically by title (recursive).
+ *
+ * @param repository - The repository to read principles from
+ * @returns Array of root principle nodes, empty array if no principles exist
+ */
+export declare function getRepositoryPrincipleHierarchy(repository: ReadOnlyArtifactsRepository): Promise<RepositoryPrincipleNode[]>;

package/dist/artifacts/tasks.d.ts

@@ -1,12 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Task {
-    slug: string;
-    title: string;
-    content: string;
-    principles: string[];
-    blockedBy: string[];
-    definitionOfDone: string[];
-}
+import type { Task } from './types';
+export type { Task };
 /**
  * Parses a task markdown file into a structured Task object.
  */

package/dist/artifacts/types.d.ts

@@ -0,0 +1,98 @@
+export type TaskType = 'implement' | 'capture' | 'refine' | 'decompose' | 'shelve';
+export interface Fact {
+    slug: string;
+    title: string;
+    content: string;
+}
+export interface IdeaOption {
+    name: string;
+    description: string;
+}
+export interface IdeaOpenQuestion {
+    question: string;
+    options: IdeaOption[];
+}
+export interface Idea {
+    slug: string;
+    title: string;
+    openingSentence: string | null;
+    content: string;
+    openQuestions: IdeaOpenQuestion[];
+}
+export interface Principle {
+    slug: string;
+    title: string;
+    content: string;
+    parentPrinciple: string | null;
+    subPrinciples: string[];
+}
+export interface Task {
+    slug: string;
+    title: string;
+    content: string;
+    principles: string[];
+    blockedBy: string[];
+    definitionOfDone: string[];
+}
+export interface OpenQuestionResponse {
+    question: string;
+    chosenOption: string;
+}
+export interface WorkflowTaskMatch {
+    type: TaskType;
+    ideaSlug: string;
+    taskSlug: string;
+    resolvedQuestions: OpenQuestionResponse[];
+}
+export interface ParsedCaptureIdeaTask {
+    ideaTitle: string;
+    ideaDescription: string;
+    expedite: boolean;
+}
+export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
+export interface TaskGraphNode {
+    task: Task;
+    workflowType: TaskType | null;
+}
+export interface TaskGraph {
+    nodes: TaskGraphNode[];
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Node in the principle hierarchy tree
+ */
+export interface RepositoryPrincipleNode {
+    slug: string;
+    title: string;
+    children: RepositoryPrincipleNode[];
+}
+export interface ReadOnlyArtifactsRepository {
+    artifactPath(type: ArtifactType, slug: string): string;
+    parseIdea(options: {
+        slug: string;
+    }): Promise<Idea>;
+    listIdeas(): Promise<string[]>;
+    parsePrinciple(options: {
+        slug: string;
+    }): Promise<Principle>;
+    listPrinciples(): Promise<string[]>;
+    parseFact(options: {
+        slug: string;
+    }): Promise<Fact>;
+    listFacts(): Promise<string[]>;
+    parseTask(options: {
+        slug: string;
+    }): Promise<Task>;
+    listTasks(): Promise<string[]>;
+    findWorkflowTaskForIdea(options: {
+        ideaSlug: string;
+    }): Promise<WorkflowTaskMatch | null>;
+    parseCaptureIdeaTask(options: {
+        taskSlug: string;
+    }): Promise<ParsedCaptureIdeaTask | null>;
+    buildTaskGraph(): Promise<TaskGraph>;
+    getRepositoryPrincipleHierarchy(): Promise<RepositoryPrincipleNode[]>;
+}

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

@@ -1,4 +1,6 @@
 import type { FileSystem, ReadableFileSystem } from '../filesystem/types';
+import type { OpenQuestionResponse, ParsedCaptureIdeaTask, TaskType, WorkflowTaskMatch } from './types';
+export type { OpenQuestionResponse, ParsedCaptureIdeaTask, TaskType, WorkflowTaskMatch, };
 export declare const IDEA_TRANSITION_PREFIXES: string[];
 export declare const CAPTURE_IDEA_PREFIX = "Add Idea: ";
 export declare const EXPEDITE_IDEA_PREFIX = "Expedite Idea: ";
@@ -6,11 +8,6 @@ export interface IdeaInProgress {
     taskSlug: string;
     ideaTitle: string;
 }
-export interface ParsedCaptureIdeaTask {
-    ideaTitle: string;
-    ideaDescription: string;
-    expedite: boolean;
-}
 /**
  * Converts a markdown title to the expected filename using deterministic rules:
  * 1. Convert to lowercase
@@ -22,18 +19,11 @@ export interface ParsedCaptureIdeaTask {
  */
 export declare function titleToFilename(title: string): string;
 export declare const VALID_TASK_TYPES: readonly ["implement", "capture", "refine", "decompose", "shelve"];
-export type TaskType = (typeof VALID_TASK_TYPES)[number];
 /**
  * Extracts and validates the task type from the ## Task Type section.
  * Returns the task type if found and valid, null otherwise.
  */
 export declare function parseTaskType(content: string): TaskType | null;
-export interface WorkflowTaskMatch {
-    type: TaskType;
-    ideaSlug: string;
-    taskSlug: string;
-    resolvedQuestions: OpenQuestionResponse[];
-}
 export interface AllWorkflowTasks {
     captureIdeaTasks: IdeaInProgress[];
     workflowTasksByIdeaSlug: Map<string, WorkflowTaskMatch>;
@@ -43,10 +33,6 @@ export declare function findWorkflowTaskForIdea(fileSystem: ReadableFileSystem,
 export interface CreateIdeaTransitionTaskResult {
     filePath: string;
 }
-export interface OpenQuestionResponse {
-    question: string;
-    chosenOption: string;
-}
 export interface DecomposeIdeaOptions {
     ideaSlug: string;
     description?: string;

package/dist/artifacts.js

@@ -294,10 +294,7 @@ async function parsePrinciple(fileSystem, dustPath, slug) {
     throw new Error(`Principle not found: "${slug}" (expected file at ${principlePath})`);
   }
   const content = await fileSystem.readFile(principlePath);
-  const title = extractTitle(content);
-  if (!title) {
-    throw new Error(`Principle file has no title: ${principlePath}`);
-  }
+  const title = extractTitle(content) || slug;
   const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
   const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
   return {
@@ -999,6 +996,42 @@ async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
   return { ideaTitle, ideaDescription, expedite };
 }
 
+// lib/artifacts/repository-principle-hierarchy.ts
+function sortNodes(nodes) {
+  nodes.sort((a, b) => a.title.localeCompare(b.title));
+  for (const node of nodes) {
+    sortNodes(node.children);
+  }
+}
+async function getRepositoryPrincipleHierarchy(repository) {
+  const slugs = await repository.listPrinciples();
+  if (slugs.length === 0) {
+    return [];
+  }
+  const principles = await Promise.all(slugs.map((slug) => repository.parsePrinciple({ slug })));
+  const principleSet = new Set(slugs);
+  const nodeBySlug = new Map;
+  for (const p of principles) {
+    nodeBySlug.set(p.slug, {
+      slug: p.slug,
+      title: p.title,
+      children: []
+    });
+  }
+  const roots = [];
+  for (const p of principles) {
+    const node = nodeBySlug.get(p.slug);
+    const parentSlug = p.parentPrinciple;
+    if (!parentSlug || !principleSet.has(parentSlug)) {
+      roots.push(node);
+    } else {
+      nodeBySlug.get(parentSlug).children.push(node);
+    }
+  }
+  sortNodes(roots);
+  return roots;
+}
+
 // lib/artifacts/index.ts
 var ARTIFACT_TYPES = [
   "facts",
@@ -1099,6 +1132,9 @@ function buildReadOperations(fileSystem, dustPath) {
         }
       }
       return { nodes, edges };
+    },
+    async getRepositoryPrincipleHierarchy() {
+      return getRepositoryPrincipleHierarchy(this);
     }
   };
 }

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

@@ -12,7 +12,7 @@ import type { SendAgentEventFn } from '../loop/wire-events';
 import { type RunnerDependencies as CodexRunnerDependencies, run as codexRun } from '../codex/run';
 import type { SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
-import type { RepositoryDependencies, RepositoryState } from './repository';
+import type { RepositoryDependencies, RepositoryState } from './repository-types';
 /**
  * Create stdout/stderr callbacks that append to a log buffer.
  * Extracted for testability (v8 coverage limitation on inline callbacks).

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

@@ -0,0 +1,58 @@
+/**
+ * Shared types for repository management.
+ *
+ * Extracted to break the cyclic dependency between repository.ts and repository-loop.ts.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { run as claudeRun } from '../claude/run';
+import type { FileSystem } from '../cli/types';
+import type { DockerDependencies } from '../docker/docker-agent';
+import type { AuthConfig, RuntimeConfig, SessionConfig } from '../env-config';
+import type { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
+import type { LogBuffer } from './log-buffer';
+import type { RepositoryLifecycleState } from './repository-lifecycle';
+import type { ToolDefinition } from './server-messages';
+export interface Repository {
+    name: string;
+    gitUrl: string;
+    gitSshUrl: string;
+    url: string;
+    id: number;
+    agentProvider?: string;
+    branch?: string;
+}
+export interface RepositoryState {
+    repository: Repository;
+    path: string;
+    logBuffer: LogBuffer;
+    lifecycle: RepositoryLifecycleState;
+    agentStatus: 'idle' | 'busy';
+    wakeUp?: () => void;
+    taskAvailablePending?: boolean;
+}
+export interface RepositoryDependencies {
+    spawn: typeof nodeSpawn;
+    run: typeof claudeRun;
+    fileSystem: FileSystem;
+    sleep: (ms: number) => Promise<void>;
+    getReposDir: () => string;
+    session: SessionConfig;
+    runtime: RuntimeConfig;
+    auth: AuthConfig;
+    /** Optional overrides for Docker dependency functions (for testing) */
+    dockerDeps?: Partial<DockerDependencies>;
+    /** Function to get current tool definitions */
+    getTools?: () => ToolDefinition[];
+    /** Function to get revealed tool families (for progressive disclosure) */
+    getRevealedFamilies?: () => Set<string>;
+    /** Forward tool execution requests to the bucket server */
+    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
+    /** Mark a tool family as revealed (for progressive disclosure) */
+    revealFamily?: (familyName: string) => void;
+    /** Shell runner for pre-flight commands (install, check) */
+    shellRunner?: import('../cli/process-runner').ShellRunner;
+    /** Force Docker mode using bundled default Dockerfile */
+    forceDocker?: boolean;
+    /** Force Apple Container mode using bundled default Dockerfile */
+    forceAppleContainer?: boolean;
+}

package/dist/bucket/repository.d.ts

@@ -4,37 +4,13 @@
  * Git operations live in repository-git.ts.
  * Loop orchestration lives in repository-loop.ts.
  */
-import { spawn as nodeSpawn } from 'node:child_process';
-import { run as claudeRun } from '../claude/run';
 import type { CommandDependencies, FileSystem } from '../cli/types';
-import type { DockerDependencies } from '../docker/docker-agent';
-import { type AuthConfig, type RuntimeConfig, type SessionConfig } from '../env-config';
-import type { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
 import { type BucketEmitFn, type SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
-import { type RepositoryLifecycleState } from './repository-lifecycle';
-import type { ToolDefinition } from './server-messages';
+import type { Repository, RepositoryDependencies, RepositoryState } from './repository-types';
 export { cloneRepository, getRepoPath, removeRepository, } from './repository-git';
 export { runRepositoryLoop } from './repository-loop';
-export type { RepositoryLifecycleState } from './repository-lifecycle';
-export interface Repository {
-    name: string;
-    gitUrl: string;
-    gitSshUrl: string;
-    url: string;
-    id: number;
-    agentProvider?: string;
-    branch?: string;
-}
-export interface RepositoryState {
-    repository: Repository;
-    path: string;
-    logBuffer: LogBuffer;
-    lifecycle: RepositoryLifecycleState;
-    agentStatus: 'idle' | 'busy';
-    wakeUp?: () => void;
-    taskAvailablePending?: boolean;
-}
+export type { Repository, RepositoryDependencies, RepositoryState, } from './repository-types';
 /**
  * Interface for the subset of bucket state needed by repository management.
  * Avoids circular dependency between repository.ts and bucket.ts.
@@ -46,32 +22,6 @@ export interface RepositoryManager {
     sendEvent: SendEventFn;
     sessionId: string;
 }
-export interface RepositoryDependencies {
-    spawn: typeof nodeSpawn;
-    run: typeof claudeRun;
-    fileSystem: FileSystem;
-    sleep: (ms: number) => Promise<void>;
-    getReposDir: () => string;
-    session: SessionConfig;
-    runtime: RuntimeConfig;
-    auth: AuthConfig;
-    /** Optional overrides for Docker dependency functions (for testing) */
-    dockerDeps?: Partial<DockerDependencies>;
-    /** Function to get current tool definitions */
-    getTools?: () => ToolDefinition[];
-    /** Function to get revealed tool families (for progressive disclosure) */
-    getRevealedFamilies?: () => Set<string>;
-    /** Forward tool execution requests to the bucket server */
-    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
-    /** Mark a tool family as revealed (for progressive disclosure) */
-    revealFamily?: (familyName: string) => void;
-    /** Shell runner for pre-flight commands (install, check) */
-    shellRunner?: import('../cli/process-runner').ShellRunner;
-    /** Force Docker mode using bundled default Dockerfile */
-    forceDocker?: boolean;
-    /** Force Apple Container mode using bundled default Dockerfile */
-    forceAppleContainer?: boolean;
-}
 /**
  * Handle loop completion: transition lifecycle and reset agent status.
  * Extracted as a named function for testability.

package/dist/bucket/server-messages.d.ts

@@ -1,13 +1,19 @@
 /**
  * Typed server-to-client WebSocket messages for the bucket protocol.
  */
-import type { Repository } from './repository';
 import type { AgentCapability } from './agent-capabilities';
 export interface RepositoryListMessage {
     type: 'repository-list';
     repositories: RepositoryListItem[];
 }
-export interface RepositoryListItem extends Repository {
+export interface RepositoryListItem {
+    name: string;
+    gitUrl: string;
+    gitSshUrl: string;
+    url: string;
+    id: number;
+    agentProvider?: string;
+    branch?: string;
     hasTask: boolean;
 }
 export interface TaskAvailableMessage {

package/dist/cli/types.d.ts

@@ -29,7 +29,11 @@ export interface DustSettings {
     excludeCorePrinciples?: string[];
     extraDirectories?: string[];
 }
-export type DirectoryFileSorter = (dir: string, files: string[]) => Promise<string[]>;
+export interface FileWithTimestamp {
+    file: string;
+    lastCommittedAt: string | null;
+}
+export type DirectoryFileSorter = (dir: string, files: string[]) => Promise<FileWithTimestamp[]>;
 /**
  * Dependencies passed to all CLI commands
  */