Skip to content

feat(codegen): put operations in subgroups of api with names.groups - #661

Merged
leemour merged 1 commit into
mainfrom
feat/api-subgroups
Nov 19, 2026
Merged

leemour merged 1 commit into
mainfrom
feat/api-subgroups

Conversation

@leemour

@leemour leemour commented Nov 19, 2026

Copy link
Copy Markdown
Member

Task

Owner decision NEED-2754 B: a generated CLI's api group stops being one flat list. A tag (a Postman folder) becomes a subgroup: api <group> <command>.

Why

A flat list of 100–500 operations is hard to read in help and hard for an agent to search. A group per resource follows the service's own reference, and one key (api.contacts) can then cover a resource.

What

  • names.groups: "tags" | "first-word" in generate writes group into each manifest operation. "first-word" is for specs whose tags name no resource (HubSpot's Basic/Batch, Linear's query/mutation). names.groupNames renames a group, or keeps it flat with "".
  • A group of one operation and an untagged operation stay flat.
  • Generation stops on a group named list/show/help, on a group named like a command (its old flat key would then cover the whole group), and on two operations on one path.
  • apiCommandPath(operation): the words after api (contacts-list in contacts → contacts list).
  • The skill's api-<group>.md files follow group when there is one.
  • wp-json routes get their resource as a tag (posts).
  • Docs: WC-CMD-33, plus WC-CMD-8's exception (the old flat permission key stays as an alias that only tightens; the old path breaks). Updated kit-surface.md.
  • Opt-in: a manifest generated without names.groups does not change.

cli-core mounts the groups in a companion PR (feat/api-subgroups). Design note: cli-private plans/2026-11-19-api-subgroups.md.

Testing

vitest run src/codegen (180 pass, new groups.test.ts), typecheck, biome check ., docs:check.

🤖 Generated with Claude Code

A flat api of a hundred operations is hard to read and to search. With
names.groups the generator writes each operation's group into the
manifest: its first tag (a Postman folder is one), or the first word of
its command for a spec whose tags name no resource. groupNames renames a
group or keeps it flat. A lone operation and an untagged one stay flat.
Generation stops on a group named list, show or help, a group named like
a command (its old key would cover the whole group), and two operations
on one path. apiCommandPath gives the words after api; the skill files
follow the groups; wp-json routes get their resource as a tag.

The rule is WC-CMD-33, with WC-CMD-8's exception for the old flat key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit 008a108 into main Nov 19, 2026
10 checks passed
@leemour
leemour deleted the feat/api-subgroups branch November 19, 2026 04:21
leemour added a commit to WireCatLabs/cli-core that referenced this pull request Nov 19, 2026
…command> (#3141)

## Task

Owner decision NEED-2754 B: a generated CLI's `api` group stops being
one flat list. This PR is the cli-core half. The cli-base half (the
manifest's `group`, `names.groups`) is WireCatLabs/cli-base#661, merged.

## Why

A flat `api` of 100–500 operations is hard to read and to search.
Grouping by resource follows the service's own reference, and one key
(`api.contacts`) can then cover a resource.

## What

- `generatedApiCommand` mounts an operation whose manifest has a `group`
as `api <group> <command>`, without the repeated word (`contacts-list` →
`api contacts list`). It reads `group` as an optional field, so cli-core
keeps working with the published cli-base 0.118 pin. A manifest without
groups mounts flat, exactly as before.
- It refuses a group and an operation that share a name
(`configuration_error`).
- `serviceApiCommand`: the key is the path (`api.contacts.list`).
`alsoChecks`, the delete defaults, `--all` and the schema loading follow
the path through a new `configure` hook, not a flat name lookup.
- **Old key alias, only tightens:** a profile that still names
`api.contacts-list` keeps its hold on that one command. The key is
known, so the unknown-key check does not refuse the config. It is
checked beside the new key through the keyed guard: `deny` refuses,
`ask` asks, `readonly` stops a write. Its `allow` lifts nothing. Each
call warns to rename it. `--dry-run` shows it as a conditional key.
- The old path `api contacts-list` stops working (WC-CMD-8).
- `api list` prints the path and a `group` column. `api show` takes the
quoted path, the old name or the id. It is still one argument, so its
MCP input schema does not change.
- Changelog: `changes/feat-api-subgroups.md` (Added).

The rule is WC-CMD-33 in cli-base. Design: cli-private
`plans/2026-11-19-api-subgroups.md` (branch `plans/hubspot-cli`).

## Testing

- New `src/cli/service-api-groups.test.ts`: mounting, keys by path, the
alias (deny, allow under a group deny, readonly on a read and on a
write), list and show, `--dry-run` keys, and the clash refusal.
- `vitest run` of `src/cli/service-api*`, `src/cli/bot`, `src/mcp`,
`profile-site`, `kit/own-catalogue`: 547 pass.
- `typecheck`, `docs:check`, and biome on the changed files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@leemour leemour mentioned this pull request Nov 19, 2026
leemour added a commit that referenced this pull request Nov 19, 2026
Dates the Unreleased section as 0.123.0: the content CLI's words (#662),
which cli-core's renamed content commands need for `cli-dev lint`.

Also moves the `names.groups` entry (#661) out of the 0.121.0 section.
It merged after 0.122.0 shipped, so it ships now.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant