@pritzlaff/celldeck 0.0.0-stage → 0.1.2

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/README.md CHANGED
@@ -1,3 +1,65 @@
1
- # Temporary Holding Version
1
+ # Cell Deck
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Bubble diagrams you pull apart, connect and present as a sequence of saved views.
4
+
5
+ **[▶ Open Cell Deck](https://aaronp.github.io/celldeck/)** ·
6
+ [Example deck](https://aaronp.github.io/celldeck/?src=examples/acme-architecture/deck.json&view=v-pulled-apart)
7
+
8
+ ## Adding it to your project
9
+
10
+ From your project's root (Bun shown; `npm i -D`, `npm pkg set` and `npm run` work the same):
11
+
12
+ ```sh
13
+ bun add -d @pritzlaff/celldeck
14
+ bun pm pkg set scripts.celldeck="celldeck docs/overview/deck.json"
15
+ bun run celldeck # creates the deck if it's missing, serves it on localhost (loopback only) and opens it
16
+ ```
17
+
18
+ The File menu's **Save to deck.json** writes the deck back to the file; commit it like any other source.
19
+ `PORT=…` fixes the port and `NO_OPEN=1` skips opening a browser, as for the other tools.
20
+
21
+ A deck is JSON rather than markdown, so it's edited in the viewer, not by hand. Its format is
22
+ **[deck.schema.json](deck.schema.json)** (JSON Schema, every field documented), also published at
23
+ <https://aaronp.github.io/celldeck/deck.schema.json> and shipped in the package as
24
+ `node_modules/@pritzlaff/celldeck/deck.schema.json`, so people and agents working in your repo can
25
+ read and check the version they run. [examples/acme-architecture/deck.json](examples/acme-architecture/deck.json)
26
+ is a complete deck. Cell Deck has no `card`/`badge` command yet;
27
+ [aaronp/template](https://github.com/aaronp/template) writes the deck's card itself
28
+ (`scripts/deck-card.ts`) and shows it beside its sibling tools (goals, architecture, decisions, risks,
29
+ schedule, delivery) on one dashboard.
30
+
31
+ ## Layout
32
+
33
+ | Path | What |
34
+ |---|---|
35
+ | `index.html` | The page: styles, markup, rendering and input (the "edge"). No build step. |
36
+ | `lib/core.js` | Pure core: data model (TypeBox schemas, incl. the `deck.json` format), scene reducers, physics. |
37
+ | `lib/store.js` | `createDeckStore(storage, key)`: CRUD over a deck (stage + views), validated on every write, backed by `localStorage` (or `memoryStorage()`). |
38
+ | `examples/` | Data-only repos that open in this viewer. Copy one with `make clone` from its folder. |
39
+ | `test/` | `npm test` (Node's built-in runner). |
40
+ | `deck.schema.json` | The `deck.json` format as JSON Schema, from `DeckSchema` (`make schema`; a test checks it's current). |
41
+
42
+ ## Data
43
+
44
+ A deck is one JSON file: `{ version, scene, camera, views: [{ id, name, scene, camera }] }`. See
45
+ [deck.schema.json](deck.schema.json), generated from `DeckSchema` in `lib/core.js` by `make schema`. `version` is the format version (currently `1`; a file without one is
46
+ read as `1`). A file with a newer version than the page knows is refused rather than misread. Edits are saved in your browser. Use **Download** to save
47
+ `deck.json`, and **Open** to load one from a file (drag-and-drop or pick it) or from a URL.
48
+
49
+ ## Links
50
+
51
+ | Param | Effect |
52
+ |---|---|
53
+ | `?src=<url>` | open that `deck.json` (relative or absolute; another host must allow CORS). It is not saved in your browser, so a shared link never overwrites your work. |
54
+ | `?view=<id or name>` | open that saved view. The address bar follows as you switch views. |
55
+ | `?present` | start in present mode |
56
+
57
+ ## Develop
58
+
59
+ ```sh
60
+ make dev # serves the repo on :8000 (python3); open the printed example URL
61
+ make test
62
+ ```
63
+
64
+ Pushing to `main`/`master` runs the tests, then publishes to GitHub Pages
65
+ (Settings → Pages → Source: **GitHub Actions**).
@@ -0,0 +1,73 @@
1
+ #!/usr/bin/env node
2
+ // celldeck <deck.json>: serves the viewer and that deck on localhost, then opens it in the browser.
3
+ // The deck is re-read on every request, so reloading shows your latest edits; File → Save writes it back (PUT).
4
+ // A missing file is created as an empty deck, so a project can start from `celldeck docs/overview/deck.json`.
5
+ import { createServer } from 'node:http';
6
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
7
+ import { spawn } from 'node:child_process';
8
+ import { basename, dirname, resolve } from 'node:path';
9
+
10
+ const file = process.argv[2];
11
+ if (!file || file === '-h' || file === '--help') {
12
+ console.error('Usage: celldeck <deck.json> (PORT=8000 to pick the port, NO_OPEN=1 to skip opening a browser)');
13
+ process.exit(file ? 0 : 1);
14
+ }
15
+ const path = resolve(file);
16
+ await readFile(path).catch(async (e) => {
17
+ if (e.code !== 'ENOENT') { console.error(`celldeck: cannot read ${file}: ${e.message}`); process.exit(1); }
18
+ await mkdir(dirname(path), { recursive: true });
19
+ await writeFile(path, JSON.stringify({ version: 1, scene: { bubbles: [], elements: [], links: [] }, camera: { x: 0, y: 0, zoom: 1 }, views: [] }, null, 2) + '\n');
20
+ console.log(`Created ${file}`);
21
+ });
22
+
23
+ const page = (p) => new URL(`..${p}`, import.meta.url);
24
+ const route = '/' + encodeURIComponent(basename(path));
25
+ // Only these routes, so nothing else on disk is reachable.
26
+ const routes = new Map([
27
+ ['/', [page('/index.html'), 'text/html']],
28
+ ['/lib/core.js', [page('/lib/core.js'), 'text/javascript']],
29
+ ['/lib/store.js', [page('/lib/store.js'), 'text/javascript']],
30
+ [route, [path, 'application/json']],
31
+ ]);
32
+ // Loopback names a browser may use for this server. Anything else in Host means DNS rebinding, so it is refused.
33
+ const hosts = (port) => new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
34
+ const handler = async (req, res) => {
35
+ if (!hosts(server.address().port).has(req.headers.host)) return res.writeHead(403).end('Forbidden host');
36
+ const [target, type] = routes.get(new URL(req.url, 'http://x').pathname) ?? [];
37
+ if (!target) return res.writeHead(404).end('Not found');
38
+ if (req.method === 'PUT' && target === path) {
39
+ // Cross-site pages cannot get here: a JSON PUT needs a CORS preflight, which this server never answers.
40
+ try {
41
+ const chunks = [];
42
+ for await (const c of req) chunks.push(c);
43
+ const body = Buffer.concat(chunks);
44
+ JSON.parse(body); // never replace the deck with something that isn't JSON
45
+ const tmp = `${path}.celldeck-tmp`;
46
+ await writeFile(tmp, body);
47
+ await rename(tmp, path); // whole file or nothing, never half-written
48
+ return res.writeHead(204).end();
49
+ } catch (e) {
50
+ return res.writeHead(e instanceof SyntaxError ? 400 : 500).end(e.message);
51
+ }
52
+ }
53
+ if (req.method !== 'GET' && req.method !== 'HEAD') return res.writeHead(405).end('Method not allowed');
54
+ try {
55
+ const body = await readFile(target);
56
+ // x-celldeck-writable tells the page that Save can PUT the deck back to this URL.
57
+ res.writeHead(200, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store', ...(target === path ? { 'x-celldeck-writable': '1' } : {}) }).end(body);
58
+ } catch (e) {
59
+ res.writeHead(e.code === 'ENOENT' ? 404 : 500).end(e.message);
60
+ }
61
+ };
62
+ const server = createServer(handler);
63
+
64
+ server.listen(Number(process.env.PORT ?? 0), '127.0.0.1', () => {
65
+ const { port } = server.address();
66
+ // Also answer on ::1 so http://localhost:<port> and http://[::1]:<port> work; skipped if IPv6 loopback is unavailable.
67
+ createServer(handler).on('error', () => {}).listen(port, '::1');
68
+ const url = `http://127.0.0.1:${port}/?src=${route}`;
69
+ console.log(`Serving ${file} at ${url} (Ctrl-C to stop)`);
70
+ if (process.env.NO_OPEN) return;
71
+ const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
72
+ spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
73
+ });