@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

package/dist/templates/monorepo/scripts/_catalog-runtime/check-core.ts

@@ -0,0 +1,280 @@
+/**
+ * Shared check engine. The duplicated git plumbing, arg parsing, index loading
+ * and mode dispatch from both `check.ts` files collapse here (fix #15).
+ *
+ * Fixes landed here:
+ *  - #5: `workingTreeFiles` uses `git status --porcelain -z` and parses the
+ *    NUL-delimited form, taking the NEW path on renames/copies (the post-NUL
+ *    token is the OLD path → skip it). `-z` disables quoting, so no brittle
+ *    `slice(3)` + quote-stripping.
+ *  - #6: `--branch` is genuinely optional; when omitted it defaults to the
+ *    current branch. The base is `defaultBaseBranch()` (origin/HEAD → origin/main
+ *    → merge-base), NOT a literal `main`. The diff uses `<base>...<branch>`
+ *    triple-dot (merge-base semantics).
+ *  - #13: `loadIndex` wraps `JSON.parse` in try/catch with a friendly
+ *    "ejecuta pnpm <generateCmd>" message.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { rulesByPath } from './glob';
+import { findRepoRoot } from './repo-root';
+import type { CatalogIndex, IndexedRule } from './types';
+
+const CHECK_MODE = {
+  AGGREGATE: 'aggregate',
+  RULE: 'rule',
+  BRANCH: 'branch',
+  PR: 'pr',
+  WORKING: 'working',
+} as const;
+
+export type CheckMode = (typeof CHECK_MODE)[keyof typeof CHECK_MODE];
+
+export { CHECK_MODE };
+
+export interface Args {
+  mode: CheckMode;
+  aggregate?: string;
+  ruleId?: string;
+  branch?: string;
+  prNumber?: string;
+}
+
+export interface ParseArgsOptions {
+  /** Regex a positional argument must match to be treated as a rule id (e.g. `^BR-[A-Z0-9-]+$`). */
+  ruleIdRegex: RegExp;
+}
+
+export interface CheckMessages {
+  /** Hint printed under impacted rules (catalog-specific wording). */
+  mergeHint: string;
+  /** Message printed when an aggregate has no indexed rules (catalog-specific). */
+  aggregateEmpty?: string;
+}
+
+export interface CheckOptions {
+  /** Index JSON path relative to repo root. */
+  indexPath: string;
+  /** Generate command name used in error hints (e.g. `br:generate`). */
+  generateCmd: string;
+  /** Regex a positional must match to be treated as a rule id. */
+  ruleIdRegex: RegExp;
+  messages: CheckMessages;
+}
+
+function runGit(args: string[], failureMessage: string): string {
+  const result = spawnSync('git', args, { encoding: 'utf-8' });
+  if (result.status !== 0) {
+    console.error(`✗ ${failureMessage}:`, result.stderr);
+    process.exit(1);
+  }
+  return result.stdout ?? '';
+}
+
+/**
+ * Resolves the repository's default base branch: prefers the symbolic ref of
+ * `origin/HEAD`, then `origin/main` when it exists, then falls back to the
+ * literal `origin/main` ref name. Never crashes in checkouts without
+ * `origin/HEAD`.
+ */
+export function defaultBaseBranch(): string {
+  const originHead = spawnSync(
+    'git',
+    ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'],
+    { encoding: 'utf-8' },
+  );
+  if (originHead.status === 0) {
+    const ref = (originHead.stdout ?? '').trim();
+    if (ref) return ref;
+  }
+  const originMain = spawnSync('git', ['rev-parse', '--verify', '--quiet', 'origin/main'], {
+    encoding: 'utf-8',
+  });
+  if (originMain.status === 0) return 'origin/main';
+  return 'origin/main';
+}
+
+/** Returns the current branch name (`git symbolic-ref --short HEAD`). */
+export function currentBranch(): string {
+  return runGit(['symbolic-ref', '--short', 'HEAD'], 'git symbolic-ref falló').trim();
+}
+
+export function parseCheckArgs(opts: ParseArgsOptions): Args {
+  const argv = process.argv.slice(2);
+  const branchIndex = argv.indexOf('--branch');
+  if (branchIndex >= 0) {
+    // --branch is genuinely optional in value: omitting it means "current branch".
+    const value = argv[branchIndex + 1];
+    const branch = value && !value.startsWith('--') ? value : undefined;
+    return { mode: CHECK_MODE.BRANCH, branch };
+  }
+  const prIndex = argv.indexOf('--pr');
+  if (prIndex >= 0) return { mode: CHECK_MODE.PR, prNumber: argv[prIndex + 1] };
+  const positional = argv.find((arg) => !arg.startsWith('--'));
+  if (!positional) return { mode: CHECK_MODE.WORKING };
+  if (opts.ruleIdRegex.test(positional)) return { mode: CHECK_MODE.RULE, ruleId: positional };
+  if (positional.includes('/')) return { mode: CHECK_MODE.AGGREGATE, aggregate: positional };
+  console.error(`✗ Argumento no reconocido: ${positional}`);
+  process.exit(1);
+}
+
+export function gitDiffFiles(args: { from?: string; to?: string }): string[] {
+  const cmd = ['diff', '--name-only'];
+  if (args.from && args.to) cmd.push(`${args.from}...${args.to}`);
+  else if (args.from) cmd.push(args.from);
+  const stdout = runGit(cmd, 'git diff falló');
+  return stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Changed files in the working tree, parsed from `git status --porcelain -z`.
+ * Entries are NUL-delimited; each entry is `XY <path>` at fixed offset 3. For a
+ * rename/copy (`R`/`C` in either status column), the FOLLOWING NUL field is the
+ * OLD path and is discarded — we keep the NEW path only. `-z` disables quoting.
+ */
+export function workingTreeFiles(): string[] {
+  const stdout = runGit(
+    ['status', '--porcelain', '-z', '--untracked-files=normal'],
+    'git status falló',
+  );
+  const entries = stdout.split('\0');
+  const out: string[] = [];
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index];
+    if (!entry) continue;
+    const status = entry.slice(0, 2);
+    const path = entry.slice(3);
+    if (!path) continue;
+    out.push(path);
+    // Rename/copy: the next NUL field is the OLD path — consume and discard it.
+    if (status[0] === 'R' || status[0] === 'C' || status[1] === 'R' || status[1] === 'C') {
+      index++;
+    }
+  }
+  return out;
+}
+
+export function prFiles(prNumber: string): string[] {
+  const result = spawnSync(
+    'gh',
+    ['pr', 'view', prNumber, '--json', 'files', '-q', '.files[].path'],
+    { encoding: 'utf-8' },
+  );
+  if (result.status !== 0) {
+    console.error('✗ gh pr view falló (¿gh autenticado?):', result.stderr);
+    process.exit(1);
+  }
+  return (result.stdout ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+export function loadIndex(
+  repoRoot: string,
+  indexPath: string,
+  generateCmd: string,
+): CatalogIndex {
+  const path = resolve(repoRoot, indexPath);
+  if (!existsSync(path)) {
+    console.error(`✗ El índice no existe. Ejecuta \`pnpm ${generateCmd}\` primero.`);
+    process.exit(1);
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (err) {
+    console.error(`✗ No se pudo leer el índice: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(raw) as CatalogIndex;
+  } catch {
+    console.error(`✗ El índice está corrupto. Ejecuta \`pnpm ${generateCmd}\`.`);
+    process.exit(1);
+  }
+}
+
+function printRule(rule: IndexedRule): void {
+  console.log(`  ${rule.id} — ${rule.title}`);
+  console.log(`    state=${rule.state}  severity=${rule.severity}`);
+  console.log(`    file: ${rule.filePath}`);
+}
+
+function checkAggregate(index: CatalogIndex, aggregate: string, messages: CheckMessages): void {
+  const ids = index.byAggregate[aggregate] ?? [];
+  if (ids.length === 0) {
+    const detail = messages.aggregateEmpty ? ` (${messages.aggregateEmpty})` : '';
+    console.log(`Sin reglas para el agregado \`${aggregate}\`.${detail}`);
+    return;
+  }
+  console.log(`Reglas para \`${aggregate}\`: ${ids.length}\n`);
+  for (const id of ids) printRule(index.byId[id]);
+}
+
+function checkRule(index: CatalogIndex, ruleId: string): void {
+  const rule = index.byId[ruleId];
+  if (!rule) {
+    console.error(`✗ Regla no encontrada: ${ruleId}`);
+    process.exit(1);
+  }
+  console.log(`${rule.id} — ${rule.title}\n`);
+  console.log(`  state:      ${rule.state}`);
+  console.log(`  severity:   ${rule.severity}`);
+  console.log(`  BCs:        ${rule.bounded_contexts.join(', ')}`);
+  console.log(`  Aggregates: ${rule.aggregates.join(', ')}`);
+  console.log(`  Paths:`);
+  for (const path of rule.paths) console.log(`    - ${path}`);
+  console.log(`  Last updated: ${rule.last_updated}`);
+  console.log(`  File: ${rule.filePath}`);
+}
+
+function checkPaths(index: CatalogIndex, paths: string[], messages: CheckMessages): void {
+  if (paths.length === 0) {
+    console.log('Sin archivos modificados.');
+    return;
+  }
+  const rules = rulesByPath(index, paths);
+  console.log(`Archivos modificados: ${paths.length}`);
+  console.log(`Reglas potencialmente impactadas: ${rules.length}\n`);
+  for (const rule of rules) printRule(rule);
+  if (rules.length > 0) {
+    console.log(`\n${messages.mergeHint}`);
+  }
+}
+
+export function runCheck(opts: CheckOptions): void {
+  const args = parseCheckArgs({ ruleIdRegex: opts.ruleIdRegex });
+  const repoRoot = findRepoRoot();
+  const index = loadIndex(repoRoot, opts.indexPath, opts.generateCmd);
+
+  switch (args.mode) {
+    case CHECK_MODE.AGGREGATE:
+      checkAggregate(index, args.aggregate ?? '', opts.messages);
+      break;
+    case CHECK_MODE.RULE:
+      checkRule(index, args.ruleId ?? '');
+      break;
+    case CHECK_MODE.BRANCH: {
+      const branch = args.branch ?? currentBranch();
+      const base = defaultBaseBranch();
+      const paths = gitDiffFiles({ from: base, to: branch });
+      checkPaths(index, paths, opts.messages);
+      break;
+    }
+    case CHECK_MODE.PR: {
+      const paths = prFiles(args.prNumber ?? '');
+      checkPaths(index, paths, opts.messages);
+      break;
+    }
+    case CHECK_MODE.WORKING: {
+      const paths = workingTreeFiles();
+      checkPaths(index, paths, opts.messages);
+      break;
+    }
+  }
+}

package/dist/templates/monorepo/scripts/_catalog-runtime/cli.ts

@@ -0,0 +1,26 @@
+/**
+ * One CLI wrapper for every catalog leaf script. Replaces the six
+ * near-identical `main().catch(...)` tails and gives the previously-uncaught
+ * sync `check.ts` `main()` the same top-level guard (fix #13 altitude).
+ *
+ * `fn` may be sync or async. Any throw — synchronous or rejected promise — is
+ * caught, printed as `✗ <label> falló:` + message, and the process exits 1.
+ * Scripts that need a non-1 exit code (e.g. validators returning 2 for
+ * warnings-only) call `process.exit` themselves before returning.
+ */
+export function runCatalogMain(fn: () => void | Promise<void>, label: string): void {
+  const fail = (err: unknown): void => {
+    console.error(`✗ ${label} falló:`);
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  };
+
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      result.catch(fail);
+    }
+  } catch (err) {
+    fail(err);
+  }
+}

package/dist/templates/monorepo/scripts/_catalog-runtime/frontmatter.ts

@@ -0,0 +1,15 @@
+/**
+ * Frontmatter normalization shared by every catalog parser.
+ *
+ * gray-matter (js-yaml) auto-parses ISO dates into `Date` objects; the catalog
+ * contract uses ISO date strings, so coerce `last_updated` back to YYYY-MM-DD.
+ */
+export function normalizeFrontmatter(
+  data: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...data };
+  if (out.last_updated instanceof Date) {
+    out.last_updated = out.last_updated.toISOString().slice(0, 10);
+  }
+  return out;
+}

package/dist/templates/monorepo/scripts/_catalog-runtime/glob.ts

@@ -0,0 +1,86 @@
+/**
+ * Glob utilities shared by every catalog CLI. Centralizes the minimal glob →
+ * regex translation (previously copy-pasted into both `check.ts` files) and the
+ * glob-metachar test reused by `validate.ts` to skip existence-checking glob
+ * patterns (fix #9) and by `check-core.ts` to match changed files against rule
+ * `paths` patterns (fix #15 dedup).
+ */
+import type { CatalogIndex, IndexedRule } from './types';
+
+/** Glob metacharacters: a candidate containing any of these is a pattern, not a concrete path. */
+const GLOB_METACHARS = ['*', '?', '{', '}'] as const;
+
+export { GLOB_METACHARS };
+
+/**
+ * True when the given path contains glob metacharacters (`* ? { }`). Concrete
+ * paths (no metachars) are the only ones worth existence-checking; patterns are
+ * skipped to avoid spurious "path inexistente" warnings (fix #9).
+ */
+export function hasGlobMetachars(candidate: string): boolean {
+  return GLOB_METACHARS.some((metachar) => candidate.includes(metachar));
+}
+
+/**
+ * Minimal glob → regex translation: `**` matches any path segments, `*` matches
+ * within a single segment (no separator), `?` matches a single non-separator
+ * character. All other regex metacharacters are escaped.
+ */
+export function globToRegex(glob: string): RegExp {
+  let regexSource = '^';
+  let index = 0;
+  while (index < glob.length) {
+    const char = glob[index];
+    if (char === '*' && glob[index + 1] === '*') {
+      regexSource += '.*';
+      index += 2;
+      if (glob[index] === '/') index++;
+    } else if (char === '*') {
+      regexSource += '[^/]*';
+      index++;
+    } else if (char === '?') {
+      regexSource += '[^/]';
+      index++;
+    } else if ('.+()[]{}|^$\\'.includes(char)) {
+      regexSource += '\\' + char;
+      index++;
+    } else {
+      regexSource += char;
+      index++;
+    }
+  }
+  regexSource += '$';
+  return new RegExp(regexSource);
+}
+
+/**
+ * Returns the indexed rules whose declared `paths` patterns match any of the
+ * given changed files. A pattern contributes its rule IDs once if at least one
+ * changed path matches it.
+ */
+export function rulesByPath(
+  index: CatalogIndex,
+  paths: readonly string[],
+): IndexedRule[] {
+  const matchedIds = new Set<string>();
+  for (const entry of index.byPath) {
+    // Defense-in-depth: a well-formed index always satisfies this (so behavior
+    // is byte-identical), but a caller that hands us an UNGUARDED index could
+    // carry a malformed entry — `globToRegex(undefined)` would throw. Skip such
+    // entries so the traversal degrades instead of crashing the caller.
+    if (typeof entry.pattern !== 'string' || !Array.isArray(entry.ruleIds)) continue;
+    const patternRegex = globToRegex(entry.pattern);
+    for (const path of paths) {
+      if (patternRegex.test(path)) {
+        for (const ruleId of entry.ruleIds) matchedIds.add(ruleId);
+        break;
+      }
+    }
+  }
+  const out: IndexedRule[] = [];
+  for (const ruleId of matchedIds) {
+    const rule = index.byId[ruleId];
+    if (rule) out.push(rule);
+  }
+  return out;
+}

package/dist/templates/monorepo/scripts/_catalog-runtime/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Public surface of the shared catalog runtime. Catalog CLIs
+ * (`scripts/business-rules/`, `scripts/harness-rules/`) import from here.
+ */
+export { findRepoRoot } from './repo-root';
+export { normalizeFrontmatter } from './frontmatter';
+export { parseCatalog, detectHyphenHeadings } from './parse';
+export type { ParseCatalogOptions, HyphenHeading } from './parse';
+export { globToRegex, rulesByPath, hasGlobMetachars, GLOB_METACHARS } from './glob';
+export {
+  isCatalogIndex,
+  isSkillTriggerIndex,
+  loadCatalogIndex,
+  loadJsonIndex,
+  toRepoRelative,
+} from './catalog-index';
+export { buildIndex, buildHumanIndex, TOTAL_FILES_MODE } from './build-index';
+export type {
+  BuildIndexOptions,
+  HumanIndexOptions,
+  FrontmatterToFields,
+  ReadFieldsResult,
+  ReadFieldsOk,
+  ReadFieldsError,
+  IndexFields,
+  TotalFilesMode,
+} from './build-index';
+export {
+  validateFrontmatter,
+  validateUniqueIds,
+  validateRuleMetadata,
+  validateImplementaPaths,
+  extractSection,
+  runCatalogValidation,
+  ISSUE_SEVERITY,
+} from './validate';
+export type { Issue, IssueSeverity, ValidateOptions, ExtraCheck } from './validate';
+export {
+  gitDiffFiles,
+  workingTreeFiles,
+  prFiles,
+  parseCheckArgs,
+  defaultBaseBranch,
+  currentBranch,
+  loadIndex,
+  runCheck,
+  CHECK_MODE,
+} from './check-core';
+export type {
+  Args,
+  CheckMode,
+  CheckOptions,
+  CheckMessages,
+  ParseArgsOptions,
+} from './check-core';
+export { runCatalogMain } from './cli';
+export {
+  RULE_STATE,
+  RULE_SEVERITY,
+  RULE_PREFIX,
+} from './types';
+export type {
+  RuleState,
+  RuleSeverity,
+  RulePrefix,
+  BaseFrontmatter,
+  ParsedRule,
+  ParsedFile,
+  IndexedRule,
+  CatalogPathEntry,
+  CatalogIndex,
+  SkillTrigger,
+  SkillTriggerIndex,
+} from './types';

package/dist/templates/monorepo/scripts/_catalog-runtime/parse.ts

@@ -0,0 +1,159 @@
+/**
+ * Generic catalog parser. Globs the given markdown patterns, parses frontmatter
+ * with gray-matter, and extracts per-rule metadata from each body using regex
+ * over the canonical structure (heading + metadata table).
+ *
+ * Per-rule structure expected:
+ *
+ *   ## <ID> — <title>
+ *
+ *   | Campo      | Valor              |
+ *   | ---------- | ------------------ |
+ *   | Tipo       | `<type>`           |
+ *   | Estado     | `<state>`          |
+ *   | Severidad  | `<severity>`       |
+ *   | Origen     | <text>             |
+ *   | Trigger en | <optional>         |
+ *   | Efecto en  | <optional>         |
+ *
+ * Anything past the table belongs to the rule body until the next `## ` heading
+ * or end of file.
+ *
+ * The heading regex is deliberately generic: it accepts any uppercase family
+ * prefix (`BR-`, `HR-`, and future prefixes) so a single parser serves every
+ * catalog.
+ */
+import fastGlob from 'fast-glob';
+import matter from 'gray-matter';
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { normalizeFrontmatter } from './frontmatter';
+import { RULE_PREFIX } from './types';
+import type { ParsedFile, ParsedRule } from './types';
+
+// Family prefixes come from ONE place (RULE_PREFIX). Anchoring the heading to
+// the known-prefix union (`BR|HR`) means a prose heading like
+// `## API-V2 — foo` no longer matches as a phantom rule (fix #1): the prefix is
+// not in the union. The separator accepts the canonical em-dash (`—`) OR a
+// spaced ASCII hyphen (` - `) so a heading authored with the wrong dash still
+// yields a rule (fix #2) instead of silently disappearing; the em-dash remains
+// the documented canonical form (README), nudged by the hyphen-heading WARN.
+function buildPrefixAlternation(): string {
+  return Object.values(RULE_PREFIX).join('|');
+}
+
+function buildRuleHeadingRegex(): RegExp {
+  const prefixes = buildPrefixAlternation();
+  return new RegExp(`^##\\s+((?:${prefixes})-[A-Z0-9-]+)\\s+(?:—|-)\\s+(.+?)\\s*$`, 'gm');
+}
+
+const RULE_HEADING_ALL = buildRuleHeadingRegex();
+
+/**
+ * Detects rule headings written with a spaced ASCII hyphen (` - `) instead of
+ * the canonical em-dash (`—`). Catalog validators use this to WARN (not error)
+ * so the deliberate em-dash convention is nudged without breaking parsing.
+ */
+export interface HyphenHeading {
+  id: string;
+  title: string;
+}
+
+export function detectHyphenHeadings(body: string): HyphenHeading[] {
+  const prefixes = buildPrefixAlternation();
+  const hyphenHeadingRegex = new RegExp(
+    `^##\\s+((?:${prefixes})-[A-Z0-9-]+)\\s+-\\s+(.+?)\\s*$`,
+    'gm',
+  );
+  const out: HyphenHeading[] = [];
+  for (const match of body.matchAll(hyphenHeadingRegex)) {
+    out.push({ id: match[1], title: match[2] });
+  }
+  return out;
+}
+
+function parseMetadataTable(text: string): Record<string, string> {
+  const tableMatch = text.match(/\|\s*Campo\s*\|\s*Valor\s*\|[\s\S]*?(?=\n\n|\n###|\n##|$)/);
+  if (!tableMatch) return {};
+  const lines = tableMatch[0].split('\n').filter((l) => l.trim().startsWith('|'));
+  const rows = lines.slice(2);
+  const out: Record<string, string> = {};
+  for (const row of rows) {
+    const cells = row
+      .split('|')
+      .slice(1, -1)
+      .map((c) => c.trim());
+    if (cells.length < 2) continue;
+    const key = cells[0].toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '');
+    const value = cells.slice(1).join(' | ').replace(/^`|`$/g, '').trim();
+    out[key] = value;
+  }
+  return out;
+}
+
+function stripBackticks(s: string): string {
+  return s.replace(/`/g, '').trim();
+}
+
+function extractRulesFromBody(body: string): ParsedRule[] {
+  const headings = Array.from(body.matchAll(RULE_HEADING_ALL)).map((m) => ({
+    id: m[1],
+    title: m[2],
+    index: m.index ?? 0,
+  }));
+  const rules: ParsedRule[] = [];
+  for (let i = 0; i < headings.length; i++) {
+    const start = headings[i].index;
+    const end = i + 1 < headings.length ? headings[i + 1].index : body.length;
+    const section = body.slice(start, end);
+    const meta = parseMetadataTable(section);
+    // The metadata table inside each rule is written in Spanish on purpose
+    // (Estado / Severidad / Origen / Trigger en / Efecto en); the JSON
+    // index uses English keys because it is a structural artifact consumed by
+    // tooling, never read directly by humans.
+    rules.push({
+      id: headings[i].id,
+      title: headings[i].title,
+      state: stripBackticks(meta['estado'] ?? ''),
+      severity: stripBackticks(meta['severidad'] ?? ''),
+      origin: meta['origen'] ?? '',
+      triggerOn: meta['trigger en'] ?? undefined,
+      effectOn: meta['efecto en'] ?? undefined,
+      body: section,
+    });
+  }
+  return rules;
+}
+
+export interface ParseCatalogOptions {
+  repoRoot: string;
+  globs: string[];
+}
+
+export async function parseCatalog<TFrontmatter = Record<string, unknown>>(
+  opts: ParseCatalogOptions,
+): Promise<ParsedFile<TFrontmatter>[]> {
+  const files = await fastGlob(opts.globs, {
+    cwd: opts.repoRoot,
+    absolute: true,
+  });
+  const out: ParsedFile<TFrontmatter>[] = [];
+  for (const filePath of files) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    // Parse boundary: YAML frontmatter is genuinely external, untyped input.
+    // The caller declares the expected shape via `TFrontmatter`; the catalog's
+    // `_schema.json` (enforced by each validate-catalog.ts) is what guarantees
+    // it at runtime. This is honest boundary narrowing — NOT a fake ACL over an
+    // already-typed aggregate.
+    const frontmatter = normalizeFrontmatter(parsed.data) as TFrontmatter;
+    const rules = extractRulesFromBody(parsed.content);
+    out.push({
+      filePath,
+      relativePath: relative(opts.repoRoot, filePath),
+      frontmatter,
+      rules,
+    });
+  }
+  return out;
+}

package/dist/templates/monorepo/scripts/_catalog-runtime/repo-root.ts

@@ -0,0 +1,36 @@
+/**
+ * Locates the `aurora-catalyst` repo root by walking up from a start directory
+ * until a `package.json` with `name === 'aurora-catalyst'` is found.
+ *
+ * Shared by every catalog CLI so that paths resolve identically regardless of
+ * the process working directory.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function readPackageName(dir: string): string | null {
+  try {
+    const pkgPath = resolve(dir, 'package.json');
+    const raw = readFileSync(pkgPath, 'utf-8');
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed === 'object' && parsed !== null && 'name' in parsed) {
+      const name = (parsed as { name: unknown }).name;
+      return typeof name === 'string' ? name : null;
+    }
+    return null;
+  } catch {
+    // No package.json here (or unreadable): keep walking up.
+    return null;
+  }
+}
+
+export function findRepoRoot(startDir: string = process.cwd()): string {
+  let dir = resolve(startDir);
+  while (dir !== '/') {
+    if (readPackageName(dir) === 'aurora-catalyst') return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`Could not locate aurora repo root from ${startDir}`);
+}