@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/src/lib/delivery/refresh.ts

@@ -0,0 +1,174 @@
+import type { ForgeAdapter, ForgeFailure, ForgeRepo, PullCandidate } from "./forge";
+import {
+  pickProvenance,
+  sameRepository,
+  upsertDelivery,
+  type DeliveryRecord,
+  type MergeProvenance,
+  type MergeState,
+} from "./record";
+
+/** Why a branch's merge state must come from the user instead of the forge. */
+export type AnswerReason =
+  | "no-token"
+  | "unsupported-host"
+  | "forge-failure"
+  | "no-pr"
+  | "ambiguous"
+  | "direct";
+
+export interface BranchOutcome {
+  repository: string;
+  branch: string;
+  /** What is now known; `unknown` when the forge could not answer. */
+  result: MergeState | "ambiguous" | "none" | "unknown";
+  pr?: string;
+  candidates?: PullCandidate[];
+  failure?: ForgeFailure;
+  /** True when the user has to answer merged, not yet merged, or dropped. */
+  needsAnswer: boolean;
+  answerReason?: AnswerReason;
+}
+
+export type ForgeAccess =
+  | { adapter: ForgeAdapter; repo: ForgeRepo }
+  | { unavailable: "no-token" | "unsupported-host" };
+
+/** The clock, forge, and local Git a refresh reads. */
+export interface RefreshAccess {
+  now: () => Date;
+  forgeAccess: (repository: string) => Promise<ForgeAccess>;
+}
+
+export interface RefreshOptions extends RefreshAccess {
+  /** Restricts the refresh to one repository's delivery. */
+  repository?: string;
+  /** Shared across changes in one run, so a branch is asked about once. */
+  cache?: RefreshCache;
+}
+
+/** The PR number in a `…/pull/<n>` URL. */
+function prNumberFrom(url: string | undefined): number | undefined {
+  const match = url ? /\/pull\/(\d+)/.exec(url) : null;
+  return match ? Number(match[1]) : undefined;
+}
+
+/**
+ * Asks the forge about every branch delivery of a record (or the one repository named)
+ * and records each definite answer with source `forge`. A direct delivery is never settled
+ * here: it always needs the user's answer. Nothing is recorded for an ambiguous,
+ * missing, or failed lookup: those come back as outcomes needing an answer. A delivery the
+ * user answered as merged or dropped is skipped.
+ */
+export async function refreshRecord(
+  record: DeliveryRecord,
+  options: RefreshOptions,
+): Promise<{ record: DeliveryRecord; outcomes: BranchOutcome[] }> {
+  let next = record;
+  const outcomes: BranchOutcome[] = [];
+  const cache: RefreshCache = options.cache ?? new Map();
+
+  for (const delivery of record.deliveries) {
+    if (delivery.notApplicable !== undefined || !delivery.branch) continue;
+    if (options.repository && !sameRepository(delivery.repository, options.repository)) continue;
+    // A user answer of merged or dropped stands; the forge may still settle a "not yet merged".
+    if (delivery.merge?.source === "user" && delivery.merge.state !== "open") continue;
+    const { repository, branch } = delivery;
+    // A recorded PR URL picks that PR when several have the branch as head, unless it was dropped.
+    const prNumber = prNumberFrom(delivery.pr);
+    const direct = Boolean(delivery.direct);
+    // A direct delivery is checked in Git, a PR delivery on the forge: never share an answer.
+    const key = JSON.stringify([repository, branch, prNumber ?? null, direct]);
+
+    let outcome = cache.get(key);
+    if (!outcome) {
+      outcome = await lookup(repository, branch, direct, prNumber, options);
+      cache.set(key, outcome);
+    }
+    outcomes.push(outcome);
+
+    if (
+      outcome.result === "merged" ||
+      outcome.result === "open" ||
+      outcome.result === "closed-unmerged"
+    ) {
+      const merge = {
+        state: outcome.result,
+        source: "forge" as const,
+        checkedAt: options.now().toISOString(),
+        ...outcome.provenance,
+      };
+      next = upsertDelivery(next, repository, { merge, ...(outcome.pr ? { pr: outcome.pr } : {}) });
+    }
+  }
+  return { record: next, outcomes: outcomes.map(publicOutcome) };
+}
+
+/** Lookups by repository, branch, and PR number. */
+export type RefreshCache = Map<string, LookupOutcome>;
+
+interface LookupOutcome extends BranchOutcome {
+  provenance?: MergeProvenance;
+}
+
+function publicOutcome(outcome: LookupOutcome): BranchOutcome {
+  const { provenance: _provenance, ...rest } = outcome;
+  return rest;
+}
+
+async function lookup(
+  repository: string,
+  branch: string,
+  direct: boolean,
+  prNumber: number | undefined,
+  options: RefreshOptions,
+): Promise<LookupOutcome> {
+  const base = { repository, branch };
+  if (direct) {
+    // Git cannot tell this change's commits from the user's other pushes, so the user decides.
+    return { ...base, result: "unknown", needsAnswer: true, answerReason: "direct" };
+  }
+  const access = await options.forgeAccess(repository);
+  if ("unavailable" in access) {
+    return { ...base, result: "unknown", needsAnswer: true, answerReason: access.unavailable };
+  }
+  let answer = await access.adapter.pullsForBranch(access.repo, branch, prNumber);
+  // A recorded PR that is closed or gone must not hide a newer PR from the same branch.
+  if (
+    prNumber !== undefined &&
+    answer.ok &&
+    (answer.value.kind === "none" || answer.value.kind === "closed-unmerged")
+  ) {
+    const wider = await access.adapter.pullsForBranch(access.repo, branch);
+    if (wider.ok && wider.value.kind !== "none") answer = wider;
+  }
+  if (!answer.ok) {
+    return {
+      ...base,
+      result: "unknown",
+      failure: answer.failure,
+      needsAnswer: true,
+      answerReason: "forge-failure",
+    };
+  }
+  const value = answer.value;
+  if (value.kind === "none") {
+    return { ...base, result: "none", needsAnswer: true, answerReason: "no-pr" };
+  }
+  if (value.kind === "ambiguous") {
+    return {
+      ...base,
+      result: "ambiguous",
+      candidates: value.candidates,
+      needsAnswer: true,
+      answerReason: "ambiguous",
+    };
+  }
+  return {
+    ...base,
+    result: value.kind,
+    pr: value.pr.url,
+    needsAnswer: false,
+    provenance: pickProvenance(value.pr),
+  };
+}

package/src/lib/delivery/repository-access.ts

@@ -0,0 +1,97 @@
+import { classifyBranch, type BranchProtection } from "./branches";
+import { sameRepository } from "./record";
+import type { DeliveryEnvironment } from "./environment";
+import { forgeFor, forgeRepoOf, type ForgeDeps, type ForgeRepo } from "./forge";
+import type { ForgeAccess } from "./refresh";
+import { resolveForgeToken, type ForgeToken } from "./token";
+
+/** What delivery needs to know about one repository, from local Git or the forge. */
+export interface RepositoryAccess {
+  /** The Working Repository's from local Git; another's from the forge, else `main`. */
+  defaultBranch(): Promise<string>;
+  /** Protected when it is the default branch or matches a configured pattern. */
+  protection(branch: string): Promise<BranchProtection>;
+  forge(): Promise<ForgeAccess>;
+}
+
+export interface RepositoryAccessDeps {
+  resolveToken?: () => Promise<ForgeToken | null>;
+  forge?: ForgeDeps;
+}
+
+/**
+ * Access per repository, the Working Repository's through local Git first. The forge token
+ * is resolved at most once, and only when a lookup needs it.
+ */
+export function repositoryAccessFor(
+  environment: DeliveryEnvironment,
+  deps: RepositoryAccessDeps = {},
+): (repository: string) => RepositoryAccess {
+  let token: Promise<ForgeToken | null> | undefined;
+  const resolveToken = (): Promise<ForgeToken | null> =>
+    (token ??= (deps.resolveToken ?? (() => resolveForgeToken()))());
+  const accesses = new Map<string, RepositoryAccess>();
+
+  return (repository) => {
+    const key = repository.toLowerCase();
+    let access = accesses.get(key);
+    if (!access) {
+      const slug = environment.workingRepo?.slug;
+      const working = slug && sameRepository(slug, repository) ? environment.workingRepo : null;
+      const forgeRepo = async (): Promise<ForgeRepo | null> =>
+        working?.forgeRepo ?? otherForgeRepo(environment, repository);
+      let forgeAccess: Promise<ForgeAccess> | undefined;
+      const forge = (): Promise<ForgeAccess> =>
+        (forgeAccess ??= connect(forgeRepo, resolveToken, deps.forge));
+      const defaultBranch = working ? () => working.git.defaultBranch() : forgeDefaultBranch(forge);
+      access = {
+        defaultBranch,
+        protection: async (branch) =>
+          classifyBranch(branch, {
+            defaultBranch: await defaultBranch(),
+            patterns: environment.protectedPatterns,
+          }),
+        forge,
+      };
+      accesses.set(key, access);
+    }
+    return access;
+  };
+}
+
+/**
+ * Another repository's host comes from a linked checkout's remote, else the Working
+ * Repository's; never assumed. Null when no host is known.
+ */
+async function otherForgeRepo(
+  environment: DeliveryEnvironment,
+  repository: string,
+): Promise<ForgeRepo | null> {
+  const host = (await environment.hostOf?.(repository)) ?? environment.workingRepo?.forgeRepo?.host;
+  return host ? forgeRepoOf(host, repository) : null;
+}
+
+async function connect(
+  forgeRepo: () => Promise<ForgeRepo | null>,
+  resolveToken: () => Promise<ForgeToken | null>,
+  deps: ForgeDeps | undefined,
+): Promise<ForgeAccess> {
+  const repo = await forgeRepo();
+  if (!repo) return { unavailable: "unsupported-host" };
+  const resolved = await resolveToken();
+  if (!resolved) return { unavailable: "no-token" };
+  const adapter = forgeFor(repo, resolved.token, deps);
+  return adapter ? { adapter, repo } : { unavailable: "unsupported-host" };
+}
+
+/** Another repository's default branch from the forge, asked once; `main` when it cannot answer. */
+function forgeDefaultBranch(forge: () => Promise<ForgeAccess>): () => Promise<string> {
+  let known: Promise<string> | undefined;
+  return () =>
+    (known ??= (async () => {
+      const access = await forge();
+      if (!("adapter" in access)) return "main";
+      const answer = await access.adapter.defaultBranch(access.repo);
+      return answer.ok ? answer.value : "main";
+    })());
+}

package/src/lib/delivery/stages.ts

@@ -0,0 +1,111 @@
+/**
+ * The Delivery Path stage contract: the action-named sequence Studio and the docs check
+ * read. Review stages come from a schema's artifacts.
+ */
+
+/** A skill stage runs a Mate skill; a human stage is a person reviewing one artifact. */
+export type DeliveryStageKind = "skill" | "human";
+
+interface StageBase {
+  /** Stable identifier, e.g. `archive` or `review-specs`. */
+  id: string;
+  /** The action the stage performs, e.g. `Archive change`. */
+  label: string;
+  kind: DeliveryStageKind;
+  /** Optional stages can be skipped and never block a later stage. */
+  optional: boolean;
+}
+
+export type SkillStageId =
+  | "clarify-intent"
+  | "explore"
+  | "propose"
+  | "apply"
+  | "inspect-outcome"
+  | "refine-code"
+  | "archive"
+  | "publish";
+
+export interface SkillStage extends StageBase {
+  id: SkillStageId;
+  kind: "skill";
+  /** The Mate skill that drives the stage. */
+  skill: string;
+}
+
+export interface ReviewStage extends StageBase {
+  kind: "human";
+  skill: null;
+  /** The schema artifact the person reviews. */
+  artifact: string;
+}
+
+export type DeliveryStage = SkillStage | ReviewStage;
+
+export interface DeliveryPath {
+  stages: DeliveryStage[];
+  /** False when the schema's artifacts could not be read, so reviews are unknown. */
+  reviewsKnown: boolean;
+}
+
+/** Artifact sets of the schemas Mate ships, in dependency order. */
+export const SCHEMA_ARTIFACTS = {
+  "mate-v1": ["proposal", "specs", "design", "tasks"],
+  "mate-minimal": ["specs", "tasks"],
+} as const satisfies Record<string, readonly string[]>;
+
+/** A schema Mate ships. */
+export type MateSchema = keyof typeof SCHEMA_ARTIFACTS;
+
+/** The schema every companion is set to. */
+export const DEFAULT_SCHEMA: MateSchema = "mate-v1";
+
+export function isMateSchema(schema: string): schema is MateSchema {
+  return Object.hasOwn(SCHEMA_ARTIFACTS, schema);
+}
+
+function skillStage(id: SkillStageId, label: string, skill: string, optional = false): SkillStage {
+  return { id, label, kind: "skill", skill, optional };
+}
+
+const BEFORE_REVIEWS: readonly SkillStage[] = [
+  skillStage("clarify-intent", "Clarify intent", "mate-clarify-intent", true),
+  skillStage("explore", "Explore change", "mate-explore-change"),
+  skillStage("propose", "Propose change", "mate-propose-change"),
+];
+
+const AFTER_REVIEWS: readonly SkillStage[] = [
+  skillStage("apply", "Apply change", "mate-apply-change"),
+  skillStage("inspect-outcome", "Inspect outcome", "mate-show-me", true),
+  skillStage("refine-code", "Refine code", "mate-simplify-code", true),
+  skillStage("archive", "Archive change", "mate-archive-change"),
+  skillStage("publish", "Publish companion artifacts", "mate-publish-artifact"),
+];
+
+/** Every skill a Delivery Path stage is driven by, in stage order. */
+export const DELIVERY_STAGE_SKILLS: readonly string[] = [...BEFORE_REVIEWS, ...AFTER_REVIEWS].map(
+  (stage) => stage.skill,
+);
+
+function reviewStage(artifact: string): ReviewStage {
+  return {
+    id: `review-${artifact}`,
+    label: `Review ${artifact}`,
+    kind: "human",
+    skill: null,
+    artifact,
+    optional: false,
+  };
+}
+
+/**
+ * The Delivery Path for one schema. `artifacts` are its artifact ids in dependency order;
+ * `undefined` means the schema could not be read, which yields the skill stages alone with
+ * `reviewsKnown: false` rather than a guessed review set.
+ */
+export function deliveryPath(artifacts: readonly string[] | undefined): DeliveryPath {
+  return {
+    stages: [...BEFORE_REVIEWS, ...(artifacts ?? []).map(reviewStage), ...AFTER_REVIEWS],
+    reviewsKnown: artifacts !== undefined,
+  };
+}

package/src/lib/delivery/token.ts

@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** The only environment variable a forge token is read from. */
+export const FORGE_TOKEN_ENV = "MATE_GIT_TOKEN";
+
+export interface ForgeToken {
+  token: string;
+  source: typeof FORGE_TOKEN_ENV | "gh";
+}
+
+export interface ForgeTokenDeps {
+  env?: Record<string, string | undefined>;
+  /** `gh auth token`, or null when the GitHub CLI is missing or signed out. */
+  ghToken?: () => Promise<string | null>;
+}
+
+/** Variables `gh auth token` would report instead of the stored login. */
+const GH_TOKEN_VARIABLES = [
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_ENTERPRISE_TOKEN",
+  "GITHUB_ENTERPRISE_TOKEN",
+];
+
+/** `env` without the token variables, so `gh` reports only its stored login. */
+export function ghAuthEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const scrubbed = { ...env };
+  for (const name of GH_TOKEN_VARIABLES) delete scrubbed[name];
+  return scrubbed;
+}
+
+async function defaultGhToken(): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("gh", ["auth", "token"], {
+      timeout: 10_000,
+      env: ghAuthEnv(process.env),
+    });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The forge token from `MATE_GIT_TOKEN`, then `gh auth token`. Other variables such as
+ * `GITHUB_TOKEN` are deliberately ignored so a broadly scoped CI token is never picked up.
+ * The returned value is for the forge request only: callers never print, log, or store it.
+ */
+export async function resolveForgeToken(deps: ForgeTokenDeps = {}): Promise<ForgeToken | null> {
+  const env = deps.env ?? process.env;
+  const fromEnv = env[FORGE_TOKEN_ENV]?.trim();
+  if (fromEnv) return { token: fromEnv, source: FORGE_TOKEN_ENV };
+  const fromGh = (await (deps.ghToken ?? defaultGhToken)())?.trim();
+  return fromGh ? { token: fromGh, source: "gh" } : null;
+}

package/src/lib/frontmatter.ts

@@ -0,0 +1,18 @@
+import { parse } from "yaml";
+
+/** A leading `---` block; group 1 is its YAML, the match ends after the closing line. */
+export const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+/** A Markdown file's leading YAML frontmatter; null when absent, malformed, or not a mapping. */
+export function readFrontmatter(source: string): Record<string, unknown> | null {
+  const header = FRONTMATTER_PATTERN.exec(source)?.[1];
+  if (header === undefined) return null;
+  try {
+    const parsed: unknown = parse(header);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/opencode-plugin-package.ts

@@ -40,11 +40,11 @@ export interface WarmPluginCacheResult {
 
 export const opencodePluginCacheDeps = {
   runInstall: (cwd: string, registry: string) =>
-    spawnSync("npm", ["install", "--no-audit", "--no-fund", "--silent", "--registry", registry], {
-      cwd,
-      encoding: "utf8" as const,
-      stdio: ["ignore", "pipe", "pipe"] as const,
-    }),
+    spawnSync(
+      "npm",
+      ["install", "--no-audit", "--no-fund", "--loglevel=error", "--registry", registry],
+      { cwd, encoding: "utf8" as const, stdio: ["ignore", "pipe", "pipe"] as const },
+    ),
 };
 
 export async function warmOpenCodePackageCache(

package/src/lib/openspec-cli.ts

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Set on every `openspec` process Mate starts. Mate decides the CLI version, so
+ * OpenSpec's own "update available" hint is wrong advice here.
+ */
+export const OPENSPEC_ENV = {
+  OPENSPEC_TELEMETRY: "0",
+  OPENSPEC_NO_UPDATE_CHECK: "1",
+} as const satisfies Record<string, string>;
+
+/** The bundled CLI, with its version when its manifest is readable, or the reinstall message. */
+export type OpenSpecLocation = { bin: string; version?: string } | { missing: string };
+
+export interface OpenSpecRunOptions {
+  cwd: string;
+  /** `capture` (default) collects output; `inherit` streams it to the terminal. */
+  stdio?: "capture" | "inherit";
+  /** Milliseconds before the child is killed. */
+  timeout?: number;
+  /** Base environment, `process.env` by default; {@link OPENSPEC_ENV} always wins. */
+  env?: NodeJS.ProcessEnv;
+  /** The CLI to run instead of the located one, e.g. when vendoring from a given CLI. */
+  bin?: string;
+}
+
+/**
+ * `code` is 1 when the CLI is missing or fails to start, with Mate's message as
+ * `stderr`; `null` when the child was killed. With `stdio: "inherit"` only that
+ * message is returned, the CLI's own output went to the terminal.
+ */
+export interface OpenSpecRun {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  /** Set when the bundled CLI is missing, so nothing ran. */
+  missing?: true;
+}
+
+export type RunOpenSpec = (args: string[], options: OpenSpecRunOptions) => Promise<OpenSpecRun>;
+
+function readVersion(bin: string): string | undefined {
+  try {
+    const manifest = path.resolve(path.dirname(bin), "../package.json");
+    return (JSON.parse(fs.readFileSync(manifest, "utf8")) as { version: string }).version;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Finds the OpenSpec CLI shipped with mate-core the way Node resolves it, never
+ * an `openspec` on `PATH`. `resolve` exists for layout tests.
+ */
+export function resolveOpenSpec(
+  resolve: (id: string) => string = require.resolve,
+): OpenSpecLocation {
+  let entryPath: string;
+  try {
+    // The package exports only `.` (dist/index.js); the binary sits beside dist/.
+    entryPath = resolve("@fission-ai/openspec");
+  } catch {
+    return { missing: "bundled OpenSpec CLI is missing. Reinstall Mate to restore it." };
+  }
+  const bin = path.resolve(path.dirname(entryPath), "../bin/openspec.js");
+  if (!fs.existsSync(bin)) {
+    return { missing: `bundled OpenSpec CLI is missing at ${bin}. Reinstall Mate to restore it.` };
+  }
+  return { bin, version: readVersion(bin) };
+}
+
+/** The one in-process seam: suites point `locate` at a stub CLI. */
+export const openSpecCliDeps = {
+  locate: (): OpenSpecLocation => resolveOpenSpec(),
+};
+
+/** The CLI every OpenSpec process Mate starts runs. */
+export function locateOpenSpec(): OpenSpecLocation {
+  return openSpecCliDeps.locate();
+}
+
+/** Runs the bundled CLI with {@link OPENSPEC_ENV} over the base environment. Never rejects. */
+export function runOpenSpec(args: string[], options: OpenSpecRunOptions): Promise<OpenSpecRun> {
+  const location = options.bin ? { bin: options.bin } : locateOpenSpec();
+  if ("missing" in location) {
+    return Promise.resolve({ code: 1, stdout: "", stderr: location.missing, missing: true });
+  }
+  return new Promise((resolve) => {
+    // A JS entry runs on the current runtime, not its `#!/usr/bin/env node` shebang,
+    // which needs an executable bit and `node` on PATH and does not work on Windows.
+    const [command, commandArgs] = location.bin.endsWith(".js")
+      ? [process.execPath, [location.bin, ...args]]
+      : [location.bin, args];
+    const child = spawn(command, commandArgs, {
+      cwd: options.cwd,
+      env: { ...(options.env ?? process.env), ...OPENSPEC_ENV },
+      stdio: options.stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+      ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => (stdout += chunk));
+    child.stderr?.on("data", (chunk: string) => (stderr += chunk));
+    child.once("error", (error) =>
+      resolve({ code: 1, stdout, stderr: `failed to run openspec: ${error.message}` }),
+    );
+    child.once("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}

package/src/lib/openspec-scopes.ts

@@ -0,0 +1,86 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRONTMATTER_PATTERN } from "./frontmatter";
+
+export const BOM = "";
+
+export interface ScopePair {
+  repository: string;
+  area: string;
+}
+
+/**
+ * A leading `<!-- mate:delta … -->` comment; group 1 is its YAML, the match ends after
+ * the closing `-->` line. OpenSpec skips HTML comments, so a delta carrying its metadata
+ * here passes `validate --strict`.
+ */
+export const DELTA_COMMENT_PATTERN =
+  /^<!--[ \t]*mate:delta[ \t]*\r?\n([\s\S]*?)\r?\n-->[ \t]*(?:\r?\n|$)/;
+
+/** Reads `scopes` from a `mate:delta` comment, else from frontmatter (proposals, legacy deltas). */
+export function parseScopes(source: string): ScopePair[] {
+  const text = source.startsWith(BOM) ? source.slice(BOM.length) : source;
+  const match = DELTA_COMMENT_PATTERN.exec(text) ?? FRONTMATTER_PATTERN.exec(text);
+  if (!match) return [];
+
+  try {
+    const parsed = parse(match[1]) as unknown;
+    if (!parsed || typeof parsed !== "object") return [];
+    const scopes = (parsed as Record<string, unknown>).scopes;
+    if (!Array.isArray(scopes)) return [];
+    return scopes.flatMap((entry) => {
+      if (!entry || typeof entry !== "object") return [];
+      const pair = entry as Record<string, unknown>;
+      return typeof pair.repository === "string" && typeof pair.area === "string"
+        ? [{ repository: pair.repository, area: pair.area }]
+        : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+async function specFiles(directory: string): Promise<string[]> {
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) return specFiles(full);
+      return entry.isFile() && entry.name.endsWith(".md") ? [full] : [];
+    }),
+  );
+  return nested.flat();
+}
+
+async function readOrEmpty(file: string): Promise<string> {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Repositories a change directory (active or archived) declares in its proposal
+ * frontmatter and delta `scopes`, deduplicated case-insensitively, first spelling kept.
+ */
+export async function scopedRepositories(changeDir: string): Promise<string[]> {
+  const sources = [
+    await readOrEmpty(path.join(changeDir, "proposal.md")),
+    ...(await Promise.all((await specFiles(path.join(changeDir, "specs"))).map(readOrEmpty))),
+  ];
+  const seen = new Map<string, string>();
+  for (const pair of sources.flatMap(parseScopes)) {
+    const key = pair.repository.toLowerCase();
+    if (!seen.has(key)) seen.set(key, pair.repository);
+  }
+  return [...seen.values()];
+}