@dunx/create-app 3.0.3 → 3.0.4

package/README.md

@@ -13,25 +13,52 @@ bunx @dunx/create-app my-api
 ```
 cd my-api
 bun install
-bun run start     # http://localhost:3000/greetings
+bun run dev       # http://localhost:3000/greetings, restarting on a change
 ```
 
+## The questions
+
+There is no flag for choosing features. The command opens a list:
+
+```
+? Features  2 chosen, 1 pulled in
+  ○ notes       CRUD routes with zod validation. The smallest real feature.
+  ◉ openapi     OpenAPI 3.1 from the routes own schemas, plus the Swagger UI page.
+  ◈ database    drizzle over bun:sqlite, with a schema, seeds and migrations.
+❯ ◉ users       A repository, a service and validated routes over the database.
+  ○ auth        better-auth mounted, with SessionGuard and an audit trail.
+  database comes along as a requirement.
+  Space toggles. ↑↓ moves. a all, n none. Enter continues.
+```
+
+| Key             | Does                                          |
+| --------------- | --------------------------------------------- |
+| `↑` `↓`, `k` `j`, Tab | Move the cursor                         |
+| Space           | Toggle the feature under it                   |
+| `a` / `n`       | Everything / nothing                          |
+| Enter           | Take the selection                            |
+| Ctrl+C, Esc     | Stop, having written nothing                  |
+
+`◉` is chosen, `◈` is pulled in by something else you chose, `○` is neither. The
+two lines under the list update as you go: what your selection drags in, and which
+of it needs Redis or Postgres running to do anything.
+
+Three more questions appear only when there is something to ask: a directory, when
+the command line named none; a package name, when the directory's is one npm would
+reject; and whether to write into a directory that already has files in it.
+
 ## Options
 
-| Flag                | Default            | Meaning                                            |
-| ------------------- | ------------------ | -------------------------------------------------- |
-| `--name <name>`     | the directory name | Package name for the generated app                 |
-| `--with <a,b,c>`    |                    | Features to compose the app from                   |
-| `--all`             | off                | Every feature                                      |
-| `--list`            |                    | Print the features and exit                        |
-| `--template <name>` | `minimal`          | Which template to write                            |
-| `--force`           | off                | Write into a directory that already has files      |
-| `--yes`, `-y`       | off                | Take the minimal template without prompting        |
-| `--help`            |                    | Print usage                                        |
-
-With neither `--with` nor `--yes`, and a terminal attached, it lists the features
-and reads one line of stdin. Piped or in CI it never prompts, so **an agent or a
-script should pass `--yes` or `--with`**.
+| Flag            | Default            | Meaning                                       |
+| --------------- | ------------------ | --------------------------------------------- |
+| `--name <name>` | the directory name | Package name for the generated app            |
+| `--force`       | off                | Write into a directory that already has files |
+| `--yes`, `-y`   | off                | Skip the questions, take the minimal template |
+| `--help`        |                    | Print usage                                   |
+
+**Piped, redirected or in CI it asks nothing** and writes the minimal template, so
+a script never hangs on a question nothing can answer. To choose features without
+a terminal, call [`scaffold`](#programmatic-use) rather than passing flags.
 
 The name is validated against npm's rules **before** anything is created, because
 an invalid one would otherwise surface as a confusing `bun install` failure inside
@@ -45,9 +72,31 @@ bunx @dunx/create-app .
 ```
 
 `.git`, `.gitkeep`, `.DS_Store` and `LICENSE` do not count as contents, so a fresh
-repo or a clone of an empty GitHub repository is a valid target without `--force`.
+repo or a clone of an empty GitHub repository is a valid target without a question.
 Nothing else is ignored: `.gitignore` and `README.md` both come out of the template,
-and overwriting your copy of either is what `--force` is there to ask about.
+and overwriting your copy of either is what the last question asks about.
+
+## What a composed app looks like
+
+```
+my-api/
+  src/
+    main.ts          exports createApp, and serves it when run directly
+    app.module.ts    the root module, importing every feature
+    config.ts        one validation function, flat env in and a shaped object out
+    users/           one directory per feature you chose
+  package.json       dev, start, test, typecheck
+  bunfig.toml        the transform preload
+```
+
+Three files are generated for the selection and the feature directories are copied.
+`main.ts` is one file rather than two: a test imports `createApp` from it, and the
+`import.meta.main` block at the bottom is what stops that starting a server.
+
+**There is no worker entry point, even with queues.** `QueueModule` is given
+`consume: true`, so the container opens the bullmq workers at `onInit` and closes
+them before the connections the handlers use. A handler marked `background: true` is
+forked by bullmq itself into `src/jobs/jobs.processor.ts`.
 
 ## What it generates
 
@@ -92,9 +141,14 @@ import { scaffold } from '@dunx/create-app';
 const { directory, files } = await scaffold({
   target: 'my-api',
   name: '@acme/my-api',
+  features: ['users', 'openapi'],
 });
 ```
 
+This is the scripted path the removed `--with` flag used to be. `features` takes
+the same names the list shows, in any order, and pulls in what they require;
+`FEATURES` exports the set. Omitting it writes the minimal template.
+
 `scaffold` throws `ScaffoldError` for anything the caller can fix - an unknown
 template, an unusable package name, a non-empty target without `force` - and lets
 everything else propagate.

package/dist/banner.d.ts

@@ -0,0 +1,14 @@
+import type { Style } from './style.js';
+/**
+ * The header the questions run under.
+ *
+ * Printed once, before the first prompt, and only when there is a terminal to
+ * print it into: a logo piped into a log file is noise. A terminal too narrow for
+ * the logo gets the one-line form rather than a wrapped one, which is what
+ * `Bun.stringWidth` is measured against.
+ */
+export declare class Banner {
+    #private;
+    constructor(style: Style);
+    lines(width: number, version: string): readonly string[];
+}

package/dist/{chunk-x7s3axkt.js → chunk-5tn3ybzv.js}

@@ -221,7 +221,7 @@ var FEATURES = [
   {
     name: "jobs",
     source: "jobs",
-    summary: "bullmq queues and a worker, over Bun.RedisClient.",
+    summary: "bullmq queues over Bun.RedisClient, background handlers forked.",
     requires: ["images"],
     module: { klass: "JobsModule", from: "./jobs/jobs.module.js" },
     dependencies: ["@dunx/infra", "bullmq", "ioredis", "zod"],
@@ -354,18 +354,20 @@ var layout = (features) => features.length === 0 ? `- \`src/main.ts\` - the entr
 - \`src/greetings.controller.ts\`, \`src/greetings.service.ts\` - one route and its provider
 - \`src/app.test.ts\` - the whole app behind a real server on port 0
 - \`bunfig.toml\` - the preload line constructor injection needs
-` : `- \`src/main.ts\` - the entry point
-- \`src/bootstrap.ts\` - builds the app; shared by \`start\` and the tests
+` : `- \`src/main.ts\` - exports \`createApp\`, and serves it when run directly
 - \`src/app.module.ts\` - the root module, importing every feature
 - \`src/config.ts\` - one validation function, flat env in and a shaped object out
 ${features.map((feature) => `- \`src/${feature.source}/\` - ${feature.name}`).join(`
 `)}
 - \`bunfig.toml\` - the preload line constructor injection needs
 
-\`main.ts\`, \`bootstrap.ts\`, \`app.module.ts\` and \`config.ts\` were generated for the
-features chosen at scaffold time. Everything else was copied from dunx's
-\`examples/full\`. The \`*.demo.ts\` files are that example's scripted walkthroughs;
-delete one and its \`providers\` entry to drop it.
+\`main.ts\`, \`app.module.ts\` and \`config.ts\` were generated for the features chosen
+at scaffold time. Everything else was copied from dunx's \`examples/full\`. The
+\`*.demo.ts\` files are that example's scripted walkthroughs; delete one and its
+\`providers\` entry to drop it.
+
+A test imports \`createApp\` from \`./main.js\`; the \`import.meta.main\` block at the
+bottom is what stops that starting a server.
 `;
 var agents = (name, features) => {
   const services = features.filter((feature) => feature.service !== undefined);
@@ -380,11 +382,16 @@ Notes for an agent working in this application. It is a
 
 \`\`\`bash
 bun install
-bun run start        # http://localhost:3000
+bun run dev          # http://localhost:3000, restarting on a change
+bun run start
 bun test
 bun run typecheck
-${hasJobs ? `bun run worker      # drains the queues; the web process does not
-` : ""}\`\`\`
+\`\`\`${hasJobs ? `
+
+**There is no worker command.** \`QueueModule\` is given \`consume: true\`, so the
+container opens the workers at \`onInit\` and closes them before the connections they
+use. A handler marked \`background: true\` is forked by bullmq into
+\`src/jobs/jobs.processor.ts\`, which nobody runs by hand.` : ""}
 
 ## Layout
 
@@ -450,13 +457,11 @@ var manifest = (features) => {
     dependencies[dep] = DUNX.test(dep) ? "__DUNX_VERSION__" : versionOf(dep);
   }
   const scripts = {
+    dev: "bun --watch src/main.ts",
     start: "bun src/main.ts",
     test: "bun test",
     typecheck: "tsc --noEmit"
   };
-  if (features.some((feature) => feature.name === "jobs")) {
-    scripts["worker"] = "bun src/worker.ts";
-  }
   return `${JSON.stringify({
     name: "__DUNX_APP_NAME__",
     version: "0.1.0",
@@ -583,15 +588,17 @@ ${chosen.map(([, group]) => `    ${group.map}`).join(`
 `;
 };
 var has = (features, name) => features.some((feature) => feature.name === name);
-var bootstrap = (name, features) => {
+var main = (name, features) => {
   const openapi = has(features, "openapi");
   const websockets = has(features, "websockets");
   const http = has(features, "http");
+  const health = has(features, "health");
   const documentsAuth = openapi && has(features, "auth");
   const assets = has(features, "assets");
   const throttle = has(features, "throttle");
   const imports = [
     ...documentsAuth ? ["import { Auth, betterAuthDocument } from '@dunx/auth';"] : [],
+    "import { Logger } from '@dunx/core';",
     `import { ${[
       "HttpFactory",
       ...websockets ? ["RedisRelay"] : [],
@@ -601,12 +608,9 @@ var bootstrap = (name, features) => {
     ].join(", ")} } from '@dunx/http';`,
     ...openapi ? ["import { OpenApiModule } from '@dunx/openapi';"] : [],
     "import { AppModule } from './app.module.js';",
-    `import { ${[
-      ...http ? ["AppConfigService"] : [],
-      ...websockets ? ["RELAY_CHANNEL"] : []
-    ].join(", ")} } from './config.js';`,
+    `import { ${["AppConfigService", ...websockets ? ["RELAY_CHANNEL"] : []].join(", ")} } from './config.js';`,
     ...http ? ["import { RequestTrailMiddleware } from './http/request-trail.js';"] : []
-  ].filter((line) => !line.includes("{  }"));
+  ];
   const root = documentsAuth ? `OpenApiModule.forRootAsync({
       root: AppModule,
       inject: [Auth] as const,
@@ -644,12 +648,20 @@ var bootstrap = (name, features) => {
     ] : [],
     ...throttle ? ["app.use(ThrottleGuard);"] : []
   ];
+  const urls = [
+    ...openapi ? [
+      "logger.info(`docs    ${new URL('api/docs', url).href}`);",
+      "logger.info(`openapi ${new URL('api/openapi.json', url).href}`);"
+    ] : [],
+    ...health ? ["logger.info(`health  ${new URL('api/health', url).href}`);"] : []
+  ];
   return `${HEADER(name)}${imports.join(`
 `)}
 
 /**
- * One app, built the same way for \`bun start\` and for the tests - so what the
- * tests exercise is what actually serves.
+ * One app for \`bun run start\`, \`bun run dev\` and the tests, and one file:
+ * \`createApp\` is exported for a caller that wants the shape without a server, and
+ * the block at the bottom serves it when this file is the entry point.
  *
  * \`create()\` boots the container and discovers routes and gateways; \`listen()\` is
  * what builds the \`Bun.serve\` route table. Everything between the two still gets to
@@ -670,23 +682,8 @@ ${shaping.map((line) => `  ${line}`).join(`
 
   return app;
 };
-`;
-};
-var main = (name, features) => {
-  const health = has(features, "health");
-  const openapi = has(features, "openapi");
-  const lines = [
-    ...openapi ? [
-      "logger.info(`docs    ${new URL('api/docs', url).href}`);",
-      "logger.info(`openapi ${new URL('api/openapi.json', url).href}`);"
-    ] : [],
-    ...health ? ["logger.info(`health  ${new URL('api/health', url).href}`);"] : []
-  ];
-  return `${HEADER(name)}import { Logger } from '@dunx/core';
-import { createApp } from './bootstrap.js';
-import { AppConfigService } from './config.js';
 
-async function bootstrap(): Promise<void> {
+const start = async (): Promise<void> => {
   const app = await createApp();
   app.enableShutdownHooks();
 
@@ -695,31 +692,24 @@ async function bootstrap(): Promise<void> {
   const url = await app.listen(config.get('port'));
 
   logger.info(\`listening on \${url}\`);
-${lines.map((line) => `  ${line}`).join(`
-`)}${lines.length > 0 ? `
+${urls.map((line) => `  ${line}`).join(`
+`)}${urls.length > 0 ? `
 ` : ""}
   // Nothing else to do: the server holds the process open, and the shutdown hooks
   // resolve this once a signal arrives.
   await app.closed;
-}
-
-bootstrap().catch((error: unknown) => {
-  console.error('failed to start', error);
-  process.exit(1);
-});
-`;
 };
-var worker = (name) => `${HEADER(name)}import { AppFactory } from '@dunx/core';
-import { AppModule } from './app.module.js';
 
-/**
- * A queue needs a process to drain it, and it is deliberately not the web one: a
- * worker that shares the server's event loop competes with request handling.
- */
-const app = await AppFactory.create(AppModule);
-app.enableShutdownHooks();
-await app.closed;
+// False when a test imports this file for \`createApp\` alone, which is what lets one
+// module be both the entry point and the app's definition.
+if (import.meta.main) {
+  start().catch((error: unknown) => {
+    console.error('failed to start', error);
+    process.exit(1);
+  });
+}
 `;
+};
 var envExample = (groups) => {
   const lines = groups.flatMap((group) => CONFIG_GROUPS[group]?.env ?? []).map((entry) => `${entry.name}=${entry.value}`);
   return lines.length === 0 ? `# Every variable has a default, so this file is optional.
@@ -736,6 +726,7 @@ Scaffolded with \`bunx @dunx/create-app\`.
 
 \`\`\`bash
 bun install
+bun run dev     # restarts on a change
 bun run start
 \`\`\`
 
@@ -754,17 +745,19 @@ ${services.map((feature) => `- **${feature.name}** needs ${feature.service}`).jo
 
 `}## Layout
 
-- \`src/main.ts\` - the entry point
-- \`src/bootstrap.ts\` - builds the app; shared by \`start\` and the tests
+- \`src/main.ts\` - exports \`createApp\`, and serves it when run directly
 - \`src/app.module.ts\` - the root module, importing every feature
 - \`src/config.ts\` - one validation function, flat env in and a shaped object out
 ${features.map((feature) => `- \`src/${feature.source}/\` - ${feature.name}`).join(`
 `)}
 
-\`main.ts\`, \`bootstrap.ts\`, \`app.module.ts\` and \`config.ts\` were generated for the
-features you chose; everything else is copied from dunx's \`examples/full\`, which is
-run and toured in CI on every push. The \`*.demo.ts\` files are that example's
-scripted walkthroughs - delete one and its \`providers\` entry when you do not want it.
+\`main.ts\`, \`app.module.ts\` and \`config.ts\` were generated for the features you
+chose; everything else is copied from dunx's \`examples/full\`, which is run and
+toured in CI on every push. The \`*.demo.ts\` files are that example's scripted
+walkthroughs - delete one and its \`providers\` entry when you do not want it.
+
+A test imports \`createApp\` from \`./main.js\` and never starts a server: the
+\`import.meta.main\` block at the bottom of the file is false for an import.
 
 ## Constructor injection
 
@@ -787,13 +780,14 @@ var IGNORED_WHEN_EMPTY = new Set([
   ".gitkeep",
   "LICENSE"
 ]);
+var blockingEntries = (directory) => existsSync(directory) ? readdirSync(directory).filter((entry) => !IGNORED_WHEN_EMPTY.has(entry)).sort() : [];
 
 class ScaffoldError extends Error {
   name = "ScaffoldError";
 }
 var templatesRoot = () => resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 var isValidPackageName = (name) => /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);
-var readPackageVersion = async () => {
+var packageVersion = async () => {
   const file = Bun.file(join(templatesRoot(), "..", "package.json"));
   const json = await file.json();
   return json.version ?? "0.0.0";
@@ -801,19 +795,14 @@ var readPackageVersion = async () => {
 var fill = (contents, name, version) => contents.replaceAll(VERSION_PLACEHOLDER, version).replaceAll("__DUNX_APP_NAME__", name);
 var generated = (name, features) => {
   const groups = configGroupsFor(features);
-  const files = {
+  return {
     "package.json": manifest(features),
     "README.md": readme(name, features),
     ".env.example": envExample(groups),
     "src/main.ts": main(name, features),
-    "src/bootstrap.ts": bootstrap(name, features),
     "src/app.module.ts": appModule(name, features),
     "src/config.ts": config(name, groups)
   };
-  if (features.some((feature) => feature.name === "jobs")) {
-    files["src/worker.ts"] = worker(name);
-  }
-  return files;
 };
 var scaffold = async (options) => {
   const template = options.template ?? "minimal";
@@ -833,15 +822,15 @@ var scaffold = async (options) => {
   if (!isValidPackageName(name)) {
     throw new ScaffoldError(`"${name}" is not a usable package name. Pass --name to choose one.`);
   }
-  if (existsSync(directory) && options.force !== true) {
-    const blocking = readdirSync(directory).filter((entry) => !IGNORED_WHEN_EMPTY.has(entry));
+  if (options.force !== true) {
+    const blocking = blockingEntries(directory);
     if (blocking.length > 0) {
-      const shown = blocking.sort().slice(0, 3).join(", ");
+      const shown = blocking.slice(0, 3).join(", ");
       const rest = blocking.length > 3 ? `, +${blocking.length - 3} more` : "";
       throw new ScaffoldError(`${directory} is not empty (${shown}${rest}). ` + `Pass --force to write into it anyway.`);
     }
   }
-  const version = options.version ?? `^${await readPackageVersion()}`;
+  const version = options.version ?? `^${await packageVersion()}`;
   const written = [];
   const copyTree = async (from, into) => {
     for await (const relative of new Glob("**/*").scan({
@@ -903,4 +892,4 @@ var scaffold = async (options) => {
   };
 };
 
-export { FEATURES, featureNames, impliedBy, TEMPLATES, VERSION_PLACEHOLDER, ScaffoldError, scaffold };
+export { FEATURES, featureNames, resolveFeatures, impliedBy, TEMPLATES, VERSION_PLACEHOLDER, blockingEntries, ScaffoldError, isValidPackageName, packageVersion, scaffold };