Skip to content
Draft
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
12 changes: 12 additions & 0 deletions changes/feat-manifest-desktop-account-remove.md
Original file line number Diff line number Diff line change
@@ -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 `<noun> 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).
5 changes: 3 additions & 2 deletions docs/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<noun> sync`: `run` is `[{profile}] <path> --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 `<noun> sync`: `run` is `[{profile}] <path> --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 `<noun> 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.
Expand Down
66 changes: 64 additions & 2 deletions src/wcat/manifest.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -147,14 +147,14 @@ describe("buildManifest", () => {
])
})

it("runs a single <noun> sync but finds its last run only for a one-word sync, which a plain word can name", () => {
it("runs a single <noun> 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,
Expand All @@ -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"]
Expand All @@ -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<typeof manifest.desktop.sync>
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")
Expand Down
66 changes: 60 additions & 6 deletions src/wcat/manifest.ts
Original file line number Diff line number Diff line change
@@ -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"
Expand Down Expand Up @@ -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 `<noun> 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))

/**
Expand Down Expand Up @@ -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(),
Expand All @@ -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.
Expand Down Expand Up @@ -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"],
Expand All @@ -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
Expand Down Expand Up @@ -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,
},
}
Expand Down
Loading