@atolljs/cli 0.1.6 → 0.1.7

package/README.md

@@ -42,6 +42,10 @@ atoll add mfe <name>      publishable micro-frontend — framework-free
                           contract (defineIslandContract) + worker entry
                           attaching it + vite.mfe.config.ts publish build
                           → dist-mfe/<name>.worker.js behind CORS
+atoll add devtools [name] observability — src/atoll/devtools.ts init module
+                          (import first in the app entry) + @atolljs/devtools
+                          dev dep. Browser apps get the ?__atoll_devtools gate;
+                          node hosts get the /node entry + ATOLL_DEVTOOLS=1
 
 atoll doctor [--fix]      verify deps, lockfile, .npmrc policy,
                           worker-entry detectability, COOP/COEP headers

package/dist/cli.js

@@ -2194,6 +2194,57 @@ export async function register() {
 `
   };
 }
+function devtoolsSetup(name, host, wsUrl) {
+  if (host === "node") {
+    return `import { initDevtools } from '@atolljs/devtools/node';
+
+/**
+ * Devtools sink \u2014 imported first from the entry so it's installed before any
+ * pool spawns (worker INIT carries the flag at spawn time; late installs
+ * leave existing workers silent).
+ *
+ * No-op unless the process was started with ATOLL_DEVTOOLS=1 \u2014 then events
+ * stream over WebSocket to the standalone dashboard (\`atoll devtools\`,
+ * http://127.0.0.1:4780). Node has no BroadcastChannel page context, so the
+ * aggregate server is the transport.
+ */
+initDevtools({ session: { name: '${name}' } });
+`;
+  }
+  if (wsUrl) {
+    return `import { initDevtools } from '@atolljs/devtools';
+
+/**
+ * Devtools sink \u2014 imported first from the app entry so it's installed before
+ * any pool spawns (worker INIT carries the flag at spawn time; late installs
+ * leave existing workers silent).
+ *
+ * No-op unless the page URL carries ?__atoll_devtools \u2014 then events stream
+ * over WebSocket to the standalone aggregate dashboard (\`atoll devtools\`,
+ * http://127.0.0.1:4780). This app's dev server doesn't mount /__atoll/, so
+ * the overlay is off and the aggregate server is the viewer.
+ */
+initDevtools({
+  session: { name: '${name}' },
+  overlay: false,
+  url: '${wsUrl}',
+});
+`;
+  }
+  return `import { initDevtools } from '@atolljs/devtools';
+
+/**
+ * Devtools sink \u2014 imported first from the app entry so it's installed before
+ * any pool spawns (worker INIT carries the flag at spawn time; late installs
+ * leave existing workers silent).
+ *
+ * No-op unless the page URL carries ?__atoll_devtools \u2014 then events stream
+ * over BroadcastChannel on the app's own origin and a flyout overlay mounts.
+ * /__atoll/ itself is served by the @atolljs/vite plugin (plugins: [atoll()]).
+ */
+initDevtools({ session: { name: '${name}' } });
+`;
+}
 
 // src/commands.ts
 var NODE_HOSTS = ["node", "nestjs"];
@@ -2292,7 +2343,8 @@ var ADD_KINDS = [
   "housed",
   "route",
   "component",
-  "instrumentation"
+  "instrumentation",
+  "devtools"
 ];
 var KIND_SCOPE = {
   worker: null,
@@ -2305,7 +2357,8 @@ var KIND_SCOPE = {
   housed: ["nestjs"],
   route: ["nextjs"],
   component: ["nextjs"],
-  instrumentation: ["nextjs"]
+  instrumentation: ["nextjs"],
+  devtools: null
 };
 var KIND_VARIANTS = {
   island: ["facade", "mono"],
@@ -2399,7 +2452,7 @@ async function runAdd(ctx) {
   } else {
     nameArg = rest[1];
   }
-  const name = await pickName(ctx, kind, nameArg);
+  const name = kind === "devtools" ? nameArg ?? flag(ctx.args, "name") ?? project.pkg?.name?.split("/").pop() ?? "app" : await pickName(ctx, kind, nameArg);
   if (!name) return 1;
   const force = { force: hasFlag(ctx.args, "force") };
   const atollDir = flag(ctx.args, "dir") ?? rel(join3(project.srcDir, "atoll"));
@@ -2578,6 +2631,45 @@ pools warm at boot \u2014 extend register() as more routes appear.`
       );
       return 0;
     }
+    case "devtools": {
+      const host = hostOf(framework);
+      const wsUrl = host === "browser" && framework === "angular" ? "ws://127.0.0.1:4780/events" : void 0;
+      const file = `${atollDir}/devtools.ts`;
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [{ path: file, content: devtoolsSetup(name, host, wsUrl) }],
+        force
+      );
+      if (missingDeps(project.pkg, ["@atolljs/devtools"]).length) {
+        await offerInstall(ctx, project, ["-D", "@atolljs/devtools"]);
+      }
+      const srcRel = rel(project.srcDir);
+      const spec = file.startsWith(`${srcRel}/`) ? `./${file.slice(srcRel.length + 1).replace(/\.ts$/, "")}` : `./${file.replace(/\.ts$/, "")}`;
+      ctx.io.print("");
+      ctx.io.print(ctx.io.fmt.strong("wire it:"));
+      ctx.io.print(`  import the module first in your entry \u2014 before any pool spawns:`);
+      ctx.io.print(ctx.io.fmt.accent(`  import '${spec}';`));
+      if (host === "node") {
+        ctx.io.print(
+          `  ${ctx.io.fmt.accent("ATOLL_DEVTOOLS=1")} starts streaming \xB7 ${ctx.io.fmt.accent("atoll devtools")} serves the dashboard`
+        );
+      } else if (wsUrl) {
+        ctx.io.print(
+          `  ${ctx.io.fmt.accent("atoll devtools")} serves the aggregate dashboard \xB7 open the app with ${ctx.io.fmt.accent("?__atoll_devtools")}`
+        );
+      } else {
+        ctx.io.print(
+          `  open the app with ${ctx.io.fmt.accent("?__atoll_devtools")} \u2014 the flyout mounts and /__atoll/ serves the dashboard`
+        );
+        ctx.io.print(
+          ctx.io.fmt.dim(
+            `  /__atoll/ needs the @atolljs/vite plugin (plugins: [atoll()]) \u2014 no plugin? run \`atoll devtools\` + pass transport: 'websocket'`
+          )
+        );
+      }
+      return 0;
+    }
     default:
       ctx.io.error(`unhandled add kind ${kind}`);
       return 1;
@@ -2639,6 +2731,26 @@ async function runCreate(ctx) {
   }
   return 0;
 }
+async function runDevtools(ctx) {
+  const { io } = ctx;
+  const spec = "@atolljs/devtools/server";
+  const mod = await import(spec).catch(async () => {
+    const local = new URL("../../devtools/dist/server.js", import.meta.url).href;
+    return import(local).catch(() => null);
+  });
+  if (!mod?.createDevtoolsServer) {
+    io.error(`@atolljs/devtools isn't installed \u2014 ${io.fmt.accent("npm i -D @atolljs/devtools")}`);
+    return 1;
+  }
+  const port = Number(flag(ctx.args, "port") ?? 4780);
+  const server = await mod.createDevtoolsServer({ port: Number.isFinite(port) ? port : 4780 });
+  io.print(`atoll devtools \u2192 ${io.fmt.accent(server.url)}`);
+  io.print(io.fmt.dim("  ingest endpoint: " + server.url.replace("http://", "ws://") + "/events"));
+  io.print(io.fmt.dim("  in the app: connectDevtools() from '@atolljs/devtools'"));
+  io.warn("serving \u2014 Ctrl+C to stop");
+  return new Promise(() => {
+  });
+}
 function runDoctor(ctx) {
   const project = detectProject(ctx.cwd);
   const fix = hasFlag(ctx.args, "fix");
@@ -2750,6 +2862,8 @@ var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fm
       route       nextjs: api route pool \u2014 task | client variants
       component   nextjs: 'use client' hooks component over a pool
       instrumentation   nextjs: server bootstrap that warms route pools
+      devtools    observability \u2014 init module + @atolljs/devtools install
+                  (browser: ?__atoll_devtools + /__atoll/ \xB7 node: ATOLL_DEVTOOLS=1)
 
       Frameworks: react vue solid svelte angular nestjs nextjs node
       [--dir <path>] [--memory <name>|--no-memory] [--variant <v>] [--force]
@@ -2758,6 +2872,10 @@ var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fm
       Check the setup \u2014 deps, lockfile, .npmrc policy, bundler-detectable
       worker entries, COOP/COEP headers. --fix writes a hardened .npmrc.
 
+  ${fmt.accent("atoll devtools")} [--port 4780]
+      Serve the local devtools dashboard \u2014 pools, task timings, shared-memory
+      writes, island traffic. Apps connect via connectDevtools().
+
   ${fmt.dim(`flags: --yes/-y accepts defaults, --force overwrites existing files,
          --no-install skips dependency installation`)}
 `;
@@ -2778,6 +2896,8 @@ async function runCli(argv, io, cwd) {
         return await runAdd(ctx);
       case "doctor":
         return runDoctor(ctx);
+      case "devtools":
+        return await runDevtools(ctx);
       case "help":
       case void 0:
         io.print(HELP(io.fmt));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "atoll — scaffold worker pools, shared-memory contracts, and framework islands (experimental)",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",

package/src/cli.ts

@@ -12,7 +12,7 @@
  */
 import { consoleIo, type Fmt, type Io } from './io.ts';
 import { hasFlag, parseArgs } from './parse.ts';
-import { runAdd, runCreate, runDoctor, runInit, type Ctx } from './commands.ts';
+import { runAdd, runCreate, runDevtools, runDoctor, runInit, type Ctx } from './commands.ts';
 
 const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading ${fmt.dim('(experimental)')}
 
@@ -38,6 +38,8 @@ const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading
       route       nextjs: api route pool — task | client variants
       component   nextjs: 'use client' hooks component over a pool
       instrumentation   nextjs: server bootstrap that warms route pools
+      devtools    observability — init module + @atolljs/devtools install
+                  (browser: ?__atoll_devtools + /__atoll/ · node: ATOLL_DEVTOOLS=1)
 
       Frameworks: react vue solid svelte angular nestjs nextjs node
       [--dir <path>] [--memory <name>|--no-memory] [--variant <v>] [--force]
@@ -46,6 +48,10 @@ const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading
       Check the setup — deps, lockfile, .npmrc policy, bundler-detectable
       worker entries, COOP/COEP headers. --fix writes a hardened .npmrc.
 
+  ${fmt.accent('atoll devtools')} [--port 4780]
+      Serve the local devtools dashboard — pools, task timings, shared-memory
+      writes, island traffic. Apps connect via connectDevtools().
+
   ${fmt.dim(`flags: --yes/-y accepts defaults, --force overwrites existing files,
          --no-install skips dependency installation`)}
 `;
@@ -72,6 +78,8 @@ export async function runCli(argv: readonly string[], io: Io, cwd: string): Prom
         return await runAdd(ctx);
       case 'doctor':
         return runDoctor(ctx);
+      case 'devtools':
+        return await runDevtools(ctx);
       case 'help':
       case undefined:
         io.print(HELP(io.fmt));

package/src/commands.ts

@@ -145,6 +145,7 @@ const ADD_KINDS = [
   'route',
   'component',
   'instrumentation',
+  'devtools',
 ] as const;
 type AddKind = (typeof ADD_KINDS)[number];
 
@@ -161,6 +162,7 @@ const KIND_SCOPE: Record<AddKind, readonly Framework[] | null> = {
   route: ['nextjs'],
   component: ['nextjs'],
   instrumentation: ['nextjs'],
+  devtools: null,
 };
 
 /**
@@ -283,7 +285,12 @@ export async function runAdd(ctx: Ctx): Promise<number> {
     nameArg = rest[1];
   }
 
-  const name = await pickName(ctx, kind, nameArg);
+  // devtools writes a fixed devtools.ts — a positional/--name argument
+  // becomes the dashboard session label, not a file name.
+  const name =
+    kind === 'devtools'
+      ? (nameArg ?? flag(ctx.args, 'name') ?? project.pkg?.name?.split('/').pop() ?? 'app')
+      : await pickName(ctx, kind, nameArg);
   if (!name) return 1;
   const force = { force: hasFlag(ctx.args, 'force') };
   const atollDir = flag(ctx.args, 'dir') ?? rel(join(project.srcDir, 'atoll'));
@@ -480,6 +487,54 @@ export async function runAdd(ctx: Ctx): Promise<number> {
       return 0;
     }
 
+    case 'devtools': {
+      const host = hostOf(framework);
+      // Angular's CLI dev server mounts no /__atoll/ — stream to the
+      // aggregate server instead of the BroadcastChannel + flyout path.
+      const wsUrl = host === 'browser' && framework === 'angular'
+        ? 'ws://127.0.0.1:4780/events'
+        : undefined;
+      const file = `${atollDir}/devtools.ts`;
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [{ path: file, content: T.devtoolsSetup(name, host, wsUrl) }],
+        force,
+      );
+      if (missingDeps(project.pkg, ['@atolljs/devtools']).length) {
+        await offerInstall(ctx, project, ['-D', '@atolljs/devtools']);
+      }
+      // Print the specifier relative to srcDir — the import lands in the
+      // app entry (src/main.ts style), not in cwd.
+      const srcRel = rel(project.srcDir);
+      const spec = file.startsWith(`${srcRel}/`)
+        ? `./${file.slice(srcRel.length + 1).replace(/\.ts$/, '')}`
+        : `./${file.replace(/\.ts$/, '')}`;
+      ctx.io.print('');
+      ctx.io.print(ctx.io.fmt.strong('wire it:'));
+      ctx.io.print(`  import the module first in your entry — before any pool spawns:`);
+      ctx.io.print(ctx.io.fmt.accent(`  import '${spec}';`));
+      if (host === 'node') {
+        ctx.io.print(
+          `  ${ctx.io.fmt.accent('ATOLL_DEVTOOLS=1')} starts streaming · ${ctx.io.fmt.accent('atoll devtools')} serves the dashboard`,
+        );
+      } else if (wsUrl) {
+        ctx.io.print(
+          `  ${ctx.io.fmt.accent('atoll devtools')} serves the aggregate dashboard · open the app with ${ctx.io.fmt.accent('?__atoll_devtools')}`,
+        );
+      } else {
+        ctx.io.print(
+          `  open the app with ${ctx.io.fmt.accent('?__atoll_devtools')} — the flyout mounts and /__atoll/ serves the dashboard`,
+        );
+        ctx.io.print(
+          ctx.io.fmt.dim(
+            `  /__atoll/ needs the @atolljs/vite plugin (plugins: [atoll()]) — no plugin? run \`atoll devtools\` + pass transport: 'websocket'`,
+          ),
+        );
+      }
+      return 0;
+    }
+
     default:
       ctx.io.error(`unhandled add kind ${kind}`);
       return 1;
@@ -557,6 +612,39 @@ export async function runCreate(ctx: Ctx): Promise<number> {
   return 0;
 }
 
+/* ── atoll devtools ─────────────────────────────────────────────────────── */
+
+/**
+ * `atoll devtools [--port N]` — boot the local devtools server + dashboard.
+ * The server lives in @atolljs/devtools: resolved as an installed package in
+ * consumer projects, with a relative fallback so `npm run atoll devtools`
+ * works inside the atoll monorepo where the package isn't installed.
+ *
+ * Never resolves — the process serves until SIGINT.
+ */
+export async function runDevtools(ctx: Ctx): Promise<number> {
+  const { io } = ctx;
+  const spec = '@atolljs/devtools/server';
+  const mod: { createDevtoolsServer?: (o: { port: number }) => Promise<{ url: string }> } | null =
+    await import(spec).catch(async () => {
+      // In-repo fallback: the workspace package's built dist (extensionless
+      // sources can't run under type stripping — `npm run build` there first).
+      const local = new URL('../../devtools/dist/server.js', import.meta.url).href;
+      return import(local).catch(() => null);
+    });
+  if (!mod?.createDevtoolsServer) {
+    io.error(`@atolljs/devtools isn't installed — ${io.fmt.accent('npm i -D @atolljs/devtools')}`);
+    return 1;
+  }
+  const port = Number(flag(ctx.args, 'port') ?? 4780);
+  const server = await mod.createDevtoolsServer({ port: Number.isFinite(port) ? port : 4780 });
+  io.print(`atoll devtools → ${io.fmt.accent(server.url)}`);
+  io.print(io.fmt.dim('  ingest endpoint: ' + server.url.replace('http://', 'ws://') + '/events'));
+  io.print(io.fmt.dim("  in the app: connectDevtools() from '@atolljs/devtools'"));
+  io.warn('serving — Ctrl+C to stop');
+  return new Promise<number>(() => {});
+}
+
 /* ── atoll doctor ───────────────────────────────────────────────────────── */
 
 interface Check {

package/src/templates.ts

@@ -2163,3 +2163,66 @@ export async function register() {
   };
 }
 
+
+/**
+ * `add devtools` — the init module, imported first from the app entry so the
+ * sink is installed before any pool spawns (worker INIT carries the flag at
+ * spawn time; late installs leave existing workers silent).
+ *
+ * Three shapes:
+ *  - node host   → '@atolljs/devtools/node' entry, ATOLL_DEVTOOLS env gate
+ *  - browser     → '@atolljs/devtools', ?__atoll_devtools URL gate + overlay
+ *  - browser + wsUrl → same browser gate but streams to the aggregate server
+ *    (angular: nothing mounts /__atoll/)
+ */
+export function devtoolsSetup(name: string, host: 'browser' | 'node', wsUrl?: string): string {
+  if (host === 'node') {
+    return `import { initDevtools } from '@atolljs/devtools/node';
+
+/**
+ * Devtools sink — imported first from the entry so it's installed before any
+ * pool spawns (worker INIT carries the flag at spawn time; late installs
+ * leave existing workers silent).
+ *
+ * No-op unless the process was started with ATOLL_DEVTOOLS=1 — then events
+ * stream over WebSocket to the standalone dashboard (\`atoll devtools\`,
+ * http://127.0.0.1:4780). Node has no BroadcastChannel page context, so the
+ * aggregate server is the transport.
+ */
+initDevtools({ session: { name: '${name}' } });
+`;
+  }
+  if (wsUrl) {
+    return `import { initDevtools } from '@atolljs/devtools';
+
+/**
+ * Devtools sink — imported first from the app entry so it's installed before
+ * any pool spawns (worker INIT carries the flag at spawn time; late installs
+ * leave existing workers silent).
+ *
+ * No-op unless the page URL carries ?__atoll_devtools — then events stream
+ * over WebSocket to the standalone aggregate dashboard (\`atoll devtools\`,
+ * http://127.0.0.1:4780). This app's dev server doesn't mount /__atoll/, so
+ * the overlay is off and the aggregate server is the viewer.
+ */
+initDevtools({
+  session: { name: '${name}' },
+  overlay: false,
+  url: '${wsUrl}',
+});
+`;
+  }
+  return `import { initDevtools } from '@atolljs/devtools';
+
+/**
+ * Devtools sink — imported first from the app entry so it's installed before
+ * any pool spawns (worker INIT carries the flag at spawn time; late installs
+ * leave existing workers silent).
+ *
+ * No-op unless the page URL carries ?__atoll_devtools — then events stream
+ * over BroadcastChannel on the app's own origin and a flyout overlay mounts.
+ * /__atoll/ itself is served by the @atolljs/vite plugin (plugins: [atoll()]).
+ */
+initDevtools({ session: { name: '${name}' } });
+`;
+}