@bitbybit-dev/create-app 1.3.2 → 1.4.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/src/index.ts CHANGED
@@ -8,10 +8,14 @@ import ora from "ora";
8
8
  import fs from "fs-extra";
9
9
  import path from "path";
10
10
  import { fileURLToPath } from "url";
11
+ import { AGENT_SECTION_FILE, applyAgentLayer, listFiles, restoreTemplateDotfiles } from "./scaffold.js";
11
12
 
12
13
  const __filename = fileURLToPath(import.meta.url);
13
14
  const __dirname = path.dirname(__filename);
14
15
 
16
+ const CLI_VERSION = "1.4.0";
17
+ const TEMPLATES_ROOT = path.join(__dirname, "..", "templates");
18
+
15
19
  const BITBYBIT_LOGO = `
16
20
  ╭──────────────────────────────────────────────────────────────────────╮
17
21
  │ │
@@ -36,7 +40,50 @@ interface CloudProjectOptions {
36
40
  backend: "hono-sdk" | "hono-rest" | "nodejs-sdk" | "nodejs-rest" | "dotnet-rest";
37
41
  }
38
42
 
39
- type AppType = "frontend" | "cloud";
43
+ type AppType = "frontend" | "cloud" | "app";
44
+
45
+ type AppTemplateId = "product-configurator" | "laser-cut-box" | "sheet-metal-unfold" | "step-to-gltf-cli" | "drone-assembly";
46
+
47
+ interface AppTemplate {
48
+ name: string;
49
+ description: string;
50
+ cloud: boolean;
51
+ }
52
+
53
+ const APP_TEMPLATES: Record<AppTemplateId, AppTemplate> = {
54
+ "product-configurator": {
55
+ name: "Product configurator",
56
+ description: "A parametric planter with its own form, a live price from the measured solid, presets and STEP, STL and GLB downloads",
57
+ cloud: false,
58
+ },
59
+ "laser-cut-box": {
60
+ name: "Laser-cut box",
61
+ 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",
62
+ cloud: false,
63
+ },
64
+ "sheet-metal-unfold": {
65
+ name: "Sheet-metal unfold",
66
+ 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",
67
+ cloud: true,
68
+ },
69
+ "step-to-gltf-cli": {
70
+ name: "STEP to glTF command line",
71
+ 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",
72
+ cloud: false,
73
+ },
74
+ "drone-assembly": {
75
+ name: "Drone assembly",
76
+ 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",
77
+ cloud: false,
78
+ },
79
+ };
80
+
81
+ const APP_TEMPLATE_IDS = Object.keys(APP_TEMPLATES) as AppTemplateId[];
82
+
83
+ interface AppProjectOptions {
84
+ projectName: string;
85
+ template: AppTemplateId;
86
+ }
40
87
 
41
88
  type EngineType = "threejs" | "babylonjs" | "playcanvas";
42
89
  type OcctArchitectureType = "32" | "64" | "64-mt";
@@ -88,6 +135,14 @@ const BACKEND_DESCRIPTIONS: Record<BackendType, string> = {
88
135
  "dotnet-rest": "HttpClient calls on ASP.NET Core minimal API (.NET 10)",
89
136
  };
90
137
 
138
+ const BACKEND_SECRET_FILES: Record<BackendType, string> = {
139
+ "hono-sdk": ".dev.vars",
140
+ "hono-rest": ".dev.vars",
141
+ "nodejs-sdk": ".env",
142
+ "nodejs-rest": ".env",
143
+ "dotnet-rest": "appsettings.Development.json",
144
+ };
145
+
91
146
  const BACKEND_COLORS: Record<BackendType, (text: string) => string> = {
92
147
  "hono-sdk": chalk.hex("#FF6633"),
93
148
  "hono-rest": chalk.hex("#FF6633"),
@@ -96,7 +151,7 @@ const BACKEND_COLORS: Record<BackendType, (text: string) => string> = {
96
151
  "dotnet-rest": chalk.hex("#512BD4"),
97
152
  };
98
153
 
99
- async function displayWelcome(): Promise<void> {
154
+ function displayWelcome(): void {
100
155
  console.clear();
101
156
  const goldGradient = gradient(["#F0CEBB", "#fff6f3", "#d6b39f", "#F0CEBB"]);
102
157
 
@@ -136,6 +191,11 @@ async function promptAppType(): Promise<AppType> {
136
191
  value: "cloud" as AppType,
137
192
  short: "CAD Cloud App"
138
193
  },
194
+ {
195
+ name: `${chalk.hex("#F0CEBB")("● App Template")} ${chalk.gray("- A complete, agent-ready product on the packages: a configurator, a laser-cut box, ...")}`,
196
+ value: "app" as AppType,
197
+ short: "App Template"
198
+ },
139
199
  ],
140
200
  default: "frontend"
141
201
  }
@@ -218,6 +278,47 @@ async function promptCloudProjectOptions(projectNameArg?: string): Promise<Cloud
218
278
  };
219
279
  }
220
280
 
281
+ async function promptAppTemplate(projectNameArg?: string): Promise<AppProjectOptions> {
282
+ interface AppAnswers {
283
+ projectName?: string;
284
+ template: AppTemplateId;
285
+ }
286
+
287
+ const choices = APP_TEMPLATE_IDS.map((id) => {
288
+ const template = APP_TEMPLATES[id];
289
+ const marker = template.cloud ? chalk.hex("#FF6633")(" (needs CAD Cloud)") : "";
290
+ return {
291
+ name: `${chalk.hex("#F0CEBB")(`● ${template.name}`)}${marker} ${chalk.gray(`- ${template.description}`)}`,
292
+ value: id,
293
+ short: template.name,
294
+ };
295
+ });
296
+
297
+ const questions = [
298
+ ...(projectNameArg ? [] : [{
299
+ type: "input" as const,
300
+ name: "projectName",
301
+ message: chalk.cyan("📁 What is your project name?"),
302
+ default: "my-bitbybit-app",
303
+ validate: (input: string) => {
304
+ if (!input.trim()) return "Project name is required";
305
+ if (!/^[a-z0-9-_]+$/i.test(input)) return "Project name can only contain letters, numbers, hyphens, and underscores";
306
+ return true;
307
+ }
308
+ }]),
309
+ {
310
+ type: "list" as const,
311
+ name: "template",
312
+ message: chalk.cyan("🧩 Which app template would you like to start from?"),
313
+ choices,
314
+ default: APP_TEMPLATE_IDS[0],
315
+ },
316
+ ];
317
+
318
+ const answers = await inquirer.prompt<AppAnswers>(questions);
319
+ return { projectName: projectNameArg || answers.projectName!, template: answers.template };
320
+ }
321
+
221
322
  async function promptProjectOptions(projectNameArg?: string): Promise<ProjectOptions> {
222
323
  interface PromptAnswers {
223
324
  projectName?: string;
@@ -337,18 +438,6 @@ async function promptProjectOptions(projectNameArg?: string): Promise<ProjectOpt
337
438
  };
338
439
  }
339
440
 
340
- /**
341
- * npm strips every file named .gitignore out of a package tarball, so the templates carry theirs as
342
- * _gitignore and each copied template restores the name here. Without it a scaffolded backend
343
- * arrives with the .env this CLI writes for it and nothing ignoring that file.
344
- */
345
- async function restoreTemplateDotfiles(dir: string): Promise<void> {
346
- const staged = path.join(dir, "_gitignore");
347
- if (await fs.pathExists(staged)) {
348
- await fs.move(staged, path.join(dir, ".gitignore"), { overwrite: true });
349
- }
350
- }
351
-
352
441
  async function createProject(options: ProjectOptions): Promise<void> {
353
442
  const { projectName, engine, bundler, language, occtArchitecture } = options;
354
443
  const targetDir = path.resolve(process.cwd(), projectName);
@@ -399,7 +488,7 @@ async function createProject(options: ProjectOptions): Promise<void> {
399
488
  }).start();
400
489
 
401
490
  try {
402
- const templateDir = path.join(__dirname, "..", "templates", bundler, engine, language);
491
+ const templateDir = path.join(TEMPLATES_ROOT, bundler, engine, language);
403
492
 
404
493
  if (!fs.existsSync(templateDir)) {
405
494
  spinner.fail("Template not found");
@@ -409,7 +498,7 @@ async function createProject(options: ProjectOptions): Promise<void> {
409
498
  }
410
499
 
411
500
  await fs.copy(templateDir, targetDir);
412
- await restoreTemplateDotfiles(targetDir);
501
+ await applyAgentLayer(TEMPLATES_ROOT, targetDir, { PROJECT_NAME: projectName, TEMPLATE_ID: `vite-${engine}`, CLI_VERSION });
413
502
  spinner.succeed("Project structure created");
414
503
 
415
504
  const packageJsonPath = path.join(targetDir, "package.json");
@@ -487,6 +576,12 @@ export default defineConfig({
487
576
  console.log(chalk.gray(" 3. Start the development server:"));
488
577
  console.log(chalk.cyan(" npm run dev"));
489
578
  console.log();
579
+ console.log(chalk.gray(" 4. Build the model headlessly and read its summary:"));
580
+ console.log(chalk.cyan(" npm run smoke"));
581
+ console.log();
582
+ console.log(chalk.gray(" Your coding agent is set up: AGENTS.md explains the project, and the"));
583
+ console.log(chalk.gray(" Bitbybit CAD MCP is configured for Claude Code, Cursor and VS Code."));
584
+ console.log();
490
585
 
491
586
  if (occtArchitecture === "64") {
492
587
  console.log(chalk.yellow(" ⚠️ Note: 64-bit OCCT may not be supported on all browsers."));
@@ -652,6 +747,22 @@ ${backend === "dotnet-rest" ? ` ├── Program.cs
652
747
  | \`POST\` | \`/api/pipeline/file-input\` | Pipeline: file upload + fillet |
653
748
  | \`GET\` | \`/api/proxy-download?url=...\` | Proxy glTF downloads (avoids CORS) |
654
749
 
750
+ ## What Needs CAD Cloud and Where to Get It
751
+
752
+ 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.
753
+
754
+ | | |
755
+ |---|---|
756
+ | What goes to the cloud | every backend route that creates a task, runs a pipeline, uploads a file or fetches a result |
757
+ | Plan needed | any [CAD Cloud plan](https://bitbybit.dev/cad-cloud); the key needs the \`cad\`, \`files\` and \`tasks\` scopes |
758
+ | Where keys live | [Bitbybit Studio](https://studio.bitbybit.dev/keys/billing), which also shows the tasks this app ran and what they cost |
759
+ | Where the key goes | \`backend/${BACKEND_SECRET_FILES[backend]}\`, already covered by \`backend/.gitignore\`; never anywhere else |
760
+ | 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 |
761
+
762
+ ## Use It With an Agent
763
+
764
+ \`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.
765
+
655
766
  ## Getting an API Key
656
767
 
657
768
  1. Create an account on [bitbybit.dev](https://bitbybit.dev)
@@ -711,7 +822,7 @@ async function createCloudProject(options: CloudProjectOptions): Promise<void> {
711
822
  }).start();
712
823
 
713
824
  try {
714
- const cloudTemplatesDir = path.join(__dirname, "..", "templates", "cloud");
825
+ const cloudTemplatesDir = path.join(TEMPLATES_ROOT, "cloud");
715
826
 
716
827
  const frontendTemplateDir = path.join(cloudTemplatesDir, "frontend");
717
828
  const frontendTargetDir = path.join(targetDir, "frontend");
@@ -766,6 +877,16 @@ async function createCloudProject(options: CloudProjectOptions): Promise<void> {
766
877
 
767
878
  await fs.writeFile(path.join(targetDir, "README.md"), generateCloudReadme(projectName, backend), "utf-8");
768
879
 
880
+ await applyAgentLayer(TEMPLATES_ROOT, targetDir, {
881
+ PROJECT_NAME: projectName,
882
+ TEMPLATE_ID: `cloud-${backend}`,
883
+ CLI_VERSION,
884
+ BACKEND_NAME: BACKEND_DISPLAY_NAMES[backend],
885
+ SECRET_FILE: BACKEND_SECRET_FILES[backend],
886
+ BACKEND_START: backend === "dotnet-rest" ? "cd backend && dotnet run" : "cd backend && npm install && npm run dev",
887
+ BACKEND_SMOKE: backend === "dotnet-rest" ? "dotnet build" : "npm run smoke",
888
+ }, path.join(cloudTemplatesDir, AGENT_SECTION_FILE));
889
+
769
890
  spinner.succeed("Project structure created");
770
891
 
771
892
  console.log();
@@ -810,6 +931,9 @@ async function createCloudProject(options: CloudProjectOptions): Promise<void> {
810
931
  console.log();
811
932
  console.log(chalk.gray(" 5. Open ") + chalk.cyan("http://localhost:5173") + chalk.gray(" in your browser"));
812
933
  console.log();
934
+ console.log(chalk.gray(" Your coding agent is set up: AGENTS.md explains the project and what needs"));
935
+ console.log(chalk.gray(" CAD Cloud, and the Bitbybit CAD MCP is configured for Claude Code, Cursor and VS Code."));
936
+ console.log();
813
937
  console.log(chalk.gray("─".repeat(72)));
814
938
  console.log();
815
939
  console.log(chalk.yellow.bold(" 🔑 You need a Bitbybit API key to use CAD Cloud:"));
@@ -829,34 +953,171 @@ async function createCloudProject(options: CloudProjectOptions): Promise<void> {
829
953
  }
830
954
  }
831
955
 
956
+ /**
957
+ * A template that needs a secret ships an .env.example beside the code that reads it; the scaffold
958
+ * gets an .env copied from it so the first run finds the file and the variable, empty. The same
959
+ * probe the cloud templates use, for any depth.
960
+ */
961
+ async function writeEnvFromExamples(dir: string): Promise<void> {
962
+ for (const example of await listFiles(dir)) {
963
+ if (path.basename(example) !== ".env.example") continue;
964
+ const env = path.join(path.dirname(example), ".env");
965
+ if (!(await fs.pathExists(env))) await fs.copy(example, env);
966
+ }
967
+ }
968
+
969
+ async function createAppProject(options: AppProjectOptions): Promise<void> {
970
+ const { projectName, template } = options;
971
+ const targetDir = path.resolve(process.cwd(), projectName);
972
+ const meta = APP_TEMPLATES[template];
973
+
974
+ console.log();
975
+ console.log(chalk.gray("─".repeat(72)));
976
+ console.log();
977
+ console.log(chalk.white.bold(" 📋 Project Configuration:"));
978
+ console.log();
979
+ console.log(` ${chalk.gray("Project:")} ${chalk.white.bold(projectName)}`);
980
+ console.log(` ${chalk.gray("Type:")} ${chalk.hex("#F0CEBB")("App Template")}`);
981
+ console.log(` ${chalk.gray("Template:")} ${chalk.hex("#F0CEBB")(meta.name)} ${chalk.gray(`(${template})`)}`);
982
+ 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")}`);
983
+ console.log();
984
+ console.log(chalk.gray("─".repeat(72)));
985
+ console.log();
986
+
987
+ if (fs.existsSync(targetDir)) {
988
+ const { overwrite } = await inquirer.prompt([
989
+ {
990
+ type: "confirm",
991
+ name: "overwrite",
992
+ message: chalk.yellow(`⚠️ Directory "${projectName}" already exists. Do you want to overwrite it?`),
993
+ default: false
994
+ }
995
+ ]);
996
+
997
+ if (!overwrite) {
998
+ console.log(chalk.red("\n ✖ Project creation cancelled.\n"));
999
+ process.exit(0);
1000
+ }
1001
+
1002
+ const spinner = ora("Removing existing directory...").start();
1003
+ await fs.remove(targetDir);
1004
+ spinner.succeed("Existing directory removed");
1005
+ }
1006
+
1007
+ const spinner = ora({ text: "Creating project structure...", color: "cyan" }).start();
1008
+
1009
+ try {
1010
+ const templateDir = path.join(TEMPLATES_ROOT, "apps", template);
1011
+ if (!fs.existsSync(templateDir)) {
1012
+ throw new Error(`The ${template} template is listed but its files are not at ${templateDir}.`);
1013
+ }
1014
+
1015
+ await fs.copy(templateDir, targetDir);
1016
+ await applyAgentLayer(TEMPLATES_ROOT, targetDir, { PROJECT_NAME: projectName, TEMPLATE_ID: template, CLI_VERSION });
1017
+ await writeEnvFromExamples(targetDir);
1018
+
1019
+ const packageJsonPath = path.join(targetDir, "package.json");
1020
+ if (fs.existsSync(packageJsonPath)) {
1021
+ const packageJson = await fs.readJson(packageJsonPath);
1022
+ packageJson.name = projectName;
1023
+ await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
1024
+ }
1025
+
1026
+ spinner.succeed("Project structure created");
1027
+
1028
+ console.log();
1029
+ console.log(chalk.gray("─".repeat(72)));
1030
+ console.log();
1031
+ console.log(chalk.gray(" Home: ") + chalk.underline.cyan("https://bitbybit.dev"));
1032
+ console.log(chalk.gray(" Learn: ") + chalk.underline.cyan("https://learn.bitbybit.dev"));
1033
+ console.log(chalk.gray(" Community: ") + chalk.underline.cyan("https://discord.gg/GSe3VMe"));
1034
+ console.log(chalk.gray(" GitHub: ") + chalk.underline.cyan("https://github.com/bitbybit-dev/bitbybit"));
1035
+ console.log();
1036
+ console.log(chalk.green.bold(` ✔ ${meta.name} created successfully! 🎉`));
1037
+ console.log();
1038
+ console.log(chalk.white(" Next steps:"));
1039
+ console.log();
1040
+ console.log(chalk.gray(" 1. Navigate to your project:"));
1041
+ console.log(chalk.cyan(` cd ${projectName}`));
1042
+ console.log();
1043
+ console.log(chalk.gray(" 2. Install dependencies:"));
1044
+ console.log(chalk.cyan(" npm install"));
1045
+ console.log();
1046
+ console.log(chalk.gray(" 3. Start the development server:"));
1047
+ console.log(chalk.cyan(" npm run dev"));
1048
+ console.log();
1049
+ console.log(chalk.gray(" 4. Build the model headlessly and read its summary:"));
1050
+ console.log(chalk.cyan(" npm run smoke"));
1051
+ console.log();
1052
+ console.log(chalk.gray(" README.md explains the app; AGENTS.md explains it to your coding agent, and the"));
1053
+ console.log(chalk.gray(" Bitbybit CAD MCP is configured for Claude Code, Cursor and VS Code."));
1054
+ console.log();
1055
+ if (meta.cloud) {
1056
+ console.log(chalk.yellow.bold(" 🔑 This template runs part of its work on CAD Cloud and needs an API key:"));
1057
+ console.log(chalk.yellow(" README.md says what needs the cloud and why; plans and keys are at"));
1058
+ console.log(chalk.underline.yellow(" https://bitbybit.dev/cad-cloud"));
1059
+ console.log();
1060
+ }
1061
+ console.log(chalk.gray("─".repeat(72)));
1062
+ console.log();
1063
+ console.log(chalk.white(" Happy coding! 💻✨"));
1064
+ console.log();
1065
+ } catch (error) {
1066
+ spinner.fail("Failed to create project");
1067
+ console.error(chalk.red("\n ✖ Error creating project:"), error);
1068
+ process.exit(1);
1069
+ }
1070
+ }
1071
+
832
1072
  async function main(): Promise<void> {
833
1073
  const program = new Command();
834
1074
 
835
1075
  program
836
1076
  .name("@bitbybit-dev/create-app")
837
1077
  .description("Scaffold a new Bit By Bit Developers 3D/CAD project")
838
- .version("1.3.2")
1078
+ .version(CLI_VERSION)
839
1079
  .argument("[project-name]", "Name of the project to create")
840
1080
  .option("-e, --engine <engine>", "Game engine to use (threejs, babylonjs, playcanvas)")
841
1081
  .option("-o, --occt-architecture <arch>", "OCCT worker architecture (32, 64, 64-mt). Default: 32")
842
- .option("-t, --type <type>", "App type (frontend, cloud)")
1082
+ .option("-t, --type <type>", "App type (frontend, cloud, app)")
843
1083
  .option("-b, --backend <backend>", "Backend for cloud app (hono-sdk, hono-rest, nodejs-sdk, nodejs-rest, dotnet-rest)")
844
- .action(async (projectName: string | undefined, cmdOptions: { engine?: string; occtArchitecture?: string; type?: string; backend?: string }) => {
845
- await displayWelcome();
1084
+ .option("-T, --template <template>", `App template for --type app (${APP_TEMPLATE_IDS.join(", ")})`)
1085
+ .action(async (projectName: string | undefined, cmdOptions: { engine?: string; occtArchitecture?: string; type?: string; backend?: string; template?: string }) => {
1086
+ displayWelcome();
846
1087
 
847
1088
  let appType: AppType;
848
1089
  if (cmdOptions.type) {
849
- if (cmdOptions.type !== "frontend" && cmdOptions.type !== "cloud") {
1090
+ if (cmdOptions.type !== "frontend" && cmdOptions.type !== "cloud" && cmdOptions.type !== "app") {
850
1091
  console.error(chalk.red(`\n ✖ Invalid app type: ${cmdOptions.type}`));
851
- console.error(chalk.gray(` Valid options: frontend, cloud`));
1092
+ console.error(chalk.gray(` Valid options: frontend, cloud, app`));
852
1093
  process.exit(1);
853
1094
  }
854
1095
  appType = cmdOptions.type;
1096
+ } else if (cmdOptions.template) {
1097
+ appType = "app";
855
1098
  } else {
856
1099
  appType = await promptAppType();
857
1100
  }
858
1101
 
859
- if (appType === "cloud") {
1102
+ if (appType === "app") {
1103
+ if (cmdOptions.template && !APP_TEMPLATE_IDS.includes(cmdOptions.template as AppTemplateId)) {
1104
+ console.error(chalk.red(`\n ✖ Invalid app template: ${cmdOptions.template}`));
1105
+ console.error(chalk.gray(` Valid options: ${APP_TEMPLATE_IDS.join(", ")}`));
1106
+ process.exit(1);
1107
+ }
1108
+ if (cmdOptions.engine || cmdOptions.occtArchitecture) {
1109
+ 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."));
1110
+ }
1111
+
1112
+ let appOptions: AppProjectOptions;
1113
+ if (projectName && cmdOptions.template) {
1114
+ appOptions = { projectName, template: cmdOptions.template as AppTemplateId };
1115
+ } else {
1116
+ appOptions = await promptAppTemplate(projectName);
1117
+ if (cmdOptions.template) appOptions.template = cmdOptions.template as AppTemplateId;
1118
+ }
1119
+ await createAppProject(appOptions);
1120
+ } else if (appType === "cloud") {
860
1121
  if (cmdOptions.backend) {
861
1122
  const validBackends = ["hono-sdk", "hono-rest", "nodejs-sdk", "nodejs-rest", "dotnet-rest"];
862
1123
  if (!validBackends.includes(cmdOptions.backend)) {
@@ -0,0 +1,177 @@
1
+ import { describe, it, expect, beforeEach, afterEach } from "vitest";
2
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import path from "node:path";
5
+ import { AGENTS_FILE, AGENT_SECTION_FILE, applyAgentLayer, listFiles, renderPlaceholders, restoreTemplateDotfiles } from "./scaffold.js";
6
+
7
+ let work: string;
8
+
9
+ const write = (relative: string, content: string): string => {
10
+ const file = path.join(work, relative);
11
+ mkdirSync(path.dirname(file), { recursive: true });
12
+ writeFileSync(file, content);
13
+ return file;
14
+ };
15
+
16
+ const read = (relative: string): string => readFileSync(path.join(work, relative), "utf8");
17
+
18
+ const fakeTemplatesRoot = (): string => {
19
+ const root = path.join(work, "templates");
20
+ mkdirSync(path.join(root, "_agent", "_dot-vscode"), { recursive: true });
21
+ writeFileSync(path.join(root, "_agent", AGENTS_FILE), "# {{PROJECT_NAME}}\n\nshared text for {{TEMPLATE_ID}}\n");
22
+ writeFileSync(path.join(root, "_agent", "CLAUDE.md"), "@AGENTS.md\n");
23
+ writeFileSync(path.join(root, "_agent", "_dot-mcp.json"), "{}\n");
24
+ writeFileSync(path.join(root, "_agent", "_dot-vscode", "mcp.json"), "{}\n");
25
+ return root;
26
+ };
27
+
28
+ describe("scaffold helpers", () => {
29
+ beforeEach(() => {
30
+ work = mkdtempSync(path.join(tmpdir(), "create-app-scaffold-"));
31
+ });
32
+
33
+ afterEach(() => {
34
+ rmSync(work, { recursive: true, force: true });
35
+ });
36
+
37
+ describe("restoreTemplateDotfiles", () => {
38
+ it("should rename every _dot- file and directory to its dotted name, however deep, and leave the rest alone", async () => {
39
+ // Arrange
40
+ write("project/_dot-gitignore", "node_modules\n");
41
+ write("project/_dot-vscode/mcp.json", "{}");
42
+ write("project/backend/_dot-env.example", "KEY=\n");
43
+ write("project/backend/src/index.ts", "export {};\n");
44
+
45
+ // Act
46
+ const restored = await restoreTemplateDotfiles(path.join(work, "project"));
47
+
48
+ // Assert
49
+ expect(restored.map((file) => path.relative(work, file)).sort()).toEqual([
50
+ "project/.gitignore", "project/.vscode", "project/backend/.env.example",
51
+ ]);
52
+ expect(read("project/.gitignore")).toBe("node_modules\n");
53
+ expect(read("project/.vscode/mcp.json")).toBe("{}");
54
+ expect(read("project/backend/.env.example")).toBe("KEY=\n");
55
+ expect(read("project/backend/src/index.ts")).toBe("export {};\n");
56
+ expect((await listFiles(path.join(work, "project"))).some((file) => file.includes("_dot-"))).toBe(false);
57
+ });
58
+
59
+ it("should not descend into node_modules", async () => {
60
+ // Arrange
61
+ write("project/node_modules/dep/_dot-npmrc", "registry=\n");
62
+
63
+ // Act
64
+ const restored = await restoreTemplateDotfiles(path.join(work, "project"));
65
+
66
+ // Assert
67
+ expect(restored).toEqual([]);
68
+ expect(existsSync(path.join(work, "project/node_modules/dep/_dot-npmrc"))).toBe(true);
69
+ });
70
+ });
71
+
72
+ describe("renderPlaceholders", () => {
73
+ it("should replace every known placeholder in every text file", async () => {
74
+ // Arrange
75
+ write("project/AGENTS.md", "# {{PROJECT_NAME}} ({{TEMPLATE_ID}}) by {{CLI_VERSION}}\n");
76
+ write("project/nested/notes.md", "again {{PROJECT_NAME}} and {{PROJECT_NAME}}\n");
77
+
78
+ // Act
79
+ await renderPlaceholders(path.join(work, "project"), { PROJECT_NAME: "demo", TEMPLATE_ID: "vite-threejs", CLI_VERSION: "9.9.9" });
80
+
81
+ // Assert
82
+ expect(read("project/AGENTS.md")).toBe("# demo (vite-threejs) by 9.9.9\n");
83
+ expect(read("project/nested/notes.md")).toBe("again demo and demo\n");
84
+ });
85
+
86
+ it("should treat a value with replacement patterns as literal text", async () => {
87
+ // Arrange
88
+ write("project/AGENTS.md", "{{PROJECT_NAME}}\n");
89
+
90
+ // Act
91
+ await renderPlaceholders(path.join(work, "project"), { PROJECT_NAME: "price $& $1 $$" });
92
+
93
+ // Assert
94
+ expect(read("project/AGENTS.md")).toBe("price $& $1 $$\n");
95
+ });
96
+
97
+ it("should leave braces that are not a placeholder alone, such as a JSX style object", async () => {
98
+ // Arrange
99
+ const jsx = "<div style={{ color: \"red\" }}>{{lower}} {{ SPACED }}</div>\n";
100
+ write("project/App.tsx", jsx);
101
+
102
+ // Act
103
+ await renderPlaceholders(path.join(work, "project"), { PROJECT_NAME: "demo" });
104
+
105
+ // Assert
106
+ expect(read("project/App.tsx")).toBe(jsx);
107
+ });
108
+
109
+ it("should fail naming the file and the placeholder when one has no value", async () => {
110
+ // Arrange
111
+ write("project/AGENTS.md", "{{PROJECT_NAME}} {{NOT_A_VALUE}}\n");
112
+
113
+ // Act
114
+ const attempt = renderPlaceholders(path.join(work, "project"), { PROJECT_NAME: "demo" });
115
+
116
+ // Assert
117
+ await expect(attempt).rejects.toThrow(/AGENTS\.md: \{\{NOT_A_VALUE\}\}/);
118
+ });
119
+
120
+ it("should not read a binary file", async () => {
121
+ // Arrange
122
+ write("project/logo.png", "{{PROJECT_NAME}}");
123
+
124
+ // Act
125
+ await renderPlaceholders(path.join(work, "project"), {});
126
+
127
+ // Assert
128
+ expect(read("project/logo.png")).toBe("{{PROJECT_NAME}}");
129
+ });
130
+ });
131
+
132
+ describe("applyAgentLayer", () => {
133
+ it("should copy the layer, append the template's section after the shared text, remove the section file, restore the dotfiles and render", async () => {
134
+ // Arrange
135
+ const templates = fakeTemplatesRoot();
136
+ write("project/src/main.ts", "export {};\n");
137
+ write(`project/${AGENT_SECTION_FILE}`, "## This template\n\nsection for {{PROJECT_NAME}}\n");
138
+
139
+ // Act
140
+ await applyAgentLayer(templates, path.join(work, "project"), { PROJECT_NAME: "demo", TEMPLATE_ID: "vite-threejs" });
141
+
142
+ // Assert
143
+ expect(read(`project/${AGENTS_FILE}`)).toBe("# demo\n\nshared text for vite-threejs\n\n## This template\n\nsection for demo\n");
144
+ expect(read("project/CLAUDE.md")).toBe("@AGENTS.md\n");
145
+ expect(existsSync(path.join(work, `project/${AGENT_SECTION_FILE}`))).toBe(false);
146
+ expect(existsSync(path.join(work, "project/.mcp.json"))).toBe(true);
147
+ expect(existsSync(path.join(work, "project/.vscode/mcp.json"))).toBe(true);
148
+ expect(existsSync(path.join(work, "project/_dot-mcp.json"))).toBe(false);
149
+ });
150
+
151
+ it("should take a section kept outside the scaffold and leave that file where it is", async () => {
152
+ // Arrange
153
+ const templates = fakeTemplatesRoot();
154
+ const shared = write("templates/cloud/AGENTS.section.md", "## Cloud\n\n{{BACKEND_NAME}}\n");
155
+ mkdirSync(path.join(work, "project"), { recursive: true });
156
+
157
+ // Act
158
+ await applyAgentLayer(templates, path.join(work, "project"), { PROJECT_NAME: "demo", TEMPLATE_ID: "cloud-hono-sdk", BACKEND_NAME: "Hono" }, shared);
159
+
160
+ // Assert
161
+ expect(read(`project/${AGENTS_FILE}`)).toContain("## Cloud\n\nHono\n");
162
+ expect(existsSync(shared)).toBe(true);
163
+ });
164
+
165
+ it("should write nothing over a file the template already has", async () => {
166
+ // Arrange
167
+ const templates = fakeTemplatesRoot();
168
+ write("project/CLAUDE.md", "the template's own\n");
169
+
170
+ // Act
171
+ await applyAgentLayer(templates, path.join(work, "project"), { PROJECT_NAME: "demo", TEMPLATE_ID: "x" });
172
+
173
+ // Assert
174
+ expect(read("project/CLAUDE.md")).toBe("the template's own\n");
175
+ });
176
+ });
177
+ });