@synap-core/workspace-templates 0.2.1

package/src/define.ts

@@ -0,0 +1,184 @@
+/**
+ * @synap-core/workspace-templates — Definition adapter
+ *
+ * Converts a YAML template (WorkspaceYaml) into the flat payload shape that
+ * the backend `workspaces.createFromDefinition` mutation + Hub REST
+ * `/workspaces/from-definition` endpoint expect.
+ *
+ * This is the single canonical seam: every consumer (browser app, onboarding,
+ * CLI, marketplace) provisions a workspace through this function so the wire
+ * shape never drifts per call-site.
+ */
+
+import type { WorkspaceYaml } from './types.js';
+import { getWorkspaceTemplate } from './templates.js';
+
+/** The flat definition object accepted by createFromDefinition. */
+export interface WorkspaceDefinitionInput {
+  workspaceName: string;
+  description: string;
+  proposalId?: string;
+  profiles: WorkspaceYaml['profiles'];
+  views: NonNullable<WorkspaceYaml['views']>;
+  entityLinks: NonNullable<WorkspaceYaml['entityLinks']>;
+  seedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+  suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+  displayTemplates?: WorkspaceYaml['displayTemplates'];
+  layoutConfig: WorkspaceYaml['layout'] | undefined;
+  bentoViewName?: string;
+  bentoViewBlocks?: NonNullable<WorkspaceYaml['bento']>['blocks'];
+  profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
+  // Workspace-level metadata (flattened from the `workspace` block)
+  workspaceSubtype?: string;
+  workspaceType?: NonNullable<WorkspaceYaml['workspace']>['workspaceType'];
+  workspaceVisibility?: string;
+  workspaceCapabilities?: string[];
+  sourceRoles?: NonNullable<WorkspaceYaml['workspace']>['sourceRoles'];
+  defaultSources?: NonNullable<WorkspaceYaml['workspace']>['defaultSources'];
+  /** Per-workspace onboarding context — written to settings.onboarding. */
+  onboarding?: WorkspaceYaml['onboarding'];
+}
+
+export interface ToDefinitionResult {
+  definition: WorkspaceDefinitionInput;
+  /** Stable idempotency key — the template's proposalId or slug. */
+  proposalId: string;
+  /** Display name for the new workspace. */
+  workspaceName: string;
+  /** Template id for telemetry / dedup. */
+  templateId: string;
+}
+
+/**
+ * Resolve a template (by slug or YAML object) into the createFromDefinition
+ * payload. Pass `nameOverride` to rename the workspace at creation time.
+ */
+export function toWorkspaceDefinition(
+  slugOrYaml: string | WorkspaceYaml,
+  nameOverride?: string,
+): ToDefinitionResult {
+  const tpl: WorkspaceYaml | undefined =
+    typeof slugOrYaml === 'string' ? getWorkspaceTemplate(slugOrYaml) : slugOrYaml;
+
+  if (!tpl) {
+    throw new Error(`Workspace template not found: ${String(slugOrYaml)}`);
+  }
+
+  const ws = tpl.workspace;
+  const name = nameOverride ?? ws.name;
+  const proposalId = ws.proposalId ?? `${tpl.meta.slug}-v1`;
+
+  const definition: WorkspaceDefinitionInput = {
+    workspaceName: name,
+    description: ws.description,
+    proposalId,
+    profiles: tpl.profiles,
+    views: tpl.views ?? [],
+    entityLinks: tpl.entityLinks ?? [],
+    seedEntities: tpl.seedEntities ?? [],
+    suggestedRelations: tpl.suggestedRelations,
+    displayTemplates: tpl.displayTemplates,
+    layoutConfig: tpl.layout,
+    bentoViewName: tpl.bento?.viewName,
+    bentoViewBlocks: tpl.bento?.blocks,
+    profileEntityBentoTemplates: tpl.profileEntityBentoTemplates,
+    workspaceSubtype: ws.subtype,
+    workspaceType: ws.workspaceType,
+    workspaceVisibility: ws.visibility,
+    workspaceCapabilities: ws.capabilities,
+    sourceRoles: ws.sourceRoles,
+    defaultSources: ws.defaultSources,
+    onboarding: tpl.onboarding,
+  };
+
+  return { definition, proposalId, workspaceName: name, templateId: tpl.meta.slug };
+}
+
+/**
+ * The unified `PackageDefinition` shape consumed by `POST /api/hub/packages/apply`
+ * (CLI `synap launch`) and the CP package registry seeder. It composes the
+ * workspace definition with the capability/playbook/onboarding layers. Mirrors
+ * `PackageDefinition` in synap-backend `package-definition.ts`. Typed loosely on
+ * the layered fields to avoid a backend import; the wire validation lives in the
+ * apply endpoint.
+ */
+export interface PackageDefinitionOutput {
+  _meta: {
+    slug: string;
+    icon?: string;
+    color?: string;
+    tags?: string[];
+    isPublic?: boolean;
+    requiredTier?: string | null;
+  };
+  workspaceName: string;
+  description: string;
+  workspaceType?: WorkspaceYaml['workspace']['workspaceType'];
+  workspaceSubtype?: string;
+  workspaceVisibility?: string;
+  workspaceCapabilities?: string[];
+  sourceRoles?: WorkspaceYaml['workspace']['sourceRoles'];
+  defaultSources?: WorkspaceYaml['workspace']['defaultSources'];
+  profiles: WorkspaceYaml['profiles'];
+  views: NonNullable<WorkspaceYaml['views']>;
+  suggestedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+  suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+  displayTemplates?: WorkspaceYaml['displayTemplates'];
+  entityLinks?: WorkspaceYaml['entityLinks'];
+  bentoLayout?: NonNullable<WorkspaceYaml['bento']>['blocks'];
+  bentoViewName?: string;
+  profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
+  layoutConfig?: WorkspaceYaml['layout'];
+  capabilities?: WorkspaceYaml['integrations'];
+  playbooks?: WorkspaceYaml['playbooks'];
+  onboarding?: WorkspaceYaml['onboarding'];
+}
+
+/**
+ * Resolve a template (by slug or YAML object) into the full `PackageDefinition`
+ * accepted by `POST /api/hub/packages/apply` and the CP registry seeder. This is
+ * the single seam the CLI and control-plane use so they read from the canonical
+ * package instead of disk-stored JSON.
+ */
+export function toPackageDefinition(
+  slugOrYaml: string | WorkspaceYaml,
+): PackageDefinitionOutput {
+  const tpl: WorkspaceYaml | undefined =
+    typeof slugOrYaml === 'string' ? getWorkspaceTemplate(slugOrYaml) : slugOrYaml;
+
+  if (!tpl) {
+    throw new Error(`Workspace template not found: ${String(slugOrYaml)}`);
+  }
+
+  const ws = tpl.workspace;
+  return {
+    _meta: {
+      slug: tpl.meta.slug,
+      icon: tpl.meta.icon,
+      color: tpl.meta.color,
+      tags: tpl.meta.tags,
+      isPublic: tpl.meta.isPublic ?? true,
+    },
+    workspaceName: ws.name,
+    description: ws.description,
+    workspaceType: ws.workspaceType,
+    workspaceSubtype: ws.subtype,
+    workspaceVisibility: ws.visibility,
+    workspaceCapabilities: ws.capabilities,
+    sourceRoles: ws.sourceRoles,
+    defaultSources: ws.defaultSources,
+    profiles: tpl.profiles,
+    views: tpl.views ?? [],
+    suggestedEntities: tpl.seedEntities ?? [],
+    suggestedRelations: tpl.suggestedRelations,
+    displayTemplates: tpl.displayTemplates,
+    entityLinks: tpl.entityLinks,
+    bentoLayout: tpl.bento?.blocks,
+    bentoViewName: tpl.bento?.viewName,
+    profileEntityBentoTemplates: tpl.profileEntityBentoTemplates,
+    layoutConfig: tpl.layout,
+    capabilities: tpl.integrations,
+    playbooks: tpl.playbooks,
+    onboarding: tpl.onboarding,
+  };
+}