@inixiative/foundry-core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/action-prompt.ts

@@ -65,6 +65,8 @@ export interface PromptOpts {
   urgency?: PromptUrgency;
   /** Auto-expire after this many ms. Resolves as rejected. */
   timeoutMs?: number;
+  /** Withdraws the prompt (the asker no longer needs an answer): it expires, resolved rejected by policy. */
+  signal?: AbortSignal;
   meta?: Record<string, unknown>;
 }
 
@@ -159,24 +161,21 @@ export class ActionQueue {
     // Register the waiter before notifying: a listener may resolve synchronously.
     const settled = new Promise<ActionResolution>((resolve) => {
       let timer: ReturnType<typeof setTimeout> | undefined;
+      const expire = (by: ActionResolution['by']) => {
+        if (prompt.status !== 'pending') return;
+        if (timer) clearTimeout(timer);
+        const resolution: ActionResolution = { by, action: 'rejected', timestamp: Date.now() };
+        prompt.status = 'expired';
+        prompt.resolution = resolution;
+        this._waiters.delete(id);
+        resolve(resolution);
+        this._settled(prompt);
+      };
 
-      if (opts.timeoutMs) {
-        timer = setTimeout(() => {
-          if (prompt.status !== 'pending') return;
-          const resolution: ActionResolution = {
-            by: 'timeout',
-            action: 'rejected',
-            timestamp: Date.now(),
-          };
-          prompt.status = 'expired';
-          prompt.resolution = resolution;
-          this._waiters.delete(id);
-          resolve(resolution);
-          this._settled(prompt);
-        }, opts.timeoutMs);
-      }
-
+      if (opts.timeoutMs) timer = setTimeout(() => expire('timeout'), opts.timeoutMs);
       this._waiters.set(id, { resolve, timer });
+      if (opts.signal?.aborted) queueMicrotask(() => expire('policy'));
+      else opts.signal?.addEventListener('abort', () => expire('policy'), { once: true });
     });
 
     // Notify listeners (viewer badge, event stream, etc.)

package/src/adapters/file-memory.ts

@@ -58,7 +58,6 @@ export const DEFAULT_MEMORY_SELECTION: MemorySelectionPolicy = Object.freeze({
     'pin',
     'pinned',
     'convention',
-    'correction',
     'decision',
     'requirement',
   ]),
@@ -72,6 +71,8 @@ export const DEFAULT_MEMORY_SELECTION: MemorySelectionPolicy = Object.freeze({
     'domain_learning',
     'tool_observation',
     'guard_finding',
+    // Captured feedback; acting on it is an explicit resolution (docs/FEEDBACK-LOOP.md).
+    'correction',
   ]),
   recentLimit: 8,
   maxEntryChars: 1200,
@@ -305,7 +306,7 @@ export function selectMemory(
   };
   const withExcerpt = (x: Excerpt) => (x.truncated ? { truncated: true, ranges: x.ranges } : {});
 
-  // 1. Pinned: explicit instructions, conventions, corrections, decisions. Injected in full, never
+  // 1. Pinned: explicit instructions, conventions, decisions. Injected in full, never
   //    excerpted. A record beyond the hard cap is named, not paraphrased, so the model knows a rule
   //    exists that it must read before acting instead of receiving its introduction as the rule.
   const pinnedLines: string[] = [];

package/src/adapters/index.ts

@@ -1,4 +1,40 @@
 export { FileMemory, fileSource, inlineSource, type MemoryEntry } from './file-memory';
 export { HttpMemory } from './http-memory';
-export { claudemdSource, MarkdownDocs } from './markdown-docs';
+export {
+  claudemdSource,
+  formatInstructionFiles,
+  type InstructionFile,
+  type InstructionReadOptions,
+  instructionImports,
+  MarkdownDocs,
+  readInstructionFile,
+  resolveInstructionImport,
+  secretInstructionPath,
+  stripInstructionComments,
+  withinAny,
+  withinPath,
+} from './markdown-docs';
+export {
+  dedupeHierarchy,
+  discoverHierarchy,
+  expandHierarchyPath,
+  type HierarchyDedupeOptions,
+  type HierarchyDiscoverOptions,
+  type HierarchyDuplicate,
+  type HierarchyDuplicateKind,
+  type HierarchyFile,
+  type HierarchyFileSource,
+  type HierarchyLocation,
+  type HierarchyMatch,
+  type HierarchyNode,
+  type HierarchyRefusal,
+  type HierarchySource,
+  type HierarchySpan,
+  type HierarchyStack,
+  type HierarchyWalkSource,
+  hierarchyFingerprint,
+  markdownSections,
+  type SelectedHierarchyNode,
+  selectHierarchyNodes,
+} from './markdown-hierarchy';
 export { type SqliteEntry, SqliteMemory } from './sqlite-memory';

package/src/adapters/markdown-docs.ts

@@ -1,4 +1,7 @@
-import { basename, extname, join, relative } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import type { ContextSource } from '../context-layer';
 import type { ContextRef, HydrationAdapter } from '../hydrator';
 
@@ -198,16 +201,251 @@ function extractHeadings(
   return { title, headings };
 }
 
+/** One instruction file as loaded: the file itself or a file it imports with `@path`. */
+export interface InstructionFile {
+  readonly path: string;
+  /** Text with block-level HTML comments removed, as Claude Code injects it. */
+  readonly content: string;
+  /** Import hops from the file the chain started at (0 for that file). */
+  readonly depth: number;
+  /** The file whose `@path` loaded this one. */
+  readonly importedBy?: string;
+}
+
+export interface InstructionReadOptions {
+  /** Home directory for `@~/` imports. Default: the process home. */
+  home?: string;
+  /** Import hops followed from the first file. Claude Code follows four. */
+  maxDepth?: number;
+  /** Real paths already loaded. Shared across a stack, it loads each file once and ends cycles. */
+  seen?: Set<string>;
+  /** Whether an import target may load; Claude Code asks before loading imports outside the project. */
+  allows?: (path: string) => boolean;
+  /** Called when a file is reached again after it already loaded (`seen`); it is not loaded twice. */
+  onDuplicate?: (reach: { path: string; real: string; importedBy?: string }) => void;
+  /** Called with every path consulted, found or not, so a caller can tell when any of them changes. */
+  onProbe?: (path: string) => void;
+  /** Instruction homes judged only below themselves by the secret check (`secretInstructionPath`). */
+  trusted?: readonly string[];
+}
+
+/**
+ * Claude Code imports a file with no extension or a text extension, and skips the rest (`.png`, an
+ * unknown extension, or `notes.md.` with trailing punctuation). Its own list is longer; this covers
+ * the text formats an instruction file plausibly imports.
+ */
+const TEXT_EXTENSIONS = new Set(
+  (
+    'md mdx markdown txt text rst adoc org json jsonc json5 yaml yml toml ini cfg conf xml csv tsv ' +
+    'html htm css scss sass less ts tsx mts cts js jsx mjs cjs py pyi rb go rs java kt kts swift c h cc ' +
+    'cpp hpp cs php sh bash zsh fish ps1 bat sql graphql gql proto prisma tf hcl lua r scala ex exs erl ' +
+    'hs ml clj dart pl vue svelte astro gradle lock log diff patch'
+  )
+    .split(' ')
+    .map((ext) => `.${ext}`),
+);
+
+/** Directories that hold credentials and tokens (`~/.config/gh/hosts.yml`, `~/.local/share/*`, `.git/config`). */
+const CREDENTIAL_DIRECTORIES = new Set([
+  '.ssh',
+  '.aws',
+  '.gnupg',
+  '.kube',
+  '.docker',
+  '.config',
+  '.local',
+  '.git',
+  '.azure',
+  '.gcloud',
+  '.oci',
+  '.password-store',
+  '.terraform.d',
+  '.cargo',
+  '.gem',
+  '.npm',
+  '.pki',
+  '.vault',
+  'Keychains',
+]);
+
+/**
+ * Never loaded, whatever a file asks or a symlink points at: dotfiles (`.env`, `.npmrc`), key
+ * material and anything under a credential directory. Claude Code would import some of these;
+ * Foundry refuses because a committed file must not be able to pull a secret into a shared context.
+ * Within a `trusted` root (an instruction home such as a CLAUDE_CONFIG_DIR under `~/.config`) only
+ * the part below the root is judged.
+ */
+export function secretInstructionPath(path: string, trusted: readonly string[] = []): boolean {
+  const root = trusted.find((dir) => withinPath(path, dir));
+  const rest = root ? relative(root, path) : path;
+  const name = basename(path);
+  return (
+    name.startsWith('.') ||
+    /^id_[a-z0-9]+/i.test(name) ||
+    /\.(pem|key|p12|pfx|keystore|jks)$/i.test(name) ||
+    rest.split(sep).some((part) => CREDENTIAL_DIRECTORIES.has(part))
+  );
+}
+
+/** Claude Code skips an instruction file larger than this. */
+export const INSTRUCTION_FILE_LIMIT = 4 * 1024 * 1024;
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+/** Splits markdown into prose and fenced-code segments, in order. */
+export function fenceSegments(text: string): Array<{ code: boolean; text: string }> {
+  const segments: Array<{ code: boolean; text: string }> = [];
+  let fence: string | undefined;
+  let lines: string[] = [];
+  const flush = (code: boolean) => {
+    if (lines.length) segments.push({ code, text: lines.join('\n') });
+    lines = [];
+  };
+  for (const line of text.split('\n')) {
+    const marker = FENCE.exec(line)?.[1];
+    if (!fence && marker) {
+      flush(false);
+      fence = marker;
+      lines.push(line);
+    } else if (
+      fence &&
+      marker &&
+      marker[0] === fence[0] &&
+      marker.length >= fence.length &&
+      !line.trim().slice(marker.length).trim()
+    ) {
+      lines.push(line);
+      flush(true);
+      fence = undefined;
+    } else lines.push(line);
+  }
+  flush(fence !== undefined);
+  return segments;
+}
+
+/** Removes block-level HTML comments outside fenced code, as Claude Code does before injecting. */
+export function stripInstructionComments(text: string): string {
+  return fenceSegments(text)
+    .map((segment) =>
+      segment.code
+        ? segment.text
+        : segment.text.replace(/^[ \t]*<!--[\s\S]*?-->[ \t]*(?:\n|$)/gm, ''),
+    )
+    .join('\n');
+}
+
+/**
+ * `@path` imports in document order. An import starts at a line start or after whitespace, so
+ * `"@x"` and `a@x` are not imports; `\ ` escapes a space; code spans and fenced blocks are skipped.
+ */
+export function instructionImports(text: string): string[] {
+  const imports: string[] = [];
+  for (const segment of fenceSegments(text)) {
+    if (segment.code) continue;
+    // A code span never crosses a blank line; an indented block after a blank line is code.
+    for (const paragraph of segment.text.split(/\n[ \t]*\n/)) {
+      if (/^( {4}|\t)/.test(paragraph)) continue;
+      const prose = paragraph.replace(/(`+)[\s\S]*?[^`]\1(?!`)|(`+)\2/g, ' ');
+      for (const match of prose.matchAll(/(?:^|\s)@((?:\\ |[^\s])+)/g))
+        imports.push(match[1]!.replace(/\\ /g, ' '));
+    }
+  }
+  return imports;
+}
+
+/** Where an import points: `~/` is the home directory, a relative path is relative to the importing file. */
+export function resolveInstructionImport(target: string, importer: string, home = homedir()) {
+  if (target === '~' || target.startsWith('~/')) return resolve(home, target.slice(2));
+  return isAbsolute(target) ? resolve(target) : resolve(dirname(importer), target);
+}
+
+/**
+ * Read an instruction file and what it imports, the way Claude Code loads CLAUDE.md: the file,
+ * then each import depth-first in document order, up to four hops. A missing, non-file, non-text,
+ * oversized or already-loaded target is skipped, so a cycle ends and a file shared by two importers
+ * loads once.
+ */
+export async function readInstructionFile(
+  path: string,
+  options: InstructionReadOptions = {},
+): Promise<InstructionFile[]> {
+  const seen = options.seen ?? new Set<string>();
+  const maxDepth = options.maxDepth ?? 4;
+  const files: InstructionFile[] = [];
+  const visit = async (file: string, depth: number, importedBy?: string) => {
+    options.onProbe?.(file);
+    let real: string;
+    try {
+      real = await realpath(file);
+      const info = await stat(real);
+      if (!info.isFile() || info.size > INSTRUCTION_FILE_LIMIT) return;
+    } catch {
+      return;
+    }
+    // An import is judged on where it resolves and where its symlinks lead.
+    if (
+      importedBy &&
+      (secretInstructionPath(real, options.trusted) || (options.allows && !options.allows(real)))
+    )
+      return;
+    if (seen.has(real)) {
+      options.onDuplicate?.({ path: file, real, ...(importedBy ? { importedBy } : {}) });
+      return;
+    }
+    seen.add(real);
+    const content = stripInstructionComments(await Bun.file(real).text());
+    files.push({ path: file, content, depth, ...(importedBy ? { importedBy } : {}) });
+    if (depth >= maxDepth) return;
+    for (const target of instructionImports(content)) {
+      const next = resolveInstructionImport(target, file, options.home);
+      const ext = extname(next).toLowerCase();
+      if ((ext && !TEXT_EXTENSIONS.has(ext)) || secretInstructionPath(next, options.trusted))
+        continue;
+      if (!options.allows || options.allows(next)) await visit(next, depth + 1, file);
+    }
+  };
+  await visit(resolve(path), 0);
+  return files;
+}
+
+/** One file, then each file it imports under its own `Contents of` heading. */
+export function formatInstructionFiles(files: readonly InstructionFile[]): string {
+  return files
+    .filter((file) => file.content.trim())
+    .map((file) =>
+      file.importedBy ? `Contents of ${file.path}:\n\n${file.content.trim()}` : file.content.trim(),
+    )
+    .join('\n\n');
+}
+
+/** Whether `path` is `root` or inside it. */
+export function withinPath(path: string, root: string): boolean {
+  const rel = relative(root, path);
+  return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/** A boundary test for `roots`, as written and with symlinks resolved, so a real path compares too. */
+export function withinAny(roots: readonly string[]): (path: string) => boolean {
+  const all = roots.flatMap((root) => {
+    try {
+      return [root, realpathSync(root)];
+    } catch {
+      return [root];
+    }
+  });
+  return (path) => all.some((root) => withinPath(path, root));
+}
+
 /**
- * Convenience: create a ContextSource from a single CLAUDE.md or similar file.
+ * A ContextSource for one CLAUDE.md or similar file, with its `@path` imports resolved. Imports
+ * load from the file's own directory tree only.
  */
 export function claudemdSource(id: string, path: string): ContextSource {
   return {
     id,
     async load() {
-      const file = Bun.file(path);
-      if (!(await file.exists())) return '';
-      return file.text();
+      return formatInstructionFiles(
+        await readInstructionFile(path, { allows: withinAny([dirname(resolve(path))]) }),
+      );
     },
   };
 }