@legionworks/facet 1.9.0

package/src/harness-adapters/mcp/cli-bridge.ts

@@ -0,0 +1,216 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  type FacetEnvelope,
+  type FacetErrorBody,
+  parseEnvelope,
+} from "../../shared/contracts/envelope";
+
+const STDERR_DETAIL_LIMIT = 4_096;
+
+export type FacetToolName = "publish" | "read_back" | "status" | "export" | "open";
+
+export interface FacetCliInvocation {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly stdin?: string;
+}
+
+export interface FacetCliResult {
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+
+export type FacetCliRunner = (invocation: FacetCliInvocation) => Promise<FacetCliResult>;
+
+export interface InvokeFacetOptions {
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly runner?: FacetCliRunner;
+  readonly stdin?: string;
+}
+
+export class FacetBridgeError extends Error {
+  constructor(
+    readonly body: FacetErrorBody,
+    cause?: unknown,
+  ) {
+    super(body.message, { cause });
+  }
+}
+
+function bridgeError(
+  code: string,
+  message: string,
+  details?: FacetErrorBody["details"],
+  cause?: unknown,
+): FacetBridgeError {
+  return new FacetBridgeError(
+    {
+      code,
+      message,
+      retryable: false,
+      ...(details === undefined ? {} : { details }),
+    },
+    cause,
+  );
+}
+
+function requiredString(input: Readonly<Record<string, unknown>>, key: string): string {
+  const value = input[key];
+  if (typeof value === "string" && value.length > 0) return value;
+  throw bridgeError("invalid_request", `${key} is required`);
+}
+
+function appendString(args: string[], flag: string, value: unknown): void {
+  if (typeof value === "string" && value.length > 0) args.push(flag, value);
+}
+
+export function buildFacetArgs(
+  tool: FacetToolName,
+  input: Readonly<Record<string, unknown>>,
+): string[] {
+  switch (tool) {
+    case "publish": {
+      const args = [
+        "publish",
+        "--artifact-id",
+        requiredString(input, "artifactId"),
+        "--type",
+        requiredString(input, "type"),
+      ];
+      appendString(args, "--renderer", input.renderer);
+      appendString(args, "--execution", input.execution);
+      appendString(args, "--file", input.file);
+      appendString(args, "--note", input.note);
+      appendString(args, "--parent-revision-id", input.parentRevisionId);
+      return args;
+    }
+    case "read_back": {
+      const args = ["read-back", "--artifact-id", requiredString(input, "artifactId")];
+      appendString(args, "--revision-sha", input.revisionSha);
+      if (input.tier !== undefined) args.push("--tier", String(input.tier));
+      return args;
+    }
+    case "status": {
+      const args = ["status"];
+      appendString(args, "--artifact-id", input.artifactId);
+      if (input.start === true) args.push("--start");
+      return args;
+    }
+    case "export": {
+      const args = [
+        "export",
+        requiredString(input, "artifactId"),
+        "--format",
+        requiredString(input, "format"),
+      ];
+      appendString(args, "--revision", input.revisionSha);
+      if (input.force === true) args.push("--force");
+      if (input.includeBytes === true) args.push("--include-bytes");
+      return args;
+    }
+    case "open": {
+      const args = ["open", "--artifact-id", requiredString(input, "artifactId")];
+      appendString(args, "--revision-sha", input.revisionSha);
+      args.push("--no-launch");
+      return args;
+    }
+  }
+}
+
+function resolveFacetCommand(env: NodeJS.ProcessEnv): Pick<FacetCliInvocation, "command" | "args"> {
+  const override = env.FACET_CLI?.trim();
+  if (override !== undefined && override.length > 0) return { command: override, args: [] };
+
+  const sourceCli = resolve(import.meta.dir, "../../cli/main.ts");
+  if (existsSync(sourceCli)) return { command: Bun.which("bun") ?? "bun", args: [sourceCli] };
+  return { command: "facet", args: [] };
+}
+
+async function runFacetCli(invocation: FacetCliInvocation): Promise<FacetCliResult> {
+  const proc = Bun.spawn([invocation.command, ...invocation.args], {
+    stderr: "pipe",
+    stdin: invocation.stdin === undefined ? "ignore" : "pipe",
+    stdout: "pipe",
+    ...(invocation.cwd === undefined ? {} : { cwd: invocation.cwd }),
+    ...(invocation.env === undefined ? {} : { env: invocation.env }),
+  });
+  if (invocation.stdin !== undefined) {
+    const stdin = proc.stdin;
+    if (stdin === undefined) throw new Error("Facet CLI stdin pipe was not created");
+    stdin.write(invocation.stdin);
+    stdin.end();
+  }
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+function boundedStderr(stderr: string): string {
+  const normalized = stderr.trim();
+  if (normalized.length <= STDERR_DETAIL_LIMIT) return normalized;
+  return `${normalized.slice(0, STDERR_DETAIL_LIMIT)}…`;
+}
+
+export function parseFacetStdout(stdout: string): FacetEnvelope<unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout);
+  } catch (cause) {
+    throw bridgeError("invalid_envelope", "Invalid Facet envelope on stdout", undefined, cause);
+  }
+  const parsed = parseEnvelope(value);
+  if (parsed.ok) return parsed.envelope;
+  throw new FacetBridgeError({
+    ...parsed.body,
+    message: `Invalid Facet envelope: ${parsed.body.message}`,
+  });
+}
+
+export async function invokeFacet(
+  args: readonly string[],
+  options: InvokeFacetOptions = {},
+): Promise<FacetEnvelope<unknown>> {
+  const env = options.env ?? process.env;
+  const resolved = resolveFacetCommand(env);
+  const invocation: FacetCliInvocation = {
+    command: resolved.command,
+    args: [...resolved.args, ...args],
+    ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    env,
+    ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+  };
+  const result = await (options.runner ?? runFacetCli)(invocation);
+  try {
+    return parseFacetStdout(result.stdout);
+  } catch (cause) {
+    const error =
+      cause instanceof FacetBridgeError
+        ? cause
+        : bridgeError(
+            "invalid_envelope",
+            cause instanceof Error ? cause.message : String(cause),
+            undefined,
+            cause,
+          );
+    throw new FacetBridgeError(
+      {
+        ...error.body,
+        details: {
+          ...error.body.details,
+          exitCode: result.exitCode,
+          ...(result.stderr.length === 0 ? {} : { stderr: boundedStderr(result.stderr) }),
+        },
+      },
+      cause,
+    );
+  }
+}

package/src/harness-adapters/mcp/main.ts

@@ -0,0 +1,15 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { createFacetMcpServer } from "./server";
+
+async function main(): Promise<void> {
+  const server = createFacetMcpServer();
+  await server.connect(new StdioServerTransport());
+}
+
+void main().catch((error: unknown) => {
+  process.stderr.write(
+    `facet MCP server failed: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+});

package/src/harness-adapters/mcp/server.ts

@@ -0,0 +1,164 @@
+import { mkdirSync } from "node:fs";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, ZodError } from "zod";
+import { FACET_VERSION } from "../../shared/version";
+
+import { buildFacetArgs, FacetBridgeError, invokeFacet } from "./cli-bridge";
+import {
+  ExportToolSchema,
+  OpenUrlToolSchema,
+  PublishToolSchema,
+  type PublishToolInput,
+  ReadBackToolSchema,
+  StatusToolSchema,
+} from "./tool-schemas";
+import { errEnvelope, type FacetEnvelope } from "../../shared/contracts/envelope";
+
+function requestId(): string {
+  return `req-mcp-${crypto.randomUUID()}`;
+}
+
+function errorEnvelope(cause: unknown): FacetEnvelope<never> {
+  if (cause instanceof ZodError) {
+    const issue = cause.issues[0];
+    const field = issue?.path.join(".") || "arguments";
+    return errEnvelope(requestId(), {
+      code: "invalid_request",
+      message: `Invalid MCP argument '${field}': ${issue?.message ?? "schema validation failed"}`,
+      retryable: false,
+      details: { field },
+    });
+  }
+  const body =
+    cause instanceof FacetBridgeError
+      ? cause.body
+      : {
+          code: "invalid_envelope",
+          message: cause instanceof Error ? cause.message : String(cause),
+          retryable: false,
+        };
+  return errEnvelope(requestId(), body);
+}
+
+const LooseToolInputSchema = z.record(z.unknown());
+
+function toolResult(envelope: FacetEnvelope<unknown>) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(envelope) }],
+    ...(envelope.ok ? {} : { isError: true }),
+  };
+}
+
+async function invoke(args: readonly string[], options: { cwd?: string; stdin?: string } = {}) {
+  try {
+    return toolResult(await invokeFacet(args, options));
+  } catch (cause) {
+    return toolResult(errorEnvelope(cause));
+  }
+}
+
+async function withInput<T>(
+  args: unknown,
+  parse: (input: unknown) => T,
+  run: (input: T) => Promise<ReturnType<typeof toolResult>>,
+): Promise<ReturnType<typeof toolResult>> {
+  try {
+    return await run(parse(args));
+  } catch (cause) {
+    return toolResult(errorEnvelope(cause));
+  }
+}
+
+function publishSource(input: PublishToolInput): {
+  file?: string;
+  stdin?: string;
+} {
+  if (input.sourceText !== undefined && input.file !== undefined) {
+    throw new FacetBridgeError({
+      code: "invalid_request",
+      message: "Pass sourceText or file, not both",
+      retryable: false,
+    });
+  }
+  if (input.sourceText !== undefined) return { stdin: input.sourceText };
+  if (input.file !== undefined) return { file: input.file };
+  throw new FacetBridgeError({
+    code: "invalid_request",
+    message: "publish requires sourceText or file",
+    retryable: false,
+  });
+}
+
+export function createFacetMcpServer(): McpServer {
+  const server = new McpServer({ name: "facet", version: FACET_VERSION });
+
+  server.registerTool(
+    "facet_export",
+    {
+      description:
+        "Export source or stored render evidence into outDir. Check envelope.ok for transport success; a successful publish verdict remains a separate data.verdict.status decision.",
+      inputSchema: LooseToolInputSchema,
+    },
+    async (args) =>
+      withInput(args, ExportToolSchema.parse, async (input) => {
+        mkdirSync(input.outDir, { recursive: true });
+        return invoke(buildFacetArgs("export", input), { cwd: input.outDir });
+      }),
+  );
+
+  server.registerTool(
+    "facet_open_url",
+    {
+      description:
+        "Return a Facet gallery frameUrl without launching a browser. This always invokes facet open --no-launch; agents must not launch desktop display.",
+      inputSchema: LooseToolInputSchema,
+    },
+    async (args) =>
+      withInput(args, OpenUrlToolSchema.parse, async (input) =>
+        invoke(buildFacetArgs("open", input)),
+      ),
+  );
+
+  server.registerTool(
+    "facet_publish",
+    {
+      description:
+        "Publish exactly one sourceText or local file. Check envelope.ok separately from data.verdict.status: stored verdict status error is not a transport failure.",
+      inputSchema: LooseToolInputSchema,
+    },
+    async (args) =>
+      withInput(args, PublishToolSchema.parse, async (input) => {
+        const source = publishSource(input);
+        return invoke(buildFacetArgs("publish", { ...input, ...source }), source);
+      }),
+  );
+
+  server.registerTool(
+    "facet_read_back",
+    {
+      description:
+        "Read back the latest or revision-bound stored verdict at Tier 0, Tier 1, or visual. Tier 1 and visual need browser evidence; inspect envelope.ok before verdict status.",
+      inputSchema: LooseToolInputSchema,
+    },
+    async (args) =>
+      withInput(args, ReadBackToolSchema.parse, async (input) =>
+        invoke(buildFacetArgs("read_back", input)),
+      ),
+  );
+
+  server.registerTool(
+    "facet_status",
+    {
+      description:
+        "Read Facet status. Set start only when activation is intended; envelope.ok reports command transport and never replaces verdict.status inspection.",
+      inputSchema: LooseToolInputSchema,
+    },
+    async (args) =>
+      withInput(args, StatusToolSchema.parse, async (input) =>
+        invoke(buildFacetArgs("status", input)),
+      ),
+  );
+
+  return server;
+}

package/src/harness-adapters/mcp/tool-schemas.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+import { ArtifactTypeSchema, RendererSchema } from "../../shared/contracts/artifact";
+
+const RevisionShaSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const ExecutionSchema = z.enum(["static", "interactive"]);
+const ReadBackTierSchema = z.union([z.literal(0), z.literal(1), z.literal("visual")]);
+
+export const PublishToolShape = {
+  artifactId: z.string().min(1),
+  type: ArtifactTypeSchema,
+  execution: ExecutionSchema.optional(),
+  renderer: RendererSchema.optional(),
+  sourceText: z.string().min(1).optional(),
+  file: z.string().min(1).optional(),
+  note: z.string().min(1).optional(),
+  parentRevisionId: z.string().min(1).optional(),
+};
+export const PublishToolSchema = z.object(PublishToolShape).strict();
+export type PublishToolInput = z.infer<typeof PublishToolSchema>;
+
+export const ReadBackToolShape = {
+  artifactId: z.string().min(1),
+  revisionSha: RevisionShaSchema.optional(),
+  tier: ReadBackTierSchema.optional(),
+};
+export const ReadBackToolSchema = z.object(ReadBackToolShape).strict();
+export type ReadBackToolInput = z.infer<typeof ReadBackToolSchema>;
+
+export const StatusToolShape = {
+  artifactId: z.string().min(1).optional(),
+  start: z.boolean().optional(),
+};
+export const StatusToolSchema = z.object(StatusToolShape).strict();
+export type StatusToolInput = z.infer<typeof StatusToolSchema>;
+
+export const ExportToolShape = {
+  artifactId: z.string().min(1),
+  revisionSha: RevisionShaSchema.optional(),
+  format: z.enum(["source", "render"]).default("source"),
+  outDir: z.string().min(1),
+  force: z.boolean().optional(),
+  includeBytes: z.boolean().optional(),
+};
+export const ExportToolSchema = z.object(ExportToolShape).strict();
+export type ExportToolInput = z.infer<typeof ExportToolSchema>;
+
+export const OpenUrlToolShape = {
+  artifactId: z.string().min(1),
+  revisionSha: RevisionShaSchema.optional(),
+};
+export const OpenUrlToolSchema = z.object(OpenUrlToolShape).strict();
+export type OpenUrlToolInput = z.infer<typeof OpenUrlToolSchema>;

package/src/harness-adapters/opencode/README.md

@@ -0,0 +1,10 @@
+# Facet adapter for OpenCode
+
+Install the adapter where OpenCode can invoke local tools, then point it at
+`facet.sh`. The adapter forwards argv and stdin to the Facet CLI and returns
+stdout unchanged.
+
+Use `facet status` before a workflow. Publish source through stdin; keep
+secrets out of artifacts. Promotion remains operator-only.
+
+→ [Facet agent skill](../../../skills/facet/SKILL.md) · [CLI reference](../../../docs/reference/cli.md)

package/src/harness-adapters/opencode/facet.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec bun "$SCRIPT_DIR/../../../src/cli/main.ts" "$@"

package/src/runtime/compiled-entrypoints.ts

@@ -0,0 +1,69 @@
+import {
+  runServiceProcess,
+  type ParsedServiceArgs,
+  type ServiceRunnerModules,
+} from "../service/process";
+import { createTier0Runner, probeTier0Isolation } from "../validation/tier0/runner";
+import { formatWorkerUnhandled, runWorkerLoop } from "../validation/tier0/worker-entry";
+import { createTier1Runner, probeTier1Availability } from "../validation/tier1/runner";
+
+export { buildTier0WorkerArgs } from "../shared/build-mode";
+
+export interface CompiledEntrypointHooks {
+  readonly runService?: (argv: readonly string[]) => Promise<number>;
+  readonly runTier0Worker?: () => Promise<number>;
+}
+
+export interface CompiledServiceDeps {
+  readonly runServiceProcess?: typeof runServiceProcess;
+}
+
+export interface CompiledWorkerDeps {
+  readonly stdin?: ReadableStreamDefaultReader<Uint8Array>;
+  readonly runWorkerLoop?: typeof runWorkerLoop;
+  readonly writeStderr?: (text: string) => void;
+  readonly writeStdout?: (text: string) => void;
+}
+
+function loadCompiledModules(
+  _args: ParsedServiceArgs,
+  _env: NodeJS.ProcessEnv,
+): Promise<ServiceRunnerModules> {
+  return Promise.resolve({
+    tier0: { factory: createTier0Runner, probe: probeTier0Isolation },
+    loadTier1: () => Promise.resolve({ factory: createTier1Runner, probe: probeTier1Availability }),
+  });
+}
+
+export async function runCompiledService(
+  argv: readonly string[],
+  deps: CompiledServiceDeps = {},
+): Promise<number> {
+  return (deps.runServiceProcess ?? runServiceProcess)(argv, process.env, loadCompiledModules);
+}
+
+export async function runCompiledTier0Worker(deps: CompiledWorkerDeps = {}): Promise<number> {
+  const stdin = deps.stdin ?? Bun.stdin.stream().getReader();
+  const writeStdout = deps.writeStdout ?? process.stdout.write.bind(process.stdout);
+  const writeStderr = deps.writeStderr ?? process.stderr.write.bind(process.stderr);
+  const workerLoop = deps.runWorkerLoop ?? runWorkerLoop;
+  try {
+    return await workerLoop(stdin, writeStdout, writeStderr);
+  } catch (error) {
+    writeStderr(formatWorkerUnhandled(error));
+    return 1;
+  }
+}
+
+export async function dispatchCompiledEntrypoint(
+  argv: readonly string[],
+  hooks: CompiledEntrypointHooks = {},
+): Promise<number | null> {
+  if (argv[0] === "--facet-internal-service") {
+    return (hooks.runService ?? runCompiledService)(argv.slice(1));
+  }
+  if (argv[0] === "--facet-internal-tier0-worker") {
+    return (hooks.runTier0Worker ?? runCompiledTier0Worker)();
+  }
+  return null;
+}