tenbo-dashboard 0.4.0 → 0.4.1

package/bin/launch-dashboard.mjs

@@ -1,8 +1,59 @@
 import { createServer } from 'vite';
 import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
+import net from 'node:net';
 
+const PREFERRED_PORT = 5174;
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// The cwd is the user's project directory (the dashboard reads .tenbo/ from there).
+// Surface it on startup so the user can tell which repo a given dashboard is
+// serving — important when multiple dashboards are running at once. (td-011)
+const cwd = process.cwd();
+console.log(`Serving .tenbo/ from ${cwd}`);
+
+// Detect whether something is already listening on the preferred port. If so,
+// try probing it for a tenbo-dashboard /api/state endpoint so we can name the
+// other repo in the warning. Either way, surface a warning so the user isn't
+// surprised when this instance lands on a different port. (td-011)
+async function isPortInUse(port) {
+  return new Promise((resolve) => {
+    const tester = net.createConnection({ port, host: '127.0.0.1' });
+    tester.once('connect', () => { tester.destroy(); resolve(true); });
+    tester.once('error', () => resolve(false));
+  });
+}
+
+async function probeOtherDashboard(port) {
+  try {
+    const r = await fetch(`http://127.0.0.1:${port}/api/state`, {
+      signal: AbortSignal.timeout(500),
+    });
+    if (!r.ok) return null;
+    // We don't have a structured "what's the cwd of this server" endpoint, so
+    // we infer from the scopes' paths. If unavailable, fall through.
+    const data = await r.json();
+    const firstScope = data?.scopes?.[0];
+    return firstScope ? `serving ${data.scopes.length} scope(s) (e.g. "${firstScope.id}")` : 'unknown repo';
+  } catch {
+    return null;
+  }
+}
+
+if (await isPortInUse(PREFERRED_PORT)) {
+  const other = await probeOtherDashboard(PREFERRED_PORT);
+  const detail = other ? ` (${other})` : '';
+  console.log(
+    `Port ${PREFERRED_PORT} is already in use — likely another tenbo-dashboard${detail}.`,
+  );
+  console.log(`This instance will start on the next available port and serve ${cwd}.`);
+}
+
 const server = await createServer({ root, configFile: path.join(root, 'vite.config.ts') });
 await server.listen();
 server.printUrls();
+
+// Touch existsSync so unused-import lint doesn't strip it — it's used for
+// future expansion (probing other dashboards' tenbo state files).
+void existsSync;

package/bin/tenbo-dashboard.mjs

@@ -41,6 +41,13 @@ const commands = {
   sync: 'scripts/sync.ts',
 };
 
+// Documented aliases for the bare-launch behavior. Users (and agents) reading
+// help shouldn't have to discover that running `tenbo-dashboard` with no args
+// launches the dashboard — these subcommand verbs are conventional and now
+// explicit. Anything not in `commands` and not in this set is treated as an
+// error rather than silently launching. (td-012)
+const LAUNCH_ALIASES = new Set(['serve', 'start', 'dev']);
+
 function run(script, scriptArgs) {
   const tsx = findTsx();
   const child = spawn(tsx, [path.join(root, script), ...scriptArgs], {
@@ -66,6 +73,7 @@ tenbo-dashboard — local architecture dashboard for .tenbo/ repos
 
 Usage:
   tenbo-dashboard                  Launch the dashboard (http://localhost:5174)
+  tenbo-dashboard serve            Same as bare invocation (also: 'start', 'dev')
   tenbo-dashboard sync             Refresh tenbo state after a change (metrics + init-check + validate, surfaces new findings)
   tenbo-dashboard validate         Run validation rules
   tenbo-dashboard init-check       Strict completeness check for fresh init (errors on missing skeletons, file_count:0, etc)
@@ -73,14 +81,22 @@ Usage:
   tenbo-dashboard metrics --all    Compute scope metrics
   tenbo-dashboard --version        Print package version
   tenbo-dashboard help             Show this help
+
+The dashboard reads/writes .tenbo/ in the current working directory. To
+serve a different repo, cd into it before running.
 `);
   process.exit(0);
 }
 
 if (commands[command]) {
   run(commands[command], args);
-} else {
-  // No recognized subcommand — default to launching the dashboard
-  // Pass the original command back as an arg in case it was a flag
+} else if (!command || LAUNCH_ALIASES.has(command)) {
+  // Bare invocation OR a documented launch alias ('serve' / 'start' / 'dev').
   startDashboard();
+} else {
+  // Unknown subcommand — surface clearly instead of silently launching.
+  // (Pre-td-012 behavior was to fall through; that hid typos.)
+  process.stderr.write(`tenbo-dashboard: unknown subcommand '${command}'\n`);
+  process.stderr.write(`Run 'tenbo-dashboard help' for usage.\n`);
+  process.exit(2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",

package/src/App.tsx

@@ -24,6 +24,30 @@ type Overlay =
   | { kind: 'modal'; scopeId: string; item: Item }
   | null;
 
+/**
+ * Loading state shown until the initial GET /api/state lands. Adds a "still
+ * loading after 5s" hint so a slow first launch (e.g. cold Vite optimizeDeps)
+ * doesn't look like a broken state. (td-013)
+ */
+function LoadingState() {
+  const [showSlowHint, setShowSlowHint] = useState(false);
+  useEffect(() => {
+    const t = window.setTimeout(() => setShowSlowHint(true), 5000);
+    return () => window.clearTimeout(t);
+  }, []);
+  return (
+    <div style={{ padding: 24, fontFamily: 'system-ui', color: 'var(--console-fog)' }}>
+      <div style={{ marginBottom: 8 }}>Loading workspace from <code>.tenbo/</code>…</div>
+      {showSlowHint && (
+        <div style={{ fontSize: 12, opacity: 0.7, maxWidth: 520 }}>
+          First launch can take ~10 seconds while Vite optimizes the dependency graph.
+          If this persists past ~30 seconds, check the terminal for errors.
+        </div>
+      )}
+    </div>
+  );
+}
+
 export default function App() {
   const { state, loadError, reload, mergeItem, generation } = useTenboState();
   const patch = useApiPatch();
@@ -50,7 +74,7 @@ export default function App() {
 
   if (loadError && loadError.includes('404')) return <EmptyState message="No .tenbo/ found at the repo root." />;
   if (loadError) return <div style={{ padding: 24, color: 'var(--error)' }}>Error: {loadError} <button onClick={reload}>retry</button></div>;
-  if (!state) return <div style={{ padding: 24 }}>Loading…</div>;
+  if (!state) return <LoadingState />;
 
   const mode = modeFromRoute(route);
   const onSelectMode = (m: Mode) => {

package/vite.config.ts

@@ -24,6 +24,12 @@ export default defineConfig({
       'remark-gfm',
       'style-to-js',
       'hast-util-to-jsx-runtime',
+      // lucide-react ships ~1500 individual icon files in dist/esm/icons/.
+      // Without pre-bundling, the dev server serves each icon as a separate
+      // ESM module the browser fetches one-by-one — first launch sits on
+      // 'Loading...' for 10+ seconds. Forcing pre-bundle collapses them
+      // into a single chunk served from .vite/deps. (td-010)
+      'lucide-react',
     ],
   },
   test: { environment: 'jsdom', globals: true, setupFiles: ['./src/test-setup.ts'] },