diff --git a/changes/feat-cli-config.md b/changes/feat-cli-config.md new file mode 100644 index 000000000..cd380d205 --- /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, 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/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..b50baeb49 --- /dev/null +++ b/src/manifest/index.test.ts @@ -0,0 +1,61 @@ +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", + 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", + "spec/openapi.json", + ]) + expect(() => parseCliConfig({ ...config, spec: { kind: "openapi", from } })).toThrow("spec.from") + 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..7a1947c1c --- /dev/null +++ b/src/manifest/index.ts @@ -0,0 +1,120 @@ +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 + } + +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: { + /** The word people type: `attio`. */ + command: string + /** `@wirecat/attio-cli`. */ + package: string + /** The environment variables' prefix: `WCATTIO`. */ + prefix: 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. */ + 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`. */ + 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")), + 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), "the https URL the description is published at"), + ), + }), + 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(CLI_CATEGORIES), + 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 +}