@joshski/dust 0.1.57 → 0.1.59

package/dist/ideas.js

@@ -0,0 +1,135 @@
+// 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/ideas.ts
+function parseOpenQuestions(content) {
+  const lines = content.split(`
+`);
+  const questions = [];
+  let inOpenQuestions = false;
+  let currentQuestion = null;
+  let currentOption = null;
+  let descriptionLines = [];
+  function flushOption() {
+    if (currentOption) {
+      currentOption.description = descriptionLines.join(`
+`).trim();
+      descriptionLines = [];
+      currentOption = null;
+    }
+  }
+  function flushQuestion() {
+    flushOption();
+    if (currentQuestion) {
+      questions.push(currentQuestion);
+      currentQuestion = null;
+    }
+  }
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      if (inOpenQuestions) {
+        flushQuestion();
+      }
+      inOpenQuestions = line.trimEnd() === "## Open Questions";
+      continue;
+    }
+    if (!inOpenQuestions)
+      continue;
+    if (line.startsWith("### ")) {
+      flushQuestion();
+      currentQuestion = {
+        question: line.slice(4).trim(),
+        options: []
+      };
+      continue;
+    }
+    if (line.startsWith("#### ")) {
+      flushOption();
+      currentOption = {
+        name: line.slice(5).trim(),
+        description: ""
+      };
+      if (currentQuestion) {
+        currentQuestion.options.push(currentOption);
+      }
+      continue;
+    }
+    if (currentOption) {
+      descriptionLines.push(line);
+    }
+  }
+  flushQuestion();
+  return questions;
+}
+async function parseIdea(fileSystem, dustPath, slug) {
+  const ideaPath = `${dustPath}/ideas/${slug}.md`;
+  if (!fileSystem.exists(ideaPath)) {
+    throw new Error(`Idea not found: "${slug}" (expected file at ${ideaPath})`);
+  }
+  const content = await fileSystem.readFile(ideaPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Idea file has no title: ${ideaPath}`);
+  }
+  const openingSentence = extractOpeningSentence(content);
+  const openQuestions = parseOpenQuestions(content);
+  return {
+    slug,
+    title,
+    openingSentence,
+    content,
+    openQuestions
+  };
+}
+export {
+  parseOpenQuestions,
+  parseIdea
+};

package/dist/logging/index.d.ts

@@ -28,34 +28,53 @@
  * structure under `lib/`. For example, `lib/bucket/repository-loop.ts` uses
  * the logger name `dust.bucket.repository-loop`.
  *
+ * ## Per-logger file routing
+ *
+ * `createLogger(name, { file })` accepts an optional `file` override:
+ * - `file: "path/to/file.log"` — route this logger to a dedicated file instead
+ *   of the global sink set by `enableFileLogs`. The path is resolved relative to
+ *   the log directory.
+ * - `file: false` — suppress file output for this logger entirely, even if
+ *   `enableFileLogs` has been called. Stdout behavior (DEBUG matching) is
+ *   unchanged.
+ * - When `file` is omitted, the logger uses the global file sink (if any).
+ *
+ * Sink selection precedence: per-logger sink → global sink → no file sink.
+ * File sinks are cached by path so multiple loggers targeting the same file
+ * share one sink instance.
+ *
  * No external dependencies.
  */
 import { type LogSink } from './sink';
 export type LogFn = (...messages: unknown[]) => void;
+export interface LoggerOptions {
+    /**
+     * Per-logger file routing override.
+     * - `string` — path to a dedicated log file (e.g. `"./log/custom.log"`)
+     * - `false` — suppress file output for this logger
+     * - `undefined` — use the global file sink from `enableFileLogs` (default)
+     */
+    file?: string | false;
+}
+export interface LoggingService {
+    enableFileLogs(scope: string, sinkForTesting?: LogSink): void;
+    createLogger(name: string, options?: LoggerOptions): LogFn;
+    isEnabled(name: string): boolean;
+}
 /**
- * Activate file logging for this command. Determines the log path as follows:
- * - If DUST_LOG_FILE is already set (inherited from a parent process such as
- *   `dust check`), use that path — all scopes land in the same file.
- * - Otherwise compute the path using DUST_LOG_DIR (if set) or `<cwd>/log`, set
- *   DUST_LOG_FILE so that any child processes inherit the same destination, then write there.
- *
- * Pass a LogSink as the second argument to override for testing.
+ * Create an isolated logging service instance. All mutable state is
+ * encapsulated inside the returned object.
  */
-export declare function enableFileLogs(scope: string, _sinkForTesting?: LogSink): void;
+export declare function createLoggingService(): LoggingService;
 /**
- * Create a named logger function. The returned function writes to:
- * - The active file sink (if `enableFileLogs` was called), always, no filtering.
- * - `process.stdout` if DEBUG is set and `name` matches the pattern.
- *
- * @param name - Logger name, e.g. `dust.bucket.loop`
+ * Activate file logging for this command. See {@link LoggingService.enableFileLogs}.
  */
-export declare function createLogger(name: string): LogFn;
+export declare const enableFileLogs: LoggingService['enableFileLogs'];
 /**
- * Check whether a logger name would produce stdout output under the current DEBUG value.
+ * Create a named logger function. See {@link LoggingService.createLogger}.
  */
-export declare function isEnabled(name: string): boolean;
+export declare const createLogger: LoggingService['createLogger'];
 /**
- * Reset internal state (for testing only).
- * Clears DUST_LOG_FILE only if this module set it (not if it was inherited).
+ * Check whether a logger name would produce stdout output under the current DEBUG value.
  */
-export declare function _reset(): void;
+export declare const isEnabled: LoggingService['isEnabled'];

package/dist/logging.js

@@ -60,55 +60,71 @@ class FileSink {
 
 // lib/logging/index.ts
 var DUST_LOG_FILE = "DUST_LOG_FILE";
-var patterns = null;
-var initialized = false;
-var activeFileSink = null;
-var ownedDustLogFile = false;
-function init() {
-  if (initialized)
-    return;
-  initialized = true;
-  const parsed = parsePatterns(process.env.DEBUG);
-  patterns = parsed.length > 0 ? parsed : null;
-}
-function enableFileLogs(scope, _sinkForTesting) {
-  const existing = process.env[DUST_LOG_FILE];
-  const logDir = process.env.DUST_LOG_DIR ?? join(process.cwd(), "log");
-  const path = existing ?? join(logDir, `${scope}.log`);
-  if (!existing) {
-    process.env[DUST_LOG_FILE] = path;
-    ownedDustLogFile = true;
+function createLoggingService() {
+  let patterns = null;
+  let initialized = false;
+  let activeFileSink = null;
+  const fileSinkCache = new Map;
+  function init() {
+    if (initialized)
+      return;
+    initialized = true;
+    const parsed = parsePatterns(process.env.DEBUG);
+    patterns = parsed.length > 0 ? parsed : null;
   }
-  activeFileSink = _sinkForTesting ?? new FileSink(path);
-}
-function createLogger(name) {
-  return (...messages) => {
-    init();
-    const line = formatLine(name, messages);
-    if (activeFileSink) {
-      activeFileSink.write(line);
+  function getOrCreateFileSink(path) {
+    let sink = fileSinkCache.get(path);
+    if (!sink) {
+      sink = new FileSink(path);
+      fileSinkCache.set(path, sink);
     }
-    if (patterns && matchesAny(name, patterns)) {
-      process.stdout.write(line);
+    return sink;
+  }
+  return {
+    enableFileLogs(scope, sinkForTesting) {
+      const existing = process.env[DUST_LOG_FILE];
+      const logDir = process.env.DUST_LOG_DIR ?? join(process.cwd(), "log");
+      const path = existing ?? join(logDir, `${scope}.log`);
+      if (!existing) {
+        process.env[DUST_LOG_FILE] = path;
+      }
+      activeFileSink = sinkForTesting ?? new FileSink(path);
+    },
+    createLogger(name, options) {
+      let perLoggerSink;
+      if (options?.file === false) {
+        perLoggerSink = null;
+      } else if (typeof options?.file === "string") {
+        perLoggerSink = getOrCreateFileSink(options.file);
+      }
+      return (...messages) => {
+        init();
+        const line = formatLine(name, messages);
+        if (perLoggerSink !== undefined) {
+          if (perLoggerSink !== null) {
+            perLoggerSink.write(line);
+          }
+        } else if (activeFileSink) {
+          activeFileSink.write(line);
+        }
+        if (patterns && matchesAny(name, patterns)) {
+          process.stdout.write(line);
+        }
+      };
+    },
+    isEnabled(name) {
+      init();
+      return patterns !== null && matchesAny(name, patterns);
     }
   };
 }
-function isEnabled(name) {
-  init();
-  return patterns !== null && matchesAny(name, patterns);
-}
-function _reset() {
-  initialized = false;
-  patterns = null;
-  activeFileSink = null;
-  if (ownedDustLogFile) {
-    delete process.env[DUST_LOG_FILE];
-    ownedDustLogFile = false;
-  }
-}
+var defaultService = createLoggingService();
+var enableFileLogs = defaultService.enableFileLogs.bind(defaultService);
+var createLogger = defaultService.createLogger.bind(defaultService);
+var isEnabled = defaultService.isEnabled.bind(defaultService);
 export {
   isEnabled,
   enableFileLogs,
-  createLogger,
-  _reset
+  createLoggingService,
+  createLogger
 };

package/dist/workflow-tasks.js

@@ -86,7 +86,7 @@ ${renderResolvedQuestions(options.resolvedQuestions)}
 
 ${openingSentence}
 ${descriptionParagraph}${resolvedSection}
-## Goals
+## Principles
 
 (none)
 
@@ -111,7 +111,7 @@ async function createIdeaTask(fileSystem, dustPath, prefix, ideaSlug, openingSen
   return { filePath };
 }
 async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description) {
-  return createIdeaTask(fileSystem, dustPath, "Refine Idea: ", ideaSlug, (ideaTitle) => `Thoroughly research this idea and refine it into a well-defined proposal. Read the idea file, explore the codebase for relevant context, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. Review \`.dust/goals/\` for alignment and \`.dust/facts/\` for relevant design decisions. See [${ideaTitle}](../ideas/${ideaSlug}.md). 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.`, [
+  return createIdeaTask(fileSystem, dustPath, "Refine Idea: ", ideaSlug, (ideaTitle) => `Thoroughly research this idea and refine it into a well-defined proposal. Read the idea file, explore the codebase for relevant context, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. Review \`.dust/principles/\` for alignment and \`.dust/facts/\` for relevant design decisions. See [${ideaTitle}](../ideas/${ideaSlug}.md). 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.`, [
     "Idea is thoroughly researched with relevant codebase context",
     "Open questions are added for any ambiguous or underspecified aspects",
     "Open questions follow the required heading format and focus on high-value decisions",
@@ -119,9 +119,9 @@ async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description)
   ], { 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/goals/\` to link relevant goals and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
+  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 Goals section links to relevant goals from .dust/goals/",
+    "Task's Principles section links to relevant principles from .dust/principles/",
     "The original idea is deleted or updated to reflect remaining scope"
   ], {
     description: options.description,
@@ -145,13 +145,13 @@ 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/goals/\` and \`.dust/facts/\` for relevant context. Each task should deliver a thin but complete vertical slice of working software.
+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.
 
 ## Idea Description
 
 ${description}
 
-## Goals
+## Principles
 
 (none)
 
@@ -162,7 +162,7 @@ ${description}
 ## Definition of Done
 
 - [ ] One or more new tasks are created in \`.dust/tasks/\`
-- [ ] Tasks link to relevant goals from \`.dust/goals/\`
+- [ ] Tasks link to relevant principles from \`.dust/principles/\`
 - [ ] Tasks are narrowly scoped vertical slices
 `;
     await fileSystem.writeFile(filePath2, content2);
@@ -175,13 +175,13 @@ ${description}
   const ideaPath = `.dust/ideas/${ideaFilename}`;
   const content = `# ${taskTitle}
 
-Research this idea thoroughly, then create an idea file at \`${ideaPath}\`. 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. Review \`.dust/goals/\` and \`.dust/facts/\` for relevant context.
+Research this idea thoroughly, then create an idea file at \`${ideaPath}\`. 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. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context.
 
 ## Idea Description
 
 ${description}
 
-## Goals
+## Principles
 
 (none)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
@@ -22,6 +22,10 @@
       "import": "./dist/agents.js",
       "types": "./dist/agents/detection.d.ts"
     },
+    "./ideas": {
+      "import": "./dist/ideas.js",
+      "types": "./dist/ideas.d.ts"
+    },
     "./istanbul/minimal-reporter": "./lib/istanbul/minimal-reporter.cjs"
   },
   "files": [
@@ -42,7 +46,7 @@
   "author": "joshski",
   "license": "MIT",
   "scripts": {
-    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && bun build lib/workflow-tasks.ts --target node --outfile dist/workflow-tasks.js && bun build lib/logging/index.ts --target node --outfile dist/logging.js && bun build lib/agents/detection.ts --target node --outfile dist/agents.js && bunx tsc --project tsconfig.build.json",
+    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && bun build lib/workflow-tasks.ts --target node --outfile dist/workflow-tasks.js && bun build lib/logging/index.ts --target node --outfile dist/logging.js && bun build lib/agents/detection.ts --target node --outfile dist/agents.js && bun build lib/ideas.ts --target node --outfile dist/ideas.js && bunx tsc --project tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "eval": "bun run ./evals/run.ts"