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-cli-config.md
Original file line number Diff line number Diff line change
@@ -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`.
2 changes: 2 additions & 0 deletions docs/dev/CRM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
61 changes: 61 additions & 0 deletions src/manifest/index.test.ts
Original file line number Diff line number Diff line change
@@ -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")
})
})
120 changes: 120 additions & 0 deletions src/manifest/index.ts
Original file line number Diff line number Diff line change
@@ -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<string, string>
/** 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
}
Loading