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

package/src/lib/delivery/branches.ts

@@ -0,0 +1,108 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import type { CapabilityConfig } from "../orchestrator/types";
+
+const execFileAsync = promisify(execFile);
+
+export type ProtectionReason = "default" | "pattern";
+
+export interface BranchProtection {
+  protected: boolean;
+  reason: ProtectionReason | null;
+}
+
+export interface ProtectionOptions {
+  defaultBranch: string;
+  /** Configured glob patterns; `*` stays within one path segment, `**` crosses segments. */
+  patterns: readonly string[];
+}
+
+function globToRegExp(pattern: string): RegExp {
+  const source = pattern
+    .split("**")
+    .map((part) =>
+      part
+        .split("*")
+        .map((literal) => literal.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[^/]*"),
+    )
+    .join(".*");
+  return new RegExp(`^${source}$`);
+}
+
+/** A branch is protected when it is the default branch or matches a pattern. */
+export function classifyBranch(branch: string, options: ProtectionOptions): BranchProtection {
+  if (branch === options.defaultBranch) return { protected: true, reason: "default" };
+  if (options.patterns.some((pattern) => globToRegExp(pattern).test(branch))) {
+    return { protected: true, reason: "pattern" };
+  }
+  return { protected: false, reason: null };
+}
+
+/** Protected-branch patterns from the companion's openspec capability config. */
+export function configuredProtectedPatterns(capabilities: readonly CapabilityConfig[]): string[] {
+  const openspec = capabilities.find((capability) => capability.name === "openspec");
+  const patterns = openspec?.protectedBranches;
+  return Array.isArray(patterns)
+    ? patterns.filter((pattern): pattern is string => typeof pattern === "string")
+    : [];
+}
+
+/** Read-only local Git queries against a Working Repository. Nothing here touches the network. */
+export interface WorkingRepoGit {
+  /** Checked-out branch, or null in a detached HEAD. */
+  currentBranch(): Promise<string | null>;
+  /** `origin/HEAD`, then an existing `origin/main` or `origin/master`, then `init.defaultBranch`, then `main`. */
+  defaultBranch(): Promise<string>;
+  /** The `origin` remote URL, or null without one. */
+  remoteUrl(): Promise<string | null>;
+  /** One-line summaries of commits on HEAD that no remote-tracking branch contains. */
+  unpushedCommits(): Promise<string[]>;
+  /** True when the branch exists locally or as `origin/<branch>`. */
+  branchExists(branch: string): Promise<boolean>;
+}
+
+export function workingRepoGit(repoPath: string): WorkingRepoGit {
+  const run = async (...args: string[]): Promise<string | null> => {
+    try {
+      const { stdout } = await execFileAsync("git", args, { cwd: repoPath });
+      return stdout.trim();
+    } catch {
+      return null;
+    }
+  };
+
+  const remoteTip = async (branch: string): Promise<string | null> =>
+    (await run("rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`)) || null;
+  const defaultBranch = async (): Promise<string> => {
+    const remoteHead = await run("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD");
+    if (remoteHead) return remoteHead.replace(/^origin\//, "");
+    for (const candidate of ["main", "master"]) {
+      // oxlint-disable-next-line no-await-in-loop -- the steps are a decision chain
+      if (await remoteTip(candidate)) return candidate;
+    }
+    return (await run("config", "--get", "init.defaultBranch")) || "main";
+  };
+
+  const currentBranch = async (): Promise<string | null> =>
+    (await run("symbolic-ref", "--quiet", "--short", "HEAD")) || null;
+
+  return {
+    currentBranch,
+    defaultBranch,
+    async remoteUrl() {
+      return (await run("remote", "get-url", "origin")) || null;
+    },
+    async unpushedCommits() {
+      const log = await run("log", "--oneline", "HEAD", "--not", "--remotes");
+      return log ? log.split("\n").filter(Boolean) : [];
+    },
+    async branchExists(branch: string) {
+      for (const ref of [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`]) {
+        if ((await run("rev-parse", "--verify", "--quiet", ref)) !== null) return true;
+      }
+      return false;
+    },
+  };
+}

package/src/lib/delivery/environment.ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+
+import type { WorkingRepoGit } from "./branches";
+import type { ForgeRepo } from "./forge";
+
+export interface WorkingRepoInfo {
+  path: string;
+  /** Full repository path from the `origin` remote (`acme/platform/api`), or null without one. */
+  slug: string | null;
+  forgeRepo: ForgeRepo | null;
+  git: WorkingRepoGit;
+}
+
+/** The companion, the Working Repository with its remote identity, and protected-branch patterns. */
+export interface DeliveryEnvironment {
+  companionPath: string;
+  workingRepo: WorkingRepoInfo | null;
+  protectedPatterns: string[];
+  /**
+   * Host of a repository other than the Working Repository, from a linked checkout's
+   * `origin` remote, else the Working Repository's host; null when neither is known.
+   */
+  hostOf?: (repository: string) => Promise<string | null>;
+}
+
+/** `dir` relative to the companion, with forward slashes. */
+export function companionRelative(environment: DeliveryEnvironment, dir: string): string {
+  return path.relative(environment.companionPath, dir).split(path.sep).join("/");
+}

package/src/lib/delivery/forge.ts

@@ -0,0 +1,279 @@
+/**
+ * Forge adapters answer read-only questions about a repository and its Delivery Branch:
+ * the default branch, whether the branch is protected, and which PR has it as head. GitHub (github.com) is the only adapter; every other host
+ * falls back to asking the user. Every failure is returned, never thrown, and the token
+ * is scrubbed from anything a failure carries.
+ */
+
+import { errorMessage } from "../../runtime/error-message";
+import { pickProvenance, type MergeProvenance, type MergeState } from "./record";
+
+export interface ForgeRepo {
+  host: string;
+  /** Every path segment before the repository; nested groups keep theirs (`acme/platform`). */
+  owner: string;
+  repo: string;
+}
+
+export interface PullCandidate {
+  number: number;
+  url: string;
+  state: MergeState;
+}
+
+export interface PullDetail extends MergeProvenance {
+  number: number;
+  url: string;
+}
+
+export type PullClassification =
+  | { kind: "merged"; pr: PullDetail }
+  | { kind: "open"; pr: PullDetail }
+  | { kind: "closed-unmerged"; pr: PullDetail }
+  | { kind: "ambiguous"; candidates: PullCandidate[] }
+  | { kind: "none" };
+
+export type ForgeFailureReason = "permission" | "rate-limit" | "auth" | "network" | "unexpected";
+
+export interface ForgeFailure {
+  reason: ForgeFailureReason;
+  message: string;
+  /** The fine-grained read permission a `permission` failure lacks. */
+  permission?: string;
+  /** The HTTP status the forge answered, when it answered. */
+  status?: number;
+}
+
+export type ForgeOutcome<T> = { ok: true; value: T } | { ok: false; failure: ForgeFailure };
+
+export interface ForgeAdapter {
+  id: string;
+  defaultBranch(repo: ForgeRepo): Promise<ForgeOutcome<string>>;
+  /** Classifies the PRs whose head is `branch`; `prNumber` picks one of several. */
+  pullsForBranch(
+    repo: ForgeRepo,
+    branch: string,
+    prNumber?: number,
+  ): Promise<ForgeOutcome<PullClassification>>;
+}
+
+export type FetchLike = (
+  url: string,
+  init?: { headers?: Record<string, string> },
+) => Promise<Response>;
+
+export interface ForgeDeps {
+  fetch?: FetchLike;
+}
+
+/** Parses SSH, scp-style, and HTTPS remotes; credentials in a URL are discarded. */
+export function parseRemote(url: string): ForgeRepo | null {
+  const cleaned = url.trim();
+  let host: string;
+  let remotePath: string;
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(cleaned)) {
+    try {
+      const parsed = new URL(cleaned);
+      host = parsed.hostname;
+      remotePath = parsed.pathname;
+    } catch {
+      return null;
+    }
+  } else {
+    // `user@` is optional: an SSH config alias such as `work:org/repo` has none.
+    const scp = /^(?:[^/\s@]+@)?([^/\s:]{2,}):(.+)$/.exec(cleaned);
+    if (!scp) return null;
+    host = scp[1];
+    remotePath = scp[2];
+  }
+  if (!host) return null;
+  return forgeRepoOf(host, remotePath.replace(/\.git\/?$/, ""));
+}
+
+/** Splits a repository path at its last segment; null below two segments. */
+export function forgeRepoOf(host: string, path: string): ForgeRepo | null {
+  const parts = path.split("/").filter(Boolean);
+  if (parts.length < 2) return null;
+  return {
+    host: host.toLowerCase(),
+    owner: parts.slice(0, -1).join("/"),
+    repo: parts.at(-1) as string,
+  };
+}
+
+/** The repository's identity: its full path on the host, `owner/repo`. */
+export function repositoryPath(repo: ForgeRepo): string {
+  return `${repo.owner}/${repo.repo}`;
+}
+
+/** The adapter for a remote's host, or null when the host has none. */
+export function forgeFor(
+  repo: ForgeRepo,
+  token: string,
+  deps: ForgeDeps = {},
+): ForgeAdapter | null {
+  return repo.host === "github.com" ? githubForge(token, deps) : null;
+}
+
+/** Replaces every occurrence of the token, so no failure text can carry it. */
+function redactToken(text: string, token: string): string {
+  return token ? text.split(token).join("[redacted]") : text;
+}
+
+const GITHUB_API = "https://api.github.com";
+
+interface GithubPull {
+  number: number;
+  html_url: string;
+  state: string;
+  merged_at: string | null;
+  merge_commit_sha?: string | null;
+  merged_by?: { login?: string } | null;
+}
+
+function candidateState(pull: GithubPull): PullCandidate["state"] {
+  if (pull.merged_at) return "merged";
+  return pull.state === "open" ? "open" : "closed-unmerged";
+}
+
+function detail(pull: GithubPull): PullDetail {
+  return {
+    number: pull.number,
+    url: pull.html_url,
+    ...pickProvenance({
+      mergedAt: pull.merged_at ?? undefined,
+      mergeCommit: (pull.merged_at && pull.merge_commit_sha) || undefined,
+      mergedBy: pull.merged_by?.login,
+    }),
+  };
+}
+
+function repoPath(repo: ForgeRepo): string {
+  return `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.repo)}`;
+}
+
+export function githubForge(token: string, deps: ForgeDeps = {}): ForgeAdapter {
+  const fetchFn: FetchLike = deps.fetch ?? ((url, init) => fetch(url, init));
+
+  async function get<T>(apiPath: string, permission: string): Promise<ForgeOutcome<T>> {
+    let response: Response;
+    try {
+      response = await fetchFn(`${GITHUB_API}${apiPath}`, {
+        headers: {
+          accept: "application/vnd.github+json",
+          authorization: `Bearer ${token}`,
+          "x-github-api-version": "2022-11-28",
+          "user-agent": "mate-cli",
+        },
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        failure: {
+          reason: "network",
+          message: redactToken(`GitHub request failed: ${errorMessage(error)}`, token),
+        },
+      };
+    }
+    const fail = (
+      reason: ForgeFailureReason,
+      message: string,
+      extra: Pick<ForgeFailure, "permission"> = {},
+    ): ForgeOutcome<T> => ({
+      ok: false,
+      failure: {
+        reason,
+        message: redactToken(message, token),
+        ...extra,
+        ...(response.ok ? {} : { status: response.status }),
+      },
+    });
+    if (response.ok) {
+      try {
+        return { ok: true, value: (await response.json()) as T };
+      } catch (error) {
+        return fail(
+          "unexpected",
+          `GitHub answered with an unreadable body: ${errorMessage(error)}`,
+        );
+      }
+    }
+    if (response.status === 401) return fail("auth", "GitHub rejected the token (401).");
+    if (response.status === 403 && response.headers.get("x-ratelimit-remaining") === "0") {
+      return fail("rate-limit", "GitHub API rate limit reached (403).");
+    }
+    if (response.status === 403 || response.status === 404) {
+      return fail(
+        "permission",
+        `GitHub refused the request (${response.status}); the token needs ${permission} on this repository.`,
+        { permission },
+      );
+    }
+    return fail("unexpected", `GitHub answered ${response.status}.`);
+  }
+
+  return {
+    id: "github",
+    async defaultBranch(repo) {
+      const result = await get<{ default_branch?: string }>(repoPath(repo), "Metadata: read");
+      if (!result.ok) return result;
+      const branch = result.value.default_branch;
+      return branch
+        ? { ok: true, value: branch }
+        : {
+            ok: false,
+            failure: { reason: "unexpected", message: "GitHub named no default branch." },
+          };
+    },
+    async pullsForBranch(repo, branch, prNumber) {
+      const head = encodeURIComponent(`${repo.owner}:${branch}`);
+      const listPulls = (target: string) =>
+        get<GithubPull[]>(
+          `${target}/pulls?head=${head}&state=all&per_page=100`,
+          "Pull requests: read",
+        );
+      let listed = await listPulls(repoPath(repo));
+      if (!listed.ok) return listed;
+      let pullRepo = repoPath(repo);
+      if (listed.value.length === 0) {
+        // A fork's PR is opened on its parent; the head stays `<fork owner>:<branch>`.
+        const metadata = await get<{ parent?: { full_name?: string } }>(
+          repoPath(repo),
+          "Metadata: read",
+        );
+        const parent = metadata.ok ? metadata.value.parent?.full_name : undefined;
+        if (parent) {
+          pullRepo = `/repos/${parent.split("/").map(encodeURIComponent).join("/")}`;
+          listed = await listPulls(pullRepo);
+          if (!listed.ok) return listed;
+        }
+      }
+      const pulls =
+        prNumber === undefined
+          ? listed.value
+          : listed.value.filter((entry) => entry.number === prNumber);
+      if (pulls.length === 0) return { ok: true, value: { kind: "none" } };
+      if (pulls.length > 1) {
+        return {
+          ok: true,
+          value: {
+            kind: "ambiguous",
+            candidates: pulls
+              .map((entry) => ({
+                number: entry.number,
+                url: entry.html_url,
+                state: candidateState(entry),
+              }))
+              .toSorted((a, b) => a.number - b.number),
+          },
+        };
+      }
+      const [only] = pulls;
+      const state = candidateState(only);
+      if (state !== "merged") return { ok: true, value: { kind: state, pr: detail(only) } };
+      // The list omits the merger; only the single-PR endpoint carries it.
+      const full = await get<GithubPull>(`${pullRepo}/pulls/${only.number}`, "Pull requests: read");
+      return { ok: true, value: { kind: "merged", pr: detail(full.ok ? full.value : only) } };
+    },
+  };
+}

package/src/lib/delivery/overlap.ts

@@ -0,0 +1,202 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  activeChanges,
+  archiveAnchors,
+  changeNameOf,
+  changesDirOf,
+  deltaSpecs,
+} from "../change-layout";
+import { readFrontmatter } from "../frontmatter";
+import { isMateSchema } from "./stages";
+
+export interface RequirementEdit {
+  capability: string;
+  requirement: string;
+  operation: "MODIFIED" | "REMOVED";
+}
+
+export type DependencyWarning = { kind: "dependency"; change: string; message: string };
+
+export type PlanningWarning = {
+  kind: "incomplete-planning";
+  change: string;
+  artifacts: string[];
+  message: string;
+};
+
+export type ArchiveWarning =
+  | { kind: "overlap"; change: string; capability: string; requirement: string; message: string }
+  | DependencyWarning
+  | PlanningWarning;
+
+const SECTION = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/;
+const REQUIREMENT = /^###\s+Requirement:\s*(.+?)\s*$/;
+const TASK = /^\s*[-*]\s+\[([ xX])\]/;
+
+/** Requirements a change's delta specs MODIFY or REMOVE, by full capability path. */
+export async function deltaRequirementEdits(changeDir: string): Promise<RequirementEdit[]> {
+  const edits: RequirementEdit[] = [];
+  for (const { file, capability } of await deltaSpecs(changeDir)) {
+    if (capability === null) continue;
+    let source: string;
+    try {
+      source = await fs.readFile(path.join(changeDir, "specs", file), "utf8");
+    } catch {
+      continue;
+    }
+    let section: string | null = null;
+    for (const line of source.split(/\r?\n/)) {
+      const heading = SECTION.exec(line);
+      if (heading) {
+        section = heading[1];
+        continue;
+      }
+      if (line.startsWith("## ")) section = null;
+      const requirement = REQUIREMENT.exec(line);
+      if (requirement && (section === "MODIFIED" || section === "REMOVED")) {
+        edits.push({ capability, requirement: requirement[1], operation: section });
+      }
+    }
+  }
+  return edits;
+}
+
+/** Change names listed under `dependsOn` in any of the change's artifact frontmatter. */
+export async function declaredDependencies(changeDir: string): Promise<string[]> {
+  let files: string[];
+  try {
+    files = (await fs.readdir(changeDir)).filter((file) => file.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  const names = new Set<string>();
+  for (const file of files) {
+    // A malformed header declares nothing; validation reports it elsewhere.
+    const dependsOn = readFrontmatter(
+      await fs.readFile(path.join(changeDir, file), "utf8"),
+    )?.dependsOn;
+    for (const name of Array.isArray(dependsOn) ? dependsOn : [dependsOn]) {
+      if (typeof name === "string" && name.trim()) names.add(name.trim());
+    }
+  }
+  return [...names].toSorted();
+}
+
+async function archivedChangeNames(companionPath: string): Promise<Set<string>> {
+  return new Set((await archiveAnchors(companionPath)).map(changeNameOf));
+}
+
+/** True when the change's `tasks.md` has tasks and every one is checked. */
+async function tasksComplete(changeDir: string): Promise<boolean> {
+  let source: string;
+  try {
+    source = await fs.readFile(path.join(changeDir, "tasks.md"), "utf8");
+  } catch {
+    return false;
+  }
+  const marks = source.split(/\r?\n/).flatMap((line) => TASK.exec(line)?.[1] ?? []);
+  return marks.length > 0 && marks.every((mark) => mark !== " ");
+}
+
+/**
+ * Warnings shown before applying `change`: declared dependencies neither archived nor fully
+ * implemented, so the change would be built without the code it builds on. Never blocks.
+ */
+export async function applyWarnings(
+  companionPath: string,
+  change: string,
+): Promise<DependencyWarning[]> {
+  const changesDir = changesDirOf(companionPath);
+  const archived = await archivedChangeNames(companionPath);
+  const warnings: DependencyWarning[] = [];
+  for (const dependency of await declaredDependencies(path.join(changesDir, change))) {
+    if (archived.has(dependency) || (await tasksComplete(path.join(changesDir, dependency)))) {
+      continue;
+    }
+    warnings.push({
+      kind: "dependency",
+      change: dependency,
+      message: `${change} depends on ${dependency}, which is not implemented yet; apply ${dependency} first.`,
+    });
+  }
+  return warnings;
+}
+
+/**
+ * Warning for schema artifacts that `openspec status --change <change> --json` reports neither
+ * done nor skipped, e.g. a design missing after a `mate-minimal` change moved to `mate-v1`.
+ * Only Mate's schemas require every artifact; OpenSpec reports another schema's conditional
+ * artifacts (spec-driven's design) as `ready`, so those yield no warning, as does unparsable output.
+ */
+export function planningWarning(change: string, statusJson: string): PlanningWarning | null {
+  let status: { schemaName?: unknown; artifacts?: unknown };
+  try {
+    status = JSON.parse(statusJson) as typeof status;
+  } catch {
+    return null;
+  }
+  const { schemaName, artifacts } = status ?? {};
+  if (typeof schemaName !== "string" || !isMateSchema(schemaName)) return null;
+  if (!Array.isArray(artifacts)) return null;
+  const missing = artifacts
+    .filter((artifact): artifact is { id: string; status?: unknown } => {
+      return typeof artifact?.id === "string";
+    })
+    .filter(({ status }) => status !== "done" && status !== "skipped")
+    .map(({ id }) => id);
+  if (missing.length === 0) return null;
+  return {
+    kind: "incomplete-planning",
+    change,
+    artifacts: missing,
+    message: `${change} is missing planning artifacts its schema requires: ${missing.join(", ")}.`,
+  };
+}
+
+function requirementKey(edit: RequirementEdit): string {
+  return JSON.stringify([edit.capability, edit.requirement]);
+}
+
+/**
+ * Warnings shown before archiving `change`: another active change MODIFYing or REMOVing a
+ * requirement this change also MODIFIES or REMOVES, and declared dependencies that are not
+ * archived yet. Warnings inform; they never block archive.
+ */
+export async function archiveWarnings(
+  companionPath: string,
+  change: string,
+): Promise<ArchiveWarning[]> {
+  const changesDir = changesDirOf(companionPath);
+  const warnings: ArchiveWarning[] = [];
+
+  const own = await deltaRequirementEdits(path.join(changesDir, change));
+  if (own.length > 0) {
+    const ownKeys = new Set(own.map(requirementKey));
+    for (const other of await activeChanges(companionPath)) {
+      if (other === change) continue;
+      for (const edit of await deltaRequirementEdits(path.join(changesDir, other))) {
+        if (!ownKeys.has(requirementKey(edit))) continue;
+        warnings.push({
+          kind: "overlap",
+          change: other,
+          capability: edit.capability,
+          requirement: edit.requirement,
+          message: `${other} also changes ${edit.capability} › ${edit.requirement}; archiving ${other} later will replace this change's version of that requirement.`,
+        });
+      }
+    }
+  }
+
+  const archived = await archivedChangeNames(companionPath);
+  for (const dependency of await declaredDependencies(path.join(changesDir, change))) {
+    if (archived.has(dependency)) continue;
+    warnings.push({
+      kind: "dependency",
+      change: dependency,
+      message: `${change} depends on ${dependency}, which is not archived yet; archive ${dependency} first.`,
+    });
+  }
+  return warnings;
+}