Skip to content

feat(tracker): the tracker category — store version 70, TrackerSource, syncTracker, commands and contract kit - #3095

Merged
leemour merged 2 commits into
mainfrom
feat/tracker
Nov 17, 2026
Merged

leemour merged 2 commits into
mainfrom
feat/tracker

Conversation

@leemour

@leemour leemour commented Nov 17, 2026

Copy link
Copy Markdown
Member

Task

L3 of the CLI factory plan: the foundation a Linear CLI needs, as a category of its own (owner's decision NEED-2717 A), not a CRM.

Why

A tracker CLI should assemble from a source and shared code, like the CRM CLIs. Issues, projects, workflow states and comments do not fit the CRM domain.

What

  • Store version 70 (reserved in docs(coordination): reserve store version 70 for the tracker category #3092): tracker_items (one row per team, user, state, label, project, issue and comment; the record as JSON plus title, body, parent and times) and the FTS5 word index tracker_item_words with its vocab, kept by triggers as crm_file_words is. Forward-only, minCompatible stays 56. Wired into account purge, store recover, store rebuild, the integrity check and the older-store undo.
  • store.tracker: a save that merges (a field a read leaves out keeps its value), removeUnlisted with a dry run, issue filters (team, project, assignee or none, state, state types through the state rows, label, archived), word search with paging, issueByKey, and people: a tracker user joined to the one person with the same e-mail, when read. Nothing is written to the people graph.
  • TrackerSource port: changes(kind, cursor, page) with reset, ids(kind, page) for deletions, archived rows listed with archivedAt.
  • syncTracker: per-kind cursors saved after each page; a daily id pass that resumes and is held when it would empty a kind, mark more than half deleted, or follows a gap (tracker.unlisted-held, released by --rescan); a run budget, with the kinds a stopped run finished skipped so a small budget still moves on; a stopped rescan goes on as one.
  • addTrackerCommands: sync, issues list|show|search|task, and list for projects, teams, users, states and labels. Tracker text is named in untrusted.
  • Issue → owner task by a link: issues task ENG-12 makes a task with source: tracker:issue/<id>, title = the key only, no copied text; the same issue again answers its task.
  • /tracker/testing: trackerSourceContract (full lists in shape, held rows, cursor reread, ids cover the list, dead cursor, ±10 min skew, archive, delete, a cut list, a spent budget), fakeTrackerSource, exampleTrackerRows.
  • Docs: docs/dev/TRACKER.md, the architecture row, the changelog fragment. Line caps raised by the lines added, as each store version PR does.

The manifest interpreter (trackerSourceFromManifest, L4) comes in a later PR, on top of the graphql executor (L2).

Testing

  • pnpm typecheck (with the test and scripts configs), pnpm lint, pnpm docs:check, pnpm schema:check.
  • Full suite: 924 files pass; the two failures it found (the vocab table, the reason registry) are fixed, and their tests pass after the rebase.
  • New: src/tracker/tracker.test.ts (the contract over the fake, sync rounds, budget resume, held passes, missing cursor, resumed rescan, cancel), src/tracker/cli/commands.test.ts, src/store/version-70.test.ts.
  • A fresh-agent review of the diff found 7 issues, all fixed in the second commit.

🤖 Generated with Claude Code

leemour and others added 2 commits November 17, 2026 22:43
…, syncTracker, commands and contract kit

Adds src/tracker, exported as @wirecat/cli-core/tracker and /tracker/testing:

- Store version 70 (reserved in #3092): tracker_items, one row per team,
  user, state, label, project, issue and comment of a tracker account,
  and the FTS5 word index tracker_item_words kept by triggers. store.tracker
  saves with a merge (a field a read leaves out keeps its value), lists
  issues by team, project, assignee, state, state type and label, finds by
  words, and joins users to people by exact e-mail when read.
- TrackerSource: changes by cursor with reset, ids for deletions.
- syncTracker: per-kind cursors saved after each page, a daily id pass
  that resumes, a run budget, and a cycle that skips the kinds a stopped
  run finished so a small budget still moves on.
- addTrackerCommands: sync, issues list/show/search/task, and lists of
  projects, teams, users, states and labels; tracker text is marked
  untrusted.
- issues task links an issue as the owner's task (source
  tracker:issue/<id>), copying only its key.
- trackerSourceContract with fault cases, fakeTrackerSource and
  exampleTrackerRows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…esume a stopped rescan

From the review of the tracker module:

- An id pass that would empty a kind, mark more than half of ten or more
  rows deleted, or follows a gap the sign-in reported, is held and marks
  nothing until sync --rescan (reason tracker.unlisted-held), as the CRM
  sync does.
- A changes page that says there is more but gives no cursor fails the
  kind instead of ending the round.
- A stopped --rescan goes on as a rescan in the next run; gaps of the
  kinds a resumed run skips are kept.
- The id pass stops on cancel, keeping its ids.
- issues search takes --page; issues show marks a cut comment list
  incomplete; a user joins a person only when one person has the e-mail.
- tracker_item_words gets its vocab table, like every word index.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit 41362d5 into main Nov 17, 2026
49 checks passed
@leemour
leemour deleted the feat/tracker branch November 17, 2026 21:53
leemour added a commit that referenced this pull request Nov 17, 2026
…ApiCall (#3097)

## 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, #3095), typecheck
(including tests), lint, docs:check and the full suite pass (12536
tests).

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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>
leemour added a commit that referenced this pull request Nov 17, 2026
…3103)

## Task

A tracker CLI made from cli-template failed `pnpm ci:quick`: `cli-dev
lint` found 19 violations in the commands `addTrackerCommands` mounts
(#3095). With cli-base#644 (tracker nouns) and this PR it finds none.

## What

- Each list narrows by its query, as `deals list` does, in place of
filter flags: `issues list team:<id> project:<id> assignee:none
state:<id> type:started label:<id>`; `archived:include` on every list.
`type:` repeats for any of several.
- `issues task` → `issues assign` (the issue becomes the owner's task;
nothing changes in the tracker). `--due <time>` reads times with
`aheadOf`, as `tasks --due` does.
- `issues search --any` is gone.

## Testing

- `src/tracker` (41 tests), the full suite locally (one timing test in
`connection-waits` failed under load and passes alone), typecheck, lint,
docs:check.
- A reviewer ran cli-base's `cli-dev lint` (with #644) over a program
mounting these commands: 0 violations.

🤖 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