@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

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

@@ -3,10 +3,8 @@ 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"
+  | "resolve"
+  | "branch-guard"
   | "cap-sync"
   | "commit"
   | "sync-remote"
@@ -17,7 +15,7 @@ export type FinishStep =
 export type FinishStatus = "ok" | "conflict" | "error" | "skipped";
 
 /**
- * Machine-readable result emitted with `--json`. The finish skill parses this to
+ * Machine-readable result emitted with `--json`. The publish skill parses this to
  * decide whether to hand a rebase conflict to a human, or to drive the remaining
  * tag + push after resolving one.
  */
@@ -26,7 +24,7 @@ export interface FinishResult {
   name: string;
   anchorName: string | null;
   tag: string | null;
-  /** True when the artifact was already produced and the engine skipped that step. */
+  /** True when a prior publication already committed or tagged this anchor. */
   resumed: boolean;
   step: FinishStep;
   status: FinishStatus;
@@ -37,7 +35,6 @@ export interface FinishResult {
 
 export interface EngineOptions {
   name: string;
-  force: boolean;
   noPush: boolean;
 }
 
@@ -49,12 +46,23 @@ export interface EngineDeps {
 }
 
 /**
- * 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.
+ * Runs the fixed publication pipeline for a resolved {@link ArtifactFinisher}:
+ * resolve → branch guard → cap sync → scoped commit → sync-remote → tag → push. The
+ * git, remote-sync, and conflict-handoff machinery is identical for every artifact
+ * kind — only the finisher's resolution and cap sync vary.
+ *
+ * Isolation is a clean abort, not a rollback: the resolved artifact is durable input
+ * the pipeline never produced, so no step resets, restores, or deletes a path.
  */
+/** Lowest free `<base>.N` (N from 2), probed against the tags that exist now. */
+async function nextFreeTag(git: GitOps, base: string): Promise<string> {
+  for (let suffix = 2; suffix <= 1000; suffix += 1) {
+    const candidate = `${base}.${suffix}`;
+    if (!(await git.tagExists(candidate))) return candidate;
+  }
+  throw new Error(`exhausted ${base}.2 through ${base}.1000 without a free tag name`);
+}
+
 export async function runFinishEngine(
   finisher: ArtifactFinisher,
   options: EngineOptions,
@@ -68,7 +76,7 @@ export async function runFinishEngine(
     anchorName: null,
     tag: null,
     resumed: false,
-    step: "validate",
+    step: "resolve",
     status: "ok",
     conflictedPaths: [],
     local: { committed: false, tagged: false, pushed: false },
@@ -93,101 +101,73 @@ export async function runFinishEngine(
     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;
-      }
-    }
+  // Resolve the already-produced artifact. Nothing is mutated, so a refusal here — an
+  // unarchived target, or a name matching two archives — leaves the companion untouched.
+  result.step = "resolve";
+  const resolution = await finisher.resolve(options.name);
+  if (!resolution.ok) {
+    fail("resolve", resolution.message);
+    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;
+  const resolved: Produced = resolution.resolved;
+  result.anchorName = resolved.anchorName;
+  const baseTag = `${resolved.tagNamespace ?? finisher.type}/${resolved.anchorName}`;
+  // Provisional: a `suffix` publication only learns its final name at the tag
+  // step, once the remote sync has revealed tags created elsewhere. Early exits
+  // therefore report the tag this run would have created, not one that exists.
+  result.tag = baseTag;
+
+  // Branch guard — before cap sync, so a refusal mutates nothing at all. It applies to
+  // --no-push too: the local tag it creates is the anchor a later push would publish.
+  result.step = "branch-guard";
+  const [expectedBranch, currentBranch] = await Promise.all([
+    git.defaultBranch(),
+    git.currentBranch(),
+  ]);
+  if (currentBranch === null) {
+    fail(
+      "branch-guard",
+      `mate: publication requires the companion's default branch (${expectedBranch}); HEAD is detached.`,
+    );
+    return result;
+  }
+  if (currentBranch !== expectedBranch) {
+    fail(
+      "branch-guard",
+      `mate: refusing to publish from ${currentBranch}; the companion's default branch is ${expectedBranch}.`,
+    );
+    return result;
   }
-  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.",
+        "mate: cap sync failed; the resolved archive was left in place — re-run `mate artifact publish` to retry.",
       );
       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.
+  // Commit — stage only the finisher's scoped paths. Nothing to stage means a prior
+  // publication already committed this anchor, which is a resume rather than an error.
   result.step = "commit";
   try {
-    await git.add(produced.commitPaths);
-    if (await git.hasStagedChanges(produced.commitPaths)) {
+    await git.add(resolved.commitPaths);
+    if (await git.hasStagedChanges(resolved.commitPaths)) {
       await git.commit(
-        `chore(${finisher.type}): finish ${produced.anchorName}`,
-        produced.commitPaths,
+        resolved.commitSubject ?? `chore(${finisher.type}): finish ${resolved.anchorName}`,
+        resolved.commitPaths,
       );
+    } else {
+      result.resumed = true;
     }
   } 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.`,
+      `mate: commit failed: ${String(err)}; the resolved archive was left in place — re-run \`mate artifact publish\` to retry.`,
     );
     return result;
   }
@@ -219,12 +199,21 @@ export async function runFinishEngine(
     }
   }
 
-  // Tag the (rebased) finish commit — idempotent if a prior finish already tagged it.
+  // Tag the (rebased) publication commit — idempotent if a prior run already tagged
+  // it. A `suffix` publication that produced a fresh commit takes the next free name
+  // instead, so its commit gets an anchor rather than trailing someone else's tag.
   result.step = "tag";
+  let tagName = baseTag;
   try {
-    if (!(await git.tagExists(tagName))) {
-      await git.tag(tagName, `Finish ${produced.anchorName}`);
+    if (!(await git.tagExists(baseTag))) {
+      await git.tag(tagName, `Publish ${resolved.anchorName}`);
+    } else if (resolved.tagCollision === "suffix" && !result.resumed) {
+      tagName = await nextFreeTag(git, baseTag);
+      await git.tag(tagName, `Publish ${resolved.anchorName}`);
+    } else {
+      result.resumed = true;
     }
+    result.tag = tagName;
   } catch (err) {
     // Post-commit failure: retain the commit, do not roll back.
     fail("tag", `mate: tag failed: ${String(err)}`);
@@ -235,7 +224,7 @@ export async function runFinishEngine(
   if (options.noPush) {
     result.step = "done";
     result.status = "skipped";
-    result.message = `Finished ${produced.anchorName} locally (commit + tag ${tagName}); not pushed (--no-push).`;
+    result.message = `Published ${resolved.anchorName} locally (commit + tag ${tagName}); not pushed (--no-push).`;
     emit();
     return result;
   }
@@ -255,7 +244,7 @@ export async function runFinishEngine(
 
   result.step = "done";
   result.status = "ok";
-  result.message = `Finished ${produced.anchorName}: ${resuming ? "resumed, " : ""}committed, tagged ${tagName}, and pushed.`;
+  result.message = `Published ${resolved.anchorName}: ${result.resumed ? "resumed, " : ""}committed, tagged ${tagName}, and pushed.`;
   emit();
   return result;
 }

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

@@ -7,38 +7,38 @@ export interface FinishContext {
 }
 
 /**
- * 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.
+ * The committable result of resolving a publication target: what anchor the tag is
+ * derived from and which paths the publication 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. */
+  /** Pathspecs the publication commit stages — and nothing outside them. */
   commitPaths: string[];
+  /** Tag namespace preceding the anchor; defaults to the finisher's type. */
+  tagNamespace?: string;
+  /** Whole commit subject; defaults to `chore(<type>): finish <anchorName>`. */
+  commitSubject?: string;
+  /**
+   * Tag behaviour when the name is taken and this run produced a fresh commit.
+   * `reuse` (default) leaves the existing tag and pushes; `suffix` takes the
+   * lowest free `.N` so the fresh commit gets an anchor of its own. A resumed
+   * run reuses under either value: its commit is the tagged one already.
+   */
+  tagCollision?: "reuse" | "suffix";
 }
 
-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;
-}
+/** Outcome of {@link ArtifactFinisher.resolve}; the failure carries the user-facing refusal. */
+export type ResolveResult = { ok: true; resolved: Produced } | { ok: false; 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).
+ * The variable, per-artifact-kind half of `mate artifact publish`. The engine
+ * ({@link ../engine}) owns everything type-agnostic — branch guard, commit,
+ * remote-sync, conflict handoff, tag, push. A finisher supplies only what differs
+ * between artifact kinds (openspec changes today; ADRs, etc. later).
+ *
+ * Producing the artifact is not part of the interface: the archive-equivalent step
+ * for every artifact kind is its own workflow, and publishing is terminal over it.
  */
 export interface ArtifactFinisher {
   /** Selector key, e.g. `openspec`. */
@@ -47,18 +47,11 @@ export interface ArtifactFinisher {
   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.
+   * Resolve a target — a dated anchor or an unambiguous artifact name — to the already
+   * produced outputs. Mutates nothing a failure would have to undo.
    */
-  detectProduced(name: string): Promise<Produced | null>;
-  /** The terminal transform that yields committable outputs (openspec archive; …). */
-  produce(name: string): Promise<ProduceResult>;
+  resolve(target: string): Promise<ResolveResult>;
   /** Optional capability sync scoped to this finisher; resolves false on failure. */
   capSync?(): Promise<boolean>;
 }

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

@@ -12,15 +12,21 @@ export interface PushResult {
   error: string;
 }
 
+export type WorkingTreeChange = "new" | "modified";
+
 /**
  * Git operations the finish engine needs, injectable for deterministic tests. All
  * operations run against the companion working tree.
  */
 export interface GitOps {
-  /** Full SHA of the current HEAD (recorded pre-finish for rollback). */
-  headRef(): Promise<string>;
+  /** Checked-out branch name, or null in a detached HEAD. */
+  currentBranch(): Promise<string | null>;
+  /** Branch publication is allowed on: remote HEAD, then `init.defaultBranch`, then `main`. */
+  defaultBranch(): Promise<string>;
   /** Paths with uncommitted changes (porcelain), for scope-aware guards. */
   changedPaths(): Promise<string[]>;
+  /** Git change kind by path, for consumers that need new versus modified metadata. */
+  changedPathKinds?(): Promise<Record<string, WorkingTreeChange>>;
   /** Paths already present in the index. */
   stagedPaths(): Promise<string[]>;
   /** Stage the given pathspecs. */
@@ -29,8 +35,6 @@ export interface GitOps {
   hasStagedChanges(paths?: string[]): Promise<boolean>;
   /** Commit only the supplied pathspecs, leaving unrelated staged work untouched. */
   commit(message: string, paths?: string[]): Promise<void>;
-  /** Restore only produced artifact paths to a recorded ref. */
-  restorePaths(ref: string, paths: string[]): Promise<void>;
   hasUpstream(): Promise<boolean>;
   fetch(): Promise<void>;
   rebaseOntoUpstream(): Promise<RebaseResult>;
@@ -98,6 +102,11 @@ function parsePorcelainPath(line: string): string {
   return arrow === -1 ? body : body.slice(arrow + 4);
 }
 
+function parsePorcelainKind(line: string): WorkingTreeChange {
+  const status = line.slice(0, 2);
+  return status.includes("?") || status.includes("A") ? "new" : "modified";
+}
+
 export function defaultGitOps(
   companionPath: string,
   workingRepoPath = process.env.MATE_REPO_PATH,
@@ -112,14 +121,33 @@ export function defaultGitOps(
     return res;
   };
   return {
-    async headRef() {
-      return execOrThrow(["rev-parse", "HEAD"]).out;
+    async currentBranch() {
+      const res = exec(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+      return res.status === 0 && res.out.length > 0 ? res.out : null;
+    },
+    async defaultBranch() {
+      // A configured remote HEAD is the only answer the remote itself asserts; the
+      // rest are local conventions, narrowing to git's own default last.
+      const remoteHead = exec(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+      if (remoteHead.status === 0 && remoteHead.out.length > 0) {
+        return remoteHead.out.replace(/^origin\//, "");
+      }
+      const configured = exec(["config", "--get", "init.defaultBranch"]);
+      if (configured.status === 0 && configured.out.length > 0) return configured.out;
+      return "main";
     },
     async changedPaths() {
       const out = exec(["status", "--porcelain"]).out;
       if (out.length === 0) return [];
       return out.split("\n").map(parsePorcelainPath);
     },
+    async changedPathKinds() {
+      const out = exec(["status", "--porcelain"]).out;
+      if (out.length === 0) return {};
+      return Object.fromEntries(
+        out.split("\n").map((line) => [parsePorcelainPath(line), parsePorcelainKind(line)]),
+      );
+    },
     async stagedPaths() {
       const out = exec(["diff", "--cached", "--name-only"]).out;
       return out.length === 0 ? [] : out.split("\n");
@@ -153,23 +181,6 @@ export function defaultGitOps(
       if (paths && paths.length > 0 && known.length === 0) return;
       execOrThrow(["commit", "-m", message, ...pathspec]);
     },
-    async restorePaths(ref, paths) {
-      const tracked = paths.filter(
-        (filePath) => exec(["ls-files", "--cached", "--", filePath]).out.length > 0,
-      );
-      if (tracked.length > 0) {
-        execOrThrow(["restore", "--source", ref, "--staged", "--worktree", "--", ...tracked]);
-      }
-
-      // `git restore` does not remove newly-created untracked archive files.
-      const untracked = paths.filter(
-        (filePath) =>
-          exec(["ls-files", "--others", "--exclude-standard", "--", filePath]).out.length > 0,
-      );
-      if (untracked.length > 0) {
-        execOrThrow(["clean", "-fd", "--", ...untracked]);
-      }
-    },
     async hasUpstream() {
       return exec(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]).status === 0;
     },

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

@@ -1,4 +1,10 @@
-export { runArtifactFinishCommand } from "./command";
-export type { FinishCommandDeps } from "./command";
+export { runArtifactPublishCommand } from "./command";
+export type { PublishCommandDeps } from "./command";
 export type { FinishResult, FinishStep, FinishStatus } from "./engine";
-export type { ArtifactFinisher, FinishContext, FinisherFactory, Produced } from "./finisher";
+export type {
+  ArtifactFinisher,
+  FinishContext,
+  FinisherFactory,
+  Produced,
+  ResolveResult,
+} from "./finisher";