diff --git a/CHANGELOG.md b/CHANGELOG.md index fb2dd22..039bc6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,13 @@ Every entry says what changed as a caller sees it, why, and what to watch for - **The command vocabulary has a tracker's nouns: `issues`, `teams`, `states` and `labels`.** cli-core's tracker commands (`issues list`, `teams list`…) name them, so `cli-dev lint` passes a tracker CLI's command tree. `labels` are a tracker's own, shared by its users; `tags` stay the labels the owner puts on things. - +- **A CLI can say how Desktop signs it in, in Desktop's own window.** `ManifestIdentity.signIn` takes an optional + `methods` list, each `{ id, label, words, stdin? }`, and `cli-dev manifest` writes it to `desktop.signIn.methods`. + Until now an own tool could only be signed in at a terminal. `words` start with `{profile}` and name a command the + CLI has; `stdin: true` says the secret the person types is the command's whole stdin. Nothing else (a password + variable, a client file, OAuth words) is accepted, because Desktop does not take those from a tool it did not build. + Watch for: a manifest without `methods` is byte-for-byte as before; one with it needs a Desktop that shows a token + field for a `stdin` method. - **ydisk (`@wirecat/yandex-disk-cli`) joins the shared lists.** It is in `PARITY_GROUPS`' `shared-roots` group, beside notion, so `cli-dev audit --family` installs its latest release and compares the root commands every CLI shares. Its monthly run holds 03:04 UTC in WC-CI-9's table. Watch for: a CLI's `--family` audit now installs one more package. diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 8fc8be6..5b7d1cf 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -389,7 +389,7 @@ cli-dev manifest --program dist/program.js --identity dist/wcat.js --check # fa `--program` exports `createProgram`; `--identity` exports `WCAT`, a `ManifestIdentity`: the `wcatStart` argument (`command`, `version`, `description`, `docs`) plus cli-core's `appName` and `envPrefix`, and the only texts the -developer types: `tagline` (at most 55 characters), `signIn: { gives, asks }` and, when the CLI has a sync command, +developer types: `tagline` (at most 55 characters), `signIn: { gives, asks, methods? }` and, when the CLI has a sync command, `syncs` (what it copies, at most 40 characters), and `hosts` (every host it contacts, `[]` for none) with `userHosts` (hosts the person chooses, in words, at most 120 characters), and `meetingsProvider` (cli-core's provider name on the calls or meetings it saves) for a CLI whose calls Desktop opens. An optional @@ -411,7 +411,7 @@ come from `package.json`. | `desktop.sync` | for a root `sync`, or the only ` sync`: `run` is `[{profile}] --record --json`; `last` is `runs list command:sync status:success --limit 50 --no-record --json` for a root `sync` with `runs list`, else `null` (`runs list` matches `command:` exactly, and a plain word cannot hold the space of `contacts sync`); `lastShape: "runs"`, `what` from `syncs`, `note: null`. A sync without `syncs` is refused | | `desktop.storage` | `{ app: appName, env: envPrefix }` | | `desktop.meetings` | with `meetingsProvider`: `{ provider, show, transcript }`, `[{profile}] meetings show {id}` and `meetings transcript {id}`, `--no-record --json`; how Desktop opens a client's call. Absent, not `null`, without it: Desktop 0.6.8 and older refuse a key they do not read. A provider without both commands is refused | -| `desktop.tagline`, `desktop.signIn` | as declared; `signIn` is `null` when not | +| `desktop.tagline`, `desktop.signIn` | as declared; `signIn` is `null` when not. `signIn.methods`, only when declared: `{ id, label, words, stdin? }` for each sign-in Desktop runs in its window; `words` start with `{profile}` and name a command of the CLI, and `stdin: true` sends what the person types as the whole stdin | | every other catalog key | `null`: `search`, `tasks`, `settings` and the `store*` keys | Every string in every array is a plain word, Desktop's own rule (`PLAIN_WORD`): letters, digits and `._:=,/+@-`, at diff --git a/src/wcat/manifest.test.ts b/src/wcat/manifest.test.ts index 29bd23e..2b42883 100644 --- a/src/wcat/manifest.test.ts +++ b/src/wcat/manifest.test.ts @@ -177,6 +177,22 @@ describe("buildManifest", () => { expect(() => build({ meetingsProvider: "Acme PBX" }, describeProgram(tree))).toThrow("a provider name") }) + it("passes the sign-ins Desktop runs in its window, only when declared and only for a command the CLI has", () => { + const token = { id: "token", label: "API token", words: ["{profile}", "session", "start", "--json"], stdin: true } + const signIn = { ...identity.signIn, methods: [token] } as ManifestIdentity["signIn"] + expect(build().desktop.signIn).not.toHaveProperty("methods") + expect(build({ signIn }).desktop.signIn?.methods).toEqual([token]) + const as = (words: string[]) => + ({ ...identity.signIn, methods: [{ ...token, words }] }) as ManifestIdentity["signIn"] + expect(() => build({ signIn: as(["session", "start"]) })).toThrow("start with {profile}") + expect(() => build({ signIn: as(["{profile}", "session"]) })).toThrow("`session` names no command") + expect(() => build({ signIn: as(["{profile}", "session", "start", "{port}"]) })).toThrow("the only slot") + expect(() => build({ signIn: as(["{profile}", "session", "start", "$(id)"]) })).toThrow("is not a plain word") + expect(() => + build({ signIn: { ...identity.signIn, methods: [{ ...token, password: "ACME_TOKEN" }] } as never }), + ).toThrow(/password/) + }) + it("matches runs list's query: command:sync status:success are two exact terms", () => { const ast = parseLucene(["command:sync", "status:success"].join(" "), { defaultField: "none" }) expect(JSON.stringify(ast)).toMatch(/"field":"command","operator":"term","value":"sync"/) diff --git a/src/wcat/manifest.ts b/src/wcat/manifest.ts index 54a7e55..c0838d5 100644 --- a/src/wcat/manifest.ts +++ b/src/wcat/manifest.ts @@ -43,11 +43,26 @@ const plainWord = v.pipe( const words = v.pipe(v.array(plainWord), v.minLength(1)) const line = (max: number) => v.pipe(v.string(), v.regex(/^\S(?:[^\n\r]*\S)?$/, "one line of text"), v.maxLength(max)) +/** + * A sign-in Desktop runs in its own window. Only the parts Desktop accepts from a tool it did not build: the words, and + * whether the secret the person types is the command's whole stdin. + */ +const signInMethodSchema = v.strictObject({ + id: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9-]{0,31}$/, "a lower-case method id")), + /** The button or tab: "API token". */ + label: line(40), + /** `{profile}` first, then the command: `["{profile}", "session", "start", "--json"]`. */ + words, + stdin: v.optional(v.boolean()), +}) + const signInSchema = v.strictObject({ /** What signing in lets the agent do, in a sentence: "Lets your agent read your Acme contacts." */ gives: line(300), /** What the person is asked for: "An Acme API token, from Settings → API." */ asks: line(300), + /** Left out when the CLI signs in only at a terminal, so the manifest of every other CLI stays as it was. */ + methods: v.optional(v.pipe(v.array(signInMethodSchema), v.minLength(1))), }) export type SignIn = v.InferOutput @@ -294,6 +309,24 @@ export const buildManifest = ({ identity, commands, pkg, skills }: ManifestInput } : {} + const methods = identity.signIn?.methods + for (const method of methods ?? []) { + const [first, ...rest] = method.words + if (first !== "{profile}" || !profiles) + throw new ManifestError([ + `signIn method ${method.id}: Desktop signs in a profile, so its words start with {profile}`, + ]) + // Arguments may follow the command (`session start qr`), so any leading run of words that is a command will do. + const runsAt = (end: number) => { + const command = at.get(rest.slice(0, end + 1).join(" ")) + return command !== undefined && (command.commands.length === 0 || command.runnable === true) + } + if (!rest.some((_, end) => runsAt(end))) + throw new ManifestError([`signIn method ${method.id}: \`${rest.join(" ")}\` names no command of this CLI`]) + if (rest.some((word) => word.includes("{"))) + throw new ManifestError([`signIn method ${method.id}: {profile} is the only slot Desktop fills in a sign-in`]) + } + const twice = identity.hosts?.filter((host, index) => identity.hosts?.indexOf(host) !== index) ?? [] if (twice.length > 0) throw new ManifestError(twice.map((host) => `hosts: ${host} is listed twice`)) if (identity.userHosts && !identity.hosts) @@ -349,7 +382,9 @@ export const buildManifest = ({ identity, commands, pkg, skills }: ManifestInput : null, search: null, setup: setupPath ? [...profile, ...setupPath.split(" ")] : null, - signIn: identity.signIn ? { gives: identity.signIn.gives, asks: identity.signIn.asks } : null, + signIn: identity.signIn + ? { gives: identity.signIn.gives, asks: identity.signIn.asks, ...(methods ? { methods } : {}) } + : null, skill: skills && has("skill status", "skill install", "skill show") ? {