@xopcai/xopc 0.0.313 → 0.0.315

package/dist/src/local-apps/capabilities/contracts.js

@@ -0,0 +1,32 @@
+import { ExtensionCapabilityBindingsSchema } from "../../../packages/gateway-contract/src/extension-capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityDispatcher } from "../../capabilities/runtime/dispatcher.js";
+import { registerNoteReadCapabilities } from "../../notes/capabilities/read.js";
+import { registerNoteWriteCapabilities } from "../../notes/capabilities/write.js";
+import { registerTaskReadCapabilities } from "../../tasks/capabilities/read.js";
+//#region src/local-apps/capabilities/contracts.ts
+init_src();
+/** Validate release bindings against the same production definitions without executing a domain service. */
+function validateLocalAppCapabilityContracts(value) {
+	const bindings = ExtensionCapabilityBindingsSchema.parse(value ?? []);
+	if (!bindings.length) return;
+	const dispatcher = new CapabilityDispatcher();
+	const unavailable = () => {
+		throw new Error("Contract validation must not execute a domain service");
+	};
+	registerNoteReadCapabilities(dispatcher, unavailable);
+	registerNoteWriteCapabilities(dispatcher, { getNotes: unavailable });
+	registerTaskReadCapabilities(dispatcher);
+	const context = {
+		principalId: "release-validator",
+		surface: "extension",
+		scopes: ["gateway.admin"],
+		authorize: () => false
+	};
+	for (const binding of bindings) {
+		const descriptor = dispatcher.describe(binding.id, context);
+		if (descriptor.majorVersion !== binding.majorVersion || descriptor.descriptorDigest !== binding.descriptorDigest) throw new Error(`Capability contract changed: ${binding.id}; update the binding and rerun acceptance`);
+	}
+}
+//#endregion
+export { validateLocalAppCapabilityContracts };

package/dist/src/local-apps/capabilities/read.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import type { LocalAppService } from '../service.js';
+export declare function registerLocalAppReadCapabilities(dispatcher: CapabilityDispatcher, service: LocalAppService): void;

package/dist/src/local-apps/capabilities/read.js

@@ -0,0 +1,48 @@
+import { ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineReadCapability } from "../../capabilities/runtime/dispatcher.js";
+//#region src/local-apps/capabilities/read.ts
+init_src();
+function registerLocalAppReadCapabilities(dispatcher, service) {
+	const policy = {
+		majorVersion: 1,
+		effect: "read",
+		surfaces: ["http", "agent"],
+		scopes: ["gateway.admin"]
+	};
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.local_apps.validate",
+		description: "Inspect local application files and validation issues without modifying the package or acceptance records.",
+		...ProductReadContracts["xopc.local_apps.validate"],
+		execute({ id }) {
+			if (!service.get(id)) throw new CapabilityError("NOT_FOUND", "Local app not found");
+			return { validation: service.validate(id) };
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.local_apps.list",
+		description: "List managed local applications.",
+		...ProductReadContracts["xopc.local_apps.list"],
+		execute: () => ({ apps: service.list().map((app) => ({ ...app })) })
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.local_apps.get",
+		description: "Read a local application, its preview and release history.",
+		...ProductReadContracts["xopc.local_apps.get"],
+		execute({ id }) {
+			const app = service.get(id);
+			if (!app) throw new CapabilityError("NOT_FOUND", "Local app not found");
+			return { app: {
+				...app,
+				releases: app.releases.map((release) => ({ ...release })),
+				acceptanceRuns: app.acceptanceRuns.map((run) => ({ ...run }))
+			} };
+		}
+	}));
+}
+//#endregion
+export { registerLocalAppReadCapabilities };

package/dist/src/local-apps/capabilities/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilityCall } from '@xopcai/gateway-contract';
+import { type CapabilityContext, type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import type { LocalAppService } from '../service.js';
+/** Shared UI/Agent execution boundary; callers cannot manufacture grants or release identity. */
+export declare function localAppCapabilities(apps: Pick<LocalAppService, 'getCapabilityAccess'>, dispatcher: CapabilityDispatcher, extensionId: string, manifestDigest: string, caller: CapabilityContext): {
+    list(): {
+        releaseId: string;
+        manifestDigest: string;
+        capabilities: import("@xopcai/gateway-contract").CapabilityDescriptor[];
+    };
+    call(id: string, call: CapabilityCall): Promise<{
+        status: "succeeded";
+        releaseId: string;
+        data: unknown;
+    }>;
+};

package/dist/src/local-apps/capabilities/runtime.js

@@ -0,0 +1,66 @@
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import "../../capabilities/runtime/dispatcher.js";
+import { createHash } from "node:crypto";
+//#region src/local-apps/capabilities/runtime.ts
+/** Shared UI/Agent execution boundary; callers cannot manufacture grants or release identity. */
+function localAppCapabilities(apps, dispatcher, extensionId, manifestDigest, caller) {
+	const access = apps.getCapabilityAccess(extensionId, manifestDigest);
+	const current = () => {
+		if (apps.getCapabilityAccess(extensionId, manifestDigest).releaseId !== access.releaseId) throw new CapabilityError("CONTRACT_CHANGED", "Local app release changed");
+	};
+	const context = {
+		...caller,
+		surface: "extension",
+		allowedCapabilities: access.bindings.map((binding) => binding.id).filter((id) => !caller.allowedCapabilities || caller.allowedCapabilities.includes(id)),
+		assertCurrent: () => {
+			caller.assertCurrent?.();
+			current();
+		},
+		authorize: async (id, input) => {
+			const allowed = await caller.authorize(id, input);
+			current();
+			return allowed;
+		}
+	};
+	return {
+		list() {
+			current();
+			return {
+				releaseId: access.releaseId,
+				manifestDigest,
+				capabilities: dispatcher.list(context).filter((item) => access.bindings.some((binding) => binding.id === item.id && binding.majorVersion === item.majorVersion && binding.descriptorDigest === item.descriptorDigest))
+			};
+		},
+		async call(id, call) {
+			current();
+			const binding = access.bindings.find((item) => item.id === id);
+			if (!binding) throw new CapabilityError("FORBIDDEN", "Capability is not declared by this release");
+			if (binding.majorVersion !== call.majorVersion || binding.descriptorDigest !== call.descriptorDigest) throw new CapabilityError("CONTRACT_CHANGED", "Capability differs from the installed binding");
+			const write = dispatcher.describe(id, context).effect !== "read";
+			if (write && !call.idempotencyKey?.trim()) throw new CapabilityError("INVALID_INPUT", "A stable idempotencyKey is required");
+			const key = call.idempotencyKey ? createHash("sha256").update(JSON.stringify([
+				caller.principalId,
+				extensionId,
+				access.releaseId,
+				call.idempotencyKey
+			])).digest("hex") : void 0;
+			const result = await dispatcher.call(id, call.input, context, {
+				...call,
+				idempotencyKey: key
+			});
+			try {
+				current();
+			} catch (error) {
+				if (write) throw new CapabilityError("OUTCOME_UNKNOWN", "Write may have committed; retain the original idempotencyKey and reconcile after restoring access");
+				throw error;
+			}
+			return {
+				status: "succeeded",
+				releaseId: access.releaseId,
+				data: result
+			};
+		}
+	};
+}
+//#endregion
+export { localAppCapabilities };

package/dist/src/local-apps/capabilities/write.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import { type LocalAppService } from '../service.js';
+export declare function registerLocalAppWriteCapabilities(dispatcher: CapabilityDispatcher, service: LocalAppService): void;

package/dist/src/local-apps/capabilities/write.js

@@ -0,0 +1,35 @@
+import { LocalAppAcceptanceInputSchema, LocalAppAcceptanceOutputSchema } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
+import { LocalAppAcceptanceValidationError, LocalAppRevisionConflictError } from "../service.js";
+import { z } from "zod";
+//#region src/local-apps/capabilities/write.ts
+init_src();
+function registerLocalAppWriteCapabilities(dispatcher, service) {
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.local_apps.record_acceptance",
+		majorVersion: 1,
+		effect: "local-write",
+		description: "Record supplied acceptance checks against the exact local source digest; this does not execute the checks.",
+		surfaces: ["http", "agent"],
+		scopes: ["gateway.admin"],
+		input: LocalAppAcceptanceInputSchema.extend({ id: z.string().min(1).max(512) }),
+		output: z.object({ acceptance: LocalAppAcceptanceOutputSchema }),
+		execute({ id, ...input }) {
+			if (!service.get(id)) throw new CapabilityError("NOT_FOUND", "Local app not found");
+			try {
+				return { acceptance: service.recordAcceptance(id, input) };
+			} catch (error) {
+				if (error instanceof LocalAppRevisionConflictError) throw new CapabilityError("REVISION_CONFLICT", error.message);
+				if (error instanceof LocalAppAcceptanceValidationError) throw new CapabilityError("INVALID_INPUT", error.message);
+				throw error;
+			}
+		},
+		afterCommit() {
+			service.flushAcceptanceEvents();
+		}
+	}));
+}
+//#endregion
+export { registerLocalAppWriteCapabilities };

package/dist/src/local-apps/release-lock.d.ts

@@ -0,0 +1,2 @@
+/** Serialize release mutations sharing an extension directory, including across service instances. */
+export declare function withLocalAppReleaseLock<T>(root: string, action: () => Promise<T>): Promise<T>;

package/dist/src/local-apps/release-lock.js

@@ -0,0 +1,20 @@
+//#region src/local-apps/release-lock.ts
+const pending = /* @__PURE__ */ new Map();
+/** Serialize release mutations sharing an extension directory, including across service instances. */
+async function withLocalAppReleaseLock(root, action) {
+	const previous = pending.get(root) ?? Promise.resolve();
+	let release;
+	const next = new Promise((resolve) => {
+		release = resolve;
+	});
+	pending.set(root, next);
+	await previous;
+	try {
+		return await action();
+	} finally {
+		release();
+		if (pending.get(root) === next) pending.delete(root);
+	}
+}
+//#endregion
+export { withLocalAppReleaseLock };

package/dist/src/local-apps/runtime-entry.d.ts

@@ -4,5 +4,3 @@ export declare const LOCAL_APP_RUNTIME_ENTRY = ".xopc/runtime/local-ui.js";
  * arbitrary Node.js in the gateway process through the extension `main` entry.
  */
 export declare const LOCAL_APP_RUNTIME_SOURCE = "export default Object.freeze({});\n";
-/** Exact legacy scaffold bytes accepted only to keep existing Phase 1 drafts upgradeable. */
-export declare function legacyLocalAppRuntimeSource(extensionId: string, name: string): string;

package/dist/src/local-apps/runtime-entry.js

@@ -6,18 +6,5 @@ const LOCAL_APP_RUNTIME_ENTRY = ".xopc/runtime/local-ui.js";
 */
 const LOCAL_APP_RUNTIME_SOURCE = `export default Object.freeze({});
 `;
-/** Exact legacy scaffold bytes accepted only to keep existing Phase 1 drafts upgradeable. */
-function legacyLocalAppRuntimeSource(extensionId, name) {
-	return `export default {
-  id: ${JSON.stringify(extensionId)},
-  name: ${JSON.stringify(name)},
-  version: '0.1.0',
-  kind: 'utility',
-  register(api) {
-    api.logger.info('Local app registered');
-  },
-};
-`;
-}
 //#endregion
-export { LOCAL_APP_RUNTIME_ENTRY, LOCAL_APP_RUNTIME_SOURCE, legacyLocalAppRuntimeSource };
+export { LOCAL_APP_RUNTIME_ENTRY, LOCAL_APP_RUNTIME_SOURCE };

package/dist/src/local-apps/scaffold.js

@@ -1,7 +1,10 @@
+import { ExtensionCapabilityBindingsSchema, extensionCapabilityPermissions } from "../../packages/gateway-contract/src/extension-capabilities.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
 import { LOCAL_APP_RUNTIME_ENTRY, LOCAL_APP_RUNTIME_SOURCE } from "./runtime-entry.js";
 import { dirname, join } from "node:path";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/local-apps/scaffold.ts
+init_src();
 const LOCAL_APP_PERMISSIONS = ["theme", "storage"];
 function writeText(root, relativePath, content) {
 	const target = join(root, relativePath);
@@ -111,7 +114,7 @@ button?.addEventListener('click', () => {
 function readLocalAppPermissions(workspaceRoot) {
 	try {
 		const raw = JSON.parse(readFileSync(join(workspaceRoot, "xopc.extension.json"), "utf8"));
-		return Array.isArray(raw.ui?.permissions) ? raw.ui.permissions.filter((permission) => typeof permission === "string") : [];
+		return [...Array.isArray(raw.ui?.permissions) ? raw.ui.permissions.filter((permission) => typeof permission === "string") : [], ...extensionCapabilityPermissions(ExtensionCapabilityBindingsSchema.parse(raw.ui?.capabilities ?? []))];
 	} catch {
 		return [];
 	}

package/dist/src/local-apps/service.d.ts

@@ -3,6 +3,10 @@ import type { ExtensionLoader } from '../extensions/index.js';
 import type { ProjectService } from '../projects/index.js';
 import { LocalAppStore } from './store.js';
 import type { CreateLocalAppInput, LocalApp, LocalAppAcceptanceRun, LocalAppDetail, LocalAppPreviewTarget, LocalAppValidationResult, LocalAppUiGrant, RecordLocalAppAcceptanceInput } from './types.js';
+export declare class LocalAppRevisionConflictError extends Error {
+}
+export declare class LocalAppAcceptanceValidationError extends Error {
+}
 export interface LocalAppServiceOptions {
     projects: ProjectService;
     workspaceRoot: string;
@@ -18,20 +22,39 @@ export declare class LocalAppService {
     private readonly options;
     private readonly store;
     constructor(options: LocalAppServiceOptions, store?: LocalAppStore);
+    private recoveryRoot;
+    private recoveryMarker;
+    /** Reconcile interrupted mutations before any extension code or request can run. */
+    recoverPendingReleases(): Promise<void>;
+    private recoverReleases;
+    private mutateRelease;
     list(): LocalApp[];
     get(id: string): LocalAppDetail | null;
     getUiGrant(extensionId: string): LocalAppUiGrant;
-    grantUiPermissions(extensionId: string): LocalAppUiGrant;
+    getCapabilityAccess(extensionId: string, expectedManifestDigest: string): {
+        releaseId: string;
+        bindings: {
+            id: "xopc.notes.get" | "xopc.notes.list" | "xopc.tasks.get" | "xopc.tasks.list" | "xopc.notes.create" | "xopc.notes.update" | "xopc.notes.append";
+            majorVersion: number;
+            descriptorDigest: string;
+        }[];
+    };
+    grantUiPermissions(extensionId: string, expectedManifestDigest: string): LocalAppUiGrant;
     create(input: CreateLocalAppInput): LocalAppDetail;
     resolvePreview(previewToken: string): LocalAppPreviewTarget | null;
     validate(id: string): LocalAppValidationResult;
     recordAcceptance(id: string, input: RecordLocalAppAcceptanceInput): LocalAppAcceptanceRun;
+    flushAcceptanceEvents(): void;
     private releaseRoot;
     private refreshExtensions;
     private assertInstalledRuntime;
     private activateArtifact;
     install(id: string): Promise<LocalAppDetail>;
+    private installRelease;
     rollback(id: string, releaseId: string): Promise<LocalAppDetail>;
+    private rollbackRelease;
     setEnabled(id: string, enabled: boolean): Promise<LocalAppDetail>;
+    private setReleaseEnabled;
     uninstall(id: string): Promise<LocalAppDetail>;
+    private uninstallRelease;
 }