@atolljs/cli 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/cli",
-  "version": "0.1.5",
+  "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,13 +12,14 @@
  */
 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)')}
 
-  ${fmt.accent('atoll new <dir>')} [--framework react|vue|solid|svelte|node] [--pm npm]
+  ${fmt.accent('atoll new <dir>')} [--framework react|vue|solid|svelte|node] [--mfe] [--pm npm]
       Scaffold a fresh app — vite shell + a worker-rendered island,
-      or a tsx Node service with a pooled worker.
+      or a tsx Node service with a pooled worker. --mfe scaffolds a
+      publishable MFE package (contract + worker + bundle build).
 
   ${fmt.accent('atoll init')} [--name app] [--force]
       Wire Atoll into the current project: hardened .npmrc, package
@@ -28,6 +29,8 @@ const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading
       worker      pool + typed client (+ framework bindings on UI projects)
       memory      shared-memory contract
       island      worker-rendered UI — facade (contract + lazy import) | mono
+      mfe         publishable micro-frontend — island contract + worker +
+                  vite.mfe.config.ts (build a self-contained remote bundle)
       service     nestjs: @AtollService class facade + pool module + worker
       method      nestjs: @AtollTask method-level offload
       module      nestjs: registerPool boundary module + worker entry
@@ -35,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]
@@ -43,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`)}
 `;
@@ -69,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

@@ -137,6 +137,7 @@ const ADD_KINDS = [
   'worker',
   'memory',
   'island',
+  'mfe',
   'service',
   'method',
   'module',
@@ -144,6 +145,7 @@ const ADD_KINDS = [
   'route',
   'component',
   'instrumentation',
+  'devtools',
 ] as const;
 type AddKind = (typeof ADD_KINDS)[number];
 
@@ -152,6 +154,7 @@ const KIND_SCOPE: Record<AddKind, readonly Framework[] | null> = {
   worker: null,
   memory: null,
   island: ISLAND_FRAMEWORKS,
+  mfe: ISLAND_FRAMEWORKS,
   service: ['nestjs'],
   method: ['nestjs'],
   module: ['nestjs'],
@@ -159,6 +162,7 @@ const KIND_SCOPE: Record<AddKind, readonly Framework[] | null> = {
   route: ['nextjs'],
   component: ['nextjs'],
   instrumentation: ['nextjs'],
+  devtools: null,
 };
 
 /**
@@ -281,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'));
@@ -360,6 +369,34 @@ export async function runAdd(ctx: Ctx): Promise<number> {
       return 0;
     }
 
+    case 'mfe': {
+      const dir = flag(ctx.args, 'dir') ?? rel(join(project.srcDir, 'mfe'));
+      const files = T.mfeFiles(name, framework, dir);
+      // The publish build lives at the project root beside vite.config.ts —
+      // it exists only for `vite build --config`, never the app dev server.
+      const publishCfg = rel(join(project.root!, 'vite.mfe.config.ts'));
+      // The config lives at the project root — the lib entry must be
+      // root-relative even when `add` ran from a subdirectory or --dir moved.
+      const dirFromRoot = relative(project.root!, join(ctx.cwd, dir)).replaceAll('\\', '/');
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [
+          ...files,
+          { path: publishCfg, content: T.mfePublishConfig(name, framework, dirFromRoot) },
+        ],
+        force,
+      );
+      if (missingDeps(project.pkg, ['vite']).length) {
+        ctx.io.warn(
+          `vite isn't installed — the publish build needs it: ${ctx.io.fmt.accent(pmInstallCmd(project.pm, ['-D', 'vite']))}`,
+        );
+      }
+      ctx.io.print(ctx.io.fmt.strong('\nwire it:'));
+      ctx.io.print(T.mfeUsage(name, framework, dir));
+      return 0;
+    }
+
     case 'service': {
       const dir = atollDir;
       mkdirSync(join(ctx.cwd, dir), { recursive: true });
@@ -450,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;
@@ -488,8 +573,17 @@ export async function runCreate(ctx: Ctx): Promise<number> {
   }
   mkdirSync(target, { recursive: true });
 
+  const mfe = hasFlag(ctx.args, 'mfe');
+  if (mfe && fw === 'node') {
+    ctx.io.error('--mfe is a browser-island shape — pick react|vue|solid|svelte');
+    return 1;
+  }
   const files =
-    fw === 'node' ? T.nodeScaffoldFiles(dirName) : T.scaffoldFiles(dirName, fw);
+    fw === 'node'
+      ? T.nodeScaffoldFiles(dirName)
+      : mfe
+        ? T.mfeScaffoldFiles(dirName, fw)
+        : T.scaffoldFiles(dirName, fw);
   await writeTree(ctx.io, target, files, { force: true });
 
   const written = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8'));
@@ -507,9 +601,50 @@ export async function runCreate(ctx: Ctx): Promise<number> {
 
   ctx.io.print('');
   ctx.io.print(`done — ${ctx.io.fmt.accent(`cd ${dirName} && ${pm} run dev`)}`);
+  if (mfe) {
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent('npm run build:mfe')} → dist-mfe/${dirName}.worker.js — publish behind CORS + a versioned URL`,
+    );
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent('npm run preview:mfe')} serves it cross-origin; shells mount the contract`,
+    );
+  }
   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 {