packages/core/block-flows · Developer Docs

PLAN_FLOWS seen through the block contract (block-contract.mjs), by DERIVING a block from each flow entry rather than rewriting the registry: PLAN_FLOWS, validatePlan and planToCommand are untouched, so a plan means e...

Core engine, next. Source: packages/core/block-flows.mjs.

Variables#

processLifecycleBlock#

const processLifecycleBlock: Block

Defined in: packages/core/block-flows.mjs:191

The process lifecycle as a contract block: read-only (empty scope), and its actions are the person-facing events the state machine accepts in state.state (allowedEvents), so the menu is the machine's own answer, never a copy of it. run(scope, { event, state, context }) refuses an event the machine does not accept there.

SCOPE_KINDS#

const SCOPE_KINDS: readonly string[]

Defined in: packages/core/block-flows.mjs:23

How a flow's scope is known: empty (read-only), derived (plan-touches.mjs computes the files) or declared (the plan step must say).

Functions#

argProblem()#

argProblem(flowId, args, executor, touches?): string

Defined in: packages/core/block-flows.mjs:69

First reason args is not runnable by executor, from validatePlan itself (so the menu, a chooser option and the validator cannot disagree), or null. Checks the arguments only: a writing flow is given the supplied touches, or an empty scope, because declaring scope is the approval gate's job.

Parameters#

flowId

string

A key of PLAN_FLOWS.

args

any

The step's arguments.

executor

string

The executor tag the step would carry (deterministic, local-model, user).

touches?

DeclaredScope

The step's declared scope, when there is one.

Returns#

string

The first validatePlan message about the step, or null when the arguments are accepted.

Example#

argProblem('create.feature', {}, 'deterministic'); // => 'Flow "create.feature" requires the "name" argument.'

flowBlock()#

flowBlock(flowId): Block

Defined in: packages/core/block-flows.mjs:131

The contract block derived from one PLAN_FLOWS entry. run(scope, args, ctx) needs ctx.root (project root) and ctx.exec({ argv, stdin, cwd, step }) (the caller's executor, sync or async, the same seam as the process engine's executeStep); it reports the files whose content changed between a before and an after snapshot of the project, so the answer does not depend on the executor's honesty. ctx.executor picks the step's executor tag (default deterministic).

Parameters#

flowId

string

A key of PLAN_FLOWS.

Returns#

Block

A frozen block.

Throws#

For an unknown flow.

Example#

const block = flowBlock('create.unit');
block.declaredScope({ layer: 'domain', name: 'Cart', feature: 'cart' }, { root });

flowBlocks()#

flowBlocks(): Record<string, Block>

Defined in: packages/core/block-flows.mjs:168

Every PLAN_FLOWS entry as a contract block, keyed by flow id. Built once, in registry order.

Returns#

Record<string, Block>

A frozen map of flow id to block.

Example#

Object.keys(flowBlocks()).length === Object.keys(PLAN_FLOWS).length; // => true

flowScopeKind()#

flowScopeKind(flowId): "empty" | "derived" | "declared"

Defined in: packages/core/block-flows.mjs:35

Classify a flow by how its declared scope is known.

Parameters#

flowId

string

A key of PLAN_FLOWS.

Returns#

"empty" | "derived" | "declared"

empty for a read-only flow, derived when plan-touches derives its files, else declared.

Throws#

For an unknown flow.

Example#

flowScopeKind('create.unit'); // => 'derived'