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

package/src/lib/change-layout.ts

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { pathIsDirectory } from "./fs-utils";
+
+/**
+ * Where a change lives in a Companion Repository: the active `openspec/changes/<name>/`
+ * directory, its dated archive `openspec/changes/archive/YYYY-MM-DD-<name>/`, and the
+ * canonical specs its delta specs map to. Only directories count, and only names are read.
+ */
+
+/** Companion-relative POSIX paths. */
+export const CHANGES_RELATIVE_DIR = "openspec/changes";
+export const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
+export const SPECS_RELATIVE_DIR = "openspec/specs";
+
+const ARCHIVE_DIR_NAME = "archive";
+
+/**
+ * One path segment: no separator, NUL, or leading dot (so never `.`, `..`, or hidden).
+ * Wider than OpenSpec's kebab-case, so archives made under older rules still resolve.
+ */
+const SEGMENT = /^[^./\\\0][^/\\\0]*$/;
+
+/** The `YYYY-MM-DD-<name>` anchor `openspec archive` gives an archived change. */
+const ANCHOR = /^(\d{4}-\d{2}-\d{2})-(.+)$/;
+
+export function changesDirOf(companionPath: string): string {
+  return path.join(companionPath, ...CHANGES_RELATIVE_DIR.split("/"));
+}
+
+export function archiveDirOf(companionPath: string): string {
+  return path.join(companionPath, ...ARCHIVE_RELATIVE_DIR.split("/"));
+}
+
+/** A change name or archive anchor: one path segment that is not the archive directory. */
+export function isChangeName(candidate: string): boolean {
+  return SEGMENT.test(candidate) && candidate !== ARCHIVE_DIR_NAME;
+}
+
+export interface Anchor {
+  date: string;
+  name: string;
+}
+
+/** `2026-01-02-acme` → `{date: "2026-01-02", name: "acme"}`; null for anything else, `2026-01-02-` included. */
+export function parseAnchor(candidate: string): Anchor | null {
+  const match = ANCHOR.exec(candidate);
+  if (!match || !isChangeName(match[2])) return null;
+  return { date: match[1], name: match[2] };
+}
+
+/** The change name of an archive anchor (`2026-01-02-acme` → `acme`); other names pass through. */
+export function changeNameOf(anchorOrName: string): string {
+  return parseAnchor(anchorOrName)?.name ?? anchorOrName;
+}
+
+async function directoryNames(dir: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Active change names, sorted. */
+export async function activeChanges(companionPath: string): Promise<string[]> {
+  return (await directoryNames(changesDirOf(companionPath))).filter(isChangeName).toSorted();
+}
+
+/** Archive anchors, optionally only those of change `name`, sorted oldest first. */
+export async function archiveAnchors(companionPath: string, name?: string): Promise<string[]> {
+  return (await directoryNames(archiveDirOf(companionPath)))
+    .filter((anchor) => {
+      const parsed = parseAnchor(anchor);
+      return parsed !== null && (name === undefined || parsed.name === name);
+    })
+    .toSorted();
+}
+
+export interface ChangeLocation {
+  dir: string;
+  archived: boolean;
+}
+
+/**
+ * Resolves a change name or anchor to its directory: the archive an anchor names exactly,
+ * else the active change, else the newest archive of that name. Anything that is not a
+ * single change-name segment resolves to nothing.
+ */
+export async function locateChange(
+  companionPath: string,
+  target: string,
+): Promise<ChangeLocation | null> {
+  if (!isChangeName(target)) return null;
+  const archiveDir = archiveDirOf(companionPath);
+  if (parseAnchor(target) && (await pathIsDirectory(path.join(archiveDir, target)))) {
+    return { dir: path.join(archiveDir, target), archived: true };
+  }
+  const active = path.join(changesDirOf(companionPath), target);
+  if (await pathIsDirectory(active)) return { dir: active, archived: false };
+  const newest = (await archiveAnchors(companionPath, target)).at(-1);
+  return newest ? { dir: path.join(archiveDir, newest), archived: true } : null;
+}
+
+export interface DeltaSpec {
+  /** POSIX path under the change's `specs/`, e.g. `identity/user-auth/spec.md`. */
+  file: string;
+  /** The companion-relative canonical path the file maps to. */
+  canonical: string;
+  /** The capability path of a `spec.md` below `specs/`; null for any other file. */
+  capability: string | null;
+}
+
+/**
+ * Every file below `dir` at any depth, as sorted POSIX paths relative to it. Reads directory
+ * entry names only, never contents; an unreadable directory contributes nothing.
+ */
+export async function filesBelow(dir: string): Promise<string[]> {
+  const walk = async (current: string, relative: string): Promise<string[]> => {
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const nested = await Promise.all(
+      entries.map(async (entry) => {
+        const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) return walk(path.join(current, entry.name), entryRelative);
+        return entry.isFile() ? [entryRelative] : [];
+      }),
+    );
+    return nested.flat();
+  };
+  return (await walk(dir, "")).toSorted();
+}
+
+/**
+ * Every file under the change's `specs/`, at any depth, sorted. Reads directory entry
+ * names only, never contents. A change without `specs/` has none.
+ */
+export async function deltaSpecs(changeDir: string): Promise<DeltaSpec[]> {
+  const files = await filesBelow(path.join(changeDir, "specs"));
+  return files.map((file) => {
+    const capability = path.posix.dirname(file);
+    return {
+      file,
+      canonical: `${SPECS_RELATIVE_DIR}/${file}`,
+      capability: path.posix.basename(file) === "spec.md" && capability !== "." ? capability : null,
+    };
+  });
+}

package/src/lib/components/wizard-header.tsx

@@ -1,5 +1,7 @@
 import { Box, Text } from "ink";
 
+import { BRAND_ACCENT } from "../../brand/palette";
+
 interface WizardHeaderProps {
   title: string;
   step: number;
@@ -12,7 +14,7 @@ export function WizardHeader({ title, step, totalSteps }: WizardHeaderProps) {
   return (
     <Box borderStyle="round" width="100%">
       <Box flexDirection="column" flexGrow={1} marginLeft={1}>
-        <Text bold color="green">
+        <Text bold color={BRAND_ACCENT}>
           mate framework
         </Text>
         <Box justifyContent="space-between">

package/src/lib/context-mode-package.ts

@@ -54,9 +54,17 @@ function validateContextModeNodeRuntime(): void {
 export async function validateContextModePackage(companionPath: string): Promise<void> {
   validateContextModeNodeRuntime();
   const root = getContextModePackageRoot(companionPath);
-  const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8")) as {
-    version?: string;
-  };
+  let manifestText: string;
+  try {
+    manifestText = await fs.readFile(path.join(root, "package.json"), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    throw new Error(
+      `Expected ${getContextModePackageReference()} at ${root}; it is not installed. Re-run \`mate companion setup\`.`,
+      { cause: error },
+    );
+  }
+  const manifest = JSON.parse(manifestText) as { version?: string };
   if (manifest.version !== CONTEXT_MODE_VERSION) {
     throw new Error(
       `Expected ${getContextModePackageReference()} at ${root}; found ${manifest.version ?? "an unknown version"}. Re-run \`mate companion setup\`.`,
@@ -72,6 +80,15 @@ export async function validateContextModePackage(companionPath: string): Promise
   );
 }
 
+export const contextModePackageDeps = {
+  runInstall: (cwd: string) =>
+    spawnSync(
+      "npm",
+      ["install", "--no-audit", "--no-fund", "--loglevel=error", "--registry", PUBLIC_NPM_REGISTRY],
+      { cwd, encoding: "utf8" as const, env: process.env },
+    ),
+};
+
 export async function installContextModePackage(companionPath: string): Promise<void> {
   validateContextModeNodeRuntime();
   const installDir = getContextModeInstallDir(companionPath);
@@ -85,15 +102,11 @@ export async function installContextModePackage(companionPath: string): Promise<
     ) + "\n",
     "utf8",
   );
-  const result = spawnSync(
-    "npm",
-    ["install", "--no-audit", "--no-fund", "--silent", "--registry", PUBLIC_NPM_REGISTRY],
-    { cwd: installDir, encoding: "utf8", env: process.env },
-  );
+  const result = contextModePackageDeps.runInstall(installDir);
   if (result.error || result.status !== 0) {
-    throw new Error(
-      `Could not install ${getContextModePackageReference()}: ${result.error?.message ?? result.stderr?.trim() ?? `npm exited with ${result.status}`}`,
-    );
+    const cause =
+      result.error?.message ?? (result.stderr?.trim() || `npm exited with ${result.status}`);
+    throw new Error(`Could not install ${getContextModePackageReference()}: ${cause}`);
   }
   await validateContextModePackage(companionPath);
 }

package/src/lib/delivery/archive-change.ts

@@ -0,0 +1,154 @@
+import { locateChange } from "../change-layout";
+import { runOpenSpec, type RunOpenSpec } from "../openspec-cli";
+import { companionRelative, type DeliveryEnvironment } from "./environment";
+import { archiveWarnings, planningWarning, type ArchiveWarning } from "./overlap";
+import {
+  isPublishable,
+  settleDelivery,
+  type DeliveryRecord,
+  type DeliverySettlement,
+  type UnscopedDelivery,
+} from "./record";
+import {
+  recordDelivery,
+  type DeliveryEdit,
+  type DeliveryRefusal,
+  type RecordDeliveryDeps,
+} from "./record-delivery";
+import type { BranchOutcome } from "./refresh";
+
+export type ArchiveStatus = "archived" | "needs-branch" | "failed";
+
+export interface ArchiveResult {
+  status: ArchiveStatus;
+  change: string;
+  /** Companion-relative archive directory, once archived. */
+  path: string | null;
+  record: DeliveryRecord;
+  settlement: DeliverySettlement;
+  outcomes: BranchOutcome[];
+  warnings: ArchiveWarning[];
+  /** `needs-branch` only: the branch to suggest, when it exists. */
+  suggestedBranch?: string | null;
+  message: string;
+}
+
+export interface ArchiveRequest {
+  change: string;
+  /** The repository `delivery` is recorded for; defaults to the Working Repository. */
+  repository?: string;
+  /** Recorded before the refresh, as `artifact link` would. */
+  delivery?: DeliveryEdit["delivery"];
+  /** Archive with an unlinked record instead of answering `needs-branch`. */
+  skipBranch?: boolean;
+}
+
+export type ArchiveOutcome = { refusal: DeliveryRefusal } | { result: ArchiveResult };
+
+export interface ArchiveChangeDeps extends RecordDeliveryDeps {
+  runOpenSpec?: RunOpenSpec;
+  /**
+   * Called once before `openspec archive` starts, so warnings are visible even when the
+   * archive fails or hangs. Never called for `needs-branch` or a refusal.
+   */
+  onWarnings?: (warnings: ArchiveWarning[], unscoped: UnscopedDelivery[]) => void;
+}
+
+/**
+ * The Archive change stage: records and refreshes the delivery, collects overlap,
+ * dependency, and incomplete-planning warnings, then runs `openspec archive`. Without a
+ * recorded delivery and no `skipBranch`, nothing is archived and the result is
+ * `needs-branch`. Merge state is reported, never a refusal.
+ */
+export async function archiveChange(
+  environment: DeliveryEnvironment,
+  request: ArchiveRequest,
+  deps: ArchiveChangeDeps = {},
+): Promise<ArchiveOutcome> {
+  const { change } = request;
+  const outcome = await recordDelivery(
+    environment,
+    {
+      changes: [change],
+      ...(request.repository ? { repository: request.repository } : {}),
+      ...(request.delivery ? { edit: { delivery: request.delivery } } : {}),
+      refresh: true,
+      // The settlement covers every repository, so each delivery's merge state is refreshed.
+      refreshAll: true,
+      requireDelivery: !request.skipBranch,
+    },
+    deps,
+  );
+  if ("refusal" in outcome) return outcome;
+
+  const runner = deps.runOpenSpec ?? runOpenSpec;
+  const cwd = environment.companionPath;
+  const [overlap, status] = await Promise.all([
+    archiveWarnings(environment.companionPath, change),
+    runner(["status", "--change", change, "--json"], { cwd }),
+  ]);
+  const planning = status.code === 0 ? planningWarning(change, status.stdout) : null;
+  const warnings = [...overlap, ...(planning ? [planning] : [])];
+
+  if ("needsBranch" in outcome) {
+    const { record, suggestedBranch } = outcome.needsBranch;
+    return {
+      result: {
+        status: "needs-branch",
+        change,
+        path: null,
+        record,
+        settlement: settleDelivery(record),
+        outcomes: [],
+        warnings,
+        suggestedBranch,
+        message: `No delivery branch is recorded for ${change}. Re-run with --branch <branch>, --not-applicable <reason>, or --skip-branch.`,
+      },
+    };
+  }
+
+  const [{ record, settlement, outcomes }] = outcome.results;
+  deps.onWarnings?.(warnings, settlement.unscoped);
+
+  const run = await runner(["archive", change, "--yes"], { cwd });
+  if (run.code !== 0) {
+    const detail = (run.stderr.trim() || run.stdout.trim()).split("\n").slice(-5).join("\n");
+    return {
+      result: {
+        status: "failed",
+        change,
+        path: null,
+        record,
+        settlement,
+        outcomes,
+        warnings,
+        message: `openspec archive ${change} failed (exit ${run.code ?? "unknown"}): ${detail}`,
+      },
+    };
+  }
+
+  const archived = await locateChange(environment.companionPath, change);
+  return {
+    result: {
+      status: "archived",
+      change,
+      path: archived?.archived ? companionRelative(environment, archived.dir) : null,
+      record,
+      settlement,
+      outcomes,
+      warnings,
+      message: archivedMessage(change, settlement),
+    },
+  };
+}
+
+function archivedMessage(change: string, settlement: DeliverySettlement): string {
+  if (isPublishable(settlement.status)) {
+    return `Archived ${change}; it can be published with mate-publish-artifact.`;
+  }
+  const missing =
+    settlement.missing.length > 0
+      ? ` No delivery is recorded for ${settlement.missing.join(", ")}, which its scopes name.`
+      : "";
+  return `Archived ${change}; publication waits until its delivery is merged (${settlement.status}).${missing}`;
+}

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("/");
+}