@atolljs/cli 0.1.12 → 0.1.13

package/README.md

@@ -30,10 +30,12 @@ atoll new <dir> [--framework react|vue|solid|svelte|node] [--mfe] [--pm npm]
     self-contained remote bundle) + a dev harness mounting the
     island through the contract.
 
-atoll init
+atoll init [--name app] [--dir <path>] [--framework <fw>]
     Wire Atoll into the current project: .npmrc, installs the @atolljs/*
     packages your framework needs, and generates a working spine —
-    app.memory.ts + app.worker.ts + app.ts under src/atoll/.
+    app.memory.ts + app.worker.ts + app.ts under src/atoll/. --dir
+    relocates the spine; --framework overrides detection (monorepos
+    where the root package.json doesn't describe the target project).
 
 atoll add worker <name>   pooled worker + typed client (browser or node)
 atoll add memory <name>   shared-memory contract module
@@ -53,3 +55,7 @@ atoll doctor [--fix]      verify deps, lockfile, .npmrc policy,
 
 Existing files are never overwritten without `--force`; missing answers
 prompt interactively (or take defaults under `--yes` / no TTY).
+
+**Nx workspaces:** use `@atolljs/nx` — `nx g @atolljs/nx:init`,
+`nx g @atolljs/nx:worker <name>`, and `nx run <p>:atoll-doctor` wrap these
+commands with project/`sourceRoot` scoping. See `packages/nx/README.md`.

package/dist/cli.js

@@ -181,9 +181,10 @@ function missingDeps(pkg, want) {
 import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
 import { dirname as dirname2, join as join2, normalize } from "node:path";
 async function writeTree(io, cwd, files, opts = {}) {
+  const bound = normalize(opts.within ?? cwd);
   for (const f of files) {
     const abs = normalize(join2(cwd, f.path));
-    if (!abs.startsWith(normalize(cwd))) {
+    if (!abs.startsWith(bound)) {
       io.error(`refusing to write outside the project: ${io.fmt.accent(f.path)}`);
       continue;
     }
@@ -579,8 +580,8 @@ var HEADERS = `  // SharedArrayBuffer is gated behind cross-origin isolation \u2
   },`;
 var SCAFFOLDS = {
   react: {
-    deps: { react: "^19.3.0", "react-dom": "^19.3.0", "react-reconciler": "^0.34.0", "@atolljs/core": "^0.1.0", "@atolljs/react": "^0.1.0", "@atolljs/react-island": "^0.1.0", zod: "^4.6.5" },
-    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@vitejs/plugin-react": "^6.1.1", "@atolljs/vite": "^0.1.0", "@types/react": "^19.3.0", "@types/react-dom": "^19.3.0" },
+    deps: { react: "^19.3.0", "react-dom": "^19.3.0", "react-reconciler": "^0.34.0", "@atolljs/core": "^0.1.12", "@atolljs/react": "^0.1.12", "@atolljs/react-island": "^0.1.12", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@vitejs/plugin-react": "^6.1.1", "@atolljs/vite": "^0.1.12", "@types/react": "^19.3.0", "@types/react-dom": "^19.3.0" },
     // `exclude` replaces the plugin's default /node_modules/ — keep it, and
     // add *.worker.*: fast-refresh injects `/@react-refresh` (which reads
     // `window` unguarded) into every transformed module, including worker
@@ -588,19 +589,19 @@ var SCAFFOLDS = {
     vitePlugin: { pkg: "@vitejs/plugin-react", import_: `import react from '@vitejs/plugin-react';`, call: "react({ exclude: [/\\/node_modules\\//, /\\.worker\\./] })" }
   },
   vue: {
-    deps: { vue: "^3.5.43", "@atolljs/core": "^0.1.0", "@atolljs/vue": "^0.1.0", "@atolljs/vue-island": "^0.1.0", zod: "^4.6.5" },
-    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@vitejs/plugin-vue": "^6.0.9", "@atolljs/vite": "^0.1.0" },
+    deps: { vue: "^3.5.43", "@atolljs/core": "^0.1.12", "@atolljs/vue": "^0.1.12", "@atolljs/vue-island": "^0.1.12", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@vitejs/plugin-vue": "^6.0.9", "@atolljs/vite": "^0.1.12" },
     vitePlugin: { pkg: "@vitejs/plugin-vue", import_: `import vue from '@vitejs/plugin-vue';`, call: "vue()" }
   },
   solid: {
-    deps: { "solid-js": "^1.9.15", "@atolljs/core": "^0.1.0", "@atolljs/solidjs": "^0.1.0", "@atolljs/solid-island": "^0.1.0", zod: "^4.6.5" },
-    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "vite-plugin-solid": "^2.11.14", "@atolljs/vite": "^0.1.0" },
+    deps: { "solid-js": "^1.9.15", "@atolljs/core": "^0.1.12", "@atolljs/solidjs": "^0.1.12", "@atolljs/solid-island": "^0.1.12", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "vite-plugin-solid": "^2.11.14", "@atolljs/vite": "^0.1.12" },
     atollCall: `atoll({ jsxImportSource: 'solid-js' })`,
     vitePlugin: { pkg: "vite-plugin-solid", import_: `import solid from 'vite-plugin-solid';`, call: "solid()" }
   },
   svelte: {
-    deps: { svelte: "^5.57.1", "@atolljs/core": "^0.1.0", "@atolljs/svelte": "^0.1.0", "@atolljs/svelte-island": "^0.1.0", zod: "^4.6.5" },
-    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@sveltejs/vite-plugin-svelte": "^7.3.1", "@atolljs/vite": "^0.1.0" },
+    deps: { svelte: "^5.57.1", "@atolljs/core": "^0.1.12", "@atolljs/svelte": "^0.1.12", "@atolljs/svelte-island": "^0.1.12", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@sveltejs/vite-plugin-svelte": "^7.3.1", "@atolljs/vite": "^0.1.12" },
     vitePlugin: { pkg: "@sveltejs/vite-plugin-svelte", import_: `import { svelte } from '@sveltejs/vite-plugin-svelte';`, call: "svelte()" }
   }
 };
@@ -896,7 +897,7 @@ function nodeScaffoldFiles(appName) {
             start: "tsx src/main.ts",
             bundle: "esbuild src/atoll/tasks.worker.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/tasks.worker.js"
           },
-          dependencies: { "@atolljs/core": "^0.1.0", "@atolljs/node": "^0.1.0", zod: "^4.6.5" },
+          dependencies: { "@atolljs/core": "^0.1.12", "@atolljs/node": "^0.1.12", zod: "^4.6.5" },
           devDependencies: { esbuild: "^0.28.2", tsx: "^4.23.15", typescript: "^7.0.2", "@types/node": "^26.6.3" }
         },
         null,
@@ -2353,21 +2354,26 @@ async function runInit(ctx) {
     return 1;
   }
   const rel = (abs) => relative(ctx.cwd, abs).replaceAll("\\", "/");
+  const framework = flag(ctx.args, "framework") ?? project.framework;
   ctx.io.print(
     ctx.io.fmt.dim(
-      `detected: ${project.framework} \xB7 ${project.pm} \xB7 root ${project.root}`
+      `detected: ${framework} \xB7 ${project.pm} \xB7 root ${project.root}`
     )
   );
-  await writeTree(ctx.io, ctx.cwd, [{ path: rel(join3(project.root, ".npmrc")), content: NPMRC }], {
-    force: hasFlag(ctx.args, "force")
-  });
-  const atollDir = join3(project.srcDir, "atoll");
-  const host = hostOf(project.framework);
+  const within = project.root;
+  await writeTree(
+    ctx.io,
+    ctx.cwd,
+    [{ path: rel(join3(project.root, ".npmrc")), content: NPMRC }],
+    { force: hasFlag(ctx.args, "force"), within }
+  );
+  const atollDir = flag(ctx.args, "dir") ? join3(ctx.cwd, flag(ctx.args, "dir")) : join3(project.srcDir, "atoll");
+  const host = hostOf(framework);
   const name = flag(ctx.args, "name") ?? "app";
   const files = [
     { path: `${rel(atollDir)}/${name}.memory.ts`, content: memoryContract(name) }
   ];
-  if (project.framework === "nestjs") {
+  if (framework === "nestjs") {
     files.push(
       ...nestjsServiceFiles(name, rel(atollDir), {
         import_: `./${name}.memory`,
@@ -2397,11 +2403,11 @@ async function runInit(ctx) {
       }
     );
   }
-  await writeTree(ctx.io, ctx.cwd, files, { force: hasFlag(ctx.args, "force") });
-  await offerInstall(ctx, project, ATOLL_DEPS[project.framework]);
+  await writeTree(ctx.io, ctx.cwd, files, { force: hasFlag(ctx.args, "force"), within });
+  await offerInstall(ctx, project, ATOLL_DEPS[framework]);
   ctx.io.print("");
   ctx.io.print(ctx.io.fmt.strong("next steps:"));
-  if (project.framework === "nestjs") {
+  if (framework === "nestjs") {
     ctx.io.print(
       `  import ${ctx.io.fmt.accent(`${pascal(name)}Module`)} into AppModule, then inject ${ctx.io.fmt.accent(`${pascal(name)}Service`)} \u2014 ${ctx.io.fmt.accent(`service.echo('hi')`)} runs in a worker`
     );
@@ -2735,7 +2741,7 @@ bind it: pass ${ctx.io.fmt.accent(`${c}Memory`)} as ${ctx.io.fmt.accent("sharedM
           ...files,
           { path: publishCfg, content: mfePublishConfig(name, framework, dirFromRoot) }
         ],
-        force
+        { ...force, within: project.root }
       );
       if (missingDeps(project.pkg, ["vite"]).length) {
         ctx.io.warn(
@@ -2821,7 +2827,8 @@ bind it: pass ${ctx.io.fmt.accent(`${c}Memory`)} as ${ctx.io.fmt.accent("sharedM
       await writeTree(
         ctx.io,
         ctx.cwd,
-        [nextjsInstrumentationFile(name, rel(project.srcDir))],
+        // --dir names the dir instrumentation.ts lands in (default: srcDir).
+        [nextjsInstrumentationFile(name, flag(ctx.args, "dir") ?? rel(project.srcDir))],
         force
       );
       ctx.io.print(
@@ -3059,9 +3066,11 @@ var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fm
       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]
+  ${fmt.accent("atoll init")} [--name app] [--dir <path>] [--framework <fw>] [--force]
       Wire Atoll into the current project: hardened .npmrc, package
       install, and a contract + worker + client spine under src/atoll/.
+      --dir relocates the spine, --framework overrides detection \u2014 both
+      are how monorepo integrations (e.g. @atolljs/nx) scope it.
 
   ${fmt.accent("atoll add [framework] <kind> [variant] [name]")}
       worker      pool + typed client (+ framework bindings on UI projects)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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

@@ -21,9 +21,11 @@ const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading
       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]
+  ${fmt.accent('atoll init')} [--name app] [--dir <path>] [--framework <fw>] [--force]
       Wire Atoll into the current project: hardened .npmrc, package
       install, and a contract + worker + client spine under src/atoll/.
+      --dir relocates the spine, --framework overrides detection — both
+      are how monorepo integrations (e.g. @atolljs/nx) scope it.
 
   ${fmt.accent('atoll add [framework] <kind> [variant] [name]')}
       worker      pool + typed client (+ framework bindings on UI projects)

package/src/commands.ts

@@ -80,28 +80,40 @@ export async function runInit(ctx: Ctx): Promise<number> {
     return 1;
   }
   const rel = (abs: string) => relative(ctx.cwd, abs).replaceAll('\\', '/');
+  // --framework overrides detection (monorepos where the root package.json
+  // doesn't describe the target project — e.g. Nx workspaces, where the nx
+  // plugin also supplies --dir for the same reason).
+  const framework = (flag(ctx.args, 'framework') as Framework | undefined) ?? project.framework;
   ctx.io.print(
     ctx.io.fmt.dim(
-      `detected: ${project.framework} · ${project.pm} · root ${project.root}`,
+      `detected: ${framework} · ${project.pm} · root ${project.root}`,
     ),
   );
 
-  // Supply-chain baseline — the same .npmrc this repo ships.
-  await writeTree(ctx.io, ctx.cwd, [{ path: rel(join(project.root, '.npmrc')), content: T.NPMRC }], {
-    force: hasFlag(ctx.args, 'force'),
-  });
+  // Supply-chain baseline — the same .npmrc this repo ships. Written at the
+  // detected project root, which may sit ABOVE cwd (the nx plugin invokes
+  // the CLI inside a project dir) — bound the write guard to the root.
+  const within = project.root;
+  await writeTree(
+    ctx.io,
+    ctx.cwd,
+    [{ path: rel(join(project.root, '.npmrc')), content: T.NPMRC }],
+    { force: hasFlag(ctx.args, 'force'), within },
+  );
 
   // A working spine — written BEFORE the install so a failed install still
   // leaves a complete, retryable scaffold. NestJS gets the DI-native spine
   // (service facade + registerPool module + worker entry); other hosts get
   // the contract + worker + client trio.
-  const atollDir = join(project.srcDir, 'atoll');
-  const host = hostOf(project.framework);
+  const atollDir = flag(ctx.args, 'dir')
+    ? join(ctx.cwd, flag(ctx.args, 'dir')!)
+    : join(project.srcDir, 'atoll');
+  const host = hostOf(framework);
   const name = flag(ctx.args, 'name') ?? 'app';
   const files: OutFile[] = [
     { path: `${rel(atollDir)}/${name}.memory.ts`, content: T.memoryContract(name) },
   ];
-  if (project.framework === 'nestjs') {
+  if (framework === 'nestjs') {
     files.push(
       ...T.nestjsServiceFiles(name, rel(atollDir), {
         import_: `./${name}.memory`,
@@ -131,13 +143,13 @@ export async function runInit(ctx: Ctx): Promise<number> {
       },
     );
   }
-  await writeTree(ctx.io, ctx.cwd, files, { force: hasFlag(ctx.args, 'force') });
+  await writeTree(ctx.io, ctx.cwd, files, { force: hasFlag(ctx.args, 'force'), within });
 
-  await offerInstall(ctx, project, ATOLL_DEPS[project.framework]);
+  await offerInstall(ctx, project, ATOLL_DEPS[framework]);
 
   ctx.io.print('');
   ctx.io.print(ctx.io.fmt.strong('next steps:'));
-  if (project.framework === 'nestjs') {
+  if (framework === 'nestjs') {
     ctx.io.print(
       `  import ${ctx.io.fmt.accent(`${pascal(name)}Module`)} into AppModule, then inject ${ctx.io.fmt.accent(`${pascal(name)}Service`)} — ${ctx.io.fmt.accent(`service.echo('hi')`)} runs in a worker`,
     );
@@ -546,7 +558,7 @@ export async function runAdd(ctx: Ctx): Promise<number> {
           ...files,
           { path: publishCfg, content: T.mfePublishConfig(name, framework, dirFromRoot) },
         ],
-        force,
+        { ...force, within: project.root! },
       );
       if (missingDeps(project.pkg, ['vite']).length) {
         ctx.io.warn(
@@ -639,7 +651,8 @@ export async function runAdd(ctx: Ctx): Promise<number> {
       await writeTree(
         ctx.io,
         ctx.cwd,
-        [T.nextjsInstrumentationFile(name, rel(project.srcDir))],
+        // --dir names the dir instrumentation.ts lands in (default: srcDir).
+        [T.nextjsInstrumentationFile(name, flag(ctx.args, 'dir') ?? rel(project.srcDir))],
         force,
       );
       ctx.io.print(

package/src/files.ts

@@ -12,16 +12,22 @@ export interface OutFile {
  * Write a set of files under `cwd`. Existing files are never silently
  * clobbered — `--force` overwrites, interactive sessions get a prompt, and
  * non-interactive runs skip with a warning.
+ *
+ * `within` bounds where writes may land (default: `cwd`). Commands invoked
+ * from a subdirectory — e.g. the nx plugin running the CLI inside a project
+ * dir — pass the detected project root so artifacts that belong there
+ * (.npmrc, vite.mfe.config.ts) don't trip the escape guard.
  */
 export async function writeTree(
   io: Io,
   cwd: string,
   files: readonly OutFile[],
-  opts: { force?: boolean } = {},
+  opts: { force?: boolean; within?: string } = {},
 ): Promise<void> {
+  const bound = normalize(opts.within ?? cwd);
   for (const f of files) {
     const abs = normalize(join(cwd, f.path));
-    if (!abs.startsWith(normalize(cwd))) {
+    if (!abs.startsWith(bound)) {
       io.error(`refusing to write outside the project: ${io.fmt.accent(f.path)}`);
       continue;
     }

package/src/templates.ts

@@ -423,8 +423,8 @@ interface ScaffoldSpec {
 
 const SCAFFOLDS: Record<string, ScaffoldSpec> = {
   react: {
-    deps: { react: '^19.3.0', 'react-dom': '^19.3.0', 'react-reconciler': '^0.34.0', '@atolljs/core': '^0.1.0', '@atolljs/react': '^0.1.0', '@atolljs/react-island': '^0.1.0', zod: '^4.6.5' },
-    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', '@vitejs/plugin-react': '^6.1.1', '@atolljs/vite': '^0.1.0', '@types/react': '^19.3.0', '@types/react-dom': '^19.3.0' },
+    deps: { react: '^19.3.0', 'react-dom': '^19.3.0', 'react-reconciler': '^0.34.0', '@atolljs/core': '^0.1.12', '@atolljs/react': '^0.1.12', '@atolljs/react-island': '^0.1.12', zod: '^4.6.5' },
+    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', '@vitejs/plugin-react': '^6.1.1', '@atolljs/vite': '^0.1.12', '@types/react': '^19.3.0', '@types/react-dom': '^19.3.0' },
     // `exclude` replaces the plugin's default /node_modules/ — keep it, and
     // add *.worker.*: fast-refresh injects `/@react-refresh` (which reads
     // `window` unguarded) into every transformed module, including worker
@@ -432,19 +432,19 @@ const SCAFFOLDS: Record<string, ScaffoldSpec> = {
     vitePlugin: { pkg: '@vitejs/plugin-react', import_: `import react from '@vitejs/plugin-react';`, call: 'react({ exclude: [/\\/node_modules\\//, /\\.worker\\./] })' },
   },
   vue: {
-    deps: { vue: '^3.5.43', '@atolljs/core': '^0.1.0', '@atolljs/vue': '^0.1.0', '@atolljs/vue-island': '^0.1.0', zod: '^4.6.5' },
-    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', '@vitejs/plugin-vue': '^6.0.9', '@atolljs/vite': '^0.1.0' },
+    deps: { vue: '^3.5.43', '@atolljs/core': '^0.1.12', '@atolljs/vue': '^0.1.12', '@atolljs/vue-island': '^0.1.12', zod: '^4.6.5' },
+    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', '@vitejs/plugin-vue': '^6.0.9', '@atolljs/vite': '^0.1.12' },
     vitePlugin: { pkg: '@vitejs/plugin-vue', import_: `import vue from '@vitejs/plugin-vue';`, call: 'vue()' },
   },
   solid: {
-    deps: { 'solid-js': '^1.9.15', '@atolljs/core': '^0.1.0', '@atolljs/solidjs': '^0.1.0', '@atolljs/solid-island': '^0.1.0', zod: '^4.6.5' },
-    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', 'vite-plugin-solid': '^2.11.14', '@atolljs/vite': '^0.1.0' },
+    deps: { 'solid-js': '^1.9.15', '@atolljs/core': '^0.1.12', '@atolljs/solidjs': '^0.1.12', '@atolljs/solid-island': '^0.1.12', zod: '^4.6.5' },
+    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', 'vite-plugin-solid': '^2.11.14', '@atolljs/vite': '^0.1.12' },
     atollCall: `atoll({ jsxImportSource: 'solid-js' })`,
     vitePlugin: { pkg: 'vite-plugin-solid', import_: `import solid from 'vite-plugin-solid';`, call: 'solid()' },
   },
   svelte: {
-    deps: { svelte: '^5.57.1', '@atolljs/core': '^0.1.0', '@atolljs/svelte': '^0.1.0', '@atolljs/svelte-island': '^0.1.0', zod: '^4.6.5' },
-    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', '@sveltejs/vite-plugin-svelte': '^7.3.1', '@atolljs/vite': '^0.1.0' },
+    deps: { svelte: '^5.57.1', '@atolljs/core': '^0.1.12', '@atolljs/svelte': '^0.1.12', '@atolljs/svelte-island': '^0.1.12', zod: '^4.6.5' },
+    devDeps: { vite: '^8.3.1', typescript: '^7.0.2', '@sveltejs/vite-plugin-svelte': '^7.3.1', '@atolljs/vite': '^0.1.12' },
     vitePlugin: { pkg: '@sveltejs/vite-plugin-svelte', import_: `import { svelte } from '@sveltejs/vite-plugin-svelte';`, call: 'svelte()' },
   },
 };
@@ -726,7 +726,7 @@ export function nodeScaffoldFiles(appName: string): OutFile[] {
               bundle:
                 'esbuild src/atoll/tasks.worker.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/tasks.worker.js',
             },
-            dependencies: { '@atolljs/core': '^0.1.0', '@atolljs/node': '^0.1.0', zod: '^4.6.5' },
+            dependencies: { '@atolljs/core': '^0.1.12', '@atolljs/node': '^0.1.12', zod: '^4.6.5' },
             devDependencies: { esbuild: '^0.28.2', tsx: '^4.23.15', typescript: '^7.0.2', '@types/node': '^26.6.3' },
           },
           null,