@synap-core/cli 1.11.0 → 1.13.0

package/dist/commands/cell.d.ts

@@ -6,31 +6,93 @@
  *
  * Usage:
  *   synap cell define --name "My Chart" --file ./chart.js [--type-key my-chart] [--deps '{"recharts":"2.12.0"}'] [--workspace <id>] [--open]
+ *   synap cell define --name "Deal board" --file ./board.js --view-types kanban,table --content-kind collection
  *   cat chart.js | synap cell define --name "My Chart"
  *
  *   synap cell build ./src/chart.tsx --out ./dist/chart.js
  *   synap cell build ./src/chart.tsx --out ./dist/chart.js --define   # bundle then define
+ *   synap cell build ./src/chart.tsx --out ./dist/chart.js --bundle-deps   # no esm.sh at runtime
+ *   synap cell build ./src/card.tsx --out ./dist/card.html --self-contained  # one HTML doc (mcp-app)
  *
  * API:
- *   POST /api/hub/cells/define — { name, rendererSource, workspaceId?, typeKey?, description?, defaultSize? }
+ *   POST /api/hub/cells/define — { name, rendererSource, workspaceId?, typeKey?,
+ *     description?, defaultSize?, deps?, viewTypes?, contentKind? }
  *
- * NOTE on deps: The /cells/define endpoint currently ignores the `deps` field in
- * the Zod schema (parsed but not persisted — the INSERT always uses `deps: {}`).
- * We send it anyway so the payload is ready when the backend adds support.
- * Track: cells.ts upsert sets `deps: {} as Record<string, string>` unconditionally.
+ * DEPS: persisted. (A prior note here claimed `/cells/define` parsed but dropped
+ * `deps` — that is STALE as of HEAD: the route forwards `deps` to `defineCell`,
+ * which writes `deps: input.deps ?? {}` on both the INSERT and the UPDATE branch,
+ * after `validateDeps` runs inside the door.)
+ *
+ * SELECTABILITY: a cell that declares neither `viewTypes` nor `contentKind`
+ * installs cleanly and is then UNPICKABLE — no error, no signal. `viewTypes`
+ * lands in `widget_definitions.view_renderer_view_types` (migration 0221) and is
+ * what the browser copies onto `viewRenderer.viewTypes`; without it the cell can
+ * never be chosen as a view renderer. `contentKind` decides which profile-renderer
+ * slot the cell can fill; omitted, the column defaults to `widget`, which is
+ * placeable but never offered as an entity-detail/card/profile/collection renderer.
+ * Both follow an omit-is-silence rule on an upsert of an EXISTING row: not passing
+ * the flag leaves the stored value untouched (so a source-only re-push can't erase
+ * a declared affinity). Pass `--view-types ""` to clear the affinity.
  *
  * cell build runtime contract:
  *   - esbuild bundles to a single ESM file (format: esm, bundle: true)
- *   - bare imports (react, react-dom, any non-relative) are externalized
- *   - externalized modules become the deps map (version from package.json if present, else "latest")
+ *   - default mode: every bare import (react, react-dom, any non-relative) is
+ *     externalized; externalized modules become the deps map (version from
+ *     package.json if present, else "latest"); at runtime Synap resolves
+ *     them via esm.sh importmap
+ *   - `--bundle-deps` mode: only react/react-dom are externalized (they are
+ *     host-inlined at runtime, never via esm.sh — see
+ *     `synap-app/packages/core/cell-runtime/src/frame-react-modules.ts`);
+ *     every other bare import is bundled into the output, so the deps map is
+ *     `{}` and the frame's runtime CSP drops esm.sh entirely (see
+ *     `ViewFrame.buildFrameCsp`'s `fullyBundled` branch) — this mode is
+ *     opt-in; the default build is byte-identical to before this flag existed
  *   - the output module default-exports a React component (or plain module)
- *   - at runtime Synap resolves bare imports via esm.sh importmap
+ *   - default and `--bundle-deps` modes REFUSE an imported `.css` file (a
+ *     `CellBundleError` naming it): the output is one JS module with nowhere to
+ *     put a stylesheet, so the CSS could only be lost. `--self-contained` is the
+ *     mode that keeps it.
+ *   - `--self-contained` mode (an `rendererType: "mcp-app"` cell — a foreign
+ *     MCP-Apps host loads ONE sandboxed HTML document whose CSP admits no
+ *     esm.sh, no Google Fonts, no host-supplied React): NOTHING is external —
+ *     React included. Imported CSS is collected and inlined in `<style>`, the
+ *     brand faces (`@synap-core/design-tokens/fonts`, base64 woff2) are
+ *     prepended when they resolve from the entry's package, and the result is
+ *     wrapped into a complete HTML document whose inline `<script
+ *     type="module">` is the bundle. The output (the cell `code`) IS that
+ *     document; `deps` is always `{}`. The entry is the document's only script,
+ *     so it must mount itself (a `#root` element is provided).
+ */
+/**
+ * The `contentKind` vocabulary — WHAT a cell renders, which decides the
+ * profile-renderer slots it can fill.
+ *
+ * SSOT: `ContentKind` in
+ * `synap-backend/packages/database/src/schema/widget-definitions.ts`
+ * (canonically mirrored from `@synap-core/capabilities`). This list is a
+ * hand-maintained copy because the CLI does not depend on either package; if
+ * the union there grows, `test/cell-define-content-kind.test.ts` is the only
+ * thing that will catch the drift — keep them together.
  */
+export declare const CONTENT_KINDS: readonly ["entity-detail", "entity-card", "entity-profile", "collection", "widget"];
+export type ContentKind = (typeof CONTENT_KINDS)[number];
+/** Narrow a raw `--content-kind` value against {@link CONTENT_KINDS}. */
+export declare function parseContentKind(raw: string): ContentKind | null;
+/**
+ * Parse a `--view-types` list. Comma-separated, trimmed, deduped.
+ *
+ * `undefined` (flag absent) ⇒ omit the field entirely, so an upsert of an
+ * existing row leaves the stored affinity untouched. An EMPTY string ⇒ `[]`,
+ * the explicit "clear it" signal the define door documents.
+ */
+export declare function parseViewTypes(raw: string | undefined): string[] | undefined;
 export interface CellDefineOpts {
     name: string;
     file?: string;
     typeKey?: string;
     deps?: string;
+    viewTypes?: string;
+    contentKind?: string;
     workspace?: string;
     description?: string;
     open?: boolean;
@@ -41,9 +103,16 @@ export interface CellDefineOpts {
 export interface CellBuildOpts {
     out?: string;
     define?: boolean;
+    bundleDeps?: boolean;
+    /** One complete HTML document, nothing external (an `mcp-app` cell). */
+    selfContained?: boolean;
+    /** `--self-contained` only: `false` skips the brand faces; `true` requires them. */
+    fonts?: boolean;
     name?: string;
     typeKey?: string;
     deps?: string;
+    viewTypes?: string;
+    contentKind?: string;
     workspace?: string;
     description?: string;
     open?: boolean;
@@ -51,5 +120,83 @@ export interface CellBuildOpts {
     podUrl?: string;
     apiKey?: string;
 }
+/**
+ * Thrown by `bundleWithEsbuild`/`buildCellFromSource` instead of exiting the
+ * process, so a caller that is NOT the direct `cell build` CLI entry point
+ * (namely `resolveCellCodeFiles` on the `market publish` path) can turn a
+ * bundle failure into its own structured `{ ok: false, ... }` envelope rather
+ * than have the process die out from under it before that envelope is ever
+ * built. `cellBuild` (the direct entry point) catches this like any other
+ * error and still exits 1 — interactive behaviour is unchanged.
+ */
+export declare class CellBundleError extends Error {
+}
+/**
+ * Package names that stay external even under `--bundle-deps` — the modules
+ * the FRAME HOST provides at runtime, which must never be pulled from
+ * node_modules: react/react-dom are host-inlined (`synap-app/packages/core/
+ * cell-runtime/src/frame-react-modules.ts`), and `@synap/view-sdk` is
+ * host-supplied via the iframe import map (`.../frame-import-map.ts`,
+ * `imports['@synap/view-sdk'] = blobs.viewSdk`). Externalizing all three
+ * costs nothing and keeps the bundle small; failing to list one here means
+ * `--bundle-deps` (now the DEFAULT for `market publish` cells) can never
+ * build a cell that imports it — esbuild tries to resolve it from
+ * node_modules and fails, dead on arrival.
+ *
+ * This set is a hand-maintained mirror of `frame-import-map.ts` — exactly the
+ * drift class this repo keeps losing to — so `frame-import-map-parity.test.ts`
+ * reads that file's own source across the repo boundary and fails the moment
+ * the host starts supplying a module this set doesn't know about.
+ */
+export declare const BUNDLE_DEPS_KEEP_EXTERNAL: Set<string>;
+/** Call esbuild programmatically. Returns { code, externals, css }. Exported for tests. */
+export declare function bundleWithEsbuild(entry: string, opts?: {
+    bundleDeps?: boolean;
+    selfContained?: boolean;
+}): Promise<{
+    code: string;
+    externals: string[];
+    css: string;
+}>;
+/** The `@synap-core/design-tokens` export that carries the inlined brand faces. */
+export declare const FONTS_MODULE = "@synap-core/design-tokens/fonts";
+/**
+ * `SYNAP_FONT_FACE_CSS`, resolved from `fromDir` the way the entry's own
+ * imports resolve — or `null` when the package is not reachable from there.
+ * The module is TypeScript source (the package ships `src/`), so it is run
+ * through esbuild and evaluated in an empty VM context rather than imported.
+ */
+export declare function resolveFontFaceCss(fromDir: string): Promise<string | null>;
+/**
+ * Wrap a self-contained bundle into the complete HTML document an MCP-Apps
+ * host loads verbatim. `</style` / `</script` are escaped so inlined text can
+ * never close its own element early (`<\/` is the same character sequence to
+ * the CSS and JS parsers, but not to the HTML tokenizer).
+ */
+export declare function wrapSelfContainedHtml(parts: {
+    js: string;
+    css: string;
+}): string;
+export interface BuiltCell {
+    code: string;
+    /** Externals → version, ready for the `deps` field the runtime resolves via esm.sh. */
+    deps: Record<string, string>;
+    externals: string[];
+}
+/**
+ * Bundle `entry` and derive its `deps` map — the shared guts behind `cell
+ * build` (which additionally writes the result to disk) and `market
+ * publish`'s `codeFile` resolution (`lib/kind-package.ts`, which inlines the
+ * result straight into a package's `code` field instead). Kept in ONE place
+ * because the bundle-deps/react-exclusion derivation below is exactly the
+ * seam `cell-build-bundle-deps.test.ts` exists to protect (see its top-of-file
+ * comment) — a second copy of this logic is how that bug would come back.
+ */
+export declare function buildCellFromSource(entry: string, opts?: {
+    bundleDeps?: boolean;
+    deps?: string;
+    selfContained?: boolean;
+    fonts?: boolean;
+}): Promise<BuiltCell>;
 export declare function cellDefine(opts: CellDefineOpts): Promise<void>;
 export declare function cellBuild(entry: string, opts: CellBuildOpts): Promise<void>;