@uniqbit/mate-core 0.16.0 → 0.17.0-canary.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.16.0",
+  "version": "0.17.0-canary.2",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/companion/companion.ts

@@ -1,5 +1,7 @@
 import { usage } from "../../usage";
 import { runCompanionLinkCommand } from "./link";
+import { runCompanionRegisterCommand } from "./register";
+import { runCompanionPrepareCommand } from "./prepare";
 import { runSetupCommand } from "../setup";
 import { runCompanionListCommand } from "./list";
 import { runCompanionSyncCommand } from "./sync";
@@ -14,6 +16,12 @@ export async function runCompanionCommand(
     case "link":
       await runCompanionLinkCommand(argv);
       return;
+    case "register":
+      await runCompanionRegisterCommand(argv);
+      return;
+    case "prepare":
+      await runCompanionPrepareCommand(argv);
+      return;
     case "setup":
       await runSetupCommand(argv);
       return;

package/src/cli/commands/companion/prepare.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { preparePrebuiltWorkspace } from "../../../lib/prebuilt-workspace-prepare";
+
+export const companionPrepareCommandDeps = {
+  preparePrebuiltWorkspace,
+};
+
+interface ParsedPrepareArgs {
+  bundle?: string;
+  companionPath?: string;
+  error?: string;
+}
+
+export function parsePrepareArgs(argv: string[]): ParsedPrepareArgs {
+  let bundle: string | undefined;
+  const positional: string[] = [];
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index]!;
+    if (arg === "--from") {
+      const value = argv[++index];
+      if (!value) return { error: "`--from` requires a path to a prebuilt dependency bundle." };
+      bundle = value;
+      continue;
+    }
+    if (arg.startsWith("--from=")) {
+      bundle = arg.slice("--from=".length);
+      if (!bundle) return { error: "`--from` requires a path to a prebuilt dependency bundle." };
+      continue;
+    }
+    if (arg.startsWith("-")) return { error: `unknown option: ${arg}` };
+    positional.push(arg);
+  }
+
+  if (positional.length > 1) return { error: "`companion prepare` accepts at most one path." };
+  if (!bundle) return { error: "`companion prepare` requires `--from <bundle>`." };
+  return { bundle, companionPath: positional[0] };
+}
+
+/**
+ * @command mate companion prepare --from <bundle> [companion-path]
+ * @description Prepares the companion's machine-local dependency workspace by
+ * validating and copying a fully installed prebuilt bundle. Runs no package
+ * manager, no dependency resolution, and no installation script; presents no
+ * selection and changes none.
+ * @flags
+ * - `--from PATH` — the prebuilt, fully installed workspace to copy.
+ */
+export async function runCompanionPrepareCommand(argv: string[] = []): Promise<void> {
+  const parsed = parsePrepareArgs(argv);
+  if (parsed.error) {
+    process.stderr.write(`${FRAMEWORK_NAME}: ${parsed.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const companionPath = path.resolve(parsed.companionPath ?? process.cwd());
+  const result = await companionPrepareCommandDeps.preparePrebuiltWorkspace(
+    companionPath,
+    path.resolve(parsed.bundle!),
+  );
+
+  if (!result.ok) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: cannot prepare local dependencies:\n${result.failures.map((failure) => `  ${failure}`).join("\n")}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(
+    `${result.reused ? "Reused" : "Prepared"} local dependencies at ${result.workspacePath}\n`,
+  );
+}

package/src/cli/commands/companion/register.ts

@@ -0,0 +1,47 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { registerConfiguredCompanion } from "../../../lib/orchestrator/companion-registration";
+import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+
+export const companionRegisterCommandDeps = {
+  registerConfiguredCompanion,
+  createGlobalConfigStore: () => new GlobalConfigStore(),
+};
+
+/**
+ * @command mate companion register [path]
+ * @description Registers an already-configured Companion Repository in the
+ * global registry. Presents no selection, reads no input, and writes nothing
+ * inside the companion — the path a script or container entrypoint calls.
+ * @remarks Defaults to the current directory. Exits non-zero when the target
+ * carries no companion configuration.
+ */
+export async function runCompanionRegisterCommand(argv: string[] = []): Promise<void> {
+  const positional = argv.filter((arg) => !arg.startsWith("-"));
+  if (positional.length !== argv.length) {
+    process.stderr.write(`${FRAMEWORK_NAME}: \`companion register\` accepts no flags.\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (positional.length > 1) {
+    process.stderr.write(`${FRAMEWORK_NAME}: \`companion register\` accepts at most one path.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const target = path.resolve(positional[0] ?? process.cwd());
+  const result = await companionRegisterCommandDeps.registerConfiguredCompanion(target, {
+    globalConfigStore: companionRegisterCommandDeps.createGlobalConfigStore(),
+  });
+
+  if (!result.ok) {
+    process.stderr.write(`${FRAMEWORK_NAME}: ${result.reason}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(
+    `${result.alreadyRegistered ? "Already registered" : "Registered"} companion: ${result.companionPath}\n`,
+  );
+}

package/src/cli/commands/launch/claude.ts

@@ -2,12 +2,14 @@ import { makeLaunchCommand } from "./shared";
 
 /**
  * @command mate claude [-- ...agentArgs]
- * @description Launches Claude Code for the active working repository. In a
- * TTY, launches directly; outside a TTY, launches via
- * {@link runLaunchToolCommand} with confirmation.
+ * @description Launches Claude Code for the active working repository, or the
+ * Companion Repository with `-- --companion`. TTY launches ask for confirmation;
+ * non-interactive launches proceed without it.
  * @flags
  * - `-- <args>` — arguments forwarded to the launched `claude` process.
  * - `-- --no-git` — skip companion Git synchronization for this launch.
+ * - `-- --companion` — launch against the Companion Repository without a Working Repository.
+ * - `-- --yes` — skip the TTY confirmation.
  * @remarks When invoked via `directPassthrough` (the top-level `mate claude`
  * alias), all args before `--` are treated as agent args rather than being
  * parsed as launch options.

package/src/cli/commands/launch/opencode.ts

@@ -2,12 +2,14 @@ import { makeLaunchCommand } from "./shared";
 
 /**
  * @command mate opencode [-- ...agentArgs]
- * @description Launches OpenCode for the active working repository. In a
- * TTY, launches directly; outside a TTY, launches via
- * {@link runLaunchToolCommand} with confirmation.
+ * @description Launches OpenCode for the active working repository, or the
+ * Companion Repository with `-- --companion`. TTY launches ask for confirmation;
+ * non-interactive launches proceed without it.
  * @flags
  * - `-- <args>` — arguments forwarded to the launched `opencode` process.
  * - `-- --no-git` — skip companion Git synchronization for this launch.
+ * - `-- --companion` — launch against the Companion Repository without a Working Repository.
+ * - `-- --yes` — skip the TTY confirmation.
  * @remarks When invoked via `directPassthrough` (the top-level `mate
  * opencode` alias), all args before `--` are treated as agent args rather
  * than being parsed as launch options.

package/src/cli/commands/launch/shared.ts

@@ -4,6 +4,7 @@ import {
   LaunchPreflightError,
   RepositoryNotSelectedError,
   ToolNotAllowedError,
+  type LaunchScope,
 } from "../../../lib/orchestrator/types";
 import { createStartupProgress } from "../../../lib/components/startup-progress";
 import { ensureUnambiguousCompanion, launchAmbiguityDeps } from "../shared/companion-selection";
@@ -20,6 +21,8 @@ const STEP_LABELS = {
 export interface ParsedLaunchArgs {
   agentArgs: string[];
   skipGit?: boolean;
+  scope?: LaunchScope;
+  skipConfirmation?: boolean;
 }
 
 export { ensureUnambiguousCompanion, launchAmbiguityDeps };
@@ -45,9 +48,14 @@ export function parseDirectLaunchArgs(argv: string[]): ParsedLaunchArgs {
   const beforeSeparator = argv.slice(0, separatorIndex);
   const afterSeparator = argv.slice(separatorIndex + 1);
   const skipGit = afterSeparator.includes("--no-git");
+  const companion = afterSeparator.includes("--companion");
+  const skipConfirmation = afterSeparator.includes("--yes");
+  const reserved = new Set(["--no-git", "--companion", "--yes"]);
   return {
-    agentArgs: [...beforeSeparator, ...afterSeparator.filter((arg) => arg !== "--no-git")],
+    agentArgs: [...beforeSeparator, ...afterSeparator.filter((arg) => !reserved.has(arg))],
     ...(skipGit ? { skipGit: true } : {}),
+    ...(companion ? { scope: "companion" as const } : {}),
+    ...(skipConfirmation ? { skipConfirmation: true } : {}),
   };
 }
 
@@ -63,17 +71,23 @@ export function parseLaunchArgs(argv: string[]): ParsedLaunchArgs | null {
   }
 
   const skipGit = agentArgs.includes("--no-git");
+  const companion = agentArgs.includes("--companion");
+  const skipConfirmation = agentArgs.includes("--yes");
+  const reserved = new Set(["--no-git", "--companion", "--yes"]);
   return {
-    agentArgs: agentArgs.filter((arg) => arg !== "--no-git"),
+    agentArgs: agentArgs.filter((arg) => !reserved.has(arg)),
     ...(skipGit ? { skipGit: true } : {}),
+    ...(companion ? { scope: "companion" as const } : {}),
+    ...(skipConfirmation ? { skipConfirmation: true } : {}),
   };
 }
 
 /**
  * @description Shared launch execution used by `mate claude`, `mate opencode`,
  * and the direct `mate claude` / `mate opencode` commands: resolves the launch via {@link FrameworkLauncher.prepare},
- * optionally confirms with the user, re-syncs capability indexes via
- * `runIndexCapCommand`, then executes and prints the JSON result.
+ * confirms with the user in a TTY unless `--yes` was supplied, re-syncs capability indexes via
+ * `runIndexCapCommand`, then executes, prints the JSON result, and adopts the
+ * agent's outcome as the command's exit status (128 + signal for a signalled stop).
  * @remarks Exits non-zero with a targeted message for `ToolNotAllowedError`
  * (repo policy disallows this tool) and `RepositoryNotSelectedError` (no
  * active repo — points the user at `mate companion link`); other errors propagate.
@@ -84,6 +98,7 @@ export async function runLaunchToolCommand(
   options: {
     skipConfirmation?: boolean;
     skipGit?: boolean;
+    scope?: LaunchScope;
   } = {},
 ): Promise<void> {
   const interactiveGit = !!(process.stdin.isTTY && process.stdout.isTTY);
@@ -98,6 +113,7 @@ export async function runLaunchToolCommand(
       tool,
       args,
       skipGit: options.skipGit,
+      scope: options.scope,
       interactiveGit,
     });
     progress?.succeed("sync");
@@ -106,7 +122,7 @@ export async function runLaunchToolCommand(
     // Ink's line tracking, corrupting later re-renders (e.g. duplicated title).
     progress?.stop();
 
-    if (!options.skipConfirmation) {
+    if (!options.skipConfirmation && process.stdin.isTTY) {
       const ok = await launchCommandDeps.confirm("Continue? [y/N] ");
       if (!ok) {
         process.stderr.write("Aborted.\n");
@@ -114,13 +130,20 @@ export async function runLaunchToolCommand(
       }
     }
 
-    await launchCommandDeps.runIndexCapCommand([], {
-      onStepStart: (step) => process.stdout.write(`${STEP_LABELS[step]}...\n`),
-      onStepDone: (step, ok) => process.stdout.write(`${ok ? "✓" : "✗"} ${STEP_LABELS[step]}\n`),
-    });
+    if (options.scope !== "companion") {
+      await launchCommandDeps.runIndexCapCommand([], {
+        onStepStart: (step) => process.stdout.write(`${STEP_LABELS[step]}...\n`),
+        onStepDone: (step, ok) => process.stdout.write(`${ok ? "✓" : "✗"} ${STEP_LABELS[step]}\n`),
+      });
+    }
 
     const result = await prepared.execute();
+    /**
+     * The printed result stays useful, but the status is what a supervisor
+     * reads: a failed agent must fail the launch.
+     */
     console.log(JSON.stringify(result, null, 2));
+    if (result.exitCode !== 0) process.exitCode = result.exitCode;
   } catch (error) {
     progress?.failCurrent();
     progress?.stop();
@@ -153,7 +176,7 @@ export async function runLaunchToolCommand(
 /**
  * Builds the `mate <tool>` command handler: parses launch args (direct
  * passthrough or flagged), guards against ambiguous companions, then launches
- * via {@link runLaunchToolCommand} with confirmation skipped in a TTY.
+ * via {@link runLaunchToolCommand}; non-interactive launches skip confirmation.
  */
 export function makeLaunchCommand(tool: LaunchTarget) {
   return async function runLaunchCommand(
@@ -163,14 +186,20 @@ export function makeLaunchCommand(tool: LaunchTarget) {
     const parsed = options.directPassthrough ? parseDirectLaunchArgs(args) : parseLaunchArgs(args);
     if (!parsed) return;
 
-    if (!(await ensureUnambiguousCompanion())) {
+    if (
+      !(await ensureUnambiguousCompanion(
+        process.cwd(),
+        parsed.scope === "companion" ? { persistSelection: false } : {},
+      ))
+    ) {
       process.exitCode = 1;
       return;
     }
 
     await runLaunchToolCommand(tool, parsed.agentArgs, {
-      skipConfirmation: !!process.stdin.isTTY,
+      skipConfirmation: !process.stdin.isTTY || parsed.skipConfirmation,
       skipGit: parsed.skipGit,
+      scope: parsed.scope,
     });
   };
 }

package/src/cli/commands/shared/companion-selection.ts

@@ -40,6 +40,8 @@ export interface CompanionSelectionOptions {
   ignoreProjection?: boolean;
   /** Outranks the environment, the projection, and the picker. */
   companion?: string;
+  /** Pin an interactive answer for this process without writing a projection. */
+  persistSelection?: boolean;
 }
 
 function pin(match: Pick<CompanionMatch, "companionPath" | "repositoryId">): void {
@@ -137,6 +139,6 @@ export async function ensureUnambiguousCompanion(
   }
 
   pin(chosen);
-  await recordCompanion(cwd, chosen);
+  if (options.persistSelection !== false) await recordCompanion(cwd, chosen);
   return true;
 }

package/src/cli/commands/studio/index.ts

@@ -1,6 +1,12 @@
 import { FRAMEWORK_NAME } from "../../../framework";
 import { openReportInBrowser } from "../report/delivery";
-import { serveUntilInterrupted, startStudioServer } from "./server";
+import {
+  serveUntilInterrupted,
+  startStudioServer,
+  STUDIO_HOSTNAME,
+  type StudioServerHandle,
+  type StudioServerOptions,
+} from "./server";
 
 export interface StudioCommandDeps {
   startStudioServer?: typeof startStudioServer;
@@ -10,16 +16,52 @@ export interface StudioCommandDeps {
   warn?: (message: string) => void;
 }
 
+export type StudioServeArgs = StudioServerOptions & { port: number; hostname: string };
+
+export function parseStudioServeArgs(argv: string[]): StudioServeArgs | { error: string } {
+  let port: number | undefined;
+  let hostname = STUDIO_HOSTNAME;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--writable") {
+      continue;
+    }
+    if (arg === "--port" || arg.startsWith("--port=")) {
+      const value = arg === "--port" ? argv[index + 1] : arg.slice("--port=".length);
+      if (!value || value.startsWith("--")) return { error: "--port requires a value" };
+      const parsed = Number(value);
+      if (!/^\d+$/.test(value) || !Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return { error: `invalid --port value: ${value}` };
+      }
+      port = parsed;
+      if (arg === "--port") index += 1;
+      continue;
+    }
+    if (arg === "--host" || arg.startsWith("--host=")) {
+      const value = arg === "--host" ? argv[index + 1] : arg.slice("--host=".length);
+      if (!value || value.startsWith("--")) return { error: "--host requires a value" };
+      hostname = value;
+      if (arg === "--host") index += 1;
+      continue;
+    }
+    return { error: `unknown studio serve option: ${arg}` };
+  }
+
+  if (port === undefined) return { error: "studio serve requires --port" };
+  return { port, hostname, writable: argv.includes("--writable") };
+}
+
 /**
  * @command mate studio
- * @description Serves a local, read-only page over the Companion Repositories
+ * @description Serves a local page over the Companion Repositories
  * registered on this machine — the workflow drawn from each companion's
  * resolved schema with its OpenSpec state on it — and opens the platform
  * browser at it. Runs in the foreground on an operating-system-assigned
  * loopback port and dies with the process: no daemon, no stop command, and no
  * state written anywhere.
- * @remarks Takes no arguments and resolves no Repository Link, so it runs from
- * any directory.
+ * @remarks Both invocations are read-only unless passed `--writable`. Neither
+ * invocation resolves a Repository Link, so it runs from any directory.
  */
 export async function runStudioCommand(
   argv: string[] = [],
@@ -28,7 +70,12 @@ export async function runStudioCommand(
   const log = deps.log ?? ((message: string) => process.stdout.write(`${message}\n`));
   const warn = deps.warn ?? ((message: string) => process.stderr.write(`${message}\n`));
 
-  if (argv.length > 0) {
+  if (argv[0] === "serve") {
+    await runStudioServeCommand(argv.slice(1), deps, log, warn);
+    return;
+  }
+
+  if (argv.some((arg) => arg !== "--writable")) {
     warn(`${FRAMEWORK_NAME}: \`studio\` takes no arguments; unrecognized: ${argv.join(" ")}`);
     process.exitCode = 1;
     return;
@@ -40,7 +87,7 @@ export async function runStudioCommand(
 
   let server;
   try {
-    server = start();
+    server = start({}, { writable: argv.includes("--writable") });
   } catch (error) {
     warn(
       `${FRAMEWORK_NAME}: studio could not bind a port: ${
@@ -67,3 +114,35 @@ export async function runStudioCommand(
 
   await serve(server);
 }
+
+async function runStudioServeCommand(
+  argv: string[],
+  deps: StudioCommandDeps,
+  log: (message: string) => void,
+  warn: (message: string) => void,
+): Promise<void> {
+  const parsed = parseStudioServeArgs(argv);
+  if ("error" in parsed) {
+    warn(`${FRAMEWORK_NAME}: ${parsed.error}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const start = deps.startStudioServer ?? startStudioServer;
+  const serve = deps.serveUntilInterrupted ?? serveUntilInterrupted;
+  let server: StudioServerHandle;
+  try {
+    server = start({}, parsed);
+  } catch (error) {
+    warn(
+      `${FRAMEWORK_NAME}: studio serve could not bind ${parsed.hostname}:${parsed.port}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  log(server.url);
+  await serve(server);
+}

package/src/cli/commands/studio/routes.ts

@@ -1,2 +1,2 @@
-/** Loopback only: a payload carries absolute companion paths and change names. */
+/** Default bind stays loopback because payloads carry absolute paths and names. */
 export const STUDIO_HOSTNAME = "127.0.0.1";

package/src/cli/commands/studio/selection.ts

@@ -2,13 +2,20 @@ import { createHash } from "node:crypto";
 
 import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
 
-export type StudioView = "dashboard" | "workflow" | "specs" | "skills";
+export type StudioView = "dashboard" | "workflow" | "specs" | "skills" | "vault";
 
-export const STUDIO_VIEWS: readonly StudioView[] = ["dashboard", "workflow", "specs", "skills"];
+export const STUDIO_VIEWS: readonly StudioView[] = [
+  "dashboard",
+  "workflow",
+  "specs",
+  "skills",
+  "vault",
+];
 
 export const COMPANION_PARAM = "companion";
 export const VIEW_PARAM = "view";
 export const REFRESH_PARAM = "refresh";
+export const FILE_PARAM = "path";
 
 /** Filled into a prompt when no change is named, so a prompt is never half-written. */
 export const CHANGE_PLACEHOLDER = "<change-name>";
@@ -23,6 +30,7 @@ export interface StudioSelection {
    * into the URL another control builds. Switching a view is not a refresh.
    */
   refresh: boolean;
+  openPath: string | null;
 }
 
 /**
@@ -57,5 +65,6 @@ export function parseStudioSelection(url: URL): StudioSelection {
     companionDigest: url.searchParams.get(COMPANION_PARAM)?.trim() || null,
     view: readView(url.searchParams.get(VIEW_PARAM)),
     refresh: url.searchParams.get(REFRESH_PARAM) === "1",
+    openPath: url.searchParams.get(FILE_PARAM)?.trim() || null,
   };
 }