@uniqbit/mate-core 0.15.0-canary.1 → 0.15.0-canary.3

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.0-canary.1",
+  "version": "0.15.0-canary.3",
   "license": "MIT",
   "files": [
-    "src/"
+    "src/",
+    "wrappers/",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./plugins": "./src/plugins.ts",
+    "./runtime": "./src/runtime/index.ts",
+    "./opencode": "./src/opencode/index.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -15,13 +21,28 @@
   },
   "scripts": {
     "test": "CI=1 bun test",
+    "typecheck": "bunx tsc --noEmit -p ../../tsconfig.json",
     "lint": "oxlint src/",
     "lint:fix": "oxlint src/ --fix",
     "format": "oxfmt src/",
     "format:check": "oxfmt src/ --check"
   },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.3",
+    "@opentui/core": "^0.4.5",
+    "@opentui/keymap": "^0.4.5",
+    "@opentui/solid": "^0.4.5",
+    "ink": "^7.1.0",
+    "react": "^19.2.7",
+    "react-doctor": "0.8.1",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.0"
+  },
   "devDependencies": {
-    "@types/bun": "^1.3.14"
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.0.1",
+    "@types/react": "^19.2.17",
+    "@types/semver": "^7.7.1"
   },
   "engines": {
     "node": "24.x"

package/src/cli/commands/artifact/artifact.ts

@@ -0,0 +1,22 @@
+import { usage } from "../../usage";
+import { runArtifactFinishCommand } from "./finish";
+
+/**
+ * @command mate artifact <subcommand>
+ * @description Dispatches to the supported `artifact` subcommands. Prints usage
+ * and sets a non-zero exit code for an unrecognized subcommand.
+ */
+export async function runArtifactCommand(
+  subcommand: string | undefined,
+  argv: string[],
+): Promise<void> {
+  switch (subcommand) {
+    case "finish":
+      await runArtifactFinishCommand(argv);
+      return;
+    default:
+      console.error(`Unknown artifact command: ${subcommand ?? ""}`);
+      console.error(usage());
+      process.exitCode = 1;
+  }
+}

package/src/cli/commands/artifact/extract-repo-name.ts

@@ -0,0 +1,35 @@
+/**
+ * Extract repository name from a git URL.
+ * Handles SSH (git@host:user/repo.git and ssh://git@host:port/user/repo.git),
+ * HTTPS (https://host/user/repo.git),
+ * and URLs without .git suffix.
+ */
+export function extractRepoName(url: string): string | null {
+  if (!url || !url.trim()) {
+    return null;
+  }
+
+  const cleaned = url.trim();
+  let repositoryPath: string;
+
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(cleaned)) {
+    try {
+      repositoryPath = new URL(cleaned).pathname;
+    } catch {
+      return null;
+    }
+  } else if (/^[^/\s@]+@[^/\s:]+:.+/.test(cleaned)) {
+    // Handle scp-style SSH URLs: git@github.com:user/repo.git
+    repositoryPath = cleaned.slice(cleaned.indexOf(":") + 1);
+  } else {
+    repositoryPath = cleaned.replace(/^https?:\/\//i, "");
+  }
+
+  const lastPart = repositoryPath.split("/").filter(Boolean).at(-1);
+  if (!lastPart) {
+    return null;
+  }
+
+  // Strip .git suffix
+  return lastPart.replace(/\.git$/, "");
+}

package/src/cli/commands/artifact/finish/command.ts

@@ -0,0 +1,160 @@
+import { resolveForCapability } from "../../../../lib/orchestrator/framework-context";
+import type { LaunchContext } from "../../../../lib/orchestrator/framework-context";
+import type { CapabilityConfig } from "../../../../lib/orchestrator/types";
+import { WorkingRepoRequiredError } from "../../../../lib/orchestrator/types";
+import { parseFlags } from "../../../parse-flags";
+import { ensureUnambiguousCompanion } from "../../shared/companion-selection";
+import { runFinishEngine } from "./engine";
+import type { FinishContext, FinisherFactory } from "./finisher";
+import { defaultGitOps, type GitOps } from "./git";
+import { DEFAULT_FINISHER_TYPE, knownFinisherTypes, selectFinisher } from "./registry";
+
+export interface FinishCommandDeps {
+  ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
+  resolveContext?: (cwd: string) => Promise<LaunchContext>;
+  loadCapabilities?: (context: LaunchContext) => Promise<CapabilityConfig[]>;
+  selectFinisher?: (type: string) => FinisherFactory | undefined;
+  git?: (companionPath: string, workingRepoPath?: string) => GitOps;
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+const VALUE_FLAGS = new Set(["--type"]);
+
+/** First non-flag token, skipping the value of any value-taking flag (e.g. `--type x`). */
+function positionalName(argv: string[]): string | undefined {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (VALUE_FLAGS.has(token)) {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--")) continue;
+    return token;
+  }
+  return undefined;
+}
+
+async function defaultLoadCapabilities(context: LaunchContext): Promise<CapabilityConfig[]> {
+  const config = await context.configStore.load();
+  return config.capabilities ?? [];
+}
+
+/**
+ * @command mate artifact finish <name>
+ * @description Finishes and archives a completed artifact/change named `<name>`.
+ * Resolves the launch context for the current working repo, loads the enabled
+ * capabilities, selects a {@link FinisherFactory} for `--type` (defaulting to
+ * `DEFAULT_FINISHER_TYPE`, e.g. an OpenSpec change), and — if that finisher is
+ * enabled for this repo's capabilities — runs {@link runFinishEngine} to
+ * validate, produce, and commit/push the finish artifacts via {@link GitOps}.
+ * @flags
+ * - `<name>` — required positional: the change/artifact name to finish.
+ * - `--type <type>` — finisher type to use; see `knownFinisherTypes()`.
+ * - `--force` — bypass the completion guard; unrelated companion work is always preserved.
+ * - `--no-push` — commit locally but skip pushing.
+ * - `--json` — emit machine-readable JSON result instead of human-readable text.
+ * @remarks No-ops (with a message on stderr) when the selected finisher is
+ * disabled for the repo's configured capabilities — nothing is validated,
+ * produced, or mutated in that case.
+ */
+export async function runArtifactFinishCommand(
+  argv: string[],
+  deps: FinishCommandDeps = {},
+): Promise<void> {
+  const emitOut = deps.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const emitErr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  const flags = parseFlags(argv);
+  const force = flags.force === true;
+  const noPush = flags["no-push"] === true;
+  const json = flags.json === true;
+  const type = typeof flags.type === "string" ? flags.type : DEFAULT_FINISHER_TYPE;
+  const name = positionalName(argv);
+
+  if (!name) {
+    emitErr("mate: artifact finish requires a change name.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const selectFinisherFn = deps.selectFinisher ?? selectFinisher;
+  const finisherFactory = selectFinisherFn(type);
+  if (!finisherFactory) {
+    emitErr(
+      `mate: unknown artifact type "${type}". Known types: ${knownFinisherTypes().join(", ")}.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const ensureCompanion = deps.ensureUnambiguousCompanion ?? ensureUnambiguousCompanion;
+  if (!(await ensureCompanion(process.cwd()))) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolveContext = deps.resolveContext ?? ((cwd: string) => resolveForCapability(cwd));
+  let context: LaunchContext;
+  try {
+    context = await resolveContext(process.cwd());
+  } catch (err) {
+    if (err instanceof WorkingRepoRequiredError) {
+      emitErr(err.message);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  const loadCapabilities = deps.loadCapabilities ?? defaultLoadCapabilities;
+  const capabilities = await loadCapabilities(context);
+
+  const finishContext: FinishContext = {
+    companionPath: context.companionPath,
+    repositoryId: context.repositoryId,
+    repository: context.repository,
+  };
+  const finisher = finisherFactory(finishContext);
+  if (!finisher.isEnabled(capabilities)) {
+    // No-op with message: nothing was validated, produced, or mutated.
+    emitErr(finisher.disabledReason);
+    return;
+  }
+
+  let git: GitOps;
+  try {
+    git = (deps.git ?? defaultGitOps)(
+      context.companionPath,
+      context.repository?.path ?? process.env.MATE_REPO_PATH,
+    );
+  } catch (err) {
+    const message = `mate: finish Git guard rejected the target: ${String(err)}`;
+    if (json) {
+      emitOut(
+        JSON.stringify({
+          type,
+          name,
+          anchorName: null,
+          tag: null,
+          resumed: false,
+          step: "commit",
+          status: "error",
+          conflictedPaths: [],
+          local: { committed: false, tagged: false, pushed: false },
+          message,
+        }),
+      );
+    } else {
+      emitErr(message);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  await runFinishEngine(
+    finisher,
+    { name, force, noPush },
+    { git, json, stdout: emitOut, stderr: emitErr },
+  );
+}

package/src/cli/commands/artifact/finish/engine.ts

@@ -0,0 +1,261 @@
+import type { ArtifactFinisher, Produced } from "./finisher";
+import type { GitOps } from "./git";
+
+/** Pipeline step a {@link FinishResult} refers to (generic across artifact kinds). */
+export type FinishStep =
+  | "validate"
+  | "complete-guard"
+  | "dirty-guard"
+  | "produce"
+  | "cap-sync"
+  | "commit"
+  | "sync-remote"
+  | "tag"
+  | "push"
+  | "done";
+
+export type FinishStatus = "ok" | "conflict" | "error" | "skipped";
+
+/**
+ * Machine-readable result emitted with `--json`. The finish skill parses this to
+ * decide whether to hand a rebase conflict to a human, or to drive the remaining
+ * tag + push after resolving one.
+ */
+export interface FinishResult {
+  type: string;
+  name: string;
+  anchorName: string | null;
+  tag: string | null;
+  /** True when the artifact was already produced and the engine skipped that step. */
+  resumed: boolean;
+  step: FinishStep;
+  status: FinishStatus;
+  conflictedPaths: string[];
+  local: { committed: boolean; tagged: boolean; pushed: boolean };
+  message: string;
+}
+
+export interface EngineOptions {
+  name: string;
+  force: boolean;
+  noPush: boolean;
+}
+
+export interface EngineDeps {
+  git: GitOps;
+  json: boolean;
+  stdout: (line: string) => void;
+  stderr: (line: string) => void;
+}
+
+/**
+ * Runs the fixed finish pipeline for a resolved {@link ArtifactFinisher}:
+ * (validate → guards) → produce* → cap sync → scoped commit → sync-remote → tag → push,
+ * where produce is skipped when the artifact is already produced (resume). The git,
+ * remote-sync, conflict-handoff, and rollback machinery is identical for every
+ * artifact kind — only the finisher's steps vary.
+ */
+export async function runFinishEngine(
+  finisher: ArtifactFinisher,
+  options: EngineOptions,
+  deps: EngineDeps,
+): Promise<FinishResult> {
+  const { git } = deps;
+
+  const result: FinishResult = {
+    type: finisher.type,
+    name: options.name,
+    anchorName: null,
+    tag: null,
+    resumed: false,
+    step: "validate",
+    status: "ok",
+    conflictedPaths: [],
+    local: { committed: false, tagged: false, pushed: false },
+    message: "",
+  };
+
+  const emit = (): void => {
+    if (deps.json) {
+      deps.stdout(JSON.stringify(result));
+    } else if (result.status === "ok" || result.status === "skipped") {
+      deps.stdout(result.message);
+    } else {
+      deps.stderr(result.message);
+    }
+  };
+
+  const fail = (step: FinishStep, message: string, status: FinishStatus = "error"): void => {
+    result.step = step;
+    result.status = status;
+    result.message = message;
+    emit();
+    process.exitCode = 1;
+  };
+
+  // Resumable detection drives which guards apply and whether we produce.
+  const existing = await finisher.detectProduced(options.name);
+  const resuming = existing !== null;
+  result.resumed = resuming;
+
+  // Produce-time guards apply only to a fresh finish. An already-produced artifact
+  // was validated at produce time and is no longer "active" to validate against.
+  if (!resuming) {
+    const validation = await finisher.validate(options.name);
+    if (!validation.valid) {
+      fail("validate", `mate: ${options.name} failed validation:\n${validation.errors.join("\n")}`);
+      return result;
+    }
+    if (!options.force) {
+      const completeness = await finisher.isComplete(options.name);
+      if (!completeness.complete) {
+        fail(
+          "complete-guard",
+          `mate: ${options.name} is not complete (${completeness.remaining} of ${completeness.total} tasks remaining). Use --force to override.`,
+        );
+        return result;
+      }
+    }
+  }
+
+  const preFinishHead = await git.headRef();
+
+  // Never reset the whole companion: unrelated staged, unstaged, and untracked work
+  // belongs to the developer. Restore only paths returned by the finisher, and only for
+  // a FAILED produce with partial output. A successful produce may have MOVED data that
+  // exists nowhere else (an active change dir that was never committed), so post-produce
+  // failures must retain the produced paths — they are the resume state, not garbage.
+  const rollback = async (paths: string[] | undefined): Promise<void> => {
+    if (resuming || !paths || paths.length === 0) return;
+    try {
+      await git.restorePaths(preFinishHead, paths);
+    } catch {
+      // Best-effort; the failing-step message already surfaced the root cause.
+    }
+  };
+
+  // Produce (skipped when resuming).
+  let produced: Produced;
+  if (resuming) {
+    produced = existing!;
+  } else {
+    result.step = "produce";
+    const outcome = await finisher.produce(options.name);
+    if (!outcome.ok || !outcome.produced) {
+      await rollback(outcome.produced?.commitPaths);
+      fail(
+        "produce",
+        `mate: ${finisher.type} produce failed: ${outcome.message}${
+          outcome.produced
+            ? " Produced paths were restored."
+            : " Any partial output was retained for inspection."
+        }`,
+      );
+      return result;
+    }
+    produced = outcome.produced;
+  }
+  result.anchorName = produced.anchorName;
+  const tagName = `${finisher.type}/${produced.anchorName}`;
+  result.tag = tagName;
+
+  // Capability sync (only openspec-derived outputs are refreshed; commit stays scoped).
+  if (finisher.capSync) {
+    result.step = "cap-sync";
+    if (!(await finisher.capSync())) {
+      // Post-produce failure: retain the produced artifact — it is the resume state.
+      fail(
+        "cap-sync",
+        "mate: cap sync failed; the produced artifact was retained — re-run `mate artifact finish` to resume.",
+      );
+      return result;
+    }
+  }
+
+  // Commit — stage only the finisher's scoped paths. When resuming a prior finish that
+  // already committed, there is nothing to stage; treat that as the commit existing.
+  result.step = "commit";
+  try {
+    await git.add(produced.commitPaths);
+    if (await git.hasStagedChanges(produced.commitPaths)) {
+      await git.commit(
+        `chore(${finisher.type}): finish ${produced.anchorName}`,
+        produced.commitPaths,
+      );
+    }
+  } catch (err) {
+    // Post-produce failure: retain the produced artifact — it is the resume state.
+    fail(
+      "commit",
+      `mate: commit failed: ${String(err)}; the produced artifact was retained — re-run \`mate artifact finish\` to resume.`,
+    );
+    return result;
+  }
+  result.local.committed = true;
+
+  // Sync with remote before tagging (skipped with --no-push — no remote target).
+  if (!options.noPush) {
+    result.step = "sync-remote";
+    if (await git.hasUpstream()) {
+      try {
+        await git.fetch();
+      } catch (err) {
+        // Post-commit failure: retain the commit, do not roll back.
+        fail("sync-remote", `mate: fetch failed: ${String(err)}`);
+        return result;
+      }
+      const rebase = await git.rebaseOntoUpstream();
+      if (!rebase.ok) {
+        // Deliberate stop-for-handoff: commit exists, no tag, not pushed. Never auto-resolve.
+        result.step = "sync-remote";
+        result.status = "conflict";
+        result.conflictedPaths = rebase.conflictedPaths;
+        result.message =
+          "mate: rebase onto remote conflicted; resolve the conflict, complete the rebase, then finish tag + push.";
+        emit();
+        process.exitCode = 1;
+        return result;
+      }
+    }
+  }
+
+  // Tag the (rebased) finish commit — idempotent if a prior finish already tagged it.
+  result.step = "tag";
+  try {
+    if (!(await git.tagExists(tagName))) {
+      await git.tag(tagName, `Finish ${produced.anchorName}`);
+    }
+  } catch (err) {
+    // Post-commit failure: retain the commit, do not roll back.
+    fail("tag", `mate: tag failed: ${String(err)}`);
+    return result;
+  }
+  result.local.tagged = true;
+
+  if (options.noPush) {
+    result.step = "done";
+    result.status = "skipped";
+    result.message = `Finished ${produced.anchorName} locally (commit + tag ${tagName}); not pushed (--no-push).`;
+    emit();
+    return result;
+  }
+
+  // Push branch + tag together.
+  result.step = "push";
+  const push = await git.push();
+  if (!push.ok) {
+    // Post-tag push failure: retain commit + tag for retry, do not roll back.
+    result.status = "error";
+    result.message = `mate: push failed (commit and tag ${tagName} retained locally): ${push.error}`;
+    emit();
+    process.exitCode = 1;
+    return result;
+  }
+  result.local.pushed = true;
+
+  result.step = "done";
+  result.status = "ok";
+  result.message = `Finished ${produced.anchorName}: ${resuming ? "resumed, " : ""}committed, tagged ${tagName}, and pushed.`;
+  emit();
+  return result;
+}

package/src/cli/commands/artifact/finish/finisher.ts

@@ -0,0 +1,66 @@
+import type { CapabilityConfig, LinkedRepository } from "../../../../lib/orchestrator/types";
+
+export interface FinishContext {
+  companionPath: string;
+  repositoryId: string;
+  repository?: LinkedRepository;
+}
+
+/**
+ * The committable result of a finisher's terminal transform: what anchor the tag is
+ * derived from and which paths the finish commit is scoped to.
+ */
+export interface Produced {
+  /** Dated/immutable anchor the tag mirrors, e.g. `2026-07-14-my-change`. */
+  anchorName: string;
+  /** Pathspecs the finish commit stages — and nothing outside them. */
+  commitPaths: string[];
+}
+
+export interface ValidateResult {
+  valid: boolean;
+  errors: string[];
+}
+
+export interface CompleteResult {
+  complete: boolean;
+  total: number;
+  remaining: number;
+}
+
+export interface ProduceResult {
+  ok: boolean;
+  produced: Produced | null;
+  message: string;
+}
+
+/**
+ * The variable, per-artifact-kind half of `mate artifact finish`. The engine
+ * ({@link ../engine}) owns everything type-agnostic — scoped rollback,
+ * commit, remote-sync, conflict handoff, tag, push. A finisher supplies only what
+ * differs between artifact kinds (openspec changes today; ADRs, etc. later).
+ */
+export interface ArtifactFinisher {
+  /** Selector key, e.g. `openspec`. */
+  readonly type: string;
+  /** Message shown when {@link isEnabled} is false (the no-op-with-message case). */
+  readonly disabledReason: string;
+  /** Gate: is this finisher usable in the resolved capability set? */
+  isEnabled(capabilities: CapabilityConfig[]): boolean;
+  /** Never-bypassable guard. Not run when resuming an already-produced artifact. */
+  validate(name: string): Promise<ValidateResult>;
+  /** `--force`-overridable guard. Not run when resuming. */
+  isComplete(name: string): Promise<CompleteResult>;
+  /**
+   * Resumable detection: return the already-produced artifact (developer ran the
+   * transform by hand, or a prior finish half-completed) so the engine skips
+   * {@link produce} and continues to commit → tag → push, or null if not yet produced.
+   */
+  detectProduced(name: string): Promise<Produced | null>;
+  /** The terminal transform that yields committable outputs (openspec archive; …). */
+  produce(name: string): Promise<ProduceResult>;
+  /** Optional capability sync scoped to this finisher; resolves false on failure. */
+  capSync?(): Promise<boolean>;
+}
+
+export type FinisherFactory = (context: FinishContext) => ArtifactFinisher;