listspace 0.1.0 → 0.2.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 ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ One version runs through the CLI, the skill and the Claude Code plugin, so each entry covers all three.
4
+
5
+ ## 0.2.0
6
+
7
+ - New command `listspace attach <item> <file> [<file>...]`: uploads files from your computer to an item through the REST API, so an agent no longer has to write a file out as base64. The type comes from the extension (the same types the app accepts; Markdown goes up as plain text), and every file is checked before the first upload: known type, present, not empty, at most 8 MB. `--json` prints one server answer per file. Needs level 4 (Act) on the board.
8
+ - The skill tells agents to use `listspace attach` for local files instead of `attach_file` with base64, and has a new reference page, `reference/files.md`.
9
+
10
+ ## 0.1.1
11
+
12
+ - The name is written Listspace everywhere: in the CLI's help, its messages and its README, and in the skill and the plugin.
13
+ - Spaces: the skill describes `list_spaces`, `create_space` and `update_space`, and `space_id` on boards (`list_boards`, `create_board`, `update_board`).
14
+ - Important items: the skill describes `list_important_items`, everything the user marked important, grouped by board.
15
+ - Link previews: the skill describes `link_previews` in `get_item` (title, image and site, and for books the ISBN, authors and summary).
16
+
17
+ ## 0.1.0
18
+
19
+ - First release: sign in with a personal token, read boards, sessions and the Inbox, add items and move them (also to the done list), work through a board with `next`, `claim` and `release`, and undo your own calls.
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`).
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 > API**, then save it:
23
+ Create a personal token in Listspace under **Settings > API**, 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 > API).
41
+ login [--token ls_...] Save a personal token (Listspace: Settings > API).
42
42
  logout Forget the saved token.
43
43
  whoami Plan, freedom levels, guidance and boards (alias: account).
44
44
 
@@ -57,6 +57,9 @@ Write (the board's freedom level decides what is made and what waits in the Inbo
57
57
  undo <request_id> Take back one of your own calls.
58
58
  Writes take --inbox --reason "<why>" to suggest instead of change.
59
59
 
60
+ Files from this computer (needs level 4, Act)
61
+ attach <item> <file> [<file>...] At most 8 MB each.
62
+
60
63
  Work on your own (needs level 4, Act)
61
64
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
62
65
  claim <item> [--ttl <minutes>]
@@ -72,6 +75,16 @@ npx listspace session "Website"
72
75
  npx listspace add "Website" ideas "Try dark mode" --description "Seen in **settings**"
73
76
  ```
74
77
 
78
+ ## Attach files
79
+
80
+ `attach` uploads files from your computer to an item, one after another:
81
+
82
+ ```bash
83
+ npx listspace attach 2b6f0c1e-... ./contract.pdf ./screenshots/footer.png
84
+ ```
85
+
86
+ 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.
87
+
75
88
  ## Output for agents and scripts
76
89
 
77
90
  Every command takes `--json` and then prints the API's JSON instead of text:
@@ -9,11 +9,13 @@ import { parseArgs } from "node:util";
9
9
  // src/decode.ts
10
10
  var DecodeError = class extends Error {
11
11
  constructor(path2, expected) {
12
- super(`Unexpected response from ListSpace: ${path2} should be ${expected}.`);
12
+ super(`Unexpected response from Listspace: ${path2} should be ${expected}.`);
13
13
  this.path = path2;
14
14
  this.expected = expected;
15
15
  this.name = "DecodeError";
16
16
  }
17
+ path;
18
+ expected;
17
19
  };
18
20
  function isRecord(value) {
19
21
  return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -207,9 +209,21 @@ function page(entry) {
207
209
  return object({ data: array(entry), next_cursor: nullable(string) });
208
210
  }
209
211
  var errorBody = object({ error: object({ code: string, message: string }) });
212
+ var attached = object({
213
+ outcome: literal("applied"),
214
+ level,
215
+ attachment: object({
216
+ id: string,
217
+ item_id: string,
218
+ filename: string,
219
+ mime_type: nullable(string),
220
+ size_bytes: nullable(number),
221
+ url: string
222
+ })
223
+ });
210
224
 
211
225
  // src/version.ts
212
- var VERSION = "0.1.0";
226
+ var VERSION = "0.2.0";
213
227
 
214
228
  // src/api.ts
215
229
  var DEFAULT_API_URL = "https://api.listspace.app/v1";
@@ -224,19 +238,21 @@ var CliFailure = class extends Error {
224
238
  this.error = error;
225
239
  this.name = "CliFailure";
226
240
  }
241
+ error;
227
242
  };
228
243
  var fail = (error) => {
229
244
  throw new CliFailure(error);
230
245
  };
231
- var LOGIN_HINT = "Run `listspace login` with a personal token (ListSpace: Settings > API), or set LISTSPACE_TOKEN.";
246
+ var LOGIN_HINT = "Run `listspace login` with a personal token (Listspace: Settings > API), or set LISTSPACE_TOKEN.";
232
247
  var ApiClient = class {
233
248
  constructor(options) {
234
249
  this.options = options;
235
250
  }
251
+ options;
236
252
  /** Sends one request and decodes `data` from the answer. */
237
253
  async data(method, path2, decoder, init = {}) {
238
254
  const json = await this.send(method, path2, init);
239
- if (!isRecord(json) || !("data" in json)) return fail({ kind: "unexpected", message: "Unexpected response from ListSpace: no data." });
255
+ if (!isRecord(json) || !("data" in json)) return fail({ kind: "unexpected", message: "Unexpected response from Listspace: no data." });
240
256
  return { value: decodeOrFail(decoder, json.data, "data"), raw: json.data };
241
257
  }
242
258
  /** Sends one request and decodes the whole body (list endpoints with next_cursor). */
@@ -263,7 +279,7 @@ var ApiClient = class {
263
279
  );
264
280
  } catch (cause) {
265
281
  const reason = cause instanceof Error ? cause.message : String(cause);
266
- return fail({ kind: "network", message: `Could not reach ListSpace at ${url.origin}: ${reason}` });
282
+ return fail({ kind: "network", message: `Could not reach Listspace at ${url.origin}: ${reason}` });
267
283
  }
268
284
  const text = await response.text();
269
285
  let json = null;
@@ -271,7 +287,7 @@ var ApiClient = class {
271
287
  try {
272
288
  json = JSON.parse(text);
273
289
  } catch {
274
- if (response.ok) return fail({ kind: "unexpected", message: `ListSpace answered ${response.status} with something that is not JSON.` });
290
+ if (response.ok) return fail({ kind: "unexpected", message: `Listspace answered ${response.status} with something that is not JSON.` });
275
291
  }
276
292
  }
277
293
  if (response.ok) return json;
@@ -288,7 +304,7 @@ function decodeOrFail(decoder, value, path2) {
288
304
  }
289
305
  function errorFor(response, json) {
290
306
  let code2 = "unknown";
291
- let message = `ListSpace answered ${response.status}.`;
307
+ let message = `Listspace answered ${response.status}.`;
292
308
  try {
293
309
  const parsed = errorBody(json, "body");
294
310
  code2 = parsed.error.code;
@@ -308,6 +324,80 @@ function errorFor(response, json) {
308
324
  return { kind: "api", status: response.status, code: code2, message };
309
325
  }
310
326
 
327
+ // src/files.ts
328
+ import { readFile, stat } from "node:fs/promises";
329
+ var MAX_FILE_BYTES = 8 * 1024 * 1024;
330
+ var TYPES = {
331
+ jpg: "image/jpeg",
332
+ jpeg: "image/jpeg",
333
+ png: "image/png",
334
+ gif: "image/gif",
335
+ webp: "image/webp",
336
+ svg: "image/svg+xml",
337
+ pdf: "application/pdf",
338
+ txt: "text/plain",
339
+ md: "text/plain",
340
+ markdown: "text/plain",
341
+ csv: "text/csv",
342
+ doc: "application/msword",
343
+ docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
344
+ xls: "application/vnd.ms-excel",
345
+ xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
346
+ ppt: "application/vnd.ms-powerpoint",
347
+ pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
348
+ zip: "application/zip",
349
+ rar: "application/x-rar-compressed",
350
+ "7z": "application/x-7z-compressed",
351
+ mp3: "audio/mpeg",
352
+ wav: "audio/wav",
353
+ ogg: "audio/ogg",
354
+ mp4: "video/mp4",
355
+ mpeg: "video/mpeg",
356
+ mpg: "video/mpeg",
357
+ mov: "video/quicktime",
358
+ json: "application/json",
359
+ js: "application/javascript",
360
+ html: "text/html",
361
+ htm: "text/html",
362
+ css: "text/css"
363
+ };
364
+ var ATTACHABLE_EXTENSIONS = Object.keys(TYPES);
365
+ function fileNameOf(path2) {
366
+ return path2.split(/[\\/]/).filter((part) => part !== "").pop() ?? path2;
367
+ }
368
+ function mimeTypeFor(fileName) {
369
+ const dot = fileName.lastIndexOf(".");
370
+ if (dot <= 0 || dot === fileName.length - 1) return null;
371
+ return TYPES[fileName.slice(dot + 1).toLowerCase()] ?? null;
372
+ }
373
+ async function readLocalFile(path2, maxBytes) {
374
+ let size;
375
+ try {
376
+ const info = await stat(path2);
377
+ if (!info.isFile()) return { kind: "not_a_file" };
378
+ size = info.size;
379
+ } catch (error) {
380
+ if (isErrnoCode(error, "ENOENT")) return { kind: "missing" };
381
+ return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
382
+ }
383
+ if (size > maxBytes) return { kind: "too_large", sizeBytes: size };
384
+ try {
385
+ const bytes = await readFile(path2);
386
+ if (bytes.length > maxBytes) return { kind: "too_large", sizeBytes: bytes.length };
387
+ return { kind: "ok", bytes };
388
+ } catch (error) {
389
+ return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
390
+ }
391
+ }
392
+ function isErrnoCode(error, code2) {
393
+ return typeof error === "object" && error !== null && "code" in error && error.code === code2;
394
+ }
395
+ function formatSize(bytes) {
396
+ if (bytes < 1024) return `${bytes} bytes`;
397
+ if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
398
+ return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
399
+ }
400
+
311
401
  // src/format.ts
312
402
  var levelText = (level2) => `level ${level2.effective} (${level2.name})`;
313
403
  function block(title, text) {
@@ -463,6 +553,12 @@ function formatRelease(result) {
463
553
  }
464
554
  }
465
555
  }
556
+ function formatAttached(results) {
557
+ return results.map(({ attachment, level: level2 }) => {
558
+ const size = attachment.size_bytes === null ? "" : ` (${formatSize(attachment.size_bytes)})`;
559
+ return `Attached "${attachment.filename}"${size} to ${attachment.item_id} ${attachment.id} (${levelText(level2)}).`;
560
+ }).join("\n");
561
+ }
466
562
 
467
563
  // src/commands.ts
468
564
  var inboxFields = (choice) => {
@@ -617,9 +713,58 @@ async function releaseCommand(client, input) {
617
713
  const answer = await client.data("DELETE", `/items/${path(input.item)}/claim`, releaseResult);
618
714
  return { raw: answer.raw, text: formatRelease(answer.value) };
619
715
  }
716
+ async function prepareFiles(paths, read) {
717
+ const out = [];
718
+ for (const filePath of paths) {
719
+ const fileName = fileNameOf(filePath);
720
+ if (fileName.length > 255) return fail({ kind: "usage", message: `${fileName}: the file name is longer than 255 characters. Rename it first.` });
721
+ const mimeType = mimeTypeFor(fileName);
722
+ if (mimeType === null) {
723
+ return fail({ kind: "usage", message: `${fileName}: this type of file cannot be attached. Allowed: ${ATTACHABLE_EXTENSIONS.join(", ")}.` });
724
+ }
725
+ const file = await read(filePath, MAX_FILE_BYTES);
726
+ switch (file.kind) {
727
+ case "ok":
728
+ if (file.bytes.length === 0) return fail({ kind: "usage", message: `${filePath} is empty.` });
729
+ out.push({ path: filePath, fileName, mimeType, bytes: file.bytes });
730
+ break;
731
+ case "missing":
732
+ return fail({ kind: "usage", message: `${filePath}: no such file.` });
733
+ case "not_a_file":
734
+ return fail({ kind: "usage", message: `${filePath} is a folder, not a file.` });
735
+ case "too_large":
736
+ 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.` });
737
+ case "unreadable":
738
+ return fail({ kind: "unexpected", message: `Could not read ${filePath}: ${file.reason}` });
739
+ default: {
740
+ const exhaustive = file;
741
+ return exhaustive;
742
+ }
743
+ }
744
+ }
745
+ return out;
746
+ }
747
+ async function attachCommand(client, input) {
748
+ if (!UUID.test(input.item)) return fail({ kind: "usage", message: `"${input.item}" is not an item id. Item ids come from \`listspace board <board>\`.` });
749
+ const results = [];
750
+ const raw = [];
751
+ for (const file of input.files) {
752
+ const body = { filename: file.fileName, mime_type: file.mimeType, content_base64: Buffer.from(file.bytes).toString("base64") };
753
+ try {
754
+ const answer = await client.data("POST", `/items/${path(input.item)}/attachments`, attached, { body });
755
+ results.push(answer.value);
756
+ raw.push(answer.raw);
757
+ } catch (error) {
758
+ if (!(error instanceof CliFailure) || results.length === 0) throw error;
759
+ const done = results.map((result) => result.attachment.filename).join(", ");
760
+ throw new CliFailure({ ...error.error, message: `Attached ${done}; ${file.fileName} and the rest were not: ${error.error.message}` });
761
+ }
762
+ }
763
+ return { raw: { data: raw }, text: formatAttached(results) };
764
+ }
620
765
 
621
766
  // src/config.ts
622
- import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
767
+ import { chmod, mkdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
623
768
  import { homedir } from "node:os";
624
769
  import { join } from "node:path";
625
770
  function configDir(env, platform = process.platform, home = homedir()) {
@@ -640,7 +785,7 @@ async function loadToken(env, dir) {
640
785
  const path2 = credentialsPath(dir);
641
786
  let text;
642
787
  try {
643
- text = await readFile(path2, "utf8");
788
+ text = await readFile2(path2, "utf8");
644
789
  } catch {
645
790
  return { kind: "none" };
646
791
  }
@@ -665,7 +810,7 @@ async function saveToken(dir, token) {
665
810
  async function removeToken(dir) {
666
811
  const path2 = credentialsPath(dir);
667
812
  try {
668
- await readFile(path2);
813
+ await readFile2(path2);
669
814
  } catch {
670
815
  return false;
671
816
  }
@@ -674,12 +819,12 @@ async function removeToken(dir) {
674
819
  }
675
820
 
676
821
  // src/cli.ts
677
- var HELP = `listspace ${VERSION}: ListSpace from the command line, for people and coding agents.
822
+ var HELP = `listspace ${VERSION}: Listspace from the command line, for people and coding agents.
678
823
 
679
824
  Usage: listspace <command> [arguments] [--json]
680
825
 
681
826
  Sign in
682
- login [--token ls_...] Save a personal token (ListSpace: Settings > API).
827
+ login [--token ls_...] Save a personal token (Listspace: Settings > API).
683
828
  Without --token it reads the token from stdin.
684
829
  logout Forget the saved token.
685
830
  whoami Plan, freedom levels, guidance and boards (alias: account).
@@ -699,6 +844,12 @@ Write (the board's freedom level decides what is made and what waits in the Inbo
699
844
  undo <request_id> Take back one of your own calls.
700
845
  Writes take --inbox --reason "<why>" to suggest instead of change.
701
846
 
847
+ Files from this computer (needs level 4, Act; a file cannot wait in the Inbox)
848
+ attach <item> <file> [<file>...]
849
+ Upload files to an item, at most 8 MB each:
850
+ images, PDF, Office files, text, Markdown, CSV,
851
+ JSON, archives, audio and video.
852
+
702
853
  Work on your own (needs level 4, Act; other agents leave a claimed item alone)
703
854
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
704
855
  Claim the top open item no one is working on and
@@ -792,7 +943,7 @@ async function clientFor(io, dir) {
792
943
  case "none":
793
944
  return fail({ kind: "auth", message: `Not signed in. ${LOGIN_HINT}` });
794
945
  case "invalid":
795
- return fail({ kind: "auth", message: `The token in ${source.where} is not a ListSpace token (ls_ and 43 characters). ${LOGIN_HINT}` });
946
+ return fail({ kind: "auth", message: `The token in ${source.where} is not a Listspace token (ls_ and 43 characters). ${LOGIN_HINT}` });
796
947
  default: {
797
948
  const exhaustive = source;
798
949
  return exhaustive;
@@ -805,7 +956,7 @@ var apiUrl = (env) => {
805
956
  };
806
957
  async function loginMethod(flags, io) {
807
958
  if (flags.token !== void 0) return { kind: "token", raw: flags.token };
808
- const typed = await io.readSecret("Paste a personal token from ListSpace (Settings > API): ");
959
+ const typed = await io.readSecret("Paste a personal token from Listspace (Settings > API): ");
809
960
  if (typed === null || typed.trim() === "") return { kind: "pairing" };
810
961
  return { kind: "token", raw: typed };
811
962
  }
@@ -815,7 +966,7 @@ async function login(flags, io, dir) {
815
966
  return usage("No token given. Pass --token ls_... or pipe one in (signing in from the browser comes later).");
816
967
  }
817
968
  const token = parseToken(method.raw);
818
- if (token === null) return usage("That is not a ListSpace token: it starts with ls_ and has 43 more characters.");
969
+ if (token === null) return usage("That is not a Listspace token: it starts with ls_ and has 43 more characters.");
819
970
  const client = new ApiClient({ baseUrl: apiUrl(io.env), token, fetch: io.fetch });
820
971
  const answer = await client.data("GET", "/account", account);
821
972
  const path2 = await saveToken(dir, token);
@@ -888,6 +1039,13 @@ async function dispatch(command, args, flags, io, dir) {
888
1039
  const [item2] = positionals(command, args, ["item"]);
889
1040
  return releaseCommand(await clientFor(io, dir), { item: item2 });
890
1041
  }
1042
+ case "attach": {
1043
+ const [item2, ...paths] = args;
1044
+ if (item2 === void 0 || paths.length === 0) return usage("`attach` takes <item> and one or more files.");
1045
+ if (flags.inbox === true) return usage("A file cannot wait in the Inbox: attaching needs level 4 (Act) on the board.");
1046
+ const files = await prepareFiles(paths, io.readFile);
1047
+ return attachCommand(await clientFor(io, dir), { item: item2, files });
1048
+ }
891
1049
  case "undo": {
892
1050
  const [requestId] = positionals(command, args, ["request_id"]);
893
1051
  return undoCommand(await clientFor(io, dir), { requestId });
@@ -971,6 +1129,7 @@ var code = await run(process.argv.slice(2), {
971
1129
  `),
972
1130
  stderr: (text) => process.stderr.write(`${text}
973
1131
  `),
974
- readSecret
1132
+ readSecret,
1133
+ readFile: readLocalFile
975
1134
  });
976
1135
  process.exitCode = code;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "listspace",
3
- "version": "0.1.0",
4
- "description": "ListSpace from the command line: the agentic project memory, for people and coding agents.",
3
+ "version": "0.2.0",
4
+ "description": "Listspace from the command line: the agentic project memory, for people and coding agents.",
5
5
  "keywords": [
6
6
  "listspace",
7
7
  "cli",
@@ -32,6 +32,7 @@
32
32
  "files": [
33
33
  "dist/listspace.mjs",
34
34
  "README.md",
35
+ "CHANGELOG.md",
35
36
  "LICENSE"
36
37
  ],
37
38
  "engines": {
@@ -40,12 +41,12 @@
40
41
  "scripts": {
41
42
  "build": "esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/listspace.mjs --banner:js=\"#!/usr/bin/env node\"",
42
43
  "typecheck": "tsc --noEmit",
43
- "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",
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
45
  "prepublishOnly": "npm run typecheck && npm test && npm run build"
45
46
  },
46
47
  "devDependencies": {
47
48
  "@types/node": "20.19.43",
48
- "esbuild": "0.25.5",
49
- "typescript": "5.8.3"
49
+ "esbuild": "0.28.2",
50
+ "typescript": "5.9.3"
50
51
  }
51
52
  }