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

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,4 +1,4 @@
 {
-  "name": "mate",
-  "description": "Mate-managed Claude Code hooks: artifact-path guardrail, session banner, and the OpenSpec archive-finish nudge. Ships inside @uniqbit/mate-core and is loaded per managed launch via --plugin-dir; it is never published separately."
+  "name": "mate-claude-plugin",
+  "description": "Mate-managed Claude Code hooks: artifact-path guardrail, session banner, and companion guidance. Ships inside @uniqbit/mate-core and is never published separately. A managed launch loads it with --plugin-dir; a wrapped repository instead inlines the guard and guidance commands into its settings, with ${CLAUDE_PLUGIN_ROOT} already resolved."
 }

package/claude-plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Mate hooks — PreToolUse artifact-path guardrail, SessionStart banner, PostToolUse OpenSpec archive-finish nudge (self-gated at runtime)",
+  "description": "Mate hooks — PreToolUse artifact-path guardrail, SessionStart banner and companion guidance",
   "hooks": {
     "PreToolUse": [
       {
@@ -20,15 +20,12 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-banner.mjs\""
           }
         ]
-      }
-    ],
-    "PostToolUse": [
+      },
       {
-        "matcher": "Bash",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/artifact-finish-nudge.mjs\""
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-guidance.mjs\""
           }
         ]
       }

package/claude-plugin/hooks/session-guidance.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/session-guidance.ts, loaded through
+// ts-loader.mjs because the installed plugin sits inside node_modules where
+// node's native type stripping is disabled.
+import "./ts-loader.mjs";
+
+const { run } = await import("../../src/hooks/session-guidance.ts");
+process.exitCode = run();

package/claude-plugin/hooks/ts-loader.mjs

@@ -15,7 +15,26 @@ process.emitWarning = (warning, ...args) => {
   emitWarning.call(process, warning, ...args);
 };
 
+// Source imports are extensionless, which node's ESM resolver refuses. Probe
+// the TypeScript candidates the type-checker resolves so a hook module can
+// import the runtime subpath the same way the rest of the source tree does.
+const TS_CANDIDATE_SUFFIXES = [".ts", ".tsx", "/index.ts", "/index.tsx"];
+
 registerHooks({
+  resolve(specifier, context, next) {
+    if (!specifier.startsWith(".") || /\.[cm]?[jt]sx?$/.test(specifier)) {
+      return next(specifier, context);
+    }
+    const base = new URL(specifier, context.parentURL);
+    for (const suffix of TS_CANDIDATE_SUFFIXES) {
+      const candidate = new URL(`${base.href}${suffix}`);
+      if (fs.existsSync(fileURLToPath(candidate))) {
+        return { url: candidate.href, format: "module", shortCircuit: true };
+      }
+    }
+    return next(specifier, context);
+  },
+
   load(url, context, next) {
     if (!url.endsWith(".ts")) return next(url, context);
     const source = fs.readFileSync(fileURLToPath(url), "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.5",
+  "version": "0.16.0-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [
@@ -27,17 +27,19 @@
     "typecheck": "bunx tsc --noEmit -p ../../tsconfig.json",
     "lint": "oxlint src/",
     "lint:fix": "oxlint src/ --fix",
-    "format": "oxfmt src/",
-    "format:check": "oxfmt src/ --check"
+    "format": "oxfmt src/ \"!**/*.generated.*\" \"!**/report-assets/**\"",
+    "format:check": "oxfmt src/ \"!**/*.generated.*\" \"!**/report-assets/**\" --check"
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.18.3",
     "@opentui/core": "^0.4.5",
     "@opentui/keymap": "^0.4.5",
     "@opentui/solid": "^0.4.5",
+    "@tanstack/highlight": "0.0.10",
+    "hono": "^4.13.5",
     "ink": "^7.1.0",
     "react": "^19.2.7",
-    "react-doctor": "0.8.1",
+    "react-doctor": "0.9.13",
     "semver": "^7.8.5",
     "yaml": "^2.9.0"
   },

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

@@ -1,5 +1,12 @@
 import { usage } from "../../usage";
-import { runArtifactFinishCommand } from "./finish";
+import { runArtifactPublishCommand } from "./finish";
+import { runArtifactPendingCommand } from "./pending";
+
+/**
+ * Pre-rename spelling of `publish`. Kept so companions whose materialized skills were
+ * written before the rename keep working until they re-sync.
+ */
+const DEPRECATED_PUBLISH_ALIAS = "finish";
 
 /**
  * @command mate artifact <subcommand>
@@ -11,8 +18,17 @@ export async function runArtifactCommand(
   argv: string[],
 ): Promise<void> {
   switch (subcommand) {
-    case "finish":
-      await runArtifactFinishCommand(argv);
+    case DEPRECATED_PUBLISH_ALIAS:
+      console.error(
+        "mate: `artifact finish` is deprecated and will be removed; use `artifact publish`.",
+      );
+      await runArtifactPublishCommand(argv);
+      return;
+    case "publish":
+      await runArtifactPublishCommand(argv);
+      return;
+    case "pending":
+      await runArtifactPendingCommand(argv);
       return;
     default:
       console.error(`Unknown artifact command: ${subcommand ?? ""}`);

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

@@ -2,37 +2,50 @@ import { resolveForCapability } from "../../../../lib/orchestrator/framework-con
 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 { type BooleanFlagSet, parseFlags } from "../../../parse-flags";
 import { ensureUnambiguousCompanion } from "../../shared/companion-selection";
-import { runFinishEngine } from "./engine";
-import type { FinishContext, FinisherFactory } from "./finisher";
+import { discoverArchives, pendingArchives } from "../pending/discovery";
+import { type FinishResult, runFinishEngine } from "./engine";
+import type { ArtifactFinisher, FinishContext, FinisherFactory } from "./finisher";
 import { defaultGitOps, type GitOps } from "./git";
+import { openspecSpecsFinisher, resolveDriftedSpecs } from "./openspec";
 import { DEFAULT_FINISHER_TYPE, knownFinisherTypes, selectFinisher } from "./registry";
 
-export interface FinishCommandDeps {
+export interface PublishCommandDeps {
   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;
+  /** Injectable clock; a spec publication's anchor is the calendar date it runs on. */
+  now?: () => Date;
+  /** Injectable spec-publication finisher; mirrors `selectFinisher` for the other unit. */
+  specsFinisher?: (context: FinishContext, paths: string[], now: () => Date) => ArtifactFinisher;
   stdout?: (line: string) => void;
   stderr?: (line: string) => void;
 }
 
-const VALUE_FLAGS = new Set(["--type"]);
+/** Presence-only flags; every other `--flag` consumes the following token as its value. */
+const BOOLEAN_FLAGS: BooleanFlagSet = new Set(["no-push", "json", "specs", "all"]);
 
-/** First non-flag token, skipping the value of any value-taking flag (e.g. `--type x`). */
-function positionalName(argv: string[]): string | undefined {
+/**
+ * Every non-flag token, in order. Consumes the value of a value-taking flag exactly as
+ * {@link parseFlags} does, so the positionals and the flags can never disagree about
+ * which token belongs to whom.
+ */
+function positionalNames(argv: string[]): string[] {
+  const names: string[] = [];
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
-    if (VALUE_FLAGS.has(token)) {
-      index += 1;
+    if (!token.startsWith("--")) {
+      names.push(token);
       continue;
     }
-    if (token.startsWith("--")) continue;
-    return token;
+    const key = token.slice(2);
+    if (key.includes("=") || BOOLEAN_FLAGS.has(key)) continue;
+    index += 1;
   }
-  return undefined;
+  return names;
 }
 
 async function defaultLoadCapabilities(context: LaunchContext): Promise<CapabilityConfig[]> {
@@ -40,41 +53,106 @@ async function defaultLoadCapabilities(context: LaunchContext): Promise<Capabili
   return config.capabilities ?? [];
 }
 
+/** A publication the pipeline never ran: nothing was resolved, committed, tagged, or pushed. */
+function nothingToPublish(name: string, message: string): FinishResult {
+  return {
+    type: DEFAULT_FINISHER_TYPE,
+    name,
+    anchorName: null,
+    tag: null,
+    resumed: false,
+    step: "done",
+    status: "skipped",
+    conflictedPaths: [],
+    local: { committed: false, tagged: false, pushed: false },
+    message,
+  };
+}
+
+function refusalResult(type: string, name: string, message: string): FinishResult {
+  return {
+    type,
+    name,
+    anchorName: null,
+    tag: null,
+    resumed: false,
+    step: "resolve",
+    status: "error",
+    conflictedPaths: [],
+    local: { committed: false, tagged: false, pushed: false },
+    message,
+  };
+}
+
 /**
- * @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}.
+ * @command mate artifact publish <target>
+ * @description Publishes an already-produced artifact. Resolves the launch context for the
+ * current working repo, loads the enabled capabilities, and runs {@link runFinishEngine} to
+ * commit/tag/push via {@link GitOps}. Two publication units exist: an archived change,
+ * named positionally, and a spec publication of drifted canonical specs, selected with
+ * `--specs`. Archiving is a precondition performed by the archive workflow; this command
+ * never archives.
  * @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.
+ * - `<target>` — a dated archive anchor (`YYYY-MM-DD-<name>`), or a change name matching
+ *   exactly one archive. Mutually exclusive with `--specs` and `--all`.
+ * - `--specs [<path>...]` — publish drifted canonical specs as their own publication under a
+ *   new `openspec/specs/<date>-<specs>` tag. Bare, it publishes every drifted spec; with paths, only
+ *   those. A bare name alongside it is a change target and is refused.
+ * - `--all` — publish every pending change in discovery order, then one spec publication for
+ *   the drift that remains. Halts at the first conflict or error; with `--json` it emits a
+ *   single array of results in execution order.
+ * - `--type <type>` — finisher type to use; see `knownFinisherTypes()`. `--specs` and
+ *   `--all` are openspec-only.
+ * - `--no-push` — commit and tag locally but skip the remote sync and push.
+ * - `--json` — emit machine-readable JSON 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 resolved or mutated in that case.
  */
-export async function runArtifactFinishCommand(
+export async function runArtifactPublishCommand(
   argv: string[],
-  deps: FinishCommandDeps = {},
+  deps: PublishCommandDeps = {},
 ): 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 flags = parseFlags(argv, BOOLEAN_FLAGS);
   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);
+  const specsMode = flags.specs === true;
+  const allMode = flags.all === true;
+  const positionals = positionalNames(argv);
 
-  if (!name) {
-    emitErr("mate: artifact finish requires a change name.");
+  /** With `--specs`, a path narrows the publication; a bare name is a change target. */
+  const specPaths = specsMode ? positionals.filter((token) => token.includes("/")) : [];
+  const changeTargets = specsMode
+    ? positionals.filter((token) => !token.includes("/"))
+    : positionals;
+
+  /** Argument refusals go to stderr in every mode: nothing was resolved to report on. */
+  const refuse = (message: string): void => {
+    emitErr(message);
     process.exitCode = 1;
+  };
+
+  if (allMode && (specsMode || positionals.length > 0)) {
+    refuse(
+      "mate: --all already publishes both pending changes and drifted specs; drop the extra target.",
+    );
+    return;
+  }
+  if (specsMode && changeTargets.length > 0) {
+    refuse(
+      `mate: "${changeTargets[0]}" is a change target and --specs publishes canonical specs; they are different publication units. Pass one or the other.`,
+    );
+    return;
+  }
+  if (!allMode && !specsMode && positionals.length === 0) {
+    refuse("mate: artifact publish requires an archive anchor or change name, --specs, or --all.");
+    return;
+  }
+  if ((allMode || specsMode) && type !== DEFAULT_FINISHER_TYPE) {
+    refuse(`mate: --specs and --all are only available for the ${DEFAULT_FINISHER_TYPE} type.`);
     return;
   }
 
@@ -129,32 +207,80 @@ export async function runArtifactFinishCommand(
       context.repository?.path ?? process.env.MATE_REPO_PATH,
     );
   } catch (err) {
-    const message = `mate: finish Git guard rejected the target: ${String(err)}`;
+    const message = `mate: publish Git guard rejected the target: ${String(err)}`;
+    if (json) emitOut(JSON.stringify(refusalResult(type, positionals[0] ?? "", message)));
+    else emitErr(message);
+    process.exitCode = 1;
+    return;
+  }
+
+  const now = deps.now ?? (() => new Date());
+  /**
+   * Under `--all --json` the array is the whole output, so the per-publication emission is
+   * suppressed; every other mode lets the engine report each publication as it finishes.
+   */
+  const quiet = allMode && json;
+  const engineDeps = {
+    git,
+    json: !allMode && json,
+    stdout: quiet ? (): void => {} : emitOut,
+    stderr: quiet ? (): void => {} : emitErr,
+  };
+
+  const runChange = (target: string): Promise<FinishResult> =>
+    runFinishEngine(finisher, { name: target, noPush }, engineDeps);
+
+  const runSpecs = async (requested: string[]): Promise<FinishResult | null> => {
+    const drift = await resolveDriftedSpecs(context.companionPath, git, requested);
+    if (!drift.ok) {
+      if (!quiet && !json) emitErr(drift.message);
+      process.exitCode = 1;
+      return refusalResult(type, "--specs", drift.message);
+    }
+    if (drift.paths.length === 0) return null;
+    const makeSpecsFinisher = deps.specsFinisher ?? openspecSpecsFinisher;
+    const specsFinisher = makeSpecsFinisher(finishContext, drift.paths, now);
+    return runFinishEngine(specsFinisher, { name: "--specs", noPush }, engineDeps);
+  };
+
+  const halted = (result: FinishResult): boolean =>
+    result.status === "conflict" || result.status === "error";
+
+  if (allMode) {
+    const results: FinishResult[] = [];
+    const changed = await git.changedPaths();
+    const changeKinds = (await git.changedPathKinds?.()) ?? {};
+    const archives = await discoverArchives(context.companionPath, changed, changeKinds);
+
+    for (const entry of pendingArchives(archives)) {
+      const result = await runChange(entry.anchor);
+      results.push(result);
+      if (halted(result)) {
+        if (json) emitOut(JSON.stringify(results));
+        return;
+      }
+    }
+
+    /** Drift is recomputed: a spec a change just committed is no longer drifted. */
+    const specResult = await runSpecs([]);
+    if (specResult) results.push(specResult);
+
+    if (json) emitOut(JSON.stringify(results));
+    else if (results.length === 0) emitOut("Nothing to publish.");
+    return;
+  }
+
+  if (specsMode) {
+    const result = await runSpecs(specPaths);
+    const emitted =
+      result ?? nothingToPublish("--specs", "No drifted canonical specs; nothing to publish.");
     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);
+      if (result === null) emitOut(JSON.stringify(emitted));
+    } else if (result === null) {
+      emitOut(emitted.message);
     }
-    process.exitCode = 1;
     return;
   }
 
-  await runFinishEngine(
-    finisher,
-    { name, force, noPush },
-    { git, json, stdout: emitOut, stderr: emitErr },
-  );
+  await runChange(positionals[0]);
 }