listspace 0.4.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 CHANGED
@@ -2,6 +2,17 @@
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.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
+
5
16
  ## 0.4.0
6
17
 
7
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.
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,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
- 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
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
@@ -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.4.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 > Developers), or set LISTSPACE_TOKEN.";
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.options.fetch(
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
- if (response.ok) return json;
298
- return fail(errorFor(response, json));
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 > Developers.` };
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 > Developers).
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 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.
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 API's JSON (for agents and scripts).
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 > Developers): ");
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 > Developers if it leaked)." : "No saved token." };
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
- return newBoardCommand(await clientFor(io, dir), { title, description: flags.description ?? null, space: flags.space ?? null });
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.4.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": {