turbometro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scs0209
+
+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,80 @@
+# turbometro
+
+**Your monorepo as a subway — trains run when turbo does.**
+
+`npx turbometro` turns a **pnpm + Turborepo** workspace into a self-contained **3D subway**: packages are stations, workspace deps are rails, and turbo tasks ride as trains.
+
+![turbometro demo](docs/demo.gif)
+
+> **v0.1 honesty:** trains are **synthetic / replay** by default (not a live turbo attach). Live attach is on the roadmap.
+
+## Quick start
+
+```bash
+npx turbometro
+# writes ./metro.html — serve it over http (CDN Three.js)
+npx --yes serve . -p 4173
+# open http://localhost:4173/metro.html
+# click a neon station → buildings assemble once → train rides
+```
+
+## Demo (this repo)
+
+```bash
+npm install
+npm run build
+node bin/turbometro.js --demo --out metro.html
+npx --yes serve . -p 4173
+```
+
+Against the fixture:
+
+```bash
+node bin/turbometro.js --cwd fixtures/mini-mono --out metro.html
+```
+
+## CLI
+
+```
+turbometro [--out metro.html] [--replay run.json] [--force] [--cwd dir]
+turbometro --demo
+```
+
+| Flag | Meaning |
+|------|---------|
+| `--demo` | Built-in sample graph (no workspace required) |
+| `--replay` | Use a timeline JSON instead of synthetic events |
+| `--force` | Bypass the 150-package hard cap |
+| `--out` | Output path (default `./metro.html`) |
+
+## Interaction
+
+- **First click** on a station: stop kit assembles piece-by-piece, then the train materializes and rides the dep path
+- **Later clicks**: train keeps the mesh — only the path retargets (no flicker)
+- Orbit: drag · zoom: scroll · **Clear train** removes the rider
+
+## Requirements
+
+- Node ≥ 20
+- Target repo: `pnpm-workspace.yaml` + `turbo.json` or `turbo.jsonc`
+- Dependency cycles: **warned** and cycle edges dropped (map still renders)
+- Open the HTML via a local static server (`file://` can block ES modules / CDN)
+
+## Replay JSON
+
+```json
+{
+  "events": [
+    { "t": 0, "task": "build", "package": "@mini/web", "status": "running" },
+    { "t": 800, "task": "build", "package": "@mini/web", "status": "pass" }
+  ]
+}
+```
+
+## Credits
+
+Metro layout engine vendored from [23min/DAG-map](https://github.com/23min/DAG-map) (Apache-2.0). See `vendor/dag-map/NOTICE`.
+
+## License
+
+MIT — © scs0209

package/bin/turbometro.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findWorkspaceRoot } from './find-root.js';
+import { dropCycleEdges } from './graph.js';
+import { parseWorkspace } from './parse-workspace.js';
+import { parseTurbo } from './parse-turbo.js';
+import { scaleGuard } from './scale.js';
+import { buildSyntheticReplay, demoGraphAndTurbo, loadReplay, } from './replay.js';
+import { renderMetroHtml } from './render-html.js';
+function parseArgs(argv) {
+    const opts = {
+        cwd: process.cwd(),
+        out: path.join(process.cwd(), 'metro.html'),
+        demo: false,
+        replayPath: null,
+        force: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--demo')
+            opts.demo = true;
+        else if (a === '--force')
+            opts.force = true;
+        else if (a === '--out')
+            opts.out = path.resolve(argv[++i] ?? 'metro.html');
+        else if (a === '--replay')
+            opts.replayPath = path.resolve(argv[++i] ?? '');
+        else if (a === '--cwd')
+            opts.cwd = path.resolve(argv[++i] ?? '.');
+        else if (a === '--help' || a === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+    }
+    return opts;
+}
+function printHelp() {
+    console.log(`turbometro — monorepo subway map
+
+Usage:
+  turbometro [--out metro.html] [--replay run.json] [--force]
+  turbometro --demo
+
+Requires pnpm-workspace.yaml + turbo.json(c). Default trains are synthetic replay.
+`);
+}
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    let graph;
+    let turbo;
+    let title;
+    let disclaimer;
+    if (opts.demo) {
+        const demo = demoGraphAndTurbo();
+        graph = demo.graph;
+        turbo = demo.turbo;
+        title = 'turbometro demo';
+        disclaimer =
+            'Demo data. v0.1 trains are synthetic/replay — not a live turbo attach.';
+    }
+    else {
+        const root = findWorkspaceRoot(opts.cwd);
+        if (!root) {
+            console.error('turbometro: no pnpm-workspace.yaml found (searched upward from cwd).');
+            process.exit(1);
+        }
+        try {
+            graph = parseWorkspace(root);
+            turbo = parseTurbo(root);
+        }
+        catch (e) {
+            console.error(`turbometro: ${e.message}`);
+            process.exit(1);
+        }
+        title = path.basename(root);
+        disclaimer =
+            'v0.1 trains are synthetic/replay (default). Pass --replay run.json to override. Live turbo attach is roadmap.';
+    }
+    const scale = scaleGuard(graph.nodes.length, opts.force);
+    if (!scale.ok) {
+        console.error(`turbometro: ${scale.error}`);
+        process.exit(1);
+    }
+    if (scale.warn)
+        console.warn(`turbometro: ${scale.warn}`);
+    const { graph: acyclic, dropped } = dropCycleEdges(graph);
+    if (dropped.length) {
+        console.warn(`turbometro: dropped ${dropped.length} cycle edge(s): ${dropped.join(', ')}`);
+    }
+    graph = acyclic;
+    const replay = opts.replayPath
+        ? loadReplay(opts.replayPath)
+        : buildSyntheticReplay(graph, turbo);
+    const html = await renderMetroHtml({
+        title,
+        graph,
+        turbo,
+        replay,
+        disclaimer,
+    });
+    fs.writeFileSync(opts.out, html, 'utf8');
+    console.log(`Wrote ${opts.out}`);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/find-root.d.ts

@@ -0,0 +1,2 @@
+/** Walk up from cwd until pnpm-workspace.yaml is found. */
+export declare function findWorkspaceRoot(cwd: string): string | null;

package/dist/find-root.js

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Walk up from cwd until pnpm-workspace.yaml is found. */
+export function findWorkspaceRoot(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/graph.d.ts

@@ -0,0 +1,14 @@
+import type { Graph } from './types.js';
+/** Find edges that participate in a cycle (DFS). */
+export declare function findCycleEdgeKeys(graph: Graph): Set<string>;
+/** Drop cycle edges; returns new graph + dropped keys. */
+export declare function dropCycleEdges(graph: Graph): {
+    graph: Graph;
+    dropped: string[];
+};
+/** Pick a parent of `pkg` if any (for short train path). */
+export declare function pickParent(graph: Graph, pkg: string): string | null;
+export declare function shortestPathEndpoints(graph: Graph, pkg: string): {
+    from: string;
+    to: string;
+} | null;

package/dist/graph.js

@@ -0,0 +1,74 @@
+/** Find edges that participate in a cycle (DFS). */
+export function findCycleEdgeKeys(graph) {
+    const children = new Map();
+    for (const n of graph.nodes)
+        children.set(n.name, []);
+    for (const [from, to] of graph.edges) {
+        children.get(from)?.push(to);
+    }
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map();
+    for (const n of graph.nodes)
+        color.set(n.name, WHITE);
+    const cycleEdges = new Set();
+    function dfs(u, stack) {
+        color.set(u, GRAY);
+        stack.push(u);
+        for (const v of children.get(u) ?? []) {
+            const c = color.get(v) ?? WHITE;
+            if (c === GRAY) {
+                // edge u→v closes a cycle; mark all edges on the cycle path
+                const idx = stack.indexOf(v);
+                const cycle = stack.slice(idx);
+                for (let i = 0; i < cycle.length; i++) {
+                    const a = cycle[i];
+                    const b = cycle[(i + 1) % cycle.length];
+                    cycleEdges.add(`${a}->${b}`);
+                }
+                cycleEdges.add(`${u}->${v}`);
+            }
+            else if (c === WHITE) {
+                dfs(v, stack);
+            }
+        }
+        stack.pop();
+        color.set(u, BLACK);
+    }
+    for (const n of graph.nodes) {
+        if (color.get(n.name) === WHITE)
+            dfs(n.name, []);
+    }
+    return cycleEdges;
+}
+/** Drop cycle edges; returns new graph + dropped keys. */
+export function dropCycleEdges(graph) {
+    const bad = findCycleEdgeKeys(graph);
+    if (bad.size === 0)
+        return { graph, dropped: [] };
+    const edges = graph.edges.filter(([a, b]) => !bad.has(`${a}->${b}`));
+    return {
+        graph: { nodes: graph.nodes, edges },
+        dropped: [...bad],
+    };
+}
+/** Pick a parent of `pkg` if any (for short train path). */
+export function pickParent(graph, pkg) {
+    // edges are depender → dependency; train rides from dependency toward depender
+    // so "parent" along the ride is a dependency of pkg... wait:
+    // Design: short dep path ride into the package that has the task.
+    // Event is on package P. Ride along an edge into P.
+    // Incoming: someone depends on P? Or P depends on someone?
+    // D6: ride short dep path then stop at event package.
+    // Heuristic: from a workspace dependency of P (upstream) → P.
+    // Our edges are [depender, dependency] i.e. app → ui.
+    // So path app→ui means app depends on ui. Train for task on `app` should come from `ui` toward `app`.
+    // Edge direction in layout: we passed [app, ui]. For train on app, reverse: ui → app.
+    const deps = graph.edges.filter(([from]) => from === pkg).map(([, to]) => to);
+    return deps[0] ?? null;
+}
+export function shortestPathEndpoints(graph, pkg) {
+    const upstream = pickParent(graph, pkg);
+    if (!upstream)
+        return null;
+    return { from: upstream, to: pkg };
+}

package/dist/layout.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Workspace graph → dag-map input
+ *
+ * Mapping rules (v0.1):
+ * - package name → node.id / label
+ * - kind (apps|packages|other) → node.cls (theme class colors)
+ * - edge [depender, dependency] kept as dag-map edge [from, to]
+ * - routes: auto-discovered by layoutMetro (greedy longest-path)
+ */
+import type { Graph } from './types.js';
+export type DagMapInput = {
+    nodes: Array<{
+        id: string;
+        label: string;
+        cls: string;
+    }>;
+    edges: Array<[string, string]>;
+};
+export declare function toDagMapInput(graph: Graph): DagMapInput;

package/dist/layout.js

@@ -0,0 +1,15 @@
+const CLS = {
+    apps: 'pure',
+    packages: 'recordable',
+    other: 'side_effecting',
+};
+export function toDagMapInput(graph) {
+    return {
+        nodes: graph.nodes.map((n) => ({
+            id: n.name,
+            label: n.name,
+            cls: CLS[n.kind] ?? 'pure',
+        })),
+        edges: graph.edges.map(([a, b]) => [a, b]),
+    };
+}

package/dist/parse-turbo.d.ts

@@ -0,0 +1,5 @@
+import type { TurboTasks } from './types.js';
+/** Strip // and /* *\/ comments for turbo.jsonc. */
+export declare function stripJsonc(text: string): string;
+export declare function findTurboConfigPath(root: string): string | null;
+export declare function parseTurbo(root: string): TurboTasks;

package/dist/parse-turbo.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Strip // and /* *\/ comments for turbo.jsonc. */
+export function stripJsonc(text) {
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/^\s*\/\/.*$/gm, '');
+}
+export function findTurboConfigPath(root) {
+    for (const name of ['turbo.json', 'turbo.jsonc']) {
+        const p = path.join(root, name);
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function parseTurbo(root) {
+    const cfgPath = findTurboConfigPath(root);
+    if (!cfgPath) {
+        throw new Error(`Missing turbo.json or turbo.jsonc in ${root}. turbometro v0.1 requires Turborepo.`);
+    }
+    const raw = stripJsonc(fs.readFileSync(cfgPath, 'utf8'));
+    const json = JSON.parse(raw);
+    const tasks = json.tasks ?? json.pipeline;
+    if (!tasks || Object.keys(tasks).length === 0) {
+        throw new Error(`No tasks/pipeline found in ${cfgPath}`);
+    }
+    return tasks;
+}

package/dist/parse-workspace.d.ts

@@ -0,0 +1,4 @@
+import type { Graph } from './types.js';
+/** Minimal pnpm-workspace.yaml packages: list parser (no full YAML dep). */
+export declare function parseWorkspacePackagesList(yamlText: string): string[];
+export declare function parseWorkspace(root: string): Graph;

package/dist/parse-workspace.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function expandGlob(root, pattern) {
+    // Support "apps/*" and "packages/*" style only (v0.1).
+    if (!pattern.endsWith('/*')) {
+        const abs = path.join(root, pattern);
+        return fs.existsSync(abs) ? [abs] : [];
+    }
+    const base = pattern.slice(0, -2);
+    const absBase = path.join(root, base);
+    if (!fs.existsSync(absBase))
+        return [];
+    return fs
+        .readdirSync(absBase, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => path.join(absBase, d.name));
+}
+/** Minimal pnpm-workspace.yaml packages: list parser (no full YAML dep). */
+export function parseWorkspacePackagesList(yamlText) {
+    const lines = yamlText.split(/\r?\n/);
+    const pkgs = [];
+    let inPackages = false;
+    for (const raw of lines) {
+        const line = raw.replace(/#.*$/, '');
+        if (/^\s*packages\s*:/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages) {
+            if (/^\S/.test(line) && !/^\s*-\s*/.test(line))
+                break;
+            const m = line.match(/^\s*-\s*['"]?([^'"]+?)['"]?\s*$/);
+            if (m)
+                pkgs.push(m[1]);
+        }
+    }
+    return pkgs;
+}
+function kindFromDir(root, dir) {
+    const rel = path.relative(root, dir).split(path.sep)[0] || 'other';
+    if (rel === 'apps')
+        return 'apps';
+    if (rel === 'packages')
+        return 'packages';
+    return 'other';
+}
+function isWorkspaceDep(spec, workspaceNames) {
+    if (spec.startsWith('workspace:'))
+        return true;
+    return workspaceNames.has(spec);
+}
+export function parseWorkspace(root) {
+    const wsPath = path.join(root, 'pnpm-workspace.yaml');
+    if (!fs.existsSync(wsPath)) {
+        throw new Error(`Missing pnpm-workspace.yaml in ${root}`);
+    }
+    const patterns = parseWorkspacePackagesList(fs.readFileSync(wsPath, 'utf8'));
+    if (patterns.length === 0) {
+        throw new Error('pnpm-workspace.yaml has no packages entries');
+    }
+    const dirs = patterns.flatMap((p) => expandGlob(root, p));
+    const nodes = [];
+    for (const dir of dirs) {
+        const pkgPath = path.join(dir, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            continue;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (!pkg.name)
+            continue;
+        nodes.push({
+            name: pkg.name,
+            dir,
+            kind: kindFromDir(root, dir),
+        });
+    }
+    if (nodes.length === 0) {
+        throw new Error('No workspace packages found');
+    }
+    const names = new Set(nodes.map((n) => n.name));
+    const edges = [];
+    const edgeSet = new Set();
+    for (const node of nodes) {
+        const pkg = JSON.parse(fs.readFileSync(path.join(node.dir, 'package.json'), 'utf8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const [depName, spec] of Object.entries(deps)) {
+            if (!names.has(depName))
+                continue;
+            if (!isWorkspaceDep(spec, names))
+                continue;
+            // dag-map expects edges [from, to] as parent→child along flow;
+            // we use dependency direction: depender → dependency (train rides toward work).
+            const key = `${node.name}->${depName}`;
+            if (edgeSet.has(key))
+                continue;
+            edgeSet.add(key);
+            edges.push([node.name, depName]);
+        }
+    }
+    return { nodes, edges };
+}

package/dist/render-html.d.ts

@@ -0,0 +1,8 @@
+import type { Graph, Replay, TurboTasks } from './types.js';
+export declare function renderMetroHtml(opts: {
+    title: string;
+    graph: Graph;
+    turbo: TurboTasks;
+    replay: Replay;
+    disclaimer: string;
+}): Promise<string>;