@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 +64 -2
- package/bin/celldeck.mjs +73 -0
- package/deck.schema.json +6299 -0
- package/index.html +3362 -0
- package/lib/core.js +1434 -0
- package/lib/store.js +87 -0
- package/package.json +27 -4
package/README.md
CHANGED
|
@@ -1,3 +1,65 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Cell Deck
|
|
2
2
|
|
|
3
|
-
|
|
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**).
|
package/bin/celldeck.mjs
ADDED
|
@@ -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
|
+
});
|