@joshski/dust 0.1.93 → 0.1.95

package/dist/env-config.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Centralized environment configuration.
+ *
+ * Reads all environment variables once at startup and provides typed access.
+ * Following the "Functional Core, Imperative Shell" principle: the shell reads
+ * process.env once, then the functional core receives typed configuration.
+ */
+/**
+ * Logging-related environment configuration.
+ * - DEBUG: Pattern for stdout debug logging (comma-separated wildcards)
+ * - DUST_LOG_DIR: Override default log directory location
+ * - DUST_LOG_FILE: Inherited log file path for child processes
+ */
+export interface LoggingConfig {
+    debug: string | undefined;
+    logDir: string | undefined;
+    logFile: string | undefined;
+}
+/**
+ * Dustbucket connection configuration.
+ * - DUST_BUCKET_HOST: Override dustbucket host for auth
+ * - DUST_BUCKET_TOKEN: Authentication token (takes precedence over stored credential)
+ * - DUST_BUCKET_AGENT_CONNECT_URL: Override WebSocket URL
+ */
+export interface BucketConfig {
+    host: string | undefined;
+    token: string | undefined;
+    agentConnectUrl: string | undefined;
+}
+/**
+ * Session-related configuration for dust commands.
+ * - DUST_PROXY_PORT: Proxy server port
+ * - DUST_UNATTENDED: Whether running in unattended mode
+ * - DUST_SKIP_AGENT: Skip agent startup
+ * - DUST_REPOSITORY_ID: Repository identifier for bucket operations
+ * - DUST_REPOS_DIR: Override default repositories directory
+ */
+export interface SessionConfig {
+    proxyPort: string | undefined;
+    unattended: string | undefined;
+    skipAgent: string | undefined;
+    repositoryId: string | undefined;
+    reposDir: string | undefined;
+}
+/**
+ * Runtime environment detection.
+ * - BUN_INSTALL: Whether Bun package manager is available
+ * - DUST_EVENTS_URL: Override events posting URL
+ */
+export interface RuntimeConfig {
+    bunInstall: string | undefined;
+    eventsUrl: string | undefined;
+}
+/**
+ * Agent detection environment variables.
+ * - CLAUDECODE: Claude Code is running
+ * - CLAUDE_CODE_REMOTE: Claude Code Web is running
+ * - CODEX_HOME: Codex home directory
+ * - CODEX_CI: Codex CI mode
+ */
+export interface AgentDetectionConfig {
+    claudeCode: string | undefined;
+    claudeCodeRemote: string | undefined;
+    codexHome: string | undefined;
+    codexCi: string | undefined;
+}
+/**
+ * Authentication tokens.
+ * - CLAUDE_CODE_OAUTH_TOKEN: OAuth token for Claude Code
+ * - OPENAI_API_KEY: OpenAI API key for Codex
+ */
+export interface AuthConfig {
+    claudeCodeOauthToken: string | undefined;
+    openaiApiKey: string | undefined;
+}
+/**
+ * Testing-related configuration.
+ * - CLAUDE_CODE_VCR_MODE: VCR recording mode ('record' or 'replay')
+ */
+export interface TestingConfig {
+    vcrMode: string | undefined;
+}
+/**
+ * Complete environment configuration.
+ * Captures all environment variables used by dust, organized by subsystem.
+ */
+export interface EnvConfig {
+    logging: LoggingConfig;
+    bucket: BucketConfig;
+    session: SessionConfig;
+    runtime: RuntimeConfig;
+    agentDetection: AgentDetectionConfig;
+    auth: AuthConfig;
+    testing: TestingConfig;
+}
+/**
+ * Read and validate all environment variables once.
+ * This function should be called once at startup in the imperative shell.
+ *
+ * @param env - The environment variables object (typically process.env)
+ * @returns Typed environment configuration
+ */
+export declare function readEnvConfig(env: Record<string, string | undefined>): EnvConfig;

package/dist/logging/index.d.ts

@@ -45,6 +45,7 @@
  *
  * No external dependencies.
  */
+import type { LoggingConfig } from '../env-config';
 import { type LogSink } from './sink';
 export type LogFn = (...messages: unknown[]) => void;
 export interface LoggerOptions {
@@ -66,9 +67,27 @@ export interface LoggingService {
  * encapsulated inside the returned object.
  */
 export interface LoggingServiceOptions {
+    /**
+     * Logging configuration from environment.
+     * Required - callers must pass configuration explicitly.
+     */
+    config: LoggingConfig;
+    /**
+     * Custom stdout writer (defaults to process.stdout.write).
+     */
     stdout?: (line: string) => boolean;
+    /**
+     * Current working directory for default log path resolution.
+     * Defaults to process.cwd().
+     */
+    cwd?: () => string;
+    /**
+     * Function to set DUST_LOG_FILE for child process inheritance.
+     * Defaults to setting process.env[DUST_LOG_FILE].
+     */
+    setLogFileEnv?: (path: string) => void;
 }
-export declare function createLoggingService(options?: LoggingServiceOptions): LoggingService;
+export declare function createLoggingService(options: LoggingServiceOptions): LoggingService;
 /**
  * Activate file logging for this command. See {@link LoggingService.enableFileLogs}.
  */

package/dist/logging.js

@@ -61,7 +61,10 @@ class FileSink {
 // lib/logging/index.ts
 var DUST_LOG_FILE = "DUST_LOG_FILE";
 function createLoggingService(options) {
-  const writeStdout = options?.stdout ?? process.stdout.write.bind(process.stdout);
+  const { config } = options;
+  const writeStdout = options.stdout ?? process.stdout.write.bind(process.stdout);
+  const getCwd = options.cwd ?? (() => process.cwd());
+  const setLogFileEnv = options.setLogFileEnv ?? ((path) => process.env[DUST_LOG_FILE] = path);
   let patterns = null;
   let initialized = false;
   let activeFileSink = null;
@@ -70,7 +73,7 @@ function createLoggingService(options) {
     if (initialized)
       return;
     initialized = true;
-    const parsed = parsePatterns(process.env.DEBUG);
+    const parsed = parsePatterns(config.debug);
     patterns = parsed.length > 0 ? parsed : null;
   }
   function getOrCreateFileSink(path) {
@@ -83,20 +86,20 @@ function createLoggingService(options) {
   }
   return {
     enableFileLogs(scope, sinkForTesting) {
-      const existing = process.env[DUST_LOG_FILE];
-      const logDir = process.env.DUST_LOG_DIR ?? join(process.cwd(), "log");
+      const existing = config.logFile;
+      const logDir = config.logDir ?? join(getCwd(), "log");
       const path = existing ?? join(logDir, `${scope}.log`);
       if (!existing) {
-        process.env[DUST_LOG_FILE] = path;
+        setLogFileEnv(path);
       }
       activeFileSink = sinkForTesting ?? new FileSink(path);
     },
-    createLogger(name, options2) {
+    createLogger(name, loggerOptions) {
       let perLoggerSink;
-      if (options2?.file === false) {
+      if (loggerOptions?.file === false) {
         perLoggerSink = null;
-      } else if (typeof options2?.file === "string") {
-        perLoggerSink = getOrCreateFileSink(options2.file);
+      } else if (typeof loggerOptions?.file === "string") {
+        perLoggerSink = getOrCreateFileSink(loggerOptions.file);
       }
       return (...messages) => {
         init();
@@ -119,7 +122,13 @@ function createLoggingService(options) {
     }
   };
 }
-var defaultService = createLoggingService();
+var defaultService = createLoggingService({
+  config: {
+    debug: process.env.DEBUG,
+    logDir: process.env.DUST_LOG_DIR,
+    logFile: process.env.DUST_LOG_FILE
+  }
+});
 var enableFileLogs = defaultService.enableFileLogs.bind(defaultService);
 var createLogger = defaultService.createLogger.bind(defaultService);
 var isEnabled = defaultService.isEnabled.bind(defaultService);

package/dist/loop/events.d.ts

@@ -0,0 +1,52 @@
+export interface LoopWarningEvent {
+    type: 'loop.warning';
+}
+export interface LoopStartedEvent {
+    type: 'loop.started';
+    maxIterations: number;
+    agentType?: string;
+}
+export interface LoopSyncingEvent {
+    type: 'loop.syncing';
+}
+export interface LoopSyncSkippedEvent {
+    type: 'loop.sync_skipped';
+    reason: string;
+}
+export interface LoopCheckingTasksEvent {
+    type: 'loop.checking_tasks';
+}
+export interface LoopNoTasksEvent {
+    type: 'loop.no_tasks';
+}
+export interface LoopTasksFoundEvent {
+    type: 'loop.tasks_found';
+}
+export interface LoopIterationCompleteEvent {
+    type: 'loop.iteration_complete';
+    iteration: number;
+    maxIterations: number;
+}
+export interface LoopEndedEvent {
+    type: 'loop.ended';
+    maxIterations: number;
+}
+export interface LoopDockerDetectedEvent {
+    type: 'loop.docker_detected';
+    imageTag: string;
+}
+export interface LoopDockerBuildingEvent {
+    type: 'loop.docker_building';
+    imageTag: string;
+}
+export interface LoopDockerBuiltEvent {
+    type: 'loop.docker_built';
+    imageTag: string;
+}
+export interface LoopDockerErrorEvent {
+    type: 'loop.docker_error';
+    error: string;
+}
+export type LoopEvent = LoopWarningEvent | LoopStartedEvent | LoopSyncingEvent | LoopSyncSkippedEvent | LoopCheckingTasksEvent | LoopNoTasksEvent | LoopTasksFoundEvent | LoopIterationCompleteEvent | LoopEndedEvent | LoopDockerDetectedEvent | LoopDockerBuildingEvent | LoopDockerBuiltEvent | LoopDockerErrorEvent;
+export type LoopEmitFn = (event: LoopEvent) => void;
+export declare function formatLoopEvent(event: LoopEvent): string | null;

package/dist/loop/git-pull.d.ts

@@ -0,0 +1,9 @@
+import type { spawn as nodeSpawn } from 'node:child_process';
+type GitPullResult = {
+    success: true;
+} | {
+    success: false;
+    message: string;
+};
+export declare function gitPull(cwd: string, spawn: typeof nodeSpawn): Promise<GitPullResult>;
+export {};

package/dist/loop/iteration.d.ts

@@ -0,0 +1,42 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { run as claudeRun } from '../claude/run';
+import type { DockerSpawnConfig } from '../claude/types';
+import type { DockerDependencies } from '../docker/docker-agent';
+import { type SessionConfig } from '../env-config';
+import type { CommandDependencies } from '../cli/types';
+import { type InvalidTask, type UnblockedTask } from '../cli/commands/next';
+import type { LoopEmitFn } from './events';
+import type { PostEventFn, SendAgentEventFn } from './wire-events';
+export interface LoopDependencies {
+    spawn: typeof nodeSpawn;
+    run: typeof claudeRun;
+    sleep: (ms: number) => Promise<void>;
+    postEvent: PostEventFn;
+    session: SessionConfig;
+    agentType?: string;
+    fetch?: typeof fetch;
+    /** Optional overrides for Docker dependency functions (for testing) */
+    dockerDeps?: Partial<DockerDependencies>;
+}
+export declare function createDefaultDependencies(): LoopDependencies;
+type IterationResult = 'no_tasks' | 'ran_claude' | 'claude_error' | 'resolved_pull_conflict';
+type LogFn = (message: string) => void;
+export interface IterationOptions {
+    onRawEvent?: (rawEvent: Record<string, unknown>) => void;
+    hooksInstalled?: boolean;
+    signal?: AbortSignal;
+    logger?: LogFn;
+    repositoryId?: string;
+    /** Docker spawn config when running in Docker mode */
+    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 findAvailableTasks(dependencies: CommandDependencies): Promise<{
+    tasks: UnblockedTask[];
+    invalidTasks: InvalidTask[];
+}>;
+export declare function runOneIteration(dependencies: CommandDependencies, loopDependencies: LoopDependencies, onLoopEvent: LoopEmitFn, onAgentEvent?: SendAgentEventFn, options?: IterationOptions): Promise<IterationResult>;
+export {};

package/dist/loop/wire-events.d.ts

@@ -0,0 +1,5 @@
+import type { AgentSessionEvent, EventMessage } from '../agent-events';
+export type PostEventFn = (url: string, payload: EventMessage) => Promise<void>;
+export type SendAgentEventFn = (event: AgentSessionEvent) => void;
+export declare function createPostEvent(fetchFn: typeof fetch): PostEventFn;
+export declare function createWireEventSender(eventsUrl: string | undefined, sessionId: string, postEvent: PostEventFn, onError: (error: unknown) => void, getAgentSessionId?: () => string | undefined, repository?: string): SendAgentEventFn;

package/dist/proxy/claude-api-proxy.d.ts

@@ -51,6 +51,34 @@ export interface ClaudeApiProxyServer {
     port: number;
     stop: () => void;
 }
+export interface ProxyRequestConfig {
+    url: string;
+    headers: Record<string, string>;
+}
+export declare function mergeAnthropicBetaHeader(incomingHeader: string | string[] | undefined): string;
+/**
+ * Build the proxy request configuration for forwarding to the Anthropic API.
+ * Returns the upstream URL and headers with the token injected.
+ */
+export declare function buildProxyRequest(pathname: string, search: string, token: string, incomingHeaders: Record<string, string | string[] | undefined>): ProxyRequestConfig;
+/**
+ * Filter response headers from upstream response for forwarding to the client.
+ * Removes transfer-encoding as we're not chunking.
+ */
+export declare function filterResponseHeaders(upstreamHeaders: Headers): Record<string, string>;
+export interface ErrorResponse {
+    statusCode: number;
+    contentType: string;
+    body: string;
+}
+/**
+ * Build a 401 response for when no OAuth token is available.
+ */
+export declare function buildNoTokenResponse(): ErrorResponse;
+/**
+ * Build a 502 response for when the upstream request fails.
+ */
+export declare function buildUpstreamErrorResponse(error: unknown): ErrorResponse;
 /**
  * Creates a Claude API proxy server.
  * The server accepts HTTP requests and forwards them to the Anthropic API

package/dist/session.d.ts

@@ -1,9 +1,11 @@
+import type { SessionConfig } from './env-config';
 export declare const DUST_UNATTENDED = "DUST_UNATTENDED";
 export declare const DUST_SKIP_AGENT = "DUST_SKIP_AGENT";
 export declare const DUST_REPOSITORY_ID = "DUST_REPOSITORY_ID";
 export declare const DUST_PROXY_PORT = "DUST_PROXY_PORT";
-export declare function isUnattended(env?: Record<string, string | undefined>): boolean;
-export declare function buildUnattendedEnv(options?: {
+export declare function isUnattended(session: SessionConfig): boolean;
+export declare function buildUnattendedEnv(options: {
     repositoryId?: string;
     proxyPort?: number;
+    session: SessionConfig;
 }): Record<string, string>;

package/dist/validation/index.d.ts

@@ -14,6 +14,9 @@ export interface ValidationResult {
     valid: boolean;
     violations: Violation[];
 }
+export interface ValidatePatchOptions {
+    cwd?: string;
+}
 /**
  * Validates a patch of artifact changes against existing .dust/ content.
  *
@@ -21,4 +24,4 @@ export interface ValidationResult {
  * @param dustPath - Absolute path to the .dust directory
  * @param patch - Proposed new/changed files, with paths relative to dustPath
  */
-export declare function validatePatch(fileSystem: ReadableFileSystem, dustPath: string, patch: ArtifactPatch): Promise<ValidationResult>;
+export declare function validatePatch(fileSystem: ReadableFileSystem, dustPath: string, patch: ArtifactPatch, options?: ValidatePatchOptions): Promise<ValidationResult>;

package/dist/validation.js

@@ -1,3 +1,6 @@
+// lib/validation/index.ts
+import { relative } from "node:path";
+
 // lib/markdown/markdown-utilities.ts
 function extractTitle(content) {
   const match = content.match(/^#\s+(.+)$/m);
@@ -161,7 +164,8 @@ async function validateContentDirectoryFiles(dirPath, fileSystem) {
 var IDEA_TRANSITION_PREFIXES = [
   "Refine Idea: ",
   "Decompose Idea: ",
-  "Shelve Idea: "
+  "Shelve Idea: ",
+  "Expedite Idea: "
 ];
 function titleToFilename(title) {
   return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
@@ -201,7 +205,8 @@ function validateTitleFilenameMatch(filePath, content) {
 var WORKFLOW_PREFIX_TO_SECTION = {
   "Refine Idea: ": "Refines Idea",
   "Decompose Idea: ": "Decomposes Idea",
-  "Shelve Idea: ": "Shelves Idea"
+  "Shelve Idea: ": "Shelves Idea",
+  "Expedite Idea: ": "Expedites Idea"
 };
 function validateIdeaOpenQuestions(filePath, content) {
   const violations = [];
@@ -450,24 +455,28 @@ function validateLinks(filePath, content, fileSystem) {
     let match = linkPattern.exec(line);
     while (match) {
       const linkTarget = match[2];
-      if (!linkTarget.startsWith("http://") && !linkTarget.startsWith("https://") && !linkTarget.startsWith("#")) {
-        if (linkTarget.startsWith("/")) {
-          violations.push({
-            file: filePath,
-            message: `Absolute link not allowed: "${linkTarget}" (use a relative path instead)`,
-            line: i + 1
-          });
-        } else {
-          const targetPath = linkTarget.split("#")[0];
-          const resolvedPath = resolve(fileDir, targetPath);
-          if (!fileSystem.exists(resolvedPath)) {
-            violations.push({
-              file: filePath,
-              message: `Broken link: "${linkTarget}"`,
-              line: i + 1
-            });
-          }
-        }
+      const isExternalOrAnchorLink = linkTarget.startsWith("http://") || linkTarget.startsWith("https://") || linkTarget.startsWith("#");
+      if (isExternalOrAnchorLink) {
+        match = linkPattern.exec(line);
+        continue;
+      }
+      if (linkTarget.startsWith("/")) {
+        violations.push({
+          file: filePath,
+          message: `Absolute link not allowed: "${linkTarget}" (use a relative path instead)`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      const targetPath = linkTarget.split("#")[0];
+      const resolvedPath = resolve(fileDir, targetPath);
+      if (!fileSystem.exists(resolvedPath)) {
+        violations.push({
+          file: filePath,
+          message: `Broken link: "${linkTarget}"`,
+          line: i + 1
+        });
       }
       match = linkPattern.exec(line);
     }
@@ -611,16 +620,21 @@ function extractPrincipleRelationships(filePath, content) {
     let match = linkPattern.exec(line);
     while (match) {
       const linkTarget = match[2];
-      if (!linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://")) {
-        const targetPath = linkTarget.split("#")[0];
-        const resolvedPath = resolve2(fileDir, targetPath);
-        if (resolvedPath.includes("/.dust/principles/")) {
-          if (currentSection === "## Parent Principle") {
-            parentPrinciples.push(resolvedPath);
-          } else {
-            subPrinciples.push(resolvedPath);
-          }
-        }
+      const isLocalLink = !linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://");
+      if (!isLocalLink) {
+        match = linkPattern.exec(line);
+        continue;
+      }
+      const targetPath = linkTarget.split("#")[0];
+      const resolvedPath = resolve2(fileDir, targetPath);
+      if (!resolvedPath.includes("/.dust/principles/")) {
+        match = linkPattern.exec(line);
+        continue;
+      }
+      if (currentSection === "## Parent Principle") {
+        parentPrinciples.push(resolvedPath);
+      } else {
+        subPrinciples.push(resolvedPath);
       }
       match = linkPattern.exec(line);
     }
@@ -768,7 +782,7 @@ var ALLOWED_ROOT_PATHS = [
 ].join(", ");
 function validatePatchRootEntries(fileSystem, dustPath, patch) {
   const violations = [];
-  const sortedPaths = Object.keys(patch.files).sort();
+  const sortedPaths = Object.keys(patch.files).toSorted();
   const reportedUnexpectedRootDirectories = new Set;
   for (const relativePath of sortedPaths) {
     const content = patch.files[relativePath];
@@ -798,7 +812,21 @@ function validatePatchRootEntries(fileSystem, dustPath, patch) {
   }
   return violations;
 }
-async function validatePatch(fileSystem, dustPath, patch) {
+function relativizeViolationFilePath(filePath, cwd) {
+  const relativePath = relative(cwd, filePath);
+  if (relativePath === "" || relativePath === "." || relativePath === ".." || relativePath.startsWith("../") || relativePath.startsWith("..\\")) {
+    return filePath;
+  }
+  return relativePath;
+}
+function relativizeViolations(violations, cwd) {
+  return violations.map((violation) => ({
+    ...violation,
+    file: relativizeViolationFilePath(violation.file, cwd)
+  }));
+}
+async function validatePatch(fileSystem, dustPath, patch, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
   const absolutePatchFiles = new Map;
   const deletedPaths = new Set;
   for (const [relativePath, content] of Object.entries(patch.files)) {
@@ -888,7 +916,7 @@ async function validatePatch(fileSystem, dustPath, patch) {
   }
   return {
     valid: violations.length === 0,
-    violations
+    violations: relativizeViolations(violations, cwd)
   };
 }
 export {

package/lib/istanbul/minimal-reporter.cjs

@@ -36,7 +36,7 @@ function getGapLines(fileCoverage) {
     }
   }
 
-  const sorted = [...gapLines].sort((a, b) => a - b)
+  const sorted = [...gapLines].toSorted((x, y) => x - y)
   const ranges = []
   let rangeStart = null
   let rangeEnd = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.93",
+  "version": "0.1.95",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
@@ -74,7 +74,7 @@
     "istanbul-lib-report": "^3.0.1",
     "knip": "^5.60.1",
     "oxfmt": "^0.36.0",
-    "oxlint": "^1.16.0",
+    "oxlint": "^1.51.0",
     "typescript": "^5.8.3",
     "vitest": "^4.0.18"
   }