@openhands/extensions 0.22.1 → 0.24.0

package/skills/canvas-extension-api/references/testing-and-installation.md

@@ -0,0 +1,286 @@
+# Testing and installing OpenHands Apps
+
+Use layered verification: static package checks, unit tests against the real entrypoint, repository build checks, then a manual Canvas lifecycle test.
+
+## Static validation
+
+Run:
+
+```sh
+node /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app-package
+```
+
+The validator checks:
+
+- app package directory and `canvas-extension.json` existence;
+- valid JSON and supported `schema_version`;
+- required fields and basic semantic version shape;
+- kebab-case app manifest name, contribution IDs, and path segments;
+- unique page IDs and paths;
+- entrypoint containment and existence;
+- `activate` export presence;
+- likely bare imports, remote imports, Node built-ins, dynamic imports, and source-map chunk references;
+- `registerPage` IDs against declared manifest IDs.
+
+Treat static import scanning as heuristic. Minified or generated bundles may require manual inspection. Treat a passing result as necessary but not sufficient. When using `--dist`, the validator checks the manifest entrypoint path under `dist/`, so a manifest entrypoint such as `bundle.mjs` requires `dist/bundle.mjs`.
+
+## Sidecar test matrix
+
+Test the browser bundle independently from the Sidecar: load the single ESM entrypoint through Blob import and confirm no service secret or origin assumption is embedded. Test the narrow bridge or deployment adapter with real request shapes and error handling. Test real Sidecar health, version, capabilities, and domain operations, including timeouts and structured failures.
+
+Exercise `unknown`, `probing`, `missing`, `stopped`, `incompatible`, `ready`, and `unhealthy` onboarding states plus consent, install, start, repair, upgrade, and stop failures. Test repeated lifecycle actions, service restarts, version mismatches, backend switching, and Canvas remounts. Test App removal, service uninstall, and data deletion as distinct operations. Treat an unavailable Sidecar as a supported UI state, not a crash.
+
+## Unit test shape
+
+Exercise the actual app entrypoint in a DOM test environment. Keep the host double small and behavior-oriented.
+
+```js
+import { describe, expect, it, vi } from "vitest";
+import { activate } from "./extension.js";
+
+describe("example app", () => {
+  it("mounts, requests backend data, and cleans up", async () => {
+    let mountPage;
+    const unregister = vi.fn();
+    const navigate = vi.fn();
+    const request = vi.fn().mockResolvedValue({ status: "ok" });
+    const host = {
+      apiVersion: "1",
+      extension: {
+        name: "example-dashboard",
+        version: "0.1.0",
+        resolvedRef: "test-ref",
+      },
+      backend: { id: "local-test", kind: "local", orgId: null },
+      registerPage: vi.fn((id, mount) => {
+        expect(id).toBe("dashboard");
+        mountPage = mount;
+        return unregister;
+      }),
+      navigate,
+      agentServer: { request },
+    };
+
+    expect(activate(host)).toBe(unregister);
+
+    const container = document.createElement("div");
+    const cleanup = mountPage({ container, path: "", navigate });
+
+    await vi.waitFor(() => {
+      expect(container.textContent).toContain("ok");
+    });
+    expect(request).toHaveBeenCalledWith({ path: "/example" });
+
+    cleanup();
+    expect(container.childElementCount).toBe(0);
+  });
+});
+```
+
+Add focused cases for nested routes, error states, malformed responses, loading deduplication, timers, and unsupported host versions as applicable.
+
+Prefer real timers for lifecycle behavior unless waiting would make the suite impractical. When fake timers are necessary, state why in the test and restore them after each case.
+
+## Build verification
+
+For a source-based TypeScript, React, Vue, or other framework implementation, configure the bundler in library mode and emit one browser ESM file matching the manifest entrypoint.
+
+Required output properties:
+
+- ESM format;
+- one JavaScript file;
+- no unresolved bare imports;
+- no external chunks;
+- no Node runtime assumptions;
+- CSS injected or embedded when the runtime cannot fetch additional package assets;
+- small local assets embedded as data URLs or otherwise included in the single bundle.
+
+Inspect output using repository tooling and direct searches. Example checks:
+
+```sh
+node --check dist/extension.js
+rg '^\s*(import|export\s+.*\s+from)\s+.*["'"'][^./]' dist/extension.js
+rg 'import\s*\(' dist/extension.js
+rg 'node:|require\(|module\.exports|process\.env|__dirname|__filename' dist/extension.js
+```
+
+Do not run the browser bundle directly with Node as a functional test. Use a DOM test environment or Canvas.
+
+## Upstream mock frontend workflow
+
+The initial OpenHands frontend includes an MSW development mode that can install a checked-in fixture before Agent Server app endpoints are available.
+
+From an OpenHands checkout:
+
+```sh
+VITE_FRONTEND_PORT=3102 \
+VITE_BACKEND_BASE_URL=http://127.0.0.1:8000 \
+VITE_SESSION_API_KEY=canvas-extension-dev \
+npm run dev:mock
+```
+
+Open:
+
+```text
+http://localhost:3102/extensions
+```
+
+Install a fixture path that exists inside that OpenHands checkout, such as:
+
+```text
+src/fixtures/canvas-extensions/demo-page
+```
+
+The mock flow validates frontend inventory, enablement, bundle loading, page registration, nested routing, and cleanup. It does not validate Agent Server installation, filesystem boundaries, persistence, authentication, Git resolution, symlinks, or immutable revisions.
+
+To test a separately located app with this mock, copy it into a suitable fixture path only when authorized and avoid copying secrets-bearing files. Prefer adding a temporary ignored fixture or using the backend flow once available. Remove temporary copies after testing.
+
+## Real Agent Server installation
+
+Use Customize -> Apps when available, or the authenticated management API when explicitly requested.
+
+### Backend-local path
+
+Use a path visible from the Agent Server process. A path visible only on the frontend host is insufficient when the backend runs in a container, remote VM, or different filesystem namespace.
+
+Install request shape:
+
+```json
+{
+  "source": "/absolute/path/on/agent-server",
+  "ref": null,
+  "repo_path": null,
+  "force": false
+}
+```
+
+### Git repository
+
+Use distribution coordinates compatible with the backend:
+
+```json
+{
+  "source": "github:owner/repository",
+  "ref": "main",
+  "repo_path": "extensions/example-dashboard",
+  "force": false
+}
+```
+
+For a repository containing the app at its root, omit `repo_path`. Pin or report the resolved revision returned by the backend.
+
+### Multiple apps in one repository
+
+Place each app under an independent package root:
+
+```text
+repository/
+├── extensions/
+│   ├── canvas-pulse/
+│   │   ├── canvas-extension.json
+│   │   ├── extension.js
+│   │   └── extension.test.js
+│   └── project-dashboard/
+│       ├── canvas-extension.json
+│       ├── dist/
+│       │   └── extension.js
+│       └── src/
+├── packages/
+│   └── shared-source/
+└── package.json
+```
+
+Keep each manifest's `entrypoint` relative to that app's package root. Configure shared build tooling to emit one self-contained browser ESM bundle per app. Do not make one app entrypoint import another app's output at runtime; Blob URL loading prevents package-relative module resolution.
+
+Validate each package separately:
+
+```sh
+for extension in extensions/*; do
+  node /path/to/validate-extension.mjs "$extension"
+done
+```
+
+The Add app form installs one app per submission. It sends one `source`, optional `ref`, and optional `repo_path` in each install request. It does not scan a repository recursively, discover all `canvas-extension.json` files, or bulk-install nested apps.
+
+Install the example repository twice:
+
+| Extension | Source | Ref | Repository path |
+| --- | --- | --- | --- |
+| Canvas Pulse | `github:owner/repository` | `main` | `extensions/canvas-pulse` |
+| Project Dashboard | `github:owner/repository` | `main` | `extensions/project-dashboard` |
+
+Each installation receives its own resolved revision, enabled state, lifecycle, and inventory entry. Installation leaves each one disabled; enable each separately after review and authorization.
+
+When preparing instructions for several apps, generate an install matrix rather than saying to add the repository once. Keep the source/ref identical when appropriate and vary `repo_path` for each package root.
+
+Do not upload or publish a local app unless requested. Do not embed credentials in a source URL.
+
+## Manual lifecycle checklist
+
+Complete these checks against the target backend:
+
+### Installation
+
+- Confirm the app appears in Customize -> Apps.
+- Confirm installation leaves it disabled.
+- Confirm the displayed name, version, description, source, requested ref, resolved ref, and contributions.
+- Confirm no navigation item appears and no app code executes while disabled.
+
+### Enablement
+
+- Read the trusted-code disclosure.
+- Enable only with user authorization.
+- Confirm the page navigation item appears without restarting Canvas.
+- Open the page and verify loading, success, empty, and failure states.
+- Verify authenticated Agent Server requests target the active owning backend.
+
+### Routing
+
+- Open the declared root route.
+- Open at least one nested route directly.
+- Confirm the mount callback receives only the remainder below the declared page path.
+- Confirm app navigation respects the Canvas base path.
+- Confirm the longest declared page path wins when page paths overlap.
+
+### Cleanup
+
+- Navigate away and verify page-level timers, listeners, observers, and DOM are removed.
+- Disable the app and confirm all page registrations and navigation disappear.
+- Re-enable and confirm the app activates cleanly a second time.
+- Update or reinstall when applicable and confirm stale effects do not remain.
+- Switch backend or reconnect and confirm the previous backend's app does not leak into the new context.
+
+### Removal
+
+- Uninstall only when explicitly requested.
+- Confirm the inventory, navigation, and routes no longer expose the app.
+
+## Diagnosing common failures
+
+### App is listed but has no page
+
+Check that the installed API response includes the parsed manifest. The frontend treats `manifest` as optional for compatibility with Agent Server versions that omit it. Without `manifest.contributes.pages`, Canvas cannot admit page registrations or render navigation.
+
+Check that the app is enabled and that `registerPage` uses an ID declared in the manifest.
+
+### Entrypoint fails to import
+
+Check for unresolved package imports, extra chunks, remote imports, syntax errors, top-level Node globals, or code that expects a normal URL instead of a Blob module URL.
+
+Remember that relative imports from a Blob URL cannot resolve to files in the installed package. Bundle everything into the entrypoint.
+
+### Agent Server request fails before network activity
+
+Ensure `path` begins with exactly one `/`. Do not use an absolute URL, protocol-relative URL, or relative path.
+
+### Nested path is wrong
+
+Treat the mount `path` as a route remainder without a leading slash. Build navigation URLs from `/extensions/{encoded-extension-name}/{declared-page-root}` and encode user-controlled route segments.
+
+### UI duplicates after re-enable
+
+Return all activation and mount disposers. Remove injected style elements, stop timers, detach listeners, and prevent late async callbacks from writing after disposal.
+
+### App works locally but not from Git
+
+Confirm the manifest and built entrypoint are committed, the requested ref contains them, `repo_path` points at the directory containing `canvas-extension.json`, and generated output is not excluded from publication.

package/skills/canvas-extension-api/references/v1-contract.md

@@ -0,0 +1,250 @@
+# Canvas Extensions API v1 contract
+
+Use this reference for manifest schema 1 and host API 1 as implemented by the initial Apps frontend landing.
+
+## Authoritative sources
+
+Upstream repository: <https://github.com/OpenHands/OpenHands>
+
+Initial frontend landing: [PR #16895](https://github.com/OpenHands/OpenHands/pull/16895), `feat: land the Canvas Extensions frontend (load pages, sidebar, customize)`.
+
+Inspect these files when targeting a newer OpenHands revision:
+
+- `specs/canvas-extensions.md` - product decisions and package contract.
+- `src/types/canvas-extension.ts` - TypeScript source of truth for host API types.
+- `src/extensions/canvas-extension-module-loader.ts` - ESM loading and `activate` validation.
+- `src/components/features/canvas-extensions/canvas-extensions-runtime.tsx` - registration, activation, disposal, and backend scoping.
+- `src/routes/canvas-extension-page.tsx` - route matching and mount lifecycle.
+- `src/api/canvas-extensions-service.ts` - management endpoints and authenticated Agent Server request behavior.
+- `src/fixtures/canvas-extensions/demo-page/` - minimal dependency-free fixture.
+- `docs/CANVAS_EXTENSIONS_TESTING.md` - mock frontend workflow.
+
+## Product and trust model
+
+Treat the active Agent Server as the owner of installed apps. Source, resolved revision, files, manifest, and enabled state live on that backend. Switching backend replaces the active app inventory.
+
+Treat enabled code as trusted same-realm JavaScript. No iframe, worker sandbox, granular permission boundary, or CSS security boundary exists in v1. Enabled code has the ambient browser authority available to Canvas and can use authenticated helpers for the current backend.
+
+Keep install and enable separate. Installation produces a disabled app. Enabling is the explicit execution consent point. Enablement and disablement are hot and require no restart.
+
+## Manifest schema 1
+
+Filename: `canvas-extension.json` at the app package root.
+
+```ts
+interface CanvasExtensionManifest {
+  schema_version: 1;
+  name: string;
+  display_name?: string | null;
+  version: string;
+  description?: string | null;
+  entrypoint: string;
+  contributes?: {
+    pages?: CanvasExtensionPageContribution[] | null;
+  } | null;
+}
+
+interface CanvasExtensionPageContribution {
+  id: string;
+  title: string;
+  path: string;
+  nav_label?: string | null;
+  description?: string | null;
+}
+```
+
+Required manifest fields are `schema_version`, `name`, `version`, and `entrypoint`. A useful page package also supplies `display_name`, `description`, and at least one `contributes.pages` entry.
+
+Apply these rules:
+
+- Match app manifest names and contribution IDs against `^[a-z0-9]+(?:-[a-z0-9]+)*$`.
+- Begin each page path with `/`.
+- Use one or more kebab-case route segments for each page path.
+- Keep the entrypoint inside the installed app package root.
+- Produce one self-contained browser ESM entrypoint.
+- Bundle or embed dependencies, CSS, and small assets.
+- Leave no unresolved bare imports or external output chunks.
+
+The frontend normalizes the declared leading slash away for internal route matching. It validates the app manifest name, contribution ID, and every path segment before admitting the page.
+
+## Host API 1
+
+```ts
+interface CanvasExtensionHost {
+  readonly apiVersion: "1";
+  readonly extension: Readonly<{
+    name: string;
+    version: string;
+    resolvedRef: string | null;
+  }>;
+  readonly backend: Readonly<{
+    id: string;
+    kind: "local" | "cloud";
+    orgId: string | null;
+  }>;
+  registerPage(
+    contributionId: string,
+    mount: CanvasExtensionPageMount,
+  ): () => void;
+  navigate(path: string): void;
+  agentServer: {
+    request<T = unknown>(request: {
+      method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+      path: string;
+      body?: unknown;
+      headers?: Record<string, string>;
+    }): Promise<T>;
+  };
+}
+
+type CanvasExtensionPageMount = (context: {
+  container: HTMLElement;
+  path: string;
+  navigate(path: string): void;
+}) => void | (() => void) | Promise<void | (() => void)>;
+```
+
+The ESM entrypoint must export:
+
+```ts
+export function activate(
+  host: CanvasExtensionHost,
+): void | (() => void) | Promise<void | (() => void)>;
+```
+
+The loader fetches authenticated JavaScript text, creates a temporary Blob URL, imports it as ESM, verifies the `activate` export, and revokes the Blob URL. Import does not activate a disabled installation.
+
+## Registration constraints
+
+Register each page during activation using exactly the page ID declared in the manifest. The runtime rejects undeclared IDs and duplicate registrations.
+
+Return the unregister function from `activate` for a single contribution, or collect multiple unregister functions and return one disposer:
+
+```js
+export function activate(host) {
+  const disposers = [
+    host.registerPage("overview", mountOverview),
+    host.registerPage("settings", mountSettings),
+  ];
+  return () => {
+    for (const dispose of disposers.reverse()) dispose();
+  };
+}
+```
+
+The runtime invokes activation cleanup and registration cleanup when disabling, uninstalling, updating, switching backend, reconnecting, or otherwise replacing the activation inventory. Cleanup errors are logged and do not prevent later cleanup attempts.
+
+## Routing
+
+Canvas mounts a declared page under:
+
+```text
+/extensions/{extension-name}/{declared-page-path}
+```
+
+For an app `canvas-pulse` and page path `/pulse`, the root URL is:
+
+```text
+/extensions/canvas-pulse/pulse
+```
+
+A visit to:
+
+```text
+/extensions/canvas-pulse/pulse/services/agent_server
+```
+
+selects the longest matching declared page path and passes this remainder to the mount callback:
+
+```text
+services/agent_server
+```
+
+Use the mount callback's `navigate` function, or `host.navigate`, rather than manipulating history directly. Pass a Canvas path, typically an absolute path such as `/extensions/canvas-pulse/pulse`.
+
+The route is base-path aware through React Router. Avoid constructing browser origins or assuming Canvas runs at `/`.
+
+## Agent Server requests
+
+Use `host.agentServer.request` to target the app-owning backend with Canvas authentication. The helper accepts method, root-relative path, body, and headers.
+
+Valid:
+
+```js
+const serverInfo = await host.agentServer.request({
+  path: "/server_info",
+});
+```
+
+Invalid:
+
+```js
+host.agentServer.request({ path: "server_info" });
+host.agentServer.request({ path: "//other-host/path" });
+host.agentServer.request({ path: "https://other-host/path" });
+```
+
+The current service rejects paths that do not begin with one `/`. It defaults `method` to `GET`.
+
+## Runtime lifecycle
+
+For every enabled installation, Canvas:
+
+1. Fetches authenticated entrypoint text from the owning backend.
+2. Imports the self-contained ESM bundle from a Blob URL.
+3. Validates the `activate` export.
+4. Creates an app-scoped registry and calls `activate`.
+5. Admits only page registrations declared by the manifest.
+6. Renders contributed pages under a Canvas-owned error boundary.
+7. Unmounts pages and invokes cleanup when the activation inventory changes.
+
+A page mount may be synchronous or asynchronous. If an async mount resolves after route disposal, Canvas immediately invokes the returned disposer.
+
+Build app code to tolerate repeated activation and mounting. Guard asynchronous requests against late state updates. Clear intervals, animation frames, observers, event listeners, and DOM/style nodes.
+
+## Management API
+
+The current Canvas frontend service calls:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/canvas-extensions/installed` | List installed apps |
+| `POST` | `/api/canvas-extensions/install` | Install disabled from Git or backend-local path |
+| `PATCH` | `/api/canvas-extensions/installed/{name}` | Set enabled state |
+| `DELETE` | `/api/canvas-extensions/installed/{name}` | Uninstall |
+| `GET` | `/api/canvas-extensions/installed/{name}/bundle` | Fetch entrypoint JavaScript text |
+
+Install request:
+
+```json
+{
+  "source": "github:owner/repository",
+  "ref": "main",
+  "repo_path": "extensions/example-dashboard",
+  "force": false
+}
+```
+
+Interpret backend-local paths on the Agent Server machine, not in the frontend process. For a backend-local source, the current Canvas frontend joins a supplied `repo_path` into `source` before sending the install request and sends `repo_path: null`; select the app package directory as seen by the Agent Server. A repository may hold multiple apps under different `repo_path` values.
+
+Each install request resolves exactly one canvas extension package root. For a remote repository, the directory selected by `repo_path`, or the repository root when `repo_path` is omitted, must contain that app's `canvas-extension.json`. For a backend-local source, the `source` path is already the selected app package directory. The current Add app form submits one install request and does not recursively discover or bulk-install nested app manifests. Install every remote app separately with the same `source` and `ref` when appropriate and a distinct `repo_path`; submit every local app package directory separately.
+
+Treat co-located apps as independent installations: each app has its own manifest name, version, resolved revision record, enabled state, bundle, registrations, and cleanup lifecycle. Shared repository source or build tooling does not combine their runtime identities.
+
+Backend endpoint availability may lag behind the frontend. HTTP 404 means the backend lacks Apps support. Cloud backends are not supported by the current frontend service.
+
+## Current v1 limitations
+
+Do not promise or implement these features without confirming a newer contract:
+
+- conversation tabs or panels;
+- header, footer, badge, or arbitrary host slots;
+- code-free theme contributions;
+- visualizer augmentation or replacement;
+- marketplace signing or publisher verification;
+- enforceable fine-grained permissions;
+- iframe or worker isolation;
+- arbitrary install lifecycle scripts;
+- automatic agent-driven enablement.
+
+Page contributions are the supported host API 1 ABI. Host compatibility manifest fields and a published Canvas Extensions API SDK or bundler template are not part of the current contract.

package/skills/canvas-extension-api/scripts/validate-extension.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+const name = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const semver = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const imports = /(?:^|[;}\n])\s*import\s+(?:[^"'()]*?\s+from\s+)?["']([^"']+)["']|(?:^|[;}\n])\s*export\s+[^"']*?\s+from\s+["']([^"']+)["']/gm;
+const forbidden = [
+  [/(?:^|[;}\n])\s*import\s*\(/m, "runtime dynamic import"],
+  [/\bexport\s+[^;]*?\sfrom\s*["']/m, "re-exported dependency"],
+  [/\bnew\s+URL\(\s*["']\.?\.?\//m, "relative URL asset"],
+  [/\b(?:require\s*\(|module\.exports)/, "CommonJS dependency"],
+  [/sourceMappingURL=/, "source-map reference"],
+];
+
+const [target, ...options] = process.argv.slice(2);
+if (!target || target === "--help" || target === "-h") {
+  console.log("Usage: validate-extension.mjs <app-directory> [--dist] [--marker <text>]");
+  process.exit(target ? 0 : 2);
+}
+const checkDist = options.includes("--dist");
+const markers = [];
+for (let i = 0; i < options.length; i += 1) {
+  if (options[i] === "--marker" && options[i + 1]) markers.push(options[++i]);
+  else if (options[i] !== "--dist") throw new Error(`Unknown option: ${options[i]}`);
+}
+const root = path.resolve(target);
+const errors = [];
+const fail = (message) => errors.push(message);
+const within = (parent, child) => {
+  const relative = path.relative(parent, child);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+
+let manifest;
+try {
+  if (!(await stat(root)).isDirectory()) throw new Error("not a directory");
+  manifest = JSON.parse(await readFile(path.join(root, "canvas-extension.json"), "utf8"));
+} catch (error) {
+  console.error(`ERROR: Cannot read App package: ${error.message}`);
+  process.exit(1);
+}
+if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) fail("Manifest root must be an object.");
+if (manifest.schema_version !== 1) fail("Manifest schema_version must equal 1.");
+for (const field of ["name", "version", "entrypoint"]) {
+  if (typeof manifest[field] !== "string" || !manifest[field].trim()) fail(`Manifest ${field} must be a non-empty string.`);
+}
+if (typeof manifest.name === "string" && !name.test(manifest.name)) fail("Manifest name must use lowercase kebab-case.");
+if (typeof manifest.version === "string" && !semver.test(manifest.version)) fail("Manifest version must use semantic versioning.");
+
+const ids = new Set();
+const paths = new Set();
+const pages = manifest.contributes?.pages;
+if (!Array.isArray(pages) || pages.length === 0) fail("Manifest must declare at least one routed page.");
+for (const [index, page] of (pages ?? []).entries()) {
+  const label = `contributes.pages[${index}]`;
+  if (!page || typeof page !== "object" || Array.isArray(page)) { fail(`${label} must be an object.`); continue; }
+  if (typeof page.id !== "string" || !name.test(page.id)) fail(`${label}.id must use lowercase kebab-case.`);
+  if (typeof page.title !== "string" || !page.title.trim()) fail(`${label}.title must be a non-empty string.`);
+  if (typeof page.path !== "string" || !/^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*)(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/.test(page.path)) fail(`${label}.path must be an absolute kebab-case route.`);
+  if (ids.has(page.id)) fail(`Page id ${page.id} is declared more than once.`); ids.add(page.id);
+  if (paths.has(page.path)) fail(`Page path ${page.path} is declared more than once.`); paths.add(page.path);
+}
+
+const entrypoint = checkDist
+  ? path.resolve(root, "dist", manifest.entrypoint ?? "")
+  : path.resolve(root, manifest.entrypoint ?? "");
+try {
+  const [realRoot, realEntrypoint] = await Promise.all([realpath(root), realpath(entrypoint)]);
+  if (!within(realRoot, realEntrypoint)) fail("Entrypoint escapes the App package root.");
+  const source = await readFile(realEntrypoint, "utf8");
+  if (!source.trim()) fail("Entrypoint is empty.");
+  if (!/\bexport\s*(?:\{[^}]*\bactivate\b[^}]*\}|(?:async\s+)?function\s+activate\b)/m.test(source)) fail("Entrypoint must export activate.");
+  for (const match of source.matchAll(imports)) {
+    const specifier = match[1] ?? match[2];
+    if (specifier && !specifier.startsWith("data:") && !specifier.startsWith("blob:")) fail(`Entrypoint contains unresolved module specifier: ${specifier}`);
+  }
+  for (const [pattern, description] of forbidden) if (pattern.test(source)) fail(`Entrypoint contains ${description}.`);
+  for (const marker of markers) if (!source.includes(marker)) fail(`Entrypoint is missing required marker: ${marker}`);
+  const registered = new Set([...source.matchAll(/\.registerPage\s*\(\s*["']([^"']+)["']/g)].map((match) => match[1]));
+  for (const id of registered) if (!ids.has(id)) fail(`Entrypoint registers undeclared page id ${id}.`);
+} catch (error) { fail(`Cannot read entrypoint: ${error.message}`); }
+
+if (checkDist) {
+  try {
+    const files = await readdir(path.join(root, "dist"), { recursive: true });
+    const expected = manifest.entrypoint;
+    if (files.length !== 1 || files[0] !== expected) fail(`Expected exactly dist/${expected}; found ${files.join(", ") || "nothing"}.`);
+  } catch (error) { fail(`Cannot inspect dist output: ${error.message}`); }
+}
+if (errors.length) { for (const error of errors) console.error(`ERROR: ${error}`); process.exit(1); }
+console.log(`Canvas App validation passed: ${root}${checkDist ? " (dist)" : ""}`);

package/skills/canvas-extension-api/scripts/validate-extension.test.mjs

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+const validator = new URL("./validate-extension.mjs", import.meta.url);
+
+async function createApp(entrypoint) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "canvas-extension-validator-"));
+  await mkdir(path.join(root, "dist"), { recursive: true });
+  await writeFile(
+    path.join(root, "canvas-extension.json"),
+    JSON.stringify({
+      schema_version: 1,
+      name: "validator-test",
+      version: "1.0.0",
+      entrypoint,
+      contributes: {
+        pages: [{ id: "home", title: "Home", path: "/home" }],
+      },
+    }),
+  );
+  await writeFile(
+    path.join(root, "dist", entrypoint),
+    "export function activate() {}",
+  );
+  return root;
+}
+
+test("--dist uses the manifest entrypoint name", async () => {
+  const root = await createApp("bundle.mjs");
+  try {
+    const result = spawnSync(
+      process.execPath,
+      [validator.pathname, root, "--dist"],
+      { encoding: "utf8" },
+    );
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("--dist rejects sibling output chunks", async () => {
+  const root = await createApp("extension.js");
+  try {
+    await writeFile(path.join(root, "dist", "lazy.js"), "export {};");
+    const result = spawnSync(
+      process.execPath,
+      [validator.pathname, root, "--dist"],
+      { encoding: "utf8" },
+    );
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /Expected exactly dist\/extension\.js/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});