listspace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sjenkie B.V. (Yellow House Digital)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# listspace
+
+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`).
+
+Node 20 or later. No runtime dependencies.
+
+## Install
+
+Run it without installing:
+
+```bash
+npx listspace --help
+```
+
+Or install it once and use `listspace` everywhere:
+
+```bash
+npm install -g listspace
+```
+
+## Sign in
+
+Create a personal token in ListSpace under **Settings > API**, then save it:
+
+```bash
+npx listspace login --token ls_...
+```
+
+Without `--token`, `login` reads the token from stdin, so it stays out of your shell history:
+
+```bash
+cat token.txt | npx listspace login
+```
+
+The token is saved as `credentials.json` (mode 600) in your OS config directory: `%APPDATA%\listspace` on Windows, `~/Library/Application Support/listspace` on macOS and `~/.config/listspace` elsewhere. `listspace logout` removes it. A read-only token works for the read commands only.
+
+## Commands
+
+```text
+Sign in
+  login [--token ls_...]    Save a personal token (ListSpace: Settings > API).
+  logout                    Forget the saved token.
+  whoami                    Plan, freedom levels, guidance and boards (alias: account).
+
+Read
+  boards                    Your boards with their ids.
+  session <board>           Start a work session: guidance, board instructions,
+                            level, open work. Run this first.
+  board <board>             Lists and items with their ids.
+  inbox <board> [--status pending|accepted|rejected|withdrawn|expired|failed|all]
+
+Write (the board's freedom level decides what is made and what waits in the Inbox)
+  new-board <title> [--description <text>]
+  add <board> <list> <title> [--description <markdown>]
+  move <item> <list>
+  done <item>               Move to the board's done list.
+  undo <request_id>         Take back one of your own calls.
+  Writes take --inbox --reason "<why>" to suggest instead of change.
+
+Work on your own (needs level 4, Act)
+  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
+  claim <item> [--ttl <minutes>]
+  release <item>
+```
+
+`<board>` is an id or a title. `<list>` is an id, a title or a kind (`todo`, `doing`, `done`, `info`, `capture`, `backlog`). `<item>` is an item id. Run `listspace --help` for every option.
+
+Example:
+
+```bash
+npx listspace session "Website"
+npx listspace add "Website" ideas "Try dark mode" --description "Seen in **settings**"
+```
+
+## Output for agents and scripts
+
+Every command takes `--json` and then prints the API's JSON instead of text:
+
+```bash
+npx listspace boards --json
+```
+
+Exit codes: 0 ok, 1 failed, 2 usage error, 3 sign-in needed, 4 rate limited (wait and retry).
+
+## Environment
+
+| Variable | What it does |
+|---|---|
+| `LISTSPACE_TOKEN` | A token for this run. It wins over the saved one. |
+| `LISTSPACE_API_URL` | Another API address. Default `https://api.listspace.app/v1`. |
+| `LISTSPACE_CONFIG_DIR` | Where `credentials.json` is kept. |
+
+## What agents may do
+
+Each board has a freedom level that decides what an agent may change on its own. Changes that need your approval wait in the board's Inbox, and every change shows who made it. The rules are in [What AI agents can do](https://listspace.app/docs/agents). Agents that support MCP can also connect to `https://mcp.listspace.app` instead of using this CLI ([setup](https://listspace.app/docs/mcp)).
+
+## License
+
+MIT, Sjenkie B.V. (Yellow House Digital). See `LICENSE`.

package/dist/listspace.mjs

@@ -0,0 +1,976 @@
+#!/usr/bin/env node
+
+// src/main.ts
+import { createInterface } from "node:readline/promises";
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// src/decode.ts
+var DecodeError = class extends Error {
+  constructor(path2, expected) {
+    super(`Unexpected response from ListSpace: ${path2} should be ${expected}.`);
+    this.path = path2;
+    this.expected = expected;
+    this.name = "DecodeError";
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var string = (value, path2) => {
+  if (typeof value !== "string") throw new DecodeError(path2, "a string");
+  return value;
+};
+var number = (value, path2) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new DecodeError(path2, "a number");
+  return value;
+};
+var boolean = (value, path2) => {
+  if (typeof value !== "boolean") throw new DecodeError(path2, "true or false");
+  return value;
+};
+function literal(...allowed) {
+  return (value, path2) => {
+    const match = allowed.find((candidate) => candidate === value);
+    if (match === void 0) throw new DecodeError(path2, `one of ${allowed.map((a) => JSON.stringify(a)).join(", ")}`);
+    return match;
+  };
+}
+function nullable(inner) {
+  return (value, path2) => value === null ? null : inner(value, path2);
+}
+function withDefault(inner, fallback) {
+  return (value, path2) => value === void 0 ? fallback : inner(value, path2);
+}
+function array(inner) {
+  return (value, path2) => {
+    if (!Array.isArray(value)) throw new DecodeError(path2, "a list");
+    return value.map((entry, index) => inner(entry, `${path2}[${index}]`));
+  };
+}
+function object(shape) {
+  return (value, path2) => {
+    if (!isRecord(value)) throw new DecodeError(path2, "an object");
+    const out = {};
+    for (const [key, decode] of Object.entries(shape)) {
+      out[key] = decode(value[key], `${path2}.${key}`);
+    }
+    return out;
+  };
+}
+function union(pick, a, b) {
+  return (value, path2) => {
+    if (!isRecord(value)) throw new DecodeError(path2, "an object");
+    return pick(value) === "a" ? a(value, path2) : b(value, path2);
+  };
+}
+
+// src/schema.ts
+var LIST_KINDS = ["info", "capture", "backlog", "todo", "doing", "done"];
+var listKind = nullable(literal(...LIST_KINDS));
+var level = object({
+  effective: literal(1, 2, 3, 4, 5),
+  name: string
+});
+var account = object({
+  guidance: nullable(string),
+  default_level: object({ effective: literal(1, 2, 3, 4, 5), name: string, limited_by_plan: boolean }),
+  plan: object({ name: string, max_agent_level: number }),
+  boards: array(
+    object({
+      id: string,
+      title: string,
+      url: string,
+      level,
+      follows_account: boolean,
+      inbox_pending: number,
+      has_instructions: boolean
+    })
+  )
+});
+var boardSummary = object({ id: string, title: string, url: string, archived: boolean });
+var cardBrief = object({ id: string, title: string, due_date: nullable(string), done: boolean });
+var boardDetail = object({
+  id: string,
+  title: string,
+  url: string,
+  guidance: withDefault(nullable(string), null),
+  instructions: withDefault(nullable(string), null),
+  level: withDefault(nullable(level), null),
+  lists: array(object({ id: string, title: string, kind: listKind, cards: array(cardBrief) })),
+  truncated: withDefault(boolean, false)
+});
+var itemBrief = object({
+  id: string,
+  title: string,
+  list_title: string,
+  due_date: nullable(string),
+  url: string
+});
+var session = object({
+  guidance: nullable(string),
+  board: object({ id: string, title: string, url: string }),
+  instructions: nullable(string),
+  level,
+  lists: array(object({ id: string, title: string, kind: listKind, open_items: number })),
+  work: array(itemBrief),
+  captured: array(itemBrief),
+  recently_done: array(itemBrief),
+  due_soon: array(itemBrief),
+  today: string,
+  truncated: boolean
+});
+var item = object({ id: string, board_id: string, list_id: string, title: string, url: string });
+var applied = object({
+  outcome: literal("applied"),
+  level,
+  undo: nullable(object({ request_id: string }))
+});
+var suggested = object({
+  outcome: literal("suggested"),
+  level,
+  message: string,
+  suggestion: object({ id: string, status: string })
+});
+var writeOutcome = union(
+  (value) => value.outcome === "suggested" ? "b" : "a",
+  applied,
+  suggested
+);
+var createdBoard = object({
+  id: string,
+  title: string,
+  url: string,
+  instructions: nullable(string),
+  level,
+  lists: array(object({ id: string, title: string, kind: listKind })),
+  undo: nullable(object({ request_id: string }))
+});
+var inbox = object({
+  suggestions: array(
+    object({
+      id: string,
+      action: string,
+      item_title: nullable(string),
+      list_title: nullable(string),
+      reason: nullable(string),
+      agent_name: string,
+      status: string,
+      stale: boolean,
+      created_at: string,
+      expires_at: string
+    })
+  )
+});
+var undoResult = object({
+  outcome: literal("undone", "already_undone"),
+  undone: array(string),
+  level: nullable(level)
+});
+var claimedBy = object({ agent_name: nullable(string), expires_at: string });
+var taken = object({
+  outcome: literal("taken"),
+  item_id: string,
+  claimed_by: claimedBy,
+  message: string,
+  level
+});
+var claimHeld = object({ outcome: literal("claimed", "renewed"), item_id: string, expires_at: string, level });
+var claimResult = union(
+  (value) => value.outcome === "taken" ? "b" : "a",
+  claimHeld,
+  taken
+);
+var released = object({ outcome: literal("released", "not_claimed"), item_id: string, level });
+var releaseResult = union(
+  (value) => value.outcome === "taken" ? "b" : "a",
+  released,
+  taken
+);
+var nextClaimed = object({
+  outcome: literal("claimed"),
+  item: object({ id: string, title: string, list_id: string, url: string }),
+  expires_at: string,
+  moved_to: nullable(object({ list_id: string, list_title: string })),
+  note: nullable(string),
+  level,
+  undo: nullable(object({ request_id: string }))
+});
+var nextEmpty = object({ outcome: literal("empty"), message: string, level });
+var nextResult = union(
+  (value) => value.outcome === "empty" ? "b" : "a",
+  nextClaimed,
+  nextEmpty
+);
+function page(entry) {
+  return object({ data: array(entry), next_cursor: nullable(string) });
+}
+var errorBody = object({ error: object({ code: string, message: string }) });
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/api.ts
+var DEFAULT_API_URL = "https://api.listspace.app/v1";
+var TOKEN_PATTERN = /^ls_[A-Za-z0-9_-]{43}$/;
+function parseToken(raw) {
+  const trimmed = raw.trim();
+  return TOKEN_PATTERN.test(trimmed) ? trimmed : null;
+}
+var CliFailure = class extends Error {
+  constructor(error) {
+    super(error.message);
+    this.error = error;
+    this.name = "CliFailure";
+  }
+};
+var fail = (error) => {
+  throw new CliFailure(error);
+};
+var LOGIN_HINT = "Run `listspace login` with a personal token (ListSpace: Settings > API), or set LISTSPACE_TOKEN.";
+var ApiClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  /** Sends one request and decodes `data` from the answer. */
+  async data(method, path2, decoder, init = {}) {
+    const json = await this.send(method, path2, init);
+    if (!isRecord(json) || !("data" in json)) return fail({ kind: "unexpected", message: "Unexpected response from ListSpace: no data." });
+    return { value: decodeOrFail(decoder, json.data, "data"), raw: json.data };
+  }
+  /** Sends one request and decodes the whole body (list endpoints with next_cursor). */
+  async body(method, path2, decoder, init = {}) {
+    const json = await this.send(method, path2, init);
+    return { value: decodeOrFail(decoder, json, "body"), raw: json };
+  }
+  async send(method, path2, init) {
+    const url = new URL(this.options.baseUrl.replace(/\/+$/, "") + path2);
+    for (const [key, value] of Object.entries(init.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = {
+      Authorization: `Bearer ${this.options.token}`,
+      Accept: "application/json",
+      "User-Agent": `listspace-cli/${VERSION}`
+    };
+    if (init.body !== void 0) headers["Content-Type"] = "application/json";
+    let response;
+    try {
+      response = await this.options.fetch(
+        url.toString(),
+        init.body === void 0 ? { method, headers } : { method, headers, body: JSON.stringify(init.body) }
+      );
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      return fail({ kind: "network", message: `Could not reach ListSpace at ${url.origin}: ${reason}` });
+    }
+    const text = await response.text();
+    let json = null;
+    if (text !== "") {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        if (response.ok) return fail({ kind: "unexpected", message: `ListSpace answered ${response.status} with something that is not JSON.` });
+      }
+    }
+    if (response.ok) return json;
+    return fail(errorFor(response, json));
+  }
+};
+function decodeOrFail(decoder, value, path2) {
+  try {
+    return decoder(value, path2);
+  } catch (error) {
+    if (error instanceof DecodeError) return fail({ kind: "unexpected", message: error.message });
+    throw error;
+  }
+}
+function errorFor(response, json) {
+  let code2 = "unknown";
+  let message = `ListSpace answered ${response.status}.`;
+  try {
+    const parsed = errorBody(json, "body");
+    code2 = parsed.error.code;
+    message = parsed.error.message;
+  } catch {
+  }
+  if (response.status === 401) return { kind: "auth", message: `${message} ${LOGIN_HINT}` };
+  if (response.status === 429) {
+    const header = response.headers.get("Retry-After");
+    const seconds = header !== null && /^\d+$/.test(header) ? Number(header) : null;
+    const wait = seconds === null ? "Wait a minute" : `Wait ${seconds} seconds`;
+    return { kind: "rate_limited", message: `${message} ${wait} before trying again.`, retryAfterSeconds: seconds };
+  }
+  if (response.status === 403 && code2 === "insufficient_scope") {
+    return { kind: "api", status: 403, code: code2, message: `${message} This token is read only; create a read and write token in Settings > API.` };
+  }
+  return { kind: "api", status: response.status, code: code2, message };
+}
+
+// src/format.ts
+var levelText = (level2) => `level ${level2.effective} (${level2.name})`;
+function block(title, text) {
+  if (text === null || text.trim() === "") return [];
+  return [`${title}:`, ...text.trim().split("\n").map((line) => `  ${line}`)];
+}
+function items(title, list, showList) {
+  if (list.length === 0) return [];
+  return [
+    `${title}:`,
+    ...list.map((entry) => {
+      const where = showList ? ` [${entry.list_title}]` : "";
+      const due = entry.due_date === null ? "" : ` (due ${entry.due_date})`;
+      return `  - ${entry.title}${where}${due}  ${entry.id}`;
+    })
+  ];
+}
+function formatAccount(account2) {
+  const lines = [
+    `Plan: ${account2.plan.name}`,
+    `Default ${levelText(account2.default_level)}${account2.default_level.limited_by_plan ? ", limited by the plan" : ""}`,
+    ...block("Guidance for agents", account2.guidance),
+    `Boards (${account2.boards.length}):`,
+    ...account2.boards.map((board) => {
+      const notes = [levelText(board.level)];
+      if (board.inbox_pending > 0) notes.push(`${board.inbox_pending} in Inbox`);
+      if (board.has_instructions) notes.push("has instructions");
+      return `  - ${board.title}  ${board.id}  (${notes.join(", ")})`;
+    })
+  ];
+  return lines.join("\n");
+}
+function formatBoards(boards) {
+  if (boards.length === 0) return 'No boards yet. Create one with `listspace new-board "<title>"`.';
+  return boards.map((board) => `${board.title}  ${board.id}`).join("\n");
+}
+function formatSession(session2) {
+  const lists = session2.lists.map((list) => `${list.title}${list.kind === null ? "" : ` (${list.kind})`}: ${list.open_items}`);
+  return [
+    `${session2.board.title}  ${session2.board.id}`,
+    `${session2.board.url}`,
+    `Agent ${levelText(session2.level)}. Today is ${session2.today}.`,
+    ...block("Guidance for agents (read first)", session2.guidance),
+    ...block("Board instructions (follow these)", session2.instructions),
+    `Lists: ${lists.join(", ")}`,
+    ...items("Work", session2.work, true),
+    ...items("Captured", session2.captured, true),
+    ...items("Due soon", session2.due_soon, true),
+    ...items("Recently done", session2.recently_done, false),
+    ...session2.truncated ? ["(Some sections were cut; run `listspace board <id>` for everything.)"] : []
+  ].join("\n");
+}
+function formatBoard(board) {
+  return [
+    `${board.title}  ${board.id}`,
+    board.url,
+    ...board.level === null ? [] : [`Agent ${levelText(board.level)}.`],
+    ...block("Guidance for agents (read first)", board.guidance),
+    ...block("Board instructions (follow these)", board.instructions),
+    ...board.lists.flatMap((list) => [
+      `${list.title}${list.kind === null ? "" : ` (${list.kind})`}  ${list.id}`,
+      ...list.cards.map((card) => `  - ${card.title}${card.due_date === null ? "" : ` (due ${card.due_date}${card.done ? ", done" : ""})`}  ${card.id}`)
+    ]),
+    ...board.truncated ? ["(Only the first 1,000 items are shown.)"] : []
+  ].join("\n");
+}
+function formatWrite(outcome, done) {
+  if (outcome.outcome === "suggested") {
+    return [
+      `Suggested, not made: ${outcome.message}`,
+      `It waits in the board's Inbox for the user to accept or reject (${levelText(outcome.level)}). Do not send it again.`,
+      `Suggestion ${outcome.suggestion.id}`
+    ].join("\n");
+  }
+  const undo = outcome.undo === null ? [] : [`Undo: listspace undo ${outcome.undo.request_id}`];
+  return [`${done} (${levelText(outcome.level)}).`, ...undo].join("\n");
+}
+function formatCreatedBoard(board) {
+  return [
+    `Created board "${board.title}"  ${board.id}`,
+    board.url,
+    `Lists: ${board.lists.map((list) => list.title).join(", ")}`,
+    ...block("Board instructions (follow these)", board.instructions),
+    ...board.undo === null ? [] : [`Undo: listspace undo ${board.undo.request_id}`]
+  ].join("\n");
+}
+function formatInbox(inbox2) {
+  if (inbox2.suggestions.length === 0) return "The Inbox is empty.";
+  return inbox2.suggestions.map((suggestion) => {
+    const target = [suggestion.item_title, suggestion.list_title].filter((part) => part !== null).join(" -> ");
+    const lines = [`${suggestion.status}: ${suggestion.action}${target === "" ? "" : ` ${target}`}  ${suggestion.id}`];
+    if (suggestion.reason !== null) lines.push(`  Reason: ${suggestion.reason}`);
+    lines.push(`  By ${suggestion.agent_name}, ${suggestion.created_at.slice(0, 10)}, expires ${suggestion.expires_at.slice(0, 10)}${suggestion.stale ? ", item changed since" : ""}`);
+    return lines.join("\n");
+  }).join("\n");
+}
+function formatUndo(result) {
+  if (result.outcome === "already_undone") return "Nothing left to undo: it was undone already.";
+  return `Undone (${result.undone.length} change${result.undone.length === 1 ? "" : "s"}).`;
+}
+function formatTaken(result) {
+  return [
+    `Taken: ${result.claimed_by.agent_name ?? "another app or assistant"} is working on this item until ${result.claimed_by.expires_at}.`,
+    result.message
+  ].join("\n");
+}
+function formatNext(result) {
+  switch (result.outcome) {
+    case "empty":
+      return `Nothing left: ${result.message}`;
+    case "claimed": {
+      const lines = [
+        `Claimed "${result.item.title}"  ${result.item.id}`,
+        result.item.url,
+        result.moved_to === null ? "Not moved." : `Moved to ${result.moved_to.list_title}.`,
+        `Claim runs out at ${result.expires_at} (${levelText(result.level)}); any write of yours on the item renews it.`
+      ];
+      if (result.note !== null) lines.push(`Note: ${result.note}`);
+      if (result.undo !== null) lines.push(`Undo the move: listspace undo ${result.undo.request_id}`);
+      lines.push(`When done: listspace release ${result.item.id}`);
+      return lines.join("\n");
+    }
+    default: {
+      const exhaustive = result;
+      return exhaustive;
+    }
+  }
+}
+function formatClaim(result) {
+  switch (result.outcome) {
+    case "claimed":
+    case "renewed":
+      return `${result.outcome === "claimed" ? "Claimed" : "Renewed"} ${result.item_id} until ${result.expires_at} (${levelText(result.level)}).`;
+    case "taken":
+      return formatTaken(result);
+    default: {
+      const exhaustive = result;
+      return exhaustive;
+    }
+  }
+}
+function formatRelease(result) {
+  switch (result.outcome) {
+    case "released":
+      return `Released ${result.item_id}.`;
+    case "not_claimed":
+      return `${result.item_id} had no claim to release.`;
+    case "taken":
+      return formatTaken(result);
+    default: {
+      const exhaustive = result;
+      return exhaustive;
+    }
+  }
+}
+
+// src/commands.ts
+var inboxFields = (choice) => {
+  switch (choice.kind) {
+    case "inbox":
+      return { inbox: true, reason: choice.reason };
+    case "direct":
+      return choice.reason === null ? {} : { reason: choice.reason };
+    default: {
+      const exhaustive = choice;
+      return exhaustive;
+    }
+  }
+};
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var path = (id) => encodeURIComponent(id);
+async function allBoards(client) {
+  const boards = [];
+  const raw = [];
+  let cursor;
+  for (let pageNumber = 0; pageNumber < 20; pageNumber += 1) {
+    const answer = await client.body("GET", "/boards", page(boardSummary), { query: { limit: 100, cursor } });
+    boards.push(...answer.value.data);
+    if (isRecord(answer.raw) && Array.isArray(answer.raw.data)) raw.push(...answer.raw.data);
+    if (answer.value.next_cursor === null) break;
+    cursor = answer.value.next_cursor;
+  }
+  return { boards, raw };
+}
+async function resolveBoardId(client, ref) {
+  if (UUID.test(ref)) return ref;
+  const { boards } = await allBoards(client);
+  const wanted = ref.trim().toLowerCase();
+  const exact = boards.filter((board) => board.title.toLowerCase() === wanted);
+  const matches = exact.length > 0 ? exact : boards.filter((board) => board.title.toLowerCase().startsWith(wanted));
+  const [first, ...others] = matches;
+  if (first === void 0) return fail({ kind: "usage", message: `No board called "${ref}". Run \`listspace boards\` to see them.` });
+  if (others.length > 0) {
+    return fail({ kind: "usage", message: `"${ref}" matches ${matches.length} boards: ${matches.map((b) => `${b.title} (${b.id})`).join(", ")}. Use the id.` });
+  }
+  return first.id;
+}
+function resolveList(board, ref) {
+  const wanted = ref.trim().toLowerCase();
+  const byId = board.lists.find((list) => list.id === ref);
+  if (byId !== void 0) return byId;
+  const byTitle = board.lists.filter((list) => list.title.toLowerCase() === wanted);
+  const kind = LIST_KINDS.find((candidate) => candidate === wanted);
+  const candidates = byTitle.length > 0 ? byTitle : kind === void 0 ? [] : board.lists.filter((list) => list.kind === kind);
+  const [first, ...others] = candidates;
+  const names = board.lists.map((list) => list.title).join(", ");
+  if (first === void 0) return fail({ kind: "usage", message: `No list "${ref}" on ${board.title}. Its lists: ${names}.` });
+  if (others.length > 0) {
+    return fail({ kind: "usage", message: `"${ref}" matches ${candidates.length} lists on ${board.title}: ${candidates.map((l) => l.title).join(", ")}. Use the title or id.` });
+  }
+  return first;
+}
+var getBoard = (client, boardId) => client.data("GET", `/boards/${path(boardId)}`, boardDetail);
+async function accountCommand(client) {
+  const answer = await client.data("GET", "/account", account);
+  return { raw: answer.raw, text: formatAccount(answer.value) };
+}
+async function boardsCommand(client) {
+  const { boards, raw } = await allBoards(client);
+  return { raw: { data: raw }, text: formatBoards(boards) };
+}
+async function sessionCommand(client, input) {
+  const boardId = await resolveBoardId(client, input.board);
+  const answer = await client.data("GET", `/boards/${path(boardId)}/session`, session);
+  return { raw: answer.raw, text: formatSession(answer.value) };
+}
+async function boardCommand(client, input) {
+  const boardId = await resolveBoardId(client, input.board);
+  const answer = await getBoard(client, boardId);
+  return { raw: answer.raw, text: formatBoard(answer.value) };
+}
+async function newBoardCommand(client, input) {
+  const body = input.description === null ? { title: input.title } : { title: input.title, description: input.description };
+  const answer = await client.data("POST", "/boards", createdBoard, { body });
+  return { raw: answer.raw, text: formatCreatedBoard(answer.value) };
+}
+async function addCommand(client, input) {
+  const boardId = await resolveBoardId(client, input.board);
+  const board = (await getBoard(client, boardId)).value;
+  const list = resolveList(board, input.list);
+  const body = {
+    list_id: list.id,
+    title: input.title,
+    ...input.description === null ? {} : { description: input.description, description_format: "markdown" },
+    ...inboxFields(input.choice)
+  };
+  const answer = await client.data("POST", "/items", writeOutcome, { body });
+  return { raw: answer.raw, text: formatWrite(answer.value, `Added "${input.title}" to ${list.title}`) };
+}
+async function moveTo(client, itemId, pickList, choice) {
+  const current = (await client.data("GET", `/items/${path(itemId)}`, item)).value;
+  const board = (await getBoard(client, current.board_id)).value;
+  const list = pickList(board);
+  const body = { list_id: list.id, position: "top", ...inboxFields(choice) };
+  const answer = await client.data("POST", `/items/${path(itemId)}/move`, writeOutcome, { body });
+  return { raw: answer.raw, text: formatWrite(answer.value, `Moved "${current.title}" to ${list.title}`) };
+}
+function moveCommand(client, input) {
+  return moveTo(client, input.item, (board) => resolveList(board, input.list), input.choice);
+}
+function doneCommand(client, input) {
+  return moveTo(
+    client,
+    input.item,
+    (board) => {
+      const doneList = board.lists.find((list) => list.kind === "done");
+      if (doneList === void 0) {
+        return fail({ kind: "usage", message: `${board.title} has no done list. Use \`listspace move <item> <list>\` instead.` });
+      }
+      return doneList;
+    },
+    input.choice
+  );
+}
+var INBOX_STATUSES = ["pending", "accepted", "rejected", "withdrawn", "expired", "failed", "all"];
+async function inboxCommand(client, input) {
+  const boardId = await resolveBoardId(client, input.board);
+  const answer = await client.data("GET", `/boards/${path(boardId)}/inbox`, inbox, { query: { status: input.status } });
+  return { raw: answer.raw, text: formatInbox(answer.value) };
+}
+async function undoCommand(client, input) {
+  const answer = await client.data("POST", `/activity/${path(input.requestId)}/undo`, undoResult);
+  return { raw: answer.raw, text: formatUndo(answer.value) };
+}
+function parseClaimMinutes(raw) {
+  if (!/^\d+$/.test(raw.trim())) return null;
+  const minutes = Number(raw.trim());
+  return minutes >= 5 && minutes <= 1440 ? minutes : null;
+}
+async function nextCommand(client, input) {
+  const boardId = await resolveBoardId(client, input.board);
+  const body = {
+    ...input.kinds.length === 0 ? {} : { kinds: input.kinds },
+    ...input.labelIds.length === 0 ? {} : { label_ids: input.labelIds },
+    move_to_doing: input.moveToDoing,
+    ...input.ttl === null ? {} : { ttl_minutes: input.ttl }
+  };
+  const answer = await client.data("POST", `/boards/${path(boardId)}/next`, nextResult, { body });
+  return { raw: answer.raw, text: formatNext(answer.value) };
+}
+async function claimCommand(client, input) {
+  const body = input.ttl === null ? {} : { ttl_minutes: input.ttl };
+  const answer = await client.data("POST", `/items/${path(input.item)}/claim`, claimResult, { body });
+  return { raw: answer.raw, text: formatClaim(answer.value) };
+}
+async function releaseCommand(client, input) {
+  const answer = await client.data("DELETE", `/items/${path(input.item)}/claim`, releaseResult);
+  return { raw: answer.raw, text: formatRelease(answer.value) };
+}
+
+// src/config.ts
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function configDir(env, platform = process.platform, home = homedir()) {
+  const override = env.LISTSPACE_CONFIG_DIR;
+  if (override !== void 0 && override !== "") return override;
+  if (platform === "win32") return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "listspace");
+  if (platform === "darwin") return join(home, "Library", "Application Support", "listspace");
+  const xdg = env.XDG_CONFIG_HOME;
+  return join(xdg !== void 0 && xdg !== "" ? xdg : join(home, ".config"), "listspace");
+}
+var credentialsPath = (dir) => join(dir, "credentials.json");
+async function loadToken(env, dir) {
+  const fromEnv = env.LISTSPACE_TOKEN;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    const token2 = parseToken(fromEnv);
+    return token2 === null ? { kind: "invalid", where: "LISTSPACE_TOKEN" } : { kind: "env", token: token2 };
+  }
+  const path2 = credentialsPath(dir);
+  let text;
+  try {
+    text = await readFile(path2, "utf8");
+  } catch {
+    return { kind: "none" };
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return { kind: "invalid", where: path2 };
+  }
+  if (!isRecord(json) || typeof json.token !== "string") return { kind: "invalid", where: path2 };
+  const token = parseToken(json.token);
+  return token === null ? { kind: "invalid", where: path2 } : { kind: "file", token, path: path2 };
+}
+async function saveToken(dir, token) {
+  await mkdir(dir, { recursive: true, mode: 448 });
+  const path2 = credentialsPath(dir);
+  await writeFile(path2, `${JSON.stringify({ token, saved_at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
+`, { mode: 384 });
+  await chmod(path2, 384);
+  return path2;
+}
+async function removeToken(dir) {
+  const path2 = credentialsPath(dir);
+  try {
+    await readFile(path2);
+  } catch {
+    return false;
+  }
+  await rm(path2);
+  return true;
+}
+
+// src/cli.ts
+var HELP = `listspace ${VERSION}: ListSpace from the command line, for people and coding agents.
+
+Usage: listspace <command> [arguments] [--json]
+
+Sign in
+  login [--token ls_...]    Save a personal token (ListSpace: Settings > API).
+                            Without --token it reads the token from stdin.
+  logout                    Forget the saved token.
+  whoami                    Plan, freedom levels, guidance and boards (alias: account).
+
+Read
+  boards                    Your boards with their ids.
+  session <board>           Start a work session: guidance, board instructions,
+                            level, open work. Run this first.
+  board <board>             Lists and items with their ids.
+  inbox <board> [--status pending|accepted|rejected|withdrawn|expired|failed|all]
+
+Write (the board's freedom level decides what is made and what waits in the Inbox)
+  new-board <title> [--description <text>]   A board from "Project (for agents)".
+  add <board> <list> <title> [--description <markdown>]
+  move <item> <list>
+  done <item>               Move to the board's done list.
+  undo <request_id>         Take back one of your own calls.
+  Writes take --inbox --reason "<why>" to suggest instead of change.
+
+Work on your own (needs level 4, Act; other agents leave a claimed item alone)
+  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
+                            Claim the top open item no one is working on and
+                            move it to Doing. --kinds: lists to take from, in
+                            order (default todo, then backlog). --label: only
+                            items with this label (repeat or comma list).
+                            --no-move: leave it in its list.
+  claim <item> [--ttl <minutes>]   Claim an item, or renew your claim.
+  release <item>            Release your claim when you stop (done or not).
+  A claim lasts --ttl minutes (5 to 1440, default 120); any write of yours on
+  the item renews it.
+
+<board> is an id or a title, <list> an id, a title or a kind (todo, doing, done,
+info, capture, backlog), <item> an item id.
+
+Options
+  --json      Print the API's JSON (for agents and scripts).
+  --help      This help.  --version  The version.
+
+Environment
+  LISTSPACE_TOKEN        A token for this run (wins over the saved one).
+  LISTSPACE_API_URL      Default ${DEFAULT_API_URL}
+  LISTSPACE_CONFIG_DIR   Where credentials.json is kept.
+
+Exit codes: 0 ok, 1 failed, 2 usage, 3 sign in needed, 4 rate limited (wait and retry).`;
+var EXIT = {
+  usage: 2,
+  auth: 3,
+  rate_limited: 4,
+  api: 1,
+  network: 1,
+  unexpected: 1
+};
+var OPTIONS = {
+  json: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+  token: { type: "string" },
+  description: { type: "string" },
+  inbox: { type: "boolean" },
+  reason: { type: "string" },
+  status: { type: "string" },
+  kinds: { type: "string" },
+  label: { type: "string", multiple: true },
+  "no-move": { type: "boolean" },
+  ttl: { type: "string" }
+};
+var usage = (message) => fail({ kind: "usage", message: `${message} Run \`listspace --help\`.` });
+function positionals(command, given, names) {
+  if (given.length !== names.length) {
+    const wanted = names.length === 0 ? "no arguments" : names.map((name) => `<${name}>`).join(" ");
+    usage(`\`${command}\` takes ${wanted}${given.length > names.length && names.length > 0 ? " (quote text with spaces)" : ""}.`);
+  }
+  return [...given];
+}
+function choiceFrom(flags) {
+  const reason = flags.reason ?? null;
+  if (reason !== null && reason.length > 500) usage("--reason is at most 500 characters.");
+  if (flags.inbox === true) {
+    if (reason === null || reason.trim() === "") return usage('--inbox needs --reason "<why>": the user reads it when deciding.');
+    return { kind: "inbox", reason };
+  }
+  return { kind: "direct", reason };
+}
+function ttlFrom(flags) {
+  if (flags.ttl === void 0) return null;
+  const minutes = parseClaimMinutes(flags.ttl);
+  if (minutes === null) return usage("--ttl is a whole number of minutes from 5 to 1440.");
+  return minutes;
+}
+function kindsFrom(flags) {
+  if (flags.kinds === void 0) return [];
+  const kinds = [];
+  for (const part of flags.kinds.split(",")) {
+    const wanted = part.trim().toLowerCase();
+    const kind = LIST_KINDS.find((candidate) => candidate === wanted);
+    if (kind === void 0) return usage(`--kinds takes a comma list of ${LIST_KINDS.join(", ")}; "${part.trim()}" is not one.`);
+    if (!kinds.includes(kind)) kinds.push(kind);
+  }
+  return kinds;
+}
+var labelsFrom = (flags) => [
+  ...new Set((flags.label ?? []).flatMap((value) => value.split(",")).map((id) => id.trim()).filter((id) => id !== ""))
+];
+async function clientFor(io, dir) {
+  const source = await loadToken(io.env, dir);
+  switch (source.kind) {
+    case "env":
+    case "file":
+      return new ApiClient({ baseUrl: apiUrl(io.env), token: source.token, fetch: io.fetch });
+    case "none":
+      return fail({ kind: "auth", message: `Not signed in. ${LOGIN_HINT}` });
+    case "invalid":
+      return fail({ kind: "auth", message: `The token in ${source.where} is not a ListSpace token (ls_ and 43 characters). ${LOGIN_HINT}` });
+    default: {
+      const exhaustive = source;
+      return exhaustive;
+    }
+  }
+}
+var apiUrl = (env) => {
+  const url = env.LISTSPACE_API_URL;
+  return url !== void 0 && url !== "" ? url : DEFAULT_API_URL;
+};
+async function loginMethod(flags, io) {
+  if (flags.token !== void 0) return { kind: "token", raw: flags.token };
+  const typed = await io.readSecret("Paste a personal token from ListSpace (Settings > API): ");
+  if (typed === null || typed.trim() === "") return { kind: "pairing" };
+  return { kind: "token", raw: typed };
+}
+async function login(flags, io, dir) {
+  const method = await loginMethod(flags, io);
+  if (method.kind === "pairing") {
+    return usage("No token given. Pass --token ls_... or pipe one in (signing in from the browser comes later).");
+  }
+  const token = parseToken(method.raw);
+  if (token === null) return usage("That is not a ListSpace token: it starts with ls_ and has 43 more characters.");
+  const client = new ApiClient({ baseUrl: apiUrl(io.env), token, fetch: io.fetch });
+  const answer = await client.data("GET", "/account", account);
+  const path2 = await saveToken(dir, token);
+  const text = [`Signed in (plan ${answer.value.plan.name}, ${answer.value.boards.length} boards). Token saved in ${path2}.`];
+  if (io.env.LISTSPACE_TOKEN !== void 0 && io.env.LISTSPACE_TOKEN !== "") text.push("Note: LISTSPACE_TOKEN is set and wins over the saved token.");
+  return { raw: { signed_in: true, path: path2 }, text: text.join("\n") };
+}
+async function dispatch(command, args, flags, io, dir) {
+  switch (command) {
+    case "login":
+      positionals(command, args, []);
+      return login(flags, io, dir);
+    case "logout": {
+      positionals(command, args, []);
+      const removed = await removeToken(dir);
+      return { raw: { signed_out: removed }, text: removed ? "Signed out: the saved token is gone (revoke it in Settings > API if it leaked)." : "No saved token." };
+    }
+    case "whoami":
+    case "account":
+      positionals(command, args, []);
+      return accountCommand(await clientFor(io, dir));
+    case "boards":
+      positionals(command, args, []);
+      return boardsCommand(await clientFor(io, dir));
+    case "session": {
+      const [board] = positionals(command, args, ["board"]);
+      return sessionCommand(await clientFor(io, dir), { board });
+    }
+    case "board": {
+      const [board] = positionals(command, args, ["board"]);
+      return boardCommand(await clientFor(io, dir), { board });
+    }
+    case "new-board": {
+      const [title] = positionals(command, args, ["title"]);
+      return newBoardCommand(await clientFor(io, dir), { title, description: flags.description ?? null });
+    }
+    case "add": {
+      const [board, list, title] = positionals(command, args, ["board", "list", "title"]);
+      const choice = choiceFrom(flags);
+      return addCommand(await clientFor(io, dir), { board, list, title, description: flags.description ?? null, choice });
+    }
+    case "move": {
+      const [item2, list] = positionals(command, args, ["item", "list"]);
+      const choice = choiceFrom(flags);
+      return moveCommand(await clientFor(io, dir), { item: item2, list, choice });
+    }
+    case "done": {
+      const [item2] = positionals(command, args, ["item"]);
+      const choice = choiceFrom(flags);
+      return doneCommand(await clientFor(io, dir), { item: item2, choice });
+    }
+    case "inbox": {
+      const [board] = positionals(command, args, ["board"]);
+      const wanted = flags.status ?? "pending";
+      const status = INBOX_STATUSES.find((candidate) => candidate === wanted);
+      if (status === void 0) return usage(`--status is one of ${INBOX_STATUSES.join(", ")}.`);
+      return inboxCommand(await clientFor(io, dir), { board, status });
+    }
+    case "next": {
+      const [board] = positionals(command, args, ["board"]);
+      const input = { board, kinds: kindsFrom(flags), labelIds: labelsFrom(flags), moveToDoing: flags["no-move"] !== true, ttl: ttlFrom(flags) };
+      return nextCommand(await clientFor(io, dir), input);
+    }
+    case "claim": {
+      const [item2] = positionals(command, args, ["item"]);
+      const ttl = ttlFrom(flags);
+      return claimCommand(await clientFor(io, dir), { item: item2, ttl });
+    }
+    case "release": {
+      const [item2] = positionals(command, args, ["item"]);
+      return releaseCommand(await clientFor(io, dir), { item: item2 });
+    }
+    case "undo": {
+      const [requestId] = positionals(command, args, ["request_id"]);
+      return undoCommand(await clientFor(io, dir), { requestId });
+    }
+    default:
+      return usage(`Unknown command "${command}".`);
+  }
+}
+async function run(argv, io) {
+  let json = argv.includes("--json");
+  try {
+    let parsed;
+    try {
+      parsed = parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true });
+    } catch (error) {
+      return usage(error instanceof Error ? error.message : String(error));
+    }
+    const flags = parsed.values;
+    json = flags.json === true;
+    const [command, ...args] = parsed.positionals;
+    if (flags.version === true) {
+      io.stdout(json ? JSON.stringify({ version: VERSION }) : VERSION);
+      return 0;
+    }
+    if (command === void 0 || command === "help" || flags.help === true) {
+      io.stdout(HELP);
+      return 0;
+    }
+    const dir = io.configDir ?? configDir(io.env);
+    const output = await dispatch(command, args, flags, io, dir);
+    io.stdout(json ? JSON.stringify(output.raw, null, 2) : output.text);
+    return 0;
+  } catch (error) {
+    if (!(error instanceof CliFailure)) throw error;
+    const failure = error.error;
+    if (json) {
+      io.stdout(JSON.stringify({ error: errorJson(failure) }, null, 2));
+    } else {
+      io.stderr(`listspace: ${failure.message}`);
+    }
+    return EXIT[failure.kind];
+  }
+}
+function errorJson(error) {
+  switch (error.kind) {
+    case "api":
+      return { kind: error.kind, status: error.status, code: error.code, message: error.message };
+    case "rate_limited":
+      return { kind: error.kind, message: error.message, retry_after_seconds: error.retryAfterSeconds };
+    case "usage":
+    case "auth":
+    case "network":
+    case "unexpected":
+      return { kind: error.kind, message: error.message };
+    default: {
+      const exhaustive = error;
+      return exhaustive;
+    }
+  }
+}
+
+// src/main.ts
+async function readSecret(prompt) {
+  if (process.stdin.isTTY) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      return await rl.question(prompt);
+    } finally {
+      rl.close();
+    }
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  return text === "" ? null : text;
+}
+var code = await run(process.argv.slice(2), {
+  env: process.env,
+  fetch: (url, init) => fetch(url, init),
+  stdout: (text) => process.stdout.write(`${text}
+`),
+  stderr: (text) => process.stderr.write(`${text}
+`),
+  readSecret
+});
+process.exitCode = code;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "listspace",
+  "version": "0.1.0",
+  "description": "ListSpace from the command line: the agentic project memory, for people and coding agents.",
+  "keywords": [
+    "listspace",
+    "cli",
+    "ai-agents",
+    "project-memory",
+    "kanban",
+    "boards",
+    "mcp",
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "homepage": "https://listspace.app/docs/agents",
+  "bugs": {
+    "url": "https://github.com/listspace/agent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/listspace/agent.git",
+    "directory": "cli"
+  },
+  "license": "MIT",
+  "author": "Sjenkie B.V. (Yellow House Digital)",
+  "type": "module",
+  "bin": {
+    "listspace": "dist/listspace.mjs"
+  },
+  "files": [
+    "dist/listspace.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/listspace.mjs --banner:js=\"#!/usr/bin/env node\"",
+    "typecheck": "tsc --noEmit",
+    "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",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "esbuild": "0.25.5",
+    "typescript": "5.8.3"
+  }
+}