@inharness-ai/claude4spec 1.0.21 → 1.0.22

package/dist/server/core/plugin-host/cross-cutting.js

@@ -1,14 +1,62 @@
 /**
- * Cross-cutting routes owned by the plugin host (M13). Currently exposes the
- * activation diagnostic endpoint. Phase 4 moves /api/entities/:type/:slug/versions
- * here too.
+ * Cross-cutting routes owned by the plugin host (M13), mounted on the PER-PROJECT
+ * router (so paths resolve under `/api/projects/:id`). Provides overlay-aware
+ * diagnostics + the machine-local trust gate:
+ *
+ *   GET  /_meta/entities  → activation partition (active/inactive/unknown)
+ *   GET  /_meta/plugins   → base ∪ overlay package diagnostics + shadow report
+ *   POST /trust-plugins   → persist trustProjectPlugins, trigger context rebuild
  */
 import { Router } from 'express';
-export function pluginHostRouter(host) {
+import { HOST_API_VERSION } from '../../../shared/plugin-host/manifest.js';
+export function pluginHostRouter(deps) {
+    const { host, registry, workspace, projectId, basePackages, overlayRecords, localPluginsPresent, trust, onContextConfigChanged, } = deps;
     const router = Router();
     router.get('/_meta/entities', (_req, res) => {
         res.json(host.partition());
     });
+    // M33: settings/commands of all loaded+trusted plugins in the
+    // effective pool — axis B, deliberately NOT filtered by `config.entities`
+    // (so a plugin's Settings section + slash-commands survive deactivation of
+    // its entity types). The Settings panel renders one section per plugin under
+    // `config.plugins[<name>]`; the editor registers each command as a slash
+    // extension.
+    router.get('/_meta/plugin-settings', (_req, res) => {
+        res.json({ sections: host.listSettings() });
+    });
+    router.get('/_meta/plugin-commands', (_req, res) => {
+        res.json({ commands: host.listCommands() });
+    });
+    router.get('/_meta/plugins', (_req, res) => {
+        const baseOriginForType = (type) => basePackages.find((p) => p.contributedTypes?.includes(type))?.package ?? '@c4s/builtin';
+        const shadowed = host.shadowReport().map((s) => ({
+            type: s.type,
+            overlayOrigin: s.overlayOrigin,
+            baseOrigin: baseOriginForType(s.type),
+        }));
+        const response = {
+            hostApiVersion: HOST_API_VERSION,
+            localPluginsPresent,
+            trust,
+            packages: [...basePackages, ...overlayRecords],
+            shadowed,
+        };
+        res.json(response);
+    });
+    // M33 trust gate. Persists the decision per (workspace × project) in
+    // `~/.claude4spec/` (never the repo) and rebuilds the context so the overlay
+    // (un)loads without a process restart. The client refetches activation after.
+    router.post('/trust-plugins', (req, res) => {
+        const value = req.body?.trust;
+        if (typeof value !== 'boolean') {
+            return res
+                .status(400)
+                .json({ error: { code: 'VALIDATION', message: 'trust must be a boolean' } });
+        }
+        registry.setProjectTrust(workspace, projectId, value);
+        onContextConfigChanged?.();
+        res.json({ trust: value });
+    });
     return router;
 }
 //# sourceMappingURL=cross-cutting.js.map

package/dist/server/core/plugin-host/cross-cutting.js.map

@@ -1 +1 @@
-{"version":3,"file":"cross-cutting.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/cross-cutting.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGjC,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAC/C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IAExB,MAAM,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC1C,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"cross-cutting.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/cross-cutting.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/frontend-assets.d.ts

@@ -0,0 +1,100 @@
+/**
+ * M33 — plugin frontend assets, two tiers.
+ *
+ * The serving layer for "Option B" plugin frontends. This express-free module
+ * owns the single path/trust convention shared by the serving route
+ * (`routes/plugins.ts`) and the manifest builder (`frontend-manifest.ts`), so
+ * the two cannot diverge.
+ *
+ *   • Overlay tier (phase 2): a TRUSTED project ships a precompiled bundle at
+ *     `<cwd>/.claude4spec/plugins/<name>/dist/frontend.js` (+ optional
+ *     `frontend.css`). Gated by `trustProjectPlugins` (per workspace × project,
+ *     machine-local) — the CALLER resolves the gate and passes `trusted`; an
+ *     untrusted/undecided project emits nothing, exactly like the overlay loader
+ *     refuses to run untrusted project code.
+ *
+ *   • Workspace tier (phase 3): a workspace/npm plugin (declared in
+ *     `~/.claude4spec/workspaces.json`, installed under `node_modules`) serves
+ *     its own `dist/frontend.js` (+ optional `dist/frontend.css`) UNGATED — a
+ *     consciously-installed base package is trusted by virtue of npm install,
+ *     parity with the backend base tier. Traversal-guarded by the passed
+ *     workspace package allowlist (the same list `loadWorkspacePlugins` uses).
+ */
+/**
+ * Walk up from `startDir` to the NEAREST ancestor that owns a readable
+ * `package.json` — the package root — or `null` if none within 12 levels. The
+ * caller has already proved the package's identity (`import.meta.resolve`
+ * resolved a DECLARED subpath of `packageName`), so we deliberately do NOT gate
+ * on the manifest `name`: a workspace plugin whose install/dir name differs from
+ * its real (e.g. scoped) `package.json` `name` must still resolve to its root.
+ * The 12-level bound is a cheap runaway guard for a pathological deep tree.
+ */
+export declare function nearestPackageRoot(startDir: string): string | null;
+/** The two precompiled assets a plugin frontend bundle may ship. */
+export type FrontendAssetFile = 'frontend.js' | 'frontend.css';
+/**
+ * Resolve the absolute path to stream for `GET /api/plugins/<name>/<file>`, or
+ * `null` when the request must 404. Returns null when:
+ *   - the trust gate is off (`!trusted`) — never emit project-committed code,
+ *   - `name` is not an actual overlay package — also guards path traversal, as
+ *     only directory names enumerated under `.claude4spec/plugins/` are eligible,
+ *   - the `dist/<file>` does not exist — a present, trusted project never
+ *     fabricates a bundle.
+ */
+export declare function resolveFrontendAsset(cwd: string, trusted: boolean, name: string, file: FrontendAssetFile): string | null;
+/** One plugin (either tier) with a built frontend bundle. */
+export interface FrontendBundle {
+    /** The manifest `name`: overlay = dir under `.claude4spec/plugins/`; workspace = npm package name. */
+    name: string;
+    /** Version from the package's `package.json`, or `'0.0.0'` if unreadable. */
+    version: string;
+    /** True when the bundle also ships a precompiled `dist/frontend.css`. */
+    hasCss: boolean;
+}
+/**
+ * Project-local plugins that ship a built `dist/frontend.js`, for the frontend
+ * manifest. Pure FS read; the caller gates by trust before calling (an
+ * untrusted project advertises nothing). A package without a built bundle is
+ * simply omitted — the build is the implementer's responsibility, not the host's.
+ */
+export declare function enumerateFrontendBundles(cwd: string): FrontendBundle[];
+/** Resolve an installed workspace plugin package's absolute root dir, or null. */
+export type WorkspaceRootResolver = (packageName: string) => string | null;
+/**
+ * Resolve the absolute path to stream for `GET /api/plugins/<name>/<file>` from a
+ * workspace/npm plugin, or `null` when the request must 404. UNGATED (a base
+ * install is trusted) — but `packageName` MUST be in `allowedPackages` (the
+ * resolved workspace plugin list), which both guards path traversal and bounds
+ * serving to actually-declared plugins. The JS path comes from the package's
+ * `exports['./frontend']` (fallback `dist/frontend.js`); CSS is its sibling
+ * `frontend.css`. Returns null when the package is unresolvable or the file is
+ * absent (a plugin without a built bundle simply serves nothing).
+ */
+export declare function resolveWorkspaceFrontendAsset(packageName: string, file: FrontendAssetFile, allowedPackages: readonly string[], resolveRoot?: WorkspaceRootResolver): string | null;
+/**
+ * Workspace/npm plugins that ship a resolvable built `frontend` entry, for the
+ * frontend manifest. UNGATED (parity with the backend base tier). A package
+ * without a built bundle (or unresolvable) is simply omitted. `resolveRoot` is a
+ * test seam — production passes the default `import.meta.resolve`-based resolver.
+ *
+ * `packageNames` is the resolved workspace allowlist, so every name is trusted by
+ * construction (the traversal guard in `resolveWorkspaceFrontendAsset` exists for
+ * the user-supplied route `:name`). Each package is resolved + its `package.json`
+ * read exactly ONCE here (this runs per `GET /frontend-manifest`).
+ */
+export declare function enumerateWorkspaceFrontendBundles(packageNames: readonly string[], resolveRoot?: WorkspaceRootResolver): FrontendBundle[];
+/** Content type for a served asset name, or `null` when the extension is not allowed. */
+export declare function assetContentType(asset: string): string | null;
+/**
+ * Overlay tier (trust-gated): resolve any allowlisted sibling of the project-local
+ * bundle at `<cwd>/.claude4spec/plugins/<name>/dist/<asset>`. Same gate + package
+ * guard as `resolveFrontendAsset`, generalized from the two fixed filenames.
+ */
+export declare function resolveOverlayAsset(cwd: string, trusted: boolean, name: string, asset: string): string | null;
+/**
+ * Workspace tier (ungated, allowlist-bounded): resolve any allowlisted sibling of
+ * a workspace/npm plugin's resolved `frontend` entry (i.e. files in the same
+ * `dist/` dir). Generalizes `resolveWorkspaceFrontendAsset` from the two fixed
+ * filenames so code-split chunks (`dto-*.js`) and source maps resolve.
+ */
+export declare function resolveWorkspaceAsset(packageName: string, asset: string, allowedPackages: readonly string[], resolveRoot?: WorkspaceRootResolver): string | null;

package/dist/server/core/plugin-host/frontend-assets.js

@@ -0,0 +1,262 @@
+/**
+ * M33 — plugin frontend assets, two tiers.
+ *
+ * The serving layer for "Option B" plugin frontends. This express-free module
+ * owns the single path/trust convention shared by the serving route
+ * (`routes/plugins.ts`) and the manifest builder (`frontend-manifest.ts`), so
+ * the two cannot diverge.
+ *
+ *   • Overlay tier (phase 2): a TRUSTED project ships a precompiled bundle at
+ *     `<cwd>/.claude4spec/plugins/<name>/dist/frontend.js` (+ optional
+ *     `frontend.css`). Gated by `trustProjectPlugins` (per workspace × project,
+ *     machine-local) — the CALLER resolves the gate and passes `trusted`; an
+ *     untrusted/undecided project emits nothing, exactly like the overlay loader
+ *     refuses to run untrusted project code.
+ *
+ *   • Workspace tier (phase 3): a workspace/npm plugin (declared in
+ *     `~/.claude4spec/workspaces.json`, installed under `node_modules`) serves
+ *     its own `dist/frontend.js` (+ optional `dist/frontend.css`) UNGATED — a
+ *     consciously-installed base package is trusted by virtue of npm install,
+ *     parity with the backend base tier. Traversal-guarded by the passed
+ *     workspace package allowlist (the same list `loadWorkspacePlugins` uses).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { enumerateOverlayPackages, projectPluginsDir, resolveExportsEntry, } from './overlay-loader.js';
+/** Read + parse a `package.json`, or `null` when missing/unreadable/invalid. */
+function readPackageJson(pkgJsonPath) {
+    try {
+        return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** A manifest's declared `version`, falling back to `'0.0.0'`. */
+function packageVersion(pkg) {
+    return pkg && typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+}
+/**
+ * Walk up from `startDir` to the NEAREST ancestor that owns a readable
+ * `package.json` — the package root — or `null` if none within 12 levels. The
+ * caller has already proved the package's identity (`import.meta.resolve`
+ * resolved a DECLARED subpath of `packageName`), so we deliberately do NOT gate
+ * on the manifest `name`: a workspace plugin whose install/dir name differs from
+ * its real (e.g. scoped) `package.json` `name` must still resolve to its root.
+ * The 12-level bound is a cheap runaway guard for a pathological deep tree.
+ */
+export function nearestPackageRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 12; i++) {
+        if (readPackageJson(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Absolute path of a plugin's precompiled `dist/<file>`. */
+function bundleAssetPath(cwd, name, file) {
+    return path.join(projectPluginsDir(cwd), name, 'dist', file);
+}
+/**
+ * Resolve the absolute path to stream for `GET /api/plugins/<name>/<file>`, or
+ * `null` when the request must 404. Returns null when:
+ *   - the trust gate is off (`!trusted`) — never emit project-committed code,
+ *   - `name` is not an actual overlay package — also guards path traversal, as
+ *     only directory names enumerated under `.claude4spec/plugins/` are eligible,
+ *   - the `dist/<file>` does not exist — a present, trusted project never
+ *     fabricates a bundle.
+ */
+export function resolveFrontendAsset(cwd, trusted, name, file) {
+    if (!trusted)
+        return null;
+    if (!enumerateOverlayPackages(cwd).includes(name))
+        return null;
+    const abs = bundleAssetPath(cwd, name, file);
+    return fs.existsSync(abs) ? abs : null;
+}
+/** Read an overlay package's declared version, falling back to `'0.0.0'`. */
+function readBundleVersion(cwd, name) {
+    return packageVersion(readPackageJson(path.join(projectPluginsDir(cwd), name, 'package.json')));
+}
+/**
+ * Project-local plugins that ship a built `dist/frontend.js`, for the frontend
+ * manifest. Pure FS read; the caller gates by trust before calling (an
+ * untrusted project advertises nothing). A package without a built bundle is
+ * simply omitted — the build is the implementer's responsibility, not the host's.
+ */
+export function enumerateFrontendBundles(cwd) {
+    const bundles = [];
+    for (const name of enumerateOverlayPackages(cwd)) {
+        if (!fs.existsSync(bundleAssetPath(cwd, name, 'frontend.js')))
+            continue;
+        bundles.push({
+            name,
+            version: readBundleVersion(cwd, name),
+            hasCss: fs.existsSync(bundleAssetPath(cwd, name, 'frontend.css')),
+        });
+    }
+    return bundles;
+}
+/**
+ * Default resolver. Two reasons `createRequire(...).resolve` is wrong here:
+ *   1. `require.resolve('<pkg>/package.json')` — a package with an `exports` map
+ *      blocks undeclared subpaths like `./package.json`; and
+ *   2. `require.resolve` uses CJS conditions (`require`/`node`/`default`), but a
+ *      modern plugin's `exports` is import-only (`{ types, import }`) ⇒ "No
+ *      exports main defined".
+ * So resolve a DECLARED ESM subpath with `import.meta.resolve` (which uses the
+ * `import` condition) — that resolution alone PROVES identity — then walk up to
+ * the nearest directory owning a `package.json` (the package root) via
+ * `nearestPackageRoot`. We do NOT re-check that `package.json`'s `name` equals
+ * the requested id: a plugin installed under an unscoped dir name whose real
+ * `name` is scoped (`@scope/pkg`) would otherwise never match and silently lose
+ * its frontend. Try `./frontend` first (the only subpath we serve), then `.`.
+ */
+const defaultWorkspaceRoot = (packageName) => {
+    let entryUrl;
+    for (const spec of [`${packageName}/frontend`, packageName]) {
+        try {
+            entryUrl = import.meta.resolve(spec);
+            break;
+        }
+        catch {
+            /* try the next entry specifier */
+        }
+    }
+    if (!entryUrl)
+        return null;
+    return nearestPackageRoot(path.dirname(fileURLToPath(entryUrl)));
+};
+/**
+ * The package's declared `./frontend` import target (relative to its root), or
+ * the `dist/frontend.js` convention when `exports` does not declare one. Reuses
+ * the overlay loader's condition handling so the two tiers can't drift.
+ */
+function workspaceFrontendEntryRel(pkg) {
+    const sub = pkg?.exports?.['./frontend'];
+    return resolveExportsEntry(sub) ?? 'dist/frontend.js';
+}
+/** Absolute path of a workspace package's `frontend.js`, given its parsed manifest. */
+function workspaceFrontendJs(root, pkg) {
+    return path.resolve(root, workspaceFrontendEntryRel(pkg));
+}
+/**
+ * Resolve the absolute path to stream for `GET /api/plugins/<name>/<file>` from a
+ * workspace/npm plugin, or `null` when the request must 404. UNGATED (a base
+ * install is trusted) — but `packageName` MUST be in `allowedPackages` (the
+ * resolved workspace plugin list), which both guards path traversal and bounds
+ * serving to actually-declared plugins. The JS path comes from the package's
+ * `exports['./frontend']` (fallback `dist/frontend.js`); CSS is its sibling
+ * `frontend.css`. Returns null when the package is unresolvable or the file is
+ * absent (a plugin without a built bundle simply serves nothing).
+ */
+export function resolveWorkspaceFrontendAsset(packageName, file, allowedPackages, resolveRoot = defaultWorkspaceRoot) {
+    if (!allowedPackages.includes(packageName))
+        return null;
+    const root = resolveRoot(packageName);
+    if (!root)
+        return null;
+    const frontendAbs = workspaceFrontendJs(root, readPackageJson(path.join(root, 'package.json')));
+    const abs = file === 'frontend.js' ? frontendAbs : path.join(path.dirname(frontendAbs), 'frontend.css');
+    return fs.existsSync(abs) ? abs : null;
+}
+/**
+ * Workspace/npm plugins that ship a resolvable built `frontend` entry, for the
+ * frontend manifest. UNGATED (parity with the backend base tier). A package
+ * without a built bundle (or unresolvable) is simply omitted. `resolveRoot` is a
+ * test seam — production passes the default `import.meta.resolve`-based resolver.
+ *
+ * `packageNames` is the resolved workspace allowlist, so every name is trusted by
+ * construction (the traversal guard in `resolveWorkspaceFrontendAsset` exists for
+ * the user-supplied route `:name`). Each package is resolved + its `package.json`
+ * read exactly ONCE here (this runs per `GET /frontend-manifest`).
+ */
+export function enumerateWorkspaceFrontendBundles(packageNames, resolveRoot = defaultWorkspaceRoot) {
+    const bundles = [];
+    for (const name of packageNames) {
+        const root = resolveRoot(name);
+        if (!root)
+            continue;
+        const pkg = readPackageJson(path.join(root, 'package.json'));
+        const frontendAbs = workspaceFrontendJs(root, pkg);
+        if (!fs.existsSync(frontendAbs))
+            continue;
+        bundles.push({
+            name,
+            version: packageVersion(pkg),
+            hasCss: fs.existsSync(path.join(path.dirname(frontendAbs), 'frontend.css')),
+        });
+    }
+    return bundles;
+}
+// ─── Generalized dist asset serving (native-ESM siblings) ───────────────────
+//
+// A plugin's `frontend.js` is served as native ESM (m33l5fe0 — the host does NOT
+// re-bundle), so its RELATIVE imports resolve against the module URL: a code-split
+// chunk `./dto-*.js` becomes `GET /api/plugins/<name>/dto-*.js`. Serving only
+// `frontend.js`/`frontend.css` (the original two-file enum) left those siblings
+// 404 and broke any code-split bundle (the first real plugin tripped on it). So
+// the host serves any allowlisted asset that physically sits next to the entry,
+// strictly contained in the bundle dir, under the SAME trust gating as the entry.
+/** Asset extensions a plugin bundle dir may serve, with their content types. */
+const ASSET_CONTENT_TYPE = {
+    '.js': 'text/javascript',
+    '.css': 'text/css',
+    '.map': 'application/json',
+};
+/** Content type for a served asset name, or `null` when the extension is not allowed. */
+export function assetContentType(asset) {
+    return ASSET_CONTENT_TYPE[path.extname(asset).toLowerCase()] ?? null;
+}
+/**
+ * Resolve a single flat `asset` strictly within `distDir`. Returns `null` (→ 404)
+ * on a disallowed extension, any path separator / traversal in the name, an
+ * escape outside `distDir`, or a missing file. Vite library output is flat
+ * (`frontend.js`, `dto-*.js`, `*.map` all in the bundle root), so a single
+ * path-segment name with no separators is exactly what a relative ESM import
+ * requests — and rejecting separators is the simplest sound traversal guard.
+ */
+function resolveWithinDist(distDir, asset) {
+    if (!assetContentType(asset))
+        return null;
+    if (asset.includes('/') || asset.includes('\\') || asset.includes('..'))
+        return null;
+    const abs = path.join(distDir, asset);
+    const rel = path.relative(distDir, abs);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return fs.existsSync(abs) ? abs : null;
+}
+/**
+ * Overlay tier (trust-gated): resolve any allowlisted sibling of the project-local
+ * bundle at `<cwd>/.claude4spec/plugins/<name>/dist/<asset>`. Same gate + package
+ * guard as `resolveFrontendAsset`, generalized from the two fixed filenames.
+ */
+export function resolveOverlayAsset(cwd, trusted, name, asset) {
+    if (!trusted)
+        return null;
+    if (!enumerateOverlayPackages(cwd).includes(name))
+        return null;
+    return resolveWithinDist(path.join(projectPluginsDir(cwd), name, 'dist'), asset);
+}
+/**
+ * Workspace tier (ungated, allowlist-bounded): resolve any allowlisted sibling of
+ * a workspace/npm plugin's resolved `frontend` entry (i.e. files in the same
+ * `dist/` dir). Generalizes `resolveWorkspaceFrontendAsset` from the two fixed
+ * filenames so code-split chunks (`dto-*.js`) and source maps resolve.
+ */
+export function resolveWorkspaceAsset(packageName, asset, allowedPackages, resolveRoot = defaultWorkspaceRoot) {
+    if (!allowedPackages.includes(packageName))
+        return null;
+    const root = resolveRoot(packageName);
+    if (!root)
+        return null;
+    const frontendAbs = workspaceFrontendJs(root, readPackageJson(path.join(root, 'package.json')));
+    return resolveWithinDist(path.dirname(frontendAbs), asset);
+}
+//# sourceMappingURL=frontend-assets.js.map

package/dist/server/core/plugin-host/frontend-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-assets.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/frontend-assets.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/frontend-manifest.d.ts

@@ -0,0 +1,33 @@
+/**
+ * M33: build the `GET /api/plugins/frontend-manifest` payload.
+ *
+ * Emits the fixed peer import map + host API version and the active plugins to
+ * boot ("Option B"). Two tiers feed `plugins[]` (see `buildFrontendManifest`):
+ * the workspace/npm tier (ungated, every project) and the project-local overlay
+ * tier (only when the primary project is trusted) — each pointing the client at
+ * the serving routes in `routes/plugins.ts`. No tiers active ⇒ `plugins: []`, so
+ * the import map + shim plumbing still stands up end-to-end with nothing to load.
+ */
+import type { FrontendManifestResponse } from '../../../shared/plugin-host/frontend-manifest.js';
+import { type WorkspaceRootResolver } from './frontend-assets.js';
+import type { PluginRegistry } from './types.js';
+/**
+ * Serving context for the process's primary project. Absent on workspace-only
+ * starts (nothing registered) ⇒ only workspace-tier frontends are advertised.
+ */
+export interface FrontendManifestServing {
+    cwd: string;
+    /** `trustProjectPlugins === true` for the primary project. Untrusted ⇒ no overlay plugins. */
+    trusted: boolean;
+}
+/**
+ * Build the boot manifest. `plugins[]` is base ∪ overlay:
+ *   • workspace tier (`workspacePackages`) — ALWAYS advertised, ungated (a base
+ *     npm install is trusted), present for every project of the process; and
+ *   • overlay tier — the primary project's project-local bundles, ONLY when that
+ *     project is trusted.
+ * De-duped by `name`: an overlay bundle overrides a workspace bundle of the same
+ * name (the project-local copy wins). CSS only when the bundle ships it, so a
+ * style-less plugin omits `css` and the client never fetches it.
+ */
+export declare function buildFrontendManifest(_registry: PluginRegistry, serving?: FrontendManifestServing, workspacePackages?: readonly string[], workspaceRootResolver?: WorkspaceRootResolver): FrontendManifestResponse;

package/dist/server/core/plugin-host/frontend-manifest.js

@@ -0,0 +1,52 @@
+/**
+ * M33: build the `GET /api/plugins/frontend-manifest` payload.
+ *
+ * Emits the fixed peer import map + host API version and the active plugins to
+ * boot ("Option B"). Two tiers feed `plugins[]` (see `buildFrontendManifest`):
+ * the workspace/npm tier (ungated, every project) and the project-local overlay
+ * tier (only when the primary project is trusted) — each pointing the client at
+ * the serving routes in `routes/plugins.ts`. No tiers active ⇒ `plugins: []`, so
+ * the import map + shim plumbing still stands up end-to-end with nothing to load.
+ */
+import { HOST_API_VERSION } from '../../../shared/plugin-host/manifest.js';
+import { buildImportMap } from './runtime-shims.js';
+import { enumerateFrontendBundles, enumerateWorkspaceFrontendBundles, } from './frontend-assets.js';
+/** One bundle → the manifest entry pointing at the (tier-agnostic) serving routes. */
+function toEntry(b) {
+    return {
+        name: b.name,
+        version: b.version,
+        entry: `/api/plugins/${b.name}/frontend.js`,
+        ...(b.hasCss ? { css: `/api/plugins/${b.name}/frontend.css` } : {}),
+    };
+}
+/**
+ * Build the boot manifest. `plugins[]` is base ∪ overlay:
+ *   • workspace tier (`workspacePackages`) — ALWAYS advertised, ungated (a base
+ *     npm install is trusted), present for every project of the process; and
+ *   • overlay tier — the primary project's project-local bundles, ONLY when that
+ *     project is trusted.
+ * De-duped by `name`: an overlay bundle overrides a workspace bundle of the same
+ * name (the project-local copy wins). CSS only when the bundle ships it, so a
+ * style-less plugin omits `css` and the client never fetches it.
+ */
+export function buildFrontendManifest(_registry, serving, workspacePackages = [], workspaceRootResolver) {
+    const byName = new Map();
+    for (const b of enumerateWorkspaceFrontendBundles(workspacePackages, workspaceRootResolver))
+        byName.set(b.name, toEntry(b));
+    if (serving?.trusted) {
+        for (const b of enumerateFrontendBundles(serving.cwd))
+            byName.set(b.name, toEntry(b));
+    }
+    const plugins = [...byName.values()];
+    // `importMap` is informational here (diagnostics / future non-head consumers).
+    // The AUTHORITATIVE copy the browser uses is injected server-side into the SPA
+    // `<head>` (see `injectImportMap` in server/index.ts) — both derive from the
+    // same `buildImportMap()`, so the two channels cannot diverge.
+    return {
+        hostApiVersion: HOST_API_VERSION,
+        importMap: buildImportMap(),
+        plugins,
+    };
+}
+//# sourceMappingURL=frontend-manifest.js.map

package/dist/server/core/plugin-host/frontend-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-manifest.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/frontend-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAK3E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,wBAAwB,EACxB,iCAAiC,GAGlC,MAAM,sBAAsB,CAAC;AAa9B,sFAAsF;AACtF,SAAS,OAAO,CAAC,CAAiB;IAChC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,KAAK,EAAE,gBAAgB,CAAC,CAAC,IAAI,cAAc;QAC3C,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAyB,EACzB,OAAiC,EACjC,oBAAuC,EAAE,EACzC,qBAA6C;IAE7C,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,iCAAiC,CAAC,iBAAiB,EAAE,qBAAqB,CAAC;QACzF,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;QACrB,KAAK,MAAM,CAAC,IAAI,wBAAwB,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,OAAO,GAA0B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5D,+EAA+E;IAC/E,+EAA+E;IAC/E,6EAA6E;IAC7E,+DAA+D;IAC/D,OAAO;QACL,cAAc,EAAE,gBAAgB;QAChC,SAAS,EAAE,cAAc,EAAE;QAC3B,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/server/core/plugin-host/loader.d.ts

@@ -0,0 +1,107 @@
+/**
+ * M33 plugin loader — the single mechanism that turns workspace-declared npm
+ * packages into registered host capabilities, run identically from every entry
+ * point (server, `c4s`, `c4s-mcp`, `c4s-reader`).
+ *
+ * Four steps, per package, each isolated in its own try/catch so a single bad
+ * plugin is skipped — never crashing the process:
+ *   1. Dynamic import      — `await import(pkg)` (native ESM).
+ *   2. Manifest extraction — `mod.manifest` or `mod.default`.
+ *   3. Validation gate     — hostApiVersion range + engines.node.
+ *   4. Registration        — `registry.registerPlugin(manifest)`.
+ */
+import type { PluginManifest } from '../../../shared/plugin-host/manifest.js';
+import { type PluginMigrationInfo } from '../../../shared/plugin-host/host-api.js';
+import type { PluginRegistry } from './types.js';
+/**
+ * `incompatible` (M33) is distinct from `skipped`: it means the package
+ * was built against an incompatible MAJOR Host API and carries a `migration`
+ * descriptor (a repair path), whereas `skipped` is an environment problem (an
+ * `engines` miss) with no migration path.
+ */
+export type PluginLoadStatus = 'loaded' | 'skipped' | 'incompatible' | 'failed';
+export type PluginLoadCode = 'PLUGIN_HOST_API_MISMATCH' | 'PLUGIN_ENGINE_UNSATISFIED' | 'PLUGIN_IMPORT_FAILED' | 'PLUGIN_INVALID_MANIFEST' | 'PLUGIN_TYPE_CONFLICT' | 'PLUGIN_PROJECT_UNTRUSTED';
+/** Which layer a record belongs to — base (workspace/npm) vs overlay (project-local). */
+export type PluginLayer = 'base' | 'overlay';
+/**
+ * Per-package outcome. Adds `layer` (base/overlay), `trust`, `origin`
+ * (project-local source path), and `shadows`/`shadowedTypes` — all optional so
+ * base records keep their shape.
+ */
+export interface PluginLoadRecord {
+    /** Source identifier: the npm package name, or a synthetic id for built-ins. */
+    package: string;
+    status: PluginLoadStatus;
+    /** Machine code for skipped/failed packages. */
+    code?: PluginLoadCode;
+    /** Human-readable explanation for skipped/failed packages. */
+    reason?: string;
+    manifestName?: string;
+    manifestVersion?: string;
+    /** Entity types this package contributed (only when `loaded`). */
+    contributedTypes?: string[];
+    /** Which layer this record came from (base/overlay). */
+    layer?: PluginLayer;
+    /** Trust state of the project-local layer (overlay only). */
+    trust?: 'trusted' | 'untrusted';
+    /** Source path under `<cwd>/.claude4spec/plugins/` (overlay only). */
+    origin?: string;
+    /**
+     * M33: present on `incompatible` records — the repair path (target
+     * Host API version, applicable migration descriptors, shim availability).
+     */
+    migration?: PluginMigrationInfo;
+}
+export interface PluginLoadResult {
+    records: PluginLoadRecord[];
+}
+/** Module importer — overridable in tests; defaults to native dynamic import. */
+export type PluginImporter = (specifier: string) => Promise<unknown>;
+/** Pull the `PluginManifest` off a freshly-imported module namespace. Shared by
+ * the workspace loader and the project-local overlay loader. */
+export declare function extractManifest(mod: unknown): PluginManifest | null;
+/** A structurally-valid manifest carries at least string `name` + `hostApiVersion`. */
+export declare function isValidManifestShape(manifest: PluginManifest | null): manifest is PluginManifest;
+/**
+ * Outcome of the compatibility gate. `status` lets the caller record an
+ * `incompatible` (major Host API mismatch — carries a `migration` repair path)
+ * distinctly from a `skipped` (host-api same-major miss, or an `engines` miss —
+ * environment problems with no migration path).
+ */
+export interface GateResult {
+    status: 'skipped' | 'incompatible';
+    code: PluginLoadCode;
+    reason: string;
+    migration?: PluginMigrationInfo;
+}
+/**
+ * Compatibility gate shared by all layers: hostApiVersion range + engines.node.
+ * Returns `null` when the manifest may register; otherwise the gate result.
+ * A MAJOR Host API mismatch → `incompatible` + a migration descriptor; an
+ * `engines` miss (or a same-major host-api miss) → `skipped`.
+ */
+export declare function gateManifest(manifest: PluginManifest): GateResult | null;
+/**
+ * Load and register the given workspace plugin packages onto `registry`.
+ * Returns one record per package for the diagnostics route. Never throws.
+ */
+export declare function loadWorkspacePlugins(registry: PluginRegistry, packageNames: string[], importer?: PluginImporter): Promise<PluginLoadResult>;
+/** Seams for `reloadPlugin` — overridable in tests. */
+export interface ReloadPluginOptions {
+    importer?: PluginImporter;
+    resolveEntry?: (pkg: string) => string | null;
+    cacheBust?: (entry: string) => string;
+}
+/**
+ * M33 — hot-reload pipeline for ONE base (workspace/npm) package.
+ *
+ * Atomicity: the failure modes the brief names "old stays" — import failure,
+ * missing manifest export, incompatible major — are all checked BEFORE any
+ * teardown, so the previously-registered version remains registered and the
+ * caller surfaces a warning. Only once a fresh, compatible manifest is in hand
+ * do we tear the old version down (`unregisterPlugin` → its `onUnregister`) and
+ * register the new one — the brief's "onUnregister old, then register new".
+ *
+ * Returns the per-package record (`loaded` / `skipped` / `failed`). Never throws.
+ */
+export declare function reloadPlugin(registry: PluginRegistry, pkg: string, opts?: ReloadPluginOptions): Promise<PluginLoadRecord>;