Property (+ JSONSchema emitter) #198

New issue

Closed

opened 2026-07-07 08:28:18 +00:00 by coilysiren · 2 comments

coilysiren commented

2026-07-07 08:28:18 +00:00

Owner

Scope (PR2 of the cli-guard#196 split - the input-schema surface)

Add the transport-neutral input-schema exposure to http/opcore. Blocked on PR1 (the extraction). Independent of PR3 once PR1 lands.

Add to `http/opcore`

type Schema struct {
    Properties map[string]Property // keyed by field name
    Required   []string
}
type Property struct {
    Type        string // string|boolean|integer|number|array
    Items       string // element type when Type==array
    Location    string // path|query|body|form (neutral hint)
    Description string
}
func (d Descriptor) InputSchema() Schema   // PathParams + Query/Body/Form -> schema
func (s Schema) JSONSchema() []byte         // draft-07 object emitter

Path params → required strings at Location=path.
Query / body / form fields lower exactly as fieldFlagsToCLI already reads them (types + required-ness from the existing Field).
JSONSchema() emits a generic draft-07 object. cli-guard stays MCP-agnostic - it emits generic JSON-schema, never an MCP tool type. The MCP tool wrapper stays in ward-mcp.

specverb describe may optionally consume InputSchema() to render its surface, but that is not required for this PR.

Done

Descriptor.InputSchema() + Schema / Property + JSONSchema() in opcore, with tests covering path-required, query-optional, typed fields, and array items.
No urfave/cli import added to opcore.
ward vet / ward test green.

cli-guard#196 (design), PR1 (the extraction this builds on), ward-mcp#7 (consumes InputSchema to build its MCP tool list).

## Scope (PR2 of the cli-guard#196 split - the input-schema surface) Add the transport-neutral input-schema exposure to `http/opcore`. **Blocked on PR1** (the extraction). Independent of PR3 once PR1 lands. ## Add to `http/opcore` ```go type Schema struct { Properties map[string]Property // keyed by field name Required []string } type Property struct { Type string // string|boolean|integer|number|array Items string // element type when Type==array Location string // path|query|body|form (neutral hint) Description string } func (d Descriptor) InputSchema() Schema // PathParams + Query/Body/Form -> schema func (s Schema) JSONSchema() []byte // draft-07 object emitter ``` - Path params → required strings at `Location=path`. - Query / body / form fields lower exactly as `fieldFlagsToCLI` already reads them (types + required-ness from the existing `Field`). - `JSONSchema()` emits a generic draft-07 object. **cli-guard stays MCP-agnostic** - it emits generic JSON-schema, never an MCP tool type. The MCP tool wrapper stays in ward-mcp. `specverb describe` may optionally consume `InputSchema()` to render its surface, but that is not required for this PR. ## Done - `Descriptor.InputSchema()` + `Schema` / `Property` + `JSONSchema()` in opcore, with tests covering path-required, query-optional, typed fields, and array items. - No urfave/cli import added to opcore. - `ward vet` / `ward test` green. ## Related cli-guard#196 (design), PR1 (the extraction this builds on), ward-mcp#7 (consumes InputSchema to build its MCP tool list).

coilysiren referenced this issue

2026-07-07 08:28:32 +00:00

feat(specverb): transport-neutral engine core + inline-operation source, so ward-mcp (and any non-CLI consumer) drives the same spec/guard engine #196

coilysiren added the

headless

label

2026-07-07 09:07:24 +00:00

coilyco-ops commented

2026-07-07 09:07:34 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-cli-guard-198 on host KAI-DESKTOP-TOWER is carrying this issue (reserved 2026-07-07T09:07:29Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/cli-guard#198 · branch issue-198 · driver claude · workflow direct-main
Run: engineer-claude-cli-guard-198 · ward v0.419.0 · dispatched 2026-07-07T09:07:29Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Issue body as seeded:

## Scope (PR2 of the cli-guard#196 split - the input-schema surface)

Add the transport-neutral input-schema exposure to `http/opcore`. **Blocked on PR1** (the extraction). Independent of PR3 once PR1 lands.

## Add to `http/opcore`

` ` `go
type Schema struct {
    Properties map[string]Property // keyed by field name
    Required   []string
}
type Property struct {
    Type        string // string|boolean|integer|number|array
    Items       string // element type when Type==array
    Location    string // path|query|body|form (neutral hint)
    Description string
}
func (d Descriptor) InputSchema() Schema   // PathParams + Query/Body/Form -> schema
func (s Schema) JSONSchema() []byte         // draft-07 object emitter
` ` `

- Path params → required strings at `Location=path`.
- Query / body / form fields lower exactly as `fieldFlagsToCLI` already reads them (types + required-ness from the existing `Field`).
- `JSONSchema()` emits a generic draft-07 object. **cli-guard stays MCP-agnostic** - it emits generic JSON-schema, never an MCP tool type. The MCP tool wrapper stays in ward-mcp.

`specverb describe` may optionally consume `InputSchema()` to render its surface, but that is not required for this PR.

## Done

- `Descriptor.InputSchema()` + `Schema` / `Property` + `JSONSchema()` in opcore, with tests covering path-required, query-optional, typed fields, and array items.
- No urfave/cli import added to opcore.
- `ward vet` / `ward test` green.

## Related

cli-guard#196 (design), PR1 (the extraction this builds on), ward-mcp#7 (consumes InputSchema to build its MCP tool list).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.419.0).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-cli-guard-198` on host `KAI-DESKTOP-TOWER` is carrying this issue (reserved 2026-07-07T09:07:29Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh** — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/cli-guard#198` · branch `issue-198` · driver `claude` · workflow `direct-main` - **Run:** `engineer-claude-cli-guard-198` · ward `v0.419.0` · dispatched `2026-07-07T09:07:29Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). **Issue body as seeded:** ``` ## Scope (PR2 of the cli-guard#196 split - the input-schema surface) Add the transport-neutral input-schema exposure to `http/opcore`. **Blocked on PR1** (the extraction). Independent of PR3 once PR1 lands. ## Add to `http/opcore` ` ` `go type Schema struct { Properties map[string]Property // keyed by field name Required []string } type Property struct { Type string // string|boolean|integer|number|array Items string // element type when Type==array Location string // path|query|body|form (neutral hint) Description string } func (d Descriptor) InputSchema() Schema // PathParams + Query/Body/Form -> schema func (s Schema) JSONSchema() []byte // draft-07 object emitter ` ` ` - Path params → required strings at `Location=path`. - Query / body / form fields lower exactly as `fieldFlagsToCLI` already reads them (types + required-ness from the existing `Field`). - `JSONSchema()` emits a generic draft-07 object. **cli-guard stays MCP-agnostic** - it emits generic JSON-schema, never an MCP tool type. The MCP tool wrapper stays in ward-mcp. `specverb describe` may optionally consume `InputSchema()` to render its surface, but that is not required for this PR. ## Done - `Descriptor.InputSchema()` + `Schema` / `Property` + `JSONSchema()` in opcore, with tests covering path-required, query-optional, typed fields, and array items. - No urfave/cli import added to opcore. - `ward vet` / `ward test` green. ## Related cli-guard#196 (design), PR1 (the extraction this builds on), ward-mcp#7 (consumes InputSchema to build its MCP tool list). ``` Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.419.0). </details>  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-07 09:13:56 +00:00

feat(opcore) [PR2/3 of #196]: Descriptor.InputSchema() -> neutral Schema/Property (+ JSONSchema emitter)

coilysiren closed this issue

2026-07-07 09:13:56 +00:00

coilysiren commented

2026-07-07 09:14:36 +00:00

Author

Owner

WARD-OUTCOME: done - opcore now exposes Descriptor.InputSchema() -> neutral Schema/Property plus a draft-07 JSONSchema() emitter, tests green, landed on main.

This one was a clean build on PR1. The engine core already carried every input in the Field/PathParams shape, so InputSchema() was mostly a faithful re-projection: path params to required strings, query/body/form lowered the same way fieldFlagsToCLI reads them, and FixedBody deliberately left out since it is never a caller input. Keeping cli-guard MCP-agnostic was the easy call - JSONSchema() emits a plain draft-07 object and the Location hint stays on the struct, out of the emitted document, for ward-mcp to read.

What fought back was the pre-commit gate, not the code: the 2-line contiguous-comment cap trimmed my docstrings twice, and docs/FEATURES.md sits at 3997/4000 chars, so there is no room to mention the new surface there without splitting the doc. I reverted the FEATURES touch rather than bloat past the cap - godoc covers the API fully. Worth a small follow-up: the FEATURES inventory is effectively frozen until someone splits it, so future additive PRs will keep hitting that wall.

Fairly confident in the result - the JSON emitter goes through encoding/json (map keys sort deterministically), required is sorted, and tests cover path-required, query-optional, typed scalars, array items, the no-required case, and fixed-body omission. PR3 will wire specverb describe / ward-mcp onto this.

WARD-OUTCOME: done - opcore now exposes Descriptor.InputSchema() -> neutral Schema/Property plus a draft-07 JSONSchema() emitter, tests green, landed on main. This one was a clean build on PR1. The engine core already carried every input in the `Field`/`PathParams` shape, so `InputSchema()` was mostly a faithful re-projection: path params to required strings, query/body/form lowered the same way `fieldFlagsToCLI` reads them, and `FixedBody` deliberately left out since it is never a caller input. Keeping cli-guard MCP-agnostic was the easy call - `JSONSchema()` emits a plain draft-07 object and the `Location` hint stays on the struct, out of the emitted document, for ward-mcp to read. What fought back was the pre-commit gate, not the code: the 2-line contiguous-comment cap trimmed my docstrings twice, and `docs/FEATURES.md` sits at 3997/4000 chars, so there is no room to mention the new surface there without splitting the doc. I reverted the FEATURES touch rather than bloat past the cap - godoc covers the API fully. Worth a small follow-up: the FEATURES inventory is effectively frozen until someone splits it, so future additive PRs will keep hitting that wall. Fairly confident in the result - the JSON emitter goes through `encoding/json` (map keys sort deterministically), required is sorted, and tests cover path-required, query-optional, typed scalars, array items, the no-required case, and fixed-body omission. PR3 will wire specverb describe / ward-mcp onto this.