listspace 0.4.0 → 0.6.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 CHANGED
@@ -2,6 +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
+ ## 0.6.0
6
+
7
+ - `listspace attach` takes files up to the plan's size of one file (Free 25 MB, Pro 2 GB, a team's boards 5 GB), at most 4 GB from the CLI. Up to 8 MB a file goes in the request as before; a larger one goes straight to Listspace's file storage: the CLI asks for an upload link with the file's size, sends the file from disk (it is never read into memory) and then finishes the upload. A file over the plan's size is refused before any byte is sent.
8
+ - The skill's file pages say how an agent sends a file over 8 MB with an upload link (`get_upload_link` with `size_bytes`, a PUT, then `finish_command`), that `attach_chat_file` takes files up to the plan's size, and what `virus_scan` `not_scanned_too_large` means.
9
+
10
+ ## 0.5.0
11
+
12
+ - 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.
13
+ - 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.
14
+ - 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`.
15
+ - `listspace new-board` takes `--template <id or name>`: a board from any template in `list_templates`, not only "Project (for agents)".
16
+ - `LISTSPACE_MCP_URL` points `tools`, `call` and the commands built on them at another MCP server.
17
+ - The skill's CLI page lists the new commands and `call`, and `my_items` has a CLI command now (`listspace call my_items`).
18
+ - 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.
19
+ - 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.
20
+
5
21
  ## 0.4.0
6
22
 
7
23
  - 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.
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 > Developers**, then save it:
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 > Developers).
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,18 +50,28 @@ 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
- With more than one space (see whoami), ask the user
55
- which one and pass --space; without it the board
56
- goes to the default space.
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
- attach <item> <file> [<file>...] At most 8 MB each.
74
+ attach <item> <file> [<file>...] Up to the plan's size of one file, at most 4 GB.
65
75
 
66
76
  Work on your own (needs level 4, Act)
67
77
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
@@ -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:
@@ -86,7 +115,7 @@ npx listspace add "Website" ideas "Try dark mode" --description "Seen in **setti
86
115
  npx listspace attach 2b6f0c1e-... ./contract.pdf ./screenshots/footer.png
87
116
  ```
88
117
 
89
- The type comes from the extension: images (jpg, png, gif, webp, svg), PDF, Word, Excel and PowerPoint files, text, Markdown, CSV, JSON, archives (zip, rar, 7z), audio and video. Each file can be at most 8 MB. Every file is checked before the first one is sent. Attaching needs level 4 (Act) on the board: a file cannot wait in the Inbox.
118
+ The type comes from the extension: images (jpg, png, gif, webp, svg), PDF, Word, Excel and PowerPoint files, text, Markdown, CSV, JSON, archives (zip, rar, 7z), audio and video. Each file can be as large as the plan of the board's owner allows (Free 25 MB, Pro 2 GB, a team's boards 5 GB), at most 4 GB from the CLI. A file over 8 MB goes straight to Listspace's file storage, sent from disk, and is put on the item when it has arrived. Every file is checked before the first one is sent. Attaching needs level 4 (Act) on the board: a file cannot wait in the Inbox.
90
119
 
91
120
  ## Output for agents and scripts
92
121
 
@@ -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
@@ -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);
@@ -225,12 +229,18 @@ var attached = object({
225
229
  url: string
226
230
  })
227
231
  });
232
+ var largeUploadLink = object({
233
+ upload_url: string,
234
+ finish_url: nullable(string)
235
+ });
228
236
 
229
237
  // src/version.ts
230
- var VERSION = "0.4.0";
238
+ var VERSION = "0.6.0";
231
239
 
232
240
  // src/api.ts
233
241
  var DEFAULT_API_URL = "https://api.listspace.app/v1";
242
+ var DEFAULT_MCP_URL = "https://mcp.listspace.app";
243
+ var MCP_PROTOCOL_VERSION = "2025-06-18";
234
244
  var TOKEN_PATTERN = /^ls_[A-Za-z0-9_-]{43}$/;
235
245
  function parseToken(raw) {
236
246
  const trimmed = raw.trim();
@@ -247,7 +257,9 @@ var CliFailure = class extends Error {
247
257
  var fail = (error) => {
248
258
  throw new CliFailure(error);
249
259
  };
250
- var LOGIN_HINT = "Run `listspace login` with a personal token (Listspace: Settings > Developers), or set LISTSPACE_TOKEN.";
260
+ var LOGIN_HINT = "Run `listspace login` with a personal token (Listspace: Settings > Your AI > API tokens), or set LISTSPACE_TOKEN.";
261
+ var RETRY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
262
+ var RETRY_DELAY_MS = 1500;
251
263
  var ApiClient = class {
252
264
  constructor(options) {
253
265
  this.options = options;
@@ -264,23 +276,100 @@ var ApiClient = class {
264
276
  const json = await this.send(method, path2, init);
265
277
  return { value: decodeOrFail(decoder, json, "body"), raw: json };
266
278
  }
279
+ /**
280
+ * PUTs a file to a signed storage link (get_upload_link for a large file).
281
+ * The link is the credential: no token is sent with it. The Blob's size
282
+ * is the Content-Length, which the link signed.
283
+ */
284
+ async putToStorage(url, file) {
285
+ let response;
286
+ try {
287
+ response = await this.options.fetch(url, { method: "PUT", body: file, headers: { "User-Agent": `listspace-cli/${VERSION}` } });
288
+ } catch (cause) {
289
+ const reason = cause instanceof Error ? cause.message : String(cause);
290
+ return fail({ kind: "network", message: `Could not send the file to Listspace's file storage: ${reason}` });
291
+ }
292
+ await response.body?.cancel();
293
+ if (!response.ok) {
294
+ return fail({ kind: "api", status: response.status, code: "upload_failed", message: `Listspace's file storage refused the file (HTTP ${response.status}). Run the command again for a new link.` });
295
+ }
296
+ }
297
+ /** POSTs to an upload link's finish address (no body; the link is the credential) and decodes `data`. */
298
+ async finishUpload(url, decoder) {
299
+ const { response, json } = await this.exchange(new URL(url), { method: "POST", headers: { Accept: "application/json", "User-Agent": `listspace-cli/${VERSION}` } }, false);
300
+ if (!response.ok) return fail(errorFor(response, json));
301
+ if (!isRecord(json) || !("data" in json)) return fail({ kind: "unexpected", message: "Unexpected response from Listspace: no data." });
302
+ return { value: decodeOrFail(decoder, json.data, "data"), raw: json.data };
303
+ }
304
+ /** A new idempotency key: a random UUID, or the tests' own. */
305
+ newKey() {
306
+ return (this.options.newKey ?? (() => crypto.randomUUID()))();
307
+ }
308
+ /**
309
+ * Runs one MCP tool by name, as the MCP server runs it for any client: the
310
+ * same token, agent access level checks and result. `retry`: the call is
311
+ * safe to send once more after a lost answer (a read, or a write with an
312
+ * idempotency_key).
313
+ */
314
+ async callTool(name, args, retry) {
315
+ const result = decodeOrFail(toolResult, await this.rpc("tools/call", { name, arguments: args }, retry), "result");
316
+ const text = result.content.flatMap((part) => part.text === null ? [] : [part.text]).join("\n");
317
+ if (result.isError) {
318
+ return fail({ kind: "tool", tool: name, message: text === "" ? `${name} failed.` : text, details: result.structuredContent });
319
+ }
320
+ return { value: result.structuredContent ?? parseText(text) };
321
+ }
322
+ /** The tools this token can use, as the MCP server lists them (a read-only token sees no write tools). */
323
+ async listTools() {
324
+ return decodeOrFail(toolList, await this.rpc("tools/list", {}, true), "result").tools;
325
+ }
326
+ /** One JSON-RPC request to the MCP server: its result, or a CliError for its error. */
327
+ async rpc(method, params, retry) {
328
+ const url = new URL(this.options.mcpUrl ?? DEFAULT_MCP_URL);
329
+ const request = {
330
+ method: "POST",
331
+ headers: {
332
+ ...this.identity(),
333
+ Accept: "application/json, text/event-stream",
334
+ "Content-Type": "application/json",
335
+ "MCP-Protocol-Version": MCP_PROTOCOL_VERSION
336
+ },
337
+ body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
338
+ };
339
+ const { response, json } = await this.exchange(url, request, retry);
340
+ const rpcError = isRecord(json) && isRecord(json.error) && typeof json.error.message === "string" && typeof json.error.code === "number" ? json.error : null;
341
+ if (rpcError !== null) {
342
+ const message = String(rpcError.message);
343
+ if (message.startsWith("Unknown tool")) return fail({ kind: "usage", message: `${message}. Run \`listspace tools\` to see the tools.` });
344
+ if (rpcError.code === INVALID_PARAMS) return fail({ kind: "usage", message });
345
+ return fail({ kind: "unexpected", message: `The Listspace MCP server answered: ${message}` });
346
+ }
347
+ if (!response.ok) return fail(errorFor(response, json));
348
+ if (!isRecord(json) || !("result" in json)) return fail({ kind: "unexpected", message: "Unexpected response from the Listspace MCP server: no result." });
349
+ return json.result;
350
+ }
351
+ /** The headers that say who is asking. The token goes only here, never into a message. */
352
+ identity() {
353
+ return { Authorization: `Bearer ${this.options.token}`, "User-Agent": `listspace-cli/${VERSION}` };
354
+ }
267
355
  async send(method, path2, init) {
268
356
  const url = new URL(this.options.baseUrl.replace(/\/+$/, "") + path2);
269
357
  for (const [key, value] of Object.entries(init.query ?? {})) {
270
358
  if (value !== void 0) url.searchParams.set(key, String(value));
271
359
  }
272
- const headers = {
273
- Authorization: `Bearer ${this.options.token}`,
274
- Accept: "application/json",
275
- "User-Agent": `listspace-cli/${VERSION}`
276
- };
360
+ const headers = { ...this.identity(), Accept: "application/json" };
277
361
  if (init.body !== void 0) headers["Content-Type"] = "application/json";
362
+ if (method === "POST") headers["Idempotency-Key"] = this.newKey();
363
+ const request = init.body === void 0 ? { method, headers } : { method, headers, body: JSON.stringify(init.body) };
364
+ const { response, json } = await this.exchange(url, request, method === "POST");
365
+ if (response.ok) return json;
366
+ return fail(errorFor(response, json));
367
+ }
368
+ /** Sends one request (once more when `retry` allows) and parses its JSON; the caller reads the status. */
369
+ async exchange(url, request, retry) {
278
370
  let response;
279
371
  try {
280
- response = await this.options.fetch(
281
- url.toString(),
282
- init.body === void 0 ? { method, headers } : { method, headers, body: JSON.stringify(init.body) }
283
- );
372
+ response = await this.attempt(url, request, retry);
284
373
  } catch (cause) {
285
374
  const reason = cause instanceof Error ? cause.message : String(cause);
286
375
  return fail({ kind: "network", message: `Could not reach Listspace at ${url.origin}: ${reason}` });
@@ -294,10 +383,54 @@ var ApiClient = class {
294
383
  if (response.ok) return fail({ kind: "unexpected", message: `Listspace answered ${response.status} with something that is not JSON.` });
295
384
  }
296
385
  }
297
- if (response.ok) return json;
298
- return fail(errorFor(response, json));
386
+ return { response, json };
387
+ }
388
+ /** One request; a write is sent once more, with the same key, after a network error or a 502, 503 or 504. */
389
+ async attempt(url, request, retry) {
390
+ let first;
391
+ try {
392
+ first = await this.options.fetch(url.toString(), request);
393
+ } catch (cause) {
394
+ if (!retry) throw cause;
395
+ await this.wait();
396
+ return await this.options.fetch(url.toString(), request);
397
+ }
398
+ if (!retry || !RETRY_STATUSES.has(first.status) || await isMaintenance(first)) return first;
399
+ await this.wait();
400
+ return await this.options.fetch(url.toString(), request);
401
+ }
402
+ async wait() {
403
+ await (this.options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(RETRY_DELAY_MS);
299
404
  }
300
405
  };
406
+ var INVALID_PARAMS = -32602;
407
+ var toolResult = object({
408
+ content: array(object({ type: string, text: withDefault(nullable(string), null) })),
409
+ structuredContent: withDefault(nullable(record), null),
410
+ isError: withDefault(boolean, false)
411
+ });
412
+ var toolInfo = object({
413
+ name: string,
414
+ title: withDefault(nullable(string), null),
415
+ description: withDefault(string, ""),
416
+ inputSchema: record
417
+ });
418
+ var toolList = object({ tools: array(toolInfo) });
419
+ function parseText(text) {
420
+ try {
421
+ return JSON.parse(text);
422
+ } catch {
423
+ return text;
424
+ }
425
+ }
426
+ async function isMaintenance(response) {
427
+ if (response.status !== 503) return false;
428
+ try {
429
+ return errorBody(JSON.parse(await response.clone().text()), "body").error.code === "maintenance";
430
+ } catch {
431
+ return false;
432
+ }
433
+ }
301
434
  function decodeOrFail(decoder, value, path2) {
302
435
  try {
303
436
  return decoder(value, path2);
@@ -323,14 +456,16 @@ function errorFor(response, json) {
323
456
  return { kind: "rate_limited", message: `${message} ${wait} before trying again.`, retryAfterSeconds: seconds };
324
457
  }
325
458
  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 > Developers.` };
459
+ 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
460
  }
328
461
  return { kind: "api", status: response.status, code: code2, message };
329
462
  }
330
463
 
331
464
  // src/files.ts
465
+ import { openAsBlob } from "node:fs";
332
466
  import { readFile, stat } from "node:fs/promises";
333
467
  var MAX_FILE_BYTES = 8 * 1024 * 1024;
468
+ var MAX_LARGE_FILE_BYTES = 4 * 1024 * 1024 * 1024;
334
469
  var TYPES = {
335
470
  jpg: "image/jpeg",
336
471
  jpeg: "image/jpeg",
@@ -374,7 +509,7 @@ function mimeTypeFor(fileName) {
374
509
  if (dot <= 0 || dot === fileName.length - 1) return null;
375
510
  return TYPES[fileName.slice(dot + 1).toLowerCase()] ?? null;
376
511
  }
377
- async function readLocalFile(path2, maxBytes) {
512
+ async function readLocalFile(path2, maxBytes, largeMaxBytes = maxBytes) {
378
513
  let size;
379
514
  try {
380
515
  const info = await stat(path2);
@@ -384,7 +519,14 @@ async function readLocalFile(path2, maxBytes) {
384
519
  if (isErrnoCode(error, "ENOENT")) return { kind: "missing" };
385
520
  return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
386
521
  }
387
- if (size > maxBytes) return { kind: "too_large", sizeBytes: size };
522
+ if (size > largeMaxBytes) return { kind: "too_large", sizeBytes: size };
523
+ if (size > maxBytes) {
524
+ try {
525
+ return { kind: "large", blob: await openAsBlob(path2), sizeBytes: size };
526
+ } catch (error) {
527
+ return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
528
+ }
529
+ }
388
530
  try {
389
531
  const bytes = await readFile(path2);
390
532
  if (bytes.length > maxBytes) return { kind: "too_large", sizeBytes: bytes.length };
@@ -399,7 +541,8 @@ function isErrnoCode(error, code2) {
399
541
  function formatSize(bytes) {
400
542
  if (bytes < 1024) return `${bytes} bytes`;
401
543
  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
402
- return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
544
+ if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
545
+ return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
403
546
  }
404
547
 
405
548
  // src/format.ts
@@ -645,7 +788,8 @@ async function newBoardCommand(client, input) {
645
788
  const body = {
646
789
  title: input.title,
647
790
  ...input.description === null ? {} : { description: input.description },
648
- ...input.space === null ? {} : { space_id: input.space }
791
+ ...input.space === null ? {} : { space_id: input.space },
792
+ ...input.templateId === null ? {} : { template_id: input.templateId }
649
793
  };
650
794
  const answer = await client.data("POST", "/boards", createdBoard, { body });
651
795
  return { raw: answer.raw, text: formatCreatedBoard(answer.value) };
@@ -732,18 +876,21 @@ async function prepareFiles(paths, read) {
732
876
  if (mimeType === null) {
733
877
  return fail({ kind: "usage", message: `${fileName}: this type of file cannot be attached. Allowed: ${ATTACHABLE_EXTENSIONS.join(", ")}.` });
734
878
  }
735
- const file = await read(filePath, MAX_FILE_BYTES);
879
+ const file = await read(filePath, MAX_FILE_BYTES, MAX_LARGE_FILE_BYTES);
736
880
  switch (file.kind) {
737
881
  case "ok":
738
882
  if (file.bytes.length === 0) return fail({ kind: "usage", message: `${filePath} is empty.` });
739
- out.push({ path: filePath, fileName, mimeType, bytes: file.bytes });
883
+ out.push({ path: filePath, fileName, mimeType, content: { kind: "bytes", bytes: file.bytes } });
884
+ break;
885
+ case "large":
886
+ out.push({ path: filePath, fileName, mimeType, content: { kind: "blob", blob: file.blob, sizeBytes: file.sizeBytes } });
740
887
  break;
741
888
  case "missing":
742
889
  return fail({ kind: "usage", message: `${filePath}: no such file.` });
743
890
  case "not_a_file":
744
891
  return fail({ kind: "usage", message: `${filePath} is a folder, not a file.` });
745
892
  case "too_large":
746
- return fail({ kind: "usage", message: `${filePath} is ${formatSize(file.sizeBytes)}; a file can be at most ${formatSize(MAX_FILE_BYTES)}. Share a link with attach_url instead, or make it smaller.` });
893
+ return fail({ kind: "usage", message: `${filePath} is ${formatSize(file.sizeBytes)}; a file can be at most ${formatSize(MAX_LARGE_FILE_BYTES)} from here. Add it in the Listspace app instead, or make it smaller.` });
747
894
  case "unreadable":
748
895
  return fail({ kind: "unexpected", message: `Could not read ${filePath}: ${file.reason}` });
749
896
  default: {
@@ -759,9 +906,8 @@ async function attachCommand(client, input) {
759
906
  const results = [];
760
907
  const raw = [];
761
908
  for (const file of input.files) {
762
- const body = { filename: file.fileName, mime_type: file.mimeType, content_base64: Buffer.from(file.bytes).toString("base64") };
763
909
  try {
764
- const answer = await client.data("POST", `/items/${path(input.item)}/attachments`, attached, { body });
910
+ const answer = await attachOne(client, input.item, file);
765
911
  results.push(answer.value);
766
912
  raw.push(answer.raw);
767
913
  } catch (error) {
@@ -772,6 +918,136 @@ async function attachCommand(client, input) {
772
918
  }
773
919
  return { raw: { data: raw }, text: formatAttached(results) };
774
920
  }
921
+ async function attachOne(client, item2, file) {
922
+ switch (file.content.kind) {
923
+ case "bytes": {
924
+ const body = { filename: file.fileName, mime_type: file.mimeType, content_base64: Buffer.from(file.content.bytes).toString("base64") };
925
+ return client.data("POST", `/items/${path(item2)}/attachments`, attached, { body });
926
+ }
927
+ case "blob": {
928
+ const link = await client.data("POST", `/items/${path(item2)}/upload-links`, largeUploadLink, { body: { filename: file.fileName, size_bytes: file.content.sizeBytes } });
929
+ if (link.value.finish_url === null) return fail({ kind: "unexpected", message: "Listspace answered without a link to finish a large upload. Update the CLI, or the server is older than it." });
930
+ await client.putToStorage(link.value.upload_url, file.content.blob);
931
+ return client.finishUpload(link.value.finish_url, attached);
932
+ }
933
+ default: {
934
+ const exhaustive = file.content;
935
+ return exhaustive;
936
+ }
937
+ }
938
+ }
939
+
940
+ // src/tools.ts
941
+ var UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
942
+ function parseToolArgs(raw) {
943
+ if (raw === void 0) return {};
944
+ let value;
945
+ try {
946
+ value = JSON.parse(raw);
947
+ } catch {
948
+ return fail({ kind: "usage", message: `The arguments are not valid JSON. Pass one object, for example '{"board_id": "..."}', in single quotes.` });
949
+ }
950
+ if (!isRecord(value)) return fail({ kind: "usage", message: `The arguments must be one JSON object, for example '{"board_id": "..."}'.` });
951
+ return value;
952
+ }
953
+ var asText = (value) => typeof value === "string" ? value : JSON.stringify(value, null, 2);
954
+ async function callCommand(client, input) {
955
+ const answer = await client.callTool(input.tool, input.args, typeof input.args.idempotency_key === "string");
956
+ return { raw: answer.value, text: asText(answer.value) };
957
+ }
958
+ var SUMMARY_MAX = 100;
959
+ function firstSentence(description) {
960
+ const end = description.search(/\.(\s|$)/);
961
+ const sentence = end === -1 ? description : description.slice(0, end + 1);
962
+ if (sentence.length <= SUMMARY_MAX) return sentence;
963
+ const cut = sentence.slice(0, SUMMARY_MAX);
964
+ const space = cut.lastIndexOf(" ");
965
+ return `${(space > 0 ? cut.slice(0, space) : cut).replace(/[,;:(]$/, "")}...`;
966
+ }
967
+ async function toolsCommand(client, input) {
968
+ const tools = await client.listTools();
969
+ if (input.name === null) {
970
+ const width = Math.max(0, ...tools.map((tool2) => tool2.name.length));
971
+ const lines = tools.map((tool2) => `${tool2.name.padEnd(width)} ${firstSentence(tool2.description)}`);
972
+ lines.push("", `${tools.length} tools. \`listspace tools <name>\` shows one with its arguments; \`listspace call <name> '<json>'\` runs it.`);
973
+ return { raw: { tools: tools.map(({ name, title, description }) => ({ name, title, description })) }, text: lines.join("\n") };
974
+ }
975
+ const tool = tools.find((candidate) => candidate.name === input.name);
976
+ if (tool === void 0) return fail({ kind: "usage", message: `No tool called "${input.name}" for this token. Run \`listspace tools\` to see them.` });
977
+ return { raw: tool, text: formatTool(tool) };
978
+ }
979
+ function formatTool(tool) {
980
+ return [
981
+ tool.title === null ? tool.name : `${tool.name}: ${tool.title}`,
982
+ "",
983
+ tool.description,
984
+ "",
985
+ "Arguments (JSON Schema):",
986
+ JSON.stringify(tool.inputSchema, null, 2)
987
+ ].join("\n");
988
+ }
989
+ async function write(client, tool, args, done, keyed) {
990
+ const sent = keyed ? { ...args, idempotency_key: client.newKey() } : args;
991
+ const answer = await client.callTool(tool, sent, keyed);
992
+ const outcome = outcomeOf(answer.value);
993
+ return { raw: answer.value, text: outcome === null ? asText(answer.value) : formatWrite(outcome, done) };
994
+ }
995
+ function outcomeOf(value) {
996
+ try {
997
+ return writeOutcome(value, "result");
998
+ } catch (error) {
999
+ if (error instanceof DecodeError) return null;
1000
+ throw error;
1001
+ }
1002
+ }
1003
+ function commentCommand(client, input) {
1004
+ return write(client, "add_comment", { item_id: input.item, text: input.text, ...inboxFields(input.choice) }, "Commented", true);
1005
+ }
1006
+ function updateCommand(client, input) {
1007
+ if (input.title === null && input.description === null) {
1008
+ return fail({ kind: "usage", message: "`update` needs --title, --description or both." });
1009
+ }
1010
+ const args = {
1011
+ item_id: input.item,
1012
+ ...input.title === null ? {} : { title: input.title },
1013
+ ...input.description === null ? {} : { description: input.description },
1014
+ ...inboxFields(input.choice)
1015
+ };
1016
+ return write(client, "update_item", args, "Updated the item", false);
1017
+ }
1018
+ async function listAddCommand(client, input) {
1019
+ const boardId = await resolveBoardId(client, input.board);
1020
+ const args = { board_id: boardId, title: input.title, ...input.kind === null ? {} : { kind: input.kind }, ...inboxFields(input.choice) };
1021
+ return write(client, "create_list", args, `Added the list "${input.title}"`, true);
1022
+ }
1023
+ function listRenameCommand(client, input) {
1024
+ return write(client, "update_list", { list_id: input.list, title: input.title, ...inboxFields(input.choice) }, `Renamed the list to "${input.title}"`, false);
1025
+ }
1026
+ var templates = (value, path2) => object({ templates: array(object({ id: string, name: string })) })(value, path2).templates;
1027
+ function decodeOrFail2(decoder, value) {
1028
+ try {
1029
+ return decoder(value, "result");
1030
+ } catch (error) {
1031
+ if (error instanceof DecodeError) return fail({ kind: "unexpected", message: error.message });
1032
+ throw error;
1033
+ }
1034
+ }
1035
+ async function resolveTemplateId(client, ref) {
1036
+ if (UUID2.test(ref)) return ref;
1037
+ const answer = await client.callTool("list_templates", {}, true);
1038
+ const all = decodeOrFail2(templates, answer.value);
1039
+ const wanted = ref.trim().toLowerCase();
1040
+ const exact = all.filter((template) => template.name.toLowerCase() === wanted);
1041
+ const matches = exact.length > 0 ? exact : all.filter((template) => template.name.toLowerCase().startsWith(wanted));
1042
+ const [first, ...others] = matches;
1043
+ if (first === void 0) {
1044
+ return fail({ kind: "usage", message: `No template called "${ref}". Run \`listspace call list_templates\` to see them.` });
1045
+ }
1046
+ if (others.length > 0) {
1047
+ return fail({ kind: "usage", message: `"${ref}" matches ${matches.length} templates: ${matches.map((t) => `${t.name} (${t.id})`).join(", ")}. Use the id.` });
1048
+ }
1049
+ return first.id;
1050
+ }
775
1051
 
776
1052
  // src/config.ts
777
1053
  import { chmod, mkdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
@@ -834,7 +1110,7 @@ var HELP = `listspace ${VERSION}: Listspace from the command line, for people an
834
1110
  Usage: listspace <command> [arguments] [--json]
835
1111
 
836
1112
  Sign in
837
- login [--token ls_...] Save a personal token (Listspace: Settings > Developers).
1113
+ login [--token ls_...] Save a personal token (Listspace: Settings > Your AI > API tokens).
838
1114
  Without --token it reads the token from stdin.
839
1115
  logout Forget the saved token.
840
1116
  whoami Plan, agent access, guidance and boards (alias: account).
@@ -847,22 +1123,37 @@ Read
847
1123
  inbox <board> [--status pending|accepted|rejected|withdrawn|expired|failed|all]
848
1124
 
849
1125
  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 agents)". With more than
852
- one space (see whoami), ask the user which one and
853
- pass --space; without it the board goes to the
854
- default space.
1126
+ new-board <title> [--template <id or name>] [--description <text>] [--space <space id>]
1127
+ A board from the template (default "Project (for
1128
+ agents)"). With more than one space (see whoami),
1129
+ ask the user which one and pass --space; without
1130
+ it the board goes to the default space.
855
1131
  add <board> <list> <title> [--description <markdown>]
1132
+ update <item> [--title <text>] [--description <markdown>]
1133
+ comment <item> <text> Add a comment (markdown) to an item.
856
1134
  move <item> <list>
857
1135
  done <item> Move to the board's done list.
1136
+ list add <board> <title> [--kind info|capture|backlog|todo|doing|done]
1137
+ list rename <list> <title> Here <list> is a list id.
858
1138
  undo <request_id> Take back one of your own calls.
859
1139
  Writes take --inbox --reason "<why>" to suggest instead of change.
860
1140
 
1141
+ Every MCP tool (the same tools, levels and results as the MCP server)
1142
+ tools The tools this token can use, one line each.
1143
+ tools <name> One tool: what it does and its arguments.
1144
+ call <tool> ['<json>'] Run a tool with its arguments as one JSON object,
1145
+ for example: call get_item --json '{"item_id": "..."}'
1146
+ Give a call that makes something an
1147
+ idempotency_key, so a retry never makes it twice.
1148
+
861
1149
  Files from this computer (needs level 4, Act; a file cannot wait in the Inbox)
862
1150
  attach <item> <file> [<file>...]
863
- Upload files to an item, at most 8 MB each:
864
- images, PDF, Office files, text, Markdown, CSV,
865
- JSON, archives, audio and video.
1151
+ Upload files to an item: images, PDF, Office
1152
+ files, text, Markdown, CSV, JSON, archives, audio
1153
+ and video. Up to the plan's size of one file
1154
+ (Free 25 MB, Pro 2 GB, a team's boards 5 GB), at
1155
+ most 4 GB from here; over 8 MB the file goes
1156
+ straight to file storage.
866
1157
 
867
1158
  Work on your own (needs level 4, Act; other agents leave a claimed item alone)
868
1159
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
@@ -880,12 +1171,14 @@ Work on your own (needs level 4, Act; other agents leave a claimed item alone)
880
1171
  info, capture, backlog), <item> an item id.
881
1172
 
882
1173
  Options
883
- --json Print the API's JSON (for agents and scripts).
1174
+ --json Print the server's JSON (for agents and scripts).
884
1175
  --help This help. --version The version.
885
1176
 
886
1177
  Environment
887
1178
  LISTSPACE_TOKEN A token for this run (wins over the saved one).
888
1179
  LISTSPACE_API_URL Default ${DEFAULT_API_URL}
1180
+ LISTSPACE_MCP_URL Default ${DEFAULT_MCP_URL} (for tools, call and the
1181
+ commands built on them).
889
1182
  LISTSPACE_CONFIG_DIR Where credentials.json is kept.
890
1183
 
891
1184
  Exit codes: 0 ok, 1 failed, 2 usage, 3 sign in needed, 4 rate limited (wait and retry).`;
@@ -895,7 +1188,8 @@ var EXIT = {
895
1188
  rate_limited: 4,
896
1189
  api: 1,
897
1190
  network: 1,
898
- unexpected: 1
1191
+ unexpected: 1,
1192
+ tool: 1
899
1193
  };
900
1194
  var OPTIONS = {
901
1195
  json: { type: "boolean" },
@@ -903,7 +1197,10 @@ var OPTIONS = {
903
1197
  version: { type: "boolean", short: "v" },
904
1198
  token: { type: "string" },
905
1199
  description: { type: "string" },
1200
+ title: { type: "string" },
906
1201
  space: { type: "string" },
1202
+ template: { type: "string" },
1203
+ kind: { type: "string" },
907
1204
  inbox: { type: "boolean" },
908
1205
  reason: { type: "string" },
909
1206
  status: { type: "string" },
@@ -954,7 +1251,7 @@ async function clientFor(io, dir) {
954
1251
  switch (source.kind) {
955
1252
  case "env":
956
1253
  case "file":
957
- return new ApiClient({ baseUrl: apiUrl(io.env), token: source.token, fetch: io.fetch });
1254
+ return new ApiClient({ baseUrl: apiUrl(io.env), mcpUrl: mcpUrl(io.env), token: source.token, fetch: io.fetch });
958
1255
  case "none":
959
1256
  return fail({ kind: "auth", message: `Not signed in. ${LOGIN_HINT}` });
960
1257
  case "invalid":
@@ -969,9 +1266,20 @@ var apiUrl = (env) => {
969
1266
  const url = env.LISTSPACE_API_URL;
970
1267
  return url !== void 0 && url !== "" ? url : DEFAULT_API_URL;
971
1268
  };
1269
+ var mcpUrl = (env) => {
1270
+ const url = env.LISTSPACE_MCP_URL;
1271
+ return url !== void 0 && url !== "" ? url : DEFAULT_MCP_URL;
1272
+ };
1273
+ function listKindFrom(flags) {
1274
+ if (flags.kind === void 0) return null;
1275
+ const wanted = flags.kind.trim().toLowerCase();
1276
+ const kind = LIST_KINDS.find((candidate) => candidate === wanted);
1277
+ if (kind === void 0) return usage(`--kind is one of ${LIST_KINDS.join(", ")}.`);
1278
+ return kind;
1279
+ }
972
1280
  async function loginMethod(flags, io) {
973
1281
  if (flags.token !== void 0) return { kind: "token", raw: flags.token };
974
- const typed = await io.readSecret("Paste a personal token from Listspace (Settings > Developers): ");
1282
+ const typed = await io.readSecret("Paste a personal token from Listspace (Settings > Your AI > API tokens): ");
975
1283
  if (typed === null || typed.trim() === "") return { kind: "pairing" };
976
1284
  return { kind: "token", raw: typed };
977
1285
  }
@@ -997,7 +1305,7 @@ async function dispatch(command, args, flags, io, dir) {
997
1305
  case "logout": {
998
1306
  positionals(command, args, []);
999
1307
  const removed = await removeToken(dir);
1000
- return { raw: { signed_out: removed }, text: removed ? "Signed out: the saved token is gone (revoke it in Settings > Developers if it leaked)." : "No saved token." };
1308
+ 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
1309
  }
1002
1310
  case "whoami":
1003
1311
  case "account":
@@ -1016,7 +1324,45 @@ async function dispatch(command, args, flags, io, dir) {
1016
1324
  }
1017
1325
  case "new-board": {
1018
1326
  const [title] = positionals(command, args, ["title"]);
1019
- return newBoardCommand(await clientFor(io, dir), { title, description: flags.description ?? null, space: flags.space ?? null });
1327
+ const client = await clientFor(io, dir);
1328
+ const templateId = flags.template === void 0 ? null : await resolveTemplateId(client, flags.template);
1329
+ return newBoardCommand(client, { title, description: flags.description ?? null, space: flags.space ?? null, templateId });
1330
+ }
1331
+ case "call": {
1332
+ const [tool, raw, ...extra] = args;
1333
+ if (tool === void 0 || extra.length > 0) return usage("`call` takes <tool> and at most one JSON object of arguments (in single quotes).");
1334
+ const toolArgs = parseToolArgs(raw);
1335
+ return callCommand(await clientFor(io, dir), { tool, args: toolArgs });
1336
+ }
1337
+ case "tools": {
1338
+ if (args.length > 1) return usage("`tools` takes no arguments, or one tool name.");
1339
+ return toolsCommand(await clientFor(io, dir), { name: args[0] ?? null });
1340
+ }
1341
+ case "comment": {
1342
+ const [item2, text] = positionals(command, args, ["item", "text"]);
1343
+ const choice = choiceFrom(flags);
1344
+ return commentCommand(await clientFor(io, dir), { item: item2, text, choice });
1345
+ }
1346
+ case "update": {
1347
+ const [item2] = positionals(command, args, ["item"]);
1348
+ const choice = choiceFrom(flags);
1349
+ return updateCommand(await clientFor(io, dir), { item: item2, title: flags.title ?? null, description: flags.description ?? null, choice });
1350
+ }
1351
+ case "list": {
1352
+ const [sub, ...rest] = args;
1353
+ switch (sub) {
1354
+ case "add": {
1355
+ const [board, title] = positionals("list add", rest, ["board", "title"]);
1356
+ const input = { board, title, kind: listKindFrom(flags), choice: choiceFrom(flags) };
1357
+ return listAddCommand(await clientFor(io, dir), input);
1358
+ }
1359
+ case "rename": {
1360
+ const [list, title] = positionals("list rename", rest, ["list", "title"]);
1361
+ return listRenameCommand(await clientFor(io, dir), { list, title, choice: choiceFrom(flags) });
1362
+ }
1363
+ default:
1364
+ return usage("`list` takes `add <board> <title>` or `rename <list> <title>`.");
1365
+ }
1020
1366
  }
1021
1367
  case "add": {
1022
1368
  const [board, list, title] = positionals(command, args, ["board", "list", "title"]);
@@ -1110,6 +1456,8 @@ function errorJson(error) {
1110
1456
  return { kind: error.kind, status: error.status, code: error.code, message: error.message };
1111
1457
  case "rate_limited":
1112
1458
  return { kind: error.kind, message: error.message, retry_after_seconds: error.retryAfterSeconds };
1459
+ case "tool":
1460
+ return { kind: error.kind, tool: error.tool, message: error.message, ...error.details === null ? {} : { details: error.details } };
1113
1461
  case "usage":
1114
1462
  case "auth":
1115
1463
  case "network":
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "listspace",
3
- "version": "0.4.0",
3
+ "version": "0.6.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": {