@boboddy/sdk 0.4.3 → 0.5.0

package/dist/client.js

@@ -1093,29 +1093,6 @@ class PipelineDefinitions extends HeyApiClient {
   unarchivePipelineDefinition(options) {
     return (options.client ?? this.client).put({ url: "/api/pipeline-definitions/{pipelineDefinitionId}/unarchive", ...options });
   }
-  addPipelineStep(options) {
-    return (options.client ?? this.client).post({
-      url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps",
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers
-      }
-    });
-  }
-  removePipelineStep(options) {
-    return (options.client ?? this.client).delete({ url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps/{pipelineStepDefinitionId}", ...options });
-  }
-  updatePipelineStep(options) {
-    return (options.client ?? this.client).put({
-      url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps/{pipelineStepDefinitionId}",
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers
-      }
-    });
-  }
   setPipelineStepAdvancementPolicy(options) {
     return (options.client ?? this.client).put({
       url: "/api/pipeline-definitions/{pipelineDefinitionId}/steps/{pipelineStepDefinitionId}/advancement-policy",

package/dist/definitions/advancement-policies/define-advancement-policy.d.ts

@@ -184,13 +184,23 @@ declare function all<TSignalKeys extends string>(conditions: RuleCondition<TSign
 declare function any<TSignalKeys extends string>(conditions: RuleCondition<TSignalKeys>[]): AnyCondition<TSignalKeys>;
 declare function any<TSignalKeys extends string>(conditions: RuleCondition<TSignalKeys>[], outcome: AdvancementOutcome): Rule<TSignalKeys>;
 /**
- * Shorthand for a single-condition rule. Equivalent to
- * `Rule.all([Rule.signal(signal, operator, value)], outcome)`.
+ * When called with only `signal`/`operator`/`value`: returns a bare
+ * `SignalCondition` — used by a `choice` node's `choices[].when`, a `loop`
+ * node's `until`, and a `step` node's `blockWhen` (see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §4/§5), none of
+ * which attach an outcome of their own (the routing target / block
+ * decision lives on the surrounding state, not on the condition).
+ *
+ * When called with `signal`/`operator`/`value`/`outcome`: returns a
+ * top-level `Rule` — shorthand for
+ * `Rule.all([Rule.signal(signal, operator, value)], outcome)`, used by the
+ * (legacy) full step-advancement-policy shape.
  *
  * @example
- * Rule.when("passed", "equal", true, "continue")
- * Rule.when("score", "greaterThanInclusive", 80, { outcome: "continue", outcomeJson: { via: "score" } })
+ * Rule.when("severity", "equal", "critical")       // bare condition
+ * Rule.when("passed", "equal", true, "continue")    // full rule
  */
+declare function when<TSignalKeys extends string>(signal: TSignalKeys | InlineComputedSignal<string, TSignalKeys>, operator: ConditionOperator, value: unknown): SignalCondition<TSignalKeys>;
 declare function when<TSignalKeys extends string>(signal: TSignalKeys | InlineComputedSignal<string, TSignalKeys>, operator: ConditionOperator, value: unknown, outcome: AdvancementOutcome): Rule<TSignalKeys>;
 /**
  * All factories for building advancement rules.
@@ -252,7 +262,15 @@ type SerializedConditionGroup = {
     all?: SerializedCondition[];
     any?: SerializedCondition[];
 };
-type SerializedCondition = SerializedLeafCondition | SerializedConditionGroup;
+/**
+ * The bare-condition wire format (no outcome) — structurally identical to
+ * `packages/core`'s `RuleCondition`/`rule-condition.ts` (leaves:
+ * `{fact,operator,value}`, groups: `{all:[...]}`/`{any:[...]}`). Reused
+ * verbatim for a `choice` node's `choices[].conditionJson` and a `loop`
+ * node's `untilConditionJson` (see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §7.2).
+ */
+export type SerializedCondition = SerializedLeafCondition | SerializedConditionGroup;
 type SerializedRule = {
     conditions: SerializedConditionGroup;
     event: {
@@ -269,6 +287,13 @@ export type SerializedAdvancementPolicy = {
     defaultEventParamsJson: Record<string, unknown> | null;
     allowedEventTypes: AdvancementEventType[];
 };
+/**
+ * Serializes an authored `RuleCondition` (leaf or `all`/`any` group) to its
+ * bare wire format — no outcome attached. Reused directly by `choice`'s
+ * `choices[].when`, `loop`'s `until`, and `step`'s `blockWhen` (see
+ * `SerializedCondition`'s own doc comment).
+ */
+export declare function serializeCondition(condition: RuleCondition): SerializedCondition;
 export declare function serializeAdvancementPolicy(policy: AdvancementPolicy | undefined): SerializedAdvancementPolicy;
 /** Wire-format computed signal definition emitted on the pipeline step. */
 export type SerializedComputedSignalDefinition = {

package/dist/definitions/advancement-policies/index.js

@@ -52,10 +52,19 @@ function any(conditions, outcome) {
   return { _tag: "rule", mode: "any", conditions, outcome };
 }
 function when(signal2, operator, value, outcome) {
+  const condition = {
+    _tag: "signal",
+    signal: signal2,
+    operator,
+    value
+  };
+  if (outcome === undefined) {
+    return condition;
+  }
   return {
     _tag: "rule",
     mode: "all",
-    conditions: [{ _tag: "signal", signal: signal2, operator, value }],
+    conditions: [condition],
     outcome
   };
 }
@@ -479,6 +488,7 @@ function makeAdvanceAllCtx() {
   };
 }
 export {
+  serializeCondition,
   serializeCohortAdvancementPolicy,
   serializeAdvancementPolicy,
   makeAdvanceEachCtx,

package/dist/definitions/pipelines/bindings.d.ts

@@ -0,0 +1,62 @@
+export type PipelineInputBinding = {
+    source: "pipeline_input";
+    path: string;
+};
+export type WorkItemBinding = {
+    source: "work_item";
+    field: string;
+};
+/** Reads a signal declared by an earlier node, addressed by its state key. */
+export type StepSignalBinding = {
+    source: "step_signal";
+    nodeKey: string;
+    signalKey: string;
+};
+/** Reads an earlier node's whole result output, addressed by its state key. */
+export type StepOutputBinding = {
+    source: "step_output";
+    nodeKey: string;
+};
+export type LiteralBinding = {
+    source: "literal";
+    value: unknown;
+};
+/** Reaches a fan-out's whole cohort (every terminal branch's signals + output). */
+export type SignalsListBinding = {
+    source: "signals_list";
+    nodeKey: string;
+};
+/** A fan-out's own per-branch item — see `FanOutNodeInputCtx`. */
+export type FanOutItemBinding = {
+    source: "fan_out_item";
+};
+export type AnyBinding = PipelineInputBinding | WorkItemBinding | StepSignalBinding | StepOutputBinding | LiteralBinding | SignalsListBinding | FanOutItemBinding;
+export type SerializedBinding = {
+    source: "pipeline_input";
+    path: string;
+} | {
+    source: "work_item";
+    field: string;
+} | {
+    source: "step_signal";
+    stepKey: string;
+    signalKey: string;
+} | {
+    source: "step_output";
+    stepKey: string;
+} | {
+    source: "literal";
+    value: unknown;
+} | {
+    source: "signals_list";
+    stepKey: string;
+} | {
+    source: "fan_out_item";
+};
+/**
+ * Builds the wire `inputBindingsJson` for any working node: `workItemTitle`/
+ * `workItemDescription` are always auto-bound (mirroring the retired
+ * builder's own behavior), then overridden/extended by whatever the
+ * author's `input` mapper returned.
+ */
+export declare function serializeInputBindings(input: Partial<Record<string, AnyBinding | undefined>>): Record<string, SerializedBinding>;

package/dist/definitions/pipelines/builder-helpers.d.ts

@@ -1,40 +1,19 @@
-import { z, type ZodType } from "zod";
-import { type AdditionalStepInputBinding, type TypedStepDefinitionSpec } from "../steps/define-step";
-import { type AnyBinding, type FanOutItemBinding, type LiteralBinding, type SignalsListBinding, type StepOutputBinding, type StepSignalBinding, type WorkItemBinding } from "./define-pipeline";
-import { type InputAccessor } from "./input-accessor";
+import type { TypedStepDefinitionSpec } from "../steps/define-step";
+import { type AnyBinding, type LiteralBinding, type WorkItemBinding } from "./define-pipeline";
 import { type WorkItemTopLevelField } from "./work-item-fields";
 export type AnyTypedStep = TypedStepDefinitionSpec<any, any, any, any>;
-type ElementOf<T extends ReadonlyArray<unknown>> = T extends ReadonlyArray<infer U> ? U : never;
-export type LastStep<T extends ReadonlyArray<AnyTypedStep>> = T extends readonly [...AnyTypedStep[], infer L] ? L extends AnyTypedStep ? L : never : never;
-export type LastSignalKeys<T extends ReadonlyArray<AnyTypedStep>> = LastStep<T> extends AnyTypedStep ? LastStep<T>["__signalKeys"] : never;
-/**
- * The per-branch `item` type a fan-out's `over` key resolves to (issue
- * #167): `never` unless `K` names a signal on the most recent ordinary step
- * (`LastStep<TSteps>`) whose resolved TS type is itself an array — in which
- * case this is that array's element type. A number-typed signal (count-only
- * mode) resolves to `never`, which is how `FanOutInputCtx` below decides
- * whether `item` exists on the ctx type at all.
- */
-export type FanOutItemType<TSteps extends ReadonlyArray<AnyTypedStep>, K extends string> = K extends keyof LastStep<TSteps>["__signalTypeMap"] ? LastStep<TSteps>["__signalTypeMap"][K] extends ReadonlyArray<infer Item> ? Item : never : never;
-/**
- * A fan-out's own `input` mapper ctx: everything `StepInputCtx` already
- * offers, plus `item` when `FanOutItemType` resolves to something other
- * than `never`. `item`'s exposed type is intersected with `FanOutItemBinding`
- * (the same "phantom binding" trick `WithWorkItemFields`/`InputAccessor`
- * use elsewhere in this file) so it reads as the real per-item TS type
- * (e.g. `string`) to callers while still structurally satisfying `AnyBinding`
- * when assigned straight into a `FanOutInputMapping` field — at runtime it
- * is always the single `{ source: "fan_out_item" }` binding object,
- * regardless of `Item`'s shape.
- */
-export type FanOutInputCtx<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, K extends string> = StepInputCtx<TInput, TSteps, TFanOuts> & (FanOutItemType<TSteps, K> extends never ? unknown : {
-    item: FanOutItemBinding & FanOutItemType<TSteps, K>;
-});
 export type IsAny<T> = 0 extends 1 & T ? true : false;
+export type RequiredInputKeys<T extends object> = {
+    [K in keyof T & string]-?: undefined extends T[K] ? never : K;
+}[keyof T & string];
+export type OptionalInputKeys<T extends object> = {
+    [K in keyof T & string]-?: undefined extends T[K] ? K : never;
+}[keyof T & string];
 /**
- * Work-item accessor for `additionalPipelineInput.bindings(({ workItem }) => ...)`:
- * a top-level property (`workItem.title`, `workItem.platform`,
- * `workItem.url`, ...) for every member of `WORK_ITEM_TOP_LEVEL_FIELDS`, plus
+ * Work-item accessor for a `step`/`fanOut`/`loop`/parallel-branch state's
+ * `input` mapper (`ctx.workItem`, `NodeInputCtx` in `node-input-ctx.ts`): a
+ * top-level property (`workItem.title`, `workItem.platform`, `workItem.url`,
+ * ...) for every member of `WORK_ITEM_TOP_LEVEL_FIELDS`, plus
  * `workItem.field(name)` for the platform-specific `fields` bag.
  *
  * Mirrors the default-pipeline-assignment DSL's `WorkItemAssignmentAccessor`
@@ -57,78 +36,12 @@ export type WorkItemAccessor = {
 } & {
     field<TName extends string = string>(fieldName: TName): WorkItemBinding;
 };
-export type PinnedWorkItemComment = {
-    createdAt: string;
-    body: string;
-};
-export type WithWorkItemFields<T> = {
-    workItemTitle: string;
-    workItemDescription: string | null;
-    workItemComments: PinnedWorkItemComment[];
-} & T;
-export type RequiredInputKeys<T extends object> = {
-    [K in keyof T & string]-?: undefined extends T[K] ? never : K;
-}[keyof T & string];
-export type OptionalInputKeys<T extends object> = {
-    [K in keyof T & string]-?: undefined extends T[K] ? K : never;
-}[keyof T & string];
-type Prettify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-export type StepInputCtx<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep> = []> = {
-    input: InputAccessor<Prettify<WithWorkItemFields<TInput["_output"]>>>;
-    signal: <S extends ElementOf<TSteps>>(step: S, key: S["__signalKeys"]) => StepSignalBinding;
-    output: (step: ElementOf<TSteps>) => StepOutputBinding;
-    literal: (value: unknown) => LiteralBinding;
-    /**
-     * Reaches a fan-out's whole cohort — every terminal branch's own signals
-     * + output, resolved server-side — from a later, non-adjacent step's
-     * input mapper (issue #167). `fanOutStep` is constrained to a fan-out
-     * step already seen earlier in this pipeline (`.fanOutStep(fanOutStep, ...)`),
-     * the same way `signal`/`output` are constrained to `TSteps`.
-     */
-    signalsList: (fanOutStep: ElementOf<TFanOuts>) => SignalsListBinding;
-};
-type ReservedPipelineInputKeys = "workItemTitle" | "workItemDescription" | "workItemComments";
-export type NoReservedKeys<T extends ZodType> = T extends {
-    shape: infer Shape;
-} ? [keyof Shape & ReservedPipelineInputKeys] extends [never] ? T : never : T;
-export type PipelineMeta<TInput extends ZodType = z.ZodUnknown> = {
-    key: string;
-    name: string;
-    description?: string;
-    version?: number;
-    status?: "draft" | "active";
-    additionalPipelineInput?: {
-        schema: NoReservedKeys<TInput>;
-        bindings: (ctx: {
-            workItem: WorkItemAccessor;
-            literal: (value: unknown) => LiteralBinding;
-        }) => TInput["_output"] extends object ? {
-            [K in RequiredInputKeys<TInput["_output"]>]: AnyBinding;
-        } & {
-            [K in OptionalInputKeys<TInput["_output"]>]?: AnyBinding;
-        } : Partial<Record<string, AnyBinding>>;
-    };
-    additionalStepInput?: {
-        schema: ZodType;
-        bindings: (ctx: {
-            /**
-             * References a platform-specific field (Jira custom field, GitHub
-             * label, etc.) in the work item's `fields` bag. `TName` optionally
-             * accepts a literal union of known field names (e.g. the generated
-             * `WorkItemFieldName`) for compile-time validation and autocomplete,
-             * exactly like `WorkItemAccessor.field` above.
-             */
-            workItemField: <TName extends string = string>(fieldName: TName) => WorkItemBinding;
-            literal: (value: unknown) => LiteralBinding;
-        }) => Partial<Record<string, AdditionalStepInputBinding>>;
-    };
-};
 export declare const WORK_ITEM_ACCESSOR: WorkItemAccessor;
-export declare function makeStepInputCtx<TInput extends ZodType>(inputSchema: TInput): StepInputCtx<TInput, ReadonlyArray<AnyTypedStep>, ReadonlyArray<AnyTypedStep>>;
 export declare function literal(value: unknown): LiteralBinding;
-export declare function normalizeInputMapping(mapping: Record<string, AnyBinding | undefined> | undefined): Record<string, AnyBinding> | undefined;
-export declare function resolveAdditionalStepInputBindings(label: "additionalStepInput", definition: PipelineMeta["additionalStepInput"] | undefined): Record<string, AnyBinding>;
-export declare function mergeStepBindings(pipelineBindings: Record<string, AnyBinding>, explicitBindings: Record<string, AnyBinding> | undefined): Record<string, AnyBinding> | undefined;
-export {};
+/**
+ * Strips `undefined` values out of a node's `input` mapper return value —
+ * an author may return `{ foo: someCondition ? binding : undefined }` to
+ * conditionally omit a field, which should not become a real
+ * `{foo: undefined}` wire entry.
+ */
+export declare function normalizeInputMapping(mapping: Record<string, AnyBinding | undefined> | undefined): Record<string, AnyBinding>;

package/dist/definitions/pipelines/chain-graph.d.ts

@@ -1,19 +1,20 @@
 import type { DependencyEdgeSpec, NodeDefinitionSpec } from "./define-pipeline";
 /**
- * Orders `nodeDefinitions` by walking `dependencyEdges` from the single root
- * to the single leaf. Returns `null` (does not throw) on any structural
- * problem: multiple roots, a node with more than one outgoing edge, a node
- * with more than one incoming edge, a cycle, or a disconnected node.
+ * Computes, for every node key, the longest-path-from-root depth ("topo
+ * rank") over the given edges, using Kahn's algorithm — identical in
+ * approach to `packages/core`'s own `computeTopoRanks`. Returns `null`
+ * (does not throw) if the graph contains a cycle, or if `dependencyEdges`
+ * references a node key outside `nodeDefinitions` (a malformed/hand-edited
+ * spec) — every caller here is a diagnostic tool, not a build-time
+ * assertion, so it degrades gracefully rather than crashing the whole
+ * validation pass.
  */
-export declare function tryOrderChainNodeDefinitions(nodeDefinitions: readonly NodeDefinitionSpec[], dependencyEdges: readonly DependencyEdgeSpec[]): NodeDefinitionSpec[] | null;
+export declare function tryComputeTopoRanks(nodeDefinitions: readonly Pick<NodeDefinitionSpec, "nodeKey">[], dependencyEdges: readonly DependencyEdgeSpec[]): Map<string, number> | null;
 /**
- * Builds one dependency edge between each consecutive pair of `orderedNodes`,
- * in the order given. Used to synthesize a chain's edges from an already-known
- * author order (e.g. declaration order in `.step()` calls).
+ * `tryComputeTopoRanks`, ordering `nodeDefinitions` by ascending rank (ties
+ * broken by declaration order) instead of returning the raw rank map —
+ * the shape `validate-definition-specs.ts`'s "runs before its consumer"
+ * check wants directly. Returns `null` under the same conditions
+ * `tryComputeTopoRanks` does.
  */
-export declare function buildChainDependencyEdges(orderedNodes: readonly Pick<NodeDefinitionSpec, "nodeKey">[]): DependencyEdgeSpec[];
-/**
- * `tryOrderChainNodeDefinitions`, but throws a descriptive error instead of
- * returning `null` when the graph isn't a single valid chain.
- */
-export declare function orderChainNodeDefinitions(nodeDefinitions: readonly NodeDefinitionSpec[], dependencyEdges: readonly DependencyEdgeSpec[]): NodeDefinitionSpec[];
+export declare function tryOrderNodeDefinitionsByTopoRank(nodeDefinitions: readonly NodeDefinitionSpec[], dependencyEdges: readonly DependencyEdgeSpec[]): NodeDefinitionSpec[] | null;

package/dist/definitions/pipelines/compile-node-definitions.d.ts

@@ -0,0 +1,27 @@
+import type { AnyTypedStep } from "./builder-helpers";
+import type { DependencyEdgeSpec, NodeDefinitionSpec } from "./define-pipeline";
+import type { ChoiceState, FanOutState, LoopState, ParallelState, StepState } from "./pipeline-states";
+export type CompileContext = {
+    pipelineKey: string;
+    stateKeys: ReadonlySet<string>;
+    registerStep: (step: AnyTypedStep) => void;
+};
+export type CompiledState = {
+    nodeDefinitions: NodeDefinitionSpec[];
+    edges: DependencyEdgeSpec[];
+};
+export declare function assertTargetExists(ctx: CompileContext, fromKey: string, toKey: string): void;
+export declare function compileStepState(stateKey: string, state: StepState, ctx: CompileContext): CompiledState;
+export declare function compileChoiceState(stateKey: string, state: ChoiceState, ctx: CompileContext): CompiledState;
+export declare function compileFanOutState(stateKey: string, state: FanOutState, ctx: CompileContext): CompiledState;
+export declare function compileParallelState(stateKey: string, state: ParallelState, ctx: CompileContext): CompiledState;
+export declare function compileLoopState(stateKey: string, state: LoopState, ctx: CompileContext): CompiledState;
+export declare function compileTerminalState(stateKey: string, kind: "succeed" | "fail"): CompiledState;
+/**
+ * The SDK-side mirror of §6's domain invariant: a node may have more than
+ * one incoming edge only when every source is a `choice`/`loop` state
+ * (never an unconditional `step`/`fanOut`/`parallel`/`cohortGate`
+ * successor) — gives authors a fast local error instead of a round-trip to
+ * the server.
+ */
+export declare function assertNoIllegalConvergentEdges(pipelineKey: string, nodeKindByKey: ReadonlyMap<string, NodeDefinitionSpec["kind"]>, edges: readonly DependencyEdgeSpec[]): void;