@atolljs/cli 0.1.5 → 0.1.7

package/dist/cli.js

@@ -1266,6 +1266,501 @@ const ${P}Island = lazyIsland(() => import('./islands/${name}.island'));
       return "";
   }
 }
+function mfeContractFile(name, fw) {
+  const c = camel(name);
+  const ext = ISLAND_EXT[fw] ?? "ts";
+  return {
+    path: `${name}.contract.ts`,
+    content: `import { z } from '@atolljs/core';
+import { defineIslandContract } from '@atolljs/islands';
+
+/**
+ * '${name}' \u2014 the wire contract for this micro-frontend. Shells import THIS
+ * module only: it names the app, pins the prop/event payload shapes, and
+ * carries the worker factory. The worker attaches the same module via
+ * { contract } so both sides validate one shape \u2014 drift fails loudly at
+ * mount or emit.
+ *
+ * The factory below is bundler-detectable (\`new URL(..., import.meta.url)\`)
+ * so local dev builds the worker entry automatically. Deployment changes
+ * only this field \u2014 see docs/islands-remote.md for the serving rules:
+ *
+ *   // CDN deploy \u2014 worker SCRIPT urls must stay same-origin (a cross-origin
+ *   // new Worker() throws SecurityError regardless of CORS), so the remote
+ *   // bundle loads through a same-origin blob: shim; CORS covers the
+ *   // import fetch inside it:
+ *   worker: () => {
+ *     const shim = \`import \${JSON.stringify(\`\${import.meta.env.VITE_MFE_ORIGIN}/${name}.worker.js\`)};\`;
+ *     return new Worker(
+ *       URL.createObjectURL(new Blob([shim], { type: 'text/javascript' })),
+ *       { type: 'module' },
+ *     );
+ *   },
+ *
+ *   // Or ship dist-mfe/ INSIDE the npm package \u2014 resolve the bundle
+ *   // package-relative as a plain ASSET (hoisted new URL \u2014 inline inside
+ *   // new Worker would make the consumer's bundler re-emit it as a worker
+ *   // entry instead of copying it verbatim):
+ *   const bundled = new URL('../../dist-mfe/${name}.worker.js', import.meta.url);
+ *   worker: () => new Worker(bundled, { type: 'module' }),
+ */
+export const ${c}Contract = defineIslandContract({
+  app: '${name}',
+  props: z.object({ label: z.string().optional() }),
+  events: {
+    incremented: z.object({ count: z.number(), label: z.string() }),
+  },
+  worker: () =>
+    new Worker(new URL('./${name}.worker.${ext}', import.meta.url), { type: 'module' }),
+});
+
+export default ${c}Contract;
+`
+  };
+}
+function mfeWorkerFiles(name, fw) {
+  const P = pascal(name);
+  const c = camel(name);
+  switch (fw) {
+    case "react":
+      return [
+        {
+          path: `${name}.worker.tsx`,
+          content: `import { useState } from 'react';
+import { defineReactMonoWorker, emit } from '@atolljs/react-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/**
+ * ${P} \u2014 a publishable React micro-frontend rendered INSIDE its own worker.
+ * The bundle is self-contained; deploy it behind CORS + a versioned URL.
+ */
+function ${P}({ label = '${name}' }: { label?: string }) {
+  const [count, setCount] = useState(0);
+  return (
+    <button
+      onClick={() => {
+        const n = count + 1;
+        setCount(n);
+        emit('incremented', { count: n, label }); // validates against the contract
+      }}
+    >
+      {label}: {count}
+    </button>
+  );
+}
+
+export const worker = defineReactMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "vue":
+      return [
+        {
+          path: `${P}.vue`,
+          content: `<script setup lang="ts">
+import { ref } from 'vue';
+import { emit } from '@atolljs/islands/worker';
+
+// Rendered inside the worker \u2014 ops stream to the shell; emit() validates
+// the payload against the contract before it leaves the worker.
+const props = defineProps<{ label?: string }>();
+const count = ref(0);
+function increment() {
+  count.value += 1;
+  emit('incremented', { count: count.value, label: props.label ?? '${name}' });
+}
+</script>
+
+<template>
+  <button @click="increment">{{ label ?? '${name}' }}: {{ count }}</button>
+</template>
+`
+        },
+        {
+          path: `${name}.worker.ts`,
+          content: `import { defineVueMonoWorker } from '@atolljs/vue-island/worker';
+import ${P} from './${P}.vue';
+import ${c}Contract from './${name}.contract';
+
+/** '${name}' \u2014 publishable Vue MFE, one app per worker. */
+export const worker = defineVueMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "solid":
+      return [
+        {
+          path: `${name}.worker.tsx`,
+          content: `import { createSignal } from 'solid-js';
+import { defineSolidMonoWorker, emit } from '@atolljs/solid-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/** ${P} \u2014 a publishable Solid MFE rendered inside its own worker. */
+function ${P}(props: { label?: string }) {
+  const [count, setCount] = createSignal(0);
+  return (
+    <button
+      onClick={() => {
+        const n = count() + 1;
+        setCount(n);
+        emit('incremented', { count: n, label: props.label ?? '${name}' });
+      }}
+    >
+      {props.label ?? '${name}'}: {count()}
+    </button>
+  );
+}
+
+export const worker = defineSolidMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "svelte":
+      return [
+        {
+          path: `${P}.svelte`,
+          content: `<script lang="ts">
+  import { emit } from '@atolljs/islands/worker';
+
+  // Rendered inside the worker \u2014 emit() validates against the contract.
+  let { label = '${name}' }: { label?: string } = $props();
+  let count = $state(0);
+  function increment() {
+    count += 1;
+    emit('incremented', { count, label });
+  }
+</script>
+
+<button onclick={increment}>{label}: {count}</button>
+`
+        },
+        {
+          path: `${name}.worker.ts`,
+          content: `import { defineSvelteMonoWorker } from '@atolljs/svelte-island/worker';
+import ${P} from './${P}.svelte';
+import ${c}Contract from './${name}.contract';
+
+/** '${name}' \u2014 publishable Svelte MFE, one app per worker. */
+export const worker = defineSvelteMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "angular":
+      return [
+        {
+          path: `${name}.worker.ts`,
+          content: `import '@angular/compiler'; // JIT \u2014 compiles the decorator template in the worker
+import { Component, input, output } from '@angular/core';
+import { defineAngularMonoWorker } from '@atolljs/angular-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/**
+ * ${P}Component \u2014 a publishable Angular MFE. The contract is checked against
+ * this class's input()/output() surface (IslandContract<IslandInputs<C>,
+ * IslandEvents<C>>) \u2014 a contract missing 'label' or 'incremented' fails
+ * typecheck HERE, not at the shell.
+ */
+@Component({
+  selector: 'mfe-${name}',
+  template: \`<button (click)="increment()">{{ label() }}: {{ count }}</button>\`,
+})
+export class ${P}Component {
+  readonly label = input('${name}');
+  readonly incremented = output<{ count: number; label: string }>();
+  count = 0;
+  increment(): void {
+    this.count += 1;
+    this.incremented.emit({ count: this.count, label: this.label() });
+  }
+}
+
+export const worker = defineAngularMonoWorker(${P}Component, {
+  contract: ${c}Contract,
+});
+`
+        }
+      ];
+    default:
+      return [];
+  }
+}
+function mfeFiles(name, fw, dir) {
+  return [
+    { ...mfeContractFile(name, fw), path: `${dir}/${name}.contract.ts` },
+    ...mfeWorkerFiles(name, fw).map((f) => ({ ...f, path: `${dir}/${f.path}` }))
+  ];
+}
+function mfePublishConfig(name, fw, dir = "src/mfe") {
+  const ext = ISLAND_EXT[fw] ?? "ts";
+  const plugin = SCAFFOLDS[fw]?.vitePlugin;
+  return `import { defineConfig } from 'vite';
+${plugin?.import_ ?? ""}
+/**
+ * MFE publish build \u2014 emits ONE self-contained ESM worker bundle at
+ * dist-mfe/${name}.worker.js (worker entry + framework runtime baked in;
+ * every remote import would need its own CORS headers, so ship one file).
+ *
+ * Serve it cross-origin with:
+ *   Access-Control-Allow-Origin: <shell origin>   // module workers fetch via CORS
+ *   Cache-Control: public, max-age=31536000, immutable
+ * and version the URL per release \u2014 the contract's worker factory is the
+ * cache key. docs/islands-remote.md covers the full matrix.
+ *
+ *   npm run build:mfe     \u2192 dist-mfe/${name}.worker.js
+ *   npm run preview:mfe   \u2192 serves dist-mfe with the CORS header below \u2014
+ *                           shells still need a same-origin shim entry
+ *                           (blob: or a local re-export file) since worker
+ *                           script URLs can't be cross-origin
+ */
+export default defineConfig({
+  plugins: [
+    {
+      // The worker entry imports the contract, so the contract's own worker
+      // factory lands in this bundle too \u2014 and its new URL(...) resolves
+      // the PREVIOUS dist-mfe output, inlining it into its own successor
+      // (the bundle grows every rebuild). The field is dead code here \u2014 a
+      // worker never spawns itself \u2014 so stub the URL before vite's asset
+      // plugin can resolve it.
+      name: 'mfe:stub-worker-url',
+      enforce: 'pre',
+      transform(code: string, id: string) {
+        if (!id.endsWith('${name}.contract.ts')) return null;
+        return code.replace(
+          /new URL\\(\\s*'[^']*'\\s*,\\s*import\\.meta\\.url,?\\s*\\)/,
+          "'about:blank'",
+        );
+      },
+    },
+    ${plugin?.call ?? ""}
+  ],
+  // App builds define process.env.NODE_ENV automatically; a lib-mode worker
+  // bundle doesn't, and framework dev/prod checks crash on a bare
+  // \`process\` in a browser worker.
+  define: { 'process.env.NODE_ENV': '"production"' },
+  build: {
+    outDir: 'dist-mfe',
+    minify: true,
+    lib: {
+      entry: '${dir}/${name}.worker.${ext}',
+      formats: ['es'],
+      fileName: () => '${name}.worker.js',
+    },
+  },
+  preview: {
+    headers: { 'Access-Control-Allow-Origin': '*' },
+  },
+});
+`;
+}
+function mfeUsage(name, fw, dir = "src/mfe") {
+  const c = camel(name);
+  const consume = {
+    react: `import { islandComponent } from '@atolljs/react-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />`,
+    vue: `import { islandComponent } from '@atolljs/vue-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island v-bind="{ label: '${name}', onEvent }" />`,
+    solid: `import { islandComponent } from '@atolljs/solid-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />`,
+    svelte: `import { island } from '@atolljs/svelte-island';
+import ${c}Contract from './${dir}/${name}.contract';
+<div use:island={{ app: ${c}Contract, props: { label: '${name}' }, onEvent }} />`,
+    angular: `import { islandComponent } from '@atolljs/angular-island';
+import ${c}Contract from './${dir}/${name}.contract';
+export const ${pascal(name)}Island = islandComponent({
+  contract: ${c}Contract,
+  selector: '${name}-island',
+});
+// <${name}-island [props]="{ label: '${name}' }" [onEvent]="onEvent" />`
+  };
+  return `shell side \u2014 mount through the contract, no framework import:
+${consume[fw] ?? ""}
+
+publish \u2014 \`vite build --config vite.mfe.config.ts\` emits dist-mfe/${name}.worker.js
+deploy it behind Access-Control-Allow-Origin + a versioned URL, then point the
+contract's worker factory at it (docs/islands-remote.md).`;
+}
+function mfeScaffoldFiles(appName, fw) {
+  const spec = SCAFFOLDS[fw];
+  if (!spec) return [];
+  const name = appName;
+  const P = pascal(name);
+  const files = [
+    {
+      path: "package.json",
+      content: JSON.stringify(
+        {
+          name: appName,
+          private: true,
+          type: "module",
+          // The package's PUBLIC surface is the contract module — shells
+          // import it, never the worker entry. The worker ships as a
+          // deployed asset (dist-mfe/) referenced by URL, not an import.
+          exports: { ".": `./src/mfe/${name}.contract.ts` },
+          files: ["src/mfe", "dist-mfe"],
+          scripts: {
+            dev: "vite",
+            "build:mfe": "vite build --config vite.mfe.config.ts",
+            "preview:mfe": "vite preview --config vite.mfe.config.ts"
+          },
+          dependencies: spec.deps,
+          devDependencies: spec.devDeps
+        },
+        null,
+        2
+      ) + "\n"
+    },
+    { path: "tsconfig.json", content: JSON.stringify(TSCONFIGS[fw], null, 2) + "\n" },
+    { path: "vite.config.ts", content: viteConfig(fw) },
+    { path: "vite.mfe.config.ts", content: mfePublishConfig(name, fw) },
+    { path: ".npmrc", content: NPMRC },
+    { path: ".gitignore", content: GITIGNORE + "dist-mfe/\n" },
+    { path: "index.html", content: INDEX_HTML(appName, `src/main.${ISLAND_EXT[fw]}`) },
+    ...mfeFiles(name, fw, "src/mfe")
+  ];
+  switch (fw) {
+    case "react":
+      files.push(
+        {
+          path: "src/main.tsx",
+          content: `import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`
+        },
+        {
+          path: "src/App.tsx",
+          content: `import { islandComponent } from '@atolljs/react-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+
+/** Dev harness \u2014 this page mounts the MFE exactly like a consuming shell. */
+export function App() {
+  return (
+    <main style={{ fontFamily: 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>
+        This island renders in a worker. Publish with{' '}
+        <code>npm run build:mfe</code> \u2192 <code>dist-mfe/</code>.
+      </p>
+      <${P}Island
+        label="${name}"
+        onEvent={(name, payload) => console.log('mfe event:', name, payload)}
+      />
+    </main>
+  );
+}
+`
+        }
+      );
+      break;
+    case "vue":
+      files.push(
+        { path: "src/env.d.ts", content: `declare module '*.vue';
+` },
+        {
+          path: "src/main.ts",
+          content: `import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#root');
+`
+        },
+        {
+          path: "src/App.vue",
+          content: `<script setup lang="ts">
+import { islandComponent } from '@atolljs/vue-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+const onEvent = (name: string, payload: unknown) => console.log('mfe event:', name, payload);
+</script>
+
+<template>
+  <main style="font-family: system-ui; padding: 2rem">
+    <h1>${appName}</h1>
+    <p>This island renders in a worker \u2014 <code>npm run build:mfe</code> publishes it.</p>
+    <${P}Island v-bind="{ label: '${name}', onEvent }" />
+  </main>
+</template>
+`
+        }
+      );
+      break;
+    case "solid":
+      files.push(
+        {
+          path: "src/main.tsx",
+          content: `import { render } from 'solid-js/web';
+import { App } from './App';
+
+render(() => <App />, document.getElementById('root')!);
+`
+        },
+        {
+          path: "src/App.tsx",
+          content: `import { islandComponent } from '@atolljs/solid-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+
+/** Dev harness \u2014 mounts the MFE exactly like a consuming shell. */
+export function App() {
+  return (
+    <main style={{ 'font-family': 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>
+        This island renders in a worker \u2014 <code>npm run build:mfe</code> publishes it.
+      </p>
+      <${P}Island
+        label="${name}"
+        onEvent={(name, payload) => console.log('mfe event:', name, payload)}
+      />
+    </main>
+  );
+}
+`
+        }
+      );
+      break;
+    case "svelte":
+      files.push(
+        {
+          path: "src/main.ts",
+          content: `import { mount } from 'svelte';
+import App from './App.svelte';
+
+mount(App, { target: document.getElementById('root')! });
+`
+        },
+        {
+          path: "src/App.svelte",
+          content: `<script lang="ts">
+  import { island } from '@atolljs/svelte-island';
+  import ${camel(name)}Contract from './mfe/${name}.contract';
+
+  const onEvent = (name: string, payload: unknown) => console.log('mfe event:', name, payload);
+</script>
+
+<main style="font-family: system-ui; padding: 2rem">
+  <h1>${appName}</h1>
+  <p>This island renders in a worker \u2014 <code>npm run build:mfe</code> publishes it.</p>
+  <div use:island={{ app: ${camel(name)}Contract, props: { label: '${name}' }, onEvent }} />
+</main>
+`
+        }
+      );
+      break;
+  }
+  return files;
+}
 function nestjsModuleFiles(name, dir, opts) {
   const P = pascal(name);
   const memImport = opts.mem ? `import { ${opts.mem.export_} } from '${opts.mem.import_}';
@@ -1699,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"];
@@ -1790,25 +2336,29 @@ var ADD_KINDS = [
   "worker",
   "memory",
   "island",
+  "mfe",
   "service",
   "method",
   "module",
   "housed",
   "route",
   "component",
-  "instrumentation"
+  "instrumentation",
+  "devtools"
 ];
 var KIND_SCOPE = {
   worker: null,
   memory: null,
   island: ISLAND_FRAMEWORKS,
+  mfe: ISLAND_FRAMEWORKS,
   service: ["nestjs"],
   method: ["nestjs"],
   module: ["nestjs"],
   housed: ["nestjs"],
   route: ["nextjs"],
   component: ["nextjs"],
-  instrumentation: ["nextjs"]
+  instrumentation: ["nextjs"],
+  devtools: null
 };
 var KIND_VARIANTS = {
   island: ["facade", "mono"],
@@ -1902,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"));
@@ -1974,6 +2524,29 @@ bind it: pass ${ctx.io.fmt.accent(`${c}Memory`)} as ${ctx.io.fmt.accent("sharedM
       }
       return 0;
     }
+    case "mfe": {
+      const dir = flag(ctx.args, "dir") ?? rel(join3(project.srcDir, "mfe"));
+      const files = mfeFiles(name, framework, dir);
+      const publishCfg = rel(join3(project.root, "vite.mfe.config.ts"));
+      const dirFromRoot = relative(project.root, join3(ctx.cwd, dir)).replaceAll("\\", "/");
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [
+          ...files,
+          { path: publishCfg, content: mfePublishConfig(name, framework, dirFromRoot) }
+        ],
+        force
+      );
+      if (missingDeps(project.pkg, ["vite"]).length) {
+        ctx.io.warn(
+          `vite isn't installed \u2014 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(mfeUsage(name, framework, dir));
+      return 0;
+    }
     case "service": {
       const dir = atollDir;
       mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
@@ -2058,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;
@@ -2087,7 +2699,12 @@ async function runCreate(ctx) {
     return 1;
   }
   mkdirSync2(target, { recursive: true });
-  const files = fw === "node" ? nodeScaffoldFiles(dirName) : scaffoldFiles(dirName, fw);
+  const mfe = hasFlag(ctx.args, "mfe");
+  if (mfe && fw === "node") {
+    ctx.io.error("--mfe is a browser-island shape \u2014 pick react|vue|solid|svelte");
+    return 1;
+  }
+  const files = fw === "node" ? nodeScaffoldFiles(dirName) : mfe ? mfeScaffoldFiles(dirName, fw) : scaffoldFiles(dirName, fw);
   await writeTree(ctx.io, target, files, { force: true });
   const written = JSON.parse(readFileSync2(join3(target, "package.json"), "utf8"));
   const allDeps = [
@@ -2104,8 +2721,36 @@ async function runCreate(ctx) {
   );
   ctx.io.print("");
   ctx.io.print(`done \u2014 ${ctx.io.fmt.accent(`cd ${dirName} && ${pm} run dev`)}`);
+  if (mfe) {
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent("npm run build:mfe")} \u2192 dist-mfe/${dirName}.worker.js \u2014 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;
 }
+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");
@@ -2195,9 +2840,10 @@ function runDoctor(ctx) {
 // src/cli.ts
 var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 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 \u2014 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
@@ -2207,6 +2853,8 @@ var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fm
       worker      pool + typed client (+ framework bindings on UI projects)
       memory      shared-memory contract
       island      worker-rendered UI \u2014 facade (contract + lazy import) | mono
+      mfe         publishable micro-frontend \u2014 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
@@ -2214,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]
@@ -2222,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`)}
 `;
@@ -2242,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));