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
8 changes: 7 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -411,7 +411,7 @@ come from `package.json`.
| `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.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
Expand Down
16 changes: 16 additions & 0 deletions src/wcat/manifest.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"/)
Expand Down
37 changes: 36 additions & 1 deletion src/wcat/manifest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<typeof signInSchema>
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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")
? {
Expand Down
Loading