listspace 0.1.1 → 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 CHANGED
@@ -2,6 +2,11 @@
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.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
+
5
10
  ## 0.1.1
6
11
 
7
12
  - The name is written Listspace everywhere: in the CLI's help, its messages and its README, and in the skill and the plugin.
package/README.md CHANGED
@@ -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:
@@ -209,9 +209,21 @@ function page(entry) {
209
209
  return object({ data: array(entry), next_cursor: nullable(string) });
210
210
  }
211
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
+ });
212
224
 
213
225
  // src/version.ts
214
- var VERSION = "0.1.1";
226
+ var VERSION = "0.2.0";
215
227
 
216
228
  // src/api.ts
217
229
  var DEFAULT_API_URL = "https://api.listspace.app/v1";
@@ -312,6 +324,80 @@ function errorFor(response, json) {
312
324
  return { kind: "api", status: response.status, code: code2, message };
313
325
  }
314
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
+
315
401
  // src/format.ts
316
402
  var levelText = (level2) => `level ${level2.effective} (${level2.name})`;
317
403
  function block(title, text) {
@@ -467,6 +553,12 @@ function formatRelease(result) {
467
553
  }
468
554
  }
469
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
+ }
470
562
 
471
563
  // src/commands.ts
472
564
  var inboxFields = (choice) => {
@@ -621,9 +713,58 @@ async function releaseCommand(client, input) {
621
713
  const answer = await client.data("DELETE", `/items/${path(input.item)}/claim`, releaseResult);
622
714
  return { raw: answer.raw, text: formatRelease(answer.value) };
623
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
+ }
624
765
 
625
766
  // src/config.ts
626
- import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
767
+ import { chmod, mkdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
627
768
  import { homedir } from "node:os";
628
769
  import { join } from "node:path";
629
770
  function configDir(env, platform = process.platform, home = homedir()) {
@@ -644,7 +785,7 @@ async function loadToken(env, dir) {
644
785
  const path2 = credentialsPath(dir);
645
786
  let text;
646
787
  try {
647
- text = await readFile(path2, "utf8");
788
+ text = await readFile2(path2, "utf8");
648
789
  } catch {
649
790
  return { kind: "none" };
650
791
  }
@@ -669,7 +810,7 @@ async function saveToken(dir, token) {
669
810
  async function removeToken(dir) {
670
811
  const path2 = credentialsPath(dir);
671
812
  try {
672
- await readFile(path2);
813
+ await readFile2(path2);
673
814
  } catch {
674
815
  return false;
675
816
  }
@@ -703,6 +844,12 @@ Write (the board's freedom level decides what is made and what waits in the Inbo
703
844
  undo <request_id> Take back one of your own calls.
704
845
  Writes take --inbox --reason "<why>" to suggest instead of change.
705
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
+
706
853
  Work on your own (needs level 4, Act; other agents leave a claimed item alone)
707
854
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
708
855
  Claim the top open item no one is working on and
@@ -892,6 +1039,13 @@ async function dispatch(command, args, flags, io, dir) {
892
1039
  const [item2] = positionals(command, args, ["item"]);
893
1040
  return releaseCommand(await clientFor(io, dir), { item: item2 });
894
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
+ }
895
1049
  case "undo": {
896
1050
  const [requestId] = positionals(command, args, ["request_id"]);
897
1051
  return undoCommand(await clientFor(io, dir), { requestId });
@@ -975,6 +1129,7 @@ var code = await run(process.argv.slice(2), {
975
1129
  `),
976
1130
  stderr: (text) => process.stderr.write(`${text}
977
1131
  `),
978
- readSecret
1132
+ readSecret,
1133
+ readFile: readLocalFile
979
1134
  });
980
1135
  process.exitCode = code;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "listspace",
3
- "version": "0.1.1",
3
+ "version": "0.2.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,12 +41,12 @@
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",
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",
45
45
  "prepublishOnly": "npm run typecheck && npm test && npm run build"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@types/node": "20.19.43",
49
49
  "esbuild": "0.28.2",
50
- "typescript": "5.8.3"
50
+ "typescript": "5.9.3"
51
51
  }
52
52
  }