@octane-xplat/mcp 0.15.0 → 0.16.1

package/README.md

@@ -38,7 +38,9 @@ A one-off run without a devDependency also works:
 pnpm dlx @octane-xplat/mcp --workspace /path/to/app-workspace
 ```
 
-For development inside this repository:
+For development inside this repository — `start` runs the TypeScript source
+directly (Node ≥22.18 strips types); `test` and `prepack` run `vite build` so
+the checked and packed surface is the emitted `dist/`:
 
 ```sh
 pnpm --filter @octane-xplat/mcp start -- --workspace <path>
@@ -122,12 +124,14 @@ The service layer lives in `packages/cli/src/mcp/` — the `xplat` CLI projects
 the same contracts through its agent commands (`xplat catalog --json` is the
 entry point). `packages/mcp/src/` holds the stdio transport adapter: tool
 registration wraps the shared services, and the published `.d.ts` contract
-surface stays here.
+surface stays here under `types/contracts/`. Sources are TypeScript; `pnpm
+build` emits the runnable ESM to `dist/` (`pnpm test` builds first).
 
 ## Contract surface (`@octane-xplat/mcp/contracts/*`)
 
-Later work packages integrate against these modules; the `.d.ts` files are the
-documented surface and the `.mjs` files carry the runtime values and stores.
+Later work packages integrate against these modules; the `.d.ts` files under
+`types/contracts/` are the documented surface and the compiled `dist/` modules
+carry the runtime values and stores (re-exported from `@octane-xplat/cli`).
 
 - `errors` — `ContractErrorCode` vocabulary (`invalid_selection`,
   `ambiguous_selection`, `permission_denied`, `unsupported_capability`,
@@ -178,7 +182,7 @@ on all six platforms. Adapters (`runtime/adapters/*`) own platform
 mechanics and always spawn the app's own toolchain — `pnpm exec vite`,
 `pnpm exec ns run …`, the app's installed `@octane-xplat/cli` dev entry, or
 its `dev` script — so a session behaves like the app's installed framework
-version. `service.mjs` owns the shared contract behavior: explicit
+version. The shared `runtime/service` module owns the contract behavior: explicit
 app+target binding, `target_busy` contention, job dedupe/cooperative
 cancel, ownership-safe cleanup, bounded logs, and capability-matrix entries.
 

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,27 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+//#endregion
+export { __exportAll, __reExport };

package/dist/actions/bridge.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/actions/bridge";

package/dist/contracts/actions.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/actions";

package/dist/contracts/boundaries.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/boundaries";

package/dist/contracts/capabilities.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/capabilities";

package/dist/contracts/code.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/code";

package/dist/contracts/errors.js

@@ -0,0 +1,8 @@
+import { __exportAll, __reExport } from "../_virtual/_rolldown/runtime.js";
+export * from "@octane-xplat/cli/mcp/contracts/errors";
+//#region src/contracts/errors.ts
+var errors_exports = /* @__PURE__ */ __exportAll({});
+import * as import__octane_xplat_cli_mcp_contracts_errors from "@octane-xplat/cli/mcp/contracts/errors";
+__reExport(errors_exports, import__octane_xplat_cli_mcp_contracts_errors);
+//#endregion
+export { errors_exports };

package/dist/contracts/evidence.js

@@ -0,0 +1,8 @@
+import { __exportAll, __reExport } from "../_virtual/_rolldown/runtime.js";
+export * from "@octane-xplat/cli/mcp/contracts/evidence";
+//#region src/contracts/evidence.ts
+var evidence_exports = /* @__PURE__ */ __exportAll({});
+import * as import__octane_xplat_cli_mcp_contracts_evidence from "@octane-xplat/cli/mcp/contracts/evidence";
+__reExport(evidence_exports, import__octane_xplat_cli_mcp_contracts_evidence);
+//#endregion
+export { evidence_exports };

package/dist/contracts/identity.js

@@ -0,0 +1,8 @@
+import { __exportAll, __reExport } from "../_virtual/_rolldown/runtime.js";
+export * from "@octane-xplat/cli/mcp/contracts/identity";
+//#region src/contracts/identity.ts
+var identity_exports = /* @__PURE__ */ __exportAll({});
+import * as import__octane_xplat_cli_mcp_contracts_identity from "@octane-xplat/cli/mcp/contracts/identity";
+__reExport(identity_exports, import__octane_xplat_cli_mcp_contracts_identity);
+//#endregion
+export { identity_exports };

package/dist/contracts/index.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/index";

package/dist/contracts/inspection.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/inspection";

package/dist/contracts/policy.js

@@ -0,0 +1,8 @@
+import { __exportAll, __reExport } from "../_virtual/_rolldown/runtime.js";
+export * from "@octane-xplat/cli/mcp/contracts/policy";
+//#region src/contracts/policy.ts
+var policy_exports = /* @__PURE__ */ __exportAll({});
+import * as import__octane_xplat_cli_mcp_contracts_policy from "@octane-xplat/cli/mcp/contracts/policy";
+__reExport(policy_exports, import__octane_xplat_cli_mcp_contracts_policy);
+//#endregion
+export { policy_exports };

package/dist/contracts/sessions.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/sessions";

package/dist/contracts/status.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/contracts/status";

package/dist/discovery.js

@@ -0,0 +1,8 @@
+import { __exportAll, __reExport } from "./_virtual/_rolldown/runtime.js";
+export * from "@octane-xplat/cli/mcp/discovery";
+//#region src/discovery.ts
+var discovery_exports = /* @__PURE__ */ __exportAll({});
+import * as import__octane_xplat_cli_mcp_discovery from "@octane-xplat/cli/mcp/discovery";
+__reExport(discovery_exports, import__octane_xplat_cli_mcp_discovery);
+//#endregion
+export { discovery_exports };

package/dist/docs.js

@@ -0,0 +1,63 @@
+import { errors_exports } from "./contracts/errors.js";
+import { identity_exports } from "./contracts/identity.js";
+import { status_exports } from "./status.js";
+import { z } from "zod";
+//#region src/docs.ts
+function registerDocsTools(server, context, respond) {
+	const run = (method) => async (args) => {
+		const permission = context.policy.require("workspace");
+		if (!permission.granted) return respond({
+			ok: false,
+			error: permission.error
+		});
+		const selection = (0, status_exports.resolveSelection)(context);
+		if (selection.state !== "bound") return respond({
+			ok: false,
+			error: (0, errors_exports.contractError)(selection.state === "ambiguous" ? "ambiguous_selection" : "invalid_selection", "Bind an app with xplat_select_app before retrieving docs.")
+		});
+		try {
+			return respond({
+				ok: true,
+				data: await context.docs.serviceFor(selection.app)[method](args)
+			});
+		} catch (error) {
+			return respond({
+				ok: false,
+				error: (0, errors_exports.toContractError)(error)
+			});
+		}
+	};
+	server.registerTool("xplat_docs_search", {
+		description: "Search the selected app’s installed-version docs. Results include version/snapshot provenance, unavailable packages, conflicts, and separately labeled project guidance.",
+		inputSchema: {
+			query: z.string().trim().min(1).max(500),
+			package: z.string().optional(),
+			version: z.string().optional().describe("Explicit comparison version, visibly outside the installed binding."),
+			platform: z.enum(identity_exports.PLATFORMS).optional(),
+			corpus: z.enum([
+				"guide",
+				"recipe",
+				"design-note",
+				"implementation-note"
+			]).optional().default("guide"),
+			limit: z.number().int().min(1).max(50).optional()
+		}
+	}, run("search"));
+	server.registerTool("xplat_docs_read", {
+		description: "Read a bounded documentation page from a search ref, or package and path, preserving its version binding.",
+		inputSchema: {
+			ref: z.string().optional(),
+			package: z.string().optional(),
+			path: z.string().optional(),
+			version: z.string().optional(),
+			offset: z.number().int().min(0).optional(),
+			limit: z.number().int().min(1).max(2e4).optional()
+		}
+	}, run("read"));
+	server.registerTool("xplat_guidance", {
+		description: "Retrieve tailored guidance for the selected app’s actual installed package versions.",
+		inputSchema: {}
+	}, run("guidance"));
+}
+//#endregion
+export { registerDocsTools };

package/dist/inspection/service.js

@@ -0,0 +1,3 @@
+import { registerInspectionTools } from "./tools.js";
+import { createInspectionService } from "@octane-xplat/cli/mcp/inspection/service";
+export { createInspectionService, registerInspectionTools };

package/dist/inspection/tools.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+//#region src/inspection/tools.ts
+function registerInspectionTools(server, context, respond) {
+	const control = z.object({
+		kind: z.enum(["id", "testID"]),
+		name: z.string().min(1).max(200)
+	});
+	const run = (method) => async (args) => {
+		const data = await context.inspection[method](args);
+		return data.error ? respond({
+			ok: false,
+			error: data.error
+		}) : respond({
+			ok: true,
+			data
+		});
+	};
+	server.registerTool("xplat_inspect", {
+		description: "Bounded main-document named DOM hosts in the owned Chromium session. Explicit id/testID selector; duplicates fail. Password/private values are redacted. Includes document/session/build identity and coverage.",
+		inputSchema: {
+			sessionId: z.string(),
+			control: control.optional(),
+			offset: z.number().int().min(0).optional(),
+			limit: z.number().int().min(1).max(100).optional()
+		}
+	}, run("inspect"));
+	server.registerTool("xplat_interact", {
+		description: "Send scoped input to one stable control from an inspected document. dom-event sends a CDP mouse click; os-input sends Space/Enter via the macOS event system to owned headed Chromium. Reserve desktop input for OS actions. Input delivery is not an app assertion.",
+		inputSchema: {
+			sessionId: z.string(),
+			documentId: z.string(),
+			control,
+			mechanism: z.enum(["dom-event", "os-input"]),
+			key: z.enum(["Space", "Enter"]).optional().default("Space")
+		}
+	}, run("interact"));
+	server.registerTool("xplat_screenshot", {
+		description: "Capture the owned Chromium viewport only with a current visual-capture grant. Returns a session-scoped artifact and provenance; capability discovery never grants approval.",
+		inputSchema: { sessionId: z.string() }
+	}, run("screenshot"));
+}
+//#endregion
+export { registerInspectionTools };

package/dist/runtime/logs.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/runtime/logs";

package/dist/runtime/process.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/runtime/process";

package/dist/runtime/service.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/runtime/service";

package/dist/runtime/targets.js

@@ -0,0 +1 @@
+export * from "@octane-xplat/cli/mcp/runtime/targets";

package/dist/runtime/tools.js

@@ -0,0 +1,119 @@
+import { identity_exports } from "../contracts/identity.js";
+import { z } from "zod";
+//#region src/runtime/tools.ts
+function registerRuntimeTools(server, context, respond) {
+	const runtime = context.runtime;
+	server.registerTool("xplat_targets", {
+		description: "Discover launchable targets for the bound app: simulators, emulators, devices and host targets with availability, missing-toolchain reasons, and session busy/ownership state.",
+		inputSchema: { platform: z.enum(identity_exports.PLATFORMS).optional().describe("Limit to one platform") }
+	}, async ({ platform }) => {
+		const result = await runtime.listTargets({ platform });
+		return result.error ? respond({
+			ok: false,
+			error: result.error
+		}) : respond({
+			ok: true,
+			data: result
+		});
+	});
+	server.registerTool("xplat_build", {
+		description: "Build the bound app for one platform as a background job (the same commands `xplat build` runs). Returns a job id — poll xplat_job_status and read output with xplat_logs. Repeating with the same requestKey returns the live job instead of duplicating it.",
+		inputSchema: {
+			platform: z.enum(identity_exports.PLATFORMS),
+			requestKey: z.string().optional().describe("Idempotence key for retries")
+		}
+	}, async ({ platform, requestKey }) => {
+		const result = await runtime.build({
+			platform,
+			requestKey
+		});
+		return result.error ? respond({
+			ok: false,
+			error: result.error
+		}) : respond({
+			ok: true,
+			data: result
+		});
+	});
+	server.registerTool("xplat_launch", {
+		description: "Start an owned development session: bind one app to one target and run the platform dev command as a job. The job completes when readiness is confirmed — a failed launch after a successful build reports accurately, and the session keeps the app alive until xplat_session_end.",
+		inputSchema: {
+			platform: z.enum(identity_exports.PLATFORMS),
+			targetId: z.string().optional().describe("Target from xplat_targets; required when several are available"),
+			requestKey: z.string().optional().describe("Idempotence key for retries"),
+			browserMode: z.enum(["headless", "headed"]).optional().describe("Web only. Headed mode enables scoped OS keyboard input on qualified hosts; reserve desktop input before using it.")
+		}
+	}, async ({ platform, targetId, requestKey, browserMode }) => {
+		const result = await runtime.launch({
+			platform,
+			targetId,
+			requestKey,
+			browserMode
+		});
+		return result.error ? respond({
+			ok: false,
+			error: result.error
+		}) : respond({
+			ok: true,
+			data: result
+		});
+	});
+	server.registerTool("xplat_attach", {
+		description: "Attach to a compatible development session that is already running — never restarts or terminates it. Reports candidates per platform; attach binds a preserved user-owned session.",
+		inputSchema: {
+			platform: z.enum(identity_exports.PLATFORMS),
+			targetId: z.string().optional().describe("Candidate target; required when several are attachable")
+		}
+	}, async ({ platform, targetId }) => {
+		const result = await runtime.attach({
+			platform,
+			targetId
+		});
+		return result.error ? respond({
+			ok: false,
+			error: result.error
+		}) : respond({
+			ok: true,
+			data: result
+		});
+	});
+	server.registerTool("xplat_logs", {
+		description: "Bounded, ordered log read for a session or build job. Cursor-paginated: pass the previous nextCursor to continue; truncated/dropped flags reveal gaps and reset marks a restarted capture. A stopped or disconnected session reports its capture as historical.",
+		inputSchema: {
+			sessionId: z.string().optional(),
+			jobId: z.string().optional(),
+			cursor: z.number().optional().describe("Continue after this record seq"),
+			limit: z.number().int().positive().max(5e3).optional(),
+			stream: z.enum([
+				"stdout",
+				"stderr",
+				"lifecycle"
+			]).optional()
+		}
+	}, async ({ sessionId, jobId, cursor, limit, stream }) => {
+		if (!sessionId && !jobId) return respond({
+			ok: false,
+			error: {
+				code: "invalid_selection",
+				message: "Pass a sessionId or a jobId.",
+				recovery: { action: "Use xplat_sessions or a build/launch job id." }
+			}
+		});
+		const result = runtime.readLogs({
+			sessionId,
+			jobId,
+			cursor,
+			limit,
+			stream
+		});
+		return result.error ? respond({
+			ok: false,
+			error: result.error
+		}) : respond({
+			ok: true,
+			data: result
+		});
+	});
+}
+//#endregion
+export { registerRuntimeTools };