@uniqbit/mate-core 0.17.0-canary.8 → 0.17.1

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

@@ -10,6 +10,7 @@ import { createStartupProgress } from "../../../lib/components/startup-progress"
 import { ensureUnambiguousCompanion, launchAmbiguityDeps } from "../shared/companion-selection";
 import { runIndexCapCommand } from "../cap/index-cmd";
 import type { LaunchTarget } from "../../launch-selector";
+import { writeJsonStdout } from "../../write-json-stdout";
 
 const STEP_LABELS = {
   sync: "Syncing mate",
@@ -127,7 +128,7 @@ export async function runLaunchToolCommand(
      * 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));
+    await writeJsonStdout(result);
     if (result.exitCode !== 0) process.exitCode = result.exitCode;
   } catch (error) {
     progress?.failCurrent();

package/src/cli/commands/plugin/plugin.ts

@@ -1,5 +1,6 @@
 import { usage } from "../../usage";
 import { runPluginInstallCommand } from "./install";
+import { runPluginVerifyCommand } from "./verify";
 
 export async function runPluginCommand(
   subcommand: string | undefined,
@@ -9,6 +10,9 @@ export async function runPluginCommand(
     case "install":
       await runPluginInstallCommand(argv);
       return;
+    case "verify":
+      await runPluginVerifyCommand();
+      return;
     default:
       console.error(`Unknown plugin command: ${subcommand ?? ""}`);
       console.error(usage());

package/src/cli/commands/plugin/verify.ts

@@ -0,0 +1,25 @@
+import { FRAMEWORK_NAME } from "../../../framework";
+import { resolveInstallContext } from "../../../lib/install";
+import { verifyDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
+
+/**
+ * @command mate plugin verify
+ * @description Strict, installation-free check that every plugin declared by the companion is allowed by `MATE_ALLOWED_PLUGINS`, installed, and loadable with the current environment. Exits non-zero naming each failing package.
+ */
+export async function runPluginVerifyCommand(cwd = process.cwd()): Promise<boolean> {
+  const context = await resolveInstallContext(cwd);
+  if ((context.kind !== "companion" && context.kind !== "hub") || !context.companionPath) {
+    process.stderr.write(`${FRAMEWORK_NAME}: \`plugin verify\` requires a companion context.\n`);
+    process.exitCode = 1;
+    return false;
+  }
+  const failures = await verifyDeclaredPlugins(context.companionPath);
+  for (const failure of failures) {
+    process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
+  }
+  if (failures.length > 0) {
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}

package/src/cli/commands/report/highlight.ts

@@ -4,10 +4,7 @@ import githubLight from "@tanstack/highlight/themes/github-light";
 
 /** Sole boundary against `@tanstack/highlight`, so an upstream API break stays a single-file fix. */
 
-/** Language every unknown or unsupported candidate resolves to. */
-export const PLAIN_LANGUAGE = "plaintext";
-
-export function resolveHighlightLanguage(candidate: string | undefined): string {
+function resolveHighlightLanguage(candidate: string | undefined): string {
   return normalizeLanguage(candidate);
 }
 

package/src/cli/commands/report/renderer.ts

@@ -456,5 +456,3 @@ const VISUAL_SECTION_CSS = `
     }`;
 
 type ReportMetricsSection = Extract<ReportSection, { type: "metrics" }>;
-
-export { escapeHTML };

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

@@ -0,0 +1,201 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+/** Shortest operator-supplied token accepted; a generated one is 43 characters. */
+export const MIN_TOKEN_LENGTH = 32;
+
+const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
+
+export type StudioInvocation = "interactive" | "serve";
+
+export interface StudioAccessOptions {
+  invocation: StudioInvocation;
+  terminal: boolean;
+  /** Bound interface as passed to the server. */
+  hostname: string;
+  /** Read at request time: the port is known only once the server has bound. */
+  port: () => number;
+  allowedHosts?: readonly string[];
+  publicOrigin?: string | null;
+  token?: string | null;
+}
+
+/**
+ * One server's Host, Origin, and token policy. `null` token means the server
+ * is unguarded and issues none.
+ */
+export interface StudioAccess {
+  invocation: StudioInvocation;
+  guarded: boolean;
+  token: string | null;
+  cookieName(): string;
+  /** Accepted origin for this request, or `null` when its Host is not one Studio answers to. */
+  acceptedOrigin(request: Request): string | null;
+  originMatches(request: Request, acceptedOrigin: string): boolean;
+  hasToken(request: Request): boolean;
+  /** Whether a request of this kind needs the token under this invocation. */
+  requires(kind: "read" | "save" | "terminal"): boolean;
+}
+
+export function generateStudioToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+export function validateStudioToken(value: string): string | null {
+  if (value.trim().length < MIN_TOKEN_LENGTH) {
+    return `the supplied token must be at least ${MIN_TOKEN_LENGTH} characters`;
+  }
+  return null;
+}
+
+/** `null` for anything other than an exact `http(s)://host[:port]` origin. */
+export function normalizeOrigin(value: string): string | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  if (parsed.username || parsed.password) return null;
+  if (parsed.pathname !== "/" || parsed.search || parsed.hash || value.endsWith("/")) return null;
+  return parsed.origin;
+}
+
+/** Lower-cased `host[:port]` with the HTTP default port dropped, or `null` when unparsable. */
+export function normalizeAuthority(value: string): string | null {
+  const trimmed = value.trim();
+  if (!trimmed || /[\s/?#@\\]/.test(trimmed)) return null;
+  try {
+    const parsed = new URL(`http://${trimmed}`);
+    return parsed.host;
+  } catch {
+    return null;
+  }
+}
+
+function bracketed(hostname: string): string {
+  return hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+}
+
+function digest(value: string): Buffer {
+  return createHash("sha256").update(value).digest();
+}
+
+/** Hashing first keeps the comparison constant-time for inputs of any length. */
+export function tokensEqual(candidate: string, expected: string): boolean {
+  return timingSafeEqual(digest(candidate), digest(expected));
+}
+
+function readCookie(request: Request, name: string): string | null {
+  const header = request.headers.get("cookie");
+  if (!header) return null;
+  for (const part of header.split(";")) {
+    const index = part.indexOf("=");
+    if (index < 0) continue;
+    if (part.slice(0, index).trim() === name) return part.slice(index + 1).trim();
+  }
+  return null;
+}
+
+export function createStudioAccess(options: StudioAccessOptions): StudioAccess {
+  const guarded = options.invocation === "serve" || options.terminal;
+  const token = guarded ? (options.token ?? generateStudioToken()) : null;
+  const publicOrigin = options.publicOrigin ? normalizeOrigin(options.publicOrigin) : null;
+  const publicAuthority = publicOrigin ? new URL(publicOrigin).host : null;
+  const configured = new Set<string>();
+  for (const host of options.allowedHosts ?? []) {
+    const authority = normalizeAuthority(host);
+    if (authority) configured.add(authority);
+  }
+  if (publicAuthority) configured.add(publicAuthority);
+
+  const accepted = (): Set<string> => {
+    const port = options.port();
+    const hosts = new Set(configured);
+    for (const hostname of [...LOOPBACK_HOSTNAMES, bracketed(options.hostname)]) {
+      const authority = normalizeAuthority(`${hostname}:${port}`);
+      if (authority) hosts.add(authority);
+    }
+    return hosts;
+  };
+
+  return {
+    invocation: options.invocation,
+    guarded,
+    token,
+    cookieName: () => `mate_studio_${options.port()}`,
+    acceptedOrigin(request) {
+      const raw = request.headers.get("host") ?? new URL(request.url).host;
+      const authority = normalizeAuthority(raw);
+      if (!authority || !accepted().has(authority)) return null;
+      if (publicOrigin && authority === publicAuthority) return publicOrigin;
+      return `http://${authority}`;
+    },
+    originMatches(request, acceptedOrigin) {
+      const origin = request.headers.get("origin");
+      if (!origin || origin === "null") return false;
+      return normalizeOrigin(origin) === acceptedOrigin;
+    },
+    hasToken(request) {
+      if (!token) return false;
+      const value = readCookie(request, `mate_studio_${options.port()}`);
+      return value !== null && tokensEqual(value, token);
+    },
+    requires(kind) {
+      if (!guarded) return false;
+      if (options.invocation === "serve") return true;
+      return kind !== "read";
+    },
+  };
+}
+
+const EXCHANGE_HEADERS = {
+  "cache-control": "no-store",
+  "referrer-policy": "no-referrer",
+};
+
+/**
+ * Trades a `?token=` navigation for the cookie and a relative redirect, so the
+ * browser never leaves the Host it asked for. `null` when the request carries
+ * no token parameter.
+ */
+export function exchangeStudioToken(
+  request: Request,
+  access: StudioAccess,
+  acceptedOrigin: string,
+): Response | null {
+  const url = new URL(request.url);
+  if (!url.searchParams.has("token")) return null;
+  if (request.method !== "GET" || !access.token) {
+    return new Response("the access token is exchanged only by opening its address", {
+      status: 400,
+      headers: EXCHANGE_HEADERS,
+    });
+  }
+  const candidate = url.searchParams.get("token") ?? "";
+  if (!tokensEqual(candidate, access.token)) {
+    return new Response("the access token does not match; open the address Studio printed", {
+      status: 403,
+      headers: EXCHANGE_HEADERS,
+    });
+  }
+  url.searchParams.delete("token");
+  const secure = acceptedOrigin.startsWith("https:") ? "; Secure" : "";
+  return new Response(null, {
+    status: 303,
+    headers: {
+      ...EXCHANGE_HEADERS,
+      location: `${url.pathname}${url.search}`,
+      "set-cookie": `${access.cookieName()}=${access.token}; Path=/; HttpOnly; SameSite=Strict${secure}`,
+    },
+  });
+}
+
+/** Address the operator opens: loopback for wildcard or loopback binds, carrying the token only when it was generated. */
+export function studioAddress(hostname: string, port: number, token: string | null): string {
+  const wildcard = hostname === "0.0.0.0" || hostname === "::" || hostname === "[::]";
+  const loopback = ["127.0.0.1", "localhost", "::1", "[::1]"].includes(hostname);
+  const host = wildcard || loopback ? "localhost" : bracketed(hostname);
+  const base = `http://${host}:${port}`;
+  return token ? `${base}/?token=${token}` : base;
+}

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

@@ -1,5 +1,9 @@
+import path from "node:path";
+
 import { FRAMEWORK_NAME } from "../../../framework";
 import { openReportInBrowser } from "../report/delivery";
+import { normalizeAuthority, normalizeOrigin, validateStudioToken } from "./access";
+import { collectStudioInventory, type StudioInventory } from "./inventory";
 import {
   serveUntilInterrupted,
   startStudioServer,
@@ -7,49 +11,196 @@ import {
   type StudioServerHandle,
   type StudioServerOptions,
 } from "./server";
+import { terminalUnsupportedReason } from "./terminal";
 
 export interface StudioCommandDeps {
   startStudioServer?: typeof startStudioServer;
   serveUntilInterrupted?: typeof serveUntilInterrupted;
   openInBrowser?: (url: string) => Promise<void>;
+  collectStudioInventory?: () => Promise<StudioInventory>;
+  terminalUnsupportedReason?: () => string | null;
+  env?: NodeJS.ProcessEnv;
   log?: (message: string) => void;
   warn?: (message: string) => void;
 }
 
 export type StudioServeArgs = StudioServerOptions & { port: number; hostname: string };
 
-export function parseStudioServeArgs(argv: string[]): StudioServeArgs | { error: string } {
+export type StudioInteractiveArgs = Pick<
+  StudioServerOptions,
+  "writable" | "terminal" | "detachMinutes"
+>;
+
+interface ParseState {
+  writable: boolean;
+  terminal: boolean;
+  detachMinutes?: number;
+}
+
+/**
+ * Reads one `--flag value` / `--flag=value` pair. `undefined` when `arg` is not
+ * that flag; `{ error }` when its value is missing.
+ */
+function flagValue(
+  argv: string[],
+  index: number,
+  flag: string,
+): { value: string; consumed: number } | { error: string } | undefined {
+  const arg = argv[index]!;
+  if (arg !== flag && !arg.startsWith(`${flag}=`)) return undefined;
+  const value = arg === flag ? argv[index + 1] : arg.slice(flag.length + 1);
+  if (!value || value.startsWith("--")) return { error: `${flag} requires a value` };
+  return { value, consumed: arg === flag ? 2 : 1 };
+}
+
+/** Flags shared by both invocations; returns how many arguments were consumed, 0 when none. */
+function parseSharedFlag(
+  argv: string[],
+  index: number,
+  state: ParseState,
+): number | { error: string } {
+  const arg = argv[index]!;
+  if (arg === "--writable") {
+    state.writable = true;
+    return 1;
+  }
+  if (arg === "--terminal") {
+    state.terminal = true;
+    return 1;
+  }
+  const detach = flagValue(argv, index, "--detach-timeout");
+  if (!detach) return 0;
+  if ("error" in detach) return detach;
+  if (!/^\d+$/.test(detach.value) || Number(detach.value) < 1) {
+    return { error: `invalid --detach-timeout value: ${detach.value} (whole minutes, at least 1)` };
+  }
+  state.detachMinutes = Number(detach.value);
+  return detach.consumed;
+}
+
+function checkTerminal(state: ParseState): { error: string } | null {
+  if (state.terminal && !state.writable) {
+    return { error: "--terminal requires --writable" };
+  }
+  return null;
+}
+
+export function parseStudioArgs(argv: string[]): StudioInteractiveArgs | { error: string } {
+  const state: ParseState = { writable: false, terminal: false };
+  for (let index = 0; index < argv.length;) {
+    const consumed = parseSharedFlag(argv, index, state);
+    if (typeof consumed === "object") return consumed;
+    if (consumed === 0) return { error: `unrecognized studio argument: ${argv[index]}` };
+    index += consumed;
+  }
+  return (
+    checkTerminal(state) ?? {
+      writable: state.writable,
+      ...(state.terminal ? { terminal: true } : {}),
+      ...(state.detachMinutes !== undefined ? { detachMinutes: state.detachMinutes } : {}),
+    }
+  );
+}
+
+export function parseStudioServeArgs(
+  argv: string[],
+  env: NodeJS.ProcessEnv = {},
+): StudioServeArgs | { error: string } {
   let port: number | undefined;
   let hostname = STUDIO_HOSTNAME;
+  let token: string | undefined;
+  let publicOrigin: string | undefined;
+  let companion: string | undefined;
+  let noGit = false;
+  const allowedHosts: string[] = [];
+  const state: ParseState = { writable: false, terminal: false };
 
-  for (let index = 0; index < argv.length; index += 1) {
+  for (let index = 0; index < argv.length;) {
     const arg = argv[index]!;
-    if (arg === "--writable") {
+    const shared = parseSharedFlag(argv, index, state);
+    if (typeof shared === "object") return shared;
+    if (shared > 0) {
+      index += shared;
+      continue;
+    }
+    if (arg === "--no-git") {
+      noGit = true;
+      index += 1;
       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}` };
+    const portFlag = flagValue(argv, index, "--port");
+    if (portFlag) {
+      if ("error" in portFlag) return portFlag;
+      const parsed = Number(portFlag.value);
+      if (!/^\d+$/.test(portFlag.value) || parsed < 1 || parsed > 65535) {
+        return { error: `invalid --port value: ${portFlag.value}` };
       }
       port = parsed;
-      if (arg === "--port") index += 1;
+      index += portFlag.consumed;
       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;
+    const valued = (
+      [
+        ["--host", (value: string) => (hostname = value)],
+        ["--token", (value: string) => (token = value)],
+        ["--allowed-host", (value: string) => allowedHosts.push(...splitHosts(value))],
+        ["--public-origin", (value: string) => (publicOrigin = value)],
+        ["--companion", (value: string) => (companion = value)],
+      ] as const
+    ).find(([flag]) => flagValue(argv, index, flag) !== undefined);
+    if (valued) {
+      const read = flagValue(argv, index, valued[0])!;
+      if ("error" in read) return read;
+      valued[1](read.value);
+      index += read.consumed;
       continue;
     }
     return { error: `unknown studio serve option: ${arg}` };
   }
 
   if (port === undefined) return { error: "studio serve requires --port" };
-  return { port, hostname, writable: argv.includes("--writable") };
+  const terminalError = checkTerminal(state);
+  if (terminalError) return terminalError;
+
+  token ??= env.MATE_STUDIO_TOKEN || undefined;
+  if (token !== undefined) {
+    const weak = validateStudioToken(token);
+    if (weak) return { error: `--token / MATE_STUDIO_TOKEN: ${weak}` };
+  }
+  if (env.MATE_STUDIO_ALLOWED_HOSTS)
+    allowedHosts.push(...splitHosts(env.MATE_STUDIO_ALLOWED_HOSTS));
+  for (const host of allowedHosts) {
+    if (!normalizeAuthority(host)) {
+      return { error: `--allowed-host / MATE_STUDIO_ALLOWED_HOSTS: invalid host: ${host}` };
+    }
+  }
+  publicOrigin ??= env.MATE_STUDIO_PUBLIC_ORIGIN || undefined;
+  if (publicOrigin !== undefined && !normalizeOrigin(publicOrigin)) {
+    return {
+      error: `--public-origin / MATE_STUDIO_PUBLIC_ORIGIN: expected http(s)://host[:port], got ${publicOrigin}`,
+    };
+  }
+
+  return {
+    port,
+    hostname,
+    writable: state.writable,
+    invocation: "serve",
+    ...(state.terminal ? { terminal: true } : {}),
+    ...(state.detachMinutes !== undefined ? { detachMinutes: state.detachMinutes } : {}),
+    ...(token !== undefined ? { token } : {}),
+    ...(allowedHosts.length > 0 ? { allowedHosts } : {}),
+    ...(publicOrigin !== undefined ? { publicOrigin } : {}),
+    ...(companion !== undefined ? { launchCompanion: path.resolve(companion) } : {}),
+    ...(noGit ? { noGit: true } : {}),
+  };
+}
+
+function splitHosts(value: string): string[] {
+  return value
+    .split(",")
+    .map((host) => host.trim())
+    .filter(Boolean);
 }
 
 /**
@@ -60,8 +211,10 @@ export function parseStudioServeArgs(argv: string[]): StudioServeArgs | { error:
  * 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 Both invocations are read-only unless passed `--writable`. Neither
- * invocation resolves a Repository Link, so it runs from any directory.
+ * @remarks Both invocations are read-only unless passed `--writable`.
+ * `--terminal` adds the agent terminal and guards Studio with a per-start
+ * access token; `serve` is always guarded. Neither invocation resolves a
+ * Repository Link, so it runs from any directory.
  */
 export async function runStudioCommand(
   argv: string[] = [],
@@ -75,11 +228,13 @@ export async function runStudioCommand(
     return;
   }
 
-  if (argv.some((arg) => arg !== "--writable")) {
-    warn(`${FRAMEWORK_NAME}: \`studio\` takes no arguments; unrecognized: ${argv.join(" ")}`);
+  const parsed = parseStudioArgs(argv);
+  if ("error" in parsed) {
+    warn(`${FRAMEWORK_NAME}: ${parsed.error}`);
     process.exitCode = 1;
     return;
   }
+  if (!terminalAvailable(parsed, deps, warn)) return;
 
   const start = deps.startStudioServer ?? startStudioServer;
   const serve = deps.serveUntilInterrupted ?? serveUntilInterrupted;
@@ -87,7 +242,7 @@ export async function runStudioCommand(
 
   let server;
   try {
-    server = start({}, { writable: argv.includes("--writable") });
+    server = start({}, parsed);
   } catch (error) {
     warn(
       `${FRAMEWORK_NAME}: studio could not bind a port: ${
@@ -98,35 +253,60 @@ export async function runStudioCommand(
     return;
   }
 
-  log(server.url);
+  log(server.address);
   log("Press Ctrl+C to stop.");
 
   try {
-    await open(server.url);
+    await open(server.address);
   } catch (error) {
     warn(
       `${FRAMEWORK_NAME}: studio could not open a browser: ${
         error instanceof Error ? error.message : String(error)
       }`,
     );
-    warn(`${FRAMEWORK_NAME}: open ${server.url} manually; the server keeps serving.`);
+    warn(`${FRAMEWORK_NAME}: open ${server.address} manually; the server keeps serving.`);
   }
 
   await serve(server);
 }
 
+function terminalAvailable(
+  options: Pick<StudioServerOptions, "terminal">,
+  deps: StudioCommandDeps,
+  warn: (message: string) => void,
+): boolean {
+  if (!options.terminal) return true;
+  const reason = (deps.terminalUnsupportedReason ?? terminalUnsupportedReason)();
+  if (!reason) return true;
+  warn(`${FRAMEWORK_NAME}: --terminal ${reason}`);
+  process.exitCode = 1;
+  return false;
+}
+
 async function runStudioServeCommand(
   argv: string[],
   deps: StudioCommandDeps,
   log: (message: string) => void,
   warn: (message: string) => void,
 ): Promise<void> {
-  const parsed = parseStudioServeArgs(argv);
+  const parsed = parseStudioServeArgs(argv, deps.env ?? process.env);
   if ("error" in parsed) {
     warn(`${FRAMEWORK_NAME}: ${parsed.error}`);
     process.exitCode = 1;
     return;
   }
+  if (!terminalAvailable(parsed, deps, warn)) return;
+
+  if (parsed.launchCompanion) {
+    const inventory = await (deps.collectStudioInventory ?? collectStudioInventory)();
+    if (!inventory.companions.some((companion) => companion.path === parsed.launchCompanion)) {
+      warn(
+        `${FRAMEWORK_NAME}: --companion ${parsed.launchCompanion} is not a registered Companion Repository`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
 
   const start = deps.startStudioServer ?? startStudioServer;
   const serve = deps.serveUntilInterrupted ?? serveUntilInterrupted;
@@ -143,6 +323,7 @@ async function runStudioServeCommand(
     return;
   }
 
-  log(server.url);
+  log(server.address);
+  if (parsed.token) log("Access token: the value pinned by --token / MATE_STUDIO_TOKEN.");
   await serve(server);
 }

package/src/cli/commands/studio/openspec-cli.ts

@@ -27,7 +27,7 @@ export const WORKFLOW_CAPABILITY_ID = "openspec";
 /** Upper bound on one collection call; a hung wrapper must not hold a request open. */
 const OPENSPEC_TIMEOUT_MS = 60_000;
 
-export function openSpecWrapperPath(): string {
+function openSpecWrapperPath(): string {
   return path.join(getWrapperBinPath(), "openspec");
 }