@process.co/element-types 0.0.8 → 0.0.9

package/src/index.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import type { z } from 'zod';
 
 // Element types
@@ -15,35 +16,67 @@ export type ElementSignal<T> = { type: "signal"; icon?: ElementIcon; label?: str
 
 export type ElementIcon = { type: "FontAwesome" | "MaterialIcons" | "ProcessIcons" | "RemoteImage" | "image"; icon: string | ['far' | 'fas' | 'fab' | 'fal' | 'fad', string] } | string;
 
-export type ISlotInstanceDefinition = {
-    id?: string;
-    label?: string;
-    enabled?: boolean;
-    path?: string;
-    idPath?: string;
-    labelPath?: string;
-    enabledPath?: string;
-    labelPlaceholderTemplate?: string;
-    labelPlaceholderValue?: string;
-    branchValue?: string;
-    hideOnDisable?: boolean;
-    actionsPath?: string;
-    exportsPath?: string;
-}
-
-export type ISlotStaticInstanceDefinition = ISlotInstanceDefinition & {
-    type: "static";
-}
-
-export type ISlotDefinition = {
-    showBranchLabels?: boolean;
-    activeSlotId?: string;
-    activeSlotLabel?: string;
-    hideDisabled?: boolean;
-    hideOnDisable?: boolean;
-    exportSchemaPath?: string;
-    slots?: (ISlotInstanceDefinition | ISlotStaticInstanceDefinition)[];
-}
+import type {
+    ISlotInstanceDefinition,
+    ISlotStaticInstanceDefinition,
+    ISlotDefinition,
+} from './slot-definition';
+
+export type { ISlotInstanceDefinition, ISlotStaticInstanceDefinition, ISlotDefinition };
+
+export {
+    builtinActionSlotsRegistry,
+    type BuiltinActionSlotsRegistry,
+    type BuiltinActionSlotsFern,
+    type InferBuiltinActionSlots,
+} from './builtin-action-slots-registry';
+
+/** Full **`process-element` CLI** JSON shape + materializer for FERN-keyed props/slots (workflow-sdk / codegen). */
+export type {
+    ProcessElementPropCliWire,
+    ProcessElementActionCliWire,
+    ProcessElementSignalCliWire,
+    ProcessElementCliOutputWire,
+} from './process-element-cli-output';
+
+export type {
+    MaterializedSlotBranch,
+    MaterializedSlotLayout,
+    MaterializedSlotDefinition,
+} from './materialize-slot-definition';
+export { materializeSlotDefinition } from './materialize-slot-definition';
+
+export type {
+    MaterializedPropAuthoring,
+    MaterializedActionAuthoringEntry,
+    MaterializedSignalAuthoringEntry,
+    MaterializedAuthoringCatalog,
+} from './materialize-authoring-from-cli-output';
+export {
+    buildProcessActionFern,
+    buildProcessSignalFern,
+    materializeAuthoringCatalogFromCliOutput,
+} from './materialize-authoring-from-cli-output';
+
+/** Locked authoring catalog + helpers for FERN / slot / prop inference (not raw CLI JSON). */
+export {
+    ELEMENT_AUTHORING_CONTRACT_VERSION,
+    toAuthoringCatalogContract,
+    authoringCatalogContractFromCliOutput,
+} from './authoring-contract';
+export type {
+    AuthoringPropWireKind,
+    AuthoringPropContract,
+    SlotBranchAuthoringContract,
+    SlotsAuthoringContract,
+    ActionAuthoringContract,
+    SignalAuthoringContract,
+    ElementAuthoringCatalogContract,
+    ChildStepsPropertyForBranch,
+    ActionPropKeys,
+    ActionContractByFern,
+    FernAuthoringShardFileV1,
+} from './authoring-contract';
 
 // Base types for module definitions
 export type ModuleDefinition = {

package/src/materialize-authoring-from-cli-output.ts

@@ -0,0 +1,157 @@
+import { materializeSlotDefinition, type MaterializedSlotDefinition } from './materialize-slot-definition';
+import type {
+  ProcessElementActionCliWire,
+  ProcessElementCliOutputWire,
+  ProcessElementPropCliWire,
+  ProcessElementSignalCliWire,
+} from './process-element-cli-output';
+
+export type MaterializedPropAuthoring = {
+  key: string;
+  label: string;
+  description: string;
+  /** String from loader **`type`** (e.g. **`string`**, **`object`**, or zodex-serialized object as JSON). */
+  wireType: string;
+  required: boolean;
+  hasJsonType: boolean;
+  isFunction: boolean;
+};
+
+export type MaterializedActionAuthoringEntry = {
+  kind: 'action';
+  fern: string;
+  /** Raw action key from the element (may include namespace prefix). */
+  elementKey: string;
+  name: string;
+  description?: string;
+  returns?: string;
+  props: MaterializedPropAuthoring[];
+  slots: MaterializedSlotDefinition | null;
+};
+
+export type MaterializedSignalAuthoringEntry = {
+  kind: 'signal';
+  fern: string;
+  elementKey: string;
+  name: string;
+  description?: string;
+  returns?: string;
+  props: MaterializedPropAuthoring[];
+};
+
+export type MaterializedAuthoringCatalog = {
+  namespace: string;
+  actionsByFern: Record<string, MaterializedActionAuthoringEntry>;
+  signalsByFern: Record<string, MaterializedSignalAuthoringEntry>;
+};
+
+function stripNamespacePrefixFromActionKey(namespace: string, key: string): string {
+  const prefix = `${namespace}-`;
+  return key.startsWith(prefix) ? key.slice(prefix.length) : key;
+}
+
+/**
+ * Build registry FERN for an action (**`namespace::action:slug`**), matching common API normalization.
+ */
+export function buildProcessActionFern(namespace: string, actionKey: string): string {
+  const slug = stripNamespacePrefixFromActionKey(namespace, actionKey);
+  return `${namespace}::action:${slug}`;
+}
+
+/** Build registry FERN for a signal (**`namespace::signal:slug`**). */
+export function buildProcessSignalFern(namespace: string, signalKey: string): string {
+  const slug = stripNamespacePrefixFromActionKey(namespace, signalKey);
+  return `${namespace}::signal:${slug}`;
+}
+
+function wireTypeLabel(type: unknown): string {
+  if (type === undefined || type === null) {
+    return 'unknown';
+  }
+  if (typeof type === 'string') {
+    return type;
+  }
+  try {
+    return JSON.stringify(type);
+  } catch {
+    return 'unknown';
+  }
+}
+
+function materializeProp(p: ProcessElementPropCliWire): MaterializedPropAuthoring {
+  return {
+    key: p.key,
+    label: p.label,
+    description: typeof p.description === 'string' ? p.description : '',
+    wireType: wireTypeLabel(p.type),
+    required: p.required === true,
+    hasJsonType: p.jsonType !== undefined && p.jsonType !== null,
+    isFunction: p.isFunction === true,
+  };
+}
+
+function materializeAction(
+  namespace: string,
+  a: ProcessElementActionCliWire,
+): MaterializedActionAuthoringEntry {
+  const fern = buildProcessActionFern(namespace, a.key);
+  return {
+    kind: 'action',
+    fern,
+    elementKey: a.key,
+    name: a.name,
+    description: typeof a.description === 'string' ? a.description : undefined,
+    returns: typeof a.returns === 'string' ? a.returns : undefined,
+    props: (Array.isArray(a.props) ? a.props : []).map(materializeProp),
+    slots: materializeSlotDefinition(a.slots),
+  };
+}
+
+function materializeSignal(
+  namespace: string,
+  s: ProcessElementSignalCliWire,
+): MaterializedSignalAuthoringEntry {
+  const fern = buildProcessSignalFern(namespace, s.key);
+  return {
+    kind: 'signal',
+    fern,
+    elementKey: s.key,
+    name: s.name,
+    description: typeof s.description === 'string' ? s.description : undefined,
+    returns: typeof s.returns === 'string' ? s.returns : undefined,
+    props: (Array.isArray(s.props) ? s.props : []).map(materializeProp),
+  };
+}
+
+/**
+ * Turn the **entire compatibility CLI / `loadElementPointers` JSON** into FERN-keyed authoring material
+ * (props + slot paths + returns hints) for codegen or merging into **`@process.co/workflow-sdk`**.
+ *
+ * @param namespace — FERN namespace segment (e.g. **`process-internal`**). Defaults to **`info.name`** (element app slug).
+ */
+export function materializeAuthoringCatalogFromCliOutput(
+  info: ProcessElementCliOutputWire,
+  namespace?: string,
+): MaterializedAuthoringCatalog {
+  const ns = namespace ?? info.name;
+  const actionsByFern: Record<string, MaterializedActionAuthoringEntry> = {};
+  const signalsByFern: Record<string, MaterializedSignalAuthoringEntry> = {};
+
+  for (const a of info.actions) {
+    if (a?.type !== 'action' || typeof a.key !== 'string') {
+      continue;
+    }
+    const entry = materializeAction(ns, a as ProcessElementActionCliWire);
+    actionsByFern[entry.fern] = entry;
+  }
+
+  for (const s of info.signals) {
+    if (s?.type !== 'signal' || typeof s.key !== 'string') {
+      continue;
+    }
+    const entry = materializeSignal(ns, s as ProcessElementSignalCliWire);
+    signalsByFern[entry.fern] = entry;
+  }
+
+  return { namespace: ns, actionsByFern, signalsByFern };
+}

package/src/materialize-slot-definition.ts

@@ -0,0 +1,88 @@
+import type {
+  ISlotDefinition,
+  ISlotInstanceDefinition,
+  ISlotStaticInstanceDefinition,
+} from './slot-definition';
+
+export type MaterializedSlotBranch = {
+  kind: 'static' | 'dynamic';
+  id?: string;
+  label?: string;
+  branchValue?: string;
+  path?: string;
+  idPath?: string;
+  labelPath?: string;
+  enabledPath?: string;
+  actionsPath?: string;
+  exportsPath?: string;
+  hideOnDisable?: boolean;
+  labelPlaceholderTemplate?: string;
+  labelPlaceholderValue?: string;
+};
+
+export type MaterializedSlotLayout = {
+  showBranchLabels?: boolean;
+  activeSlotId?: string;
+  activeSlotLabel?: string;
+  hideDisabled?: boolean;
+  hideDisabledPath?: string;
+  hideOnDisable?: boolean;
+  exportSchemaPath?: string;
+};
+
+export type MaterializedSlotDefinition = {
+  layout: MaterializedSlotLayout;
+  branches: MaterializedSlotBranch[];
+};
+
+function branchKind(row: ISlotInstanceDefinition | ISlotStaticInstanceDefinition): 'static' | 'dynamic' {
+  return 'type' in row && row.type === 'static' ? 'static' : 'dynamic';
+}
+
+function pickBranch(row: ISlotInstanceDefinition | ISlotStaticInstanceDefinition): MaterializedSlotBranch {
+  const b: MaterializedSlotBranch = { kind: branchKind(row) };
+  if (row.id !== undefined) b.id = row.id;
+  if (row.label !== undefined) b.label = row.label;
+  if (row.branchValue !== undefined) b.branchValue = row.branchValue;
+  if (row.path !== undefined) b.path = row.path;
+  if (row.idPath !== undefined) b.idPath = row.idPath;
+  if (row.labelPath !== undefined) b.labelPath = row.labelPath;
+  if (row.enabledPath !== undefined) b.enabledPath = row.enabledPath;
+  if (row.actionsPath !== undefined) b.actionsPath = row.actionsPath;
+  if (row.exportsPath !== undefined) b.exportsPath = row.exportsPath;
+  if (row.hideOnDisable !== undefined) b.hideOnDisable = row.hideOnDisable;
+  if (row.labelPlaceholderTemplate !== undefined) b.labelPlaceholderTemplate = row.labelPlaceholderTemplate;
+  if (row.labelPlaceholderValue !== undefined) b.labelPlaceholderValue = row.labelPlaceholderValue;
+  return b;
+}
+
+function pickLayout(def: ISlotDefinition): MaterializedSlotLayout {
+  const layout: MaterializedSlotLayout = {};
+  if (def.showBranchLabels !== undefined) layout.showBranchLabels = def.showBranchLabels;
+  if (def.activeSlotId !== undefined) layout.activeSlotId = def.activeSlotId;
+  if (def.activeSlotLabel !== undefined) layout.activeSlotLabel = def.activeSlotLabel;
+  if (def.hideDisabled !== undefined) layout.hideDisabled = def.hideDisabled;
+  if (def.hideDisabledPath !== undefined) layout.hideDisabledPath = def.hideDisabledPath;
+  if (def.hideOnDisable !== undefined) layout.hideOnDisable = def.hideOnDisable;
+  if (def.exportSchemaPath !== undefined) layout.exportSchemaPath = def.exportSchemaPath;
+  return layout;
+}
+
+function isEffectivelyEmpty(def: ISlotDefinition): boolean {
+  const rows = def.slots ?? [];
+  const layout = pickLayout(def);
+  return rows.length === 0 && Object.keys(layout).length === 0;
+}
+
+/** Normalize **`ISlotDefinition`** for codegen / workflow inference (JSON-serializable). */
+export function materializeSlotDefinition(
+  def: ISlotDefinition | null | undefined,
+): MaterializedSlotDefinition | null {
+  if (def == null || isEffectivelyEmpty(def)) {
+    return null;
+  }
+  return {
+    layout: pickLayout(def),
+    branches: (def.slots ?? []).map(pickBranch),
+  };
+}

package/src/process-element-cli-output.ts

@@ -0,0 +1,85 @@
+import type { ISlotDefinition } from './slot-definition';
+
+/**
+ * One flattened prop row from **`process-co` compatibility `loadElementPointers`** (`buildProp` output).
+ * Matches **`@process.co/elements`** `IProcessDefinitionUIPointers.props[]` plus loader fields.
+ */
+export type ProcessElementPropCliWire = {
+  key: string;
+  label: string;
+  description?: string;
+  type?: unknown;
+  jsonType?: unknown;
+  isFunction?: boolean;
+  required?: boolean;
+  default?: unknown;
+  ui?: string;
+  options?: unknown;
+  deps?: string[];
+  placeholder?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * One action row from **`loadElementPointers`** for a Process element (not Pipedream shape).
+ * This is what sits in **`IProcessDefinitionUIInfo.actions[]`** after the process loader runs.
+ */
+export type ProcessElementActionCliWire = {
+  type: 'action';
+  key: string;
+  name: string;
+  description?: string;
+  icon?: unknown;
+  ui?: string;
+  categoryKey?: string;
+  sampleEmit?: unknown;
+  returns?: string;
+  slots?: ISlotDefinition;
+  noAuth?: boolean;
+  hasNew?: boolean;
+  initValue?: unknown;
+  props?: ProcessElementPropCliWire[];
+  [key: string]: unknown;
+};
+
+/**
+ * One signal row from **`loadElementPointers`** for a Process element.
+ */
+export type ProcessElementSignalCliWire = {
+  type: 'signal';
+  key: string;
+  name: string;
+  description?: string;
+  ui?: string;
+  categoryKey?: string;
+  sampleEmit?: unknown;
+  returns?: string;
+  noAuth?: boolean;
+  hasNew?: boolean;
+  initValue?: unknown;
+  icon?: unknown;
+  hooks?: boolean;
+  dedupe?: unknown;
+  http?: unknown;
+  instant?: boolean;
+  props?: ProcessElementPropCliWire[];
+  [key: string]: unknown;
+};
+
+/**
+ * Full object emitted by **`process-element`** (compatibility CLI): **`SuperJSON.stringify(loadElementPointers(...))`**.
+ * Structurally aligned with **`@process.co/elements` `IProcessDefinitionUIInfo`** plus process-loader fields on each row.
+ */
+export type ProcessElementCliOutputWire = {
+  elementType: 'process' | 'pipedream' | 'dofloV1' | 'n8n';
+  /** App / namespace slug (`element.app`); used as default FERN namespace when building keys. */
+  name: string;
+  description: {
+    short: string;
+    long: string;
+    MD: string;
+  };
+  actions: ProcessElementActionCliWire[];
+  signals: ProcessElementSignalCliWire[];
+  credentials: unknown[];
+};

package/src/slot-definition.ts

@@ -0,0 +1,31 @@
+export type ISlotInstanceDefinition = {
+  id?: string;
+  label?: string;
+  enabled?: boolean;
+  path?: string;
+  idPath?: string;
+  labelPath?: string;
+  enabledPath?: string;
+  labelPlaceholderTemplate?: string;
+  labelPlaceholderValue?: string;
+  branchValue?: string;
+  hideOnDisable?: boolean;
+  actionsPath?: string;
+  exportsPath?: string;
+};
+
+export type ISlotStaticInstanceDefinition = ISlotInstanceDefinition & {
+  type: 'static';
+};
+
+export type ISlotDefinition = {
+  showBranchLabels?: boolean;
+  activeSlotId?: string;
+  activeSlotLabel?: string;
+  hideDisabled?: boolean;
+  /** Expression/template path for per-row hide-disabled (flow editor / container layout). */
+  hideDisabledPath?: string;
+  hideOnDisable?: boolean;
+  exportSchemaPath?: string;
+  slots?: (ISlotInstanceDefinition | ISlotStaticInstanceDefinition)[];
+};