@p10i/create-nestbox 0.1.0 → 0.1.2

package/INSTALL.md

@@ -10,7 +10,7 @@ For ordinary new projects, prefer the npm creator:
 npm create @p10i/nestbox@latest
 ```
 
-The published npm package is `@p10i/create-nestbox`; npm maps `npm create @p10i/nestbox` to that package. The creator scaffolds one of the two default layouts, copies `.env.example` to `.env`, copies `home/configs/opencode/instance.example.md` to `instance.md`, records npm package provenance in the instance policy, and initializes fresh installation Git history when Git is available.
+The published npm package is `@p10i/create-nestbox`; npm maps `npm create @p10i/nestbox` to that package. The creator explains and previews one of the two default layouts before writing files. The recommended layout installs at `<workspace>/.nestbox` so Nestbox stays separate from project files. The direct layout writes Nestbox files into an empty selected directory. The creator copies `.env.example` to `.env`, copies `home/configs/opencode/instance.example.md` to `instance.md`, records npm package provenance in the instance policy, and initializes fresh installation Git history when Git is available.
 
 The creator does not start Docker or collect secrets. After it finishes, edit `.env`, then run from the installation directory:
 

package/README.md

@@ -24,7 +24,7 @@ Create a new Nestbox project with npm:
 npm create @p10i/nestbox@latest
 ```
 
-The creator offers the two default layouts: install directly into the selected directory or install at `<workspace>/.nestbox`. After creation, edit `.env`, then run the Docker Compose validation and startup commands printed by the creator.
+The creator previews the exact paths before it writes files. The recommended layout installs Nestbox at `<workspace>/.nestbox` so Nestbox stays separate from your project files. You can also choose a direct install into an empty directory. After creation, edit `.env`, then run the Docker Compose validation and startup commands printed by the creator.
 
 For agent-guided installation or repair work, copy and send this to an agent with filesystem, Git, Docker, and terminal access:
 

package/bin/create-nestbox.js

@@ -49,7 +49,12 @@ function parseArgs(argv) {
 }
 
 function printHelp() {
-  console.log(`Create a Nestbox project.\n\nUsage:\n  npm create @p10i/nestbox@latest [target] [options]\n  npx @p10i/create-nestbox [target] [options]\n\nOptions:\n  --layout current|nestbox  Install directly into target or into target/.nestbox\n  --target <path>          Target directory\n  --yes, -y                Use defaults for missing prompts\n  --no-git                 Do not initialize fresh installation Git history\n  --help, -h               Show this help\n`);
+  console.log(`Create a Nestbox project.\n\nUsage:\n  npm create @p10i/nestbox@latest [workspace] [options]\n  npx @p10i/create-nestbox [workspace] [options]\n\nOptions:\n  --layout nestbox         Create <workspace>/.nestbox (recommended)\n  --layout current         Put Nestbox files directly in <workspace>\n  --target <path>          Workspace directory\n  --yes, -y                Use defaults and skip confirmation\n  --no-git                 Do not initialize fresh installation Git history\n  --help, -h               Show this help\n`);
+}
+
+function printBanner() {
+  console.log('\nNestbox Creator');
+  console.log('Create an agent-guided Docker workspace for project tools and interfaces.\n');
 }
 
 async function pathExists(path) {
@@ -70,7 +75,7 @@ async function isDirectoryEmpty(path) {
 
 function validateLayout(layout) {
   if (layout !== 'current' && layout !== 'nestbox') {
-    throw new Error('Layout must be "current" or "nestbox".');
+    throw new Error('Layout must be "nestbox" or "current".');
   }
 }
 
@@ -81,6 +86,39 @@ async function ask(question, defaultValue, rl, yes) {
   return answer || defaultValue;
 }
 
+async function askLayout(rl, yes) {
+  if (yes) return 'nestbox';
+
+  console.log('Where should Nestbox files go?');
+  console.log('  1. Keep Nestbox in .nestbox (recommended)');
+  console.log('     Creates <workspace>/.nestbox and keeps Nestbox separate from project files.');
+  console.log('  2. Put Nestbox directly in the workspace');
+  console.log('     Writes docker-compose.yaml, docker/, home/, and tests/ into the selected directory.');
+
+  while (true) {
+    const answer = (await rl.question('Choose layout [1]: ')).trim().toLowerCase();
+    if (!answer || answer === '1' || answer === 'nestbox' || answer === '.nestbox') return 'nestbox';
+    if (answer === '2' || answer === 'current' || answer === 'direct') return 'current';
+    console.log('Please choose 1 for .nestbox or 2 for direct install.');
+  }
+}
+
+async function confirmCreation(rl, yes, workspaceDir, installDir, layout) {
+  console.log('\nReview');
+  console.log(`  Workspace:    ${workspaceDir}`);
+  console.log(`  Nestbox files: ${installDir}`);
+  console.log(`  Layout:       ${layout === 'nestbox' ? 'workspace/.nestbox' : 'directly in workspace'}`);
+  console.log('  Creates:      .env, home/configs/opencode/instance.md');
+  console.log('  Does not:     start Docker or collect provider secrets');
+
+  if (yes) return;
+
+  const answer = (await rl.question('\nCreate Nestbox here? [y/N]: ')).trim().toLowerCase();
+  if (answer !== 'y' && answer !== 'yes') {
+    throw new Error('Cancelled. No files were created.');
+  }
+}
+
 async function copyTemplate(installDir) {
   for (const entry of copyEntries) {
     await cp(join(packageRoot, entry), join(installDir, entry), {
@@ -127,13 +165,13 @@ async function configureInstance(installDir, workspaceDir, layout) {
 }
 
 function commandExists(command) {
-  const result = spawnSync(command, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' });
+  const result = spawnSync(command, ['--version'], { stdio: 'ignore' });
   return result.status === 0;
 }
 
 function initGit(installDir) {
   if (!commandExists('git')) return false;
-  const result = spawnSync('git', ['init'], { cwd: installDir, stdio: 'inherit', shell: process.platform === 'win32' });
+  const result = spawnSync('git', ['init'], { cwd: installDir, stdio: 'inherit' });
   if (result.status !== 0) throw new Error('git init failed.');
   return true;
 }
@@ -147,13 +185,17 @@ async function main() {
 
   const rl = createInterface({ input, output });
   try {
-    const targetInput = options.target || await ask('Target directory', '.', rl, options.yes);
-    const layoutInput = options.layout || await ask('Layout: current or nestbox', 'nestbox', rl, options.yes);
+    printBanner();
+
+    const targetInput = options.target || await ask('Workspace directory', '.', rl, options.yes);
+    const layoutInput = options.layout || await askLayout(rl, options.yes);
     validateLayout(layoutInput);
 
     const workspaceDir = resolve(process.cwd(), targetInput);
     const installDir = layoutInput === 'nestbox' ? join(workspaceDir, '.nestbox') : workspaceDir;
 
+    await confirmCreation(rl, options.yes, workspaceDir, installDir, layoutInput);
+
     if (!(await isDirectoryEmpty(installDir))) {
       throw new Error(`Refusing to overwrite non-empty installation target: ${installDir}`);
     }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@p10i/create-nestbox",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Create Nestbox projects.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "create-nestbox": "./bin/create-nestbox.js"
+    "create-nestbox": "bin/create-nestbox.js"
   },
   "files": [
     "bin/",