@boboddy/sdk 0.4.3 → 0.5.1

package/dist/definitions/pipelines/node-input-ctx.d.ts

@@ -0,0 +1,31 @@
+import type { ZodType } from "zod";
+import type { DotPaths } from "../steps/define-step";
+import { type WorkItemAccessor } from "./builder-helpers";
+import type { FanOutItemBinding, LiteralBinding, PipelineInputBinding, SignalsListBinding, StepOutputBinding, StepSignalBinding } from "./bindings";
+/**
+ * The `input:` mapper ctx every `step`/`fanOut`/`loop`/parallel-branch
+ * state receives (see docs/research/flat-pipeline-sdk-and-visual-designer.md
+ * §4). Nodes are addressed by their plain string state key rather than a
+ * typed step reference — the flat, forward-only authoring model has no
+ * "tuple of prior steps" to statically check a binding's source/signal
+ * key against (cross-node static proof is explicitly out of scope; see
+ * that doc's §1).
+ */
+export type NodeInputCtx<TInput extends ZodType = ZodType> = {
+    /** Reads a value from the pipeline's own input, by dot-path. */
+    pipelineInput: (path: DotPaths<TInput["_output"]>) => PipelineInputBinding;
+    workItem: WorkItemAccessor;
+    /** Reads a signal declared by an earlier node, addressed by its state key. */
+    signal: (nodeKey: string, signalKey: string) => StepSignalBinding;
+    /** Reads an earlier node's whole result output, addressed by its state key. */
+    output: (nodeKey: string) => StepOutputBinding;
+    /** Reaches a fan-out's whole cohort (every terminal branch's signals + output). */
+    signalsList: (nodeKey: string) => SignalsListBinding;
+    literal: (value: unknown) => LiteralBinding;
+};
+/** `NodeInputCtx`, plus `item` — the current fan-out branch's own item. */
+export type FanOutNodeInputCtx<TInput extends ZodType = ZodType> = NodeInputCtx<TInput> & {
+    item: FanOutItemBinding;
+};
+export declare function makeNodeInputCtx<TInput extends ZodType>(): NodeInputCtx<TInput>;
+export declare function makeFanOutNodeInputCtx<TInput extends ZodType>(): FanOutNodeInputCtx<TInput>;

package/dist/definitions/pipelines/pipeline-definitions-client.d.ts

@@ -1,6 +1,6 @@
 import { PipelineDefinitions } from "../../generated/sdk.gen";
 import type { PutApiPipelineDefinitionsData } from "../../generated/types.gen";
-import type { PipelineDefinitionSpec } from "./define-pipeline";
+import { type PipelineDefinitionSpec } from "./define-pipeline";
 type RequestOptions = {
     headers?: Record<string, unknown> | undefined;
 };
@@ -26,6 +26,7 @@ declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefi
         stepDefinitions: Array<{
             id: string;
             pipelineDefinitionId: string;
+            kind: "step" | "fanOut" | "cohortGate" | "choice" | "parallel" | "loop" | "succeed" | "fail";
             stepDefinitionId: string;
             stepDefinitionVersion: number;
             key: string;
@@ -131,11 +132,23 @@ declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefi
     }[]>;
     /**
      * Upserts a pipeline definition keyed by (projectId, key). Accepts the
-     * `PipelineDefinitionSpec` produced by `pipeline().build()`, along with the
+     * `PipelineDefinitionSpec` produced by `definePipeline()`, along with the
      * list of pushed step definitions (used to resolve `stepDefinitionId` for
-     * each pipeline step).
+     * each node/branch referencing a step by key).
      *
-     * Throws if any pipeline step references a step key/version that isn't
+     * Pushes via the richer `nodeDefinitions[]`/`dependencyEdges[]` graph
+     * shape (see `buildGraphNodeInput`) rather than the old flat,
+     * `position`-ordered `stepDefinitions[]` shape — every node kind
+     * `definePipeline()` can produce (`choice`/`fanOut`/`cohortGate`/
+     * `parallel`/`loop`/`succeed`/`fail`, not just `step`) is representable
+     * this way; the flat shape could only ever represent a `step`-only
+     * chain. The generated `UpsertPipelineDefinitionInput` type doesn't yet
+     * reflect this (it's OpenAPI-codegen'd from the pre-existing flat
+     * contract), so the body is cast at the boundary — the server's zod
+     * schema (`createPipelineDefinitionInputSchema`, extended to accept
+     * either shape) is the real, enforced contract.
+     *
+     * Throws if any node/branch references a step key/version that isn't
      * present in `stepDefs`.
      */
     upsertFromSpec: (projectId: string, spec: PipelineDefinitionSpec, stepDefs: ReadonlyArray<StepDefinitionRef>, options?: RequestOptions) => Promise<{
@@ -152,6 +165,7 @@ declare const buildPipelineDefinitionsClient: (pipelineDefinitions: PipelineDefi
         stepDefinitions: Array<{
             id: string;
             pipelineDefinitionId: string;
+            kind: "step" | "fanOut" | "cohortGate" | "choice" | "parallel" | "loop" | "succeed" | "fail";
             stepDefinitionId: string;
             stepDefinitionVersion: number;
             key: string;

package/dist/definitions/pipelines/pipeline-states.d.ts

@@ -0,0 +1,104 @@
+import type { ZodType } from "zod";
+import type { RuleCondition } from "../advancement-policies/define-advancement-policy";
+import type { AdvanceAllCtx, AdvanceAllResult, AdvanceEachCtx, AdvanceEachResult } from "../advancement-policies/cohort-fluent-rules";
+import type { AnyTypedStep } from "./builder-helpers";
+import type { AnyBinding } from "./bindings";
+import type { FanOutNodeInputCtx, NodeInputCtx } from "./node-input-ctx";
+/**
+ * The 7 authoring state kinds (see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §4/§5). Every
+ * kind besides `choice`/`succeed`/`fail` does its own work (a `step`) and
+ * therefore declares exactly one authored `input`/`timeout`; `choice` and
+ * `loop` are the only kinds with more than one possible exit.
+ */
+/** `next: "otherStateKey"`, or a special cross-pipeline route target. */
+export type NextTarget = string | {
+    routeToPipeline: string;
+    input?: Record<string, unknown> | null;
+};
+export type StepState = {
+    kind: "step";
+    step: AnyTypedStep;
+    input?: (ctx: NodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+    /**
+     * A single-condition "pause for human review" gate — the narrow
+     * replacement for the old per-step rules-engine policy object (see §5's
+     * `complete`/`route`/`block` migration notes). When the condition
+     * matches, the node run blocks instead of advancing to `next`.
+     */
+    blockWhen?: RuleCondition;
+    next: NextTarget;
+};
+export type ChoiceCase = {
+    when: RuleCondition;
+    next: string;
+};
+export type ChoiceState = {
+    kind: "choice";
+    /** At least one of `choices`/`default` is required — see `compileChoiceState`. */
+    choices?: ReadonlyArray<ChoiceCase>;
+    default?: string | null;
+};
+export type FanOutState = {
+    kind: "fanOut";
+    step: AnyTypedStep;
+    /**
+     * The signal to resolve branch cardinality (and, in array mode, each
+     * branch's own item) from. A bare signal key (`"changedFiles"`) or a
+     * `"stateKey.signalKey"` dotted convenience form — the dotted prefix is
+     * author-facing documentation only; the runtime resolves the signal by
+     * scanning every upstream node's own signals for a matching key (see
+     * `resolveFanOutCardinality`), not by an explicit node reference.
+     */
+    over: string;
+    maxConcurrency?: number | null;
+    input?: (ctx: FanOutNodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+    advanceEach: (ctx: AdvanceEachCtx) => AdvanceEachResult;
+    advanceAll: (ctx: AdvanceAllCtx) => AdvanceAllResult;
+    next: string;
+};
+export type ParallelBranchConfig = {
+    step: AnyTypedStep;
+    input?: (ctx: NodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+};
+export type ParallelState = {
+    kind: "parallel";
+    /** Named branches (v1: single-step only — see decision 5). */
+    branches: Record<string, ParallelBranchConfig>;
+    /** Defaults to "continue iff every branch continued" when omitted. */
+    advanceAll?: (ctx: AdvanceAllCtx) => AdvanceAllResult;
+    next: string;
+};
+export type LoopState = {
+    kind: "loop";
+    step: AnyTypedStep;
+    maxIterations: number;
+    input?: (ctx: NodeInputCtx) => Partial<Record<string, AnyBinding>>;
+    timeout?: number | null;
+    until: RuleCondition;
+    next: string;
+    onExhausted: string;
+};
+export type SucceedState = {
+    kind: "succeed";
+};
+export type FailState = {
+    kind: "fail";
+};
+export type PipelineState = StepState | ChoiceState | FanOutState | ParallelState | LoopState | SucceedState | FailState;
+export type DefinePipelineInput<TInput extends ZodType = ZodType> = {
+    key: string;
+    name?: string;
+    description?: string | null;
+    version?: number;
+    status?: "draft" | "active";
+    /** The pipeline's own input schema — drives `ctx.pipelineInput(path)`'s typing and `inputSchemaJson`. */
+    input?: TInput;
+    /** The entry state's key. Must not name a `choice`/`succeed`/`fail` state. */
+    startAt: string;
+    /** Every state in the pipeline, keyed by its unique node key. */
+    states: Record<string, PipelineState>;
+};

package/dist/definitions/steps/define-code-step.d.ts

@@ -0,0 +1,50 @@
+import type { ZodType } from "zod";
+import type { SignalKeysOf, SignalTypeMapOf, TypedStepDefinitionSpec } from "./define-step";
+/**
+ * `codeStep()`'s own signal spec shape — unlike `defineStep()`'s
+ * `SignalSpecInput`, `type` is required rather than inferred from the
+ * result schema at a dot-path (`resolveZodSchemaAtPath`/
+ * `zodTypeToSignalType` are `define-step.ts`-internal, and a code step's
+ * result shape is arbitrary application data, not necessarily reflecting
+ * one at all) — a small, deliberate simplification over `defineStep`'s own
+ * signal authoring surface.
+ */
+export type CodeStepSignalSpec = {
+    key?: string;
+    sourcePath: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    required?: boolean;
+    availableWhenResultStatusIn?: string[] | null;
+};
+export type CodeStepFn<TInput, TResult> = (input: TInput) => TResult | Promise<TResult>;
+export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType> = {
+    key: string;
+    name: string;
+    description?: string | null;
+    version?: number;
+    /**
+     * The step's own implementation — resolved by `collect-definitions.ts`
+     * to a portable `{sourceFile, exportName}` pair (by identity-matching
+     * this reference against the declaring module's other exports) before
+     * the (unserializable) function reference is ever sent over the wire.
+     * Must be a plain named export of the same module `codeStep()` is
+     * called from (see docs/research/flat-pipeline-sdk-and-visual-designer.md
+     * §7.7/§8's "code-step entrypoints resolve against the target repo").
+     */
+    fn: CodeStepFn<TInput["_output"], TResult["_output"]>;
+    inputSchema?: TInput;
+    resultSchema?: TResult;
+    signals?: readonly CodeStepSignalSpec[];
+    status?: "draft" | "active";
+};
+/**
+ * Defines a `kind: "code"` step: a plain function instead of an LLM
+ * prompt. Produces the same phantom-typed `TypedStepDefinitionSpec` shape
+ * `defineStep()` does (so it plugs into `definePipeline()`'s
+ * `states[key].step` field unchanged), but with no `prompt` and a live
+ * `entrypoint.fn` reference attached instead — see `StepDefinitionSpec`'s
+ * own doc comment for what happens to it during collection.
+ */
+export declare function codeStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TSignals extends ReadonlyArray<CodeStepSignalSpec> = never[]>(config: DefineCodeStepInput<TInput, TResult> & {
+    signals?: TSignals;
+}): TypedStepDefinitionSpec<TInput["_output"], TResult["_output"], SignalKeysOf<TSignals>, SignalTypeMapOf<TSignals, TResult["_output"]>>;

package/dist/definitions/steps/define-step.d.ts

@@ -108,12 +108,21 @@ export type AdditionalStepInputLiteralBinding = LiteralBinding;
  * coincidence, not by design.
  */
 export type AdditionalStepInputBinding = WorkItemBinding | LiteralBinding;
+/**
+ * A `kind: "code"` step's portable entrypoint, once resolved by
+ * `collect-definitions.ts`'s identity-capture pass — see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §7.7/§8.
+ */
+export type StepDefinitionEntrypointJson = {
+    sourceFile: string;
+    exportName: string;
+};
 export type StepDefinitionSpec = {
     key: string;
     name: string;
     description: string | null;
     version: number;
-    kind: "user_defined";
+    kind: "user_defined" | "code";
     status: "draft" | "active" | "archived";
     executionMode?: "workspace" | "no_workspace";
     prompt: string | null;
@@ -129,6 +138,18 @@ export type StepDefinitionSpec = {
     opencodeMcpJson: OpenCodeMcpServers | null;
     opencodePluginJson: OpenCodePlugins | null;
     healthChecksJson: HealthChecks | null;
+    /**
+     * `kind === "code"` only, and only *before* collection —
+     * `collect-definitions.ts` resolves this live `fn` reference down to
+     * `entrypointJson` (by identity-matching against the declaring module's
+     * other exports) and strips this field before the spec is ever pushed;
+     * it can never be serialized into the push request.
+     */
+    entrypoint?: {
+        fn: (input: unknown) => unknown;
+    };
+    /** `kind === "code"` only, present after `collect-definitions.ts` has run. */
+    entrypointJson?: StepDefinitionEntrypointJson | null;
 };
 export type SignalTypeStrToTs<T extends SignalTypeStr> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "array" ? unknown[] : T extends "object" ? object : unknown;
 export type SignalTypeMapOf<TSignals extends readonly unknown[], TResult> = Prettify<{

package/dist/definitions/steps/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./define-step";
+export * from "./define-code-step";
 export * from "./prompt-template";
 export * from "./step-definitions-client";
 export * from "./step-features";