morffy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tally Barak
+
+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,62 @@
+# morffy
+
+A read-only visualizer that shows how a system-architecture diagram **evolves
+over a timeline**. It pairs a Visio-style graph canvas with a Gantt-style
+timeline, both driven by a single AI-generated JSON/YAML file.
+
+See [`SPEC.md`](SPEC.md) for the full design.
+
+## Running the app
+
+There are two ways to view a diagram.
+
+### 1. Browser file picker (no setup)
+
+Open the app and click **Load file** (top bar or empty state) to pick a JSON or
+YAML diagram from disk.
+
+### 2. CLI — serve a file by path (with live reload)
+
+```sh
+morffy <diagram.json|yaml> [--port 4173] [--no-open] [--no-watch]
+```
+
+The CLI serves the app and **auto-loads** the given file. It also **watches the
+file** — edit it on disk and the diagram refreshes on screen automatically
+(disable with `--no-watch`).
+
+> [!IMPORTANT]
+> **The CLI serves a built app, so a build must exist first.**
+> When you install the published npm package this is already done for you — it
+> ships a prebuilt `dist/`, so `npx morffy diagram.json` just works.
+>
+> When working **from this repo**, build first (the CLI will tell you if you
+> forget):
+>
+> ```sh
+> npm run serve -- diagram.json          # build, then serve (one step)
+> # or, if dist/ is already built:
+> npm run serve:built -- diagram.json    # serve without rebuilding
+> ```
+>
+> Note: the CLI watches your **diagram file**, not the app source. After editing
+> app source, rebuild (`npm run build`) to see those changes. For live app-source
+> reloading, use the Vite dev server (`npm run dev`) instead.
+
+## Development
+
+```sh
+npm install
+npm run dev          # vite dev server (http://localhost:5173)
+```
+
+### Quality gate
+
+```sh
+npm run typecheck    # tsc -b --noEmit
+npm test             # vitest (unit + CLI integration)
+npm run test:e2e     # playwright
+npm run lint         # eslint
+npm run build        # tsc -b && vite build
+npm run format       # prettier --write
+```

package/bin/morffy.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * morffy CLI — serve the built app against a diagram file by path.
+ *
+ *   morffy <diagram.json|yaml> [--port 4173] [--no-open]
+ *   morffy --file <path> [--port 4173]
+ *
+ * Morffy is a client-side SPA; there is no server-side rendering. This CLI is a
+ * tiny zero-dependency static server that:
+ *
+ *   1. serves the built `dist/` bundle,
+ *   2. exposes the chosen diagram file's RAW TEXT at `/__morffy/diagram`
+ *      (with the original filename in a header so the app picks JSON vs YAML),
+ *   3. exposes `/__morffy/config.json` describing what to auto-load,
+ *   4. exposes `/__morffy/events` (Server-Sent Events) and watches the data file
+ *      with chokidar — on a change it pushes a `reload` event so the app
+ *      re-fetches and live-refreshes the diagram (disable with `--no-watch`).
+ *
+ * The app's boot effect (see AppShell) fetches `/__morffy/config.json`; when a
+ * diagram is configured it auto-loads it and subscribes to `/__morffy/events`.
+ * Under plain static hosting / dev those endpoints 404, so the app stays empty
+ * exactly as before.
+ */
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { extname, join, resolve, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chokidar from 'chokidar';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DIST_DIR = resolve(__dirname, '..', 'dist');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json; charset=utf-8',
+};
+
+function parseArgs(argv) {
+  const opts = { file: null, port: 4173, open: true, watch: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--version' || a === '-v') opts.version = true;
+    else if (a === '--port' || a === '-p') opts.port = Number(argv[++i]);
+    else if (a === '--no-open') opts.open = false;
+    else if (a === '--no-watch') opts.watch = false;
+    else if (a === '--file' || a === '-f') opts.file = argv[++i];
+    else if (a.startsWith('--port=')) opts.port = Number(a.slice('--port='.length));
+    else if (a.startsWith('--file=')) opts.file = a.slice('--file='.length);
+    else if (!a.startsWith('-') && !opts.file) opts.file = a;
+  }
+  return opts;
+}
+
+const HELP = `morffy — serve the architecture-timeline visualizer against a diagram file.
+
+Usage:
+  morffy <diagram.json|yaml> [options]
+  morffy --file <path> [options]
+
+Options:
+  -f, --file <path>   Diagram file to load (JSON or YAML). Also positional.
+  -p, --port <n>      Port to listen on (default: 4173).
+      --no-open       Do not open the browser automatically.
+      --no-watch      Do not live-reload the app when the file changes.
+  -h, --help          Show this help.
+  -v, --version       Print the morffy version.
+
+Examples:
+  morffy ./architecture.json
+  morffy --file evolution.yaml --port 8080 --no-open
+`;
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { 'Cache-Control': 'no-store', ...headers });
+  res.end(body);
+}
+
+/** Resolve a URL path to a file inside dist/, guarding against traversal. */
+function safeDistPath(urlPath) {
+  const clean = decodeURIComponent(urlPath.split('?')[0]).replace(/^\/+/, '');
+  const full = resolve(DIST_DIR, clean);
+  if (full !== DIST_DIR && !full.startsWith(DIST_DIR + '/')) return null; // traversal
+  return full;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (opts.version) {
+    const pkg = JSON.parse(await readFile(resolve(__dirname, '..', 'package.json'), 'utf8'));
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+
+  // The app must be built first.
+  try {
+    await stat(join(DIST_DIR, 'index.html'));
+  } catch {
+    process.stderr.write(
+      `morffy: no build found at ${DIST_DIR}.\n` +
+        `Build first, then serve:  npm run build && npm run serve:built -- <file>\n` +
+        `Or do both in one step:    npm run serve -- <file>\n` +
+        `(The published npm package ships a prebuilt dist, so end users never build.)\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let dataPath = null;
+  let dataName = null;
+  if (opts.file) {
+    dataPath = resolve(process.cwd(), opts.file);
+    try {
+      await stat(dataPath);
+    } catch {
+      process.stderr.write(`morffy: diagram file not found: ${dataPath}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    dataName = basename(dataPath);
+  }
+
+  // Open Server-Sent-Events connections, notified when the file changes.
+  const sseClients = new Set();
+  const broadcast = (event) => {
+    for (const client of sseClients) {
+      try {
+        client.write(`event: ${event}\ndata: ${dataName ?? ''}\n\n`);
+      } catch {
+        sseClients.delete(client);
+      }
+    }
+  };
+
+  const server = createServer(async (req, res) => {
+    try {
+      const url = req.url || '/';
+
+      // --- morffy control endpoints -------------------------------------
+      if (url === '/__morffy/config.json') {
+        return send(
+          res,
+          200,
+          JSON.stringify({ autoLoad: Boolean(dataPath), filename: dataName, watch: opts.watch }),
+          { 'Content-Type': MIME['.json'] },
+        );
+      }
+      if (url.split('?')[0] === '/__morffy/events') {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-store',
+          Connection: 'keep-alive',
+        });
+        res.write('event: ready\ndata: connected\n\n');
+        sseClients.add(res);
+        req.on('close', () => sseClients.delete(res));
+        return;
+      }
+      if (url.split('?')[0] === '/__morffy/diagram') {
+        if (!dataPath) return send(res, 404, 'no diagram configured');
+        const text = await readFile(dataPath);
+        const type = /\.ya?ml$/i.test(dataName) ? 'text/yaml; charset=utf-8' : MIME['.json'];
+        return send(res, 200, text, {
+          'Content-Type': type,
+          'X-Morffy-Filename': dataName,
+        });
+      }
+
+      // --- static dist/ assets ------------------------------------------
+      const pathname = url.split('?')[0];
+      let filePath = safeDistPath(pathname === '/' ? '/index.html' : pathname);
+      if (!filePath) return send(res, 403, 'forbidden');
+
+      let info = null;
+      try {
+        info = await stat(filePath);
+      } catch {
+        info = null;
+      }
+
+      // SPA fallback: unknown non-asset routes serve index.html.
+      if (!info || info.isDirectory()) {
+        filePath = join(DIST_DIR, 'index.html');
+      }
+
+      const type = MIME[extname(filePath).toLowerCase()] || 'application/octet-stream';
+      res.writeHead(200, { 'Content-Type': type });
+      createReadStream(filePath).pipe(res);
+    } catch (err) {
+      send(res, 500, `morffy: ${String(err)}`);
+    }
+  });
+
+  let watcher = null;
+  server.listen(opts.port, () => {
+    const at = `http://localhost:${opts.port}`;
+    if (dataPath) process.stdout.write(`morffy: serving ${dataName} at ${at}\n`);
+    else process.stdout.write(`morffy: serving (no diagram — use the Load file button) at ${at}\n`);
+
+    // Watch the data file and live-reload the app on every change.
+    if (dataPath && opts.watch) {
+      watcher = chokidar.watch(dataPath, {
+        ignoreInitial: true,
+        // Wait for the writer to finish (editors save in bursts) but stay snappy.
+        awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 },
+      });
+      watcher
+        .on('change', () => {
+          process.stdout.write(`morffy: ${dataName} changed — reloading\n`);
+          broadcast('reload');
+        })
+        .on('add', () => broadcast('reload')) // re-created after an atomic save
+        .on('error', () => {});
+      process.stdout.write('morffy: watching for changes (use --no-watch to disable)\n');
+    }
+
+    if (opts.open) openBrowser(at);
+  });
+
+  const shutdown = () => {
+    if (watcher) watcher.close();
+    server.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  server.on('error', (err) => {
+    if (err && err.code === 'EADDRINUSE') {
+      process.stderr.write(`morffy: port ${opts.port} is in use. Try --port <n>.\n`);
+      process.exitCode = 1;
+    } else {
+      process.stderr.write(`morffy: ${String(err)}\n`);
+      process.exitCode = 1;
+    }
+  });
+}
+
+/** Best-effort browser open; never fatal. */
+function openBrowser(url) {
+  import('node:child_process')
+    .then(({ spawn }) => {
+      const cmd =
+        process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+      const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+      spawn(cmd, args, { stdio: 'ignore', detached: true })
+        .on('error', () => {})
+        .unref();
+    })
+    .catch(() => {});
+}
+
+main();