@joshski/dust 0.1.109 → 0.1.111

package/dist/dust.js

@@ -7,7 +7,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@joshski/dust",
-    version: "0.1.109",
+    version: "0.1.111",
     description: "Flow state for AI coding agents",
     type: "module",
     bin: {
@@ -721,7 +721,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.109";
+var DUST_VERSION = "0.1.111";
 
 // lib/cli/middleware.ts
 function applyMiddleware(middlewares, execute) {
@@ -2895,6 +2895,168 @@ function slowTests() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function overAbstraction() {
+  return dedent`
+    # Over-Abstraction
+
+    Identify violations of the "reasonably-dry" principle where code has been over-engineered with excessive abstraction.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Detect these over-abstraction patterns:
+
+    1. **Single-use abstractions** - Interfaces, base classes, or utility functions used in only one place
+    2. **Deep inheritance hierarchies** - Classes extending more than 2 levels deep
+    3. **Premature generalization** - Parameters always used with the same value, unused options/flags
+    4. **Excessive indirection** - Multiple layers of wrappers adding no value
+
+    ## Analysis Steps
+
+    ### 1. Find Single-Use Abstractions
+
+    Search for abstractions that are only used once:
+
+    1. **Interfaces with one implementation**
+       - Search for \`interface\` declarations
+       - Check if each interface has only one implementing class
+       - Flag interfaces that exist solely for testing (can be replaced with the concrete type)
+
+    2. **Base classes with one subclass**
+       - Search for \`abstract class\` or classes used as base classes
+       - Count implementations extending each base class
+       - Flag base classes with only one subclass
+
+    3. **Utility functions called once**
+       - Search for exported utility functions
+       - Check call sites - if only called from one location, it's over-abstraction
+       - Consider inlining single-use utilities
+
+    4. **Generic types with one concrete usage**
+       - Find generic type parameters: \`<T>\`, \`<TData>\`, etc.
+       - Check if T is always the same type at all call sites
+       - Flag generics that could be concrete types
+
+    ### 2. Detect Deep Inheritance Hierarchies
+
+    Find inheritance chains longer than 2 levels:
+
+    1. Search for \`extends\` keywords in class declarations
+    2. Build inheritance tree for each class
+    3. Flag chains deeper than 2 (A extends B extends C extends D...)
+    4. Respect framework conventions (don't flag React.Component, etc.)
+
+    ### 3. Identify Premature Generalization
+
+    Look for flexibility that's never used:
+
+    1. **Always-same parameter values**
+       - Find function parameters
+       - Check all call sites - if always the same value, it's not needed
+       - Flag parameters that could be constants or removed
+
+    2. **Unused configuration options**
+       - Search for configuration objects/interfaces
+       - Check which options are actually used
+       - Flag options that are never set or always default
+
+    3. **Unused function parameters**
+       - Find parameters that aren't referenced in function bodies
+       - Flag as candidates for removal
+
+    ### 4. Find Excessive Indirection
+
+    Detect wrapper chains that add no value:
+
+    1. **Delegation chains**
+       - Search for functions that only call another function
+       - Flag wrappers that don't add logic, just forward calls
+       - Example: \`function foo(x) { return bar(x) }\`
+
+    2. **Proxy patterns without behavior**
+       - Find classes that wrap another class
+       - Check if wrapper adds any logic beyond forwarding
+       - Flag pure proxies
+
+    3. **Middleware without transformation**
+       - Look for middleware/interceptor patterns
+       - Check if they modify data or just pass through
+       - Flag pass-through middleware
+
+    ## Output Format
+
+    For each over-abstraction found, create an idea file in \`.dust/ideas/\` with:
+
+    \`\`\`markdown
+    # Over-Abstraction: [Type] in [Location]
+
+    ## Type
+
+    [Single-use | Deep hierarchy | Premature generalization | Excessive indirection]
+
+    ## Location
+
+    \`\`\`
+    [file path]:[line number]
+    \`\`\`
+
+    ## Description
+
+    [What the abstraction is]
+
+    ## Problem
+
+    [Why this is over-abstraction - complexity without benefit]
+
+    ## Usage Analysis
+
+    - **Times used**: [count]
+    - **Variation in usage**: [how different are the use cases]
+    - **Complexity cost**: [lines of code, indirection levels, etc.]
+
+    ## Suggested Simplification
+
+    [How to remove or reduce this abstraction]
+
+    ## Impact
+
+    [Lines of code saved, reduced complexity, improved clarity]
+    \`\`\`
+
+    ## Special Considerations
+
+    1. **Framework conventions** - Don't flag patterns mandated by frameworks:
+       - React: Component base classes, hooks patterns
+       - Express: Middleware signatures
+       - Testing: Test base classes, fixture patterns
+
+    2. **Library boundaries** - Public API abstractions may be justified even if internal usage is simple
+
+    3. **Test code** - Apply the same standards to test code as production code
+
+    4. **Context depth thresholds**:
+       - Deep hierarchies (>2 levels) make understanding difficult
+       - Wrapper chains (>2 levels) obscure actual behavior
+       - Generic parameters should have multiple concrete usages
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Searched for single-use interfaces, base classes, and utility functions
+    - Identified deep inheritance hierarchies (>2 levels)
+    - Found parameters always used with the same value
+    - Detected unused configuration options
+    - Located excessive wrapper chains and delegation
+    - Respected framework conventions (didn't flag framework-mandated patterns)
+    - Created idea files for each over-abstraction found
+    - Each idea includes usage analysis and simplification suggestions
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function primitiveObsession() {
   return dedent`
     # Primitive Obsession
@@ -4270,6 +4432,7 @@ var stockAuditFunctions = {
   "idiomatic-style": idiomaticStyle,
   "incidental-test-details": incidentalTestDetails,
   "logging-and-traceability": loggingAndTraceability,
+  "over-abstraction": overAbstraction,
   "primitive-obsession": primitiveObsession,
   "repository-context": repositoryContext,
   "security-review": securityReview,
@@ -5754,6 +5917,8 @@ function buildImplementationInstructions(bin, hooksInstalled, taskTitle, taskPat
     steps.push(`${step}. Run \`${bin} check\` to verify the project is in a good state`);
     step++;
   }
+  steps.push(`${step}. If the task file contains Principles and Guidance sections, read and follow them before implementing changes`);
+  step++;
   steps.push(`${step}. Implement the task`);
   step++;
   if (!hooksInstalled) {
@@ -6081,6 +6246,55 @@ async function findAllWorkflowTasks(fileSystem, dustPath) {
   }
   return { captureIdeaTasks, workflowTasksByIdeaSlug };
 }
+async function findWorkflowTaskForIdea(fileSystem, dustPath, ideaSlug) {
+  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")).toSorted()) {
+    const content = await fileSystem.readFile(`${tasksPath}/${file}`);
+    const taskSlug = file.replace(/\.md$/, "");
+    const match = findWorkflowMatch(content, ideaSlug, taskSlug);
+    if (match) {
+      return match;
+    }
+  }
+  return null;
+}
+function findWorkflowMatch(content, ideaSlug, taskSlug) {
+  const taskType = parseTaskType(content);
+  if (taskType) {
+    const heading = WORKFLOW_SECTION_HEADINGS.find((h) => h.type === taskType)?.heading;
+    if (heading) {
+      const linkedSlug = extractIdeaSlugFromSection(content, heading);
+      if (linkedSlug === ideaSlug) {
+        return {
+          type: taskType,
+          ideaSlug,
+          taskSlug,
+          resolvedQuestions: parseResolvedQuestions(content)
+        };
+      }
+    }
+  }
+  for (const { type, heading } of WORKFLOW_SECTION_HEADINGS) {
+    const linkedSlug = extractIdeaSlugFromSection(content, heading);
+    if (linkedSlug === ideaSlug) {
+      return {
+        type,
+        ideaSlug,
+        taskSlug,
+        resolvedQuestions: parseResolvedQuestions(content)
+      };
+    }
+  }
+  return null;
+}
 function parseResolvedQuestions(content) {
   const lines = content.split(`
 `);
@@ -6121,6 +6335,42 @@ function parseResolvedQuestions(content) {
   }
   return results;
 }
+async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
+  const filePath = `${dustPath}/tasks/${taskSlug}.md`;
+  if (!fileSystem.exists(filePath)) {
+    return null;
+  }
+  const content = await fileSystem.readFile(filePath);
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  if (!titleMatch) {
+    return null;
+  }
+  const title = titleMatch[1].trim();
+  const taskType = parseTaskType(content);
+  let ideaTitle;
+  let expedite;
+  if (taskType === "implement") {
+    expedite = true;
+    ideaTitle = title.startsWith(EXPEDITE_IDEA_PREFIX) ? title.slice(EXPEDITE_IDEA_PREFIX.length) : title;
+  } else if (taskType === "capture") {
+    expedite = false;
+    ideaTitle = title.startsWith(CAPTURE_IDEA_PREFIX) ? title.slice(CAPTURE_IDEA_PREFIX.length) : title;
+  } else if (title.startsWith(EXPEDITE_IDEA_PREFIX)) {
+    ideaTitle = title.slice(EXPEDITE_IDEA_PREFIX.length);
+    expedite = true;
+  } else if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
+    ideaTitle = title.slice(CAPTURE_IDEA_PREFIX.length);
+    expedite = false;
+  } else {
+    return null;
+  }
+  const descriptionMatch = content.match(/^## Idea Description\n\n([\s\S]*?)\n\n## /m);
+  if (!descriptionMatch) {
+    return null;
+  }
+  const ideaDescription = descriptionMatch[1];
+  return { ideaTitle, ideaDescription, expedite };
+}
 
 // lib/lint/validators/content-validator.ts
 var REQUIRED_TASK_HEADINGS = ["Task Type", "Blocked By", "Definition of Done"];
@@ -9261,6 +9511,34 @@ function executeMessageEffects(effects, dependencies) {
   }
 }
 
+// lib/bucket/bucket-dependencies.ts
+function createAuthFileSystem(dependencies) {
+  return {
+    exists: (path3) => {
+      try {
+        dependencies.accessSync(path3);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    isDirectory: (path3) => {
+      try {
+        return dependencies.statSync(path3).isDirectory();
+      } catch {
+        return false;
+      }
+    },
+    getFileCreationTime: (path3) => dependencies.statSync(path3).birthtimeMs,
+    readFile: (path3) => dependencies.readFile(path3, "utf8"),
+    writeFile: (path3, content) => dependencies.writeFile(path3, content, "utf8"),
+    mkdir: (path3, options) => dependencies.mkdir(path3, options).then(() => {}),
+    readdir: dependencies.readdir.bind(dependencies),
+    chmod: dependencies.chmod.bind(dependencies),
+    rename: dependencies.rename.bind(dependencies)
+  };
+}
+
 // lib/bucket/native-io.ts
 import { spawn as nodeSpawn4 } from "node:child_process";
 import { EventEmitter } from "node:events";
@@ -9732,32 +10010,6 @@ function findRepoPathByRepositoryId(repositories, repositoryId) {
   return;
 }
 var DEFAULT_DUSTBUCKET_WS_URL = "wss://dustbucket.com/agent/connect";
-function createAuthFileSystem(dependencies) {
-  return {
-    exists: (path3) => {
-      try {
-        dependencies.accessSync(path3);
-        return true;
-      } catch {
-        return false;
-      }
-    },
-    isDirectory: (path3) => {
-      try {
-        return dependencies.statSync(path3).isDirectory();
-      } catch {
-        return false;
-      }
-    },
-    getFileCreationTime: (path3) => dependencies.statSync(path3).birthtimeMs,
-    readFile: (path3) => dependencies.readFile(path3, "utf8"),
-    writeFile: (path3, content) => dependencies.writeFile(path3, content, "utf8"),
-    mkdir: (path3, options) => dependencies.mkdir(path3, options).then(() => {}),
-    readdir: dependencies.readdir.bind(dependencies),
-    chmod: dependencies.chmod.bind(dependencies),
-    rename: dependencies.rename.bind(dependencies)
-  };
-}
 function createInitialState() {
   const sessionId = crypto.randomUUID();
   const systemBuffer = createLogBuffer();
@@ -10567,6 +10819,273 @@ Run \`dust bucket tool ${toolName}\` to see available operations.`);
 // lib/cli/commands/lint-markdown.ts
 import { isAbsolute, join as join11, relative, sep } from "node:path";
 
+// lib/artifacts/facts.ts
+async function parseFact(fileSystem, dustPath, slug) {
+  const factPath = `${dustPath}/facts/${slug}.md`;
+  if (!fileSystem.exists(factPath)) {
+    throw new Error(`Fact not found: "${slug}" (expected file at ${factPath})`);
+  }
+  const content = await fileSystem.readFile(factPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Fact file has no title: ${factPath}`);
+  }
+  return {
+    slug,
+    title,
+    content
+  };
+}
+
+// lib/artifacts/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;
+    }
+  }
+  let inCodeFence = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      inCodeFence = !inCodeFence;
+      if (currentOption) {
+        descriptionLines.push(line);
+      }
+      continue;
+    }
+    if (inCodeFence) {
+      if (currentOption) {
+        descriptionLines.push(line);
+      }
+      continue;
+    }
+    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
+  };
+}
+
+// lib/artifacts/principles.ts
+function extractLinksFromSection(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const links = [];
+  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) {
+        links.push(slugMatch[1]);
+      }
+    }
+  }
+  return links;
+}
+function extractSingleLinkFromSection(content, sectionHeading) {
+  const links = extractLinksFromSection(content, sectionHeading);
+  return links.length === 1 ? links[0] : null;
+}
+async function parsePrinciple(fileSystem, dustPath, slug) {
+  const principlePath = `${dustPath}/principles/${slug}.md`;
+  if (!fileSystem.exists(principlePath)) {
+    throw new Error(`Principle not found: "${slug}" (expected file at ${principlePath})`);
+  }
+  const content = await fileSystem.readFile(principlePath);
+  const title = extractTitle(content) || slug;
+  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
+  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
+  return {
+    slug,
+    title,
+    content,
+    parentPrinciple,
+    subPrinciples
+  };
+}
+
+// lib/artifacts/tasks.ts
+function extractLinksFromSection2(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const links = [];
+  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) {
+        links.push(slugMatch[1]);
+      }
+    }
+  }
+  return links;
+}
+function extractDefinitionOfDone(content) {
+  const lines = content.split(`
+`);
+  const items = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inSection = line.trimEnd() === "## Definition of Done";
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.startsWith("# "))
+      break;
+    const listMatch = line.match(/^-\s+(.+)$/);
+    if (listMatch) {
+      items.push(listMatch[1].trim());
+    }
+  }
+  return items;
+}
+async function parseTask(fileSystem, dustPath, slug) {
+  const taskPath = `${dustPath}/tasks/${slug}.md`;
+  if (!fileSystem.exists(taskPath)) {
+    throw new Error(`Task not found: "${slug}" (expected file at ${taskPath})`);
+  }
+  const content = await fileSystem.readFile(taskPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Task file has no title: ${taskPath}`);
+  }
+  const principles = extractLinksFromSection2(content, "Principles");
+  const blockedBy = extractLinksFromSection2(content, "Blocked By");
+  const definitionOfDone = extractDefinitionOfDone(content);
+  return {
+    slug,
+    title,
+    content,
+    principles,
+    blockedBy,
+    definitionOfDone
+  };
+}
+
+// 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",
@@ -10574,6 +11093,90 @@ var ARTIFACT_TYPES = [
   "principles",
   "tasks"
 ];
+function buildReadOperations(fileSystem, dustPath) {
+  return {
+    artifactPath(type, slug) {
+      return `${dustPath}/${type}/${slug}.md`;
+    },
+    async parseIdea(options) {
+      return parseIdea(fileSystem, dustPath, options.slug);
+    },
+    async listIdeas() {
+      const ideasPath = `${dustPath}/ideas`;
+      if (!fileSystem.exists(ideasPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(ideasPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).toSorted();
+    },
+    async parsePrinciple(options) {
+      return parsePrinciple(fileSystem, dustPath, options.slug);
+    },
+    async listPrinciples() {
+      const principlesPath = `${dustPath}/principles`;
+      if (!fileSystem.exists(principlesPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(principlesPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).toSorted();
+    },
+    async parseFact(options) {
+      return parseFact(fileSystem, dustPath, options.slug);
+    },
+    async listFacts() {
+      const factsPath = `${dustPath}/facts`;
+      if (!fileSystem.exists(factsPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(factsPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).toSorted();
+    },
+    async parseTask(options) {
+      return parseTask(fileSystem, dustPath, options.slug);
+    },
+    async listTasks() {
+      const tasksPath = `${dustPath}/tasks`;
+      if (!fileSystem.exists(tasksPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(tasksPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).toSorted();
+    },
+    async findWorkflowTaskForIdea(options) {
+      return findWorkflowTaskForIdea(fileSystem, dustPath, options.ideaSlug);
+    },
+    async parseCaptureIdeaTask(options) {
+      return parseCaptureIdeaTask(fileSystem, dustPath, options.taskSlug);
+    },
+    async buildTaskGraph() {
+      const taskSlugs = await this.listTasks();
+      const allWorkflowTasks = await findAllWorkflowTasks(fileSystem, dustPath);
+      const workflowTypeByTaskSlug = new Map;
+      for (const match of allWorkflowTasks.workflowTasksByIdeaSlug.values()) {
+        workflowTypeByTaskSlug.set(match.taskSlug, match.type);
+      }
+      const nodes = [];
+      const edges = [];
+      for (const slug of taskSlugs) {
+        const task = await this.parseTask({ slug });
+        nodes.push({
+          task,
+          workflowType: workflowTypeByTaskSlug.get(slug) ?? null
+        });
+        for (const blockerSlug of task.blockedBy) {
+          edges.push({ from: blockerSlug, to: slug });
+        }
+      }
+      return { nodes, edges };
+    },
+    async getRepositoryPrincipleHierarchy() {
+      return getRepositoryPrincipleHierarchy(this);
+    }
+  };
+}
+function buildReadOnlyArtifactsRepository(fileSystem, dustPath) {
+  return buildReadOperations(fileSystem, dustPath);
+}
 
 // lib/lint/validators/directory-validator.ts
 var EXPECTED_DIRECTORIES = [...ARTIFACT_TYPES, "config"];
@@ -12916,10 +13519,10 @@ Surprising behavior erodes trust and slows people down. Unsurprising behavior le
 ];
 
 // lib/artifacts/core-principles.ts
-function sortNodes(nodes) {
+function sortNodes2(nodes) {
   nodes.sort((a, b) => a.title.localeCompare(b.title));
   for (const node of nodes) {
-    sortNodes(node.children);
+    sortNodes2(node.children);
   }
 }
 function isInternalPrinciple(principleContent) {
@@ -12963,12 +13566,12 @@ function getCorePrincipleTree(allPrinciples, config) {
       nodeBySlug.get(parentSlug).children.push(node);
     }
   }
-  sortNodes(roots);
+  sortNodes2(roots);
   return roots;
 }
 
 // lib/core-principles.ts
-function extractLinksFromSection(content, sectionHeading) {
+function extractLinksFromSection3(content, sectionHeading) {
   const lines = content.split(`
 `);
   const links = [];
@@ -12993,8 +13596,8 @@ function extractLinksFromSection(content, sectionHeading) {
   }
   return links;
 }
-function extractSingleLinkFromSection(content, sectionHeading) {
-  const links = extractLinksFromSection(content, sectionHeading);
+function extractSingleLinkFromSection2(content, sectionHeading) {
+  const links = extractLinksFromSection3(content, sectionHeading);
   return links.length === 1 ? links[0] : null;
 }
 function parsePrincipleContent(slug, content) {
@@ -13002,8 +13605,8 @@ function parsePrincipleContent(slug, content) {
   if (!title) {
     throw new Error(`Principle has no title: ${slug}`);
   }
-  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
-  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
+  const parentPrinciple = extractSingleLinkFromSection2(content, "Parent Principle");
+  const subPrinciples = extractLinksFromSection3(content, "Sub-Principles");
   return {
     slug,
     title,
@@ -13212,7 +13815,6 @@ async function init(dependencies) {
 }
 
 // lib/cli/commands/list.ts
-import { basename as basename3 } from "node:path";
 function workflowTypeToStatus(type) {
   switch (type) {
     case "refine":
@@ -13282,41 +13884,7 @@ function formatPrinciplesSection(header, entries) {
   }
   return lines;
 }
-async function buildPrincipleHierarchy(principlesPath, fileSystem) {
-  const files = await fileSystem.readdir(principlesPath);
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  const relationships = [];
-  const titleMap = new Map;
-  for (const file of mdFiles) {
-    const filePath = `${principlesPath}/${file}`;
-    const content = await fileSystem.readFile(filePath);
-    const artifact = parseArtifact(filePath, content);
-    relationships.push(extractPrincipleRelationships(artifact));
-    const title = extractTitle(content) || basename3(file, ".md");
-    titleMap.set(filePath, title);
-  }
-  const relMap = new Map;
-  for (const rel of relationships) {
-    relMap.set(rel.filePath, rel);
-  }
-  const rootPrinciples = relationships.filter((rel) => rel.parentPrinciples.length === 0);
-  function buildNode(filePath) {
-    const rel = relMap.get(filePath);
-    const children = [];
-    if (rel) {
-      for (const childPath of rel.subPrinciples) {
-        children.push(buildNode(childPath));
-      }
-    }
-    return {
-      filePath,
-      title: titleMap.get(filePath) || basename3(filePath, ".md"),
-      children
-    };
-  }
-  return rootPrinciples.map((rel) => buildNode(rel.filePath));
-}
-function renderHierarchy(nodes, output, prefix = "") {
+function renderRepositoryPrincipleHierarchy(nodes, output, prefix = "") {
   for (let i = 0;i < nodes.length; i++) {
     const node = nodes[i];
     const isLastNode = i === nodes.length - 1;
@@ -13324,7 +13892,7 @@ function renderHierarchy(nodes, output, prefix = "") {
     const childPrefix = isLastNode ? "    " : "│   ";
     output(`${prefix}${connector}${node.title}`);
     if (node.children.length > 0) {
-      renderHierarchy(node.children, output, prefix + childPrefix);
+      renderRepositoryPrincipleHierarchy(node.children, output, prefix + childPrefix);
     }
   }
 }
@@ -13434,9 +14002,10 @@ async function processPrinciplesList(context) {
       stdout("");
     }
     if (hasLocalPrinciples) {
-      const localHierarchy = await buildPrincipleHierarchy(localDirPath, fileSystem);
+      const repository = buildReadOnlyArtifactsRepository(fileSystem, dustPath);
+      const localHierarchy = await repository.getRepositoryPrincipleHierarchy();
       stdout(`${colors.bold}Local${colors.reset}`);
-      renderHierarchy(localHierarchy, (line) => stdout(line));
+      renderRepositoryPrincipleHierarchy(localHierarchy, (line) => stdout(line));
       stdout("");
       const collectedItems = [];
       for (const file of localMdFiles) {