wicked-crew-api-types 0.28.0 → 0.30.0

package/index.d.ts

@@ -1328,6 +1328,11 @@ export interface SteeringLandingResult {
 
 // ── Skills — the daemon-owned garden plugin root, published as immutable snapshots (api-types 0.28.0) ──
 //
+// api-types 0.29.0 (design amendment v3.6, crew #490): the installer-managed copy
+// `<config dir>/plugins/wicked-garden` is a LAST-resort seed source — `SkillSourceKind` gains
+// `installer-copy`, and `DiagnosticsSkillsFinding.kind` gains the persistent `skills.source` warning
+// and the fail-closed `skills.manifest` error.
+//
 // Skills are files (skills keystone, design v3 + amendments v3.1/v3.2). The daemon owns ONE
 // effective `wicked-garden`-shaped plugin root — `<state home>/skills/effective/`, the dependency
 // closure of the installed plugin: `.claude-plugin/{plugin.json,archetypes.json,components.json}`,
@@ -1361,10 +1366,14 @@ export type SkillKind = 'router' | 'fork-worker' | 'module';
  *  it while the operator's edits were kept). */
 export type SkillProvenance = 'shipped' | 'override' | 'user-added';
 
-/** Where a baseline was captured from. `claude-plugin-cache` covers the marketplace cache AND the
- *  hand-installed `plugins/wicked-garden` copy (both are "the installed plugin"); `checkout` is a
- *  git working tree; `directory` any other explicit plugin-shaped directory. */
-export type SkillSourceKind = 'claude-plugin-cache' | 'checkout' | 'directory';
+/** Where a baseline was captured from. `claude-plugin-cache` is the marketplace cache
+ *  (`<config dir>/plugins/cache/wicked-garden/wicked-garden/<version>` — the plugin Claude Code
+ *  runs); `installer-copy` is the installer-managed `<config dir>/plugins/wicked-garden` copy
+ *  (`npx wicked-installer install wicked-garden`), accepted only as the LAST resort when no cache
+ *  exists (design v3.6, api-types 0.29.0) and flagged by the `skills.source` diagnostics finding
+ *  while it is the current baseline; `checkout` is a git working tree; `directory` any other
+ *  explicit plugin-shaped directory. */
+export type SkillSourceKind = 'claude-plugin-cache' | 'installer-copy' | 'checkout' | 'directory';
 
 /** The per-baseline `uv sync` state (`<baseline>/.venv`, provisioned once per content hash — the
  *  publish that needs it AWAITS it — and shared read-only by every snapshot that links it):
@@ -2701,6 +2710,128 @@ export interface InteractiveDocDeleteResponse {
   ledger: InteractiveDocDeleteLedgerReport;
 }
 
+/** One hand-pinned demo step on a `kind: "demo"` create (api-types 0.30.0): the wizard's ordered
+ *  steps the governed run authors the spec from (ADR-0018: the agent authors, the service records). */
+export interface InteractiveDemoStepDraft {
+  index: number;
+  subject: string;
+  action: string;
+}
+
+/**
+ * The body of `POST /projects/:projectId/interactive/api/docs` as crew's proxy understands it
+ * (acceptance finding F-046; api-types 0.30.0 — the studio types its create from THIS declaration,
+ * no local mirror). The bridge's own fields (`name`, `kind`, `html`, `brief`, `source_paths`,
+ * `url`, `demo_steps`, `style`, `project`, `source_message_id`) are relayed as-is — this type
+ * documents the two things CREW adds at the proxy before forwarding:
+ *
+ *  - `repo_ref` / `repo_refs` — the repository (or repositories) this document is ABOUT, each a
+ *    registered repo id, its registry name, or its root directory's basename. Crew validates them
+ *    against the project's `crew.repo` members BEFORE the bridge sees the request (a miss is the
+ *    400 {@link InteractiveDocCreateRefusal}, nothing created), strips them from the forwarded
+ *    body, and remembers the binding so the governed draft/demo run is grounded on THOSE repos
+ *    (offline snapshot + the project graph) — never on the project's first member. Unfiled
+ *    (`default` mount) documents cannot name a repository.
+ *  - `style` — passed through when given; when ABSENT crew infers it from the brief's format
+ *    words (print-ready / A4 / brochure → `brochure`; slides / deck → `ppt`; memo / whitepaper →
+ *    `doc`) so the bridge's own print instructions apply to a print brief. No format words → the
+ *    bridge's `web` default.
+ */
+export interface InteractiveDocCreateRequest {
+  /** The doc name; the bridge slugifies it (409 when taken or retired). */
+  name?: string;
+  /** Omitted = a plain html doc (`html` required); `source` = generated from brief/sources; `demo` = a recording. */
+  kind?: 'source' | 'demo';
+  /** A plain html doc's content (or a `source` doc's seed). */
+  html?: string;
+  brief?: string;
+  source_paths?: string[];
+  /** `kind: "demo"` — the live app URL to record against. */
+  url?: string;
+  /** `kind: "demo"` — hand-pinned steps; omitted = the run authors them from the brief. */
+  demo_steps?: InteractiveDemoStepDraft[];
+  style?: 'web' | 'ppt' | 'brochure' | 'doc';
+  /** Crew project binding (DES-PROJECT-001 §2.3): registration is the authority. */
+  project?: string;
+  /** The thread message this generation came from (§7.6). */
+  source_message_id?: string;
+  /** ONE subject repository: a repo id, its name, or its root basename. */
+  repo_ref?: string;
+  /** SEVERAL subject repositories (at most 8); the union with `repo_ref`, de-duplicated. */
+  repo_refs?: string[];
+}
+
+/**
+ * The bridge's answer to a successful `POST /projects/:projectId/interactive/api/docs`, relayed
+ * verbatim by crew's proxy (api-types 0.30.0): interactive's `{ name, head, … }` — `generating`
+ * for a `kind: "source"` doc whose first draft a governed run now produces, `learning` for a demo,
+ * `project_id` echoed for a project-bound doc.
+ */
+export interface InteractiveDocCreateResult {
+  name: string;
+  head: number;
+  kind?: 'doc' | 'demo';
+  generating?: boolean;
+  learning?: boolean;
+  project_id?: string;
+}
+
+/**
+ * Crew's 400 on `POST /projects/:projectId/interactive/api/docs` when the request names a
+ * repository the document cannot be grounded on (F-046; api-types 0.30.0). Nothing was created
+ * on the bridge.
+ */
+export interface InteractiveDocCreateRefusal {
+  /** Human-readable, names the fix (attach the repo, pick one of `available`, name it by id, …). */
+  error: string;
+  /**
+   * `repo_not_in_project` — a ref matched no member repo; `unfiled_doc_repo` — a repo named on the
+   * Unfiled mount; `invalid_repo_ref` — junk spelling / shape / over the cap; `ambiguous_repo_ref`
+   * — a name or basename shared by several member repos (name it by id); `project_mismatch` — the
+   * body's `project` is not the route's project (or is present on the Unfiled mount). The proxy
+   * canonicalizes an OMITTED `project` from the route.
+   */
+  code: 'repo_not_in_project' | 'unfiled_doc_repo' | 'invalid_repo_ref' | 'ambiguous_repo_ref' | 'project_mismatch';
+  /** The refs the request named, as spelled (best-effort stringified when malformed). */
+  requested: string[];
+  /** The subset of `requested` that matched no member repo (`repo_not_in_project` only). */
+  missing?: string[];
+  /** `ambiguous_repo_ref`: each ambiguous ref with the member repos it names. */
+  ambiguous?: Array<{ ref: string; candidates: Array<{ id: string; name: string }> }>;
+  /** The project's `crew.repo` members the request could have named. */
+  available?: Array<{ id: string; name: string }>;
+}
+
+/**
+ * The 502 the create earns when the bridge dropped the connection AFTER the request had reached it
+ * (api-types 0.30.0): the document may already exist, so the proxy never replays the POST — list the
+ * project's documents before creating again.
+ */
+export interface InteractiveDocCreateUndetermined {
+  code: 'create_undetermined';
+  error: string;
+}
+
+/**
+ * The payload of `wicked.interactive.status.posted` as crew's own seams emit it (`producer_id:
+ * "wi-crew"`, relayed on `/ws` inside an `interactiveEvent` frame; api-types 0.30.0). Acceptance finding F-045: every
+ * seam emit — status narration, the terminal error/complete lines, and the closing
+ * `draft.completed` / `edit.completed` / `demo.requested` — now carries `project_id` for a
+ * project-bound document (omitted for an Unfiled one), exactly like the bridge's own emits, so a
+ * skin can file the frame under the right thread. A skin should ALSO match frames by
+ * `document_id` alone when the doc is open under exactly one mount (belt and braces).
+ */
+export interface InteractiveStatusPosted {
+  ts: string;
+  document_id: string;
+  /** Present for a project-bound document. */
+  project_id?: string;
+  state: 'processing' | 'working' | 'asking' | 'complete' | 'error';
+  message?: string;
+  /** The edit seam stamps the handoff version it is answering. */
+  version?: number;
+}
+
 /**
  * One row of `GET /projects/:projectId/interactive/api/docs` (crew#472) — the bridge's own
  * `GET /api/docs` row (interactive's `listDocs` shape, relayed field-for-field) stamped with the
@@ -3376,8 +3507,17 @@ export interface DiagnosticsSkillsFinding {
    *  blocked (engine input points at a non-existent refusal path — launches fail loudly until the
    *  catalog is fixed); `skills.config` = the configured root is corrupt/unusable (same refusal;
    *  `error`), or — as a `warning` on the `published` state — the root lies OUTSIDE the daemon
-   *  state home, so core's fence cross-check (`WICKED_CREW_STATE_HOME`) refuses every launch. */
-  kind: 'skills.fallback' | 'skills.blocked' | 'skills.config';
+   *  state home, so core's fence cross-check (`WICKED_CREW_STATE_HOME`) refuses every launch;
+   *  `skills.source` (`warning`, api-types 0.29.0, design v3.6) = the CURRENT baseline was seeded
+   *  from the installer-managed copy (`SkillSourceKind` `installer-copy`) — the daemon works, but
+   *  that copy receives no marketplace updates until the plugin is registered with Claude Code; it
+   *  persists (alongside the ladder's own finding, if any) until a refresh from the marketplace
+   *  cache re-records the baseline's provenance (byte-identical or not); `skills.manifest`
+   *  (`error`, api-types 0.29.0) = `manifest.json` could not be read when diagnostics were taken
+   *  (corrupt, unreadable, or the root no longer the one the store bound) — reported as
+   *  `config-error` with the cause instead of the stale boot outcome; the exported engine input is
+   *  unchanged until the daemon restarts. */
+  kind: 'skills.fallback' | 'skills.blocked' | 'skills.config' | 'skills.source' | 'skills.manifest';
   severity: 'warning' | 'error';
   message: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",