listspace 0.3.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -1
- package/README.md +37 -7
- package/dist/listspace.mjs +313 -27
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,7 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
One version runs through the CLI, the skill and the Claude Code plugin, so each entry covers all three.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 0.5.0
|
|
6
|
+
|
|
7
|
+
- New command `listspace call <tool> ['<json>']`: runs any tool of the Listspace MCP server by name, with its arguments as one JSON object, for example `listspace call get_item --json '{"item_id": "..."}'`. It goes to the MCP server with the same token, so the tools, the agent access level checks and the results are the same as for an MCP client, and a new tool works without a CLI update. A tool that refuses (a level, a wrong argument) exits 1 with `error.kind` `tool`. A call with an `idempotency_key` is sent once more after a network error or a 502, 503 or 504; one without is sent once.
|
|
8
|
+
- New command `listspace tools`: the tools this token can use, one line each. `listspace tools <name>` shows one tool with its description and input schema.
|
|
9
|
+
- New short commands, each one MCP tool through the same path as `call`: `comment <item> <text>` (`add_comment`), `update <item> [--title] [--description]` (`update_item`), `list add <board> <title> [--kind]` (`create_list`) and `list rename <list> <title>` (`update_list`). They take `--inbox --reason` like the other writes, and the ones that make something send an `idempotency_key`.
|
|
10
|
+
- `listspace new-board` takes `--template <id or name>`: a board from any template in `list_templates`, not only "Project (for agents)".
|
|
11
|
+
- `LISTSPACE_MCP_URL` points `tools`, `call` and the commands built on them at another MCP server.
|
|
12
|
+
- The skill's CLI page lists the new commands and `call`, and `my_items` has a CLI command now (`listspace call my_items`).
|
|
13
|
+
- Safe retries. Every `POST` the CLI sends carries its own `Idempotency-Key`; after a network error or a 502, 503 or 504 it sends the request once more with the same key, so a lost answer (for example while Listspace restarts) never adds a second item. A 503 for maintenance is passed on as before.
|
|
14
|
+
- The skill and `reference/tools.md` tell agents to send `idempotency_key` with every MCP call that makes something, to retry with the same key after a network error or a 5xx, and to check before making it again when they sent none. Results with `replayed: true` are the first result, not a new change.
|
|
15
|
+
|
|
16
|
+
## 0.4.0
|
|
17
|
+
|
|
18
|
+
- The Claude Code plugin adds the board rules back to Claude's context (`hooks/board-hooks.mjs`): at the start of a session it names the project's board and says to start from it; after a compaction it says to look up the open work (`claimed_by_you`, `started_by_you`) and update it before going on; after `gh pr create`, `gh pr merge` or a deploy it says to move the matching item and comment. Only in a project with a `Listspace board:` line or a session that uses Listspace. Context only, it never blocks a command.
|
|
19
|
+
|
|
20
|
+
## 0.3.0
|
|
6
21
|
|
|
7
22
|
- The Claude Code plugin has a progress check (`hooks/progress-check.mjs`): when a turn in a session that uses Listspace changed files, committed, pushed, opened or merged a pull request or deployed, and made no Listspace write after that work, Claude is sent back once to move the item and add a short comment. At most once every 3 turns, never twice in a row. It keeps only the facts, no command or file name.
|
|
8
23
|
- The skill and `AGENTS.md.snippet` say that work tracked elsewhere, such as a pull request or a deploy, still moves the matching item with a short comment, and the skill reads the server's `reminder` and `claimed_by_you`. It also offers an optional line for the project's CLAUDE.md or AGENTS.md that asks every agent to keep the board up to date.
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# listspace
|
|
2
2
|
|
|
3
|
-
The command line for [Listspace](https://listspace.app), the project board your AI agents keep up to date. People and coding agents use it to read boards, add and move items, work through a board on their own, and undo their own changes. It talks to the Listspace REST API (`https://api.listspace.app/v1`).
|
|
3
|
+
The command line for [Listspace](https://listspace.app), the project board your AI agents keep up to date. People and coding agents use it to read boards, add and move items, work through a board on their own, and undo their own changes. It talks to the Listspace REST API (`https://api.listspace.app/v1`), and `call` runs any tool of the Listspace MCP server (`https://mcp.listspace.app`) with the same token.
|
|
4
4
|
|
|
5
5
|
Node 20 or later. No runtime dependencies.
|
|
6
6
|
|
|
@@ -20,7 +20,7 @@ npm install -g listspace
|
|
|
20
20
|
|
|
21
21
|
## Sign in
|
|
22
22
|
|
|
23
|
-
Create a personal token in Listspace under **Settings >
|
|
23
|
+
Create a personal token in Listspace under **Settings > Your AI > API tokens**, then save it:
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
26
|
npx listspace login --token ls_...
|
|
@@ -38,7 +38,7 @@ The token is saved as `credentials.json` (mode 600) in your OS config directory:
|
|
|
38
38
|
|
|
39
39
|
```text
|
|
40
40
|
Sign in
|
|
41
|
-
login [--token ls_...] Save a personal token (Listspace: Settings >
|
|
41
|
+
login [--token ls_...] Save a personal token (Listspace: Settings > Your AI > API tokens).
|
|
42
42
|
logout Forget the saved token.
|
|
43
43
|
whoami Plan, agent access, guidance and boards (alias: account).
|
|
44
44
|
|
|
@@ -50,16 +50,26 @@ Read
|
|
|
50
50
|
inbox <board> [--status pending|accepted|rejected|withdrawn|expired|failed|all]
|
|
51
51
|
|
|
52
52
|
Write (the board's agent access level decides what is made and what waits in the Inbox)
|
|
53
|
-
new-board <title> [--description <text>] [--space <space id>]
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
goes to the
|
|
53
|
+
new-board <title> [--template <id or name>] [--description <text>] [--space <space id>]
|
|
54
|
+
Default template "Project (for agents)". With more
|
|
55
|
+
than one space (see whoami), ask the user which one
|
|
56
|
+
and pass --space; without it the board goes to the
|
|
57
|
+
default space.
|
|
57
58
|
add <board> <list> <title> [--description <markdown>]
|
|
59
|
+
update <item> [--title <text>] [--description <markdown>]
|
|
60
|
+
comment <item> <text> Add a comment (markdown) to an item.
|
|
58
61
|
move <item> <list>
|
|
59
62
|
done <item> Move to the board's done list.
|
|
63
|
+
list add <board> <title> [--kind info|capture|backlog|todo|doing|done]
|
|
64
|
+
list rename <list> <title> Here <list> is a list id.
|
|
60
65
|
undo <request_id> Take back one of your own calls.
|
|
61
66
|
Writes take --inbox --reason "<why>" to suggest instead of change.
|
|
62
67
|
|
|
68
|
+
Every MCP tool (the same tools, levels and results as the MCP server)
|
|
69
|
+
tools The tools this token can use, one line each.
|
|
70
|
+
tools <name> One tool: what it does and its arguments.
|
|
71
|
+
call <tool> ['<json>'] Run a tool with its arguments as one JSON object.
|
|
72
|
+
|
|
63
73
|
Files from this computer (needs level 4, Act)
|
|
64
74
|
attach <item> <file> [<file>...] At most 8 MB each.
|
|
65
75
|
|
|
@@ -78,6 +88,25 @@ npx listspace session "Website"
|
|
|
78
88
|
npx listspace add "Website" ideas "Try dark mode" --description "Seen in **settings**"
|
|
79
89
|
```
|
|
80
90
|
|
|
91
|
+
## Every MCP tool: `call`
|
|
92
|
+
|
|
93
|
+
The short commands above cover what people type often. Everything else the Listspace MCP server can do works too, by the tool's name, with its arguments as one JSON object:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npx listspace tools # every tool this token can use, one line each
|
|
97
|
+
npx listspace tools record_decision # what it does and its arguments (JSON Schema)
|
|
98
|
+
npx listspace call my_items
|
|
99
|
+
npx listspace call get_item --json '{"item_id": "2b6f0c1e-..."}'
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`call` sends the call to the MCP server with your token, so it has the same tools, the same agent access levels and the same results as an MCP client. A read-only token sees only the read tools. A new tool on the server works in the CLI right away, with no update.
|
|
103
|
+
|
|
104
|
+
With `--json`, the arguments come right after it, and the output is the tool's result as JSON. A refusal, for example a board at level 1 (Read only), exits 1 with `error.kind` `tool` and the server's message.
|
|
105
|
+
|
|
106
|
+
Give every call that makes something an `idempotency_key`, a new one per call, such as a UUID. The CLI then sends it once more after a network error or a 502, 503 or 504, and the server makes it only once. A call without a key is sent once. The short commands add a key themselves where the tool takes one.
|
|
107
|
+
|
|
108
|
+
PowerShell treats quotes in JSON differently. On Windows, run these commands from Git Bash, where the quotes work as shown.
|
|
109
|
+
|
|
81
110
|
## Attach files
|
|
82
111
|
|
|
83
112
|
`attach` uploads files from your computer to an item, one after another:
|
|
@@ -104,6 +133,7 @@ Exit codes: 0 ok, 1 failed, 2 usage error, 3 sign-in needed, 4 rate limited (wai
|
|
|
104
133
|
|---|---|
|
|
105
134
|
| `LISTSPACE_TOKEN` | A token for this run. It wins over the saved one. |
|
|
106
135
|
| `LISTSPACE_API_URL` | Another API address. Default `https://api.listspace.app/v1`. |
|
|
136
|
+
| `LISTSPACE_MCP_URL` | Another MCP server address, for `tools`, `call` and the commands built on them. Default `https://mcp.listspace.app`. |
|
|
107
137
|
| `LISTSPACE_CONFIG_DIR` | Where `credentials.json` is kept. |
|
|
108
138
|
|
|
109
139
|
## What agents may do
|
package/dist/listspace.mjs
CHANGED
|
@@ -32,6 +32,10 @@ var boolean = (value, path2) => {
|
|
|
32
32
|
if (typeof value !== "boolean") throw new DecodeError(path2, "true or false");
|
|
33
33
|
return value;
|
|
34
34
|
};
|
|
35
|
+
var record = (value, path2) => {
|
|
36
|
+
if (!isRecord(value)) throw new DecodeError(path2, "an object");
|
|
37
|
+
return value;
|
|
38
|
+
};
|
|
35
39
|
function literal(...allowed) {
|
|
36
40
|
return (value, path2) => {
|
|
37
41
|
const match = allowed.find((candidate) => candidate === value);
|
|
@@ -227,10 +231,12 @@ var attached = object({
|
|
|
227
231
|
});
|
|
228
232
|
|
|
229
233
|
// src/version.ts
|
|
230
|
-
var VERSION = "0.
|
|
234
|
+
var VERSION = "0.5.0";
|
|
231
235
|
|
|
232
236
|
// src/api.ts
|
|
233
237
|
var DEFAULT_API_URL = "https://api.listspace.app/v1";
|
|
238
|
+
var DEFAULT_MCP_URL = "https://mcp.listspace.app";
|
|
239
|
+
var MCP_PROTOCOL_VERSION = "2025-06-18";
|
|
234
240
|
var TOKEN_PATTERN = /^ls_[A-Za-z0-9_-]{43}$/;
|
|
235
241
|
function parseToken(raw) {
|
|
236
242
|
const trimmed = raw.trim();
|
|
@@ -247,7 +253,9 @@ var CliFailure = class extends Error {
|
|
|
247
253
|
var fail = (error) => {
|
|
248
254
|
throw new CliFailure(error);
|
|
249
255
|
};
|
|
250
|
-
var LOGIN_HINT = "Run `listspace login` with a personal token (Listspace: Settings >
|
|
256
|
+
var LOGIN_HINT = "Run `listspace login` with a personal token (Listspace: Settings > Your AI > API tokens), or set LISTSPACE_TOKEN.";
|
|
257
|
+
var RETRY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
|
|
258
|
+
var RETRY_DELAY_MS = 1500;
|
|
251
259
|
var ApiClient = class {
|
|
252
260
|
constructor(options) {
|
|
253
261
|
this.options = options;
|
|
@@ -264,23 +272,75 @@ var ApiClient = class {
|
|
|
264
272
|
const json = await this.send(method, path2, init);
|
|
265
273
|
return { value: decodeOrFail(decoder, json, "body"), raw: json };
|
|
266
274
|
}
|
|
275
|
+
/** A new idempotency key: a random UUID, or the tests' own. */
|
|
276
|
+
newKey() {
|
|
277
|
+
return (this.options.newKey ?? (() => crypto.randomUUID()))();
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* Runs one MCP tool by name, as the MCP server runs it for any client: the
|
|
281
|
+
* same token, agent access level checks and result. `retry`: the call is
|
|
282
|
+
* safe to send once more after a lost answer (a read, or a write with an
|
|
283
|
+
* idempotency_key).
|
|
284
|
+
*/
|
|
285
|
+
async callTool(name, args, retry) {
|
|
286
|
+
const result = decodeOrFail(toolResult, await this.rpc("tools/call", { name, arguments: args }, retry), "result");
|
|
287
|
+
const text = result.content.flatMap((part) => part.text === null ? [] : [part.text]).join("\n");
|
|
288
|
+
if (result.isError) {
|
|
289
|
+
return fail({ kind: "tool", tool: name, message: text === "" ? `${name} failed.` : text, details: result.structuredContent });
|
|
290
|
+
}
|
|
291
|
+
return { value: result.structuredContent ?? parseText(text) };
|
|
292
|
+
}
|
|
293
|
+
/** The tools this token can use, as the MCP server lists them (a read-only token sees no write tools). */
|
|
294
|
+
async listTools() {
|
|
295
|
+
return decodeOrFail(toolList, await this.rpc("tools/list", {}, true), "result").tools;
|
|
296
|
+
}
|
|
297
|
+
/** One JSON-RPC request to the MCP server: its result, or a CliError for its error. */
|
|
298
|
+
async rpc(method, params, retry) {
|
|
299
|
+
const url = new URL(this.options.mcpUrl ?? DEFAULT_MCP_URL);
|
|
300
|
+
const request = {
|
|
301
|
+
method: "POST",
|
|
302
|
+
headers: {
|
|
303
|
+
...this.identity(),
|
|
304
|
+
Accept: "application/json, text/event-stream",
|
|
305
|
+
"Content-Type": "application/json",
|
|
306
|
+
"MCP-Protocol-Version": MCP_PROTOCOL_VERSION
|
|
307
|
+
},
|
|
308
|
+
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
|
|
309
|
+
};
|
|
310
|
+
const { response, json } = await this.exchange(url, request, retry);
|
|
311
|
+
const rpcError = isRecord(json) && isRecord(json.error) && typeof json.error.message === "string" && typeof json.error.code === "number" ? json.error : null;
|
|
312
|
+
if (rpcError !== null) {
|
|
313
|
+
const message = String(rpcError.message);
|
|
314
|
+
if (message.startsWith("Unknown tool")) return fail({ kind: "usage", message: `${message}. Run \`listspace tools\` to see the tools.` });
|
|
315
|
+
if (rpcError.code === INVALID_PARAMS) return fail({ kind: "usage", message });
|
|
316
|
+
return fail({ kind: "unexpected", message: `The Listspace MCP server answered: ${message}` });
|
|
317
|
+
}
|
|
318
|
+
if (!response.ok) return fail(errorFor(response, json));
|
|
319
|
+
if (!isRecord(json) || !("result" in json)) return fail({ kind: "unexpected", message: "Unexpected response from the Listspace MCP server: no result." });
|
|
320
|
+
return json.result;
|
|
321
|
+
}
|
|
322
|
+
/** The headers that say who is asking. The token goes only here, never into a message. */
|
|
323
|
+
identity() {
|
|
324
|
+
return { Authorization: `Bearer ${this.options.token}`, "User-Agent": `listspace-cli/${VERSION}` };
|
|
325
|
+
}
|
|
267
326
|
async send(method, path2, init) {
|
|
268
327
|
const url = new URL(this.options.baseUrl.replace(/\/+$/, "") + path2);
|
|
269
328
|
for (const [key, value] of Object.entries(init.query ?? {})) {
|
|
270
329
|
if (value !== void 0) url.searchParams.set(key, String(value));
|
|
271
330
|
}
|
|
272
|
-
const headers = {
|
|
273
|
-
Authorization: `Bearer ${this.options.token}`,
|
|
274
|
-
Accept: "application/json",
|
|
275
|
-
"User-Agent": `listspace-cli/${VERSION}`
|
|
276
|
-
};
|
|
331
|
+
const headers = { ...this.identity(), Accept: "application/json" };
|
|
277
332
|
if (init.body !== void 0) headers["Content-Type"] = "application/json";
|
|
333
|
+
if (method === "POST") headers["Idempotency-Key"] = this.newKey();
|
|
334
|
+
const request = init.body === void 0 ? { method, headers } : { method, headers, body: JSON.stringify(init.body) };
|
|
335
|
+
const { response, json } = await this.exchange(url, request, method === "POST");
|
|
336
|
+
if (response.ok) return json;
|
|
337
|
+
return fail(errorFor(response, json));
|
|
338
|
+
}
|
|
339
|
+
/** Sends one request (once more when `retry` allows) and parses its JSON; the caller reads the status. */
|
|
340
|
+
async exchange(url, request, retry) {
|
|
278
341
|
let response;
|
|
279
342
|
try {
|
|
280
|
-
response = await this.
|
|
281
|
-
url.toString(),
|
|
282
|
-
init.body === void 0 ? { method, headers } : { method, headers, body: JSON.stringify(init.body) }
|
|
283
|
-
);
|
|
343
|
+
response = await this.attempt(url, request, retry);
|
|
284
344
|
} catch (cause) {
|
|
285
345
|
const reason = cause instanceof Error ? cause.message : String(cause);
|
|
286
346
|
return fail({ kind: "network", message: `Could not reach Listspace at ${url.origin}: ${reason}` });
|
|
@@ -294,10 +354,54 @@ var ApiClient = class {
|
|
|
294
354
|
if (response.ok) return fail({ kind: "unexpected", message: `Listspace answered ${response.status} with something that is not JSON.` });
|
|
295
355
|
}
|
|
296
356
|
}
|
|
297
|
-
|
|
298
|
-
|
|
357
|
+
return { response, json };
|
|
358
|
+
}
|
|
359
|
+
/** One request; a write is sent once more, with the same key, after a network error or a 502, 503 or 504. */
|
|
360
|
+
async attempt(url, request, retry) {
|
|
361
|
+
let first;
|
|
362
|
+
try {
|
|
363
|
+
first = await this.options.fetch(url.toString(), request);
|
|
364
|
+
} catch (cause) {
|
|
365
|
+
if (!retry) throw cause;
|
|
366
|
+
await this.wait();
|
|
367
|
+
return await this.options.fetch(url.toString(), request);
|
|
368
|
+
}
|
|
369
|
+
if (!retry || !RETRY_STATUSES.has(first.status) || await isMaintenance(first)) return first;
|
|
370
|
+
await this.wait();
|
|
371
|
+
return await this.options.fetch(url.toString(), request);
|
|
372
|
+
}
|
|
373
|
+
async wait() {
|
|
374
|
+
await (this.options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(RETRY_DELAY_MS);
|
|
299
375
|
}
|
|
300
376
|
};
|
|
377
|
+
var INVALID_PARAMS = -32602;
|
|
378
|
+
var toolResult = object({
|
|
379
|
+
content: array(object({ type: string, text: withDefault(nullable(string), null) })),
|
|
380
|
+
structuredContent: withDefault(nullable(record), null),
|
|
381
|
+
isError: withDefault(boolean, false)
|
|
382
|
+
});
|
|
383
|
+
var toolInfo = object({
|
|
384
|
+
name: string,
|
|
385
|
+
title: withDefault(nullable(string), null),
|
|
386
|
+
description: withDefault(string, ""),
|
|
387
|
+
inputSchema: record
|
|
388
|
+
});
|
|
389
|
+
var toolList = object({ tools: array(toolInfo) });
|
|
390
|
+
function parseText(text) {
|
|
391
|
+
try {
|
|
392
|
+
return JSON.parse(text);
|
|
393
|
+
} catch {
|
|
394
|
+
return text;
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
async function isMaintenance(response) {
|
|
398
|
+
if (response.status !== 503) return false;
|
|
399
|
+
try {
|
|
400
|
+
return errorBody(JSON.parse(await response.clone().text()), "body").error.code === "maintenance";
|
|
401
|
+
} catch {
|
|
402
|
+
return false;
|
|
403
|
+
}
|
|
404
|
+
}
|
|
301
405
|
function decodeOrFail(decoder, value, path2) {
|
|
302
406
|
try {
|
|
303
407
|
return decoder(value, path2);
|
|
@@ -323,7 +427,7 @@ function errorFor(response, json) {
|
|
|
323
427
|
return { kind: "rate_limited", message: `${message} ${wait} before trying again.`, retryAfterSeconds: seconds };
|
|
324
428
|
}
|
|
325
429
|
if (response.status === 403 && code2 === "insufficient_scope") {
|
|
326
|
-
return { kind: "api", status: 403, code: code2, message: `${message} This token is read only; create a read and write token in Settings >
|
|
430
|
+
return { kind: "api", status: 403, code: code2, message: `${message} This token is read only; create a read and write token in Settings > Your AI > API tokens.` };
|
|
327
431
|
}
|
|
328
432
|
return { kind: "api", status: response.status, code: code2, message };
|
|
329
433
|
}
|
|
@@ -645,7 +749,8 @@ async function newBoardCommand(client, input) {
|
|
|
645
749
|
const body = {
|
|
646
750
|
title: input.title,
|
|
647
751
|
...input.description === null ? {} : { description: input.description },
|
|
648
|
-
...input.space === null ? {} : { space_id: input.space }
|
|
752
|
+
...input.space === null ? {} : { space_id: input.space },
|
|
753
|
+
...input.templateId === null ? {} : { template_id: input.templateId }
|
|
649
754
|
};
|
|
650
755
|
const answer = await client.data("POST", "/boards", createdBoard, { body });
|
|
651
756
|
return { raw: answer.raw, text: formatCreatedBoard(answer.value) };
|
|
@@ -773,6 +878,118 @@ async function attachCommand(client, input) {
|
|
|
773
878
|
return { raw: { data: raw }, text: formatAttached(results) };
|
|
774
879
|
}
|
|
775
880
|
|
|
881
|
+
// src/tools.ts
|
|
882
|
+
var UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
883
|
+
function parseToolArgs(raw) {
|
|
884
|
+
if (raw === void 0) return {};
|
|
885
|
+
let value;
|
|
886
|
+
try {
|
|
887
|
+
value = JSON.parse(raw);
|
|
888
|
+
} catch {
|
|
889
|
+
return fail({ kind: "usage", message: `The arguments are not valid JSON. Pass one object, for example '{"board_id": "..."}', in single quotes.` });
|
|
890
|
+
}
|
|
891
|
+
if (!isRecord(value)) return fail({ kind: "usage", message: `The arguments must be one JSON object, for example '{"board_id": "..."}'.` });
|
|
892
|
+
return value;
|
|
893
|
+
}
|
|
894
|
+
var asText = (value) => typeof value === "string" ? value : JSON.stringify(value, null, 2);
|
|
895
|
+
async function callCommand(client, input) {
|
|
896
|
+
const answer = await client.callTool(input.tool, input.args, typeof input.args.idempotency_key === "string");
|
|
897
|
+
return { raw: answer.value, text: asText(answer.value) };
|
|
898
|
+
}
|
|
899
|
+
var SUMMARY_MAX = 100;
|
|
900
|
+
function firstSentence(description) {
|
|
901
|
+
const end = description.search(/\.(\s|$)/);
|
|
902
|
+
const sentence = end === -1 ? description : description.slice(0, end + 1);
|
|
903
|
+
if (sentence.length <= SUMMARY_MAX) return sentence;
|
|
904
|
+
const cut = sentence.slice(0, SUMMARY_MAX);
|
|
905
|
+
const space = cut.lastIndexOf(" ");
|
|
906
|
+
return `${(space > 0 ? cut.slice(0, space) : cut).replace(/[,;:(]$/, "")}...`;
|
|
907
|
+
}
|
|
908
|
+
async function toolsCommand(client, input) {
|
|
909
|
+
const tools = await client.listTools();
|
|
910
|
+
if (input.name === null) {
|
|
911
|
+
const width = Math.max(0, ...tools.map((tool2) => tool2.name.length));
|
|
912
|
+
const lines = tools.map((tool2) => `${tool2.name.padEnd(width)} ${firstSentence(tool2.description)}`);
|
|
913
|
+
lines.push("", `${tools.length} tools. \`listspace tools <name>\` shows one with its arguments; \`listspace call <name> '<json>'\` runs it.`);
|
|
914
|
+
return { raw: { tools: tools.map(({ name, title, description }) => ({ name, title, description })) }, text: lines.join("\n") };
|
|
915
|
+
}
|
|
916
|
+
const tool = tools.find((candidate) => candidate.name === input.name);
|
|
917
|
+
if (tool === void 0) return fail({ kind: "usage", message: `No tool called "${input.name}" for this token. Run \`listspace tools\` to see them.` });
|
|
918
|
+
return { raw: tool, text: formatTool(tool) };
|
|
919
|
+
}
|
|
920
|
+
function formatTool(tool) {
|
|
921
|
+
return [
|
|
922
|
+
tool.title === null ? tool.name : `${tool.name}: ${tool.title}`,
|
|
923
|
+
"",
|
|
924
|
+
tool.description,
|
|
925
|
+
"",
|
|
926
|
+
"Arguments (JSON Schema):",
|
|
927
|
+
JSON.stringify(tool.inputSchema, null, 2)
|
|
928
|
+
].join("\n");
|
|
929
|
+
}
|
|
930
|
+
async function write(client, tool, args, done, keyed) {
|
|
931
|
+
const sent = keyed ? { ...args, idempotency_key: client.newKey() } : args;
|
|
932
|
+
const answer = await client.callTool(tool, sent, keyed);
|
|
933
|
+
const outcome = outcomeOf(answer.value);
|
|
934
|
+
return { raw: answer.value, text: outcome === null ? asText(answer.value) : formatWrite(outcome, done) };
|
|
935
|
+
}
|
|
936
|
+
function outcomeOf(value) {
|
|
937
|
+
try {
|
|
938
|
+
return writeOutcome(value, "result");
|
|
939
|
+
} catch (error) {
|
|
940
|
+
if (error instanceof DecodeError) return null;
|
|
941
|
+
throw error;
|
|
942
|
+
}
|
|
943
|
+
}
|
|
944
|
+
function commentCommand(client, input) {
|
|
945
|
+
return write(client, "add_comment", { item_id: input.item, text: input.text, ...inboxFields(input.choice) }, "Commented", true);
|
|
946
|
+
}
|
|
947
|
+
function updateCommand(client, input) {
|
|
948
|
+
if (input.title === null && input.description === null) {
|
|
949
|
+
return fail({ kind: "usage", message: "`update` needs --title, --description or both." });
|
|
950
|
+
}
|
|
951
|
+
const args = {
|
|
952
|
+
item_id: input.item,
|
|
953
|
+
...input.title === null ? {} : { title: input.title },
|
|
954
|
+
...input.description === null ? {} : { description: input.description },
|
|
955
|
+
...inboxFields(input.choice)
|
|
956
|
+
};
|
|
957
|
+
return write(client, "update_item", args, "Updated the item", false);
|
|
958
|
+
}
|
|
959
|
+
async function listAddCommand(client, input) {
|
|
960
|
+
const boardId = await resolveBoardId(client, input.board);
|
|
961
|
+
const args = { board_id: boardId, title: input.title, ...input.kind === null ? {} : { kind: input.kind }, ...inboxFields(input.choice) };
|
|
962
|
+
return write(client, "create_list", args, `Added the list "${input.title}"`, true);
|
|
963
|
+
}
|
|
964
|
+
function listRenameCommand(client, input) {
|
|
965
|
+
return write(client, "update_list", { list_id: input.list, title: input.title, ...inboxFields(input.choice) }, `Renamed the list to "${input.title}"`, false);
|
|
966
|
+
}
|
|
967
|
+
var templates = (value, path2) => object({ templates: array(object({ id: string, name: string })) })(value, path2).templates;
|
|
968
|
+
function decodeOrFail2(decoder, value) {
|
|
969
|
+
try {
|
|
970
|
+
return decoder(value, "result");
|
|
971
|
+
} catch (error) {
|
|
972
|
+
if (error instanceof DecodeError) return fail({ kind: "unexpected", message: error.message });
|
|
973
|
+
throw error;
|
|
974
|
+
}
|
|
975
|
+
}
|
|
976
|
+
async function resolveTemplateId(client, ref) {
|
|
977
|
+
if (UUID2.test(ref)) return ref;
|
|
978
|
+
const answer = await client.callTool("list_templates", {}, true);
|
|
979
|
+
const all = decodeOrFail2(templates, answer.value);
|
|
980
|
+
const wanted = ref.trim().toLowerCase();
|
|
981
|
+
const exact = all.filter((template) => template.name.toLowerCase() === wanted);
|
|
982
|
+
const matches = exact.length > 0 ? exact : all.filter((template) => template.name.toLowerCase().startsWith(wanted));
|
|
983
|
+
const [first, ...others] = matches;
|
|
984
|
+
if (first === void 0) {
|
|
985
|
+
return fail({ kind: "usage", message: `No template called "${ref}". Run \`listspace call list_templates\` to see them.` });
|
|
986
|
+
}
|
|
987
|
+
if (others.length > 0) {
|
|
988
|
+
return fail({ kind: "usage", message: `"${ref}" matches ${matches.length} templates: ${matches.map((t) => `${t.name} (${t.id})`).join(", ")}. Use the id.` });
|
|
989
|
+
}
|
|
990
|
+
return first.id;
|
|
991
|
+
}
|
|
992
|
+
|
|
776
993
|
// src/config.ts
|
|
777
994
|
import { chmod, mkdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
|
|
778
995
|
import { homedir } from "node:os";
|
|
@@ -834,7 +1051,7 @@ var HELP = `listspace ${VERSION}: Listspace from the command line, for people an
|
|
|
834
1051
|
Usage: listspace <command> [arguments] [--json]
|
|
835
1052
|
|
|
836
1053
|
Sign in
|
|
837
|
-
login [--token ls_...] Save a personal token (Listspace: Settings >
|
|
1054
|
+
login [--token ls_...] Save a personal token (Listspace: Settings > Your AI > API tokens).
|
|
838
1055
|
Without --token it reads the token from stdin.
|
|
839
1056
|
logout Forget the saved token.
|
|
840
1057
|
whoami Plan, agent access, guidance and boards (alias: account).
|
|
@@ -847,17 +1064,29 @@ Read
|
|
|
847
1064
|
inbox <board> [--status pending|accepted|rejected|withdrawn|expired|failed|all]
|
|
848
1065
|
|
|
849
1066
|
Write (the board's agent access level decides what is made and what waits in the Inbox)
|
|
850
|
-
new-board <title> [--description <text>] [--space <space id>]
|
|
851
|
-
A board from "Project (for
|
|
852
|
-
one space (see whoami),
|
|
853
|
-
|
|
854
|
-
default space.
|
|
1067
|
+
new-board <title> [--template <id or name>] [--description <text>] [--space <space id>]
|
|
1068
|
+
A board from the template (default "Project (for
|
|
1069
|
+
agents)"). With more than one space (see whoami),
|
|
1070
|
+
ask the user which one and pass --space; without
|
|
1071
|
+
it the board goes to the default space.
|
|
855
1072
|
add <board> <list> <title> [--description <markdown>]
|
|
1073
|
+
update <item> [--title <text>] [--description <markdown>]
|
|
1074
|
+
comment <item> <text> Add a comment (markdown) to an item.
|
|
856
1075
|
move <item> <list>
|
|
857
1076
|
done <item> Move to the board's done list.
|
|
1077
|
+
list add <board> <title> [--kind info|capture|backlog|todo|doing|done]
|
|
1078
|
+
list rename <list> <title> Here <list> is a list id.
|
|
858
1079
|
undo <request_id> Take back one of your own calls.
|
|
859
1080
|
Writes take --inbox --reason "<why>" to suggest instead of change.
|
|
860
1081
|
|
|
1082
|
+
Every MCP tool (the same tools, levels and results as the MCP server)
|
|
1083
|
+
tools The tools this token can use, one line each.
|
|
1084
|
+
tools <name> One tool: what it does and its arguments.
|
|
1085
|
+
call <tool> ['<json>'] Run a tool with its arguments as one JSON object,
|
|
1086
|
+
for example: call get_item --json '{"item_id": "..."}'
|
|
1087
|
+
Give a call that makes something an
|
|
1088
|
+
idempotency_key, so a retry never makes it twice.
|
|
1089
|
+
|
|
861
1090
|
Files from this computer (needs level 4, Act; a file cannot wait in the Inbox)
|
|
862
1091
|
attach <item> <file> [<file>...]
|
|
863
1092
|
Upload files to an item, at most 8 MB each:
|
|
@@ -880,12 +1109,14 @@ Work on your own (needs level 4, Act; other agents leave a claimed item alone)
|
|
|
880
1109
|
info, capture, backlog), <item> an item id.
|
|
881
1110
|
|
|
882
1111
|
Options
|
|
883
|
-
--json Print the
|
|
1112
|
+
--json Print the server's JSON (for agents and scripts).
|
|
884
1113
|
--help This help. --version The version.
|
|
885
1114
|
|
|
886
1115
|
Environment
|
|
887
1116
|
LISTSPACE_TOKEN A token for this run (wins over the saved one).
|
|
888
1117
|
LISTSPACE_API_URL Default ${DEFAULT_API_URL}
|
|
1118
|
+
LISTSPACE_MCP_URL Default ${DEFAULT_MCP_URL} (for tools, call and the
|
|
1119
|
+
commands built on them).
|
|
889
1120
|
LISTSPACE_CONFIG_DIR Where credentials.json is kept.
|
|
890
1121
|
|
|
891
1122
|
Exit codes: 0 ok, 1 failed, 2 usage, 3 sign in needed, 4 rate limited (wait and retry).`;
|
|
@@ -895,7 +1126,8 @@ var EXIT = {
|
|
|
895
1126
|
rate_limited: 4,
|
|
896
1127
|
api: 1,
|
|
897
1128
|
network: 1,
|
|
898
|
-
unexpected: 1
|
|
1129
|
+
unexpected: 1,
|
|
1130
|
+
tool: 1
|
|
899
1131
|
};
|
|
900
1132
|
var OPTIONS = {
|
|
901
1133
|
json: { type: "boolean" },
|
|
@@ -903,7 +1135,10 @@ var OPTIONS = {
|
|
|
903
1135
|
version: { type: "boolean", short: "v" },
|
|
904
1136
|
token: { type: "string" },
|
|
905
1137
|
description: { type: "string" },
|
|
1138
|
+
title: { type: "string" },
|
|
906
1139
|
space: { type: "string" },
|
|
1140
|
+
template: { type: "string" },
|
|
1141
|
+
kind: { type: "string" },
|
|
907
1142
|
inbox: { type: "boolean" },
|
|
908
1143
|
reason: { type: "string" },
|
|
909
1144
|
status: { type: "string" },
|
|
@@ -954,7 +1189,7 @@ async function clientFor(io, dir) {
|
|
|
954
1189
|
switch (source.kind) {
|
|
955
1190
|
case "env":
|
|
956
1191
|
case "file":
|
|
957
|
-
return new ApiClient({ baseUrl: apiUrl(io.env), token: source.token, fetch: io.fetch });
|
|
1192
|
+
return new ApiClient({ baseUrl: apiUrl(io.env), mcpUrl: mcpUrl(io.env), token: source.token, fetch: io.fetch });
|
|
958
1193
|
case "none":
|
|
959
1194
|
return fail({ kind: "auth", message: `Not signed in. ${LOGIN_HINT}` });
|
|
960
1195
|
case "invalid":
|
|
@@ -969,9 +1204,20 @@ var apiUrl = (env) => {
|
|
|
969
1204
|
const url = env.LISTSPACE_API_URL;
|
|
970
1205
|
return url !== void 0 && url !== "" ? url : DEFAULT_API_URL;
|
|
971
1206
|
};
|
|
1207
|
+
var mcpUrl = (env) => {
|
|
1208
|
+
const url = env.LISTSPACE_MCP_URL;
|
|
1209
|
+
return url !== void 0 && url !== "" ? url : DEFAULT_MCP_URL;
|
|
1210
|
+
};
|
|
1211
|
+
function listKindFrom(flags) {
|
|
1212
|
+
if (flags.kind === void 0) return null;
|
|
1213
|
+
const wanted = flags.kind.trim().toLowerCase();
|
|
1214
|
+
const kind = LIST_KINDS.find((candidate) => candidate === wanted);
|
|
1215
|
+
if (kind === void 0) return usage(`--kind is one of ${LIST_KINDS.join(", ")}.`);
|
|
1216
|
+
return kind;
|
|
1217
|
+
}
|
|
972
1218
|
async function loginMethod(flags, io) {
|
|
973
1219
|
if (flags.token !== void 0) return { kind: "token", raw: flags.token };
|
|
974
|
-
const typed = await io.readSecret("Paste a personal token from Listspace (Settings >
|
|
1220
|
+
const typed = await io.readSecret("Paste a personal token from Listspace (Settings > Your AI > API tokens): ");
|
|
975
1221
|
if (typed === null || typed.trim() === "") return { kind: "pairing" };
|
|
976
1222
|
return { kind: "token", raw: typed };
|
|
977
1223
|
}
|
|
@@ -997,7 +1243,7 @@ async function dispatch(command, args, flags, io, dir) {
|
|
|
997
1243
|
case "logout": {
|
|
998
1244
|
positionals(command, args, []);
|
|
999
1245
|
const removed = await removeToken(dir);
|
|
1000
|
-
return { raw: { signed_out: removed }, text: removed ? "Signed out: the saved token is gone (revoke it in Settings >
|
|
1246
|
+
return { raw: { signed_out: removed }, text: removed ? "Signed out: the saved token is gone (revoke it in Settings > Your AI > API tokens if it leaked)." : "No saved token." };
|
|
1001
1247
|
}
|
|
1002
1248
|
case "whoami":
|
|
1003
1249
|
case "account":
|
|
@@ -1016,7 +1262,45 @@ async function dispatch(command, args, flags, io, dir) {
|
|
|
1016
1262
|
}
|
|
1017
1263
|
case "new-board": {
|
|
1018
1264
|
const [title] = positionals(command, args, ["title"]);
|
|
1019
|
-
|
|
1265
|
+
const client = await clientFor(io, dir);
|
|
1266
|
+
const templateId = flags.template === void 0 ? null : await resolveTemplateId(client, flags.template);
|
|
1267
|
+
return newBoardCommand(client, { title, description: flags.description ?? null, space: flags.space ?? null, templateId });
|
|
1268
|
+
}
|
|
1269
|
+
case "call": {
|
|
1270
|
+
const [tool, raw, ...extra] = args;
|
|
1271
|
+
if (tool === void 0 || extra.length > 0) return usage("`call` takes <tool> and at most one JSON object of arguments (in single quotes).");
|
|
1272
|
+
const toolArgs = parseToolArgs(raw);
|
|
1273
|
+
return callCommand(await clientFor(io, dir), { tool, args: toolArgs });
|
|
1274
|
+
}
|
|
1275
|
+
case "tools": {
|
|
1276
|
+
if (args.length > 1) return usage("`tools` takes no arguments, or one tool name.");
|
|
1277
|
+
return toolsCommand(await clientFor(io, dir), { name: args[0] ?? null });
|
|
1278
|
+
}
|
|
1279
|
+
case "comment": {
|
|
1280
|
+
const [item2, text] = positionals(command, args, ["item", "text"]);
|
|
1281
|
+
const choice = choiceFrom(flags);
|
|
1282
|
+
return commentCommand(await clientFor(io, dir), { item: item2, text, choice });
|
|
1283
|
+
}
|
|
1284
|
+
case "update": {
|
|
1285
|
+
const [item2] = positionals(command, args, ["item"]);
|
|
1286
|
+
const choice = choiceFrom(flags);
|
|
1287
|
+
return updateCommand(await clientFor(io, dir), { item: item2, title: flags.title ?? null, description: flags.description ?? null, choice });
|
|
1288
|
+
}
|
|
1289
|
+
case "list": {
|
|
1290
|
+
const [sub, ...rest] = args;
|
|
1291
|
+
switch (sub) {
|
|
1292
|
+
case "add": {
|
|
1293
|
+
const [board, title] = positionals("list add", rest, ["board", "title"]);
|
|
1294
|
+
const input = { board, title, kind: listKindFrom(flags), choice: choiceFrom(flags) };
|
|
1295
|
+
return listAddCommand(await clientFor(io, dir), input);
|
|
1296
|
+
}
|
|
1297
|
+
case "rename": {
|
|
1298
|
+
const [list, title] = positionals("list rename", rest, ["list", "title"]);
|
|
1299
|
+
return listRenameCommand(await clientFor(io, dir), { list, title, choice: choiceFrom(flags) });
|
|
1300
|
+
}
|
|
1301
|
+
default:
|
|
1302
|
+
return usage("`list` takes `add <board> <title>` or `rename <list> <title>`.");
|
|
1303
|
+
}
|
|
1020
1304
|
}
|
|
1021
1305
|
case "add": {
|
|
1022
1306
|
const [board, list, title] = positionals(command, args, ["board", "list", "title"]);
|
|
@@ -1110,6 +1394,8 @@ function errorJson(error) {
|
|
|
1110
1394
|
return { kind: error.kind, status: error.status, code: error.code, message: error.message };
|
|
1111
1395
|
case "rate_limited":
|
|
1112
1396
|
return { kind: error.kind, message: error.message, retry_after_seconds: error.retryAfterSeconds };
|
|
1397
|
+
case "tool":
|
|
1398
|
+
return { kind: error.kind, tool: error.tool, message: error.message, ...error.details === null ? {} : { details: error.details } };
|
|
1113
1399
|
case "usage":
|
|
1114
1400
|
case "auth":
|
|
1115
1401
|
case "network":
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "listspace",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Listspace from the command line: the agentic project memory, for people and coding agents.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"listspace",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"scripts": {
|
|
42
42
|
"build": "esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/listspace.mjs --banner:js=\"#!/usr/bin/env node\"",
|
|
43
43
|
"typecheck": "tsc --noEmit",
|
|
44
|
-
"test": "tsc -p tsconfig.test.json && node --test build/test/api.test.js build/test/cli.test.js build/test/config.test.js build/test/commands.test.js build/test/attach.test.js",
|
|
44
|
+
"test": "tsc -p tsconfig.test.json && node --test build/test/api.test.js build/test/cli.test.js build/test/config.test.js build/test/commands.test.js build/test/attach.test.js build/test/tools.test.js",
|
|
45
45
|
"prepublishOnly": "npm run typecheck && npm test && npm run build"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|