@uniqbit/mate-core 0.18.1-canary.4 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.1-canary.4",
+  "version": "0.18.1",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {

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

@@ -77,3 +77,53 @@ export function openReportInBrowser(
     });
   });
 }
+
+export const STUDIO_PUBLISH_TIMEOUT_MS = 3_000;
+
+export interface StudioPublishDeps {
+  env?: NodeJS.ProcessEnv;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export interface HostedReport {
+  id: string;
+  /** Present only when Studio has a configured public origin. */
+  url?: string;
+}
+
+/**
+ * Publishes to the Studio that spawned this process; `null` outside one. Errors
+ * never carry the credential or the loopback endpoint.
+ */
+export async function publishReportToStudio(
+  title: string,
+  html: string,
+  deps: StudioPublishDeps = {},
+): Promise<HostedReport | null> {
+  const env = deps.env ?? process.env;
+  const endpoint = env.MATE_STUDIO_REPORT_URL;
+  const token = env.MATE_STUDIO_REPORT_TOKEN;
+  if (!endpoint || !token) return null;
+
+  let response: Response;
+  try {
+    response = await (deps.fetch ?? fetch)(new URL("/api/reports", endpoint), {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ title, html }),
+      signal: AbortSignal.timeout(deps.timeoutMs ?? STUDIO_PUBLISH_TIMEOUT_MS),
+    });
+  } catch {
+    throw new Error("Studio did not answer in time");
+  }
+  if (!response.ok) throw new Error(`Studio refused the report (HTTP ${response.status})`);
+  let body: { id?: unknown; url?: unknown };
+  try {
+    body = (await response.json()) as typeof body;
+  } catch {
+    throw new Error("Studio answered with an unreadable response");
+  }
+  if (typeof body.id !== "string") throw new Error("Studio answered with an unreadable response");
+  return { id: body.id, ...(typeof body.url === "string" ? { url: body.url } : {}) };
+}

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

@@ -11,7 +11,7 @@ import {
 import type { CollectorDeps } from "./collector";
 import { reportDataToDocument } from "./adapter";
 import { parseReportDocument, type ReportValidationError } from "./contract";
-import { openReportInBrowser, writeTemporaryReport } from "./delivery";
+import { openReportInBrowser, publishReportToStudio, writeTemporaryReport } from "./delivery";
 import { renderHTML, renderJSON } from "./renderer";
 import type { ReportData, ReportDocument, ReportOptions } from "./types";
 
@@ -20,6 +20,7 @@ interface ReportCommandDeps extends CollectorDeps {
   resolveFrameworkContext?: typeof resolveFrameworkContext;
   writeTemporaryReport?: typeof writeTemporaryReport;
   openReportInBrowser?: typeof openReportInBrowser;
+  publishReportToStudio?: typeof publishReportToStudio;
   readInput?: (input: string) => Promise<string>;
 }
 
@@ -196,11 +197,28 @@ export async function runReportCommand(
     return;
   }
 
-  let reportPath: string | undefined;
+  const html = renderHTML(reportDocument);
   try {
-    reportPath = await (deps.writeTemporaryReport ?? writeTemporaryReport)(
-      renderHTML(reportDocument),
+    const hosted = await (deps.publishReportToStudio ?? publishReportToStudio)(
+      reportDocument.title,
+      html,
     );
+    if (hosted) {
+      console.log(
+        hosted.url
+          ? `Report hosted in Studio: ${hosted.url}`
+          : `Report hosted in Studio: open Studio → Reports (report ${hosted.id})`,
+      );
+      return;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Unable to host the report in Studio: ${message}; opening it locally instead`);
+  }
+
+  let reportPath: string | undefined;
+  try {
+    reportPath = await (deps.writeTemporaryReport ?? writeTemporaryReport)(html);
     await (deps.openReportInBrowser ?? openReportInBrowser)(reportPath);
     console.log(`Report opened from ${reportPath}`);
   } catch (error) {

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

@@ -86,6 +86,12 @@ export function tokensEqual(candidate: string, expected: string): boolean {
   return timingSafeEqual(digest(candidate), digest(expected));
 }
 
+/** The `Authorization: Bearer` credential, or `null`; callers compare it with `tokensEqual`. */
+export function readBearer(request: Request): string | null {
+  const match = /^Bearer ([^\s]+)$/i.exec(request.headers.get("authorization") ?? "");
+  return match ? match[1]! : null;
+}
+
 function readCookie(request: Request, name: string): string | null {
   const header = request.headers.get("cookie");
   if (!header) return null;

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

@@ -0,0 +1,87 @@
+import type { StudioSkillInventory } from "./mate-inventory";
+import type { TerminalAgent } from "./terminal";
+
+/** Lowercase letters, digits and hyphens, so a subject can never carry shell syntax or a flag. */
+export const SUBJECT_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/**
+ * A skill Studio may launch with a subject. Fixed in code: the registry, not
+ * an installed skill directory, authorizes an action.
+ */
+export interface StudioAction {
+  id: string;
+  skill: string;
+  label: string;
+  subject: "spec";
+  prompts: Record<TerminalAgent, (subject: string) => string>;
+}
+
+export const STUDIO_ACTIONS: readonly StudioAction[] = [
+  {
+    id: "show-me",
+    skill: "mate-show-me",
+    label: "Show me",
+    subject: "spec",
+    prompts: {
+      claude: (subject) => `/mate-show-me ${subject}`,
+      opencode: (subject) => `Use the mate-show-me skill on spec ${subject}.`,
+    },
+  },
+];
+
+export function findAction(id: unknown): StudioAction | null {
+  return STUDIO_ACTIONS.find((action) => action.id === id) ?? null;
+}
+
+/** Skill trees each agent loads; Claude does not read the shared Agents tree. */
+const SKILL_TREES: Record<TerminalAgent, (keyof StudioSkillInventory)[]> = {
+  claude: ["claude"],
+  opencode: ["opencode", "agents"],
+};
+
+/** Availability only: a directory shows the skill is installed, not that Mate shipped it. */
+export function skillInstalledFor(
+  inventory: StudioSkillInventory,
+  skill: string,
+  agent: TerminalAgent,
+): boolean {
+  return SKILL_TREES[agent].some((tree) => inventory[tree].includes(skill));
+}
+
+/** The first-turn prompt arguments for one agent: a trailing positional for Claude, `--prompt` for OpenCode. */
+export function promptArgs(action: StudioAction, agent: TerminalAgent, subject: string): string[] {
+  const prompt = action.prompts[agent](subject);
+  return agent === "opencode" ? ["--prompt", prompt] : [prompt];
+}
+
+/** What the Specs view renders for one action on the displayed companion. */
+export interface SpecActionOffer {
+  action: StudioAction;
+  /** Agents a run button may start; empty without a matching terminal. */
+  runAgents: TerminalAgent[];
+  /** Agents whose prompt Copy may offer. */
+  copyAgents: TerminalAgent[];
+}
+
+const AGENTS: readonly TerminalAgent[] = ["claude", "opencode"];
+
+/**
+ * Run needs a terminal targeting the displayed companion and a launchable
+ * agent with the skill; Copy needs only the installed skill.
+ */
+export function specActionOffers(
+  companionPath: string,
+  inventory: StudioSkillInventory | undefined,
+  terminal: { target: { path: string } | null; agents: TerminalAgent[] } | null,
+): SpecActionOffer[] {
+  if (!inventory) return [];
+  const targeted = terminal?.target?.path === companionPath;
+  return STUDIO_ACTIONS.flatMap((action) => {
+    const copyAgents = AGENTS.filter((agent) => skillInstalledFor(inventory, action.skill, agent));
+    if (copyAgents.length === 0) return [];
+    const runAgents = targeted
+      ? copyAgents.filter((agent) => terminal?.agents.includes(agent))
+      : [];
+    return [{ action, runAgents, copyAgents }];
+  });
+}

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

@@ -0,0 +1,176 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { COMPANION_DIGEST_PATTERN } from "./selection";
+
+export const REPORT_LIMITS = {
+  reports: 20,
+  bytes: 50 * 1024 * 1024,
+  ageMs: 7 * 24 * 60 * 60 * 1000,
+  /** The bundled inlined Mermaid runtime alone is about 5.3 MiB. */
+  uploadBytes: 10 * 1024 * 1024,
+};
+
+/** What listings expose: no paths, no content. */
+export interface StoredReport {
+  id: string;
+  title: string;
+  createdAt: number;
+  bytes: number;
+}
+
+export interface ReportStoreOptions {
+  /** Defaults to `~/.mate/studio/reports`. */
+  root?: string;
+  now?: () => number;
+  limits?: Partial<typeof REPORT_LIMITS>;
+}
+
+export interface ReportStore {
+  publish(companion: string, report: { title: string; html: string }): Promise<StoredReport>;
+  /** Newest first. Never expires by age: only `publish` and `cleanup` remove. */
+  list(companion: string): Promise<StoredReport[]>;
+  /** The HTML of a stored report of any companion, or `null`. */
+  read(id: string): Promise<string | null>;
+  /** Removes expired reports from every companion. */
+  cleanup(): Promise<void>;
+}
+
+const REPORT_ID_PATTERN = /^[0-9a-f]{32}$/;
+
+export function isReportId(value: string): boolean {
+  return REPORT_ID_PATTERN.test(value);
+}
+
+function defaultReportRoot(): string {
+  return path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "studio", "reports");
+}
+
+function isEntry(value: unknown): value is StoredReport {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.id === "string" &&
+    isReportId(entry.id) &&
+    typeof entry.title === "string" &&
+    typeof entry.createdAt === "number" &&
+    typeof entry.bytes === "number"
+  );
+}
+
+export function createReportStore(options: ReportStoreOptions = {}): ReportStore {
+  const root = options.root ?? defaultReportRoot();
+  const now = options.now ?? Date.now;
+  const limits = { ...REPORT_LIMITS, ...options.limits };
+  let queue: Promise<unknown> = Promise.resolve();
+
+  /** One writer at a time: index read-modify-write must not interleave. */
+  const serialized = <T>(task: () => Promise<T>): Promise<T> => {
+    const run = queue.then(task, task);
+    queue = run.catch(() => {});
+    return run;
+  };
+
+  const directory = (companion: string) => {
+    if (!COMPANION_DIGEST_PATTERN.test(companion)) throw new Error("invalid companion digest");
+    return path.join(root, companion);
+  };
+
+  const readIndex = async (dir: string): Promise<StoredReport[]> => {
+    try {
+      const parsed: unknown = JSON.parse(await readFile(path.join(dir, "index.json"), "utf8"));
+      return Array.isArray(parsed) ? parsed.filter(isEntry) : [];
+    } catch {
+      return [];
+    }
+  };
+
+  const writeIndex = async (dir: string, entries: StoredReport[]) => {
+    const temporary = path.join(dir, `index.${randomBytes(4).toString("hex")}.tmp`);
+    await writeFile(temporary, JSON.stringify(entries), "utf8");
+    await rename(temporary, path.join(dir, "index.json"));
+  };
+
+  const remove = (dir: string, entry: StoredReport) =>
+    rm(path.join(dir, `${entry.id}.html`), { force: true });
+
+  /** Newest first; drops expired entries, then evicts oldest until both caps hold. */
+  const prune = async (dir: string, entries: StoredReport[], keep?: string) => {
+    const cutoff = now() - limits.ageMs;
+    const kept: StoredReport[] = [];
+    let bytes = 0;
+    for (const entry of entries.toSorted((a, b) => b.createdAt - a.createdAt)) {
+      const evictable =
+        entry.createdAt < cutoff ||
+        kept.length >= limits.reports ||
+        bytes + entry.bytes > limits.bytes;
+      if (evictable && entry.id !== keep) {
+        await remove(dir, entry);
+        continue;
+      }
+      kept.push(entry);
+      bytes += entry.bytes;
+    }
+    return kept;
+  };
+
+  return {
+    publish: (companion, report) =>
+      serialized(async () => {
+        const dir = directory(companion);
+        await mkdir(dir, { recursive: true });
+        const entry: StoredReport = {
+          id: randomBytes(16).toString("hex"),
+          title: report.title,
+          createdAt: now(),
+          bytes: Buffer.byteLength(report.html),
+        };
+        await writeFile(path.join(dir, `${entry.id}.html`), report.html, "utf8");
+        const kept = await prune(dir, [entry, ...(await readIndex(dir))], entry.id);
+        await writeIndex(dir, kept);
+        return entry;
+      }),
+    list: (companion) =>
+      serialized(async () =>
+        (await readIndex(directory(companion))).toSorted((a, b) => b.createdAt - a.createdAt),
+      ),
+    read: (id) =>
+      serialized(async () => {
+        if (!isReportId(id)) return null;
+        let companions: string[];
+        try {
+          companions = await readdir(root);
+        } catch {
+          return null;
+        }
+        for (const companion of companions) {
+          if (!COMPANION_DIGEST_PATTERN.test(companion)) continue;
+          const dir = path.join(root, companion);
+          if (!(await readIndex(dir)).some((entry) => entry.id === id)) continue;
+          try {
+            return await readFile(path.join(dir, `${id}.html`), "utf8");
+          } catch {
+            return null;
+          }
+        }
+        return null;
+      }),
+    cleanup: () =>
+      serialized(async () => {
+        let companions: string[];
+        try {
+          companions = await readdir(root);
+        } catch {
+          return;
+        }
+        for (const companion of companions) {
+          if (!COMPANION_DIGEST_PATTERN.test(companion)) continue;
+          const dir = path.join(root, companion);
+          await writeIndex(dir, await prune(dir, await readIndex(dir)));
+        }
+      }),
+  };
+}

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

@@ -1,2 +1,14 @@
 /** Default bind stays loopback because payloads carry absolute paths and names. */
 export const STUDIO_HOSTNAME = "127.0.0.1";
+
+/** A folder's entries as an HTML fragment, fetched when the viewer first expands it. */
+export const VAULT_DIR_ROUTE = "/api/vault/dir";
+/** Name-filter matches over the whole listed tree, as an HTML fragment. */
+export const VAULT_FILTER_ROUTE = "/api/vault/filter";
+/** Server-sent listing generations: a newer one marks the displayed tree stale. */
+export const VAULT_CHANGES_ROUTE = "/api/vault/changes";
+
+/** `GET` lists a companion's hosted reports; `POST` publishes with a session credential. */
+export const REPORTS_ROUTE = "/api/reports";
+/** A hosted report's HTML is served at this prefix plus its id. */
+export const REPORT_VIEW_PREFIX = "/studio/reports/";

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

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 
 import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
 
-export type StudioView = "dashboard" | "workflow" | "specs" | "skills" | "vault";
+export type StudioView = "dashboard" | "workflow" | "specs" | "skills" | "vault" | "reports";
 
 export const STUDIO_VIEWS: readonly StudioView[] = [
   "dashboard",
@@ -10,6 +10,7 @@ export const STUDIO_VIEWS: readonly StudioView[] = [
   "specs",
   "skills",
   "vault",
+  "reports",
 ];
 
 export const COMPANION_PARAM = "companion";