@uniqbit/mate-core 0.17.0-canary.10 → 0.17.0-canary.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.17.0-canary.10",
+  "version": "0.17.0-canary.11",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [
@@ -36,6 +36,11 @@
     "@opentui/keymap": "^0.4.5",
     "@opentui/solid": "^0.4.5",
     "@tanstack/highlight": "0.0.10",
+    "@xterm/addon-clipboard": "^0.2.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
     "hono": "^4.13.5",
     "ink": "^7.1.0",
     "react": "^19.2.7",

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

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

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

@@ -269,7 +269,7 @@ async function resolved(
 }
 
 /** Tag namespace segregating spec publications from dated change anchors. */
-export const SPEC_TAG_NAMESPACE = "openspec/specs";
+const SPEC_TAG_NAMESPACE = "openspec/specs";
 /** Spec ids named individually before the remainder collapses into a count. */
 const SPEC_LABEL_LIMIT = 3;
 
@@ -297,7 +297,7 @@ function specLabel(paths: string[]): string {
 }
 
 /** Commit subject for a spec publication; it belongs to no change, so it names specs, never an anchor. */
-export function specCommitSubject(paths: string[]): string {
+function specCommitSubject(paths: string[]): string {
   const ids = specIds(paths);
   const named = ids.slice(0, SPEC_LABEL_LIMIT);
   const remaining = ids.length - named.length;

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

@@ -5,7 +5,7 @@ import { openspecFinisher } from "./openspec";
  * Artifact-kind → finisher factory. openspec is the only kind for now; a future ADR
  * finisher registers here and is selected via `--type`, with no engine changes.
  */
-export const FINISHERS: Record<string, FinisherFactory> = {
+const FINISHERS: Record<string, FinisherFactory> = {
   openspec: openspecFinisher,
 };
 

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

@@ -52,7 +52,7 @@ export interface ArchiveEntry {
 const ARCHIVE_ANCHOR_PATTERN = /^\d{4}-\d{2}-\d{2}-.+$/;
 const ARCHIVE_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/;
 
-export const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
+const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
 export const SPECS_RELATIVE_DIR = "openspec/specs";
 
 /** The tag `mate artifact publish` creates, never a recomputed date. */

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

@@ -1,17 +1,2 @@
 export { runArtifactPendingCommand } from "./command";
 export type { PendingCommandDeps, PendingResult } from "./command";
-export {
-  ARCHIVE_RELATIVE_DIR,
-  SPECS_RELATIVE_DIR,
-  discoverArchives,
-  finishMarker,
-  pendingArchives,
-  unattributedSpecs,
-} from "./discovery";
-export type {
-  ArchiveEntry,
-  CommitState,
-  SpecAttribution,
-  UnattributedSpec,
-  UncommittedSpecChange,
-} from "./discovery";

package/src/cli/commands/cap/graphify.ts

@@ -29,7 +29,7 @@ const GRAPHIFY_PATH_COMMANDS = new Set([
 
 const GRAPHIFY_GRAPH_COMMANDS = new Set(["query", "path", "explain", "affected", "tree"]);
 
-export function deriveGraphifyPaths(companionPath: string, repositoryId: string): GraphifyPaths {
+function deriveGraphifyPaths(companionPath: string, repositoryId: string): GraphifyPaths {
   const graphifyOut = path.join(
     companionPath,
     GRAPHIFY_STORE_SEGMENT,

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

@@ -8,6 +8,7 @@ import {
   updateHubPlugins,
 } from "../../../lib/orchestrator/companion-hub";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+import { writeJsonStdout } from "../../write-json-stdout";
 
 function positionalArgs(argv: string[]): string[] {
   const values: string[] = [];
@@ -71,7 +72,7 @@ async function runHubSync(argv: string[]): Promise<void> {
   const results = await syncHub(process.cwd());
   const plugins = await updateHubPlugins(process.cwd());
   if (argv.includes("--json")) {
-    console.log(JSON.stringify({ companions: results, plugins }));
+    await writeJsonStdout({ companions: results, plugins }, { space: 0 });
     return;
   }
   for (const result of results) console.log(`${result.id}: ${result.status} (${result.message})`);

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

@@ -1,6 +1,7 @@
 import { CompanionStore } from "../../../lib/orchestrator/companion-store";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
 import { renderRepoListTable } from "../../repo-list-table";
+import { writeJsonStdout } from "../../write-json-stdout";
 
 /**
  * @command mate companion list
@@ -23,7 +24,7 @@ export async function runCompanionListCommand(argv: string[] = []): Promise<void
   const forceJson = argv.includes("--json");
 
   if (forceJson || !process.stdout.isTTY) {
-    console.log(JSON.stringify({ repositories }, null, 2));
+    await writeJsonStdout({ repositories });
     return;
   }
 

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

@@ -3,7 +3,7 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { preparePrebuiltWorkspace } from "../../../lib/prebuilt-workspace-prepare";
 
-export const companionPrepareCommandDeps = {
+const companionPrepareCommandDeps = {
   preparePrebuiltWorkspace,
 };
 
@@ -13,7 +13,7 @@ interface ParsedPrepareArgs {
   error?: string;
 }
 
-export function parsePrepareArgs(argv: string[]): ParsedPrepareArgs {
+function parsePrepareArgs(argv: string[]): ParsedPrepareArgs {
   let bundle: string | undefined;
   const positional: string[] = [];
 

package/src/cli/commands/doctor.ts

@@ -10,6 +10,7 @@ import { resolveRootContext, type RootContext } from "../../lib/orchestrator/roo
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
 import { getRequiredPluginDrift } from "../../tools/setup/policy";
 import { resolveCommandOnPath } from "../../tools/setup/utils";
+import { writeJsonStdout } from "../write-json-stdout";
 import { printSection, renderKeyValueTable, renderTable } from "./status";
 
 interface DoctorDeps {
@@ -354,7 +355,7 @@ function renderHumanReport(report: DoctorReport): void {
 export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {}): Promise<void> {
   const report = await collectDoctorReport(deps);
   if (argv.includes("--json")) {
-    console.log(JSON.stringify(report, null, 2));
+    await writeJsonStdout(report);
     return;
   }
   renderHumanReport(report);

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/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,203 @@
+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;
+}
+
+export type StudioRequirement = "none" | "token";
+
+/**
+ * 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;
+}