@inharness-ai/claude4spec 1.0.20 → 1.0.22

package/dist/shared/plugin-host/manifest.d.ts

@@ -0,0 +1,194 @@
+/**
+ * M33 — runtime plugin manifest contract.
+ *
+ * A plugin is an npm package that default-exports (or named-exports as
+ * `manifest`) a {@link PluginManifest}. The host loader (`loadWorkspacePlugins`)
+ * dynamic-imports each workspace-declared package, validates `hostApiVersion`
+ * / `engines`, then fans `contributes.entities` out to `registerEntityModule`.
+ *
+ * This lives in `shared/` (not `server/`) because the external `c4s-reader`
+ * and plugin authors need the contract without pulling in express /
+ * better-sqlite3. Server-only payloads (the express Router, the L9 serializer)
+ * are typed `unknown` here and narrowed server-side.
+ */
+import type { EntityModuleManifest, SystemPromptContribution } from './types.js';
+/**
+ * The Host API version this build advertises. Bumped on a breaking change to
+ * any surface counted into the contract: the manifest / EntityModule
+ * signatures, the `mountBackend(app, mcpHost, db, cwd)` mount-context shape,
+ * the chip/card/row prop shapes, the L8 editor registration contract, and the
+ * prop contracts of the `stable` Host UI Kit components (M34/L12;
+ * `@c4s/plugin-runtime/ui`). See `UI_KIT_STABLE_COMPONENTS` in
+ * `ui-kit-surface.ts`; `experimental` kit components are deliberately NOT part
+ * of this surface.
+ *
+ * A plugin whose `hostApiVersion` range does not satisfy this version is
+ * skipped with a warning (never crashed over) — on the backend during load and
+ * independently on the frontend during manifest consumption.
+ *
+ * Versioning rule — only a breaking slot-shape change bumps the version, and it
+ * bumps the MAJOR (with a descriptor in the changelog — see `host-api.ts`); the
+ * loader gate compares majors only. A plugin built against a different major is
+ * reported `incompatible` with a migration descriptor (vs the environment-level
+ * `skipped` for an `engines` miss).
+ *
+ * `1.0.0` baseline — the Host UI Kit catalog + `stable` prop contracts
+ * (`@c4s/plugin-runtime/ui`, M34/L12) shipped WITHIN this major, so they are
+ * folded into the `1.0.0` versioned surface rather than bumping it; no major has
+ * been crossed, so the changelog stays empty.
+ */
+export declare const HOST_API_VERSION = "1.0.0";
+/** Node/host engine constraints — checked by the loader before registration. */
+export interface PluginEngines {
+    /** semver range matched against `process.versions.node`. */
+    node?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Authoring shape for one contributed entity type. A superset of the shared
+ * {@link EntityModuleManifest} carrying the slots the host needs to lower it
+ * into a server `BackendModule`. The express Router (`backend.routes`) and the
+ * L9 serializer are typed `unknown` here so the shared bundle stays dep-free;
+ * the registry narrows them at registration time.
+ */
+export interface EntityContribution extends EntityModuleManifest {
+    /** L9 — JSON serializer (server `EntitySerializer<unknown>`; narrowed server-side). */
+    serializer: unknown;
+    /** M05 — system prompt contribution composed by buildSystemPrompt. */
+    systemPrompt: SystemPromptContribution;
+    backend?: {
+        /** Per-plugin idempotent SQL migrations (server `SqlMigration[]`). */
+        migrations?: unknown[];
+        /**
+         * Full-power imperative mount hook (server `PluginMountFn`). Receives the
+         * MountContext; owns service construction, route mounting, MCP + service
+         * registration. Takes precedence over `routes`.
+         */
+        mount?: unknown;
+        /**
+         * Sugar: a pre-built express Router mounted at `pathPrefix`. When supplied
+         * without `mount`, the registry synthesizes
+         * `mount = (ctx) => ctx.app.use(pathPrefix, routes)` — no MCP server, no
+         * entity service, no migrations.
+         */
+        routes?: unknown;
+    };
+    /** L8 — client editor extensions + render slots (narrowed client-side). */
+    frontend?: unknown;
+}
+/**
+ * Authoring shape for one contributed writing style (M15). A plugin carries the
+ * style inline (body + optional attached files) rather than dropping a SKILL.md
+ * dir on disk — discovery is by push at load time (the loader fans these into
+ * the per-project SkillRegistry as `source: "plugin"`), not by FS scan.
+ */
+export interface WritingStyleContribution {
+    /** Stable identifier; also the dedup key against bundled/user styles. */
+    slug: string;
+    title: string;
+    description: string;
+    /** Positive integer; mirrors SKILL.md frontmatter `version`. */
+    version: number;
+    language: 'en' | 'pl';
+    /** The skill body markdown (the SKILL.md content without frontmatter). */
+    content: string;
+    /** Optional attached files (templates/examples/workflows), keyed by rel path. */
+    files?: Record<string, string>;
+}
+/**
+ * M33 — one settings field a plugin renders in its own Settings section
+ * (panel M26), values stored under `config.plugins[<manifest.name>][key]`.
+ * `kind` drives the reload classification on write:
+ *   - `hot-reload` → only `invalidateQueries(['config'])`, no context rebuild
+ *     (parity with `writingStyle` / `language`; takes effect next turn/thread).
+ *   - `executive` → invalidates the `ProjectContext` (rebuild, no banner, no
+ *     restart).
+ */
+export interface PluginSettingField {
+    /** Stable field key inside the plugin's config namespace. */
+    key: string;
+    /** Human label shown in the Settings panel. */
+    label: string;
+    control: 'toggle' | 'text' | 'select' | 'multiselect';
+    kind: 'hot-reload' | 'executive';
+    /** Default applied when `config.plugins[<name>][key]` is absent. */
+    default: unknown;
+    /** Choices for `select` / `multiselect` controls. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Optional help/description text. */
+    help?: string;
+}
+/** A plugin's settings module = an ordered list of fields. */
+export type PluginSettingsModule = PluginSettingField[];
+/**
+ * M33 — declarative editor slash-command contributed by a plugin
+ * (typically an entity-less one). The loader normalizes each entry into an
+ * `EditorExtensionRegistration.slashCommand` and routes it through
+ * `registerEditorExtension(...)` — the SAME path as entity-borne extensions.
+ * Declarative, not imperative: the plugin declares the trigger + popover to
+ * open; execution is the editor framework's popover dispatch, not plugin code.
+ * Kept as a dep-free subset here (the full `EditorExtensionRegistration` lives
+ * client-side); `popoverKind` is narrowed against the client `PopoverMap`.
+ */
+export interface PluginCommandContribution {
+    /** Stable registration name (unique within the editor extension registry). */
+    name: string;
+    /** Slash trigger token, e.g. "mychart". */
+    trigger: string;
+    /** Menu label shown in the slash palette. */
+    label: string;
+    /** Popover kind dispatched on invoke (client `PopoverKind`). */
+    popoverKind: string;
+    /** Editor contexts the command is available in. Omitted = all contexts. */
+    availableIn?: string[];
+}
+/**
+ * The default export of a plugin package. `contributes` is the capability
+ * bundle: `contributes.entities`, `contributes.writingStyles` (pushed into the
+ * SkillRegistry as `source: "plugin"`), and
+ * `contributes.settings` / `contributes.commands`.
+ */
+export interface PluginManifest {
+    /** npm package name. */
+    name: string;
+    /** plugin semver. */
+    version: string;
+    /** semver range — which Host API the plugin targets, e.g. "^1.0.0". */
+    hostApiVersion: string;
+    /** node/host engine constraints. */
+    engines?: PluginEngines;
+    /**
+     * REQUIRED teardown hook, symmetric to backend mount — a required slot from
+     * the `1.0.0` baseline. The hot-reload pipeline calls it on the OLD version
+     * before registering the new one; without it a reload would leave duplicated
+     * slots (MCP server, Express routes, editor extensions, zustand slice). Must
+     * be idempotent and non-throwing — a thrown error is logged as a warning and
+     * never blocks the reload.
+     */
+    onUnregister(): void;
+    contributes: {
+        entities?: EntityContribution[];
+        /** M15 — writing styles contributed by this plugin. */
+        writingStyles?: WritingStyleContribution[];
+        /** M33 — settings fields rendered per-plugin in Settings (M26). */
+        settings?: PluginSettingsModule;
+        /** M33 — declarative editor slash-commands (entity-less plugins). */
+        commands?: PluginCommandContribution[];
+    };
+}
+/** One plugin's Settings section, as returned by `ProjectPluginHost.listSettings()`. */
+export interface PluginSettingsSection {
+    /** Plugin package name — also the `config.plugins` namespace key. */
+    name: string;
+    version: string;
+    fields: PluginSettingsModule;
+}
+/**
+ * Parse the major component of a clean semver string (e.g. "1.4.0" -> 1).
+ * Used for the cheap major-mismatch gate on the frontend, mirroring the
+ * backend's `semver.satisfies` check. Returns `null` for unparseable input.
+ */
+export declare function parseMajor(version: string): number | null;

package/dist/shared/plugin-host/manifest.js

@@ -0,0 +1,52 @@
+/**
+ * M33 — runtime plugin manifest contract.
+ *
+ * A plugin is an npm package that default-exports (or named-exports as
+ * `manifest`) a {@link PluginManifest}. The host loader (`loadWorkspacePlugins`)
+ * dynamic-imports each workspace-declared package, validates `hostApiVersion`
+ * / `engines`, then fans `contributes.entities` out to `registerEntityModule`.
+ *
+ * This lives in `shared/` (not `server/`) because the external `c4s-reader`
+ * and plugin authors need the contract without pulling in express /
+ * better-sqlite3. Server-only payloads (the express Router, the L9 serializer)
+ * are typed `unknown` here and narrowed server-side.
+ */
+/**
+ * The Host API version this build advertises. Bumped on a breaking change to
+ * any surface counted into the contract: the manifest / EntityModule
+ * signatures, the `mountBackend(app, mcpHost, db, cwd)` mount-context shape,
+ * the chip/card/row prop shapes, the L8 editor registration contract, and the
+ * prop contracts of the `stable` Host UI Kit components (M34/L12;
+ * `@c4s/plugin-runtime/ui`). See `UI_KIT_STABLE_COMPONENTS` in
+ * `ui-kit-surface.ts`; `experimental` kit components are deliberately NOT part
+ * of this surface.
+ *
+ * A plugin whose `hostApiVersion` range does not satisfy this version is
+ * skipped with a warning (never crashed over) — on the backend during load and
+ * independently on the frontend during manifest consumption.
+ *
+ * Versioning rule — only a breaking slot-shape change bumps the version, and it
+ * bumps the MAJOR (with a descriptor in the changelog — see `host-api.ts`); the
+ * loader gate compares majors only. A plugin built against a different major is
+ * reported `incompatible` with a migration descriptor (vs the environment-level
+ * `skipped` for an `engines` miss).
+ *
+ * `1.0.0` baseline — the Host UI Kit catalog + `stable` prop contracts
+ * (`@c4s/plugin-runtime/ui`, M34/L12) shipped WITHIN this major, so they are
+ * folded into the `1.0.0` versioned surface rather than bumping it; no major has
+ * been crossed, so the changelog stays empty.
+ */
+export const HOST_API_VERSION = '1.0.0';
+/**
+ * Parse the major component of a clean semver string (e.g. "1.4.0" -> 1).
+ * Used for the cheap major-mismatch gate on the frontend, mirroring the
+ * backend's `semver.satisfies` check. Returns `null` for unparseable input.
+ */
+export function parseMajor(version) {
+    const match = /^\s*v?(\d+)\./.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    return Number.isFinite(major) ? major : null;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/shared/plugin-host/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/shared/plugin-host/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AA8JxC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}

package/dist/shared/plugin-host/ui-kit-surface.d.ts

@@ -0,0 +1,22 @@
+/**
+ * M34 / L12 ↔ L11 — the versioned slice of the Host UI Kit.
+ *
+ * React-free so both the server (`server/plugin-runtime/ui.ts`) and the version
+ * surface (`host-api.ts`) can reference it without importing the client catalog
+ * (which pulls in React). The client catalog (`client/host-ui-kit/registry.ts`)
+ * derives the SAME stable set from the components' field-level `stability`
+ * constants; a test asserts the two agree, so this list can't silently drift
+ * from the actual components.
+ */
+/** Per-component stability tier. */
+export type Stability = 'stable' | 'experimental';
+/**
+ * The catalog components whose prop contracts are part of the versioned
+ * `hostApiVersion` surface — the `stable` (Core) tier only. A breaking
+ * prop-shape change to any of these requires a major `hostApiVersion` bump + a
+ * `migrations[]` descriptor (see {@link file://./host-api.ts}). `experimental`
+ * components are exposed by `/ui` but excluded from the surface; promoting one
+ * to `stable` adds it here.
+ */
+export declare const UI_KIT_STABLE_COMPONENTS: readonly ["EntityListHeader", "DetailPanelShell", "FieldRow", "FieldGrid"];
+export type StableUiKitComponent = (typeof UI_KIT_STABLE_COMPONENTS)[number];

package/dist/shared/plugin-host/ui-kit-surface.js

@@ -0,0 +1,25 @@
+/**
+ * M34 / L12 ↔ L11 — the versioned slice of the Host UI Kit.
+ *
+ * React-free so both the server (`server/plugin-runtime/ui.ts`) and the version
+ * surface (`host-api.ts`) can reference it without importing the client catalog
+ * (which pulls in React). The client catalog (`client/host-ui-kit/registry.ts`)
+ * derives the SAME stable set from the components' field-level `stability`
+ * constants; a test asserts the two agree, so this list can't silently drift
+ * from the actual components.
+ */
+/**
+ * The catalog components whose prop contracts are part of the versioned
+ * `hostApiVersion` surface — the `stable` (Core) tier only. A breaking
+ * prop-shape change to any of these requires a major `hostApiVersion` bump + a
+ * `migrations[]` descriptor (see {@link file://./host-api.ts}). `experimental`
+ * components are exposed by `/ui` but excluded from the surface; promoting one
+ * to `stable` adds it here.
+ */
+export const UI_KIT_STABLE_COMPONENTS = [
+    'EntityListHeader',
+    'DetailPanelShell',
+    'FieldRow',
+    'FieldGrid',
+];
+//# sourceMappingURL=ui-kit-surface.js.map

package/dist/shared/plugin-host/ui-kit-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-kit-surface.js","sourceRoot":"","sources":["../../../src/shared/plugin-host/ui-kit-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kBAAkB;IAClB,kBAAkB;IAClB,UAAU;IACV,WAAW;CACH,CAAC"}

package/dist/shared/types.d.ts

@@ -85,6 +85,11 @@ export type WsEvent = {
     ts: number;
 } | {
     kind: 'project:disposed';
+} | {
+    kind: 'plugin:reloaded';
+    name: string;
+    version: string;
+    tier: 'base' | 'overlay';
 };
 /** M02 multidir: discriminator dla source-of-truth (pagesDir / briefsDir / patchesDir). */
 export type PagesRootDir = 'pages' | 'briefs' | 'patches';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inharness-ai/claude4spec",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Plan the whole system before your agent writes a line of code. Local-first planning layer with structured entities and typed relations.",
   "license": "MIT",
   "author": "Mike Tomala <mike@inharness.ai>",
@@ -38,15 +38,28 @@
     "c4s": "dist/bin/c4s.js",
     "c4s-mcp": "dist/bin/c4s-mcp.js"
   },
+  "exports": {
+    "./package.json": "./package.json",
+    "./plugin-runtime": {
+      "types": "./dist/plugin-types/plugin-runtime.d.ts"
+    },
+    "./plugin-runtime/ui": {
+      "types": "./dist/plugin-types/ui.d.ts"
+    },
+    "./plugin-runtime/ambient": {
+      "types": "./dist/plugin-types/ambient.d.ts"
+    }
+  },
   "scripts": {
     "dev": "tsx watch src/bin/claude4spec.ts --mode dev",
     "dev:sandbox": "tsx watch src/bin/claude4spec.ts --mode dev --cwd .claude/skills/specyfikacja --pages .",
     "c4s": "tsx src/bin/c4s.ts",
     "build:server": "tsc -p tsconfig.server.json && rm -rf dist/server/db/migrations && cp -R src/server/db/migrations dist/server/db/migrations && rm -rf dist/server/skills && cp -R src/server/skills dist/server/skills && chmod +x dist/bin/claude4spec.js dist/bin/c4s.js dist/bin/c4s-mcp.js",
     "build:client": "vite build",
-    "build": "npm run build:client && npm run build:server",
+    "build:types": "tsc -p tsconfig.types.json && cp src/plugin-types/ambient.d.ts dist/plugin-types/ambient.d.ts",
+    "build": "npm run build:client && npm run build:server && npm run build:types",
     "start": "node dist/bin/claude4spec.js",
-    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.types.json --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -78,6 +91,7 @@
     "@tiptap/suggestion": "^2.27.2",
     "@types/diff": "^7.0.2",
     "better-sqlite3": "^11.7.0",
+    "@inharness-ai/c4s-plugin-simple-database-tables": "^0.1.0",
     "chokidar": "^4.0.3",
     "diff": "^9.0.0",
     "express": "^4.21.2",
@@ -91,6 +105,7 @@
     "react-markdown": "^9.1.0",
     "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
+    "semver": "^6.3.1",
     "tar": "^7.5.15",
     "tiptap-markdown": "^0.8.10",
     "ws": "^8.18.0",

package/dist/client/assets/channel-CTF_J4I4.js

@@ -1 +0,0 @@
-import{ai as o,aj as n}from"./mermaid.core-CMX3GAvM.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/client/assets/classDiagram-4FO5ZUOK-Dt9RLC8r.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-BpxYq7ab.js";import{_ as i}from"./mermaid.core-CMX3GAvM.js";import"./chunk-FMBD7UC4-4sXokGgd.js";import"./chunk-ND2GUHAM-DYQOCE5T.js";import"./chunk-55IACEB6-CeHg_yjT.js";import"./chunk-2J33WTMH-ChycTonk.js";import"./index-DnLELaLA.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/client/assets/classDiagram-v2-Q7XG4LA2-Dt9RLC8r.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-BpxYq7ab.js";import{_ as i}from"./mermaid.core-CMX3GAvM.js";import"./chunk-FMBD7UC4-4sXokGgd.js";import"./chunk-ND2GUHAM-DYQOCE5T.js";import"./chunk-55IACEB6-CeHg_yjT.js";import"./chunk-2J33WTMH-ChycTonk.js";import"./index-DnLELaLA.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};