create-ngis-plugin 0.1.0

package/dist/templates/plugin-starter/presets/connector/src/plugin.ts

@@ -0,0 +1,132 @@
+/**
+ * **Archetype: connector** (Stage 15 Z8, F15.13).
+ *
+ * No panel, no rail entry, no UI at all — only `capabilities.commands`. A
+ * connector exists to be **driven from outside the browser**: a scene script
+ * calls `scene.plugin("org.example.connector").invoke("list-resources", {...})`
+ * and the invocation travels the codeenv mailbox (Stage 11 E7) to whichever
+ * browser tab has this scene open and this plugin active. That lane and its
+ * failure modes are documented at `/market/devkit/docs/agent-operation`.
+ *
+ * ## What a connector must get right
+ *
+ * - **Every value it returns crosses a JSON boundary.** The mailbox stores
+ *   `result_json` and the sandbox reads it back over HTTP, so a returned DOM
+ *   node, class instance or function is not "unsupported" — it is silently
+ *   lost. F15.2(1) is the same rule for host-crossing surfaces generally; here
+ *   it also binds the return value.
+ * - **The result has a size cap.** `codeenv.plugin-invoke.max-result-bytes`
+ *   defaults to **65536**, and `max-args-bytes` likewise. A connector that
+ *   returns a whole attribute table gets a `400`, so page and cap deliberately.
+ * - **A caller waits, and a caller gives up.** The mailbox TTL defaults to
+ *   **60 s** (`codeenv.plugin-invoke.ttl-seconds`); an invocation no tab claims
+ *   expires and the sandbox raises "expired before a browser tab claimed it".
+ *   Do slow work in a task, return its id, and let the caller poll.
+ * - **The host is `ctx.host`, never a stored reference** (F15.2(2)).
+ * - **The command id must be prefixed with the *whole* plugin id.**
+ *   `commandPluginId` splits on the **last** dot, so a command called
+ *   `connector.list` would resolve to a plugin named `connector` and arrive with
+ *   no `ctx.host` at all.
+ */
+
+import { defineNgisPlugin } from "@ngis/plugin-sdk";
+import type {
+  CommandInvokeContext,
+  NgisPlugin,
+  NgisResourceType,
+} from "@ngis/plugin-sdk";
+
+const EXT_ID = "org.example.connector";
+const LIST_COMMAND_ID = `${EXT_ID}.list-resources`;
+const DESCRIBE_COMMAND_ID = `${EXT_ID}.describe-scene`;
+
+/** Well under `max-result-bytes` even with long names. Page, do not truncate
+ *  silently: the caller is told how many rows exist. */
+const PAGE_SIZE = 100;
+
+function requireHost(ctx: CommandInvokeContext, commandId: string) {
+  const host = ctx.host;
+  if (!host) throw new Error(`${commandId} was invoked without a host facade`);
+  return host;
+}
+
+interface ListArgs {
+  readonly types?: readonly string[];
+  readonly offset?: number;
+}
+
+/** The closed set `resources.list` accepts. A caller's JSON is filtered against
+ *  it rather than cast: an unknown type is dropped, never forwarded. */
+const RESOURCE_TYPES: readonly NgisResourceType[] = ["vector", "raster", "table", "file"];
+
+function readResourceTypes(types: readonly string[] | undefined): readonly NgisResourceType[] {
+  if (!types) return [];
+  return RESOURCE_TYPES.filter((known) => types.includes(known));
+}
+
+const plugin: NgisPlugin = defineNgisPlugin({
+  manifest: {
+    id: EXT_ID,
+    name: "Connector",
+    version: "0.1.0",
+    minNgisVersion: "0.4.0",
+    capabilities: {
+      commands: [
+        {
+          id: LIST_COMMAND_ID,
+          title: "List scene resources",
+          paramsSchema: {
+            type: "object",
+            properties: {
+              types: { type: "array", items: { type: "string" } },
+              offset: { type: "integer", minimum: 0 },
+            },
+          },
+          invoke: async (args: unknown, ctx: CommandInvokeContext) => {
+            const host = requireHost(ctx, LIST_COMMAND_ID);
+            const { types, offset = 0 } =
+              (typeof args === "object" && args !== null ? args : {}) as ListArgs;
+
+            const wanted = readResourceTypes(types);
+            const all = await host.resources.list(
+              wanted.length > 0 ? { types: wanted } : undefined,
+            );
+            const page = all.slice(offset, offset + PAGE_SIZE);
+
+            return {
+              total: all.length,
+              offset,
+              // `nextOffset` is `null` at the end rather than absent: a caller
+              // must be able to tell "no more" from "the field was dropped".
+              nextOffset: offset + PAGE_SIZE < all.length ? offset + PAGE_SIZE : null,
+              resources: page.map((resource) => ({
+                id: resource.id,
+                name: resource.name,
+                type: resource.type,
+                // The id every dataset API takes, and the one a recipe's input
+                // slot is filled with — a scene-resource id is not a file id.
+                fileId: resource.fileId,
+              })),
+            };
+          },
+        },
+        {
+          id: DESCRIBE_COMMAND_ID,
+          title: "Describe the current scene",
+          paramsSchema: { type: "object", properties: {} },
+          invoke: async (_args: unknown, ctx: CommandInvokeContext) => {
+            const host = requireHost(ctx, DESCRIBE_COMMAND_ID);
+            const scene = await host.scene.get();
+            if (!scene) return { scene: null };
+            return {
+              scene: { id: scene.id, name: scene.name, type: scene.type },
+            };
+          },
+        },
+      ],
+    },
+  },
+});
+
+export default plugin;
+export { EXT_ID, LIST_COMMAND_ID, DESCRIBE_COMMAND_ID, PAGE_SIZE };

package/dist/templates/plugin-starter/presets/tool-frontend/manifest.json

@@ -0,0 +1,22 @@
+{
+  "id": "org.example.tool-frontend",
+  "kind": "ui-plugin",
+  "name": "Tool front end",
+  "version": "0.1.0",
+  "minNgisVersion": "0.4.0",
+  "entry": "bundle.mjs",
+  "capabilities": {
+    "panels": [
+      { "id": "org.example.tool-frontend.main", "slot": "right" }
+    ],
+    "railTools": [
+      { "id": "org.example.tool-frontend.open" }
+    ],
+    "commands": [
+      { "id": "org.example.tool-frontend.run" }
+    ]
+  },
+  "description": "A rail entry and side panel for one analysis tool, with the run itself exposed as a command.",
+  "category": "analysis",
+  "tags": ["archetype", "tool-frontend"]
+}

package/dist/templates/plugin-starter/presets/tool-frontend/src/plugin.ts

@@ -0,0 +1,158 @@
+/**
+ * **Archetype: tool front end** (Stage 15 Z8, F15.13).
+ *
+ * The shape most first plugins want: one rail entry, one side panel, and a
+ * single analysis tool run. What makes it an archetype rather than a demo is
+ * where the host lives.
+ *
+ * ## The rule this file exists to demonstrate (F15.2)
+ *
+ * **The host is reached as `ctx.host`, inside the invocation, and is never
+ * stored.** A host handle does not outlive the call that produced it — Stage 13
+ * `V-142`, elevated to contract by F15.2(2) — so a `let host` at module scope is
+ * a shape this template must warn against rather than show, even though three
+ * Stage 13 dogfood plugins still carry one.
+ *
+ * **A declarative panel has no channel through which a host arrives.** The
+ * runtime registers `capabilities.panels` before `activate(host)` runs and
+ * `PanelRenderContext` carries only `close` (`V-339`, F15.2(3)). That is why the
+ * panel below renders and the *command* runs: the run path is a command, and a
+ * command's `ctx.host` is the command owner's own scope-enforced 0.4 facade.
+ *
+ * The same command is the plugin's whole external surface. A scene script calls
+ * it with `scene.plugin("org.example.tool-frontend").invoke("run", {...})` and a
+ * remote agent reaches it the same way through the codeenv mailbox — see the
+ * agent-operation guide at `/market/devkit/docs/agent-operation`.
+ */
+
+import { defineNgisPlugin } from "@ngis/plugin-sdk";
+import type {
+  CommandInvokeContext,
+  GisRailInvokeContext,
+  NgisPlugin,
+} from "@ngis/plugin-sdk";
+
+const EXT_ID = "org.example.tool-frontend";
+const PANEL_ID = `${EXT_ID}.main`;
+const OPEN_TOOL_ID = `${EXT_ID}.open`;
+const RUN_COMMAND_ID = `${EXT_ID}.run`;
+
+/**
+ * The analysis tool this front end drives. Replace it with a real tool id from
+ * `GET /api/analysis/tools/page`.
+ *
+ * Two catalog facts worth knowing before you pick one. `/ui-schema` answers
+ * `200` for **883** tools whose detail endpoint answers `404` because they are
+ * disabled (`V-371`), so read the detail endpoint before trusting a schema. And
+ * the nine PostGIS tools are invisible to `ngis-geoanalysis`'s binding and
+ * execution validation (`V-47`), so a wrong binding on one of those is not
+ * refused — it just runs wrong.
+ */
+const TOOL_ID = "00000000-0000-4000-8000-000000000000";
+
+interface RunArgs {
+  readonly params?: Record<string, string>;
+  readonly sceneId?: string;
+}
+
+function readRunArgs(args: unknown): RunArgs {
+  if (typeof args !== "object" || args === null) return {};
+  return args as RunArgs;
+}
+
+const plugin: NgisPlugin = defineNgisPlugin({
+  manifest: {
+    id: EXT_ID,
+    name: "Tool front end",
+    version: "0.1.0",
+    minNgisVersion: "0.4.0",
+    capabilities: {
+      panels: [
+        {
+          id: PANEL_ID,
+          slot: "right",
+          label: "Tool front end",
+          render: (container) => {
+            container.replaceChildren();
+            const root = document.createElement("div");
+            root.style.padding = "16px";
+            root.style.display = "grid";
+            root.style.gap = "8px";
+
+            const heading = document.createElement("p");
+            heading.textContent = "Tool front end";
+            const body = document.createElement("p");
+            body.textContent =
+              `Run this plugin's tool by invoking the command ${RUN_COMMAND_ID}. ` +
+              "The panel is presentation only: a declarative panel is registered " +
+              "before activate(host) runs, so no host reaches it.";
+
+            root.append(heading, body);
+            container.appendChild(root);
+            return () => container.replaceChildren();
+          },
+        },
+      ],
+      railTools: [
+        {
+          id: OPEN_TOOL_ID,
+          // A literal string, not an i18n key — a third-party plugin has no
+          // message catalog for the host to resolve against.
+          label: "Open tool front end",
+          kind: "action",
+          invoke: (ctx: GisRailInvokeContext) => {
+            ctx.api.panels.open("right", PANEL_ID);
+          },
+        },
+      ],
+      commands: [
+        {
+          id: RUN_COMMAND_ID,
+          title: "Run the tool",
+          paramsSchema: {
+            type: "object",
+            properties: {
+              params: {
+                type: "object",
+                description: "Tool parameters, every value a string.",
+                additionalProperties: { type: "string" },
+              },
+              sceneId: { type: "string" },
+            },
+          },
+          invoke: async (args: unknown, ctx: CommandInvokeContext) => {
+            // Guarded, always: an id whose namespace names no plugin the host
+            // knows yields a ctx with no `host` key at all, because the factory
+            // mints rather than validates.
+            const host = ctx.host;
+            if (!host) {
+              throw new Error(`${RUN_COMMAND_ID} was invoked without a host facade`);
+            }
+
+            const { params = {}, sceneId } = readRunArgs(args);
+            const handle = await host.tasks.run({
+              toolId: TOOL_ID,
+              params,
+              ...(sceneId ? { sceneId } : {}),
+            });
+
+            await host.ui.toast({
+              message: "Run submitted",
+              kind: "info",
+              description: handle.id,
+            });
+
+            // JSON, because this value crosses the codeenv mailbox back to the
+            // caller: every host-crossing value is JSON-serializable (F15.2).
+            return { taskId: handle.id, kind: handle.kind };
+          },
+        },
+      ],
+    },
+  },
+});
+
+// The bundle contract (ED16c) requires a default export — the loader's
+// `import()` reads `module.default` as the `NgisPlugin`.
+export default plugin;
+export { EXT_ID, PANEL_ID, OPEN_TOOL_ID, RUN_COMMAND_ID, TOOL_ID };

package/dist/templates/plugin-starter/presets/workflow-app/manifest.json

@@ -0,0 +1,20 @@
+{
+  "id": "org.example.workflow-app",
+  "kind": "ui-plugin",
+  "name": "Workflow app",
+  "version": "0.1.0",
+  "minNgisVersion": "0.4.0",
+  "entry": "bundle.mjs",
+  "capabilities": {
+    "panels": [
+      { "id": "org.example.workflow-app.main", "slot": "right" }
+    ],
+    "commands": [
+      { "id": "org.example.workflow-app.run" },
+      { "id": "org.example.workflow-app.status" }
+    ]
+  },
+  "description": "A front end for one published recipe: run it by slot key, then read the instance back.",
+  "category": "workflow",
+  "tags": ["archetype", "workflow-app", "recipe"]
+}

package/dist/templates/plugin-starter/presets/workflow-app/src/plugin.ts

@@ -0,0 +1,161 @@
+/**
+ * **Archetype: workflow app** (Stage 15 Z8, F15.13).
+ *
+ * A front end for one **published recipe** — a saved flow graph published as a
+ * workflow tool and listed as a `tool`-kind extension. This is the archetype the
+ * describe→recipe scaffolder at `/market/author/ai` produces work for: the
+ * scaffolder emits the recipe (data), and a package like this one gives it a
+ * button and an external command.
+ *
+ * ## Three facts about a published recipe that change how you write this
+ *
+ * 1. **Its whole invocable surface is `slotKey → fileId`.**
+ *    `compileToolSchema` emits `x-role` of `"input"` and `"output"` and never
+ *    `"option"`, so a published workflow tool has **no knobs**. Every option the
+ *    recipe's author chose is already baked into the published graph's node
+ *    `params`. Passing anything but file ids here is passing nothing.
+ * 2. **You do not branch on it.** `host.tasks.run` forks on the registry row's
+ *    `provider` inside the facade — `"workflow"` invokes the tool and polls an
+ *    instance, anything else submits an analysis task. The plugin sees one API
+ *    and must not branch itself (F13.2).
+ * 3. **A workflow run has no log stream.** There is no workflow SSE endpoint and
+ *    the facade does not fabricate one: `NgisTaskState.logs` is permanently `[]`
+ *    for `kind: "workflow"`. A UI that shows a log pane for a recipe shows an
+ *    empty box forever.
+ *
+ * The host is reached as `ctx.host` inside each command and never stored
+ * (F15.2); the panel is presentation only, because a declarative panel is
+ * registered before `activate(host)` runs and `PanelRenderContext` carries only
+ * `close` (`V-339`).
+ */
+
+import { defineNgisPlugin } from "@ngis/plugin-sdk";
+import type { CommandInvokeContext, NgisPlugin } from "@ngis/plugin-sdk";
+
+const EXT_ID = "org.example.workflow-app";
+const PANEL_ID = `${EXT_ID}.main`;
+const RUN_COMMAND_ID = `${EXT_ID}.run`;
+const STATUS_COMMAND_ID = `${EXT_ID}.status`;
+
+/**
+ * The published recipe this app drives — a **bare uuid in the shared
+ * `ngis_model_tool` id space** with `provider = "workflow"`, which is why
+ * `GetToolSchema(toolId)` and the ui-schema endpoint resolve it exactly like a
+ * builtin. Replace it with your own published recipe's tool id.
+ */
+const RECIPE_TOOL_ID = "00000000-0000-4000-8000-000000000000";
+
+interface RunArgs {
+  /** `slotKey → fileId`. Nothing else is accepted by the server. */
+  readonly inputs?: Record<string, string>;
+  readonly sceneId?: string;
+}
+
+function readArgs<T>(args: unknown): Partial<T> {
+  if (typeof args !== "object" || args === null) return {};
+  return args as Partial<T>;
+}
+
+function requireHost(ctx: CommandInvokeContext, commandId: string) {
+  const host = ctx.host;
+  if (!host) throw new Error(`${commandId} was invoked without a host facade`);
+  return host;
+}
+
+const plugin: NgisPlugin = defineNgisPlugin({
+  manifest: {
+    id: EXT_ID,
+    name: "Workflow app",
+    version: "0.1.0",
+    minNgisVersion: "0.4.0",
+    capabilities: {
+      panels: [
+        {
+          id: PANEL_ID,
+          slot: "right",
+          label: "Workflow app",
+          render: (container) => {
+            container.replaceChildren();
+            const root = document.createElement("div");
+            root.style.padding = "16px";
+            root.style.display = "grid";
+            root.style.gap = "8px";
+
+            const heading = document.createElement("p");
+            heading.textContent = "Workflow app";
+            const body = document.createElement("p");
+            body.textContent =
+              `Invoke ${RUN_COMMAND_ID} with one file id per input slot, then ` +
+              `${STATUS_COMMAND_ID} with the returned id. A recipe run is a ` +
+              "workflow instance and has no log stream.";
+
+            root.append(heading, body);
+            container.appendChild(root);
+            return () => container.replaceChildren();
+          },
+        },
+      ],
+      commands: [
+        {
+          id: RUN_COMMAND_ID,
+          title: "Run the recipe",
+          paramsSchema: {
+            type: "object",
+            properties: {
+              inputs: {
+                type: "object",
+                description: "slotKey -> fileId. A recipe takes no options.",
+                additionalProperties: { type: "string" },
+              },
+              sceneId: { type: "string" },
+            },
+          },
+          invoke: async (args: unknown, ctx: CommandInvokeContext) => {
+            const host = requireHost(ctx, RUN_COMMAND_ID);
+            const { inputs = {}, sceneId } = readArgs<RunArgs>(args);
+            const handle = await host.tasks.run({
+              toolId: RECIPE_TOOL_ID,
+              // `params` is the facade's one channel; for a workflow tool it is
+              // forwarded verbatim as `InvokeToolRequest.inputs`.
+              params: inputs,
+              ...(sceneId ? { sceneId } : {}),
+            });
+            return { id: handle.id, kind: handle.kind };
+          },
+        },
+        {
+          id: STATUS_COMMAND_ID,
+          title: "Read a run back",
+          paramsSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+          },
+          invoke: async (args: unknown, ctx: CommandInvokeContext) => {
+            const host = requireHost(ctx, STATUS_COMMAND_ID);
+            const { id } = readArgs<{ id: string }>(args);
+            if (!id) throw new Error(`${STATUS_COMMAND_ID} requires an id`);
+
+            const state = await host.tasks.get(id);
+            if (!state) return { id, status: null, outputs: [] };
+            return {
+              id: state.id,
+              kind: state.kind,
+              status: state.status,
+              stage: state.stage,
+              error: state.error,
+              outputs: state.outputs.map((output) => ({
+                name: output.name,
+                fileId: output.fileId,
+                primary: output.primary,
+              })),
+            };
+          },
+        },
+      ],
+    },
+  },
+});
+
+export default plugin;
+export { EXT_ID, PANEL_ID, RUN_COMMAND_ID, STATUS_COMMAND_ID, RECIPE_TOOL_ID };

package/dist/templates/plugin-starter/scripts/build.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Bundles `src/plugin.ts` -> `dist/bundle.mjs` per the frozen bundle contract
+ * (ED16c, `docs/design-extension-platform.md` §5): self-contained ESM, one
+ * file, externals `react`/`react-dom`/`react/jsx-runtime`/`@ngis/plugin-sdk`
+ * (the host's import map resolves those bare specifiers at load time — never
+ * bundle them).
+ *
+ * Matches the shape `ngis-extension`'s own seed-bundle spike used to
+ * repackage `ngis.sample-coordinate-pin` (esbuild, the same externals) —
+ * see `ngis-backend/stages/11-extension-platform/session-2026-07-23-e1-extension-service.md`.
+ *
+ * **`react/jsx-runtime` + `jsx: "automatic"` (Stage 13 X6).** X4b added
+ * `react/jsx-runtime` to the loader's externals table and shipped the shim
+ * under `public/plugin-externals/`; this is the authoring half. The two lines
+ * below land together on purpose: esbuild's default JSX mode is the *classic*
+ * runtime, which emits `React.createElement` and never references
+ * `react/jsx-runtime` at all — so adding the external without the mode leaves
+ * a dead entry, and adding the mode without the external makes esbuild
+ * **resolve and inline** the host's React copy, which breaks hooks the moment
+ * two React instances share a page.
+ */
+
+import esbuild from "esbuild";
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const outfile = join(root, "dist", "bundle.mjs");
+
+if (!existsSync(join(root, "dist"))) mkdirSync(join(root, "dist"));
+
+await esbuild.build({
+  entryPoints: [join(root, "src", "plugin.ts")],
+  outfile,
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2020",
+  jsx: "automatic",
+  // All five entries in the host's import map (`src/sdk/plugin-loader.ts`'s
+  // `PLUGIN_EXTERNAL_SHIM_URLS`). `@ngis/plugin-ui` is the fifth, added in Stage 14: its
+  // components' runtime lives in the host bundle, so bundling it gives you a second copy of the
+  // host's own components rendering against a different React — the same silent breakage as
+  // bundling React itself, and just as invisible at build time.
+  external: [
+    "react",
+    "react-dom",
+    "react/jsx-runtime",
+    "@ngis/plugin-sdk",
+    "@ngis/plugin-ui",
+  ],
+  sourcemap: false,
+  minify: false,
+});
+
+const size = statSync(outfile).size;
+process.stdout.write(`[plugin-starter build] wrote ${outfile} (${size} bytes)\n`);

package/dist/templates/plugin-starter/scripts/finalize.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Final step of `npm run package`: copies the validated `manifest.json`
+ * alongside the built `dist/bundle.mjs` and prints a summary — the pair is
+ * then ready for `POST /api/extensions/{extId}/versions` (multipart
+ * `manifest` + `bundle`).
+ */
+
+import { copyFileSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const manifestSrc = join(root, "manifest.json");
+const manifestDist = join(root, "dist", "manifest.json");
+const bundlePath = join(root, "dist", "bundle.mjs");
+
+copyFileSync(manifestSrc, manifestDist);
+
+const manifest = JSON.parse(readFileSync(manifestSrc, "utf8"));
+const bundleSize = statSync(bundlePath).size;
+const manifestSize = statSync(manifestDist).size;
+
+process.stdout.write("\n[package] Ready for upload:\n");
+process.stdout.write(`  dist/manifest.json  (${manifestSize} bytes)  id=${manifest.id} version=${manifest.version}\n`);
+process.stdout.write(`  dist/bundle.mjs      (${bundleSize} bytes)\n`);
+process.stdout.write(
+  "\n  Upload with: curl -X POST <gateway>/api/extensions/{extId}/versions \\\n" +
+    '    -H "Authorization: Bearer <token>" \\\n' +
+    '    -F "manifest=@dist/manifest.json;type=application/json" \\\n' +
+    '    -F "bundle=@dist/bundle.mjs;type=text/javascript"\n' +
+    "  (creates a DRAFT — see ../../docs/plugin-authoring-guide.md for the full dev loop.)\n",
+);

package/dist/templates/plugin-starter/scripts/validate-manifest.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Client-side sanity check for `manifest.json`, mirroring
+ * `ngis-extension`'s `PackageManifestValidator` (ED16a/b) — catches the same
+ * mistakes locally instead of on a failed upload. Not a substitute for the
+ * server's validation (which is the actual authority); this just saves a
+ * round trip.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const manifestPath = join(root, "manifest.json");
+
+const EXT_ID_PATTERN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+const KNOWN_CAPABILITY_KEYS = new Set(["panels", "railTools", "layerTypes", "commands"]);
+
+const errors = [];
+function require_(condition, message) {
+  if (!condition) errors.push(message);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+require_(typeof manifest.id === "string" && manifest.id.length > 0, "manifest.id is required");
+require_(typeof manifest.name === "string" && manifest.name.length > 0, "manifest.name is required");
+require_(typeof manifest.version === "string" && manifest.version.length > 0, "manifest.version is required");
+require_(
+  typeof manifest.minNgisVersion === "string" && manifest.minNgisVersion.length > 0,
+  "manifest.minNgisVersion is required",
+);
+require_(typeof manifest.entry === "string" && manifest.entry.length > 0, "manifest.entry is required");
+
+if (typeof manifest.id === "string") {
+  require_(
+    EXT_ID_PATTERN.test(manifest.id),
+    `manifest.id must match ${EXT_ID_PATTERN} (namespaced, e.g. "org.example.my-plugin"): ${manifest.id}`,
+  );
+  require_(!manifest.id.startsWith("ngis."), `manifest.id "ngis.*" is reserved for first-party plugins`);
+}
+
+if (manifest.kind !== undefined) {
+  require_(manifest.kind === "ui-plugin", `manifest.kind must be "ui-plugin" in this stage: ${manifest.kind}`);
+}
+
+if (typeof manifest.version === "string") {
+  require_(SEMVER_PATTERN.test(manifest.version), `manifest.version must be strict x.y.z: ${manifest.version}`);
+}
+if (typeof manifest.minNgisVersion === "string") {
+  require_(
+    SEMVER_PATTERN.test(manifest.minNgisVersion),
+    `manifest.minNgisVersion must be strict x.y.z: ${manifest.minNgisVersion}`,
+  );
+}
+
+require_(manifest.entry === "bundle.mjs", `manifest.entry is fixed to "bundle.mjs" in v1: ${manifest.entry}`);
+
+if (manifest.capabilities === undefined || typeof manifest.capabilities !== "object" || manifest.capabilities === null) {
+  errors.push("manifest.capabilities must be an object");
+} else {
+  for (const key of Object.keys(manifest.capabilities)) {
+    require_(KNOWN_CAPABILITY_KEYS.has(key), `Unknown capability-summary key: "${key}"`);
+  }
+}
+
+if (errors.length > 0) {
+  process.stderr.write("[validate-manifest] manifest.json is invalid:\n");
+  for (const error of errors) process.stderr.write(`  - ${error}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(
+  `[validate-manifest] manifest.json OK — id=${manifest.id} version=${manifest.version} minNgisVersion=${manifest.minNgisVersion}\n`,
+);