@agentpulselabs/cli-plugin-pulse 0.1.0 → 1.0.0

package/src/lib/redaction.js

@@ -0,0 +1,128 @@
+import {
+  CREDENTIAL_REPLACEMENT, SECRET_RULES, WITHHELD_MARKER, redactSecretBlocks, redactSecretLines, secretKeyReplacement, secretLeafReplacement,
+  secretSubtreeFamily, v1GateFires,
+} from './mirrorContract.js';
+
+function truncateUtf8(value, maxBytes) {
+  const bytes = Buffer.from(value, 'utf8');
+  if (bytes.length <= maxBytes) return { text: value, truncated: false };
+  if (maxBytes <= 0) return { text: '', truncated: true };
+  return {
+    text: bytes.subarray(0, maxBytes).toString('utf8').replace(/\uFFFD$/, ''),
+    truncated: true,
+  };
+}
+
+/**
+ * The contract's passes over one string, without the v1 gate: the block pass, the secret table, the line net, then each
+ * held credential by identity. Every upload path goes through redactSecrets, which adds the gate.
+ */
+export function redactSecretPasses(input, { secrets = [] } = {}) {
+  const blocks = redactSecretBlocks(String(input ?? ''));
+  let { text, redactions } = blocks;
+  for (const rule of SECRET_RULES) {
+    if (!rule.probe.test(text)) continue;
+    text = text.replace(rule.pattern, (...match) => {
+      redactions += 1;
+      const groups = typeof match.at(-1) === 'object' ? match.at(-1) : {};
+      return `${groups.keep ?? ''}${rule.replacement}${groups.tail ?? ''}`;
+    });
+  }
+  const lines = redactSecretLines(text);
+  text = lines.text;
+  redactions += lines.redactions;
+  for (const secret of secrets) {
+    if (!secret || !text.includes(secret)) continue;
+    redactions += text.split(secret).length - 1;
+    text = text.split(secret).join(CREDENTIAL_REPLACEMENT);
+  }
+  return blocks.withheld ? { text, redactions, withheld: true } : { text, redactions };
+}
+
+/**
+ * The contract's passes over one string (redactSecretPasses), then its v1 gate. Returns the text, how many matches were
+ * replaced, and `withheld` (only when true) when a block had no end or v1's pattern still matches with the markers
+ * deleted: the item holding the text is withheld, and a gated text is the withheld marker alone. No replacement matches
+ * a rule, so redacting twice changes nothing.
+ */
+export function redactSecrets(input, options = {}) {
+  const result = redactSecretPasses(input, options);
+  if (result.withheld || !v1GateFires(result.text)) return result;
+  return { text: WITHHELD_MARKER, redactions: result.redactions + 1, withheld: true };
+}
+
+/**
+ * Every string value and key of a JSON value through redactSecrets, the whole string value of an entry whose key names
+ * a secret through secretKeyReplacement, and every string leaf under such a key through secretLeafReplacement; other
+ * values are kept as they are. `withheld` says some string held a block with no end.
+ */
+export function redactSecretsDeep(value, options = {}) {
+  let redactions = 0;
+  let withheld = false;
+  const text = (entry) => {
+    const result = redactSecrets(entry, options);
+    redactions += result.redactions;
+    withheld ||= result.withheld === true;
+    return result.text;
+  };
+  const walk = (entry, family = null) => {
+    if (typeof entry === 'string') {
+      const replacement = family && secretLeafReplacement(family, entry);
+      if (!replacement) return text(entry);
+      redactions += 1;
+      return replacement;
+    }
+    if (Array.isArray(entry)) return entry.map((item) => walk(item, family));
+    if (entry && typeof entry === 'object') {
+      return Object.fromEntries(Object.entries(entry).map(([key, item]) => {
+        const replacement = secretKeyReplacement(key, item);
+        if (replacement) redactions += 1;
+        return [text(key), replacement ?? walk(item, family ?? secretSubtreeFamily(key, item))];
+      }));
+    }
+    return entry;
+  };
+  const redacted = walk(value);
+  return withheld ? { value: redacted, redactions, withheld } : { value: redacted, redactions };
+}
+
+export function redactText(input, { roots = [], maxBytes = 32 * 1024 } = {}) {
+  let { text, redactions } = redactSecrets(input);
+  for (const root of [...roots].filter(Boolean).sort((left, right) => right.length - left.length)) {
+    if (!text.includes(root)) continue;
+    redactions += text.split(root).length - 1;
+    text = text.split(root).join('<root>');
+  }
+  const bounded = truncateUtf8(text, maxBytes);
+  return { ...bounded, redactions };
+}
+
+export function redactObject(value, options = {}) {
+  const maxBytes = options.maxBytes ?? 32 * 1024;
+  if (!Number.isInteger(maxBytes) || maxBytes < 64) {
+    const error = new Error('Object redaction limit must be an integer of at least 64 bytes');
+    error.code = 'HUB_REDACTION_LIMIT_INVALID';
+    throw error;
+  }
+  const roots = [...(options.roots || [])].filter(Boolean).sort((left, right) => right.length - left.length);
+  let withheld = false;
+  const text = (entry) => {
+    const result = redactSecrets(entry);
+    withheld ||= result.withheld === true;
+    return roots.reduce((out, root) => out.split(root).join('<root>'), result.text);
+  };
+  const walk = (entry, family = null) => {
+    if (typeof entry === 'string') return (family && secretLeafReplacement(family, entry)) || text(entry);
+    if (Array.isArray(entry)) return entry.map((item) => walk(item, family));
+    if (entry && typeof entry === 'object') {
+      return Object.fromEntries(Object.entries(entry).map(([key, item]) => [
+        text(key),
+        secretKeyReplacement(key, item) ?? walk(item, family ?? secretSubtreeFamily(key, item)),
+      ]));
+    }
+    return entry;
+  };
+  const redacted = walk(value === undefined ? null : value);
+  if (!withheld && Buffer.byteLength(JSON.stringify(redacted), 'utf8') <= maxBytes) return redacted;
+  return { contentWithheld: true, redactionVersion: 1 };
+}

package/src/lib/rootPolicy.js

@@ -0,0 +1,372 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { HubError } from './errors.js';
+import {
+  ensureOwnerOnlyDirectory,
+  readOwnerOnlyJson,
+  writeOwnerOnlyJson,
+} from './storage.js';
+import { execFileBounded as execFile } from './subprocess.js';
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{2,79}$/;
+const SAFE_REF = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,179}$/;
+
+function isContained(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+async function exists(file) {
+  try {
+    await lstat(file);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+async function gitDirectory(root) {
+  const dotGit = path.join(root, '.git');
+  const info = await lstat(dotGit);
+  if (info.isDirectory()) return realpath(dotGit);
+  if (!info.isFile()) {
+    throw new HubError('HUB_NOT_REPOSITORY', `Unsupported .git entry under ${root}`);
+  }
+  const contents = await readFile(dotGit, 'utf8');
+  const match = contents.match(/^gitdir:\s*(.+)\s*$/m);
+  if (!match) throw new HubError('HUB_NOT_REPOSITORY', `Invalid .git file under ${root}`);
+  return realpath(path.resolve(root, match[1]));
+}
+
+async function repositoryIdentity(canonicalRoot) {
+  let gitDir;
+  try {
+    gitDir = await gitDirectory(canonicalRoot);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new HubError('HUB_NOT_REPOSITORY', `Approved root is not a Git repository: ${canonicalRoot}`);
+    }
+    throw error;
+  }
+  const rootInfo = await lstat(canonicalRoot);
+  const gitInfo = await lstat(gitDir);
+  return createHash('sha256')
+    .update(
+      [
+        canonicalRoot,
+        rootInfo.dev,
+        rootInfo.ino,
+        gitDir,
+        gitInfo.dev,
+        gitInfo.ino,
+      ].join('\0')
+    )
+    .digest('hex');
+}
+
+export class WorktreeRegistry {
+  #queue = Promise.resolve();
+
+  static async open(directory) {
+    await ensureOwnerOnlyDirectory(directory);
+    const file = path.join(directory, 'worktrees.json');
+    const data = await readOwnerOnlyJson(file, { schemaVersion: 1, worktrees: {} });
+    if (data.schemaVersion !== 1 || !data.worktrees || typeof data.worktrees !== 'object') {
+      throw new HubError('HUB_WORKTREE_REGISTRY_INVALID', 'Worktree registry is invalid');
+    }
+    return new WorktreeRegistry(file, data);
+  }
+
+  constructor(file, data) {
+    this.file = file;
+    this.data = data;
+  }
+
+  async #mutate(operation) {
+    const pending = this.#queue.then(async () => {
+      const draft = structuredClone(this.data);
+      const result = operation(draft);
+      await writeOwnerOnlyJson(this.file, draft);
+      this.data = draft;
+      return structuredClone(result);
+    });
+    this.#queue = pending.catch(() => {});
+    return pending;
+  }
+
+  get(worktreeId) {
+    const record = Object.hasOwn(this.data.worktrees, worktreeId)
+      ? this.data.worktrees[worktreeId]
+      : null;
+    return record ? structuredClone(record) : null;
+  }
+
+  list(rootId = null) {
+    return Object.values(this.data.worktrees)
+      .filter((record) => rootId === null || record.rootId === rootId)
+      .map((record) => structuredClone(record));
+  }
+
+  async add(record) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{5,160}$/.test(record.worktreeId)) {
+      throw new HubError('HUB_INVALID_WORKTREE_ID', 'Worktree record id is invalid');
+    }
+    return this.#mutate((draft) => {
+      if (Object.hasOwn(draft.worktrees, record.worktreeId)) {
+        throw new HubError('HUB_WORKTREE_EXISTS', `Worktree record already exists: ${record.worktreeId}`);
+      }
+      draft.worktrees[record.worktreeId] = structuredClone(record);
+      return record;
+    });
+  }
+}
+
+export async function captureRootGrant({ rootId, root, repoWrite = false, worktreeBase }) {
+  if (!SAFE_ID.test(rootId)) {
+    throw new HubError('HUB_INVALID_ROOT_ID', 'Root id must be opaque and path-free');
+  }
+  let canonicalRoot;
+  try {
+    canonicalRoot = await realpath(root);
+  } catch (error) {
+    if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+    throw new HubError('HUB_ROOT_DENIED', `Root "${rootId}" does not exist: ${root}`);
+  }
+  const info = await lstat(canonicalRoot);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new HubError('HUB_ROOT_DENIED', 'Approved root must be a real directory');
+  }
+  if (!(await exists(path.join(canonicalRoot, '.git')))) {
+    throw new HubError('HUB_NOT_REPOSITORY', `Root "${rootId}" must be a git repository: ${canonicalRoot} has no .git`);
+  }
+  const configuredWorktreeBase =
+    worktreeBase ||
+    path.join(path.dirname(canonicalRoot), '.agentpulse-worktrees', rootId);
+  await ensureOwnerOnlyDirectory(configuredWorktreeBase);
+  const head = await readFile(path.join(await gitDirectory(canonicalRoot), 'HEAD'), 'utf8');
+  const branch = head.match(/^ref:\s*refs\/heads\/(.+)\s*$/)?.[1];
+  if (!branch) {
+    throw new HubError('HUB_INVALID_GIT_REF', 'Approved root must have a local branch checked out');
+  }
+  validateBaseRef(branch);
+  return {
+    rootId,
+    canonicalRoot,
+    repositoryIdentity: await repositoryIdentity(canonicalRoot),
+    worktreeBase: await realpath(configuredWorktreeBase),
+    baseRef: branch,
+    repoWrite: Boolean(repoWrite),
+  };
+}
+
+export async function validateRootGrant(grant) {
+  let currentRoot;
+  try {
+    currentRoot = await realpath(grant.canonicalRoot);
+  } catch (error) {
+    throw new HubError('HUB_ROOT_REPLACED', 'Approved root no longer exists', { cause: error });
+  }
+  const identity = await repositoryIdentity(currentRoot);
+  if (currentRoot !== grant.canonicalRoot || identity !== grant.repositoryIdentity) {
+    throw new HubError('HUB_ROOT_REPLACED', 'Approved root or repository identity changed');
+  }
+  return currentRoot;
+}
+
+async function nearestExisting(candidate, boundary) {
+  let current = candidate;
+  while (!await exists(current)) {
+    const parent = path.dirname(current);
+    if (parent === current || !isContained(boundary, parent)) {
+      throw new HubError('HUB_ROOT_ESCAPE', 'Target has no existing parent inside the approved root');
+    }
+    current = parent;
+  }
+  return current;
+}
+
+async function rejectNestedRepository(root, target) {
+  let current = target;
+  const relative = path.relative(root, target);
+  const parts = relative ? relative.split(path.sep) : [];
+  current = root;
+  for (const part of parts) {
+    current = path.join(current, part);
+    const currentInfo = await lstat(current);
+    if (current !== root && currentInfo.isDirectory() && await exists(path.join(current, '.git'))) {
+      throw new HubError('HUB_NESTED_REPOSITORY', `Nested repository is not separately approved: ${current}`);
+    }
+  }
+}
+
+export async function resolveApprovedPath(
+  grant,
+  relativePath,
+  { access = 'read', worktreeId = null, registry = null } = {}
+) {
+  await validateRootGrant(grant);
+  if (
+    typeof relativePath !== 'string' ||
+    relativePath.length === 0 ||
+    relativePath.includes('\0') ||
+    relativePath.includes('\\') ||
+    path.isAbsolute(relativePath)
+  ) {
+    throw new HubError('HUB_PATH_DENIED', 'Target must be a portable relative path');
+  }
+  const normalized = path.posix.normalize(relativePath);
+  if (normalized !== relativePath || normalized === '..' || normalized.startsWith('../')) {
+    throw new HubError('HUB_PATH_DENIED', 'Path traversal or non-canonical path is denied');
+  }
+
+  let boundary = grant.canonicalRoot;
+  if (access === 'write') {
+    if (!grant.repoWrite) {
+      throw new HubError('HUB_REPO_WRITE_DENIED', 'Approved root does not allow repository writes');
+    }
+    if (!worktreeId || !registry) {
+      throw new HubError('HUB_WRITE_REQUIRES_WORKTREE', 'Writes require a connector-owned worktree');
+    }
+    const record = registry.get(worktreeId);
+    if (!record || record.rootId !== grant.rootId) {
+      throw new HubError('HUB_WRITE_REQUIRES_WORKTREE', 'Worktree is not registered for the approved root');
+    }
+    boundary = await realpath(record.canonicalPath);
+    const boundaryInfo = await lstat(boundary);
+    const configuredBase = await realpath(grant.worktreeBase);
+    if (
+      !isContained(configuredBase, boundary) ||
+      path.dirname(boundary) !== configuredBase
+    ) {
+      throw new HubError(
+        'HUB_WRITE_REQUIRES_WORKTREE',
+        'Writes require a direct child of the connector-owned worktree directory'
+      );
+    }
+    try {
+      const mainGit = await gitDirectory(grant.canonicalRoot);
+      const linkedGit = await gitDirectory(boundary);
+      if (
+        !isContained(path.join(mainGit, 'worktrees'), linkedGit) ||
+        linkedGit !== record.gitDirectory ||
+        boundary !== record.canonicalPath ||
+        boundaryInfo.dev !== record.pathDevice ||
+        boundaryInfo.ino !== record.pathInode ||
+        record.repositoryIdentity !== grant.repositoryIdentity
+      ) {
+        throw new HubError(
+          'HUB_WRITE_REQUIRES_WORKTREE',
+          'Write target is not a worktree of the approved repository'
+        );
+      }
+    } catch (error) {
+      if (error instanceof HubError && error.code === 'HUB_WRITE_REQUIRES_WORKTREE') throw error;
+      throw new HubError(
+        'HUB_WRITE_REQUIRES_WORKTREE',
+        'Write target is not a valid connector-owned worktree',
+        { cause: error }
+      );
+    }
+  } else if (access !== 'read') {
+    throw new HubError('HUB_PATH_DENIED', `Unsupported access mode: ${access}`);
+  }
+
+  const candidate = path.resolve(boundary, relativePath);
+  if (!isContained(boundary, candidate)) {
+    throw new HubError('HUB_ROOT_ESCAPE', 'Target leaves the approved boundary');
+  }
+  const existing = await nearestExisting(candidate, boundary);
+  const canonicalExisting = await realpath(existing);
+  if (!isContained(boundary, canonicalExisting)) {
+    throw new HubError('HUB_ROOT_ESCAPE', 'Symlink resolves outside the approved boundary');
+  }
+  await rejectNestedRepository(boundary, existing);
+  return candidate;
+}
+
+function validateWorktreeIdentifier(value) {
+  if (!SAFE_ID.test(value)) {
+    throw new HubError('HUB_INVALID_WORKTREE_ID', 'Worktree identifiers must be opaque');
+  }
+  return value;
+}
+
+function validateBaseRef(value) {
+  if (
+    !SAFE_REF.test(value) ||
+    value.startsWith('-') ||
+    value.includes('..') ||
+    value.includes('@{') ||
+    value.endsWith('.lock')
+  ) {
+    throw new HubError('HUB_INVALID_GIT_REF', 'Base ref is not safe');
+  }
+  return value;
+}
+
+export async function createOwnedWorktree({
+  grant,
+  deliveryId,
+  streamId,
+  baseRef,
+  registry,
+  execute = execFile,
+}) {
+  await validateRootGrant(grant);
+  if (!grant.repoWrite) {
+    throw new HubError('HUB_REPO_WRITE_DENIED', 'Approved root does not allow repository writes');
+  }
+  if (!registry) throw new HubError('HUB_WORKTREE_REGISTRY_REQUIRED', 'Worktree registry is required');
+  validateWorktreeIdentifier(deliveryId);
+  validateWorktreeIdentifier(streamId);
+  validateBaseRef(baseRef);
+  const worktreeBase = grant.worktreeBase;
+  await ensureOwnerOnlyDirectory(worktreeBase);
+  const name = `${deliveryId}-${streamId}`;
+  const destination = path.join(worktreeBase, name);
+  if (!isContained(worktreeBase, destination)) {
+    throw new HubError('HUB_ROOT_ESCAPE', 'Generated worktree path escaped its owner directory');
+  }
+  if (await exists(destination)) {
+    throw new HubError('HUB_WORKTREE_EXISTS', `Connector worktree already exists: ${name}`);
+  }
+  const branch = `pulse/${deliveryId}/${streamId}`;
+  await execute(
+    'git',
+    ['-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '-b', branch, destination, baseRef],
+    {
+      cwd: grant.canonicalRoot,
+      timeout: 60_000,
+      maxBuffer: 1024 * 1024,
+      env: {
+        PATH: process.env.PATH || '/usr/bin:/bin',
+        LC_ALL: 'C',
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_CONFIG_SYSTEM: '/dev/null',
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_OPTIONAL_LOCKS: '0',
+      },
+    }
+  );
+  const canonicalPath = await realpath(destination);
+  const pathInfo = await lstat(canonicalPath);
+  const linkedGit = await gitDirectory(canonicalPath);
+  const mainGit = await gitDirectory(grant.canonicalRoot);
+  if (!isContained(path.join(mainGit, 'worktrees'), linkedGit)) {
+    throw new HubError('HUB_WORKTREE_INVALID', 'Created worktree is not linked to the approved repository');
+  }
+  return registry.add({
+    worktreeId: name,
+    rootId: grant.rootId,
+    deliveryId,
+    streamId,
+    branch,
+    canonicalPath,
+    pathDevice: pathInfo.dev,
+    pathInode: pathInfo.ino,
+    gitDirectory: linkedGit,
+    repositoryIdentity: grant.repositoryIdentity,
+    createdAt: new Date().toISOString(),
+  });
+}

package/src/lib/rulePacks.js

@@ -0,0 +1,162 @@
+import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const DENIED_NAME = /^\.env|secret|token/i;
+const REPO_DOCS = ['AGENTS.md', 'CLAUDE.md'];
+const MAX_DEPTH = 4;
+export const RULES_SUBDIR = path.join('.cursor', 'rules');
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (/^(["']).*\1$/.test(trimmed)) return trimmed.slice(1, -1);
+  return trimmed;
+}
+
+function listValue(value) {
+  const trimmed = value.trim();
+  const inner = trimmed.startsWith('[') && trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed;
+  return inner.split(',').map(unquote).filter(Boolean);
+}
+
+export function parseRuleFile(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const fields = {};
+  if (match) {
+    let listKey = null;
+    for (const line of match[1].split(/\r?\n/)) {
+      const item = line.match(/^\s+-\s+(.*)$/);
+      if (item && listKey) {
+        fields[listKey].push(unquote(item[1]));
+        continue;
+      }
+      const pair = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+      if (!pair) continue;
+      listKey = pair[2].trim() === '' ? pair[1] : null;
+      fields[pair[1]] = listKey ? [] : pair[2];
+    }
+  }
+  const globs = fields.globs;
+  return {
+    description: typeof fields.description === 'string' && fields.description.trim() ? unquote(fields.description) : null,
+    alwaysApply: typeof fields.alwaysApply === 'string' && fields.alwaysApply.trim() === 'true',
+    globs: Array.isArray(globs) ? globs.filter(Boolean) : typeof globs === 'string' ? listValue(globs) : [],
+    body: match ? text.slice(match[0].length) : text,
+  };
+}
+
+async function canonical(target) {
+  try {
+    return await realpath(target);
+  } catch {
+    return null;
+  }
+}
+
+function contained(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+class PackBuilder {
+  constructor({ id, name, source, repo, maxRulesPerPack, maxRuleBytes, skipped }) {
+    this.pack = { id, name, source, ...(repo ? { repo } : {}), rules: [] };
+    this.maxRulesPerPack = maxRulesPerPack;
+    this.maxRuleBytes = maxRuleBytes;
+    this.skipped = skipped;
+  }
+
+  skip(file, reason) {
+    this.skipped.push({ pack: this.pack.id, file, reason });
+  }
+
+  async add({ file, absolute, boundary, alwaysApply = null }) {
+    if (DENIED_NAME.test(path.basename(file))) return this.skip(file, 'denied_name');
+    const info = await lstat(absolute);
+    let target = absolute;
+    if (info.isSymbolicLink()) {
+      target = await canonical(absolute);
+      if (!target || !contained(boundary, target)) return this.skip(file, 'outside_pack');
+    }
+    const targetInfo = await stat(target);
+    if (!targetInfo.isFile()) return this.skip(file, 'not_a_rule');
+    if (targetInfo.size > this.maxRuleBytes) return this.skip(file, 'too_large');
+    if (this.pack.rules.length >= this.maxRulesPerPack) return this.skip(file, 'pack_full');
+    const parsed = parseRuleFile(await readFile(target, 'utf8'));
+    this.pack.rules.push({
+      name: file.endsWith('.mdc') ? path.basename(file, '.mdc') : path.basename(file),
+      file,
+      description: parsed.description,
+      alwaysApply: alwaysApply ?? parsed.alwaysApply,
+      globs: parsed.globs,
+      body: parsed.body,
+    });
+    return undefined;
+  }
+
+  async addRulesDirectory(rulesDir) {
+    const boundary = await canonical(rulesDir);
+    if (!boundary) return;
+    const walk = async (directory, relative, depth) => {
+      const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+        left.name < right.name ? -1 : left.name > right.name ? 1 : 0
+      );
+      for (const entry of entries) {
+        const file = relative ? `${relative}/${entry.name}` : entry.name;
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+          if (DENIED_NAME.test(entry.name)) this.skip(file, 'denied_name');
+          else if (depth < MAX_DEPTH) await walk(absolute, file, depth + 1);
+          continue;
+        }
+        if (DENIED_NAME.test(entry.name)) this.skip(file, 'denied_name');
+        else if (!entry.name.endsWith('.mdc')) this.skip(file, 'not_a_rule');
+        else await this.add({ file, absolute, boundary });
+      }
+    };
+    await walk(boundary, '', 0);
+  }
+}
+
+export async function readRulePacks({
+  workspace,
+  home,
+  repos = [],
+  maxRulesPerPack = 100,
+  maxRuleBytes = 64 * 1024,
+  rulesSubdir = RULES_SUBDIR,
+}) {
+  const skipped = [];
+  const packs = [];
+  const options = { maxRulesPerPack, maxRuleBytes, skipped };
+  const finish = (builder) => {
+    if (builder.pack.rules.length > 0) packs.push(builder.pack);
+  };
+
+  if (workspace) {
+    const builder = new PackBuilder({ id: 'workspace', name: 'Workspace rules', source: 'workspace', ...options });
+    await builder.addRulesDirectory(path.join(workspace, rulesSubdir));
+    finish(builder);
+  }
+
+  const seen = new Set([await canonical(workspace || '')]);
+  const repoPacks = [];
+  for (const repo of repos) {
+    const root = await canonical(repo.root);
+    if (!root || seen.has(root)) continue;
+    seen.add(root);
+    const builder = new PackBuilder({ id: `repo:${repo.name}`, name: repo.name, source: 'repo', repo: repo.name, ...options });
+    await builder.addRulesDirectory(path.join(root, rulesSubdir));
+    for (const doc of REPO_DOCS) {
+      const absolute = path.join(root, doc);
+      if (await canonical(absolute)) await builder.add({ file: doc, absolute, boundary: root, alwaysApply: true });
+    }
+    repoPacks.push(builder);
+  }
+  repoPacks.sort((left, right) => (left.pack.id < right.pack.id ? -1 : 1)).forEach(finish);
+
+  if (home) {
+    const builder = new PackBuilder({ id: 'user', name: 'User rules', source: 'user', ...options });
+    await builder.addRulesDirectory(path.join(home, rulesSubdir));
+    finish(builder);
+  }
+  return { packs, skipped };
+}