T-HQ2D-config-needs

State: closed/done · Impact: medium · Complexity: medium

Goal

Ops that cannot run without a setting in sdlc.yaml (the lease ops and lease_authority) each checked for it by hand, with their own wording and exit code, and nothing listed which settings an op depends on. Make the dependency a declaration on the op descriptor so every op fails the same way, --help shows it, and sdlc project doctor reports gaps before a run hits them.

Today

Location	Role today
solutions/ontological/lib/registry.ts	OpNeed is `‘project'
solutions/ontological/lib/preflight.ts	Probes the three environment needs before a handler runs
solutions/ontological/lib/services/lease/ops/_common.ts	resolveLeaseContext throws its own “no lease authority configured” error
solutions/ontological/lib/services/project/ops/doctor.ts	Probes binaries and the harness install; knows nothing about config

Proposed

needs accepts { config: 'dotted.key', unlessInput?: 'inputKey' }. The preflight reads the key from the hydrated project config, then the machine config, treats empty text/list/map as unset, and fails with one message: the op, the key, the key’s own schema description, and where to set it. Every lease op declares lease_authority with --authority as the stand-in. sdlc <op> --help ends with a Needs: line and sdlc project doctor lists every declared setting with the ops that need it.

Approach

1. Extend OpNeed with ConfigNeed; add configNeedsOf.
2. Add lib/config/describe.ts: value-at-path, is-set, and the schema description for a key (record entries report the record’s).
3. Handle config needs in preflight, taking the op path and raw input.
4. Declare the need on all sixteen lease ops from one constant in _common.ts.
5. Render a Needs: help line in the CLI adapter.
6. Add a config section to project doctor.
7. Update tests whose expectations named the old lease message; document in cli/README.md.

Files to touch

Location	Kind	Change
solutions/ontological/lib/registry.ts	modify	ConfigNeed, configNeedsOf
solutions/ontological/lib/config/describe.ts	new	value/description lookup by dotted key
solutions/ontological/lib/preflight.ts	modify	config-need check and message
solutions/ontological/cli/registry_adapter.ts	modify	pass path/input to preflight; Needs: help line
solutions/ontological/lib/services/lease/ops/	modify	every op declares LEASE_AUTHORITY_NEED
solutions/ontological/lib/services/project/ops/doctor.ts	modify	configNeeds section
solutions/ontological/cli/README.md	modify	document config needs

Acceptance criteria

• AC-1: A lease op run in a project without lease_authority fails before the handler with a message naming the op, the key, the key’s description and the file to set it in; --authority satisfies it.
• AC-2: sdlc lease list --help ends with Needs: lease_authority (sdlc.yaml, or --authority).
• AC-3: sdlc project doctor prints a config section with each declared key, set/UNSET, and the ops that need it; an unset key writes CONFIG-UNSET key=… ops=… to stderr without changing the exit code.
• AC-4: A setting present only in the machine config satisfies a need; an empty list or map does not.

Out of scope

• Needs an op can only know at run time (which paths: token a checkout.layout uses) stay in the handler.
• Listing needs on the generated docs site’s op reference pages.

Result

Shipped as declared. The check, the message and the machine-config loader then moved to packages/ts/toolconfig (@sksizer/toolconfig) so pr-updater, which has the same two files, shares them; sdlc binds the package to its schemas in lib/config/describe.ts.

Dependencies

• none

---

← Back to Tasks