diff --git a/changes/feat-tracker-commands-vocabulary.md b/changes/feat-tracker-commands-vocabulary.md new file mode 100644 index 000000000..4accdae1b --- /dev/null +++ b/changes/feat-tracker-commands-vocabulary.md @@ -0,0 +1,9 @@ +### Changed — may break callers + +- **The tracker's commands follow the command vocabulary**, so `cli-dev lint` passes a tracker CLI (with cli-base + 0.117.0, which has `issues`, `teams`, `states` and `labels`). Each list narrows by its query, as `deals list` does: + `issues list team: project: assignee:none state: type:started label:`, and `archived:include` on + every list, in place of `--team`, `--project`, `--assignee`, `--state`, `--type`, `--label` and `--archived`. + `type:` repeats for any of several types. `issues task` is `issues assign`: it makes the issue the owner's task + and changes nothing in the tracker; its `--due` reads times as `tasks --due` does (a day is its end, `3d` works). `issues search --any` is gone. + See [Trackers](../docs/dev/TRACKER.md#commands). diff --git a/docs/dev/TRACKER.md b/docs/dev/TRACKER.md index a810b8285..e266c6837 100644 --- a/docs/dev/TRACKER.md +++ b/docs/dev/TRACKER.md @@ -57,15 +57,16 @@ identity linked to a person has, joined when read. Nothing is written to the peo ## An issue as the owner's task -`trackerIssueTask(store, account, issue)` and `issues task ` make an issue the owner's task: `source` is +`trackerIssueTask(store, account, issue)` and `issues assign ` make an issue the owner's task: `source` is `tracker:issue/`, `sourceKind` is `tracker_issue`, and the title is the issue's key only. The task links to the issue and copies none of its text. The same issue again answers the task it already has. ## Commands -`addTrackerCommands(program, { app, open })` mounts `sync`, `issues list|show|search|task`, and `list` for +`addTrackerCommands(program, { app, open })` mounts `sync`, `issues list|show|search|assign`, and `list` for `projects`, `teams`, `users` (each with its person), `states` and `labels`. Every text field from the tracker is named -in the row's `untrusted`. +in the row's `untrusted`. Each list narrows by its query, as `deals list` does: +`issues list team: assignee:none type:started`, and `archived:include` for archived rows too. ## A tracker described as data diff --git a/src/tracker/cli/commands.test.ts b/src/tracker/cli/commands.test.ts index 41c131a2d..a1502f27a 100644 --- a/src/tracker/cli/commands.test.ts +++ b/src/tracker/cli/commands.test.ts @@ -51,13 +51,16 @@ const setup = async () => { const ids = (answer: Answer) => answer.items.map((one) => one.external_id) describe("tracker commands", () => { - it("syncs, then lists, shows, searches and makes a task of an issue", async () => { + it("syncs, then lists, shows, searches and assigns an issue to the owner as a task", async () => { const { cli, store } = await setup() expect((await cli("sync")).item).toMatchObject({ state: "complete", provider: "fake-tracker" }) - expect(ids(await cli("issues", "list", "--type", "started", "--type", "unstarted"))).toEqual(["issue-2", "issue-1"]) - expect(ids(await cli("issues", "list", "--assignee", "none"))).toEqual(["issue-3"]) - const [first] = (await cli("issues", "list", "--label", "label-bug")).items + expect(ids(await cli("issues", "list", "type:started"))).toEqual(["issue-1"]) + expect(ids(await cli("issues", "list", "type:unstarted"))).toEqual(["issue-2"]) + expect(ids(await cli("issues", "list", "type:started", "type:unstarted"))).toEqual(["issue-2", "issue-1"]) + expect(ids(await cli("issues", "list", "assignee:None"))).toEqual(["issue-3"]) + expect(ids(await cli("issues", "list", "assignee:none"))).toEqual(["issue-3"]) + const [first] = (await cli("issues", "list", "label:label-bug")).items expect(first).toMatchObject({ key: "ENG-1", state_name: "In Progress", @@ -77,14 +80,15 @@ describe("tracker commands", () => { expect(ids(second)).toHaveLength(1) expect(ids(second)[0]).not.toBe(one) - const task = (await cli("issues", "task", "ENG-2", "--due", "2026-12-01")).item + const task = (await cli("issues", "assign", "ENG-2", "--due", "2026-12-01")).item expect(task).toMatchObject({ issue: "tracker:issue/issue-2", created: true }) - expect((await cli("issues", "task", "issue-2")).item).toMatchObject({ task_id: task.task_id, created: false }) + expect((await cli("issues", "assign", "issue-2")).item).toMatchObject({ task_id: task.task_id, created: false }) const [stored] = await store.tasks.query("fake-tracker:workspace", undefined, { limit: 10, offset: 0 }) expect(stored).toMatchObject({ title: "ENG-2", task: { source: "tracker:issue/issue-2" } }) expect(stored?.task).not.toHaveProperty("description") expect(ids(await cli("states", "list", "--limit", "10"))).toHaveLength(6) + await expect(cli("issues", "list", "team:a", "team:b")).rejects.toThrow() expect(ids(await cli("projects", "list"))).toEqual(["project-1"]) }) }) diff --git a/src/tracker/cli/index.ts b/src/tracker/cli/index.ts index 47c6e3c7c..33001fe5a 100644 --- a/src/tracker/cli/index.ts +++ b/src/tracker/cli/index.ts @@ -1,4 +1,5 @@ import { annotate, sharedCommand } from "@wirecat/cli-base/commands" +import type { QueryRegistry } from "@wirecat/cli-base/query" import type { NextStep } from "@wirecat/cli-base/standards" import { type Command, InvalidArgumentError } from "commander" import * as v from "valibot" @@ -7,6 +8,8 @@ import { environmentOf, inCommandRun, outputFor, runBudgetOf } from "../../cli/c import { honoursDryRun } from "../../cli/dry-run-guard.js" import { FETCH, LOCAL_READ, LOCAL_WRITE, NO_EFFECTS } from "../../cli/effects.js" import { type Body, itemOf, listOf, renderAnswer } from "../../cli/envelope.js" +import { listQuery, nativeTermLists, queryTerms, termField, typedQuery, withQuery } from "../../cli/list-query.js" +import { aheadOf } from "../../domain/moment.js" import { STATE_TYPES, type StateType, @@ -49,17 +52,31 @@ const integer = (most: number) => (value: string) => { return number } -const day = (value: string) => { - if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(value))) - throw new InvalidArgumentError("a day as YYYY-MM-DD") - return value -} +const ARCHIVED = termField("archived", "enum", "archived:include", { + values: ["include"], + relation: "archived ones too; left out, only those not archived", +}) -const stateTypes = (value: string, previous: StateType[] = []) => { - if (!(STATE_TYPES as readonly string[]).includes(value)) - throw new InvalidArgumentError(`one of ${STATE_TYPES.join(", ")}`) - return [...previous, value as StateType] -} +const listQueryOf = (kind: TrackerKind): QueryRegistry => ({ + entity: `tracker_${kind}`, + backend: "native", + fields: [ARCHIVED], +}) + +/** What `issues list` narrows by: each by the tracker's id, as `issues show` and the lists name them. */ +const ISSUES_QUERY = { + entity: "tracker_issue", + backend: "native", + fields: [ + termField("team", "kw", "team:team-1", { relation: "the team's id, as teams list shows it" }), + termField("project", "kw", "project:project-1", { relation: "the project's id, as projects list shows it" }), + termField("assignee", "kw", "assignee:none", { relation: "the user's id, as users list shows it, or none" }), + termField("state", "kw", "state:state-1", { relation: "the state's id, as states list shows it" }), + termField("type", "enum", "type:started", { values: [...STATE_TYPES], relation: "repeat for any of several" }), + termField("label", "kw", "label:label-1", { relation: "the label's id, as labels list shows it" }), + ARCHIVED, + ], +} as const satisfies QueryRegistry const TIMES = new Set(["createdAt", "updatedAt", "archivedAt", "completedAt", "canceledAt"]) @@ -238,59 +255,44 @@ const addTrackerCommandsDefinition = (program: Command, options: TrackerCommandO ) example( paging( - answerEntity(annotate(issues.command("list"), { effects: LOCAL_READ }), "tracker_issue", trackerView) - .description("issues copied from the tracker, newest change first; run sync to bring them up to date") - .option("--team ", "only this team's issues") - .option("--project ", "only this project's issues") - .option("--assignee ", "only issues assigned to this user; `none` for unassigned ones") - .option("--state ", "only issues in this state") - .option( - "--type ", - `only issues whose state is of this type, repeatable: ${STATE_TYPES.join(", ")}`, - stateTypes, - ) - .option("--label ", "only issues with this label") - .option("--archived", "archived issues too"), + withQuery( + answerEntity(annotate(issues.command("list"), { effects: LOCAL_READ }), "tracker_issue", trackerView), + ISSUES_QUERY, + ).description("issues copied from the tracker, newest change first; run sync to bring them up to date"), ), - "issues list --type started --type unstarted", - "issues list --assignee none --json", - ).action( - async ( - opts: { - team?: string - project?: string - assignee?: string - state?: string - type?: StateType[] - label?: string - archived?: boolean - limit: number - page: number - }, - command: Command, - ) => { - await within(command, true, async (run) => { - const filter: TrackerFilter = { - ...(opts.team ? { parent: opts.team } : {}), - ...(opts.project ? { project: opts.project } : {}), - ...(opts.assignee ? { assignee: opts.assignee === "none" ? null : opts.assignee } : {}), - ...(opts.state ? { state: opts.state } : {}), - ...(opts.type?.length ? { stateTypes: opts.type } : {}), - ...(opts.label ? { label: opts.label } : {}), - ...(opts.archived ? { archived: true } : {}), - limit: opts.limit, - offset: (opts.page - 1) * opts.limit, - } - const found = await run.store.tracker.list(run.account, "issue", filter) - return listOf("issues list", { - items: await withNames(run, found.items), - limit: opts.limit, - page: opts.page, - has_more: found.hasMore, - }) + "issues list type:started", + "issues list assignee:none --json", + ).action(async (words: string[], opts: { limit: number; page: number }, command: Command) => { + const lists = nativeTermLists(listQuery(typedQuery(words), ISSUES_QUERY, "issues list"), "issues list", ["type"]) + if ([...lists.values()].flat().some((one) => one.operator !== "term" && one.operator !== "phrase")) + throw new InvalidArgumentError("issues list takes field:value terms, each one whole value") + const types = (lists.get("type") ?? []).map((one) => one.value.toLowerCase() as StateType) + const terms = new Map( + [...lists].filter(([field]) => field !== "type").map(([field, [one]]) => [field, one?.value as string]), + ) + const assignee = terms.get("assignee")?.toLowerCase() === "none" ? "none" : terms.get("assignee") + await within(command, true, async (run) => { + const filter: TrackerFilter = { + ...(terms.has("team") ? { parent: terms.get("team") as string } : {}), + ...(terms.has("project") ? { project: terms.get("project") as string } : {}), + ...(assignee !== undefined ? { assignee: assignee === "none" ? null : assignee } : {}), + ...(terms.has("state") ? { state: terms.get("state") as string } : {}), + ...(types.length ? { stateTypes: types } : {}), + ...(terms.has("label") ? { label: terms.get("label") as string } : {}), + ...(terms.has("archived") ? { archived: true } : {}), + limit: opts.limit, + offset: (opts.page - 1) * opts.limit, + } + const found = await run.store.tracker.list(run.account, "issue", filter) + return listOf("issues list", { + items: await withNames(run, found.items), + limit: opts.limit, + page: opts.page, + has_more: found.hasMore, + ...(words.length ? { args: { query: words } } : {}), }) - }, - ) + }) + }) example( answerEntity(annotate(issues.command("show"), { effects: LOCAL_READ }), "tracker_issue_detail", trackerView) .description("one issue with its state, assignee and comments") @@ -314,11 +316,10 @@ const addTrackerCommandsDefinition = (program: Command, options: TrackerCommandO paging( answerEntity(annotate(issues.command("search"), { effects: LOCAL_READ }), "tracker_hit", trackerView) .description("find issues, projects and comments in the copy by their words") - .argument("", "every word must match; prefixes of three letters or more match too") - .option("--any", "any word may match"), + .argument("", "every word must match; prefixes of three letters or more match too"), ), 'issues search "invoice currency"', - ).action(async (words: string[], opts: { any?: boolean; limit: number; page: number }, command: Command) => { + ).action(async (words: string[], opts: { limit: number; page: number }, command: Command) => { await within(command, true, async (run) => { const found = await run.store.tracker.find({ words, @@ -326,7 +327,6 @@ const addTrackerCommandsDefinition = (program: Command, options: TrackerCommandO kinds: ["issue", "project", "comment"], limit: opts.limit, offset: (opts.page - 1) * opts.limit, - ...(opts.any ? { anyWord: true } : {}), }) return listOf("issues search", { items: found.items.map((hit) => viewOf(hit.item, { excerpt: hit.excerpt })), @@ -338,19 +338,23 @@ const addTrackerCommandsDefinition = (program: Command, options: TrackerCommandO }) }) example( - answerEntity(annotate(issues.command("task"), { effects: LOCAL_WRITE }), "tracker_issue_task", trackerTask) + answerEntity(annotate(issues.command("assign"), { effects: LOCAL_WRITE }), "tracker_issue_task", trackerTask) .description( "make an issue the owner's task: the task points at the issue and copies none of its text; the same issue " + "again answers its existing task", ) .argument("", "the issue's key (ENG-12) or id") - .option("--due ", "when it is due, YYYY-MM-DD", day), - "issues task ENG-12 --due 2026-12-01", - ).action(async (reference: string, opts: { due?: string }, command: Command) => { + .option( + "--due