From eb2edf167adb6efb2b65e17e299c77e68c6156ed Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 17:08:19 +0100 Subject: [PATCH 1/3] feat(manifest): defineCli and parseCliConfig, the shape of wirecat.config.ts Co-Authored-By: Claude Opus 5.5 --- changes/feat-cli-config.md | 7 +++ docs/dev/CRM.md | 2 + package.json | 4 ++ src/manifest/index.test.ts | 58 ++++++++++++++++++ src/manifest/index.ts | 121 +++++++++++++++++++++++++++++++++++++ 5 files changed, 192 insertions(+) create mode 100644 changes/feat-cli-config.md create mode 100644 src/manifest/index.test.ts create mode 100644 src/manifest/index.ts diff --git a/changes/feat-cli-config.md b/changes/feat-cli-config.md new file mode 100644 index 000000000..bf2390798 --- /dev/null +++ b/changes/feat-cli-config.md @@ -0,0 +1,7 @@ +### Added + +- **`@wirecat/cli-core/manifest`: `defineCli` and `parseCliConfig`, the shape of `wirecat.config.ts`.** One file names + the CLI (command, package, prefix, provider, service, owner), its API description, its sign-in (`none`, `token`, or + `oauth2-pkce` with its scopes and redirect), its category and, for a CRM, its source. cli-template's + `new --from-config` builds a CLI from it. Each error names the field; the source is checked against the generated + API by `parseCrmManifest`. diff --git a/docs/dev/CRM.md b/docs/dev/CRM.md index 7f8bd26b2..14d39c830 100644 --- a/docs/dev/CRM.md +++ b/docs/dev/CRM.md @@ -246,6 +246,8 @@ hooks })` builds the `CrmSource` (design and evidence: cli-private `plans/2026-1 answers; a CLI runs it in a test, so a wrong path fails before any sync. - `hooks.enrich` reads more for a whole page in one batch before the map; `optional` makes a refused kind a gap; `select.max` caps the account's own fields in `{select}`; mapped fields are always asked for. +- `defineCli` and `parseCliConfig` (`@wirecat/cli-core/manifest`) give the whole CLI's `wirecat.config.ts`: identity, + API description, sign-in preset, category and this source. - Not yet: deletions named in the answer, a live `list`. - `src/crm/manifest/manifest.test.ts` writes HubSpot's contacts, companies and deals as a manifest and runs `crmSourceContract`, faults included, against a strict fake of HubSpot's API. diff --git a/package.json b/package.json index 01bba07ce..b13377394 100644 --- a/package.json +++ b/package.json @@ -143,6 +143,10 @@ "types": "./dist/calendar/testing/index.d.ts", "default": "./dist/calendar/testing/index.js" }, + "./manifest": { + "types": "./dist/manifest/index.d.ts", + "default": "./dist/manifest/index.js" + }, "./crm": { "types": "./dist/crm/index.d.ts", "default": "./dist/crm/index.js" diff --git a/src/manifest/index.test.ts b/src/manifest/index.test.ts new file mode 100644 index 000000000..284703af8 --- /dev/null +++ b/src/manifest/index.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it } from "vitest" +import { type CliConfig, defineCli, parseCliConfig } from "./index.js" + +const config: CliConfig = { + identity: { + command: "acme", + package: "@wirecat/acme-cli", + prefix: "WCACME", + provider: "acme", + service: "Acme", + owner: "WireCatLabs", + }, + spec: { kind: "openapi", from: "https://api.acme.test/openapi.json" }, + auth: { preset: "token" }, + category: "other", +} + +describe("parseCliConfig", () => { + it("takes a config as defineCli gives it", () => { + expect(parseCliConfig(defineCli(config))).toEqual(config) + const oauth = { + ...config, + auth: { preset: "oauth2-pkce" as const, scopes: ["record:read"] }, + hooks: "./src/hooks.ts", + } + expect(parseCliConfig(oauth)).toEqual(oauth) + }) + + it("names where a config is wrong", () => { + expect(() => parseCliConfig({ ...config, identity: { ...config.identity, command: "Acme" } })).toThrow( + "wirecat.config: identity.command: lower-case letters and digits, words joined by one dash", + ) + expect(() => parseCliConfig({ ...config, auth: { preset: "oauth2-pkce" } })).toThrow("wirecat.config: auth.scopes") + expect(() => + parseCliConfig({ + ...config, + auth: { preset: "oauth2-pkce", scopes: [], redirect: { kind: "relay", url: "http://relay.test/" } }, + }), + ).toThrow("auth.redirect") + expect(() => parseCliConfig({ ...config, spec: { kind: "openapi", from: "http://api.acme.test/x" } })).toThrow( + "spec.from", + ) + expect(() => parseCliConfig({ ...config, category: "crm" })).toThrow("a crm CLI needs its source") + for (const from of ["/etc/spec.json", "//evil.test/x", "../../spec.json", "https://", "file:spec.json"]) + expect(() => parseCliConfig({ ...config, spec: { kind: "openapi", from } })).toThrow("spec.from") + expect(parseCliConfig({ ...config, spec: { kind: "openapi", from: "spec/openapi.json" } }).spec.from).toBe( + "spec/openapi.json", + ) + expect(() => parseCliConfig({ ...config, identity: { ...config.identity, command: "acme-" } })).toThrow( + "identity.command", + ) + 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, extra: true })).toThrow("wirecat.config") + }) +}) diff --git a/src/manifest/index.ts b/src/manifest/index.ts new file mode 100644 index 000000000..2db70c77b --- /dev/null +++ b/src/manifest/index.ts @@ -0,0 +1,121 @@ +import { isAbsolute } from "node:path" +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" + +export type CliAuth = + | { preset: "none" } + /** A token or key, sent where the spec's `securitySchemes` say: a bearer header, an API key header or query. */ + | { preset: "token" } + /** The browser sign-in the spec's authorization code flow declares; the redirect is what the app registered. */ + | { + preset: "oauth2-pkce" + scopes: readonly string[] + scheme?: string + redirect?: OAuthProvider["redirect"] + revokeUrl?: string + authorizeParams?: Record + /** The provider sends a new refresh token on each refresh; the spec cannot say so. */ + rotating?: boolean + } + +/** One file, `wirecat.config.ts`, that `new --from-config` builds a CLI from. */ +export interface CliConfig { + identity: { + /** The word people type: `attio`. */ + command: string + /** `@wirecat/attio-cli`. */ + package: string + /** The environment variables' prefix: `WCATTIO`. */ + prefix: string + /** The registry name: `attio`. */ + provider: string + /** The name people know: `Attio`. */ + service: string + /** The GitHub owner of the repository. */ + owner: string + } + spec: { kind: "openapi" | "swagger"; from: string } + auth: CliAuth + category: "crm" | "other" + /** The CRM source; checked against the generated API by `parseCrmManifest` once the api group exists. */ + source?: CrmManifest + /** The module of named hooks, relative to the config: `./src/hooks.ts`. */ + hooks?: string +} + +/** Types the config in the editor; it returns what it is given. */ +export const defineCli = (config: CliConfig): CliConfig => config + +const word = v.pipe( + v.string(), + v.regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "lower-case letters and digits, words joined by one dash"), +) + +/** In the project: no absolute path, no `..`, no scheme. */ +const projectPath = (text: string) => + !isAbsolute(text) && !text.split(/[\\/]/).includes("..") && !/^[a-z][a-z0-9+.-]*:/i.test(text) + +const schema = v.strictObject({ + identity: v.strictObject({ + command: word, + package: v.pipe(v.string(), v.regex(/^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/, "an npm package name")), + prefix: v.pipe(v.string(), v.regex(/^[A-Z][A-Z0-9_]*$/, "upper-case letters, digits and underscores")), + provider: word, + service: v.pipe(v.string(), v.minLength(1)), + 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"]), + from: v.pipe( + v.string(), + v.check( + (text) => /^https:\/\/[^/\s]+/.test(text) || (text.length > 0 && projectPath(text)), + "an https URL or a path in the project", + ), + ), + }), + auth: v.variant("preset", [ + v.strictObject({ preset: v.literal("none") }), + v.strictObject({ preset: v.literal("token") }), + v.strictObject({ + preset: v.literal("oauth2-pkce"), + scopes: v.array(v.string()), + scheme: v.optional(v.string()), + revokeUrl: v.optional(v.pipe(v.string(), v.startsWith("https://"))), + authorizeParams: v.optional(v.record(v.string(), v.string())), + rotating: v.optional(v.boolean()), + redirect: v.optional( + v.variant("kind", [ + v.strictObject({ kind: v.literal("loopback"), host: v.optional(v.literal("localhost")) }), + v.strictObject({ kind: v.literal("relay"), url: v.pipe(v.string(), v.startsWith("https://")) }), + ]), + ), + }), + ]), + category: v.picklist(["crm", "other"]), + source: v.optional(v.looseObject({})), + hooks: v.optional(v.pipe(v.string(), v.startsWith("./"), v.check(projectPath, "a module in the project"))), +}) + +/** The config checked against its shape; every error names where it is. A CRM CLI needs its source. */ +export const parseCliConfig = (input: unknown): CliConfig => { + const parsed = v.safeParse(schema, input) + if (!parsed.success) { + const [issue] = parsed.issues + throw new CliError("configuration_error", `wirecat.config: ${v.getDotPath(issue) ?? "(root)"}: ${issue.message}`, { + reason: "manifest.invalid", + }) + } + const config = parsed.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", { + reason: "manifest.invalid", + }) + if (config.category === "crm" && !config.source) + throw new CliError("configuration_error", "wirecat.config: source: a crm CLI needs its source", { + reason: "manifest.invalid", + }) + return config +} From bee5dc243e0c39f2304f7ffcfe4b26d086749d87 Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 17:14:30 +0100 Subject: [PATCH 2/3] feat(manifest): the config's category takes cli-template's categories Co-Authored-By: Claude Opus 5.5 --- src/manifest/index.ts | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/manifest/index.ts b/src/manifest/index.ts index 2db70c77b..222badf7f 100644 --- a/src/manifest/index.ts +++ b/src/manifest/index.ts @@ -20,6 +20,9 @@ export type CliAuth = rotating?: boolean } +export const CLI_CATEGORIES = ["messenger", "mail", "notes", "files", "meetings", "calendar", "crm", "other"] as const +export type CliCategory = (typeof CLI_CATEGORIES)[number] + /** One file, `wirecat.config.ts`, that `new --from-config` builds a CLI from. */ export interface CliConfig { identity: { @@ -38,7 +41,8 @@ export interface CliConfig { } spec: { kind: "openapi" | "swagger"; from: string } auth: CliAuth - category: "crm" | "other" + /** 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 /** The module of named hooks, relative to the config: `./src/hooks.ts`. */ @@ -94,7 +98,7 @@ const schema = v.strictObject({ ), }), ]), - category: v.picklist(["crm", "other"]), + category: v.picklist(CLI_CATEGORIES), source: v.optional(v.looseObject({})), hooks: v.optional(v.pipe(v.string(), v.startsWith("./"), v.check(projectPath, "a module in the project"))), }) From a2c808d717559d8ae11c82ff65d69ff842f1874c Mon Sep 17 00:00:00 2001 From: leemour Date: Tue, 17 Nov 2026 17:23:09 +0100 Subject: [PATCH 3/3] feat(manifest): spec.from is the https URL; identity drops provider, which the source carries The kit reads nothing else yet: a local description has no URL to resolve relative servers against, and a CRM source names its own provider. Either can be added later without breaking a config. Co-Authored-By: Claude Opus 5.5 --- changes/feat-cli-config.md | 8 ++++---- src/manifest/index.test.ts | 13 ++++++++----- src/manifest/index.ts | 9 ++------- 3 files changed, 14 insertions(+), 16 deletions(-) diff --git a/changes/feat-cli-config.md b/changes/feat-cli-config.md index bf2390798..cd380d205 100644 --- a/changes/feat-cli-config.md +++ b/changes/feat-cli-config.md @@ -1,7 +1,7 @@ ### Added - **`@wirecat/cli-core/manifest`: `defineCli` and `parseCliConfig`, the shape of `wirecat.config.ts`.** One file names - the CLI (command, package, prefix, provider, service, owner), its API description, its sign-in (`none`, `token`, or - `oauth2-pkce` with its scopes and redirect), its category and, for a CRM, its source. cli-template's - `new --from-config` builds a CLI from it. Each error names the field; the source is checked against the generated - API by `parseCrmManifest`. + the CLI (command, package, environment prefix, service, owner), its API description (an https URL), its sign-in + (`none`, `token`, or `oauth2-pkce` with the options `oauthPreset` takes), its category (cli-template's, or `other`) + and, for a CRM, its source. cli-template's `new --from-config` builds a CLI from it. Each error names the field; the + source is checked against the generated API by `parseCrmManifest`. diff --git a/src/manifest/index.test.ts b/src/manifest/index.test.ts index 284703af8..b50baeb49 100644 --- a/src/manifest/index.test.ts +++ b/src/manifest/index.test.ts @@ -6,7 +6,6 @@ const config: CliConfig = { command: "acme", package: "@wirecat/acme-cli", prefix: "WCACME", - provider: "acme", service: "Acme", owner: "WireCatLabs", }, @@ -41,11 +40,15 @@ describe("parseCliConfig", () => { "spec.from", ) expect(() => parseCliConfig({ ...config, category: "crm" })).toThrow("a crm CLI needs its source") - for (const from of ["/etc/spec.json", "//evil.test/x", "../../spec.json", "https://", "file:spec.json"]) - expect(() => parseCliConfig({ ...config, spec: { kind: "openapi", from } })).toThrow("spec.from") - expect(parseCliConfig({ ...config, spec: { kind: "openapi", from: "spec/openapi.json" } }).spec.from).toBe( + for (const from of [ + "/etc/spec.json", + "//evil.test/x", + "../../spec.json", + "https://", + "file:spec.json", "spec/openapi.json", - ) + ]) + expect(() => parseCliConfig({ ...config, spec: { kind: "openapi", from } })).toThrow("spec.from") expect(() => parseCliConfig({ ...config, identity: { ...config.identity, command: "acme-" } })).toThrow( "identity.command", ) diff --git a/src/manifest/index.ts b/src/manifest/index.ts index 222badf7f..7a1947c1c 100644 --- a/src/manifest/index.ts +++ b/src/manifest/index.ts @@ -32,13 +32,12 @@ export interface CliConfig { package: string /** The environment variables' prefix: `WCATTIO`. */ prefix: string - /** The registry name: `attio`. */ - provider: string /** The name people know: `Attio`. */ service: string /** The GitHub owner of the repository. */ owner: string } + /** `from`: the https URL the description is published at. */ spec: { kind: "openapi" | "swagger"; from: string } auth: CliAuth /** cli-template's `--category`; `other` is any API outside them. */ @@ -66,7 +65,6 @@ const schema = v.strictObject({ command: word, package: v.pipe(v.string(), v.regex(/^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/, "an npm package name")), prefix: v.pipe(v.string(), v.regex(/^[A-Z][A-Z0-9_]*$/, "upper-case letters, digits and underscores")), - provider: word, service: v.pipe(v.string(), v.minLength(1)), owner: v.pipe(v.string(), v.regex(/^[A-Za-z0-9](?:-?[A-Za-z0-9]){0,38}$/, "a GitHub owner")), }), @@ -74,10 +72,7 @@ const schema = v.strictObject({ kind: v.picklist(["openapi", "swagger"]), from: v.pipe( v.string(), - v.check( - (text) => /^https:\/\/[^/\s]+/.test(text) || (text.length > 0 && projectPath(text)), - "an https URL or a path in the project", - ), + v.check((text) => /^https:\/\/[^/\s]+/.test(text), "the https URL the description is published at"), ), }), auth: v.variant("preset", [