Skip to content

feat(cli): send a GraphQL operation through the api group and serviceApiCall - #3097

Merged
leemour merged 2 commits into
mainfrom
feat/graphql-executor
Nov 17, 2026
Merged

leemour merged 2 commits into
mainfrom
feat/graphql-executor

Conversation

@leemour

@leemour leemour commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Task

L2 of the source-manifest plan (Linear first). It builds on L1, cli-base #635 (0.115.0): the graphql binding, graphqlDocument and graphqlFake. It follows the agreed contract, "Поправка L1" in source-manifest.md section 6.2.

Why

A manifest generated from a GraphQL schema could not be sent. The api group and serviceApiCall knew only http and rpc bindings, and cli-core did not build against cli-base 0.115.0 (src/cli/bot/api.ts:45 read binding.name).

What

  • cli-base 0.115.0; the peer range is now >=0.115.0 <1.0.0.
  • A GraphQL operation is one POST of its document to the server URL, built by graphqlDocument(binding, selection?).
  • Variables are --body as one object, with each flag over it.
    • Each flag is read by its schema: a number, true/false, JSON for an input object, a bare word for an enum.
    • In the api group the merged variables go through the request schema before anything is sent.
    • A variable the operation does not declare is refused before anything is sent.
  • errors[] is a failure even at HTTP 200.
    • It is named by extensions.code, using Apollo's names (UNAUTHENTICATED, FORBIDDEN, RATELIMITED, BAD_USER_INPUT…); any other code is provider_error.
    • The service's own message is never repeated.
    • A write with partial data says to check before repeating.
  • The answer is data.<field>. --all pages by pageInfo through the existing cursor style. withValue drops a flag of the same name, so later pages ask for the next cursor.
  • ApiCommandInput.selection gives a source a deeper selection than the generated one. The api group never sets it.
  • api list and the run record name a GraphQL operation as query issues or mutation issueCreate.

Not done here

  • No not-found code is mapped: Linear's code for a missing issue(id) is not checked yet. It is noted in the plan for L3/L4 (get → null).
  • errors[] sent with HTTP 400 goes through the usual refusal path, and its extensions.code is lost.

Review

A fresh review found SEC-1/2, BUG-1 to BUG-4, RISK-1 to RISK-3, DEBT-1/2 and NIT-1 to NIT-6. The second commit fixes these:

  • SEC-1: a GraphQL flag is the body, so it stays out of the run's files.
  • SEC-2: a code is repeated only when it is a plain constant.
  • BUG-1: a write whose errors[] does not show it as undone is outcome_unknown.
  • BUG-2: the run log records the failure.
  • BUG-3: the endpoint is named query/issues.
  • BUG-4: digits go as written; 0x10 and 1e1 are refused.
  • RISK-1: a missing required variable is refused unsent, in serviceApiCall too.
  • RISK-2: the credential check runs before the GraphQL branch.
  • RISK-3: a CLI's failure is asked first; rate_limited is retryable.
  • DEBT-1: graphqlVariables moved to api-input.ts.
  • NIT-1: --body 5 gives a clear error.
  • NIT-3: api list shows POST only for GraphQL operations.
  • NIT-5: the POST never follows a redirect.
  • NIT-6: the fragment is complete.

Left as is:

  • NIT-2: a bare null given as a flag is sent as text. Use --body for it.
  • NIT-4: on a 4xx answer the HTTP status decides the error.
  • DEBT-2: the test schemas stay hand-copied, because the generated file imports a types module that a test lacks.

Testing

  • service-api-graphql.test.ts runs on graphqlFake over a manifest generated from a Linear-shaped fixture (copied from cli-base's test fixture). It checks:
    • variables from flags and the body together;
    • errors[] at HTTP 200;
    • a wrong-type flag and an undeclared variable, both refused unsent;
    • --all across two pages;
    • serviceApiCall with a deeper selection;
    • request-schema checks on the merged variables;
    • a mutation's errors[] as validation_error or outcome_unknown;
    • a mutation's flags kept out of the run's files;
    • the run record naming mutation/issueCreate.
  • Typecheck (including tests), lint and docs:check pass.
  • After rebasing on main (with the tracker category, feat(tracker): the tracker category — store version 70, TrackerSource, syncTracker, commands and contract kit #3095), typecheck (including tests), lint, docs:check and the full suite pass (12536 tests).

🤖 Generated with Claude Code

leemour added a commit that referenced this pull request Nov 17, 2026
…s, echoed codes

From the review of #3097: a write that errors[] does not show as undone is outcome_unknown; a GraphQL flag is the
body and stays out of the run's files; the run log records the failure and names the endpoint query/issues; digits
go as written, without 0x or 1e; a code is repeated only when it is a plain constant; a CLI's failure is asked first;
a missing required variable is refused unsent in serviceApiCall too; the POST never follows a redirect; the credential
check comes before the GraphQL branch; graphqlVariables lives in api-input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
leemour and others added 2 commits November 17, 2026 23:05
…ApiCall

L2 of the source-manifest plan, on cli-base 0.115.0's graphql binding. A call is one POST of the document
graphqlDocument builds; the variables are --body with each flag over it, read by its schema, and the request
schema sees them merged. errors[] fails even at HTTP 200, named by extensions.code, never by the message; the
answer is data.<field>. --all pages by pageInfo through the existing cursor style. ApiCommandInput.selection lets
a source ask for more than the generated selection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s, echoed codes

From the review of #3097: a write that errors[] does not show as undone is outcome_unknown; a GraphQL flag is the
body and stays out of the run's files; the run log records the failure and names the endpoint query/issues; digits
go as written, without 0x or 1e; a code is repeated only when it is a plain constant; a CLI's failure is asked first;
a missing required variable is refused unsent in serviceApiCall too; the POST never follows a redirect; the credential
check comes before the GraphQL branch; graphqlVariables lives in api-input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour force-pushed the feat/graphql-executor branch from e6566b5 to e10ff12 Compare November 17, 2026 22:12
@leemour
leemour merged commit 6323715 into main Nov 17, 2026
50 checks passed
@leemour
leemour deleted the feat/graphql-executor branch November 17, 2026 22:20
leemour added a commit that referenced this pull request Nov 17, 2026
….config, over GraphQL (#3099)

## Task

L4 of the Linear pilot: a tracker CLI assembles from
`wirecat.config.ts`, as a CRM does. This adds
`trackerSourceFromManifest` over the tracker category (#3095) and the
GraphQL executor (#3097).

## What

- `src/tracker/manifest/`: `TrackerManifest`, `parseTrackerManifest`,
`mapTrackerRecord`, `trackerSourceFromManifest`.
- Each kind names a `list`, a `changes` call with `"{since}"` (the
cursor less `overlapMs`), and an `ids` call; a `map` in the CRM rule
language.
- Over GraphQL a call sends its own `selection`; the parser refuses a
map path the selection leaves out, so a field missing from the request
is never read as "cleared".
- A selected object answered `null` clears the field, converted by its
type (`[]` for a list).
- An `optional` kind refused (`errors[]` FORBIDDEN through the executor)
is a gap; the other kinds still sync.
- `syncTracker`: an id pass after a gap for its kind is held even under
`--rescan`.
- `wirecat.config`: `category: "tracker"` with its `source`, `spec.kind:
"graphql"`.
- CRM manifest: a `number` conversion; `crmRuleSchema` exported.

## Testing

- `trackerSourceContract` over a Linear-shaped `graphqlFake` (pages by
two, filters on `updatedAt.gte`, archived only on ask), every call
through `serviceApiCall`.
- Mapping tests (null under every rule kind), optional-kind tests, and
refusal tests for the parser.
- Local: typecheck (all configs), lint, `docs:check`, `src/tracker
src/manifest src/crm/manifest src/cli/service-api` (130 tests).

🤖 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