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
14 changes: 14 additions & 0 deletions changes/feat-tracker-graphql.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
### Added

- **`new --spec graphql` makes the api group from a GraphQL schema.** With `--spec-url` (or a config's `spec.from`),
`new` asks the endpoint for its schema by introspection, as `pnpm spec:sync` does later, and `pnpm generate` makes
one command of each query and mutation. A GraphQL schema names no sign-in, so the header the key travels in is
`auth` in `scripts/generate.ts`.
- **A `tracker` category.** `new --from-config` with `category: "tracker"` and a `source` mounts cli-core's tracker
commands (`sync`, `issues`, `projects`, `teams`…) over `trackerSourceFromManifest`, with a test that checks the
source against the generated API and syncs through the CLI over a fake of the schema.

### Changed — may break callers

- **cli-core 0.697.0**, which has the tracker category, `trackerSourceFromManifest` and the
GraphQL executor.
20 changes: 13 additions & 7 deletions kit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,16 +89,22 @@ read before the CLI has `node_modules`: its import resolves to the kit's own cli

- `pnpm generate` first writes `src/generated/wirecat-config.ts` from the config (`scripts/from-config.ts`): the
token check, the source and the hooks, which `src/` reads; the config stays the one file to edit.
- A CRM `source` needs `auth: { preset: "token", verify }`; `new` writes the files below only for what the config
- A `source` (a `crm` or a `tracker` category) needs `auth: { preset: "token", verify }`; `new` writes the files below only for what the config
holds at `new`, and `pnpm generate` then reads their values again.
- With `auth.verify`, `session start` is cli-core's `tokenSessionCommand`: it checks a token with that operation and
keeps the account's id from the answer.
- With a `source`, `src/commands/crm.ts` mounts cli-core's CRM commands (`sync`, `store status`, `deals`, `search`…)
over `crmSourceFromManifest`, the store keyed by the account `session start` checked.
over `crmSourceFromManifest`, the store keyed by the account `session start` checked. A `tracker` source gets
`src/commands/tracker.ts` in its place: cli-core's tracker commands (`sync`, `issues`, `projects`…) over
`trackerSourceFromManifest`, usually with `spec: { kind: "graphql", from: "<endpoint>" }`. `new` asks the endpoint
for its schema by introspection; a GraphQL schema names no sign-in, so the header the key travels in is `auth` in
`scripts/generate.ts`, the sample's `Authorization` until you check the service's documentation.
- Tests come with them: `src/commands/session.test.ts` signs in against a fake of the API, and
`src/crm-contracts.test.ts` runs `crmSourceContract` and `crmSyncContract`. `lint/contract-exceptions.json` excepts
`crmWriteContract`, as the source only reads. A list the generator finds no paging for fails the contract's
cut-list case on purpose: describe the paging in the API description or an override.
cut-list case on purpose: describe the paging in the API description or an override. A tracker's
`src/tracker-contracts.test.ts` checks the source against the generated API and syncs through the CLI over a fake
of the schema.
- `pnpm source:check` checks the source's operations and every path its map reads against the generated API, after
`pnpm generate`.

Expand All @@ -112,15 +118,15 @@ choices. Nothing is guessed.
| `--package` | the npm package name |
| `--owner` | the GitHub owner |
| `--tagline` | the line WireCat Desktop shows, at most 55 characters; left out, it is made from the description |
| `--category` | one for each of cli-core's kinds: `messenger`, `mail`, `notes`, `files`, `meetings`, `calendar`, `crm` |
| `--category` | one for each of cli-core's kinds: `messenger`, `mail`, `notes`, `files`, `meetings`, `calendar`, `crm`; and `tracker` |
| `--content-lang` | language codes, several: `en,ru` |
| `--sign-in` | `oauth`, `token`, `session`, `none` |
| `--api` | `official-client`, `official-docs`, `unofficial` |
| `--spec` | `openapi`, `swagger`, `discovery`, `none`; left out with `--spec-url`, it is the downloaded description's |
| `--spec-url` | the URL of the service's OpenAPI 3 or Swagger 2.0 description, JSON or YAML |
| `--spec` | `openapi`, `swagger`, `discovery`, `graphql`, `none`; left out with `--spec-url`, it is the downloaded description's |
| `--spec-url` | the URL of the service's OpenAPI 3 or Swagger 2.0 description, JSON or YAML; with `--spec graphql`, the endpoint |
| `--filters` | several of `time`, `person`, `container`, `text`, `status` |
| `--never-store` | several of `tokens`, `codes`, `secret-links`, `content` |
| `--untrusted` | several of `files`, `links`, `names`, and for its category `messages` (messenger, mail), `records` (crm), `invitations` (calendar), `transcripts` (meetings); or `none` alone |
| `--untrusted` | several of `files`, `links`, `names`, and for its category `messages` (messenger, mail), `records` (crm), `issues` (tracker), `invitations` (calendar), `transcripts` (meetings); or `none` alone |

Every question except the names, `--tagline` and `--content-lang` also takes `other:<your answer>`. `--tagline` is the
one answer with a default: left out, it is the description cut on a word at 55 characters, and in a terminal an empty
Expand Down
18 changes: 12 additions & 6 deletions kit/seeds/config/scripts/from-config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { parseCliConfig } from "@wirecat/cli-core/manifest"
import config from "../wirecat.config.ts"

// wirecat.config.ts → src/generated/wirecat-config.ts, what the CLI reads of it at run time: the call that checks a
// token and the CRM source. src/ cannot import the config itself: it sits outside src/ and the bin is bundled.
// token and the source. src/ cannot import the config itself: it sits outside src/ and the bin is bundled.
const root = join(import.meta.dirname, "..")
const out = join(root, "src/generated/wirecat-config.ts")
if (process.argv.includes("--if-missing") && existsSync(out)) process.exit(0)
Expand Down Expand Up @@ -42,11 +42,17 @@ const text = formatted(
"",
...(hooksImport
? [`export { hooks as HOOKS } from "${hooksImport}"`]
: [
'import type { CrmManifestHooks } from "@wirecat/cli-core/crm"',
"",
"export const HOOKS: CrmManifestHooks | undefined = undefined",
]),
: cli.category === "tracker"
? [
'import type { TrackerManifestHooks } from "@wirecat/cli-core/tracker"',
"",
"export const HOOKS: TrackerManifestHooks | undefined = undefined",
]
: [
'import type { CrmManifestHooks } from "@wirecat/cli-core/crm"',
"",
"export const HOOKS: CrmManifestHooks | undefined = undefined",
]),
"",
].join("\n"),
)
Expand Down
18 changes: 12 additions & 6 deletions kit/seeds/config/scripts/source-check.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
import { crmManifestProblems, parseCrmManifest } from "@wirecat/cli-core/crm"
import { parseCliConfig } from "@wirecat/cli-core/manifest"
import { parseTrackerManifest } from "@wirecat/cli-core/tracker"
import { definitions } from "../dist/generated/definitions.js"
import * as api from "../dist/generated/manifest.js"
import config from "../wirecat.config.ts"

// wirecat.config.ts against the generated API: its shape, the auth.verify call, then each source operation and every
// path its map reads.
// Run after pnpm generate, which builds dist/.
const problemsOf = (): { problems: string[]; crm: boolean } => {
const problemsOf = (): { problems: string[]; source: boolean } => {
try {
const cli = parseCliConfig(config)
const verify = cli.auth.preset === "none" ? undefined : cli.auth.verify
Expand All @@ -20,17 +21,22 @@ const problemsOf = (): { problems: string[]; crm: boolean } => {
: operation.effect !== "read"
? [`auth.verify: ${verify.operation} is not a read, and session start sends only reads`]
: []
if (!cli.source) return { problems: verifying, crm: false }
if (!cli.source) return { problems: verifying, source: false }
if (cli.category === "tracker") {
// Refuses a map path the selection leaves out, which would read as "the tracker cleared it".
parseTrackerManifest(cli.source, api)
return { problems: verifying, source: true }
}
return {
problems: [...verifying, ...crmManifestProblems(parseCrmManifest(cli.source, api), api, definitions)],
crm: true,
source: true,
}
} catch (error) {
return { problems: [error instanceof Error ? error.message : String(error)], crm: false }
return { problems: [error instanceof Error ? error.message : String(error)], source: false }
}
}

const { problems, crm } = problemsOf()
const { problems, source } = problemsOf()
for (const problem of problems) process.stderr.write(`${problem}\n`)
if (problems.length) process.exit(1)
process.stdout.write(`wirecat.config.ts: ${crm ? "the source matches the generated API" : "ok"}\n`)
process.stdout.write(`wirecat.config.ts: ${source ? "the source matches the generated API" : "ok"}\n`)
77 changes: 77 additions & 0 deletions kit/seeds/config/src/commands/tracker.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
import { CliError } from "@wirecat/cli-base"
import { hostFetch, retrying } from "@wirecat/cli-base/http"
import { recalledAccount, serviceApiCall } from "@wirecat/cli-core/cli"
import { openCrmStore } from "@wirecat/cli-core/crm/cli"
import { Pacer, pacePathFor } from "@wirecat/cli-core/sends"
import type { MessageStore } from "@wirecat/cli-core/store"
import { addTrackerCommands, type TrackerRun, trackerSourceFromManifest } from "@wirecat/cli-core/tracker"
import { Command } from "commander"
import { API } from "../config.js"
import { contextOf, PACE, tokenOf } from "../context.js"
import { HOOKS, SOURCE } from "../generated/wirecat-config.js"
import { DESKTOP, IDENTITY } from "../identity.js"

const provider = (): string => {
if (typeof SOURCE?.provider !== "string") throw new CliError("configuration_error", "wirecat.config.ts has no source")
return SOURCE.provider
}

// A tracker's items are not a kind the shared search reads yet, so the store gets no provider entry.
const openStore = async (env: NodeJS.ProcessEnv, { readOnly = false } = {}): Promise<MessageStore> => {
const { ensureSqlite } = await import("@wirecat/cli-core/sqlite-runtime")
await ensureSqlite()
const { openStore: open, storePath } = await import("@wirecat/cli-core/store")
return open({
path: storePath(env),
env,
command: IDENTITY.command,
version: IDENTITY.version,
...(readOnly ? { readOnly } : {}),
})
}

// The account is the one `session start` checked the token against; the store keeps each account's rows apart.
const accountOf = (command: Command) => {
const { env, profile } = contextOf(command)
const account = recalledAccount(IDENTITY, provider(), profile, env)
if (!account)
throw new CliError(
"authentication_error",
`${profile} is not signed in; run ${IDENTITY.command} ${profile} session start`,
{ reason: "auth.missing" },
)
return account
}

const open = async (command: Command, { readOnly }: { readOnly: boolean }): Promise<TrackerRun> => {
const { env, profile, environment } = contextOf(command)
const { store, account } = await openCrmStore({
app: IDENTITY,
env,
profile,
readOnly,
provider: provider(),
open: openStore,
account: () => accountOf(command),
})
const fetch = retrying(
hostFetch({ hosts: DESKTOP.hosts ?? [], ...(environment.fetch ? { fetch: environment.fetch } : {}) }),
{ pacer: new Pacer(pacePathFor(IDENTITY, profile, env), PACE) },
)
const call = serviceApiCall({ manifest: API.manifest, service: API.service, fetch, token: () => tokenOf(command) })
let source: ReturnType<typeof trackerSourceFromManifest> | undefined
return {
account,
store,
source: () =>
(source ??= trackerSourceFromManifest(SOURCE, { api: API.manifest, call, ...(HOOKS ? { hooks: HOOKS } : {}) })),
close: () => store.close(),
}
}

/** cli-core's tracker commands over the source wirecat.config.ts describes: sync, issues and the lists. */
export const trackerCommands = (): Command[] => {
const holder = new Command(IDENTITY.command)
addTrackerCommands(holder, { app: IDENTITY, open })
return [...holder.commands]
}
35 changes: 26 additions & 9 deletions kit/seeds/config/src/testing/fake-api.ts
Original file line number Diff line number Diff line change
@@ -1,21 +1,38 @@
import { fakeApi } from "@wirecat/cli-base/codegen"
import { fakeApi, graphqlFake } from "@wirecat/cli-base/codegen"
import { manifestBaseUrl } from "@wirecat/cli-core/cli"
import { API } from "../config.js"
import { definitions } from "../generated/definitions.js"

/** The token fakeServiceApi takes; never a real one (WC-TEST-2). */
export const FAKE_API_TOKEN = "fake0api0token"

const graphql = API.manifest.operations.some((operation) => operation.binding.kind === "graphql")

// A GraphQL schema names no sign-in: the header is the one scripts/generate.ts sets in `auth`.
const graphqlAuth = (token: string) => {
const scheme = Object.values(API.manifest.securitySchemes ?? {})[0] as { type?: string; in?: string; name?: string }
return scheme?.type === "apiKey" && scheme.in === "header" && scheme.name
? { header: scheme.name, value: token }
: { header: "Authorization", value: `Bearer ${token}` }
}

/** The service's API as its description says, answering only `token`: a sample of each answer schema. */
export const fakeServiceApi = (token = FAKE_API_TOKEN) =>
fakeApi({
operations: API.manifest.operations,
definitions,
baseUrl: manifestBaseUrl(API.manifest),
security: API.manifest.security,
securitySchemes: API.manifest.securitySchemes,
token,
})
graphql
? graphqlFake({
operations: API.manifest.operations,
definitions,
url: manifestBaseUrl(API.manifest),
auth: graphqlAuth(token),
})
: fakeApi({
operations: API.manifest.operations,
definitions,
baseUrl: manifestBaseUrl(API.manifest),
security: API.manifest.security,
securitySchemes: API.manifest.securitySchemes,
token,
})

type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>

Expand Down
30 changes: 30 additions & 0 deletions kit/seeds/config/src/tracker-contracts.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import { memoryKeyring } from "@wirecat/cli-base"
import { parseTrackerManifest } from "@wirecat/cli-core/tracker"
import { expect, it } from "vitest"
import { API } from "./config.js"
import { SOURCE } from "./generated/wirecat-config.js"
import { FAKE_API_TOKEN, fakeServiceApi } from "./testing/fake-api.js"
import { runCli } from "./testing/harness.js"

it("the source in wirecat.config.ts reads only what the generated API offers and selects", () => {
expect(() => parseTrackerManifest(SOURCE, API.manifest)).not.toThrow()
})

// The fake answers a sample of each selection, so this checks the calls, not the mapping of real rows.
it("sync through this CLI sends only calls the schema allows, under the account session start checked", async () => {
const keyring = memoryKeyring()
const fake = fakeServiceApi()
const started = await runCli(["personal", "session", "start", "--json"], {
keyring,
service: fake,
stdin: FAKE_API_TOKEN,
})
expect(started.code, started.err).toBe(0)
const synced = await runCli(["personal", "sync", "--json"], { keyring, service: fake })
expect(synced.code, synced.err).toBe(0)
// A kind that failed is a partial answer with exit 0: its issues name it.
expect(synced.json().issues ?? []).toEqual([])
const listed = await runCli(["personal", "issues", "list", "--json"], { keyring, service: fake })
expect(listed.code, listed.err).toBe(0)
expect(fake.refusals).toEqual([])
})
71 changes: 71 additions & 0 deletions kit/seeds/graphql/scripts/generate.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
import { execFileSync } from "node:child_process"
import { existsSync } from "node:fs"
import { join, resolve } from "node:path"
import {
coverageGenerator,
definitionsGenerator,
generate,
manifestGenerator,
typesGenerator,
valibotGenerator,
writeArtifacts,
} from "@wirecat/cli-base/codegen"
import { specModel } from "./spec-model.ts"

// The service's API description → src/generated/ and docs/dev/API_COVERAGE.md. Each correction below is read from
// the service's documentation, never guessed; cli-base docs/standards/kit-surface.md says what each one does.
const root = resolve(import.meta.dirname, "..")
// A fresh CLI has no src/generated/ yet and cannot build without it, so build runs this with --if-missing first.
if (process.argv.includes("--if-missing") && existsSync(join(root, "src/generated/manifest.ts"))) process.exit(0)
const { model, notes } = await specModel(root)
const artifacts = generate(
model,
[
typesGenerator({ path: "src/generated/types.ts" }),
valibotGenerator({ path: "src/generated/schemas.ts", typesImport: "./types.js" }),
manifestGenerator({ path: "src/generated/manifest.ts" }),
definitionsGenerator({ path: "src/generated/definitions.ts" }),
coverageGenerator({
path: "docs/dev/API_COVERAGE.md",
title: "API coverage",
command: (operation) => `clidev <profile> api ${operation.command}`,
}),
],
{
banner: ["Source: spec/clidev/, checked against provenance.json", "Run: pnpm generate"],
// SAMPLE: operation id → { effect, reason } where the HTTP method misleads, as a POST that deletes.
overrides: {},
// SAMPLE: true when the service's POST …/search and …/query only read.
readingPosts: false,
// SAMPLE: command names from the paths; map an operation whose name comes out wrong in `commands`.
names: { fromPath: true },
// SAMPLE: the permission group, and the body fields or query parameters that delete when true.
permissions: { group: "comments", deletingFlags: [] },
// SAMPLE: how each read pages, found from the spec; an override's `pagination` wins.
pagination: true,
// SAMPLE: a GraphQL schema names no sign-in, so the header the token travels in is set here, from the service's
// documentation: an API key as it is (`Authorization: <key>`), or `{ type: "http", scheme: "bearer" }`.
auth: {
securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } },
security: [{ key: [] }],
reason: "a GraphQL schema names no sign-in; the service's documentation sends the key in Authorization",
},
},
)
const coverage = artifacts.find((artifact) => artifact.path === "docs/dev/API_COVERAGE.md")
if (coverage && notes.length)
coverage.content += ["", "## Spec corrections", "", ...notes.map((n) => `- ${n}`), ""].join("\n")
const format = (path: string, content: string) =>
path.endsWith(".ts")
? execFileSync(
process.execPath,
[`${root}/node_modules/@biomejs/biome/bin/biome`, "check", "--write", `--stdin-file-path=${path}`],
{ cwd: root, encoding: "utf8", input: content, maxBuffer: 64 * 1024 * 1024 },
)
: content
const check = process.argv.includes("--check")
const stale = writeArtifacts(artifacts, { root, check, format })
if (check && stale.length) {
process.stderr.write(`Generated files are stale: ${stale.join(", ")}; run pnpm generate\n`)
process.exitCode = 1
}
20 changes: 20 additions & 0 deletions kit/seeds/graphql/scripts/spec-model.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import { join } from "node:path"
import { type ApiModel, adaptGraphql, readGraphql } from "@wirecat/cli-base/codegen"

// SAMPLE: the endpoint every operation is sent to.
const URL = "https://comments.example.invalid/graphql"

/** The schema as committed; readGraphql refuses one whose hash no longer matches provenance.json. */
export const specModel = async (root: string): Promise<{ model: ApiModel; notes: string[] }> => {
const dir = join(root, "spec/clidev")
const model = adaptGraphql(readGraphql(dir), {
url: URL,
sourceUrl: URL,
// SAMPLE: the schema's own scalars as the JSON they travel as, such as { DateTime: { type: "string" } }; a scalar
// left out stops generation.
scalars: {},
// SAMPLE: field → why the CLI leaves it out, as `mutation.<name>` when both roots have one of that name.
exclude: {},
})
return { model, notes: [] }
}
Loading
Loading