@bakery-framework/cli 2.0.0-alpha.12 → 2.0.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/cli",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.14",
   "description": "Bakery entry point and process supervision: mode dispatch, dev watcher, cluster.",
   "keywords": [
     "bakery",
@@ -39,10 +39,10 @@
     "bun": ">=1.4.0"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.12"
+    "@bakery-framework/core": "^2.0.0-alpha.14"
   },
   "peerDependencies": {
-    "@bakery-framework/orm": "^2.0.0-alpha.12"
+    "@bakery-framework/orm": "^2.0.0-alpha.14"
   },
   "peerDependenciesMeta": {
     "@bakery-framework/orm": {

package/src/index.ts

@@ -14,6 +14,44 @@ const isThreadWorker = import.meta.env.THREAD_WORKER
 
 const threadsOption = parseThreadsOption(process.argv.slice(2))
 
+/**
+ * `--help` before anything else, because everything else starts a server.
+ *
+ * There was no help branch at all: `bakery --help` fell through to `./prod`,
+ * booted a production server, bound the configured port and sat there. On a
+ * machine where that port is already taken it fails with a bind error, and on
+ * one where it is free it silently *takes* it — either way the user asked what
+ * the flags were and got a running service.
+ *
+ * Printed with `console.log` and not the structured logger, for the reason
+ * CLAUDE.md records as one of the two standing exceptions: usage text is
+ * program output, not a log line, and it goes to stdout so it can be piped.
+ */
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+Usage: bakery [--dev] [--sync] [--threads N] [--port N]
+
+Runs the application in the current directory — the one whose
+\`server.config.ts\` sits beside it.
+
+Flags:
+  --dev             Development: a supervisor that watches files, compiles on
+                    demand and reloads the browser. Without it, production.
+  --sync, -s        Run the schema sync before starting. Requires
+                    @bakery-framework/orm; it is an error rather than a skip
+                    when that is missing, because asking for a sync and
+                    silently not doing one looks like it worked.
+  --threads N, -t N Fork a cluster of N workers. Production only — ignored
+                    under --dev. THREAD_ID 0 owns the startup banner.
+  --port N, -p N    Listening port. Overrides \`port\` in server.config.ts and
+                    the PORT environment variable.
+  --help, -h        This.
+
+Schema commands have their own help: \`bun run db:sync --help\`.
+`)
+  process.exit(0)
+}
+
 // Before any mode takes over, and before the config is read: `applyPortFlag`
 // writes `process.env.PORT`, which is what the worker, the startup banner and
 // the dev master's advertised URL all resolve from — and what the spawned dev
@@ -23,6 +61,16 @@ applyPortFlag()
 
 if (
   (process.argv.includes('--sync') || process.argv.includes('-s')) &&
+  // **Not in development, where `dev.ts` owns the decision.** Under `--dev`
+  // this file is the watcher master, which then spawns a `--dev-worker` that
+  // reaches `dev.ts` — and that path reads `--sync` as `force`, hashes the
+  // schema sources, decides skip-or-run against the recorded hash and writes
+  // the new one. Running here as well meant `--dev --sync` synced twice per
+  // boot: once blindly in the master and once properly in the worker, against
+  // the same database, with the master's pass doing work the worker was about
+  // to redo. Production keeps this branch, because `prod.ts` does not sync at
+  // all and this is the only thing that answers `--sync` there.
+  !isDev &&
   !isDevWorker &&
   !isThreadWorker
 ) {