Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions changes/feat-tracker-manifest.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
### Added

- **A tracker CLI can be described as data: `trackerSourceFromManifest`.** A `TrackerManifest` names, for each kind,
the list, changes and ids operations of the generated API and maps our fields to paths in a row, in the CRM
manifest's rule language. Over GraphQL each call may send its own selection, and `parseTrackerManifest` refuses a
map path the selection leaves out. `wirecat.config` takes `category: "tracker"` with its `source`, and
`spec.kind: "graphql"`. See [Trackers](../docs/dev/TRACKER.md#a-tracker-described-as-data).
25 changes: 22 additions & 3 deletions docs/dev/TRACKER.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,12 @@ stops keeps its ids and the page it reached.
`state: "partial"` and `stopped`; the kinds it finished are skipped by the next run until every kind has had its
round, so a budget smaller than the number of kinds still moves on.
- **Held passes.** A pass is held (`pass: "held"`, with the reason in `held`) and marks nothing when the list is empty
while rows are stored, when it would mark more than half of ten or more stored rows deleted, or when the sign-in
reported a gap for the kind: a tracker that lost rights lists none of what it can no longer see.
while rows are stored, or when it would mark more than half of ten or more stored rows deleted: a tracker that lost
rights lists none of what it can no longer see. `--rescan` lets those through. A pass after the sign-in reported a
gap for the kind is held even then: what it could not read is not gone.
- **Failures.** A kind that fails is named in its result's `error` and the others still sync. A page that says there is
more but gives no next page fails the kind.
- **`rescan`.** Lists everything again and every id, dropping a round in progress, and lets a held pass through. A
- **`rescan`.** Lists everything again and every id, dropping a round in progress, and lets a held pass through unless a gap held it. A
rescan that stops goes on as one in the next run.

A save merges: a field the read left out keeps its stored value, so a partial selection never erases.
Expand All @@ -66,6 +67,24 @@ to the issue and copies none of its text. The same issue again answers the task
`projects`, `teams`, `users` (each with its person), `states` and `labels`. Every text field from the tracker is named
in the row's `untrusted`.

## A tracker described as data

`trackerSourceFromManifest(manifest, { api, call, hooks? })` builds a `TrackerSource` from the generated API manifest
and a `TrackerManifest`, as `crmSourceFromManifest` does for a CRM. Each kind names a `list` call, a `changes` call
whose `variables` hold `"{since}"` (the cursor less `overlapMs`, ten minutes by default), an `ids` call that selects
only the id, and a `map` from our fields to paths in a row, in the CRM manifest's rule language. A selected object
the tracker answers `null` (`project: null`) is none, so the stored link is cleared.

Over GraphQL a call's `selection` replaces the operation's default one, so a tracker reads `state { id }` or
`labels { nodes { id } }`. `parseTrackerManifest` refuses a map path the selection leaves out, before any request:
a field missing from the request would read as "the tracker cleared it". The variables travel as the request body;
the selection rides on the request as `selection`, which the `api` group's GraphQL executor sends.

`self: { call, path }` names the signed-in user. `hooks.after` corrects a record; `hooks.extend` adds methods.

A `wirecat.config.ts` with `category: "tracker"` needs its `source`; `spec.kind: "graphql"` names an introspection
result.

## The contract kit

`trackerSourceContract(make)` checks an adapter: full lists in the domain's shape, every held row listed, a cursor
Expand Down
4 changes: 3 additions & 1 deletion src/crm/manifest/manifest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ export interface CrmManifestHooks {
const path = v.pipe(v.string(), v.regex(/^[^.\s]+(\.[^.\s]+)*$/, "a dotted path such as properties.name"))
const paths = v.pipe(v.array(path), v.minLength(1))

const rule: v.GenericSchema<CrmRule> = v.union(
export const crmRuleSchema: v.GenericSchema<CrmRule> = v.union(
[
path,
v.strictObject({ first: paths }),
Expand All @@ -166,6 +166,8 @@ const rule: v.GenericSchema<CrmRule> = v.union(
"a path, one of first, join, all, path, each, value, or a function",
) as v.GenericSchema<CrmRule>

const rule = crmRuleSchema

const call = v.strictObject({
operation: v.pipe(v.string(), v.minLength(1)),
path: v.optional(v.record(v.string(), v.string())),
Expand Down
3 changes: 2 additions & 1 deletion src/crm/manifest/map.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { CrmField, CrmKind, CrmRecords } from "../../domain/crm.js"
import { DEAL_STATUSES } from "../../domain/deals.js"
import { amountOf, type CrmRaw, crmValuesOf, epoch, fullName, id, isRaw, text } from "../values.js"
import { amountOf, type CrmRaw, crmValuesOf, epoch, fullName, id, isRaw, number, text } from "../values.js"
import type { CrmRule } from "./manifest.js"

/** The service sent nothing at this path: the field is left out, so the stored copy keeps what it held. */
Expand Down Expand Up @@ -105,6 +105,7 @@ const CONVERT = {
epoch: epochOf,
day: dayOf,
bool: yes,
number,
texts: (value: unknown) => unique(listOf(value).map(text)),
ids: (value: unknown) => linksOf(value).map(({ externalId }) => externalId),
status: (value: unknown) => {
Expand Down
13 changes: 11 additions & 2 deletions src/manifest/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ describe("parseCliConfig", () => {
hooks: "./src/hooks.ts",
}
expect(parseCliConfig(oauth)).toEqual(oauth)
const tracker = {
...config,
spec: { kind: "graphql" as const, from: "https://api.acme.test/graphql" },
category: "tracker" as const,
source: { provider: "acme", kinds: ["issue"], entities: {} },
}
expect(parseCliConfig(tracker)).toEqual(tracker)
})

it("names where a config is wrong", () => {
Expand All @@ -40,6 +47,8 @@ describe("parseCliConfig", () => {
"spec.from",
)
expect(() => parseCliConfig({ ...config, category: "crm" })).toThrow("a crm CLI needs its source")
expect(() => parseCliConfig({ ...config, category: "tracker" })).toThrow("a tracker CLI needs its source")
expect(() => parseCliConfig({ ...config, source: { provider: "acme" } })).toThrow("only a crm or tracker CLI")
for (const from of [
"/etc/spec.json",
"//evil.test/x",
Expand All @@ -55,7 +64,7 @@ describe("parseCliConfig", () => {
expect(() => parseCliConfig({ ...config, identity: { ...config.identity, owner: "-owner" } })).toThrow(
"identity.owner",
)
expect(() => parseCliConfig({ ...config, source: { provider: "acme" } })).toThrow("only a crm CLI")
expect(() => parseCliConfig({ ...config, source: { provider: "acme" } })).toThrow("only a crm or tracker CLI")
expect(() => parseCliConfig({ ...config, extra: true })).toThrow(
"wirecat.config: extra: not a field of wirecat.config",
)
Expand All @@ -64,7 +73,7 @@ describe("parseCliConfig", () => {
it("takes each category, a crm CLI with its source, and a token's verify call", () => {
for (const category of ["mail", "files", "other"] as const)
expect(parseCliConfig({ ...config, category }).category).toBe(category)
expect(() => parseCliConfig({ ...config, category: "tracker" })).toThrow("wirecat.config: category")
expect(() => parseCliConfig({ ...config, category: "erp" })).toThrow("wirecat.config: category")
const crm = { ...config, category: "crm" as const, source: { provider: "acme" } }
expect(parseCliConfig(crm).source).toEqual({ provider: "acme" })
const verify = { operation: "getV2Self", id: "workspace_id", name: "workspace_name" }
Expand Down
35 changes: 25 additions & 10 deletions src/manifest/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { CliError } from "@wirecat/cli-base"
import * as v from "valibot"
import type { CrmManifest } from "../crm/manifest/manifest.js"
import type { OAuthProvider } from "../oauth/provider.js"
import type { TrackerManifest } from "../tracker/manifest/manifest.js"

/**
* The operation that answers whose the token is, and where its answer holds the account's id (and a name to show):
Expand Down Expand Up @@ -30,7 +31,17 @@ export type CliAuth =
rotating?: boolean
}

export const CLI_CATEGORIES = ["messenger", "mail", "notes", "files", "meetings", "calendar", "crm", "other"] as const
export const CLI_CATEGORIES = [
"messenger",
"mail",
"notes",
"files",
"meetings",
"calendar",
"crm",
"tracker",
"other",
] as const
export type CliCategory = (typeof CLI_CATEGORIES)[number]

/** One file, `wirecat.config.ts`, that `new --from-config` builds a CLI from. */
Expand All @@ -48,12 +59,15 @@ export interface CliConfig {
owner: string
}
/** `from`: the https URL the description is published at. */
spec: { kind: "openapi" | "swagger"; from: string }
spec: { kind: "openapi" | "swagger" | "graphql"; from: string }
auth: CliAuth
/** cli-template's `--category`; `other` is any API outside them. */
category: CliCategory
/** The CRM source; checked against the generated API by `parseCrmManifest` once the api group exists. */
source?: CrmManifest
/**
* A crm or tracker CLI's source; checked against the generated API by `parseCrmManifest` or `parseTrackerManifest`
* once the api group exists.
*/
source?: CrmManifest | TrackerManifest
/** The module of named hooks, relative to the config: `./src/hooks.ts`. */
hooks?: string
}
Expand Down Expand Up @@ -126,7 +140,7 @@ const schema = v.strictObject({
owner: v.pipe(v.string(), v.regex(/^[A-Za-z0-9](?:-?[A-Za-z0-9]){0,38}$/, "a GitHub owner")),
}),
spec: v.strictObject({
kind: v.picklist(["openapi", "swagger"]),
kind: v.picklist(["openapi", "swagger", "graphql"]),
from: httpsUrl,
}),
auth: v.variant("preset", [
Expand Down Expand Up @@ -161,7 +175,7 @@ const schema = v.strictObject({
})

/**
* The config checked against its shape; every error names where it is. A CRM CLI needs its source. `source` comes back
* The config checked against its shape; every error names where it is. A crm or tracker CLI needs its source. `source` comes back
* unchecked: `parseCrmManifest` checks it against the generated API.
*/
export const parseCliConfig = (input: unknown): CliConfig => {
Expand All @@ -184,12 +198,13 @@ export const parseCliConfig = (input: unknown): CliConfig => {
// Typed, not cast: a field CliConfig needs that the schema lacks or types otherwise fails to compile (not the reverse).
const output: Omit<CliConfig, "source"> & { source?: Readonly<Record<string, unknown>> } = parsed.output
const config = output as CliConfig
if (config.category !== "crm" && config.source)
throw new CliError("configuration_error", "wirecat.config: source: only a crm CLI reads a source yet", {
const sourced = config.category === "crm" || config.category === "tracker"
if (!sourced && config.source)
throw new CliError("configuration_error", "wirecat.config: source: only a crm or tracker CLI reads a source yet", {
reason: "manifest.invalid",
})
if (config.category === "crm" && !config.source)
throw new CliError("configuration_error", "wirecat.config: source: a crm CLI needs its source", {
if (sourced && !config.source)
throw new CliError("configuration_error", `wirecat.config: source: a ${config.category} CLI needs its source`, {
reason: "manifest.invalid",
})
return config
Expand Down
14 changes: 14 additions & 0 deletions src/tracker/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,20 @@ export {
type TrackerUser,
} from "../domain/tracker.js"
export { addTrackerCommands, type TrackerCommandOptions, type TrackerRun } from "./cli/index.js"
export {
parseTrackerManifest,
type TrackerAfterHook,
type TrackerChangesCall,
type TrackerManifest,
type TrackerManifestEntity,
type TrackerManifestHooks,
type TrackerOperationCall,
} from "./manifest/manifest.js"
export { TRACKER_FIELDS } from "./manifest/map.js"
export {
type TrackerManifestSourceOptions,
trackerSourceFromManifest,
} from "./manifest/source.js"
export type {
TrackerCallContext,
TrackerChanges,
Expand Down
Loading
Loading