@rungs/cli 0.1.0

package/src/render.ts

@@ -0,0 +1,222 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { walk } from './glob.ts';
+
+export type Harness = 'claude' | 'copilot' | 'cursor' | 'agents-md';
+
+export interface Rule {
+  file: string;
+  description?: string;
+  paths: string[];
+  enforcement?: string;
+  body: string;
+}
+
+export interface RenderEntry {
+  rule: string;
+  harness: Harness;
+  target?: string;
+  degraded?: string;
+  dropped?: string[];
+}
+
+const DO_NOT_EDIT = (source: string) =>
+  `Generated by \`rungs render\` from ${source}. Do not edit — your changes are overwritten.`;
+
+/** Parse `.ai/rules/*.md`: the neutral source ADR-0001 renders from. */
+export function readRules(repoRoot: string): Rule[] {
+  const dir = join(repoRoot, '.ai', 'rules');
+  const rules: Rule[] = [];
+  let files: string[];
+  try {
+    files = walk(dir).filter((f) => f.endsWith('.md') && f !== 'README.md');
+  } catch {
+    return rules;
+  }
+  for (const rel of files) {
+    const raw = readFileSync(join(dir, rel), 'utf8');
+    const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!m) continue;
+    const [, fm, body] = m;
+    rules.push({
+      file: rel,
+      description: scalar(fm, 'description'),
+      paths: list(fm, 'paths'),
+      enforcement: scalar(fm, 'enforcement'),
+      body: body.trim(),
+    });
+  }
+  return rules;
+}
+
+function scalar(fm: string, key: string): string | undefined {
+  const folded = fm.match(new RegExp(`^${key}:\\s*>-?\\s*\\n([\\s\\S]*?)(?=\\n\\S|$)`, 'm'));
+  if (folded) return folded[1].split('\n').map((l) => l.trim()).filter(Boolean).join(' ');
+  const plain = fm.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return plain?.[1].trim().replace(/^["']|["']$/g, '');
+}
+
+function list(fm: string, key: string): string[] {
+  const block = fm.match(new RegExp(`^${key}:\\s*\\n((?:\\s*-\\s*.+\\n?)+)`, 'm'));
+  if (!block) return [];
+  return [...block[1].matchAll(/^\s*-\s*(.+)$/gm)].map((m) => m[1].trim().replace(/^["']|["']$/g, ''));
+}
+
+/**
+ * Emit one rule into one harness's dialect. Full bodies, never pointers: a
+ * wrapper that references a shared file relies on the harness following the
+ * reference, and only some do. A rule that does not load is worth nothing.
+ */
+export function renderRule(rule: Rule, harness: Harness): { target: string; content: string; dropped: string[] } | { degraded: string } {
+  const stem = rule.file.replace(/\.md$/, '');
+  const source = `.ai/rules/${rule.file}`;
+  const dropped: string[] = [];
+
+  if (harness === 'claude') {
+    // No description field in a Claude rule; the routing is done by `paths`.
+    if (rule.description) dropped.push('description');
+    const fm = rule.paths.length ? `paths:\n${rule.paths.map((p) => `  - "${p}"`).join('\n')}\n` : '';
+    return {
+      target: `.claude/rules/${stem}.md`,
+      content: `---\n${fm}---\n\n<!-- ${DO_NOT_EDIT(source)} -->\n\n${rule.body}\n`,
+      dropped,
+    };
+  }
+
+  if (harness === 'copilot') {
+    const applyTo = rule.paths.length ? rule.paths.join(', ') : '**/*';
+    const desc = rule.description ? `description: '${rule.description.replace(/'/g, "''")}'\n` : '';
+    return {
+      target: `.github/instructions/${stem}.instructions.md`,
+      content: `---\n${desc}applyTo: '${applyTo}'\n---\n\n<!-- ${DO_NOT_EDIT(source)} -->\n\n${rule.body}\n`,
+      dropped,
+    };
+  }
+
+  if (harness === 'cursor') {
+    // `.mdc` is required — a plain .md in .cursor/rules is ignored entirely.
+    const desc = rule.description ? `description: ${rule.description}\n` : '';
+    const globs = rule.paths.length ? `globs: ${rule.paths.join(',')}\n` : '';
+    return {
+      target: `.cursor/rules/${stem}.mdc`,
+      content: `---\n${desc}${globs}alwaysApply: ${rule.paths.length === 0}\n---\n\n<!-- ${DO_NOT_EDIT(source)} -->\n\n${rule.body}\n`,
+      dropped,
+    };
+  }
+
+  // AGENTS.md-only harnesses have no glob scoping at all. Degrade explicitly
+  // and report it — never drop a rule silently.
+  const prefix = commonDirPrefix(rule.paths);
+  if (prefix) {
+    return {
+      target: `${prefix}/AGENTS.md`,
+      content: `<!-- ${DO_NOT_EDIT(source)} -->\n\n${rule.body}\n`,
+      dropped: ['description', 'paths (directory-scoped instead of glob)'],
+    };
+  }
+  return {
+    degraded: `routing-only: globs do not share a directory prefix, so root AGENTS.md gets a pointer to ${source}`,
+  };
+}
+
+function commonDirPrefix(paths: string[]): string | null {
+  if (!paths.length) return null;
+  const dirs = paths.map((p) => p.split('/').filter((s) => !s.includes('*')).join('/')).filter(Boolean);
+  if (dirs.length !== paths.length) return null;
+  const first = dirs[0];
+  return dirs.every((d) => d === first) && first.includes('/') ? first : null;
+}
+
+export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
+  const rules = readRules(repoRoot);
+  const entries: RenderEntry[] = [];
+  const routingOnly: Rule[] = [];
+
+  for (const rule of rules) {
+    for (const harness of harnesses) {
+      const out = renderRule(rule, harness);
+      if ('degraded' in out) {
+        entries.push({ rule: rule.file, harness, degraded: out.degraded });
+        if (harness === 'agents-md') routingOnly.push(rule);
+        continue;
+      }
+      const full = join(repoRoot, out.target);
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, out.content);
+      entries.push({ rule: rule.file, harness, target: out.target, dropped: out.dropped });
+    }
+  }
+
+  // The report said root AGENTS.md "gets a pointer" and nothing wrote one — a
+  // degradation notice that was itself a silent drop, in the function whose
+  // whole job is not to have those. Written now, as a managed block.
+  writeRoutingBlock(repoRoot, routingOnly, harnesses);
+  return entries;
+}
+
+function writeRoutingBlock(repoRoot: string, rules: Rule[], harnesses: Harness[]) {
+  if (!harnesses.includes('agents-md')) return;
+  const target = join(repoRoot, 'AGENTS.md');
+  if (!existsSync(target)) return;
+  const begin = '<!-- rungs:begin rules-routing -->';
+  const end = '<!-- rungs:end rules-routing -->';
+
+  const body = rules.length
+    ? [
+        begin,
+        '## Rules for specific paths',
+        '',
+        'This harness has no glob scoping, so these load only if you open them. **Read the one that',
+        'matches what you are editing before editing broadly.**',
+        '',
+        ...rules.map((r) => `- \`${r.paths.join('\`, \`')}\` → [\`.ai/rules/${r.file}\`](.ai/rules/${r.file})`),
+        end,
+      ].join('\n')
+    : '';
+
+  const existing = readFileSync(target, 'utf8');
+  const beginRe = /^[ \t]*<!--\s*rungs:begin rules-routing\s*-->[ \t]*$/m;
+  const endRe = /^[ \t]*<!--\s*rungs:end rules-routing\s*-->[ \t]*$/m;
+  const b = existing.match(beginRe);
+  const e = existing.match(endRe);
+  if (b && e && b.index !== undefined && e.index !== undefined) {
+    const next = existing.slice(0, b.index) + body.trim() + existing.slice(e.index + e[0].length);
+    writeFileSync(target, body ? next : next.replace(/\n{3,}/g, '\n\n'));
+    return;
+  }
+  if (body) writeFileSync(target, `${existing.replace(/\n+$/, '\n')}\n${body}\n`);
+}
+
+/**
+ * ADR-0001: a render that quietly dropped a rule reads identically to one that
+ * had nothing to drop, so every degradation lands here.
+ */
+export function writeReport(repoRoot: string, entries: RenderEntry[], harnesses: Harness[], stamp: string): string {
+  const lines = [
+    '# Render report',
+    '',
+    `> Generated by \`rungs render\` on ${stamp}. Do not edit.`,
+    '',
+    `Harnesses: ${harnesses.join(', ')}`,
+    '',
+    '| Rule | Harness | Emitted | Dropped / degraded |',
+    '| --- | --- | --- | --- |',
+  ];
+  for (const e of entries) {
+    const lost = e.degraded ?? (e.dropped?.length ? e.dropped.join(', ') : '—');
+    lines.push(`| \`${e.rule}\` | ${e.harness} | ${e.target ? `\`${e.target}\`` : '**not emitted**'} | ${lost} |`);
+  }
+  const degraded = entries.filter((e) => e.degraded).length;
+  const lossy = entries.filter((e) => e.dropped?.length).length;
+  lines.push(
+    '',
+    `${entries.length} renderings · ${lossy} lost a field · ${degraded} degraded.`,
+    '',
+    'A field listed as dropped is one the target harness has no way to express. It is recorded',
+    'here rather than silently discarded, so a repo can see what its harness choice costs it.',
+    '',
+  );
+  const content = lines.join('\n');
+  writeFileSync(join(repoRoot, '.ai', 'render-report.md'), content);
+  return content;
+}

package/src/substitute.ts

@@ -0,0 +1,78 @@
+import type { Manifest } from './types.ts';
+
+export type Params = Record<string, Record<string, unknown>>;
+
+/**
+ * `{{param}}` substitution, in file contents and in path segments. No
+ * conditionals, no loops — ADR-0003. A module that needs a conditional is two
+ * modules, or reaches file content through a managed block.
+ *
+ * `${{ … }}` is never substituted: GitHub Actions expressions share the
+ * delimiter, and without the passthrough the `ci` module corrupts its own
+ * workflow file at install — a broken file rather than an error.
+ */
+export function substitute(text: string, module: string, params: Params): string {
+  return text.replace(/(^|[^$])\{\{([a-z_.]+)\}\}/g, (whole, lead: string, ref: string) => {
+    const [a, b] = ref.includes('.') ? ref.split('.') : [module, ref];
+    const value = params[a]?.[b];
+    if (value === undefined) return whole; // leave it visible rather than emitting an empty string
+    return lead + format(value);
+  });
+}
+
+function format(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map((x) => JSON.stringify(x)).join(', ')}]`;
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  return String(v);
+}
+
+/** Defaults from every manifest, with explicit overrides applied on top. */
+export function resolveParams(mods: Manifest[], overrides: Params = {}): Params {
+  const out: Params = {};
+  for (const m of mods) {
+    out[m.name] = {};
+    for (const [k, spec] of Object.entries(m.params)) out[m.name][k] = spec.default;
+  }
+  // A default may itself reference another module's parameter, e.g. findings'
+  // register living at `docs/{{backlog.root}}/FINDINGS.md`. Resolve after all
+  // defaults are in place, and only one level — a chain would be a template
+  // language arriving through the back door.
+  for (const m of mods) {
+    for (const [k, v] of Object.entries(out[m.name])) {
+      if (typeof v === 'string' && v.includes('{{')) out[m.name][k] = substitute(v, m.name, out);
+    }
+  }
+  for (const [mod, vals] of Object.entries(overrides)) {
+    out[mod] = { ...(out[mod] ?? {}), ...vals };
+  }
+  return out;
+}
+
+/** Comment syntax for a managed block, chosen by the target file. */
+export function markers(targetPath: string, module: string, version: string) {
+  const hash = /\.(toml|ya?ml|gitignore|gitattributes|sh|ps1|conf|properties)$|(^|\/)\.(gitignore|gitattributes)$/.test(
+    targetPath,
+  );
+  return hash
+    ? { begin: `# rungs:begin ${module}@${version}`, end: `# rungs:end ${module}` }
+    : { begin: `<!-- rungs:begin ${module}@${version} -->`, end: `<!-- rungs:end ${module} -->` };
+}
+
+/**
+ * Replace an existing managed block, or append one. Content outside every block
+ * is the user's and is never touched — that is what makes the upgrade story
+ * mechanical and divergence a decision rather than an error.
+ */
+export function mergeBlock(existing: string, fragment: string, module: string): string {
+  const beginRe = new RegExp(`^[ \\t]*(?:<!--|#)\\s*rungs:begin ${module}(?:@[\\w.\\-]+)?\\s*(?:-->)?[ \\t]*$`, 'm');
+  const endRe = new RegExp(`^[ \\t]*(?:<!--|#)\\s*rungs:end ${module}\\s*(?:-->)?[ \\t]*$`, 'm');
+  const b = existing.match(beginRe);
+  const e = existing.match(endRe);
+  if (b && e && b.index !== undefined && e.index !== undefined && e.index > b.index) {
+    const before = existing.slice(0, b.index);
+    const after = existing.slice(e.index + e[0].length);
+    return `${before}${fragment.trim()}${after}`;
+  }
+  const sep = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${sep}${fragment.trim()}\n`;
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+/** Shapes read from a module's `module.toml`. See ADR-0003 for the format. */
+
+export interface ParamSpec {
+  description?: string;
+  default?: unknown;
+  allowed?: unknown[];
+  pattern?: string;
+  required?: boolean;
+  /**
+   * Marks a *behavioural* parameter: it changes what the CLI does rather than
+   * being substituted into a template, so it never appears as `{{name}}`.
+   * Without this the dead-parameter check reports it, and the obvious "fix"
+   * deletes the parameter that decides which harnesses exist.
+   */
+  consumed_by?: string;
+}
+
+export interface GateSpec {
+  id: string;
+  kind: 'declared' | 'command';
+  engine?: string;
+  table?: string;
+  command?: string;
+  tier?: string;
+  /** A hook is a gate with a lifecycle trigger rather than a runner trigger. */
+  trigger?: string;
+  matcher?: string;
+  why?: string;
+}
+
+export interface ParadigmSpec {
+  id: string;
+  paths?: string[];
+  compare?: string;
+  note?: string;
+}
+
+export interface InferSpec {
+  param: string;
+  pattern?: string;
+  min?: number;
+  scope?: string[];
+  exclude?: string[];
+  paths?: Record<string, string>;
+  /**
+   * A regex that settles the value outright, ahead of frequency. Frequency
+   * alone made `findings` propose the backlog's prefix, because a register
+   * cites work items more often than it defines its own ids.
+   */
+  anchor?: string;
+  anchor_name?: string;
+  /** Values that share the id shape but are never ids — `UTF-8`, `SHA-256`. */
+  exclude_values?: string[];
+}
+
+export interface DetectSpec {
+  paths?: string[];
+  markers?: string[];
+  /** Files to scan for markers when path existence is not discriminating. */
+  marker_paths?: string[];
+  paradigm?: ParadigmSpec[];
+  infer?: InferSpec[];
+  adopt_as?: { kind: string; paths?: string[]; note?: string }[];
+}
+
+export interface Provenance {
+  sources: string[];
+  patterns: string[];
+  incident: string;
+}
+
+export interface Manifest {
+  name: string;
+  version: string;
+  rung: number;
+  summary: string;
+  requires: string[];
+  conflicts: string[];
+  params: Record<string, ParamSpec>;
+  gates: GateSpec[];
+  detect: DetectSpec;
+  provenance: Provenance;
+  threshold?: { metric: string; minimum: number; confirm?: boolean };
+  /** Absolute path to the module directory. */
+  dir: string;
+}
+
+/** One of ADR-0004's six states, for one module in one repo. */
+export type DetectState =
+  | 'absent'
+  | 'ours-current'
+  | 'ours-diverged'
+  | 'theirs'
+  | 'paradigm'
+  | 'unknown';
+
+export interface DetectResult {
+  module: string;
+  state: DetectState;
+  /** Detect globs that matched, with a sample of what they hit. */
+  matchedPaths: { pattern: string; count: number; sample: string[] }[];
+  matchedMarkers: string[];
+  paradigm?: { id: string; note?: string; compare?: string; matched: string[] };
+  /** Parameters detection *proposes*. Never used to conclude presence. */
+  proposals: { param: string; value: string; evidence: string }[];
+  /** Set when the repo installed this module: what we wrote, and whether it still says so. */
+  ours?: { version: string; current: string[]; stale: string[]; diverged: string[]; missing: string[]; kept: string[] };
+  /** Existing artifacts that would adopt as `command` gates or similar. */
+  adoptable: { kind: string; count: number; sample: string[]; note?: string }[];
+}