@ambitresearch/genie 1.3.1

package/dist/tools/plan.js

@@ -0,0 +1,146 @@
+/**
+ * MCP tool: plan (M1-07).
+ *
+ * The single user-visible permission grant that locks `writes`, `deletes`,
+ * and `localDir`. Returns a `planId` that downstream write/delete calls must
+ * present. Without a valid `planId`, those verbs are rejected.
+ *
+ * Input:  { kitId: string, writes: string[], deletes?: string[], localDir?: string }
+ * Output: { planId: string }
+ */
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { createPlan, TooManyWritesError, TooComplexGlobError, MAX_WRITES, MAX_WILDCARDS, } from "../plans/index.js";
+/** Input schema for plan (Zod v4). */
+const inputSchema = {
+    kitId: z.string().min(1).describe("The kit ID to create a plan for."),
+    // Intentionally NOT `.max(MAX_WRITES)`: a schema-level cap makes the MCP SDK
+    // reject oversized arrays at the protocol layer with a generic, non-JSON
+    // "MCP error ..." string — before the handler below runs. That would bypass
+    // the structured `TooManyWritesError` JSON payload (AC3) and its audit-log
+    // line (AC10). `createPlan()` enforces the same limit at runtime instead, so
+    // the handler's own try/catch owns the response shape.
+    writes: z
+        .array(z.string())
+        .describe(`Array of glob patterns for files that will be written (max ${MAX_WRITES} patterns, ≤${MAX_WILDCARDS} wildcards each).`),
+    deletes: z
+        .array(z.string())
+        .optional()
+        .describe("Optional array of glob patterns for files that will be deleted."),
+    localDir: z
+        .string()
+        .optional()
+        .describe("Optional local directory path that uploads may read from. Defaults to current working directory."),
+};
+/** Output schema for plan (Zod v4 raw shape) — declared alongside the
+ * `structuredContent` return so `tools/list` advertises it, matching the
+ * repo-wide convention (see list_kits.ts, get_project.ts, bind_kit.ts). */
+const outputSchema = {
+    planId: z
+        .string()
+        .describe("The plan ID that downstream write_files/delete_files calls must present."),
+};
+/**
+ * Register the `mcp__genie__plan` tool on the given MCP server.
+ */
+export function registerPlan(server) {
+    server.registerTool("mcp__genie__plan", {
+        title: "Plan",
+        description: "Lock write/delete patterns and localDir for a kit. Returns a planId " +
+            "that must be presented to write_files/delete_files. " +
+            "Plans expire after 1h of inactivity. Reach for this after conjure/refine returns " +
+            "files you want to persist — plan first, then write_files (or delete_files) with " +
+            "the returned planId.",
+        inputSchema,
+        outputSchema,
+    }, async ({ kitId, writes, deletes = [], localDir, }) => {
+        // Default localDir to cwd
+        const resolvedLocalDir = localDir ? resolve(localDir) : process.cwd();
+        // Validate that localDir exists AND is a directory. AC5 requires "an
+        // existing directory" — a plain existence check would also accept a
+        // regular file, silently creating a plan whose localDir is unusable.
+        let localDirStat;
+        try {
+            localDirStat = await stat(resolvedLocalDir);
+        }
+        catch {
+            localDirStat = null;
+        }
+        if (!localDirStat || !localDirStat.isDirectory()) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "InvalidLocalDir",
+                            message: `Local directory "${resolvedLocalDir}" does not exist or is not a directory.`,
+                        }),
+                    },
+                ],
+            };
+        }
+        try {
+            const state = await createPlan(kitId, writes, deletes, resolvedLocalDir);
+            // Emit audit log line. MUST go to stderr, never stdout: on the stdio
+            // transport (the default when a harness pipes JSON-RPC — see
+            // transport.ts), stdout *is* the protocol stream, and a stray
+            // console.log line there corrupts every client's message framing.
+            process.stderr.write(JSON.stringify({
+                event: "plan.created",
+                kitId,
+                planId: state.planId,
+                writeCount: writes.length,
+                deleteCount: deletes.length,
+                timestamp: state.createdAt,
+            }) + "\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ planId: state.planId }),
+                    },
+                ],
+                structuredContent: { planId: state.planId },
+            };
+        }
+        catch (err) {
+            if (err instanceof TooManyWritesError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "TooManyWritesError",
+                                message: err.message,
+                                count: err.count,
+                                max: MAX_WRITES,
+                            }),
+                        },
+                    ],
+                };
+            }
+            if (err instanceof TooComplexGlobError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "TooComplexGlobError",
+                                message: err.message,
+                                pattern: err.pattern,
+                                wildcardCount: err.wildcardCount,
+                                max: MAX_WILDCARDS,
+                            }),
+                        },
+                    ],
+                };
+            }
+            throw err; // unexpected errors bubble up as MCP internal errors
+        }
+    });
+}
+//# sourceMappingURL=plan.js.map

package/dist/tools/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"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"}

package/dist/tools/preview.d.ts

@@ -0,0 +1,289 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Manifest } from "../manifest/index.js";
+import { type TransportKind } from "../transport.js";
+import type { CardAssetBroker } from "../ui/card-asset-broker.js";
+import { type EmbeddedManifest, type PreviewReader } from "../ui/grid-resource.js";
+export declare const PREVIEW_TOOL_NAME = "mcp__genie__preview";
+/**
+ * Vite dev-server default port. Duplicated as a local literal (rather than
+ * imported from `@ambitresearch/genie-viewer`) so this module carries no build-time edge to
+ * the viewer package — the whole point of the lazy boot seam below. Kept in
+ * sync with `@ambitresearch/genie-viewer`'s `DEFAULT_VIEWER_PORT` (RFC §6.9/§14).
+ */
+export declare const DEFAULT_VIEWER_PORT = 5173;
+/**
+ * The MCP Apps extension identifier (ext-apps spec 2026-01-26, "Client<>Server
+ * Capability Negotiation"): a host that renders `ui://` app resources
+ * advertises `capabilities.extensions["io.modelcontextprotocol/ui"]` in its
+ * `initialize` request, with `mimeTypes` naming the profiles it can render.
+ */
+export declare const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** The MCP-Apps HTML profile the grid resource serves (spec §Resource Discovery). */
+export declare const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** Widget-only tool-result metadata carrying CSP-authorized card routes. */
+export declare const PREVIEW_EMBEDDED_MANIFEST_META_KEY = "genie/embeddedManifest";
+/**
+ * Authoritative `ui://` capability check: true when the client's `initialize`
+ * capabilities carry the MCP Apps extension with a `mimeTypes` array that
+ * includes {@link MCP_APP_MIME}. This is the spec-defined negotiation. `caps`
+ * is typed `unknown` because the SDK's `ClientCapabilities` models
+ * `extensions` as a passthrough bag — every level is checked defensively.
+ */
+export declare function hasUiExtensionCapability(caps: unknown): boolean;
+/**
+ * Resolve MCP Apps negotiation without collapsing "not advertised" and
+ * "explicitly not supported." A missing `extensions` mechanism returns
+ * `undefined`. This is distinct from an explicit negative because metadata-linked
+ * MCP Apps hosts may omit the extension capability even when they advertise
+ * unrelated extensions. Only a present UI extension with a malformed or
+ * unsupported MIME declaration is a negotiated negative.
+ */
+export declare function getUiExtensionCapability(caps: unknown): boolean | undefined;
+export interface ResourceUriParams {
+    kitId: string;
+    componentName?: string;
+    group?: string;
+}
+/**
+ * Build the `ui://genie/grid?…` resource URI (AC3/AC4). The query string always
+ * carries `kitId` and appends the optional `componentName` / `group` filters in
+ * a STABLE order (kitId → componentName → group) so the URI — and thus the
+ * resource M4-06 resolves and any cache keyed on it — is deterministic for a
+ * given argument set. Values are percent-encoded via `URLSearchParams`.
+ */
+export declare function buildResourceUri(params: ResourceUriParams): string;
+/** A `kitId` that fails the shared `KIT_ID_PATTERN` shape (traversal guard). */
+export declare class InvalidKitIdError extends Error {
+    readonly kitId: string;
+    readonly code = "InvalidKitIdError";
+    constructor(kitId: string);
+}
+/** A well-formed kitId that does not identify an existing kit directory. */
+export declare class KitNotFoundError extends Error {
+    readonly kitId: string;
+    readonly code = "KitNotFoundError";
+    constructor(kitId: string);
+}
+/**
+ * Resolve a `kitId` to its on-disk kit directory under `kitsRoot`, rejecting
+ * any id that isn't a well-formed slug BEFORE the `join` — an unvalidated id
+ * like `../../etc` would otherwise escape the kits root (RFC §10 T-13, the same
+ * traversal class `write_files`/`read_file` guard). Only shape is checked here;
+ * Existence is checked by {@link runPreview} before compilation so a missing
+ * slug cannot create a phantom kit through manifest persistence.
+ */
+export declare function resolveKitDir(kitsRoot: string, kitId: string): string;
+/** A request to boot (or reuse) a viewer for one kit directory. */
+export interface BootRequest {
+    /** Absolute kit directory the viewer serves as its Vite root. */
+    kitDir: string;
+    /** Requested dev-server port; the booter may fall back to the next free one. */
+    port?: number;
+    /**
+     * Whether the booter should open its unfiltered base URL on first boot.
+     * On its local path, {@link runPreview} boots or reuses with `false`, adds the
+     * requested component and group filters, then calls
+     * {@link ViewerRegistry.open} with that exact target when harness policy
+     * allows browser fallback. This option remains available to direct
+     * registry/booter callers that explicitly want the base URL opened during
+     * boot.
+     * Undefined is treated as `false` (a booter that never opens is always safe).
+     */
+    open?: boolean;
+}
+/** A running viewer the registry hands back to the tool. */
+export interface BootedViewer {
+    /** The browsable preview URL (what the text content advertises). */
+    url: string;
+    /** The port the viewer actually bound. */
+    port: number;
+    /** Best-effort browser open for this already-running viewer. */
+    open: (target?: string) => Promise<void>;
+    /** Tear the viewer down (used by {@link ViewerRegistry.closeAll}). */
+    close: () => Promise<void>;
+}
+/** Boots a viewer for a kit dir, or rejects if it cannot (→ AC6 fallback). */
+export type ViewerBooter = (req: BootRequest) => Promise<BootedViewer>;
+/**
+ * Caches one running viewer per kit directory so repeated `preview` calls reuse
+ * it instead of booting a fresh Vite each time (AC5). Keyed on the resolved kit
+ * dir; concurrent calls for the same dir share ONE in-flight boot (the promise
+ * is cached, not just the resolved value). A boot that REJECTS is evicted so a
+ * later call retries rather than replaying the dead promise forever.
+ */
+export declare class ViewerRegistry {
+    private readonly booter;
+    private readonly viewers;
+    constructor(booter: ViewerBooter);
+    private queueBrowserOpen;
+    /**
+     * Return the viewer for `kitDir`, booting it on first request. Subsequent
+     * calls for the same dir return the cached (in-flight or resolved) promise.
+     *
+     * Booting and browser opening are tracked separately. Direct callers can use
+     * `open:true` for the base URL, while {@link runPreview}'s local path boots or
+     * reuses headlessly and calls {@link ViewerRegistry.open} after constructing
+     * its filtered target. Repeated requests for the same target share one
+     * promise; a changed filter target is opened again so the requested component
+     * is not hidden behind an older tab.
+     */
+    ensure(kitDir: string, port?: number, open?: boolean): Promise<BootedViewer>;
+    open(kitDir: string, target: string): Promise<void>;
+    /** Tear down every booted viewer (best-effort). For clean shutdown/tests. */
+    closeAll(): Promise<void>;
+}
+/**
+ * The default `ViewerBooter`. Lazily loads `@ambitresearch/genie-viewer` and boots its Vite
+ * dev server against the kit dir and honors {@link BootRequest.open} for direct
+ * callers. On its local path, {@link runPreview} deliberately passes `false`,
+ * constructs the filter-bearing viewer URL, and invokes
+ * {@link ViewerRegistry.open} separately so browser fallback never opens the
+ * unfiltered base URL. Absent → `false` (never opens), preserving the safe
+ * headless default.
+ * ALL of the viewer's own stdout is routed to STDERR — on the stdio transport
+ * the tool's stdout is the JSON-RPC stream, so the viewer's `Preview:` banner
+ * would corrupt framing if left on stdout.
+ */
+export declare const defaultViewerBooter: ViewerBooter;
+/** Injected collaborators for {@link runPreview} (kits location + viewer cache). */
+export interface PreviewDeps {
+    kitsRoot: string;
+    registry: ViewerRegistry;
+    /**
+     * Process env consulted for the `GENIE_PREVIEW_NO_OPEN` opt-out (piece B).
+     * Injectable so tests can drive the auto-open branch without mutating the real
+     * `process.env`. Defaults to `process.env` at registration time.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Manifest compiler seam; production uses the shared compile-and-persist helper. */
+    ensureManifest?: (kitDir: string) => Promise<Manifest>;
+    /** Preview reader used to build the self-contained app result. */
+    readPreviewBytes?: PreviewReader;
+    /** Optional separate-origin previews host for embedded manifest card URLs. */
+    previewsBaseUrl?: string;
+    /**
+     * Lazily resolves the process-scoped local card broker. It is consulted only
+     * for a local MCP Apps-capable host, so tools-only clients never start the
+     * listener merely because the preview tool was registered.
+     */
+    getCardAssetBroker?: () => Promise<CardAssetBroker>;
+}
+/** The three-field tool input (AC2). */
+export interface PreviewArgs {
+    kitId: string;
+    componentName?: string;
+    group?: string;
+}
+/** Per-request context sniffed off the wire (AC7). */
+export interface PreviewContext {
+    clientName?: string;
+    /**
+     * Tri-state MCP Apps negotiation from `initialize`: true/false are
+     * authoritative, while undefined means the client omitted the extension and
+     * should receive the metadata-linked app before any browser fallback.
+     */
+    uiCapable?: boolean;
+    /** Active server transport; HTTP suppresses server-machine browser opening. */
+    transportKind?: TransportKind;
+    /** Whether the viewer URL is reachable by the MCP client host. */
+    locality?: PreviewLocality;
+}
+export type PreviewLocality = "local" | "remote";
+/**
+ * The tool's return shape (AC3): text URLs + the ui:// resource pointer.
+ *
+ * `_meta` carries the resource pointer under TWO keys so both app ecosystems
+ * link the result to the same `ui://genie/grid` widget:
+ *   - `ui.resourceUri` — the portable MCP Apps standard, including current
+ *     ChatGPT Apps SDK guidance.
+ *   - `openai/outputTemplate` — the ChatGPT compatibility alias (M4-06 AC6,
+ *     research report §3.4 cross-vendor note). Both carry the same URI.
+ */
+export interface PreviewResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    /**
+     * Model-visible tool state. The host also forwards it to the rendered app via
+     * `ui/notifications/tool-result`, but route-bearing card data belongs in
+     * result `_meta`, which MCP Apps keeps out of model context.
+     */
+    structuredContent: {
+        kitId: string;
+        componentName?: string;
+        group?: string;
+        /** The live Vite viewer URL when it booted; absent on local file/inline fallbacks. */
+        viewerUrl?: string;
+        /** Local-only fallback; omitted from remote results to avoid leaking server paths. */
+        fileUrl?: string;
+        transportKind?: TransportKind;
+        locality: PreviewLocality;
+        embeddedError?: string;
+    };
+    _meta: {
+        ui: {
+            resourceUri: string;
+        };
+        "openai/outputTemplate": string;
+        "genie/embeddedManifest"?: EmbeddedManifest;
+    };
+}
+/**
+ * True when the operator has opted OUT of preview's server-side browser
+ * auto-open by setting `GENIE_PREVIEW_NO_OPEN` to a truthy value (design
+ * 2026-07-05, piece B — auto-open is opt-OUT, on by default for non-`ui://`
+ * hosts). Any non-empty value other than `0`/`false` (case-insensitive) counts
+ * as set, so `GENIE_PREVIEW_NO_OPEN=1`, `=true`, `=yes` all disable it.
+ */
+export declare function autoOpenDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Decide whether {@link runPreview} should ask the booter to open a browser.
+ * Only an explicit negotiated negative authorizes auto-open. An omitted
+ * capability is ambiguous (Codex Desktop and tools-only Codex currently look
+ * identical to a custom MCP server), so it receives a viewer URL but never a
+ * surprise system-browser launch.
+ */
+export declare function shouldAutoOpen(uiCapable: boolean | undefined, env?: NodeJS.ProcessEnv, transportKind?: TransportKind): boolean;
+/**
+ * Core `preview` logic (exported for direct unit testing without the MCP
+ * transport). Compiles + persists the kit's manifest (piece A) so all three
+ * vehicles render real cards, resolves the kit dir, tries to boot/reuse the
+ * viewer — opening a browser server-side for non-`ui://` hosts (piece B) — and
+ * builds the text summary: the live URL when the viewer is up (AC5), else a
+ * `file://` fallback (AC6). `_meta.ui.resourceUri` is emitted either way
+ * (AC3/AC4), and one `preview.request` line is logged recording the client and
+ * its `ui://` support (AC7). Remote results never expose server-local file
+ * paths; a failed local viewer can deliver a CSP-safe manifest to an MCP App
+ * when a previews origin is configured.
+ */
+export declare function runPreview(deps: PreviewDeps, args: PreviewArgs, ctx: PreviewContext): Promise<PreviewResult>;
+/** Options for {@link registerPreviewTool}. `booter` defaults to the lazy one. */
+export interface PreviewToolOptions {
+    kitsRoot: string;
+    /** Injectable for tests; production uses {@link defaultViewerBooter}. */
+    booter?: ViewerBooter;
+    /** Injectable env for the `GENIE_PREVIEW_NO_OPEN` opt-out; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable manifest seam for tests. */
+    ensureManifest?: (kitDir: string) => Promise<Manifest>;
+    /** Injectable preview-byte seam for self-contained app results. */
+    readPreviewBytes?: PreviewReader;
+    /** Optional separate-origin previews host used in embedded manifests. */
+    previewsBaseUrl?: string;
+    /** Lazy process-scoped card broker for local MCP Apps-capable hosts. */
+    getCardAssetBroker?: () => Promise<CardAssetBroker>;
+    /** Explicit transport override for embedded servers and tests. */
+    transportKind?: TransportKind;
+    /** Explicit deployment locality for embedded servers and tests. */
+    locality?: PreviewLocality;
+}
+/**
+ * Register `mcp__genie__preview`. One {@link ViewerRegistry} is created per
+ * registration and shared across every call so viewers are reused (AC5). The
+ * handler resolves the client's identity (per-request `_meta` escape hatch,
+ * else the initialize handshake) and its MCP Apps capability, then delegates
+ * to {@link runPreview}.
+ */
+export declare function registerPreviewTool(server: McpServer, options: PreviewToolOptions): ViewerRegistry;
+//# sourceMappingURL=preview.d.ts.map

package/dist/tools/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/tools/preview.ts"],"names":[],"mappings":"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"}