#1063 - Flows YAML — op registry with per-op typed context - charles/claude-hooks

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#1063

claude-desktop commented

2026-05-10 15:38:49 +00:00

Collaborator

User story

As a maintainer, I want each flow operation to declare its own dependencies via a typed ctx parameter, so that adding a new op is a single new file with no edits to a central injection bundle.

Resolves audit finding §1.1.2 (injection bundle bloat, defaultArgInjections 100-line god function).

Acceptance criteria

Op interface

Operation type in apps/server/src/domain/flows-yaml/op-types.ts with: name, argsSchema (Zod), outputsSchema (Zod), run(ctx, args) => Promise<output>, deps (string array of capability keys).
Op modules under apps/server/src/domain/flows-yaml/ops/<name>.ts, one per file.
Index file aggregates ops into a Record<string, Operation> registry.

Context composition

buildOpContext(op, env) returns only the capabilities listed in op.deps.
Capability sources: workers, mcp client, db, logger, dedup store, agent-resolver, expression evaluator.
Tests can substitute a fake context per op without touching others.

Wiring

Executor calls op.run(ctx, parsedArgs) with argsSchema parse + interpolation already applied.
Output validated against outputsSchema before being stored under steps.<id>.outputs.

Migration shim

Legacy defaultArgInjections keeps working unchanged for the existing JSON node engine during shadow mode.
After cutover (#flows-14) the shim + injection bundle are deleted.

Tests

Unit: op runs with a fake ctx; missing-capability ctx panics with clear message.
Lint rule (or PR-checklist note) preventing direct imports from outside the registry.

Out of scope

Authoring the actual ops (covered by #flows-6 + #flows-7).
Plugin / external-op loading.

References

Spec: docs/specs/flows-yaml.md §9.
Replaces: defaultArgInjections() at apps/server/src/domain/flows/flow-dispatch.ts:113–218.

## User story As a maintainer, I want each flow operation to declare its own dependencies via a typed `ctx` parameter, so that adding a new op is a single new file with no edits to a central injection bundle. Resolves audit finding §1.1.2 (injection bundle bloat, `defaultArgInjections` 100-line god function). ## Acceptance criteria ### Op interface - [ ] `Operation` type in `apps/server/src/domain/flows-yaml/op-types.ts` with: `name`, `argsSchema` (Zod), `outputsSchema` (Zod), `run(ctx, args) => Promise<output>`, `deps` (string array of capability keys). - [ ] Op modules under `apps/server/src/domain/flows-yaml/ops/<name>.ts`, one per file. - [ ] Index file aggregates ops into a `Record<string, Operation>` registry. ### Context composition - [ ] `buildOpContext(op, env)` returns only the capabilities listed in `op.deps`. - [ ] Capability sources: workers, mcp client, db, logger, dedup store, agent-resolver, expression evaluator. - [ ] Tests can substitute a fake context per op without touching others. ### Wiring - [ ] Executor calls `op.run(ctx, parsedArgs)` with `argsSchema` parse + interpolation already applied. - [ ] Output validated against `outputsSchema` before being stored under `steps.<id>.outputs`. ### Migration shim - [ ] Legacy `defaultArgInjections` keeps working unchanged for the existing JSON node engine during shadow mode. - [ ] After cutover (#flows-14) the shim + injection bundle are deleted. ### Tests - [ ] Unit: op runs with a fake ctx; missing-capability ctx panics with clear message. - [ ] Lint rule (or PR-checklist note) preventing direct imports from outside the registry. ## Out of scope - Authoring the actual ops (covered by #flows-6 + #flows-7). - Plugin / external-op loading. ## References - Spec: `docs/specs/flows-yaml.md` §9. - Replaces: `defaultArgInjections()` at `apps/server/src/domain/flows/flow-dispatch.ts:113–218`.

claude-desktop added this to the Flows YAML milestone

claude-desktop

closed this issue
added the
area:flows

type:user-story
labels

Rows
Columns

Flows YAML — op registry with per-op typed context #1063