@bitbybit-dev/create-app 1.3.2-rc.1 → 1.4.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (190) hide show
  1. package/README.md +47 -124
  2. package/dist/index.js +253 -21
  3. package/dist/index.js.map +1 -1
  4. package/dist/scaffold.d.ts +30 -0
  5. package/dist/scaffold.d.ts.map +1 -0
  6. package/dist/scaffold.js +107 -0
  7. package/dist/scaffold.js.map +1 -0
  8. package/package.json +4 -3
  9. package/src/index.test.ts +309 -8
  10. package/src/index.ts +285 -24
  11. package/src/scaffold.test.ts +177 -0
  12. package/src/scaffold.ts +99 -0
  13. package/templates/_agent/AGENTS.md +39 -0
  14. package/templates/_agent/CLAUDE.md +1 -0
  15. package/templates/_agent/_dot-cursor/mcp.json +5 -0
  16. package/templates/_agent/_dot-gitignore +7 -0
  17. package/templates/_agent/_dot-mcp.json +5 -0
  18. package/templates/_agent/_dot-vscode/mcp.json +5 -0
  19. package/templates/apps/drone-assembly/AGENTS.section.md +20 -0
  20. package/templates/apps/drone-assembly/README.md +35 -0
  21. package/templates/apps/drone-assembly/eslint.config.js +47 -0
  22. package/templates/apps/drone-assembly/index.html +17 -0
  23. package/templates/apps/drone-assembly/package.json +31 -0
  24. package/templates/apps/drone-assembly/public/favicon.ico +0 -0
  25. package/templates/apps/drone-assembly/public/logo.png +0 -0
  26. package/templates/apps/drone-assembly/scripts/smoke.ts +172 -0
  27. package/templates/apps/drone-assembly/src/assembly.ts +99 -0
  28. package/templates/apps/drone-assembly/src/exports.ts +10 -0
  29. package/templates/apps/drone-assembly/src/kernel.ts +14 -0
  30. package/templates/apps/drone-assembly/src/main.ts +298 -0
  31. package/templates/apps/drone-assembly/src/materials.ts +58 -0
  32. package/templates/apps/drone-assembly/src/model.ts +280 -0
  33. package/templates/apps/drone-assembly/src/parts.ts +343 -0
  34. package/templates/apps/drone-assembly/src/style.css +219 -0
  35. package/templates/apps/drone-assembly/src/ui.ts +180 -0
  36. package/templates/apps/drone-assembly/src/vite-env.d.ts +1 -0
  37. package/templates/apps/drone-assembly/tsconfig.json +29 -0
  38. package/templates/apps/laser-cut-box/AGENTS.section.md +17 -0
  39. package/templates/apps/laser-cut-box/README.md +34 -0
  40. package/templates/apps/laser-cut-box/eslint.config.js +47 -0
  41. package/templates/apps/laser-cut-box/index.html +17 -0
  42. package/templates/apps/laser-cut-box/package.json +30 -0
  43. package/templates/apps/laser-cut-box/public/favicon.ico +0 -0
  44. package/templates/apps/laser-cut-box/public/logo.png +0 -0
  45. package/templates/apps/laser-cut-box/scripts/smoke.ts +106 -0
  46. package/templates/apps/laser-cut-box/src/exports.ts +28 -0
  47. package/templates/apps/laser-cut-box/src/main.ts +176 -0
  48. package/templates/apps/laser-cut-box/src/model.ts +92 -0
  49. package/templates/apps/laser-cut-box/src/panels.ts +229 -0
  50. package/templates/apps/laser-cut-box/src/style.css +223 -0
  51. package/templates/apps/laser-cut-box/src/ui.ts +136 -0
  52. package/templates/apps/laser-cut-box/src/vite-env.d.ts +1 -0
  53. package/templates/apps/laser-cut-box/tsconfig.json +29 -0
  54. package/templates/apps/product-configurator/AGENTS.section.md +19 -0
  55. package/templates/apps/product-configurator/README.md +33 -0
  56. package/templates/apps/product-configurator/eslint.config.js +47 -0
  57. package/templates/apps/product-configurator/index.html +17 -0
  58. package/templates/apps/product-configurator/package.json +30 -0
  59. package/templates/apps/product-configurator/public/favicon.ico +0 -0
  60. package/templates/apps/product-configurator/public/logo.png +0 -0
  61. package/templates/apps/product-configurator/scripts/smoke.ts +69 -0
  62. package/templates/apps/product-configurator/src/catalog.ts +56 -0
  63. package/templates/apps/product-configurator/src/exports.ts +19 -0
  64. package/templates/apps/product-configurator/src/main.ts +134 -0
  65. package/templates/apps/product-configurator/src/model.ts +153 -0
  66. package/templates/apps/product-configurator/src/style.css +177 -0
  67. package/templates/apps/product-configurator/src/ui.ts +150 -0
  68. package/templates/apps/product-configurator/src/vite-env.d.ts +1 -0
  69. package/templates/apps/product-configurator/tsconfig.json +29 -0
  70. package/templates/apps/sheet-metal-unfold/AGENTS.section.md +26 -0
  71. package/templates/apps/sheet-metal-unfold/README.md +41 -0
  72. package/templates/apps/sheet-metal-unfold/backend/_dot-env.example +5 -0
  73. package/templates/apps/sheet-metal-unfold/backend/eslint.config.js +47 -0
  74. package/templates/apps/sheet-metal-unfold/backend/package.json +28 -0
  75. package/templates/apps/sheet-metal-unfold/backend/scripts/smoke.ts +52 -0
  76. package/templates/apps/sheet-metal-unfold/backend/src/app.ts +65 -0
  77. package/templates/apps/sheet-metal-unfold/backend/src/cloud.ts +42 -0
  78. package/templates/apps/sheet-metal-unfold/backend/src/index.ts +13 -0
  79. package/templates/apps/sheet-metal-unfold/backend/tsconfig.build.json +9 -0
  80. package/templates/apps/sheet-metal-unfold/backend/tsconfig.json +27 -0
  81. package/templates/apps/sheet-metal-unfold/frontend/eslint.config.js +47 -0
  82. package/templates/apps/sheet-metal-unfold/frontend/index.html +17 -0
  83. package/templates/apps/sheet-metal-unfold/frontend/package.json +30 -0
  84. package/templates/apps/sheet-metal-unfold/frontend/public/favicon.ico +0 -0
  85. package/templates/apps/sheet-metal-unfold/frontend/public/logo.png +0 -0
  86. package/templates/apps/sheet-metal-unfold/frontend/scripts/smoke.ts +84 -0
  87. package/templates/apps/sheet-metal-unfold/frontend/src/cloud-access.ts +37 -0
  88. package/templates/apps/sheet-metal-unfold/frontend/src/exports.ts +10 -0
  89. package/templates/apps/sheet-metal-unfold/frontend/src/flat.ts +71 -0
  90. package/templates/apps/sheet-metal-unfold/frontend/src/main.ts +193 -0
  91. package/templates/apps/sheet-metal-unfold/frontend/src/model.ts +166 -0
  92. package/templates/apps/sheet-metal-unfold/frontend/src/style.css +291 -0
  93. package/templates/apps/sheet-metal-unfold/frontend/src/ui.ts +150 -0
  94. package/templates/apps/sheet-metal-unfold/frontend/src/vite-env.d.ts +1 -0
  95. package/templates/apps/sheet-metal-unfold/frontend/tsconfig.json +29 -0
  96. package/templates/apps/sheet-metal-unfold/frontend/vite.config.ts +9 -0
  97. package/templates/apps/sheet-metal-unfold/package.json +18 -0
  98. package/templates/apps/step-to-gltf-cli/AGENTS.section.md +20 -0
  99. package/templates/apps/step-to-gltf-cli/README.md +34 -0
  100. package/templates/apps/step-to-gltf-cli/eslint.config.js +47 -0
  101. package/templates/apps/step-to-gltf-cli/package.json +26 -0
  102. package/templates/apps/step-to-gltf-cli/samples/bracket.step +2545 -0
  103. package/templates/apps/step-to-gltf-cli/scripts/smoke.ts +49 -0
  104. package/templates/apps/step-to-gltf-cli/src/cli.ts +106 -0
  105. package/templates/apps/step-to-gltf-cli/src/cloud.ts +34 -0
  106. package/templates/apps/step-to-gltf-cli/src/convert.ts +65 -0
  107. package/templates/apps/step-to-gltf-cli/src/kernel.ts +14 -0
  108. package/templates/apps/step-to-gltf-cli/tsconfig.json +27 -0
  109. package/templates/cloud/AGENTS.section.md +22 -0
  110. package/templates/cloud/backends/dotnet-rest/BitbybitClient.cs +22 -50
  111. package/templates/cloud/backends/dotnet-rest/Program.cs +1 -11
  112. package/templates/cloud/backends/dotnet-rest/dotnet-rest.csproj +4 -1
  113. package/templates/cloud/backends/hono-rest/eslint.config.js +47 -0
  114. package/templates/cloud/backends/hono-rest/package.json +11 -4
  115. package/templates/cloud/backends/hono-rest/src/bitbybit-client.ts +34 -45
  116. package/templates/cloud/backends/hono-rest/src/index.ts +1 -11
  117. package/templates/cloud/backends/hono-rest/tsconfig.json +19 -8
  118. package/templates/cloud/backends/hono-sdk/eslint.config.js +47 -0
  119. package/templates/cloud/backends/hono-sdk/package.json +12 -5
  120. package/templates/cloud/backends/hono-sdk/src/bitbybit-client.ts +6 -37
  121. package/templates/cloud/backends/hono-sdk/src/index.ts +1 -12
  122. package/templates/cloud/backends/hono-sdk/tsconfig.json +19 -8
  123. package/templates/cloud/backends/nodejs-rest/eslint.config.js +47 -0
  124. package/templates/cloud/backends/nodejs-rest/package.json +12 -5
  125. package/templates/cloud/backends/nodejs-rest/src/bitbybit-client.ts +6 -35
  126. package/templates/cloud/backends/nodejs-rest/src/index.ts +6 -16
  127. package/templates/cloud/backends/nodejs-rest/tsconfig.build.json +9 -0
  128. package/templates/cloud/backends/nodejs-rest/tsconfig.json +17 -7
  129. package/templates/cloud/backends/nodejs-sdk/eslint.config.js +47 -0
  130. package/templates/cloud/backends/nodejs-sdk/package.json +14 -7
  131. package/templates/cloud/backends/nodejs-sdk/src/bitbybit-client.ts +8 -33
  132. package/templates/cloud/backends/nodejs-sdk/src/index.ts +5 -16
  133. package/templates/cloud/backends/nodejs-sdk/tsconfig.build.json +9 -0
  134. package/templates/cloud/backends/nodejs-sdk/tsconfig.json +19 -9
  135. package/templates/cloud/frontend/eslint.config.js +50 -0
  136. package/templates/cloud/frontend/index.html +3 -1
  137. package/templates/cloud/frontend/package.json +13 -4
  138. package/templates/cloud/frontend/public/favicon.ico +0 -0
  139. package/templates/cloud/frontend/public/logo.png +0 -0
  140. package/templates/cloud/frontend/src/App.tsx +11 -9
  141. package/templates/cloud/frontend/src/api.ts +31 -0
  142. package/templates/cloud/frontend/src/components/ApiKeyWarning.tsx +28 -25
  143. package/templates/cloud/frontend/src/components/Header.tsx +4 -2
  144. package/templates/cloud/frontend/src/components/Tabs.tsx +4 -3
  145. package/templates/cloud/frontend/src/components/Viewer.tsx +57 -77
  146. package/templates/cloud/frontend/src/main.tsx +6 -1
  147. package/templates/cloud/frontend/src/panels/ModelsPanel.tsx +65 -73
  148. package/templates/cloud/frontend/src/panels/PipelinesPanel.tsx +82 -83
  149. package/templates/cloud/frontend/src/vite-env.d.ts +1 -0
  150. package/templates/cloud/frontend/tsconfig.json +19 -7
  151. package/templates/vite/babylonjs/typescript/AGENTS.section.md +13 -0
  152. package/templates/vite/babylonjs/typescript/eslint.config.js +47 -0
  153. package/templates/vite/babylonjs/typescript/index.html +4 -2
  154. package/templates/vite/babylonjs/typescript/package.json +14 -4
  155. package/templates/vite/babylonjs/typescript/public/favicon.ico +0 -0
  156. package/templates/vite/babylonjs/typescript/public/logo.png +0 -0
  157. package/templates/vite/babylonjs/typescript/scripts/smoke.ts +41 -0
  158. package/templates/vite/babylonjs/typescript/src/main.ts +8 -17
  159. package/templates/vite/babylonjs/typescript/src/model.ts +24 -0
  160. package/templates/vite/babylonjs/typescript/tsconfig.json +16 -12
  161. package/templates/vite/playcanvas/typescript/AGENTS.section.md +13 -0
  162. package/templates/vite/playcanvas/typescript/eslint.config.js +47 -0
  163. package/templates/vite/playcanvas/typescript/index.html +4 -2
  164. package/templates/vite/playcanvas/typescript/package.json +14 -4
  165. package/templates/vite/playcanvas/typescript/public/favicon.ico +0 -0
  166. package/templates/vite/playcanvas/typescript/public/logo.png +0 -0
  167. package/templates/vite/playcanvas/typescript/scripts/smoke.ts +41 -0
  168. package/templates/vite/playcanvas/typescript/src/main.ts +11 -22
  169. package/templates/vite/playcanvas/typescript/src/model.ts +24 -0
  170. package/templates/vite/playcanvas/typescript/tsconfig.json +16 -12
  171. package/templates/vite/threejs/typescript/AGENTS.section.md +13 -0
  172. package/templates/vite/threejs/typescript/eslint.config.js +47 -0
  173. package/templates/vite/threejs/typescript/index.html +4 -2
  174. package/templates/vite/threejs/typescript/package.json +16 -6
  175. package/templates/vite/threejs/typescript/public/favicon.ico +0 -0
  176. package/templates/vite/threejs/typescript/public/logo.png +0 -0
  177. package/templates/vite/threejs/typescript/scripts/smoke.ts +41 -0
  178. package/templates/vite/threejs/typescript/src/main.ts +11 -22
  179. package/templates/vite/threejs/typescript/src/model.ts +24 -0
  180. package/templates/vite/threejs/typescript/tsconfig.json +16 -12
  181. package/templates/vite/babylonjs/typescript/public/vite.svg +0 -1
  182. package/templates/vite/playcanvas/typescript/public/vite.svg +0 -1
  183. package/templates/vite/threejs/typescript/public/vite.svg +0 -1
  184. /package/templates/cloud/backends/dotnet-rest/{_gitignore → _dot-gitignore} +0 -0
  185. /package/templates/cloud/backends/hono-rest/{_gitignore → _dot-gitignore} +0 -0
  186. /package/templates/cloud/backends/hono-sdk/{_gitignore → _dot-gitignore} +0 -0
  187. /package/templates/cloud/backends/nodejs-rest/{.env.example → _dot-env.example} +0 -0
  188. /package/templates/cloud/backends/nodejs-rest/{_gitignore → _dot-gitignore} +0 -0
  189. /package/templates/cloud/backends/nodejs-sdk/{.env.example → _dot-env.example} +0 -0
  190. /package/templates/cloud/backends/nodejs-sdk/{_gitignore → _dot-gitignore} +0 -0
package/README.md CHANGED
@@ -1,163 +1,86 @@
1
1
  # @bitbybit-dev/create-app
2
2
 
3
- 🚀 **CLI tool to scaffold Bit By Bit Developers 3D/CAD projects - browser-based frontend apps and CAD Cloud backend projects**
3
+ **Scaffold a Bit By Bit Developers 3D/CAD project: a browser app on one of three game engines, a complete app template ready for a coding agent, or a CAD Cloud backend with its frontend.**
4
4
 
5
- Create stunning 3D/CAD applications with ease using our powerful geometry kernels: OCCT (OpenCascade), JSCAD, and Manifold. Or scaffold a full-stack project that connects to our [CAD Cloud API](https://learn.bitbybit.dev/api/cloud-api) for server-side model generation and file conversion.
5
+ Every project it creates runs on the open-source [Bitbybit](https://bitbybit.dev) CAD packages (OpenCascade, JSCAD and Manifold compiled to WebAssembly, MIT licensed), ships with a headless smoke test behind a strict TypeScript configuration and the ESLint rules the Bitbybit code base is held to, and comes configured for AI coding agents: an `AGENTS.md` that explains the project, and the free [Bitbybit CAD MCP](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/bitbybit-mcp) server set up for Claude Code, Cursor and VS Code, so the agent looks the API up instead of guessing it.
6
6
 
7
- ## Quick Start
8
-
9
- ### Using npm init (Recommended)
7
+ ## Quick start
10
8
 
11
9
  ```bash
12
- npm init @bitbybit-dev/app my-project
10
+ npm init @bitbybit-dev/app my-project # interactive
11
+ npm init @bitbybit-dev/app my-project -- -T laser-cut-box
12
+ npx @bitbybit-dev/create-app my-project --type frontend --engine threejs
13
13
  ```
14
14
 
15
- ### Using npx
15
+ Then:
16
16
 
17
17
  ```bash
18
- npx @bitbybit-dev/create-app my-project
18
+ cd my-project
19
+ npm install
20
+ npm run dev # the app
21
+ npm run smoke # builds the geometry headlessly in Node and prints a JSON summary
19
22
  ```
20
23
 
21
- ## Usage
24
+ ## Three kinds of project
22
25
 
23
- ### Interactive Mode
26
+ | `--type` | What you get | Runs on |
27
+ |---|---|---|
28
+ | `frontend` | A Vite + TypeScript app on Three.js, Babylon.js or PlayCanvas with all three kernels wired up, a starter model in `src/model.ts` and a smoke that builds it in Node | your users' browsers, free |
29
+ | `app` | A complete product on the packages, chosen with `--template` (below): its own UI, real exports, a smoke with domain assertions | the browser, free; one template adds CAD Cloud for a Pro algorithm and says so |
30
+ | `cloud` | A backend that calls the CAD Cloud REST API with your key (Hono on Cloudflare Workers, Express on Node, or ASP.NET Core) and a React + Three.js frontend that proxies to it | CAD Cloud, metered on your key |
24
31
 
25
- Simply run the command without options to enter interactive mode:
32
+ ### App templates (`--type app --template <id>`, or `-T <id>`)
26
33
 
27
- ```bash
28
- npm init @bitbybit-dev/app my-project
29
- ```
34
+ | Template | What it does | Exports | Needs CAD Cloud? |
35
+ |---|---|---|---|
36
+ | `product-configurator` | A parametric planter with a form, presets, and a price computed from the solid's measured volume and surface area | STEP, STL, GLB | no |
37
+ | `laser-cut-box` | A finger-jointed box from one sheet: thickness, kerf and finger width; the assembled box and the cutting layout | DXF, SVG, STEP | no |
38
+ | `sheet-metal-unfold` | A channel built in the browser and unfolded on CAD Cloud, a Pro algorithm; flat pattern with bend lines and a bend table; a forty-line backend keeps the key | DXF, STEP | yes, for the unfold only |
39
+ | `step-to-gltf-cli` | Batch STEP and IGES to GLB and STL in-process, with a JSON of facts per file; `--cloud` for serverless or volume | GLB, STL, JSON | optional |
40
+ | `drone-assembly` | A multirotor as a real assembly: twenty-seven parts placed through sub-assemblies (four, six or eight arms change only the placements), physically based materials, spinning propellers, a bill of materials | STEP assembly, GLB | no |
30
41
 
31
- You'll be prompted to select:
32
- - 📦 **App Type**: Frontend (browser 3D app) or Cloud (backend + frontend for CAD Cloud API)
33
- - 🎮 **Game Engine** (frontend): Three.js, Babylon.js, or PlayCanvas
34
- - ⚙️ **OCCT Architecture** (frontend): 32-bit, 64-bit, or 64-bit Multi-threaded
35
- - 🖥️ **Backend Template** (cloud): Hono + SDK, Hono + REST, Node.js + SDK, Node.js + REST, or .NET + REST
42
+ Every scaffold ships bitbybit.dev's favicon and logo in `public/`, linked from its page; replace them with your own. Every app template is MIT code you own. Its `README.md` explains the product, its `AGENTS.md` explains it to an agent, and its smoke pins facts about the geometry (face counts, volumes, extents, that a box's joints close) so an agent has something to iterate against. `--engine` and `--occt-architecture` do not apply to app templates: each ships its own engine (Three.js) and kernel.
36
43
 
37
- ### CLI Options
44
+ ### Frontend options
38
45
 
39
46
  ```bash
40
- npm init @bitbybit-dev/app my-project --engine threejs --occt-architecture 32
47
+ npm init @bitbybit-dev/app my-project -- --type frontend --engine babylonjs --occt-architecture 32
41
48
  ```
42
49
 
43
- Available engines:
44
- - `threejs` - Three.js: Lightweight and flexible 3D library
45
- - `babylonjs` - Babylon.js: Powerful and feature-rich game engine
46
- - `playcanvas` - PlayCanvas: Fast and lightweight WebGL game engine
47
-
48
- Available OCCT architectures:
49
- - `32` - 32-bit (Default): Supported on all browsers
50
- - `64` - 64-bit: May not be supported on all browsers (requires WebAssembly Memory64)
51
- - `64-mt` - 64-bit Multi-threaded: Requires special server configuration (COOP/COEP headers)
52
-
53
- ### OCCT Architecture Notes
54
-
55
- **32-bit (Default)**: Works on all browsers and is recommended for maximum compatibility.
56
-
57
- **64-bit**: Uses WebAssembly Memory64, which may not be available in older browsers. Use this when you need to work with larger CAD models that exceed 32-bit memory limits.
58
-
59
- **64-bit Multi-threaded**: Enables parallel processing using WebAssembly threads. Requires your server to send the following headers:
60
- - `Cross-Origin-Opener-Policy: same-origin`
61
- - `Cross-Origin-Embedder-Policy: require-corp`
62
-
63
- When you select 64-bit MT, a `vite.config.ts` is automatically created with these headers pre-configured for development.
64
-
65
- ## What You Get
66
-
67
- ### Frontend Projects
68
-
69
- Each scaffolded frontend project includes:
70
-
71
- - ⚡ **Vite** - Lightning fast build tool
72
- - 📘 **TypeScript** - Type-safe development
73
- - 🎨 **Bitbybit** - All geometry kernels pre-configured:
74
- - **OCCT** (OpenCascade) - Professional CAD kernel
75
- - **JSCAD** - Programmatic solid modeling
76
- - **Manifold** - Fast mesh boolean operations
77
- - 🎮 **Your chosen 3D engine** - Three.js, Babylon.js, or PlayCanvas
78
-
79
- ### Cloud Projects
50
+ - `--engine`: `threejs`, `babylonjs` or `playcanvas`
51
+ - `--occt-architecture`: `32` (default, every browser), `64` (WebAssembly Memory64, larger models), `64-mt` (multi-threaded; needs `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy` headers, which the generated `vite.config.ts` sets for the dev server)
80
52
 
81
- Each scaffolded cloud project includes:
82
-
83
- - 🖥️ **Your chosen backend** - Hono (Cloudflare Workers), Express 5 (Node.js), or ASP.NET Core (.NET 10)
84
- - 🌐 **React + Three.js frontend** - shared across all backends for visualizing CAD results
85
- - 🔑 **Secure API key handling** - keys stay on the server; the frontend proxies requests through your backend
86
- - 📘 **TypeScript SDK or raw REST** - depending on your chosen template
87
- - 📖 **Ready-to-run examples** - model generation, CAD pipelines, file conversion, and file uploads
88
-
89
- ## After Scaffolding
90
-
91
- Navigate to your project and start developing:
53
+ ### Cloud options
92
54
 
93
55
  ```bash
94
- cd my-project
95
- npm install
96
- npm run dev
56
+ npm init @bitbybit-dev/app my-project -- --type cloud --backend hono-sdk
97
57
  ```
98
58
 
99
- ## Project Structure
100
-
101
- ### Frontend Projects
102
-
103
- ```
104
- my-project/
105
- ├── index.html
106
- ├── package.json
107
- ├── tsconfig.json
108
- ├── public/
109
- │ └── vite.svg
110
- └── src/
111
- ├── main.ts
112
- ├── style.css
113
- └── vite-env.d.ts
114
- ```
59
+ - `--backend`: `hono-sdk`, `hono-rest`, `nodejs-sdk`, `nodejs-rest` or `dotnet-rest`
115
60
 
116
- ### Cloud Projects
61
+ The generated README says what needs CAD Cloud and where to get a key; the key goes in the backend's own secret file (`.dev.vars`, `.env` or `appsettings.Development.json`), never in the frontend.
117
62
 
118
- ```
119
- my-cloud-project/
120
- ├── README.md
121
- ├── frontend/
122
- │ ├── src/
123
- │ │ ├── App.tsx
124
- │ │ ├── components/ # Three.js viewer, header, API key warning
125
- │ │ └── panels/ # Models and Pipelines UI panels
126
- │ ├── vite.config.ts # Dev proxy: /api → localhost:3000
127
- │ └── package.json
128
- └── backend/
129
- ├── src/
130
- │ ├── index.ts # Routes
131
- │ └── bitbybit-client.ts # API calls
132
- └── package.json
133
- ```
63
+ ## Where geometry runs
134
64
 
135
- ## Use It With an AI Agent
65
+ The packages, in your own process, are the complete answer for everything they can do: they are free, and nothing of ours sits in the loop. [CAD Cloud](https://bitbybit.dev/cad-cloud) exists for Pro algorithms that are available nowhere else (the sheet-metal unfold, for one) and for compute you cannot provide, such as an edge function or file conversion at volume. Every template that touches the cloud explains this in its README and its `AGENTS.md`, keeps working without a key, and links to the [plans](https://bitbybit.dev/cad-cloud) and to [Bitbybit Studio](https://studio.bitbybit.dev/keys/billing), where keys are made.
136
66
 
137
- Scaffolding is the first half; the second is writing the geometry. An agent that does not know an API invents plausible names for it, and Bitbybit has more functions across its three CAD kernels than any model holds in memory. Connect the free **[Bitbybit CAD MCP](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/bitbybit-mcp)** server in the project this CLI just created, and your agent looks up the exact signature, parameter defaults, return type and examples for the `@bitbybit-dev` versions it installed, instead of guessing them.
67
+ ## Every project is agent-ready
138
68
 
139
- ```bash
140
- claude mcp add --transport http bitbybit https://mcp.bitbybit.dev/mcp
141
- ```
69
+ Each scaffold contains:
142
70
 
143
- Cursor, VS Code, claude.ai, ChatGPT and the Claude API connect to the same endpoint; [`npx -y @bitbybit-dev/mcp`](https://www.npmjs.com/package/@bitbybit-dev/mcp) runs the same server locally, pinned to the versions in your new project's `package.json`. [Every configuration is here](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/bitbybit-mcp).
71
+ - `AGENTS.md`, written for the agent: what the project is, the look-the-API-up rule, where geometry runs, the smoke loop, and what never to do. `CLAUDE.md` points at it.
72
+ - `.mcp.json`, `.cursor/mcp.json` and `.vscode/mcp.json`, all pointing at `https://mcp.bitbybit.dev/mcp`, the free docs server. Open the project in Claude Code, Cursor or VS Code and the agent can `describe` any function of the version you installed. Other hosts: [every configuration](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/bitbybit-mcp).
73
+ - `tsconfig.json` and `eslint.config.js`: the strict compiler flags and the type-aware lint rules every Bitbybit project is held to, at error; `npm run typecheck` and `npm run lint` run them alone.
74
+ - `npm run smoke`: the typecheck, the lint, then the geometry built headlessly in Node on the in-process kernel, printed as one JSON line, with assertions that fail loudly. Ask the agent for a change; it runs the smoke and reads the counts.
144
75
 
145
- With a [CAD Cloud](https://bitbybit.dev/cad-cloud) key, the [Bitbybit CAD Cloud MCP](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/cad-cloud-mcp) goes further and lets the agent run the geometry for you - measure a STEP file, run a pipeline, convert to glTF - and hand back the results as files. For assistants that cannot speak MCP, the whole API is also published as [context files](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/prompt-contexts). The [AI section of the documentation](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/intro) explains all of it.
76
+ For offline or exact-version answers, `npx -y @bitbybit-dev/mcp` runs the same server locally, pinned to the packages in the project's `node_modules`.
146
77
 
147
78
  ## Links
148
79
 
149
- - 🌐 **Website**: [https://bitbybit.dev](https://bitbybit.dev)
150
- - 📚 **Documentation**: [https://learn.bitbybit.dev](https://learn.bitbybit.dev)
151
- - 🤖 **Using AI with Bitbybit**: [https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/intro](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/intro)
152
- - 💬 **Discord Community**: [https://discord.gg/GSe3VMe](https://discord.gg/GSe3VMe)
153
- - 🐛 **Issues**: [https://github.com/bitbybit-dev/bitbybit/issues](https://github.com/bitbybit-dev/bitbybit/issues)
154
- - 📦 **Monorepo**: [https://github.com/bitbybit-dev/bitbybit](https://github.com/bitbybit-dev/bitbybit)
155
-
156
- ## Support Us
157
-
158
- ⭐ **The best way to support Bit By Bit Developers is with a Silver or Gold plan subscription!**
159
-
160
- [Subscribe Now](https://bitbybit.dev/auth/pick-plan)
80
+ - [Documentation](https://learn.bitbybit.dev) and [the npm packages](https://learn.bitbybit.dev/learn/npm-packages/intro)
81
+ - [Using AI with Bitbybit](https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/intro)
82
+ - [CAD Cloud](https://bitbybit.dev/cad-cloud) and the [REST API](https://learn.bitbybit.dev/api/cloud-api)
83
+ - [Discord](https://discord.gg/GSe3VMe), [issues](https://github.com/bitbybit-dev/bitbybit/issues), [the monorepo](https://github.com/bitbybit-dev/bitbybit)
161
84
 
162
85
  ## License
163
86
 
package/dist/index.js CHANGED
@@ -7,8 +7,11 @@ import ora from "ora";
7
7
  import fs from "fs-extra";
8
8
  import path from "path";
9
9
  import { fileURLToPath } from "url";
10
+ import { AGENT_SECTION_FILE, applyAgentLayer, listFiles, restoreTemplateDotfiles } from "./scaffold.js";
10
11
  const __filename = fileURLToPath(import.meta.url);
11
12
  const __dirname = path.dirname(__filename);
13
+ const CLI_VERSION = "1.4.0-rc.0";
14
+ const TEMPLATES_ROOT = path.join(__dirname, "..", "templates");
12
15
  const BITBYBIT_LOGO = `
13
16
  ╭──────────────────────────────────────────────────────────────────────╮
14
17
  │ │
@@ -19,6 +22,34 @@ const BITBYBIT_LOGO = `
19
22
  │ 3D CAD Development on the Web │
20
23
  ╰──────────────────────────────────────────────────────────────────────╯
21
24
  `;
25
+ const APP_TEMPLATES = {
26
+ "product-configurator": {
27
+ name: "Product configurator",
28
+ description: "A parametric planter with its own form, a live price from the measured solid, presets and STEP, STL and GLB downloads",
29
+ cloud: false,
30
+ },
31
+ "laser-cut-box": {
32
+ name: "Laser-cut box",
33
+ description: "A finger-jointed box from one sheet: thickness, kerf and finger width, the assembled box and the cutting layout, DXF, SVG and STEP downloads",
34
+ cloud: false,
35
+ },
36
+ "sheet-metal-unfold": {
37
+ name: "Sheet-metal unfold",
38
+ description: "A channel built in the browser and unfolded on CAD Cloud, a Pro algorithm: flat pattern with bend lines, DXF and STEP; a small backend keeps the key",
39
+ cloud: true,
40
+ },
41
+ "step-to-gltf-cli": {
42
+ name: "STEP to glTF command line",
43
+ description: "Batch STEP and IGES to GLB and STL in-process on the open-source kernel, with a JSON of facts per file; --cloud for serverless or volume",
44
+ cloud: false,
45
+ },
46
+ "drone-assembly": {
47
+ name: "Drone assembly",
48
+ description: "A multirotor built as a real assembly: twenty-seven parts placed through sub-assemblies, physically based materials, spinning propellers, a bill of materials, STEP and GLB exports that keep the tree",
49
+ cloud: false,
50
+ },
51
+ };
52
+ const APP_TEMPLATE_IDS = Object.keys(APP_TEMPLATES);
22
53
  const ENGINE_DISPLAY_NAMES = {
23
54
  "threejs": "Three.js",
24
55
  "babylonjs": "Babylon.js",
@@ -58,6 +89,13 @@ const BACKEND_DESCRIPTIONS = {
58
89
  "nodejs-rest": "Raw fetch calls on Node.js with Express 5",
59
90
  "dotnet-rest": "HttpClient calls on ASP.NET Core minimal API (.NET 10)",
60
91
  };
92
+ const BACKEND_SECRET_FILES = {
93
+ "hono-sdk": ".dev.vars",
94
+ "hono-rest": ".dev.vars",
95
+ "nodejs-sdk": ".env",
96
+ "nodejs-rest": ".env",
97
+ "dotnet-rest": "appsettings.Development.json",
98
+ };
61
99
  const BACKEND_COLORS = {
62
100
  "hono-sdk": chalk.hex("#FF6633"),
63
101
  "hono-rest": chalk.hex("#FF6633"),
@@ -65,7 +103,7 @@ const BACKEND_COLORS = {
65
103
  "nodejs-rest": chalk.hex("#68A063"),
66
104
  "dotnet-rest": chalk.hex("#512BD4"),
67
105
  };
68
- async function displayWelcome() {
106
+ function displayWelcome() {
69
107
  console.clear();
70
108
  const goldGradient = gradient(["#F0CEBB", "#fff6f3", "#d6b39f", "#F0CEBB"]);
71
109
  console.log(goldGradient(BITBYBIT_LOGO));
@@ -103,6 +141,11 @@ async function promptAppType() {
103
141
  value: "cloud",
104
142
  short: "CAD Cloud App"
105
143
  },
144
+ {
145
+ name: `${chalk.hex("#F0CEBB")("● App Template")} ${chalk.gray("- A complete, agent-ready product on the packages: a configurator, a laser-cut box, ...")}`,
146
+ value: "app",
147
+ short: "App Template"
148
+ },
106
149
  ],
107
150
  default: "frontend"
108
151
  }
@@ -178,6 +221,41 @@ async function promptCloudProjectOptions(projectNameArg) {
178
221
  backend: answers.backend,
179
222
  };
180
223
  }
224
+ async function promptAppTemplate(projectNameArg) {
225
+ const choices = APP_TEMPLATE_IDS.map((id) => {
226
+ const template = APP_TEMPLATES[id];
227
+ const marker = template.cloud ? chalk.hex("#FF6633")(" (needs CAD Cloud)") : "";
228
+ return {
229
+ name: `${chalk.hex("#F0CEBB")(`● ${template.name}`)}${marker} ${chalk.gray(`- ${template.description}`)}`,
230
+ value: id,
231
+ short: template.name,
232
+ };
233
+ });
234
+ const questions = [
235
+ ...(projectNameArg ? [] : [{
236
+ type: "input",
237
+ name: "projectName",
238
+ message: chalk.cyan("📁 What is your project name?"),
239
+ default: "my-bitbybit-app",
240
+ validate: (input) => {
241
+ if (!input.trim())
242
+ return "Project name is required";
243
+ if (!/^[a-z0-9-_]+$/i.test(input))
244
+ return "Project name can only contain letters, numbers, hyphens, and underscores";
245
+ return true;
246
+ }
247
+ }]),
248
+ {
249
+ type: "list",
250
+ name: "template",
251
+ message: chalk.cyan("🧩 Which app template would you like to start from?"),
252
+ choices,
253
+ default: APP_TEMPLATE_IDS[0],
254
+ },
255
+ ];
256
+ const answers = await inquirer.prompt(questions);
257
+ return { projectName: projectNameArg || answers.projectName, template: answers.template };
258
+ }
181
259
  async function promptProjectOptions(projectNameArg) {
182
260
  const occtArchitectureChoices = [
183
261
  {
@@ -288,17 +366,6 @@ async function promptProjectOptions(projectNameArg) {
288
366
  occtArchitecture: answers.occtArchitecture
289
367
  };
290
368
  }
291
- /**
292
- * npm strips every file named .gitignore out of a package tarball, so the templates carry theirs as
293
- * _gitignore and each copied template restores the name here. Without it a scaffolded backend
294
- * arrives with the .env this CLI writes for it and nothing ignoring that file.
295
- */
296
- async function restoreTemplateDotfiles(dir) {
297
- const staged = path.join(dir, "_gitignore");
298
- if (await fs.pathExists(staged)) {
299
- await fs.move(staged, path.join(dir, ".gitignore"), { overwrite: true });
300
- }
301
- }
302
369
  async function createProject(options) {
303
370
  const { projectName, engine, bundler, language, occtArchitecture } = options;
304
371
  const targetDir = path.resolve(process.cwd(), projectName);
@@ -342,7 +409,7 @@ async function createProject(options) {
342
409
  color: "cyan"
343
410
  }).start();
344
411
  try {
345
- const templateDir = path.join(__dirname, "..", "templates", bundler, engine, language);
412
+ const templateDir = path.join(TEMPLATES_ROOT, bundler, engine, language);
346
413
  if (!fs.existsSync(templateDir)) {
347
414
  spinner.fail("Template not found");
348
415
  console.error(chalk.red(`\n ✖ Template for ${bundler}/${engine}/${language} not found.`));
@@ -350,7 +417,7 @@ async function createProject(options) {
350
417
  process.exit(1);
351
418
  }
352
419
  await fs.copy(templateDir, targetDir);
353
- await restoreTemplateDotfiles(targetDir);
420
+ await applyAgentLayer(TEMPLATES_ROOT, targetDir, { PROJECT_NAME: projectName, TEMPLATE_ID: `vite-${engine}`, CLI_VERSION });
354
421
  spinner.succeed("Project structure created");
355
422
  const packageJsonPath = path.join(targetDir, "package.json");
356
423
  if (fs.existsSync(packageJsonPath)) {
@@ -422,6 +489,12 @@ export default defineConfig({
422
489
  console.log(chalk.gray(" 3. Start the development server:"));
423
490
  console.log(chalk.cyan(" npm run dev"));
424
491
  console.log();
492
+ console.log(chalk.gray(" 4. Build the model headlessly and read its summary:"));
493
+ console.log(chalk.cyan(" npm run smoke"));
494
+ console.log();
495
+ console.log(chalk.gray(" Your coding agent is set up: AGENTS.md explains the project, and the"));
496
+ console.log(chalk.gray(" Bitbybit CAD MCP is configured for Claude Code, Cursor and VS Code."));
497
+ console.log();
425
498
  if (occtArchitecture === "64") {
426
499
  console.log(chalk.yellow(" ⚠️ Note: 64-bit OCCT may not be supported on all browsers."));
427
500
  console.log(chalk.gray(" Some older browsers may lack WebAssembly Memory64 support."));
@@ -582,6 +655,22 @@ ${backend === "dotnet-rest" ? ` ├── Program.cs
582
655
  | \`POST\` | \`/api/pipeline/file-input\` | Pipeline: file upload + fillet |
583
656
  | \`GET\` | \`/api/proxy-download?url=...\` | Proxy glTF downloads (avoids CORS) |
584
657
 
658
+ ## What Needs CAD Cloud and Where to Get It
659
+
660
+ Everything this app renders is computed on CAD Cloud. That is the point of this template: it is the hosted-compute case, for a backend that cannot host the CAD kernels (a Cloudflare Worker, a .NET server) or chooses not to. If your geometry could run in your users' browsers, or in a Node server with the memory for a kernel, the free open-source packages are the whole answer and \`npm init @bitbybit-dev/app\` has Vite templates for that; nothing of Bitbybit's sits in the loop there.
661
+
662
+ | | |
663
+ |---|---|
664
+ | What goes to the cloud | every backend route that creates a task, runs a pipeline, uploads a file or fetches a result |
665
+ | Plan needed | any [CAD Cloud plan](https://bitbybit.dev/cad-cloud); the key needs the \`cad\`, \`files\` and \`tasks\` scopes |
666
+ | Where keys live | [Bitbybit Studio](https://studio.bitbybit.dev/keys/billing), which also shows the tasks this app ran and what they cost |
667
+ | Where the key goes | \`backend/${BACKEND_SECRET_FILES[backend]}\`, already covered by \`backend/.gitignore\`; never anywhere else |
668
+ | Without a key | every \`/api/*\` route answers 503 and the frontend explains this with the links above; the app is not broken, it is waiting for a key |
669
+
670
+ ## Use It With an Agent
671
+
672
+ \`AGENTS.md\` (which \`CLAUDE.md\` points at) explains the project to a coding agent, and the free Bitbybit CAD MCP server is configured in \`.mcp.json\` (Claude Code), \`.cursor/mcp.json\` (Cursor) and \`.vscode/mcp.json\` (VS Code), so the agent looks the API up instead of guessing it. \`npm run smoke\` in \`frontend/\` and \`backend/\` typechecks each against the pinned packages; that is the loop an agent iterates against without a key.
673
+
585
674
  ## Getting an API Key
586
675
 
587
676
  1. Create an account on [bitbybit.dev](https://bitbybit.dev)
@@ -634,7 +723,7 @@ async function createCloudProject(options) {
634
723
  color: "cyan"
635
724
  }).start();
636
725
  try {
637
- const cloudTemplatesDir = path.join(__dirname, "..", "templates", "cloud");
726
+ const cloudTemplatesDir = path.join(TEMPLATES_ROOT, "cloud");
638
727
  const frontendTemplateDir = path.join(cloudTemplatesDir, "frontend");
639
728
  const frontendTargetDir = path.join(targetDir, "frontend");
640
729
  await fs.copy(frontendTemplateDir, frontendTargetDir);
@@ -679,6 +768,15 @@ async function createCloudProject(options) {
679
768
  await fs.writeJson(path.join(backendTargetDir, "appsettings.Development.json"), devSettings, { spaces: 2 });
680
769
  }
681
770
  await fs.writeFile(path.join(targetDir, "README.md"), generateCloudReadme(projectName, backend), "utf-8");
771
+ await applyAgentLayer(TEMPLATES_ROOT, targetDir, {
772
+ PROJECT_NAME: projectName,
773
+ TEMPLATE_ID: `cloud-${backend}`,
774
+ CLI_VERSION,
775
+ BACKEND_NAME: BACKEND_DISPLAY_NAMES[backend],
776
+ SECRET_FILE: BACKEND_SECRET_FILES[backend],
777
+ BACKEND_START: backend === "dotnet-rest" ? "cd backend && dotnet run" : "cd backend && npm install && npm run dev",
778
+ BACKEND_SMOKE: backend === "dotnet-rest" ? "dotnet build" : "npm run smoke",
779
+ }, path.join(cloudTemplatesDir, AGENT_SECTION_FILE));
682
780
  spinner.succeed("Project structure created");
683
781
  console.log();
684
782
  console.log(chalk.gray("─".repeat(72)));
@@ -722,6 +820,9 @@ async function createCloudProject(options) {
722
820
  console.log();
723
821
  console.log(chalk.gray(" 5. Open ") + chalk.cyan("http://localhost:5173") + chalk.gray(" in your browser"));
724
822
  console.log();
823
+ console.log(chalk.gray(" Your coding agent is set up: AGENTS.md explains the project and what needs"));
824
+ console.log(chalk.gray(" CAD Cloud, and the Bitbybit CAD MCP is configured for Claude Code, Cursor and VS Code."));
825
+ console.log();
725
826
  console.log(chalk.gray("─".repeat(72)));
726
827
  console.log();
727
828
  console.log(chalk.yellow.bold(" 🔑 You need a Bitbybit API key to use CAD Cloud:"));
@@ -740,32 +841,163 @@ async function createCloudProject(options) {
740
841
  process.exit(1);
741
842
  }
742
843
  }
844
+ /**
845
+ * A template that needs a secret ships an .env.example beside the code that reads it; the scaffold
846
+ * gets an .env copied from it so the first run finds the file and the variable, empty. The same
847
+ * probe the cloud templates use, for any depth.
848
+ */
849
+ async function writeEnvFromExamples(dir) {
850
+ for (const example of await listFiles(dir)) {
851
+ if (path.basename(example) !== ".env.example")
852
+ continue;
853
+ const env = path.join(path.dirname(example), ".env");
854
+ if (!(await fs.pathExists(env)))
855
+ await fs.copy(example, env);
856
+ }
857
+ }
858
+ async function createAppProject(options) {
859
+ const { projectName, template } = options;
860
+ const targetDir = path.resolve(process.cwd(), projectName);
861
+ const meta = APP_TEMPLATES[template];
862
+ console.log();
863
+ console.log(chalk.gray("─".repeat(72)));
864
+ console.log();
865
+ console.log(chalk.white.bold(" 📋 Project Configuration:"));
866
+ console.log();
867
+ console.log(` ${chalk.gray("Project:")} ${chalk.white.bold(projectName)}`);
868
+ console.log(` ${chalk.gray("Type:")} ${chalk.hex("#F0CEBB")("App Template")}`);
869
+ console.log(` ${chalk.gray("Template:")} ${chalk.hex("#F0CEBB")(meta.name)} ${chalk.gray(`(${template})`)}`);
870
+ console.log(` ${chalk.gray("Runs on:")} ${meta.cloud ? chalk.hex("#FF6633")("the packages + CAD Cloud (API key needed)") : chalk.green("the open-source packages, in the browser")}`);
871
+ console.log();
872
+ console.log(chalk.gray("─".repeat(72)));
873
+ console.log();
874
+ if (fs.existsSync(targetDir)) {
875
+ const { overwrite } = await inquirer.prompt([
876
+ {
877
+ type: "confirm",
878
+ name: "overwrite",
879
+ message: chalk.yellow(`⚠️ Directory "${projectName}" already exists. Do you want to overwrite it?`),
880
+ default: false
881
+ }
882
+ ]);
883
+ if (!overwrite) {
884
+ console.log(chalk.red("\n ✖ Project creation cancelled.\n"));
885
+ process.exit(0);
886
+ }
887
+ const spinner = ora("Removing existing directory...").start();
888
+ await fs.remove(targetDir);
889
+ spinner.succeed("Existing directory removed");
890
+ }
891
+ const spinner = ora({ text: "Creating project structure...", color: "cyan" }).start();
892
+ try {
893
+ const templateDir = path.join(TEMPLATES_ROOT, "apps", template);
894
+ if (!fs.existsSync(templateDir)) {
895
+ throw new Error(`The ${template} template is listed but its files are not at ${templateDir}.`);
896
+ }
897
+ await fs.copy(templateDir, targetDir);
898
+ await applyAgentLayer(TEMPLATES_ROOT, targetDir, { PROJECT_NAME: projectName, TEMPLATE_ID: template, CLI_VERSION });
899
+ await writeEnvFromExamples(targetDir);
900
+ const packageJsonPath = path.join(targetDir, "package.json");
901
+ if (fs.existsSync(packageJsonPath)) {
902
+ const packageJson = await fs.readJson(packageJsonPath);
903
+ packageJson.name = projectName;
904
+ await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
905
+ }
906
+ spinner.succeed("Project structure created");
907
+ console.log();
908
+ console.log(chalk.gray("─".repeat(72)));
909
+ console.log();
910
+ console.log(chalk.gray(" Home: ") + chalk.underline.cyan("https://bitbybit.dev"));
911
+ console.log(chalk.gray(" Learn: ") + chalk.underline.cyan("https://learn.bitbybit.dev"));
912
+ console.log(chalk.gray(" Community: ") + chalk.underline.cyan("https://discord.gg/GSe3VMe"));
913
+ console.log(chalk.gray(" GitHub: ") + chalk.underline.cyan("https://github.com/bitbybit-dev/bitbybit"));
914
+ console.log();
915
+ console.log(chalk.green.bold(` ✔ ${meta.name} created successfully! 🎉`));
916
+ console.log();
917
+ console.log(chalk.white(" Next steps:"));
918
+ console.log();
919
+ console.log(chalk.gray(" 1. Navigate to your project:"));
920
+ console.log(chalk.cyan(` cd ${projectName}`));
921
+ console.log();
922
+ console.log(chalk.gray(" 2. Install dependencies:"));
923
+ console.log(chalk.cyan(" npm install"));
924
+ console.log();
925
+ console.log(chalk.gray(" 3. Start the development server:"));
926
+ console.log(chalk.cyan(" npm run dev"));
927
+ console.log();
928
+ console.log(chalk.gray(" 4. Build the model headlessly and read its summary:"));
929
+ console.log(chalk.cyan(" npm run smoke"));
930
+ console.log();
931
+ console.log(chalk.gray(" README.md explains the app; AGENTS.md explains it to your coding agent, and the"));
932
+ console.log(chalk.gray(" Bitbybit CAD MCP is configured for Claude Code, Cursor and VS Code."));
933
+ console.log();
934
+ if (meta.cloud) {
935
+ console.log(chalk.yellow.bold(" 🔑 This template runs part of its work on CAD Cloud and needs an API key:"));
936
+ console.log(chalk.yellow(" README.md says what needs the cloud and why; plans and keys are at"));
937
+ console.log(chalk.underline.yellow(" https://bitbybit.dev/cad-cloud"));
938
+ console.log();
939
+ }
940
+ console.log(chalk.gray("─".repeat(72)));
941
+ console.log();
942
+ console.log(chalk.white(" Happy coding! 💻✨"));
943
+ console.log();
944
+ }
945
+ catch (error) {
946
+ spinner.fail("Failed to create project");
947
+ console.error(chalk.red("\n ✖ Error creating project:"), error);
948
+ process.exit(1);
949
+ }
950
+ }
743
951
  async function main() {
744
952
  const program = new Command();
745
953
  program
746
954
  .name("@bitbybit-dev/create-app")
747
955
  .description("Scaffold a new Bit By Bit Developers 3D/CAD project")
748
- .version("1.3.2-rc.1")
956
+ .version(CLI_VERSION)
749
957
  .argument("[project-name]", "Name of the project to create")
750
958
  .option("-e, --engine <engine>", "Game engine to use (threejs, babylonjs, playcanvas)")
751
959
  .option("-o, --occt-architecture <arch>", "OCCT worker architecture (32, 64, 64-mt). Default: 32")
752
- .option("-t, --type <type>", "App type (frontend, cloud)")
960
+ .option("-t, --type <type>", "App type (frontend, cloud, app)")
753
961
  .option("-b, --backend <backend>", "Backend for cloud app (hono-sdk, hono-rest, nodejs-sdk, nodejs-rest, dotnet-rest)")
962
+ .option("-T, --template <template>", `App template for --type app (${APP_TEMPLATE_IDS.join(", ")})`)
754
963
  .action(async (projectName, cmdOptions) => {
755
- await displayWelcome();
964
+ displayWelcome();
756
965
  let appType;
757
966
  if (cmdOptions.type) {
758
- if (cmdOptions.type !== "frontend" && cmdOptions.type !== "cloud") {
967
+ if (cmdOptions.type !== "frontend" && cmdOptions.type !== "cloud" && cmdOptions.type !== "app") {
759
968
  console.error(chalk.red(`\n ✖ Invalid app type: ${cmdOptions.type}`));
760
- console.error(chalk.gray(` Valid options: frontend, cloud`));
969
+ console.error(chalk.gray(` Valid options: frontend, cloud, app`));
761
970
  process.exit(1);
762
971
  }
763
972
  appType = cmdOptions.type;
764
973
  }
974
+ else if (cmdOptions.template) {
975
+ appType = "app";
976
+ }
765
977
  else {
766
978
  appType = await promptAppType();
767
979
  }
768
- if (appType === "cloud") {
980
+ if (appType === "app") {
981
+ if (cmdOptions.template && !APP_TEMPLATE_IDS.includes(cmdOptions.template)) {
982
+ console.error(chalk.red(`\n ✖ Invalid app template: ${cmdOptions.template}`));
983
+ console.error(chalk.gray(` Valid options: ${APP_TEMPLATE_IDS.join(", ")}`));
984
+ process.exit(1);
985
+ }
986
+ if (cmdOptions.engine || cmdOptions.occtArchitecture) {
987
+ console.log(chalk.yellow(" Note: --engine and --occt-architecture do not apply to an app template (each ships its own engine and kernel) and are ignored."));
988
+ }
989
+ let appOptions;
990
+ if (projectName && cmdOptions.template) {
991
+ appOptions = { projectName, template: cmdOptions.template };
992
+ }
993
+ else {
994
+ appOptions = await promptAppTemplate(projectName);
995
+ if (cmdOptions.template)
996
+ appOptions.template = cmdOptions.template;
997
+ }
998
+ await createAppProject(appOptions);
999
+ }
1000
+ else if (appType === "cloud") {
769
1001
  if (cmdOptions.backend) {
770
1002
  const validBackends = ["hono-sdk", "hono-rest", "nodejs-sdk", "nodejs-rest", "dotnet-rest"];
771
1003
  if (!validBackends.includes(cmdOptions.backend)) {