@snap-rail/plugin-kit 0.0.0-stage → 0.2.0

package/lib/types/pack.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Final-format assembly: turn a built plugin package into the file set of
+ * its installable zip. The zip is **the release artifact, not the source
+ * tree** — a trimmed manifest whose `main` names the host face (or, for
+ * `clientOnly` packages, the client bundle), the built faces themselves, and
+ * an `exports` map covering the subpaths pool-resident importers resolve
+ * (`./contract` and friends). The settings page's 安装插件, the CLI packer,
+ * the feed publishers, and the offline combo assembler all consume the same
+ * shape.
+ *
+ * @module @snap-rail/plugin-kit/pack
+ */
+import { type SeedAbi } from './seeds.ts';
+/** The manifest fields the release manifest carries over from the source. */
+interface SourceManifest {
+    name?: unknown;
+    version?: unknown;
+    description?: unknown;
+    snapRail?: {
+        clientOnly?: unknown;
+        client?: {
+            entry?: unknown;
+        } | undefined;
+    } & Record<string, unknown>;
+}
+/** What one plugin package ships: its host face directory and (optionally)
+ * the built client bundle directory (the bundle plus emitted assets). */
+export interface ReleaseSpec {
+    /** The package's npm name; must match the source manifest. */
+    name: string;
+    /** Absolute package directory (the workspace package at pack time). */
+    dir: string;
+    /** Directory inside the package holding the built host face — included
+     * wholesale (multi-entry builds emit shared chunks beside the entries).
+     * Declarations, source maps, and tsbuildinfo files never ship. Required
+     * with `hostFace`. */
+    hostDir?: string | undefined;
+    /** Path inside the package of the host face entry — becomes the manifest
+     * `main` (the pool mounts exactly one host entry per package). Omitted for
+     * `snapRail.clientOnly` packages (renderer-only; `main` names the client
+     * bundle instead). */
+    hostFace?: string | undefined;
+    /** Directory inside the package holding the built client bundle and its
+     * assets; required iff the manifest declares `snapRail.client`. */
+    clientFace?: string | undefined;
+    /** Extra subpath exports the release manifest carries beyond `.` (e.g.
+     * `'./contract' → 'lib/contract.js'`), so pool-resident importers and the
+     * resolve-hooks pool fallback can bind them. Targets must ship. */
+    exports?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Derive the release manifest: the npm identity plus `main` plus the trimmed
+ * `exports` map. Everything else (scripts, dev dependencies) is workspace
+ * plumbing the pool never reads and the zip never carries. A stamped seed
+ * ABI merges into `snapRail.client` — the build-truth declaration replaces
+ * anything a source manifest may have carried.
+ *
+ * @param source - the parsed source `package.json`.
+ * @param main - the entry the manifest `main` names.
+ * @param exports - subpath exports beyond `.`; the root voice is always
+ *   included.
+ * @param seedAbi - the pack-time seed-contract stamp for client faces.
+ * @returns the manifest serialized for the zip root.
+ */
+export declare function releaseManifest(source: SourceManifest, main: string, exports?: Readonly<Record<string, string>>, seedAbi?: SeedAbi | undefined): string;
+/**
+ * Assemble one package's release file set: the release manifest, the declared
+ * faces, and the exports targets. Fails loud when the source manifest drifts
+ * from the spec or a declared face is missing on disk, so a broken build can
+ * never ship as a plausible zip.
+ *
+ * @param spec - what the package ships and from where.
+ * @returns the zip's files, keyed by package-relative path.
+ */
+export declare function releaseFiles(spec: ReleaseSpec): Promise<Record<string, Uint8Array>>;
+/** The zip file name a package's release takes under dist-plugins/. */
+export declare function zipFileName(packageName: string): string;
+export {};
+//# sourceMappingURL=pack.d.ts.map

package/lib/types/recipe.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The combo (recipe) document shipped inside an offline combo archive: the
+ * exact `plugins.yml` row shape plus the combination's identity. The archive
+ * itself is a plain zip — `recipe.yml` at the root, one signed plugin zip per
+ * referenced package under `plugins/` — so an offline terminal can install a
+ * whole scenario without any feed request.
+ *
+ * @module @snap-rail/plugin-kit/recipe
+ */
+import { z } from 'zod';
+/** One combo row: exactly the user-layer row shape, strict. */
+export declare const recipeRowSchema: z.ZodObject<{
+    name: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    config: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+/** A combo package's document: identity + the rows the preset carries. */
+export declare const recipeDocumentSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    title: z.ZodString;
+    kind: z.ZodEnum<{
+        base: "base";
+        scenario: "scenario";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    plugins: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        config: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** One parsed combo row. */
+export type RecipeRow = z.output<typeof recipeRowSchema>;
+/** One parsed combo document. */
+export type RecipeDocument = z.output<typeof recipeDocumentSchema>;
+/**
+ * The real package names a combo references, deduplicated in document order.
+ * A subpath row (`@snap-rail/equipment/rpc`) addresses the package
+ * `@snap-rail/equipment`; the combo archive carries one zip per package.
+ *
+ * @param document - the parsed combo document.
+ * @returns unique package names in first-reference order.
+ */
+export declare function recipePackageNames(document: RecipeDocument): string[];
+/**
+ * The npm package a row belongs to (`@scope/pkg/sub` → `@scope/pkg`).
+ *
+ * @param name - a package name or subpath entry.
+ * @returns the package name.
+ */
+export declare function packageNameOf(name: string): string;
+//# sourceMappingURL=recipe.d.ts.map

package/lib/types/seeds.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The renderer's shared-module vocabulary, in two tiers.
+ *
+ * `SEED_MODULES` is the **base tier**: the ids the shell itself seeds (by
+ * importing them statically into the app bundle) and parity-checks at boot.
+ * Everything a client bundle `require`s beyond this list must either be
+ * bundled in or contributed (below). Cross-plugin value imports are
+ * forbidden (collaboration goes through cordis services and slots); spine
+ * contract faces (`./contract` — zod + types only) and pure utility faces
+ * qualify; package host entries never do — the node side (store, drizzle,
+ * node:sqlite) must stay out of the client graph. Adding a base id is a
+ * spine decision.
+ *
+ * `CONTRIBUTED_SEED_MODULES` is the **installed tier**: ids that arrive with
+ * an installed plugin's client face (the framework's primitives, an
+ * extension pack's components). The provider's client entry default-exports
+ * a `seeds` map (`{ seeds: { ui: namespace, … } }`); the shell requires the
+ * face once and seeds every `<package>/<key>` id from that map, so every
+ * consumer shares the provider's single instances. The shell never seeds
+ * these itself — an absent provider simply leaves the ids unseeded and
+ * dependent faces skip with a load error instead of mounting half a UI.
+ *
+ * `CLIENT_EXTERNALS` (the union) is the external surface client bundles
+ * build against: the plugin-kit's client preset externalizes exactly these
+ * ids.
+ *
+ * @module @snap-rail/plugin-kit/seeds
+ */
+/** Module ids the shell seeds and every client bundle may require. */
+export declare const SEED_MODULES: readonly string[];
+/**
+ * Module ids installed plugins contribute through their client face's
+ * `seeds` map — the framework tier: every face of an installed UI framework
+ * (primitives, slot registry, runtime, fallback) serves as a shared
+ * instance for the components bound to it. The equipment wire contract
+ * rides the base tier instead — it is the station platform's API surface,
+ * not an installed framework's; a scenario's own contract stays inside its
+ * suite package. A third-party framework contributes its own ids; this
+ * list covers the in-repo builds.
+ */
+export declare const CONTRIBUTED_SEED_MODULES: readonly string[];
+/** The full external surface for in-repo client-bundle builds. */
+export declare const CLIENT_EXTERNALS: readonly string[];
+/**
+ * The seed contract's ABI revision. Bump when the contract between the
+ * shell's seed table and client bundles changes shape — interop semantics,
+ * a seed id's export shape. Packs stamp every client face with the revision
+ * it was built against (`snapRail.client.seedAbi`); the shell refuses a
+ * face stamped with a foreign revision instead of letting it crash the
+ * renderer (r1 exists because a seed default-import compiled to a namespace
+ * where the author meant a class — the shape must be checkable).
+ */
+export declare const SEED_ABI_REVISION = 1;
+/** What a client face declares about the seed table it was built against. */
+export interface SeedAbi {
+    /** The contract revision the face was built against. */
+    revision: number;
+    /** Base-package versions of the seeds the bundle requires, by seed id. */
+    versions: Record<string, string>;
+}
+/** The verdict of comparing a face's declaration against the live table. */
+export interface SeedAbiVerdict {
+    /** Whether the face may load. */
+    ok: boolean;
+    /** The face carries no declaration — the grace-window pass. */
+    undeclared: boolean;
+    /** Human-readable refusal reason; absent when `ok`. */
+    reason?: string;
+}
+/**
+ * Compare a client face's stamped seed ABI against the live table. Only the
+ * ids present in BOTH maps are compared (a stamp covers exactly what its
+ * build could resolve): the revision must match exactly, every shared
+ * version must agree on the major. An absent declaration passes — zips
+ * predating the stamping stay installable, marked for the caller to log.
+ */
+export declare function checkSeedAbi(declared: SeedAbi | undefined, host: SeedAbi): SeedAbiVerdict;
+//# sourceMappingURL=seeds.d.ts.map

package/lib/types/sign.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Release metadata and Ed25519 signatures for installable plugins.
+ *
+ * The signature covers a canonical release manifest. The manifest contains a
+ * digest for every payload file, so the verifier authenticates both the
+ * publisher and the bytes that will be installed without signing the zip
+ * container itself.
+ *
+ * @module @snap-rail/plugin-kit/sign
+ */
+import { type KeyObject } from 'node:crypto';
+/** The metadata file embedded in a release archive. */
+export declare const RELEASE_METADATA_PATH = "META-INF/release.json";
+/** The signature envelope embedded in a release archive. */
+export declare const RELEASE_SIGNATURE_PATH = "META-INF/signature.json";
+/** A release manifest's file digest table. */
+export interface ReleaseFileDigests {
+    readonly [path: string]: string;
+}
+/** Signed metadata carried by one plugin release. */
+export interface ReleaseMetadata {
+    format: 1;
+    name: string;
+    version: string;
+    publisher?: string;
+    createdAt: string;
+    files: ReleaseFileDigests;
+}
+/** The detached signature envelope carried by one plugin release. */
+export interface ReleaseSignature {
+    algorithm: 'Ed25519';
+    keyId: string;
+    signedFile: typeof RELEASE_METADATA_PATH;
+    signature: string;
+}
+/** A trusted public key indexed by the publisher's stable key id. */
+export interface TrustedReleaseKey {
+    keyId: string;
+    publicKey: KeyObject | string | Uint8Array;
+    publisher?: string;
+}
+/** Stable JSON serialization used as the Ed25519 signing input. */
+export declare function canonicalJson(value: unknown): string;
+/** SHA-256 digest of one payload file. */
+export declare function sha256(data: Uint8Array): string;
+/**
+ * Build signed metadata from a release file set. Metadata and signature files
+ * are excluded from the digest table so signing never becomes recursive.
+ */
+export declare function releaseMetadata(files: Readonly<Record<string, Uint8Array>>, options: {
+    name: string;
+    version: string;
+    publisher?: string;
+    createdAt?: string;
+}): ReleaseMetadata;
+/** Sign release metadata with an Ed25519 private key. */
+export declare function signReleaseMetadata(metadata: ReleaseMetadata, key: {
+    keyId: string;
+    privateKey: KeyObject | string | Uint8Array;
+}): ReleaseSignature;
+/** Add signed metadata and signature files to a release file set. */
+export declare function signReleaseFiles(files: Readonly<Record<string, Uint8Array>>, options: {
+    name: string;
+    version: string;
+    keyId: string;
+    privateKey: KeyObject | string | Uint8Array;
+    publisher?: string;
+    createdAt?: string;
+}): Record<string, Uint8Array>;
+/** Verify release metadata, signature and every payload file digest. */
+export declare function verifyReleaseFiles(files: Readonly<Record<string, Uint8Array>>, trustedKeys: readonly TrustedReleaseKey[]): ReleaseMetadata;
+//# sourceMappingURL=sign.d.ts.map

package/lib/types/slot-vocabulary.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Authoring helper for UI framework packages: define the package's slot
+ * vocabulary in one place and get a runtime membership guard for it. A
+ * vocabulary is plain data — a `shell.menu`-style dotted id table plus the
+ * reserved `custom:<publisher>.<name>` extension namespace — and every
+ * consumer (components, layouts) checks membership through the returned
+ * guard instead of hand-rolled string tests. Ids are declared with an
+ * `as const` object so consumers get autocomplete and compile-time
+ * misspelling errors from the literal-union type (`SlotIdOf`).
+ *
+ * The shipped framework (@snap-rail/framework-shadcn) implements the same
+ * contract inline (`UI_SLOT_IDS`/`isValidUiSlotId`); new frameworks start
+ * here.
+ *
+ * @module @snap-rail/plugin-kit/slot-vocabulary
+ */
+/** The reserved extension namespace: a custom slot is owned by a publisher. */
+export declare const CUSTOM_SLOT_PATTERN: RegExp;
+/** The slot id union of a vocabulary: its declared ids plus `custom:` seats. */
+export type SlotIdOf<T extends Record<string, string>> = T[keyof T] | `custom:${string}`;
+export interface SlotVocabulary<T extends Record<string, string>> {
+    /** The frozen id table (e.g. `{ menu: 'shell.menu', titlebar: 'shell.titlebar' }`). */
+    readonly ids: T;
+    /** Membership guard: the declared vocabulary plus `custom:` seats. */
+    isSlotId(value: string): value is SlotIdOf<T>;
+}
+/** Define and validate a framework's slot vocabulary. Malformed ids throw at
+ * definition time — a vocabulary ships once and is consumed everywhere, so
+ * it fails loudly in the framework author's build, never in a component. */
+export declare function defineSlotVocabulary<const T extends Record<string, string>>(ids: T, options?: {
+    customPattern?: RegExp;
+}): SlotVocabulary<T>;
+//# sourceMappingURL=slot-vocabulary.d.ts.map

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@snap-rail/plugin-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "The plugin author's kit: snapRail manifest vocabulary, the renderer seed whitelist, and tsdown presets for installable host + client faces",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./manifest": {
+      "types": "./lib/types/manifest.d.ts",
+      "default": "./lib/manifest.js"
+    },
+    "./seeds": {
+      "types": "./lib/types/seeds.d.ts",
+      "default": "./lib/seeds.js"
+    },
+    "./build": {
+      "types": "./lib/types/build.d.ts",
+      "default": "./lib/build.js"
+    },
+    "./pack": {
+      "types": "./lib/types/pack.d.ts",
+      "default": "./lib/pack.js"
+    },
+    "./sign": {
+      "types": "./lib/types/sign.d.ts",
+      "default": "./lib/sign.js"
+    },
+    "./recipe": {
+      "types": "./lib/types/recipe.d.ts",
+      "default": "./lib/recipe.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@snap-rail/util": "^0.1.2"
+  },
+  "peerDependencies": {
+    "tsdown": "^0.22.2"
+  },
+  "devDependencies": {
+    "rolldown": "^1.2.5",
+    "tsdown": "^0.22.2"
+  },
+  "snapRail": {
+    "layer": "base"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.