@caplets/core 0.18.9 → 0.20.0

package/dist/setup/hash.d.ts

@@ -0,0 +1,3 @@
+import type { CapletConfig } from "../config";
+export declare function capletSetupContentHash(caplet: CapletConfig): string;
+export declare function stableJson(value: unknown): string;

package/dist/setup/local-store.d.ts

@@ -0,0 +1,34 @@
+import { type SetupApproval, type SetupAttempt, type SetupTargetKind } from "./types";
+type SetupApprovalInput = Omit<SetupApproval, "projectFingerprint"> & {
+    projectFingerprint?: string | undefined;
+};
+export type LocalSetupStoreOptions = {
+    baseDir?: string;
+    now?: () => Date;
+    maxAttempts?: number;
+    retentionDays?: number;
+};
+export declare class LocalSetupStore {
+    private readonly root;
+    private readonly now;
+    private readonly maxAttempts;
+    private readonly retentionDays;
+    constructor(options?: LocalSetupStoreOptions);
+    getApproval(capletId: string, contentHash: string, targetKind: SetupTargetKind): Promise<SetupApproval | undefined>;
+    getApproval(projectFingerprint: string, capletId: string, contentHash: string, targetKind: SetupTargetKind): Promise<SetupApproval | undefined>;
+    approve(input: SetupApprovalInput): Promise<SetupApproval>;
+    recordAttempt(attempt: SetupAttempt): Promise<void>;
+    listAttempts(capletId: string): Promise<SetupAttempt[]>;
+    listAttempts(projectFingerprint: string, capletId: string): Promise<SetupAttempt[]>;
+    retention(): {
+        maxAttempts: number;
+        days: number;
+    };
+    private approvals;
+    private prunedAttempts;
+    private approvalsPath;
+    private attempts;
+    private attemptsDir;
+    private attemptsPath;
+}
+export {};

package/dist/setup/runner.d.ts

@@ -0,0 +1,40 @@
+import type { CapletSetupConfig } from "../config";
+import type { RuntimeFeature } from "../config-runtime";
+import type { LocalSetupStore } from "./local-store";
+import { type SetupActor, type SetupAttempt, type SetupTargetKind } from "./types";
+export type SpawnResult = {
+    exitCode?: number | undefined;
+    signal?: string | undefined;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+};
+export type SetupSpawn = (command: string, args: string[], options: {
+    cwd?: string | undefined;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    maxOutputBytes: number;
+}) => Promise<SpawnResult>;
+export type RunCapletSetupOptions = {
+    projectFingerprint?: string;
+    capletId: string;
+    contentHash: string;
+    setupHash?: string | undefined;
+    targetKind: SetupTargetKind;
+    runtimeFeatures?: RuntimeFeature[] | undefined;
+    projectBindingRequired?: boolean | undefined;
+    projectWorkspacePath?: string | undefined;
+    setup: CapletSetupConfig;
+    actor: SetupActor;
+    approved: boolean;
+    store: Pick<LocalSetupStore, "recordAttempt" | "retention">;
+    spawn?: SetupSpawn;
+    now?: () => Date;
+};
+export declare function runCapletSetup(options: RunCapletSetupOptions): Promise<SetupAttempt[]>;
+export declare function spawnCommand(command: string, args: string[], options: {
+    cwd?: string | undefined;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    maxOutputBytes: number;
+}): Promise<SpawnResult>;

package/dist/setup/types.d.ts

@@ -0,0 +1,52 @@
+import type { CapletSetupCommandConfig, CapletSetupConfig } from "../config";
+import type { RuntimeFeature } from "../config-runtime";
+export declare const setupTargetKinds: readonly ["local_host", "remote_host", "hosted_sandbox"];
+export type SetupTargetKind = (typeof setupTargetKinds)[number];
+export type SetupActor = "cli-interactive" | "cli-yes" | "ui" | "automation";
+export type SetupAttemptStatus = "running" | "succeeded" | "failed";
+export type SetupApproval = {
+    projectFingerprint: string;
+    capletId: string;
+    contentHash: string;
+    targetKind: SetupTargetKind;
+    approvedAt: string;
+    actor: SetupActor;
+};
+export type SetupAttempt = {
+    attemptId: string;
+    projectFingerprint: string;
+    capletId: string;
+    contentHash: string;
+    setupHash?: string | undefined;
+    targetKind: SetupTargetKind;
+    runtimeFeatures?: RuntimeFeature[] | undefined;
+    actor: SetupActor;
+    status: SetupAttemptStatus;
+    phase: "commands" | "verify";
+    commandLabel: string;
+    argv: string[];
+    exitCode?: number | undefined;
+    signal?: string | undefined;
+    durationMs: number;
+    startedAt: string;
+    finishedAt: string;
+    stdout: string;
+    stderr: string;
+    redacted: boolean;
+    retention: {
+        maxAttempts: number;
+        days: number;
+    };
+};
+export type SetupPlan = {
+    projectFingerprint: string;
+    capletId: string;
+    name: string;
+    contentHash: string;
+    targetKind: SetupTargetKind;
+    setup: CapletSetupConfig;
+    approved: boolean;
+    commands: CapletSetupCommandConfig[];
+    verify: CapletSetupCommandConfig[];
+};
+export declare function isSetupTargetKind(value: string): value is SetupTargetKind;

package/dist/stable-json.d.ts

@@ -0,0 +1,3 @@
+export declare function stableJsonValue(value: unknown): unknown;
+export declare function stableJsonStringify(value: unknown): string;
+export declare function stableJsonSha256Hex(value: unknown): Promise<string>;

package/dist/stable-json.js

@@ -0,0 +1,26 @@
+//#region src/stable-json.ts
+function stableJsonValue(value) {
+	if (Array.isArray(value)) return value.map((item) => stableJsonValue(item));
+	if (isPlainObject(value)) {
+		const sorted = {};
+		for (const key of Object.keys(value).sort()) {
+			const item = value[key];
+			if (item !== void 0) sorted[key] = stableJsonValue(item);
+		}
+		return sorted;
+	}
+	return value;
+}
+function stableJsonStringify(value) {
+	return JSON.stringify(stableJsonValue(value));
+}
+async function stableJsonSha256Hex(value) {
+	const bytes = new TextEncoder().encode(stableJsonStringify(value));
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function isPlainObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+export { stableJsonSha256Hex, stableJsonStringify, stableJsonValue };

package/dist/tools.d.ts

@@ -6,43 +6,54 @@ import type { DownstreamManager } from "./downstream";
 import type { GraphQLManager } from "./graphql";
 import type { HttpActionManager } from "./http-actions";
 import type { OpenApiManager } from "./openapi";
+import { type ObservedOutputShapeStore } from "./observed-output-shapes";
 import type { ServerRegistry } from "./registry";
 import { type ResultMarkdownContext } from "./result-content";
 export { generatedToolInputSchema } from "./generated-tool-input-schema";
 export type GeneratedServerToolRequest = RequiredOperationRequest;
-export declare function handleServerTool(server: CapletConfig, request: unknown, registry: ServerRegistry, downstream: DownstreamManager, openapi?: OpenApiManager, graphql?: GraphQLManager, http?: HttpActionManager, cli?: CliToolsManager, caplets?: CapletSetManager): Promise<any>;
-export declare function validateOperationRequest(request: unknown, maxSearchLimit: number, backend?: string): RequiredOperationRequest;
+export type HandleServerToolOptions = {
+    observedOutputShapeStore?: ObservedOutputShapeStore | undefined;
+    observedOutputShapeScope?: "local" | "self_hosted" | "cloud" | undefined;
+    workspaceId?: string | undefined;
+    projectFingerprint?: string | undefined;
+};
+export declare function handleServerTool(server: CapletConfig, request: unknown, registry: ServerRegistry, downstream: DownstreamManager, openapi?: OpenApiManager, graphql?: GraphQLManager, http?: HttpActionManager, cli?: CliToolsManager, caplets?: CapletSetManager, options?: HandleServerToolOptions): Promise<any>;
+export declare function validateOperationRequest(request: unknown, _maxSearchLimit: number, backend?: string): RequiredOperationRequest;
 type RequiredOperationRequest = {
-    operation: "inspect" | "check_backend";
+    operation: "inspect" | "check";
 } | {
-    operation: "list_tools";
+    operation: "tools";
     limit?: number;
+    cursor?: string;
 } | {
     operation: "search_tools";
     query: string;
     limit?: number;
+    cursor?: string;
 } | {
-    operation: "get_tool";
-    tool: string;
+    operation: "describe_tool";
+    name: string;
 } | {
     operation: "call_tool";
-    tool: string;
-    arguments: Record<string, unknown>;
+    name: string;
+    args: Record<string, unknown>;
     fields?: string[];
 } | {
-    operation: "list_resources" | "list_resource_templates" | "list_prompts";
+    operation: "resources" | "resource_templates" | "prompts";
     limit?: number;
+    cursor?: string;
 } | {
     operation: "search_resources" | "search_prompts";
     query: string;
     limit?: number;
+    cursor?: string;
 } | {
     operation: "read_resource";
     uri: string;
 } | {
     operation: "get_prompt";
-    prompt: string;
-    arguments: Record<string, unknown>;
+    name: string;
+    args: Record<string, unknown>;
 } | {
     operation: "complete";
     ref: {
@@ -62,6 +73,20 @@ export type CapletArtifact = {
     displayPath: string;
     pathResolution: "absolute" | "relative-to-mcp-server";
 };
+export type CapletExecutionMetadata = {
+    kind: "local" | "remote" | "cloud" | "local-fallback";
+    runtimeId?: string | undefined;
+    sandboxId?: string | undefined;
+    presenceId?: string | undefined;
+    fallback?: boolean | undefined;
+    fallbackReason?: "hosted_runtime_limit_reached" | "hosted_runtime_degraded" | undefined;
+    project?: {
+        bound: boolean;
+        fingerprint?: string | undefined;
+        syncReceiptId?: string | undefined;
+        applyReceiptId?: string | undefined;
+    } | undefined;
+};
 export type CapletResultMetadata = {
     id: string;
     name: string;
@@ -73,12 +98,13 @@ export type CapletResultMetadata = {
     status: "ok" | "error";
     elapsedMs?: number;
     artifacts?: CapletArtifact[];
+    execution?: CapletExecutionMetadata | undefined;
 };
 export declare function metadataFor(server: CapletConfig, operation: RequiredOperationRequest["operation"], target?: string | {
     tool?: string;
     uri?: string;
     prompt?: string;
-}, startedAt?: number): CapletResultMetadata;
+}, startedAt?: number, execution?: CapletExecutionMetadata): CapletResultMetadata;
 export declare function annotateMcpResult<T extends object>(result: T, metadata: CapletResultMetadata): T;
 export declare function jsonResult(value: unknown, metadata?: CapletResultMetadata): CallToolResult;
 export declare function annotateCallToolResult<T extends object>(result: T, metadata: CapletResultMetadata): T & CallToolResult;

package/dist/validation-CdqbI2zN.js

@@ -0,0 +1,174 @@
+//#region src/redaction.ts
+const SECRET_KEY_PATTERN = /(token|secret|authorization|auth|api[-_]?key|password|credential|clientsecret|client_secret|code|refresh)/iu;
+const SECRET_TEXT_PATTERNS = [
+	/(Authorization:\s*Bearer\s+)[0-9A-Za-z._~+/=-]+/giu,
+	/(bearer\s+)[a-z0-9._~+/=-]+/giu,
+	/([?&](?:access_token|refresh_token|token|code)=)[^&\s]+/giu
+];
+function isSecretKey(key) {
+	return SECRET_KEY_PATTERN.test(key);
+}
+function redactSecretText(value, options = {}) {
+	const replacement = options.replacement ?? "[REDACTED]";
+	let text = value;
+	for (const pattern of [...options.patterns ?? [], ...SECRET_TEXT_PATTERNS]) text = text.replace(pattern, (...args) => {
+		return `${typeof args[1] === "string" ? args[1] : ""}${replacement}`;
+	});
+	for (const secret of options.additionalSecrets?.filter(Boolean) ?? []) text = text.split(secret).join(replacement);
+	return {
+		text,
+		redacted: text !== value
+	};
+}
+//#endregion
+//#region src/errors.ts
+const CAPLETS_ERROR_CODES = [
+	"CONFIG_NOT_FOUND",
+	"CONFIG_EXISTS",
+	"CONFIG_INVALID",
+	"REQUEST_INVALID",
+	"SERVER_NOT_FOUND",
+	"SERVER_UNAVAILABLE",
+	"SERVER_START_TIMEOUT",
+	"UNKNOWN_OPERATION",
+	"TOOL_NOT_FOUND",
+	"TOOL_CALL_TIMEOUT",
+	"AUTH_REQUIRED",
+	"AUTH_FAILED",
+	"AUTH_REFRESH_FAILED",
+	"DOWNSTREAM_PROTOCOL_ERROR",
+	"DOWNSTREAM_TOOL_ERROR",
+	"UNSUPPORTED_OPERATION",
+	"UNSUPPORTED_CAPABILITY",
+	"PROMPT_NOT_FOUND",
+	"DOWNSTREAM_RESOURCE_ERROR",
+	"DOWNSTREAM_PROMPT_ERROR",
+	"DOWNSTREAM_COMPLETION_ERROR",
+	"UNSUPPORTED_TRANSPORT",
+	"INTERNAL_ERROR"
+];
+var CapletsError = class extends Error {
+	code;
+	details;
+	constructor(code, message, details) {
+		super(message);
+		this.name = "CapletsError";
+		this.code = code;
+		this.details = details;
+	}
+};
+function redactSecrets(value) {
+	if (typeof value === "string") return redactSecretText(value).text;
+	if (Array.isArray(value)) return value.map((item) => redactSecrets(item));
+	if (value && typeof value === "object") {
+		const redacted = {};
+		for (const [key, nested] of Object.entries(value)) redacted[key] = isSecretKey(key) ? "[REDACTED]" : redactSecrets(nested);
+		return redacted;
+	}
+	return value;
+}
+function toSafeError(error, fallback = "INTERNAL_ERROR") {
+	if (error instanceof CapletsError) return {
+		code: error.code,
+		message: String(redactSecrets(error.message)),
+		...error.details === void 0 ? {} : { details: redactSecrets(error.details) }
+	};
+	if (error instanceof Error) return {
+		code: fallback,
+		message: String(redactSecrets(error.message))
+	};
+	return {
+		code: fallback,
+		message: String(redactSecrets(error))
+	};
+}
+function errorResult(error, fallback) {
+	const safe = toSafeError(error, fallback);
+	const structuredContent = { error: safe };
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: [
+				"# Error",
+				"",
+				`## ${safe.code}`,
+				"",
+				safe.message,
+				"",
+				"## Details",
+				"",
+				"```json",
+				JSON.stringify(safe, null, 2),
+				"```"
+			].join("\n")
+		}],
+		structuredContent
+	};
+}
+//#endregion
+//#region src/config/validation.ts
+const SERVER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const HTTP_BASE_URL_PATTERN = /^(?![a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*@)[^?#]*$/;
+const FORBIDDEN_HEADERS = new Set([
+	"accept",
+	"authorization",
+	"connection",
+	"content-length",
+	"content-type",
+	"host",
+	"keep-alive",
+	"mcp-protocol-version",
+	"mcp-session-id",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+]);
+function validateHttpActionHeaders(headers, ctx, path) {
+	for (const headerName of Object.keys(headers)) {
+		const normalized = headerName.toLowerCase();
+		if (!HEADER_NAME_PATTERN.test(headerName) || FORBIDDEN_HEADERS.has(normalized)) ctx.addIssue({
+			code: "custom",
+			path: [...path, headerName],
+			message: `header ${headerName} is not allowed`
+		});
+	}
+}
+function isAllowedRemoteUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	if (url.protocol === "https:") return true;
+	return url.protocol === "http:" && [
+		"localhost",
+		"127.0.0.1",
+		"[::1]",
+		"::1"
+	].includes(url.hostname);
+}
+function isAllowedHttpBaseUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	return isAllowedRemoteUrl(value) && !url.username && !url.password && !url.search && !url.hash;
+}
+function isUrl(value) {
+	try {
+		new URL(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { isAllowedHttpBaseUrl as a, validateHttpActionHeaders as c, errorResult as d, redactSecrets as f, SERVER_ID_PATTERN as i, CAPLETS_ERROR_CODES as l, HEADER_NAME_PATTERN as n, isAllowedRemoteUrl as o, toSafeError as p, HTTP_BASE_URL_PATTERN as r, isUrl as s, FORBIDDEN_HEADERS as t, CapletsError as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@caplets/core",
-  "version": "0.18.9",
-  "description": "Core runtime library for Caplets progressive disclosure gateways.",
+  "version": "0.20.0",
+  "description": "Core runtime library for Caplets Code Mode and progressive disclosure gateways.",
   "keywords": [
     "caplets",
     "gateway",
@@ -38,6 +38,46 @@
     "./native": {
       "types": "./dist/native.d.ts",
       "default": "./dist/native.js"
+    },
+    "./caplet-source": {
+      "types": "./dist/caplet-source/index.d.ts",
+      "default": "./dist/caplet-source.js"
+    },
+    "./caplet-source/filesystem": {
+      "types": "./dist/caplet-source/filesystem.d.ts",
+      "default": "./dist/caplet-source/filesystem.js"
+    },
+    "./code-mode": {
+      "types": "./dist/code-mode/index.d.ts",
+      "default": "./dist/code-mode.js"
+    },
+    "./observed-output-shapes": {
+      "types": "./dist/observed-output-shapes/index.d.ts",
+      "default": "./dist/observed-output-shapes.js"
+    },
+    "./observed-output-shapes/pure": {
+      "types": "./dist/observed-output-shapes/pure.d.ts",
+      "default": "./dist/observed-output-shapes/pure.js"
+    },
+    "./project-binding": {
+      "types": "./dist/project-binding/index.d.ts",
+      "default": "./dist/project-binding.js"
+    },
+    "./redaction": {
+      "types": "./dist/redaction.d.ts",
+      "default": "./dist/redaction.js"
+    },
+    "./runtime-plan": {
+      "types": "./dist/runtime-plan/index.d.ts",
+      "default": "./dist/runtime-plan.js"
+    },
+    "./stable-json": {
+      "types": "./dist/stable-json.d.ts",
+      "default": "./dist/stable-json.js"
+    },
+    "./config-runtime": {
+      "types": "./dist/config-runtime.d.ts",
+      "default": "./dist/config-runtime.js"
     }
   },
   "publishConfig": {
@@ -48,9 +88,12 @@
     "@hono/mcp": "^0.3.0",
     "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.20.0",
     "commander": "^15.0.0",
-    "graphql": "^16.14.0",
+    "graphql": "^16.14.1",
     "hono": "^4.12.23",
+    "quickjs-emscripten": "^0.32.0",
+    "typescript": "^6.0.3",
     "vfile": "^6.0.3",
     "vfile-matter": "^5.0.1",
     "yaml": "^2.9.0",
@@ -58,10 +101,9 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "@typescript/native-preview": "7.0.0-dev.20260603.1",
     "rolldown": "^1.0.3",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=22"