diff --git a/changes/feat-manifest-desktop-account-remove.md b/changes/feat-manifest-desktop-account-remove.md new file mode 100644 index 0000000..902b9ef --- /dev/null +++ b/changes/feat-manifest-desktop-account-remove.md @@ -0,0 +1,12 @@ +### Added + +- **The manifest tells WireCat Desktop how to remove an account.** `desktop.accountRemove` is written from the + command tree: `signOut` when the CLI has `session end`, `remove` when its `account remove` takes `--keep-data`, + `--delete-data` and `--dry-run`. The key is left out for a CLI with neither, because a Desktop that does + not read it refuses the whole manifest. See [the reference](../docs/REFERENCE.md). + +### Fixed + +- **WireCat Desktop shows when a ` sync` last ran.** For `meetings sync`, `desktop.sync.last` was `null`; it is + now `runs list 'command:"meetings sync" status:success'`, one word as in Desktop's catalog. It is the one word the + manifest takes that is not plain, and only in `sync.last`. See [the reference](../docs/REFERENCE.md). diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index d82d46d..7c325b9 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -427,13 +427,14 @@ come from `package.json`. | `desktop.runs` | `runs list {query} --limit {limit} --page {page}` and `runs show {run}`, `--no-record --json` | | `desktop.skill` | `skill status`, `skill install --for {target}`, `skill show`, when `skills/` ships too | | `desktop.mcpServer` | `mcp server start --port {port}`, `stop`, `status`, `mcp revoke`, `mcp config`; `--public-url` and `--profiles all` where the command takes them. No `port`: Desktop gives the tool a free port no catalog tool uses and fills `{port}` | -| `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.sync` | for a root `sync`, or the only ` sync`: `run` is `[{profile}] --record --json`; with `runs list`, `last` is `runs list command:sync status:success --limit 50 --no-record --json` for a root `sync`, and `runs list 'command:"contacts sync" status:success' --limit 50 --no-record --json` for a ` sync`: one word, the quoted phrase `runs list` matches exactly. It is the only word that is not plain (`SYNC_QUERY`), and only `sync.last` takes it; without `runs list`, `null`; `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.accountRemove` | with `profiles` and `session end` or `account remove`: `signOut` is `{profile} session end --record --json`, else `null`; `remove` is `{profile} account remove --keep-data` and `--delete-data`, `--record --json`, `dryRun: "--dry-run"`, `confirm: "--yes"`, `minVersion: "0.0.0"`, when `account remove` takes `--keep-data`, `--delete-data` and `--dry-run` (`--yes` is cli-core's global flag), else `null`; `removes: ["signIn"]` and `keeps: ["settings", "data", "listed"]` say what the sign-out alone does, `[]` without one. Absent, not `null`, without both commands, as `meetings` is | | `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 +Every string in every array but that query is a plain word, Desktop's own rule (`PLAIN_WORD`): letters, digits and `._:=,/+@-`, at most two leading dashes, `--` alone and `{name}` slots. `buildManifest` throws a `ManifestError` naming the key and the word instead of writing anything else. `manifestSchema` (valibot) and `manifestJsonSchema()` check a manifest; `manifestText` gives the exact bytes the command writes. diff --git a/src/wcat/manifest.test.ts b/src/wcat/manifest.test.ts index 2b42883..1fd977e 100644 --- a/src/wcat/manifest.test.ts +++ b/src/wcat/manifest.test.ts @@ -147,14 +147,14 @@ describe("buildManifest", () => { ]) }) - it("runs a single sync but finds its last run only for a one-word sync, which a plain word can name", () => { + it("runs a single sync and finds its last run by the quoted phrase, as Desktop's catalog does", () => { const tree = new Command("acme") .addCommand(new Command("doctor").action(() => {})) .addCommand(new Command("runs").addCommand(new Command("list").action(() => {}))) .addCommand(new Command("contacts").addCommand(new Command("sync").action(() => {}))) expect(build({}, describeProgram(tree)).desktop.sync).toEqual({ run: ["contacts", "sync", "--record", "--json"], - last: null, + last: ["runs", "list", 'command:"contacts sync" status:success', "--limit", "50", "--no-record", "--json"], lastShape: "runs", what: "contacts and deals", note: null, @@ -177,6 +177,46 @@ describe("buildManifest", () => { expect(() => build({ meetingsProvider: "Acme PBX" }, describeProgram(tree))).toThrow("a provider name") }) + it("removes an account with session end and account remove, and leaves the key out for a CLI with neither", () => { + const withAccounts = (account: Command) => { + const root = program().addCommand(account) + root.commands.find((command) => command.name() === "session")?.addCommand(new Command("end").action(() => {})) + return describeProgram(root) + } + const remove = new Command("remove").action(() => {}) + for (const flag of ["--keep-data", "--delete-data", "--dry-run"]) remove.option(flag, flag) + const full = new Command("account").addCommand(new Command("list").action(() => {})).addCommand(remove) + expect(build({}, withAccounts(full)).desktop.accountRemove).toEqual({ + signOut: ["{profile}", "session", "end", "--record", "--json"], + remove: { + minVersion: "0.0.0", + keepData: ["{profile}", "account", "remove", "--keep-data", "--record", "--json"], + deleteData: ["{profile}", "account", "remove", "--delete-data", "--record", "--json"], + dryRun: "--dry-run", + confirm: "--yes", + }, + removes: ["signIn"], + keeps: ["settings", "data", "listed"], + }) + + const listOnly = new Command("account").addCommand(new Command("list").action(() => {})) + expect(build({}, withAccounts(listOnly)).desktop.accountRemove).toEqual({ + signOut: ["{profile}", "session", "end", "--record", "--json"], + remove: null, + removes: ["signIn"], + keeps: ["settings", "data", "listed"], + }) + + const removeOnly = program().addCommand(full) + expect(build({}, describeProgram(removeOnly)).desktop.accountRemove).toMatchObject({ + signOut: null, + removes: [], + keeps: [], + }) + + expect(build().desktop).not.toHaveProperty("accountRemove") + }) + 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"] @@ -199,6 +239,28 @@ describe("buildManifest", () => { expect(JSON.stringify(ast)).toMatch(/"field":"status","operator":"term","value":"success"/) }) + it("matches runs list's query: a quoted command is one phrase, so it equals the recorded `contacts sync`", () => { + const ast = JSON.stringify(parseLucene('command:"contacts sync" status:success', { defaultField: "none" })) + expect(ast).toMatch(/"field":"command","operator":"phrase","value":"contacts sync"/) + expect(ast).toMatch(/"field":"status","operator":"term","value":"success"/) + }) + + it("takes the quoted sync query in sync.last only, and no other quoted word", () => { + const manifest = build() + const query = 'command:"contacts sync" status:success' + const at = (desktop: object) => v.safeParse(manifestSchema, { ...manifest, desktop }).success + const sync = manifest.desktop.sync as NonNullable + expect(at({ ...manifest.desktop, sync: { ...sync, last: ["runs", "list", query] } })).toBe(true) + expect(at({ ...manifest.desktop, sync: { ...sync, run: ["runs", "list", query] } })).toBe(false) + expect(at({ ...manifest.desktop, doctor: [query] })).toBe(false) + for (const word of [ + 'command:"contacts sync"; rm -rf ~', + 'command:"$(id) x" status:success', + 'command:"sync" status:success', + ]) + expect(at({ ...manifest.desktop, sync: { ...sync, last: ["runs", "list", word] } })).toBe(false) + }) + it("refuses a CLI without doctor, a tagline or its wcat- bin, saying what to add", () => { expect(() => build({}, [])).toThrow("no doctor command") expect(() => build({ tagline: undefined })).toThrow("no tagline") diff --git a/src/wcat/manifest.ts b/src/wcat/manifest.ts index c0838d5..3786fba 100644 --- a/src/wcat/manifest.ts +++ b/src/wcat/manifest.ts @@ -1,7 +1,8 @@ /** * `contracts/wirecat.json`, format 2: what a CLI tells WireCat Desktop about itself, built from its command tree so * nothing in it is typed by hand except the tagline and the sign-in texts. Desktop reads it out of the npm tarball - * without running the package, so every array holds plain words only: the same rule as Desktop's `community.rs`. + * without running the package, so every array holds plain words only, the same rule as Desktop's `community.rs`, but + * the one query in `sync.last` (`SYNC_QUERY`). */ import * as v from "valibot" import { type CommandInfo, flatten, type OptionInfo, summaryOf } from "../commands/registry.js" @@ -41,6 +42,14 @@ const plainWord = v.pipe( ), ) const words = v.pipe(v.array(plainWord), v.minLength(1)) + +/** + * The one word that is not plain: `runs list` matches `command:` exactly, so a ` sync` is found only as the + * quoted phrase, `command:"meetings sync" status:success`. Desktop runs it without a shell and accepts this form in + * `sync.last` only. + */ +export const SYNC_QUERY = /^command:"[a-z0-9][a-z0-9-]*(?: [a-z0-9][a-z0-9-]*)+" status:success$/ +const lastWords = v.pipe(v.array(v.union([plainWord, v.pipe(v.string(), v.regex(SYNC_QUERY))])), v.minLength(1)) const line = (max: number) => v.pipe(v.string(), v.regex(/^\S(?:[^\n\r]*\S)?$/, "one line of text"), v.maxLength(max)) /** @@ -91,7 +100,7 @@ const desktopSchema = v.strictObject({ sync: v.nullable( v.strictObject({ run: words, - last: v.nullable(words), + last: v.nullable(lastWords), lastShape: v.literal("runs"), what: line(40), note: v.null(), @@ -110,6 +119,26 @@ const desktopSchema = v.strictObject({ env: v.pipe(v.string(), v.regex(/^[A-Z][A-Z0-9_]*$/, "an upper-case environment prefix")), }), settings: v.null(), + /** + * Removing one account: `session end` signs it out, cli-core's `account remove` forgets it. `removes` and `keeps` + * say what the sign-out alone takes and leaves. Left out when the CLI has neither, like `meetings`. + */ + accountRemove: v.optional( + v.strictObject({ + signOut: v.nullable(words), + remove: v.nullable( + v.strictObject({ + minVersion: v.literal("0.0.0"), + keepData: words, + deleteData: words, + dryRun: plainWord, + confirm: plainWord, + }), + ), + removes: v.array(v.literal("signIn")), + keeps: v.array(v.picklist(["settings", "data", "listed"])), + }), + ), /** * How a client's call or a meeting this tool saved opens: Desktop finds the tool by `provider`. Left out, not `null`, * when the tool records none, because Desktop 0.6.8 and older refuse a manifest with a key they do not read. @@ -280,11 +309,10 @@ export const buildManifest = ({ identity, commands, pkg, skills }: ManifestInput throw new ManifestError([ `no syncs: \`${syncPath.join(" ")}\` exists, so add \`syncs\`, what it copies in at most 40 characters`, ]) - // `runs list` matches `command:` exactly and a plain word holds no space, so only a one-word path can be found. + const query = + syncPath?.length === 1 ? ["command:sync", "status:success"] : [`command:"${syncPath?.join(" ")}" status:success`] const last = - syncPath?.length === 1 && has("runs list") - ? ["runs", "list", "command:sync", "status:success", "--limit", "50", "--no-record", "--json"] - : null + syncPath && has("runs list") ? ["runs", "list", ...query, "--limit", "50", "--no-record", "--json"] : null const sync = syncPath ? { run: [...profile, ...syncPath, "--record", "--json"], @@ -309,6 +337,31 @@ export const buildManifest = ({ identity, commands, pkg, skills }: ManifestInput } : {} + const signOut = profiles && has("session end") ? [...profile, "session", "end", "--record", "--json"] : null + // `--yes` is a global flag of cli-core's programs, read with optsWithGlobals, so `account remove` does not list it. + const remove = + profiles && ["--keep-data", "--delete-data", "--dry-run"].every((flag) => takes("account remove", flag)) + ? { + // The manifest ships inside the version it describes, so that version always has the command. + minVersion: "0.0.0", + keepData: [...profile, "account", "remove", "--keep-data", "--record", "--json"], + deleteData: [...profile, "account", "remove", "--delete-data", "--record", "--json"], + dryRun: "--dry-run", + confirm: "--yes", + } + : null + const accountRemove = + signOut || remove + ? { + accountRemove: { + signOut, + remove, + removes: signOut ? ["signIn"] : [], + keeps: signOut ? ["settings", "data", "listed"] : [], + }, + } + : {} + const methods = identity.signIn?.methods for (const method of methods ?? []) { const [first, ...rest] = method.words @@ -406,6 +459,7 @@ export const buildManifest = ({ identity, commands, pkg, skills }: ManifestInput storeReset: null, storage: { app: identity.appName, env: identity.envPrefix }, settings: null, + ...accountRemove, ...meetings, }, }