@joshski/dust 0.1.88 → 0.1.90

package/biome/no-unsafe-double-cast.grit

@@ -0,0 +1,5 @@
+language js
+
+`$value as unknown as $target` where {
+  register_diagnostic(span=$target, message="Avoid double-casting with 'as unknown as'. Prefer typed helpers/adapters, or add a local suppression with rationale at unavoidable interop boundaries.")
+}

package/dist/agent-events.d.ts

@@ -4,6 +4,7 @@
  * These types define the transport-agnostic event format used by both
  * the HTTP (loop) and WebSocket (bucket) paths.
  */
+import type { CommandEvent } from './command-events';
 export type AgentSessionEvent = {
     type: 'agent-session-started';
     title: string;
@@ -25,6 +26,9 @@ export type AgentSessionEvent = {
     type: 'agent-event';
     provider: string;
     rawEvent: Record<string, unknown>;
+} | {
+    type: 'command-event';
+    commandEvent: CommandEvent;
 };
 export interface EventMessage {
     sequence: number;

package/dist/artifacts.js

@@ -409,6 +409,16 @@ function renderIdeaSection(ideaSection) {
 - [${ideaSection.ideaTitle}](../ideas/${ideaSection.ideaSlug}.md)
 `;
 }
+function renderRepositoryHintsSection(repositoryHint) {
+  if (!repositoryHint) {
+    return "";
+  }
+  return `
+## Repository Hints
+
+${repositoryHint}
+`;
+}
 function renderTask(title, openingSentence, definitionOfDone, ideaSection, options) {
   const descriptionParagraph = options?.description !== undefined ? `
 ${options.description}
@@ -419,12 +429,14 @@ ${renderResolvedQuestions(options.resolvedQuestions)}
   const ideaSectionContent = `
 ${renderIdeaSection(ideaSection)}
 `;
+  const repositoryHintsSection = renderRepositoryHintsSection(options?.repositoryHint);
   return `# ${title}
 
 ${openingSentence}
 ${descriptionParagraph}${resolvedSection}${ideaSectionContent}## Blocked By
 
 (none)
+${repositoryHintsSection}
 
 ## Definition of Done
 
@@ -439,13 +451,11 @@ async function createIdeaTransitionTask(fileSystem, dustPath, workflowType, pref
   const filePath = `${dustPath}/tasks/${filename}`;
   const baseOpeningSentence = openingSentenceTemplate(ideaTitle);
   const hint = await readWorkflowHint(fileSystem, dustPath, workflowType);
-  const openingSentence = hint ? `${baseOpeningSentence}
-
-${hint}` : baseOpeningSentence;
   const ideaSection = { heading: ideaSectionHeading, ideaTitle, ideaSlug };
-  const content = renderTask(taskTitle, openingSentence, definitionOfDone, ideaSection, {
+  const content = renderTask(taskTitle, baseOpeningSentence, definitionOfDone, ideaSection, {
     description: taskOptions?.description,
-    resolvedQuestions: taskOptions?.resolvedQuestions
+    resolvedQuestions: taskOptions?.resolvedQuestions,
+    repositoryHint: hint ?? undefined
   });
   await fileSystem.writeFile(filePath, content);
   return { filePath };
@@ -488,12 +498,10 @@ async function createIdeaTask(fileSystem, dustPath, options) {
     const filePath2 = `${dustPath}/tasks/${filename2}`;
     const baseOpeningSentence2 = `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/\`. Run \`${cmd} principles\` and \`${cmd} facts\` for relevant context.`;
     const hint2 = await readWorkflowHint(fileSystem, dustPath, "expedite-idea");
-    const openingSentence2 = hint2 ? `${baseOpeningSentence2}
-
-${hint2}` : baseOpeningSentence2;
+    const repositoryHintsSection2 = renderRepositoryHintsSection(hint2 ?? undefined);
     const content2 = `# ${taskTitle2}
 
-${openingSentence2}
+${baseOpeningSentence2}
 
 ## Idea Description
 
@@ -502,6 +510,7 @@ ${description}
 ## Blocked By
 
 (none)
+${repositoryHintsSection2}
 
 ## Definition of Done
 
@@ -517,12 +526,10 @@ ${description}
   const filePath = `${dustPath}/tasks/${filename}`;
   const baseOpeningSentence = `Research this idea thoroughly, then create one or more idea files in \`.dust/ideas/\`. Read the codebase for relevant context, flesh out the description, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking. Run \`${cmd} principles\` and \`${cmd} facts\` for relevant context.`;
   const hint = await readWorkflowHint(fileSystem, dustPath, "add-idea");
-  const openingSentence = hint ? `${baseOpeningSentence}
-
-${hint}` : baseOpeningSentence;
+  const repositoryHintsSection = renderRepositoryHintsSection(hint ?? undefined);
   const content = `# ${taskTitle}
 
-${openingSentence}
+${baseOpeningSentence}
 
 ## Idea Description
 
@@ -531,6 +538,7 @@ ${description}
 ## Blocked By
 
 (none)
+${repositoryHintsSection}
 
 ## Definition of Done
 

package/dist/audits.js

@@ -778,6 +778,204 @@ function slowTests() {
     - [ ] Proposed ideas for optimizing the slowest tests
   `;
 }
+function namingConsistency() {
+  return dedent`
+    # Naming Consistency
+
+    Review high-confidence naming consistency issues for equivalent factory/constructor creation APIs.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus only on high-confidence factory/constructor naming inconsistencies where intent is clearly the same:
+    - Equivalent creation abstractions using \`build*\`, \`create*\`, \`make*\`, or \`new*\`
+    - Cases where names differ but behavior and role clearly indicate the same creation concept
+
+    Out of scope:
+    - Canonical artifact-list ordering or shape checks
+    - Broad terminology drift and ambiguous language choices (covered by the \`ubiquitous-language\` audit)
+
+    ## Analysis Steps
+
+    1. Identify factory/constructor APIs with equivalent behavior that use \`build*\`, \`create*\`, \`make*\`, or \`new*\` naming variants
+    2. Group findings by shared creation concept to avoid duplicate reporting
+    3. Keep only high-confidence inconsistencies where the compared usages clearly represent the same concept
+    4. Recommend only high-confidence renames with clear semantic equivalence; do not propose speculative broad renames
+    5. Preserve Functional Core, Imperative Shell boundaries in recommendations (pure matching/analysis logic separated from IO shell)
+
+    ## Output
+
+    For each inconsistency, provide:
+    - **Locations** - File paths and line numbers where inconsistent factory/constructor names appear
+    - **Inconsistent term set** - The observed naming variants (for example \`createWidget\`, \`buildWidget\`, \`makeWidget\`)
+    - **Canonical proposal** - The recommended canonical name and rationale
+    - **Migration strategy** - Choose either **incremental** (aliases/adapters then cleanup) or **one-shot** (single coordinated rename), with rationale
+
+    ## Principles
+
+    - [Consistent Naming](../principles/consistent-naming.md)
+    - [Naming Matters](../principles/naming-matters.md)
+    - [Clarity Over Brevity](../principles/clarity-over-brevity.md)
+    - [Functional Core, Imperative Shell](../principles/functional-core-imperative-shell.md)
+    - [Small Units](../principles/small-units.md)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed high-confidence factory/constructor naming consistency for equivalent creation APIs
+    - [ ] Constrained findings to \`build*\`, \`create*\`, \`make*\`, and \`new*\` naming variants with clearly equivalent intent
+    - [ ] Documented each finding with locations, inconsistent term set, canonical proposal, and migration strategy
+    - [ ] Chose incremental or one-shot migration strategy for each canonical proposal
+    - [ ] Avoided speculative broad renames
+    - [ ] Avoided artifact-list ordering/shape checks and broad terminology drift
+    - [ ] Proposed ideas for naming consistency improvements identified
+  `;
+}
+function primitiveObsession() {
+  return dedent`
+    # Primitive Obsession
+
+    Review high-confidence primitive obsession where call sites use free-form literals instead of canonical domain representations.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus only on two high-confidence slices:
+    - Existing-type drift for domain string concepts
+    - Numeric magic values where naming/domain wrappers would improve clarity
+
+    Existing-type drift scope:
+    - Call sites using free-form string literals where a canonical domain type already exists
+    - Cases where the existing domain type is bypassed (for example artifact directory names that should use \`ArtifactType\`)
+    - High-confidence matches where intent is clear and the existing type is directly applicable
+
+    Numeric magic value scope:
+    - Thresholds, limits, retries, and timing values whose domain meaning is clear at call sites
+    - High-confidence literals that would be clearer as named constants or existing domain wrappers
+    - Examples: retry counts like \`3\`, timeout values like \`30_000\`, batch limits like \`100\`
+
+    Out of scope:
+    - Proposing entirely new domain types in this slice
+    - Ambiguous literals where no canonical existing type or constant naming opportunity can be identified with high confidence
+    - Obvious local loop indices/counters and trivial literals like \`0\` or \`1\` where no domain meaning exists
+
+    ## Analysis Steps
+
+    1. Identify domain string concepts with existing canonical types (enums, unions, branded strings, or shared constants)
+    2. Search for free-form string literals that represent those same concepts at call sites
+    3. Identify numeric literals used as thresholds, limits, retries, or timing values where domain meaning is clear
+    4. Keep only high-confidence findings (exclude ambiguous values and obvious local indices/counters)
+    5. Group duplicate call-site drift by concept to avoid repetitive findings
+    6. Preserve Functional Core, Imperative Shell boundaries in recommendations (pure matching/analysis logic separated from IO shell)
+    7. Recommend incremental migrations only; avoid speculative introduction of brand-new types
+
+    ## Output
+
+    For each finding, provide:
+    - **Locations** - File paths and line numbers where primitive literals are used
+    - **Primitive pattern** - The free-form literal pattern currently used (string concept or numeric role)
+    - **Constant/type opportunity** - The canonical existing type or named constant/domain wrapper that should be used instead
+    - **Incremental migration path** - A safe sequence of steps to migrate call sites with minimal risk
+
+    For numeric findings specifically, include:
+    - **Locations** - File paths and line numbers for the numeric literals
+    - **Numeric pattern** - The repeated threshold/limit/retry/timing literal pattern
+    - **Constant/type opportunity** - A named constant or existing domain wrapper to encode intent
+    - **Incremental migration path** - Steps to introduce the constant/wrapper and migrate call sites safely
+
+    ## Principles
+
+    - [Functional Core, Imperative Shell](../principles/functional-core-imperative-shell.md)
+    - [Small Units](../principles/small-units.md)
+    - [Make the Change Easy](../principles/make-the-change-easy.md)
+    - [Naming Matters](../principles/naming-matters.md)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed high-confidence existing-type drift for domain string literals and numeric magic values
+    - [ ] Constrained findings to cases where canonical domain types or clear constant/wrapper opportunities already exist
+    - [ ] Documented each finding with locations, primitive pattern, constant/type opportunity, and incremental migration path
+    - [ ] Documented numeric findings with locations, numeric pattern, constant/type opportunity, and incremental migration path
+    - [ ] Preserved Functional Core, Imperative Shell boundaries in recommendations
+    - [ ] Avoided speculative introduction of entirely new types
+    - [ ] Proposed ideas for primitive obsession improvements identified
+  `;
+}
+function singleResponsibilityViolations() {
+  return dedent`
+    # Single Responsibility Violations
+
+    Review high-confidence single responsibility violations driven by responsibility count at function level.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Focus only on high-confidence function-level findings where one function clearly combines 3+ distinct responsibilities.
+
+    Responsibility examples:
+    - Parsing/validation
+    - Domain decision/execution logic
+    - Side effects or IO coordination
+    - Presentation/formatting/reporting
+    - Cross-module orchestration
+
+    Include both runtime code and test helpers.
+
+    Out of scope:
+    - Module-level layer-mixing findings (future slices)
+    - Collector/orchestrator hotspot findings based on collaborator/parameter load (future slices)
+    - Functions with only one or two responsibilities
+    - Ambiguous style-only concerns without clear responsibility boundaries
+    - Broad rewrite recommendations without clear extraction seams
+
+    ## Analysis Steps
+
+    1. Identify runtime functions and test helpers that appear to mix concerns
+    2. Keep findings only when 3+ distinct responsibilities are clearly present in the same function
+    3. Validate a concrete extraction seam for each responsibility split (no speculative or style-only recommendations)
+    4. Keep recommendations incremental and high-confidence only
+    5. Preserve Functional Core, Imperative Shell boundaries by extracting pure logic from imperative shells where possible
+
+    ## Output
+
+    For each finding, provide:
+    - **Location** - File path and function name where applicable
+    - **Responsibility split** - Distinct responsibilities currently mixed (for example parsing, execution, presentation)
+    - **Severity** - \`high\`, \`medium\`, or \`low\` based on extraction urgency and coupling risk
+    - **Suggested extraction plan** - A small-step plan describing what to extract first, with Functional Core, Imperative Shell boundaries preserved
+
+    ## Principles
+
+    - [Functional Core, Imperative Shell](../principles/functional-core-imperative-shell.md)
+    - [Decoupled Code](../principles/decoupled-code.md)
+    - [Small Units](../principles/small-units.md)
+    - [Make the Change Easy](../principles/make-the-change-easy.md)
+    - [Context-Optimised Code](../principles/context-optimised-code.md)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed high-confidence function-level findings where 3+ distinct responsibilities are combined
+    - [ ] Included runtime code and test helpers in scope
+    - [ ] Documented each finding with location, responsibility split, severity, and suggested extraction plan
+    - [ ] Preserved Functional Core, Imperative Shell boundaries in recommendations
+    - [ ] Kept recommendations high-confidence only with clear concern boundaries
+    - [ ] Proposed ideas for substantial responsibility-splitting work identified
+  `;
+}
 function ubiquitousLanguage() {
   return dedent`
     # Ubiquitous Language
@@ -911,10 +1109,13 @@ var stockAuditFunctions = {
   "global-state": globalState,
   "ideas-from-commits": ideasFromCommits,
   "ideas-from-principles": ideasFromPrinciples,
+  "naming-consistency": namingConsistency,
   "performance-review": performanceReview,
+  "primitive-obsession": primitiveObsession,
   "refactoring-opportunities": refactoringOpportunities,
   "repository-context": repositoryContext,
   "security-review": securityReview,
+  "single-responsibility-violations": singleResponsibilityViolations,
   "slow-tests": slowTests,
   "stale-ideas": staleIdeas,
   "test-coverage": testCoverage,

package/dist/bucket/command-events-proxy.d.ts

@@ -0,0 +1,29 @@
+import type { CommandEventMessage } from '../command-events';
+import type { ToolDefinition } from './server-messages';
+export interface CommandEventsProxy {
+    port: number;
+    stop: () => Promise<void>;
+}
+export interface ToolExecutionRequest {
+    toolName: string;
+    arguments: string[];
+    repositoryId: string;
+}
+export type ToolExecutionStatus = 'success' | 'tool-not-found' | 'error';
+export interface ToolExecutionResult {
+    status: ToolExecutionStatus;
+    output?: string;
+    error?: string;
+}
+interface CommandEventsProxyHandlers {
+    forwardEvent: (event: CommandEventMessage) => void;
+    getTools: () => ToolDefinition[];
+    forwardToolExecution: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
+}
+export declare function isCommandEventMessage(payload: unknown): payload is CommandEventMessage;
+/**
+ * Start a local HTTP proxy that accepts command events on POST /events.
+ * Accepted payloads are forwarded to the bucket WebSocket channel.
+ */
+export declare function startCommandEventsProxy(handlers: CommandEventsProxyHandlers): Promise<CommandEventsProxy>;
+export {};

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

@@ -4,7 +4,7 @@
  * Manages the async loop that picks tasks and runs Claude sessions
  * for a single repository.
  */
-import type { AgentSessionEvent, EventMessage } from '../agent-events';
+import type { EventMessage } from '../agent-events';
 import { type run as claudeRun, type RunnerDependencies } from '../claude/run';
 import type { OutputSink } from '../claude/types';
 import { type LoopEmitFn, type SendAgentEventFn } from '../cli/commands/loop';
@@ -35,7 +35,7 @@ export declare function buildEventMessage(parameters: {
     sessionId: string;
     repository: string;
     repoId?: number;
-    event: AgentSessionEvent;
+    event: EventMessage['event'];
     agentSessionId?: string;
 }): EventMessage;
 /**

package/dist/bucket/repository.d.ts

@@ -8,6 +8,7 @@ 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 { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
 import { type BucketEmitFn, type SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
 import type { ToolDefinition } from './server-messages';
@@ -53,6 +54,8 @@ export interface RepositoryDependencies {
     dockerDeps?: Partial<DockerDependencies>;
     /** Function to get current tool definitions */
     getTools?: () => ToolDefinition[];
+    /** Forward tool execution requests to the bucket server */
+    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
 }
 /**
  * Start (or restart) the per-repository loop and keep loopPromise state accurate.

package/dist/claude/spawn-claude-code.d.ts

@@ -1,9 +1,8 @@
-import { spawn as nodeSpawn } from 'node:child_process';
-import { createInterface as nodeCreateInterface } from 'node:readline';
+import type { CreateReadlineForEvents, SpawnForEvents } from '../process/spawn-contract';
 import type { DockerSpawnConfig, RawEvent, SpawnOptions } from './types';
 export interface EventSourceDependencies {
-    spawn: typeof nodeSpawn;
-    createInterface: typeof nodeCreateInterface;
+    spawn: SpawnForEvents;
+    createInterface: CreateReadlineForEvents;
 }
 export declare const defaultDependencies: EventSourceDependencies;
 /**

package/dist/cli/commands/loop.d.ts

@@ -109,6 +109,8 @@ interface IterationOptions {
     docker?: DockerSpawnConfig;
     /** Pre-formatted tools section to inject into the prompt */
     toolsSection?: string;
+    /** Port of the command events proxy for this iteration */
+    proxyPort?: number;
 }
 export declare function runOneIteration(dependencies: CommandDependencies, loopDependencies: LoopDependencies, onLoopEvent: LoopEmitFn, onAgentEvent?: SendAgentEventFn, options?: IterationOptions): Promise<IterationResult>;
 export declare function parseMaxIterations(commandArguments: string[]): number;

package/dist/codex/spawn-codex.d.ts

@@ -1,9 +1,8 @@
-import { spawn as nodeSpawn } from 'node:child_process';
-import { createInterface as nodeCreateInterface } from 'node:readline';
 import type { RawEvent, SpawnOptions } from '../claude/types';
+import type { CreateReadlineForEvents, SpawnForEvents } from '../process/spawn-contract';
 export interface EventSourceDependencies {
-    spawn: typeof nodeSpawn;
-    createInterface: typeof nodeCreateInterface;
+    spawn: SpawnForEvents;
+    createInterface: CreateReadlineForEvents;
 }
 export declare const defaultDependencies: EventSourceDependencies;
 export declare function spawnCodex(prompt: string, options?: SpawnOptions, dependencies?: EventSourceDependencies): AsyncGenerator<RawEvent>;

package/dist/command-events.d.ts

@@ -1,9 +1,9 @@
 /**
  * Command event types for the dust back channel protocol.
  *
- * These types define structured events emitted by dust commands
- * to a file descriptor specified by DUST_EVENTS_FD. Events are
- * written as newline-delimited JSON using the CommandEventMessage envelope.
+ * These types define structured events emitted by dust commands.
+ * Events are transported via DUST_PROXY_PORT (HTTP POST /events),
+ * using the same envelope.
  */
 /**
  * Events emitted by dust commands.