@xemahq/kernel-contracts 0.1.0 → 0.2.1

package/src/project-kit/lib/project-kit.ts

@@ -0,0 +1,227 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Project Kit — attachable, installable units for interactive sessions.
+//
+// A "project kit" is a named, typed, reusable unit that, when attached to a
+// project, gets INSTALLED INTO that project's repo/workspace when an
+// interactive session starts. Unlike a workspace mount (platform-side,
+// ephemeral), a kit is a DURABLE mutation the project carries forward on its
+// own — e.g. an npm dependency that lands in `package.json` + lockfile and is
+// committed, so cloning the repo later and running `npm install` reproduces it.
+//
+// Pure types + enums, zero domain knowledge and zero runtime deps. The catalog
+// lives in `llm-registry-api`; the per-session binding rides `customConfig`;
+// the npm-specific install is the agent-session-api `provision` phase's job
+// (a guard-gated EQUIP step synthesized per kit). This contract only knows
+// the closed shape of a kit, not how any one session type applies it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * HOW a project kit is installed into the target project. Closed,
+ * platform-owned set.
+ *
+ * `NpmDependency` installs a package (registry or git source) — the produced
+ * file mutation is a `dependencies` entry in `package.json` + lockfile.
+ *
+ * `ShadcnRegistry` is a codegen-style install: the shadcn CLI copies component
+ * SOURCE FILES into the project (typically `src/components/ui/<name>.tsx`)
+ * plus a `components.json` config and small `lib/utils.ts` helper. Resulting
+ * components ARE the project's own code — they are not imported from a library.
+ * Distinct from `NpmDependency` because the install mechanism (`npx shadcn
+ * init` + `add`), the produced file shape, and the agent's mental model are
+ * fundamentally different. The two are mutually exclusive per project.
+ *
+ * `FileTree` and `CodeSnippet` remain reserved — adding either is a deliberate
+ * platform change (a new applicator interpretation in the consuming session
+ * type), not a biome extension. The enum stays the single seam.
+ */
+export enum ProjectKitKind {
+  /** An npm package added to a project's `package.json` (registry or git source). */
+  NpmDependency = 'npm-dependency',
+  /** A shadcn-style codegen kit: CLI copies component source files into the repo. */
+  ShadcnRegistry = 'shadcn-registry',
+}
+
+/**
+ * WHAT a kit is, from the code-producing agent's point of view. Drives
+ * whether the agent receives an enrichment skill.
+ *
+ * `ComponentLibrary` is a "known concept" — the agent should build WITH it,
+ * so the kit carries an `enrichmentSkillSlug`. `GenericDependency` is a plain
+ * library the agent simply sees in `package.json`; no extra instruction.
+ */
+export enum ProjectKitPurpose {
+  ComponentLibrary = 'component-library',
+  GenericDependency = 'generic-dependency',
+}
+
+/**
+ * Where a kit's payload comes from. The semantics depend on the kit kind:
+ *
+ * - For `NpmDependency` kits: `NpmRegistry` resolves a `package@versionRange`
+ *   against an npm registry; `Git` resolves `git+<url>#<ref>` directly.
+ * - For `ShadcnRegistry` kits: `ShadcnRegistry` carries the shadcn-CLI config
+ *   (style, baseColor, components list, optional custom registry URLs).
+ *
+ * Cross-kind sources are rejected by the resolver — e.g. an `NpmDependency`
+ * kit cannot carry a `ShadcnRegistry` source, and vice versa. This is enforced
+ * at parse time, not at install time, so the failure is loud.
+ */
+export enum ProjectKitSourceKind {
+  /** Resolved from an npm registry (the public registry, or a scoped private one). */
+  NpmRegistry = 'npm-registry',
+  /** Resolved directly from a git repository (`npm install git+https://…#ref`). */
+  Git = 'git',
+  /** A shadcn-CLI config: registry URL, baseline component list, style + theme. */
+  ShadcnRegistry = 'shadcn-registry',
+}
+
+/**
+ * Tier of visibility for a kit and the registry namespace it pulls from. Carried on
+ * every `ResolvedProjectKit` so the install path can enforce tenant isolation
+ * at the wire layer (System / System-shareable / Org tiers in our hosted npm
+ * + container registries) and the FE can render the right badge.
+ *
+ * Precedence:
+ *   `System`            — only the platform writes AND reads (kernel-internal kits).
+ *                         Never selectable by org users; rejected by the catalog
+ *                         endpoint unless the caller has the platform role.
+ *   `SystemShareable`   — only the platform writes; ANY org reads. Curated kits
+ *                         shipped by Xema (`xema-component-library`, future
+ *                         `@xema/shadcn-presets`). Anonymous-read on our registries.
+ *   `Org`               — the org owns push + pull. Custom kits that point at a
+ *                         private package or git repo bound to the caller's org.
+ *                         Cross-org reads structurally impossible (JWT `x_org_id`
+ *                         scope at the registry layer).
+ *   `External`          — registries the platform does not host. ACLs are
+ *                         whatever the external system enforces (npmjs public,
+ *                         GH Packages private, etc.). Token resolution rides
+ *                         the existing wallet model.
+ *
+ * The order in the enum reflects "most platform-restricted" → "least platform-
+ * controlled" — useful for sorting in the catalog UI.
+ */
+export enum RegistryVisibilityTier {
+  System = 'system',
+  SystemShareable = 'system-shareable',
+  Org = 'org',
+  External = 'external',
+}
+
+/**
+ * Auth for a private kit source. The token itself is NEVER stored on the kit
+ * — it lives in a wallet. At session start the bootstrap resolves `walletName`
+ * and injects that wallet's entries as worker env vars; `tokenEnvVar` names
+ * the entry holding the registry/git token. The scaffolder references
+ * `${tokenEnvVar}` from `.npmrc` / git config so npm interpolates the token at
+ * install time and the raw token is never written into the committed repo.
+ */
+export interface ProjectKitAuth {
+  /** Name of the wallet (project- or org-scoped) that holds the token. */
+  readonly walletName: string;
+  /** Env-var key, within the resolved wallet, that holds the auth token. */
+  readonly tokenEnvVar: string;
+}
+
+/**
+ * A package resolved from an npm registry. For the public registry, only
+ * `package` + `versionRange` are set. For a scoped private registry,
+ * `registryUrl` + `scope` declare the registry and `auth` points at the wallet
+ * entry holding the token — referenced from `.npmrc` via `${ENV}`
+ * interpolation, never written raw into the committed repo.
+ */
+export interface NpmRegistryKitSource {
+  readonly kind: ProjectKitSourceKind.NpmRegistry;
+  /** Package name, e.g. `@acme/widgets` or `lodash`. */
+  readonly package: string;
+  /** Semver range stored into `package.json`, e.g. `^1.2.0`. */
+  readonly versionRange: string;
+  /** Registry URL for a scoped/private package. Omit for the public registry. */
+  readonly registryUrl?: string;
+  /** npm scope (`@acme`) the `registryUrl` serves. Required when `registryUrl` is set. */
+  readonly scope?: string;
+  /** Wallet-backed auth for a private registry. Omit for public registries. */
+  readonly auth?: ProjectKitAuth;
+}
+
+/**
+ * A package resolved directly from a git repository. `package.json` records
+ * `git+<gitUrl>#<ref>`. For a private repo, `auth` points at the wallet entry
+ * holding the git token; the workspace rewrites the clone URL with it via git
+ * `insteadOf` so the committed `package.json` URL stays clean.
+ */
+export interface GitKitSource {
+  readonly kind: ProjectKitSourceKind.Git;
+  /** HTTPS git URL, e.g. `https://gitea.example.com/xema/component-library.git`. */
+  readonly gitUrl: string;
+  /** Tag / branch / commit to pin. Strongly recommended. */
+  readonly ref?: string;
+  /**
+   * The `package.json` `name` the repo publishes — i.e. the key the kit
+   * lands under in the consuming repo's `dependencies`. An npm-registry
+   * source carries this implicitly as `package`; a git source does not,
+   * so it is declared here. When set, the deterministic provisioning
+   * `EQUIP` step can guard on `MARKER_ABSENT` (`/dependencies/<packageName>`)
+   * and cleanly skip an already-installed kit. When omitted, the EQUIP
+   * step falls back to an unconditional (still idempotent) `npm install`.
+   */
+  readonly packageName?: string;
+  /** Wallet-backed auth for a private repository. Omit for public repos. */
+  readonly auth?: ProjectKitAuth;
+}
+
+/** Discriminated union of every `NpmDependency` kit source. */
+export type ProjectKitSource = NpmRegistryKitSource | GitKitSource;
+
+/** Discriminator for how a per-session kit binding was chosen. */
+export enum ProjectKitBindingKind {
+  /** A first-party kit picked from the seeded catalog (referenced by slug). */
+  Catalog = 'catalog',
+  /** A kit the user supplied ad-hoc (an npm name or git URL pasted at create time). */
+  Custom = 'custom',
+}
+
+/** A binding that references a catalog kit by slug. */
+export interface CatalogProjectKitBinding {
+  readonly binding: ProjectKitBindingKind.Catalog;
+  readonly slug: string;
+}
+
+/** A binding that carries its own inline kit spec (user-provided). */
+export interface CustomProjectKitBinding {
+  readonly binding: ProjectKitBindingKind.Custom;
+  readonly kitKind: ProjectKitKind;
+  /** Defaults to `GenericDependency` when the user does not classify it. */
+  readonly purpose?: ProjectKitPurpose;
+  readonly source: ProjectKitSource;
+}
+
+/**
+ * A kit attached to a single interactive session. Persisted on the owning
+ * session-domain row (e.g. `WebappStudio.projectKits`) and threaded verbatim
+ * through `customConfig.projectKits` to the session.
+ */
+export type ProjectKitBinding =
+  | CatalogProjectKitBinding
+  | CustomProjectKitBinding;
+
+/**
+ * A kit binding after the session bootstrap has resolved every catalog
+ * reference against the kit catalog. The deterministic `provision` phase
+ * synthesizes one guard-gated EQUIP step per resolved kit.
+ *
+ * `compatibleTargets` is an opaque list of tech-stack tags — the consuming
+ * session type interprets them (webapp-studio matches them against its
+ * `appTarget.kind` values). This contract does not know what the tags mean.
+ */
+export interface ResolvedProjectKit {
+  /** Stable identifier — the catalog slug, or a derived id for custom bindings. */
+  readonly id: string;
+  readonly kitKind: ProjectKitKind;
+  readonly purpose: ProjectKitPurpose;
+  readonly source: ProjectKitSource;
+  /** Skill slug the bootstrap mounts so the agent knows how to use the kit. */
+  readonly enrichmentSkillSlug?: string;
+  /** Opaque tech-stack tags the consuming session type matches against. */
+  readonly compatibleTargets: readonly string[];
+}
+

package/src/provisioning/index.ts

@@ -0,0 +1,17 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/provisioning-contracts — Workspace Provisioning wire contracts.
+//
+// Pure types + Zod schemas for the `provision` lifecycle phase (Epic A): the
+// deterministic, guard-gated `SCAFFOLD` / `EQUIP` steps that prepare a
+// session's repo content. agent-session-api's `provisioning-plan-resolver`
+// RESOLVES a plan from biome manifests; workspace-proxy's
+// `provisioning-plan` handler EXECUTES it. Both validate against the schemas
+// here, so the wire shape has exactly one source of truth.
+//
+// A FOCUSED leaf package on purpose (same rationale as
+// `@xemahq/project-kit-contracts`): kept un-nested so any service exposing
+// these enums via `@ApiProperty({ enum })` resolves a clean top-level
+// specifier. Zero runtime deps beyond `zod`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/provisioning';