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

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;
+}

package/src/lib/delivery/record-delivery.ts

@@ -0,0 +1,196 @@
+import type { ProtectionReason } from "./branches";
+import { locateChange, type ChangeLocation } from "../change-layout";
+import { companionRelative, type DeliveryEnvironment } from "./environment";
+import {
+  defaultDeliveryBranch,
+  findDelivery,
+  readOrUnlinkedRecord,
+  settleChangeDir,
+  upsertDelivery,
+  writeDeliveryRecord,
+  type DeliveryRecord,
+  type DeliverySettlement,
+  type MergeState,
+} from "./record";
+import {
+  refreshRecord,
+  type BranchOutcome,
+  type RefreshAccess,
+  type RefreshCache,
+} from "./refresh";
+import {
+  repositoryAccessFor,
+  type RepositoryAccess,
+  type RepositoryAccessDeps,
+} from "./repository-access";
+
+/** Edits to one repository's delivery, applied in this order around an optional refresh. */
+export interface DeliveryEdit {
+  delivery?: { branch: string; direct: boolean } | { notApplicable: string };
+  /** Informational PR URL; also picks the PR a refresh asks about. */
+  pr?: string;
+  /** The user's answer, recorded after any refresh with source `user`. */
+  confirm?: MergeState;
+}
+
+export interface DeliveryRequest {
+  changes: string[];
+  /**
+   * The delivery to edit, and the only one refreshed unless `refreshAll`. Without it the
+   * Working Repository's delivery is edited and every delivery is refreshed.
+   */
+  repository?: string;
+  edit?: DeliveryEdit;
+  /** Ask the forge for each branch's merge state; a direct delivery needs the user's answer instead. */
+  refresh?: boolean;
+  /** Refresh every delivery even when `repository` names the one to edit. */
+  refreshAll?: boolean;
+  /** Archived changes may be edited; otherwise only active ones are found. */
+  includeArchived?: boolean;
+  /** A change left without any delivery answers `needsBranch` and nothing is written. */
+  requireDelivery?: boolean;
+}
+
+export type DeliveryRefusal =
+  | { reason: "unknown-change"; change: string }
+  | { reason: "no-repository" }
+  | { reason: "protected-branch"; branch: string; protection: ProtectionReason | null }
+  | {
+      reason: "no-delivery-branch";
+      change: string;
+      repository: string;
+      for: "pr" | "confirm";
+    };
+
+export interface DeliveryResult {
+  change: string;
+  /** Companion-relative path of the change directory. */
+  path: string;
+  archived: boolean;
+  record: DeliveryRecord;
+  settlement: DeliverySettlement;
+  /** Lookups made by the refresh, including the ones the user must answer. */
+  outcomes: BranchOutcome[];
+}
+
+export interface NeedsBranch {
+  change: string;
+  record: DeliveryRecord;
+  /** `change/<change-name>` when that branch exists in the Working Repository. */
+  suggestedBranch: string | null;
+}
+
+export type DeliveryOutcome =
+  | { refusal: DeliveryRefusal }
+  | { needsBranch: NeedsBranch }
+  /** Every record is already written when the request edited or refreshed. */
+  | { results: DeliveryResult[] };
+
+export interface RecordDeliveryDeps extends RepositoryAccessDeps {
+  now?: () => Date;
+  repositoryAccess?: (repository: string) => RepositoryAccess;
+}
+
+function hasDeliveryBranch(record: DeliveryRecord, repository: string): boolean {
+  return Boolean(findDelivery(record, repository)?.branch);
+}
+
+/**
+ * Reads, edits, refreshes, and writes the Delivery Records of `request.changes`. Every
+ * change resolves before any record is written, so a refusal leaves no partial update; a
+ * request without an edit or refresh only reads. Network requests go only to the forge:
+ * for another repository's default branch, and to refresh. `--direct` is
+ * accepted on any branch; a protected one requires it.
+ */
+export async function recordDelivery(
+  environment: DeliveryEnvironment,
+  request: DeliveryRequest,
+  deps: RecordDeliveryDeps = {},
+): Promise<DeliveryOutcome> {
+  const { edit = {} } = request;
+  const now = deps.now ?? (() => new Date());
+  const access = deps.repositoryAccess ?? repositoryAccessFor(environment, deps);
+
+  const located: Array<ChangeLocation & { change: string }> = [];
+  for (const change of request.changes) {
+    const location = await locateChange(environment.companionPath, change);
+    if (!location || (location.archived && !request.includeArchived)) {
+      return { refusal: { reason: "unknown-change", change } };
+    }
+    located.push({ ...location, change });
+  }
+
+  const repository = request.repository ?? environment.workingRepo?.slug ?? null;
+  const edits = edit.delivery !== undefined || edit.pr !== undefined || edit.confirm !== undefined;
+  if (edits && !repository) return { refusal: { reason: "no-repository" } };
+  if (repository && edit.delivery && "branch" in edit.delivery) {
+    const { branch, direct } = edit.delivery;
+    const protection = await access(repository).protection(branch);
+    if (protection.protected && !direct) {
+      return { refusal: { reason: "protected-branch", branch, protection: protection.reason } };
+    }
+  }
+
+  const refreshAccess: RefreshAccess = {
+    now,
+    forgeAccess: (repo) => access(repo).forge(),
+  };
+  const cache: RefreshCache = new Map();
+  const resolved: Array<DeliveryResult & { dir: string }> = [];
+
+  for (const { change, dir, archived } of located) {
+    let record = await readOrUnlinkedRecord(dir, change);
+    if (repository && edit.delivery) {
+      record = upsertDelivery(record, repository, edit.delivery);
+    }
+
+    if (request.requireDelivery && record.deliveries.length === 0) {
+      const suggested = defaultDeliveryBranch(change);
+      const exists = (await environment.workingRepo?.git.branchExists(suggested)) ?? false;
+      return { needsBranch: { change, record, suggestedBranch: exists ? suggested : null } };
+    }
+
+    if (repository && edit.pr !== undefined) {
+      if (!hasDeliveryBranch(record, repository)) {
+        return { refusal: { reason: "no-delivery-branch", change, repository, for: "pr" } };
+      }
+      record = upsertDelivery(record, repository, { pr: edit.pr });
+    }
+
+    let outcomes: BranchOutcome[] = [];
+    if (request.refresh) {
+      const refreshed = await refreshRecord(record, {
+        ...refreshAccess,
+        cache,
+        ...(request.repository && !request.refreshAll ? { repository: request.repository } : {}),
+      });
+      record = refreshed.record;
+      outcomes = refreshed.outcomes;
+    }
+
+    if (repository && edit.confirm !== undefined) {
+      if (!hasDeliveryBranch(record, repository)) {
+        return { refusal: { reason: "no-delivery-branch", change, repository, for: "confirm" } };
+      }
+      record = upsertDelivery(record, repository, {
+        merge: { state: edit.confirm, source: "user", checkedAt: now().toISOString() },
+      });
+    }
+
+    resolved.push({
+      dir,
+      change: record.change,
+      path: companionRelative(environment, dir),
+      archived,
+      record,
+      settlement: await settleChangeDir(dir, record),
+      outcomes,
+    });
+  }
+
+  if (edits || request.refresh) {
+    for (const { dir, record } of resolved) await writeDeliveryRecord(dir, record);
+  }
+  const results = resolved.map(({ dir: _dir, ...result }) => result);
+  return { results };
+}