@dunx/create-app 3.0.2 → 3.0.4

package/README.md

@@ -13,18 +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                 |
-| `--template <name>` | `minimal`          | Which template to write                            |
-| `--force`           | off                | Write into a directory that already has files      |
-| `--yes`, `-y`       |                    | Accepted and ignored; nothing here ever prompts    |
-| `--help`            |                    | Print usage                                        |
+| 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
@@ -38,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
 
@@ -49,7 +105,12 @@ The `minimal` template, the same app as
 server, and the `bunfig.toml` preload line that makes constructor injection work.
 
 Its `src/` is a **byte-for-byte copy** of that example, and a test in this package
-fails if the two ever drift. The example is the one CI boots, so keeping them
+fails if the two ever drift.
+
+Every app also gets an `AGENTS.md` naming its layout, its commands and the rules
+dunx fails at boot over, plus a `CLAUDE.md` pointing at it. Both link
+<https://petarzarkov.github.io/dunx/setup.md>, which is served per release, rather
+than copying the framework's own instructions into your repository. The example is the one CI boots, so keeping them
 identical is what makes the template trustworthy rather than merely plausible.
 
 ## Two details
@@ -80,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/agents.d.ts

@@ -0,0 +1,5 @@
+import type { Feature } from './features.js';
+export declare const CLAUDE_POINTER = "# CLAUDE.md\n\nThe instructions for this application live in `AGENTS.md`, imported below so every\nagent reads one file.\n\n@AGENTS.md\n";
+export declare const agents: (name: string, features: readonly Feature[]) => string;
+/** Both files, written for a fixed template and a composed app alike. */
+export declare const agentFiles: (name: string, features: readonly Feature[]) => Readonly<Record<string, string>>;

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-nn9ekg83.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"],
@@ -318,6 +318,119 @@ import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 var {Glob } = globalThis.Bun;
 
+// src/agents.ts
+var SETUP_URL = "https://petarzarkov.github.io/dunx/setup.md";
+var LLMS_URL = "https://petarzarkov.github.io/dunx/llms.txt";
+var CLAUDE_POINTER = `# CLAUDE.md
+
+The instructions for this application live in \`AGENTS.md\`, imported below so every
+agent reads one file.
+
+@AGENTS.md
+`;
+var RULES = `## Rules that produce a boot error when broken
+
+- **No \`@Injectable()\`, no \`@Inject()\`.** Listing a class in a module's
+  \`providers\` is what makes it injectable. dunx uses TC39 standard decorators,
+  which have no parameter decorators. For a value with no constructor parameter to
+  hang off, use \`inject(Token)\` in a field initializer.
+- **Do not add \`reflect-metadata\`, \`experimentalDecorators\` or
+  \`emitDecoratorMetadata\`.** \`bunfig.toml\` preloads \`@dunx/transform\`, which
+  records each class's constructor parameter types. Removing that line makes every
+  provider fail at boot.
+- **A constructor parameter whose type is erased fails at boot, naming the
+  parameter.** An interface, a primitive, a union, a class type parameter, or a
+  \`import type\` at an injection site all record as \`unresolved\`. Inject a class,
+  and drop \`type\` from the import.
+- **Relative imports carry \`.js\`**: \`'./users.service.js'\`, never
+  \`'./users.service'\`.
+- **A module's \`exports\` is its public surface.** The container is scoped per
+  module, so a provider another module injects has to be exported by the module that
+  declares it.
+- **\`bun\` only.** No \`npm\`, \`npx\`, \`yarn\` or \`pnpm\`; run tools with \`bunx\`.
+`;
+var layout = (features) => features.length === 0 ? `- \`src/main.ts\` - the entry point
+- \`src/app.module.ts\` - the root module; \`controllers\` get routes, \`providers\` do not
+- \`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\` - 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\`, \`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);
+  const hasJobs = features.some((feature) => feature.name === "jobs");
+  return `# ${name}
+
+Notes for an agent working in this application. It is a
+[dunx](https://github.com/petarzarkov/dunx) app, scaffolded by
+\`bunx @dunx/create-app\`.
+
+## Commands
+
+\`\`\`bash
+bun install
+bun run dev          # http://localhost:3000, restarting on a change
+bun run start
+bun test
+bun run typecheck
+\`\`\`${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
+
+${layout(features)}
+${features.length === 0 ? "" : `## What is wired up
+
+${features.map((feature) => `- **${feature.name}** - ${feature.summary}`).join(`
+`)}
+
+`}${services.length === 0 ? "" : `## Services
+
+Each of these reports itself degraded rather than failing the boot, so the app
+starts without them.
+
+${services.map((feature) => `- **${feature.name}** needs ${feature.service}`).join(`
+`)}
+
+`}${RULES}
+## Reading this app instead of grepping it
+
+\`\`\`bash
+bunx @dunx/mcp ./src/app.module.ts
+\`\`\`
+
+An MCP server over stdio answering what routes, providers, modules and gateways
+exist, and which constructor parameters would fail to resolve. It reads the module
+graph and never boots the app.
+
+## The framework's own instructions
+
+- <${SETUP_URL}> - installing, wiring and verifying a dunx app
+- <${LLMS_URL}> - every dunx document, as raw markdown
+`;
+};
+var agentFiles = (name, features) => ({
+  "AGENTS.md": agents(name, features),
+  "CLAUDE.md": CLAUDE_POINTER
+});
+
 // src/generate.ts
 var HEADER = (name) => `// Generated by @dunx/create-app for ${name}. Yours to edit.
 `;
@@ -344,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",
@@ -477,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"] : [],
@@ -495,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,
@@ -538,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
@@ -564,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();
 
@@ -589,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.
@@ -630,6 +726,7 @@ Scaffolded with \`bunx @dunx/create-app\`.
 
 \`\`\`bash
 bun install
+bun run dev     # restarts on a change
 bun run start
 \`\`\`
 
@@ -648,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
 
@@ -681,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";
@@ -695,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";
@@ -727,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({
@@ -751,12 +846,19 @@ var scaffold = async (options) => {
       written.push(target);
     }
   };
+  const writeAll = async (files) => {
+    for (const [target, contents] of Object.entries(files)) {
+      await Bun.write(join(directory, target), fill(contents, name, version));
+      written.push(target);
+    }
+  };
   if (!composing) {
     const source = join(templatesRoot(), template);
     if (!existsSync(source)) {
       throw new ScaffoldError(`Template "${template}" is missing from ${source}.`);
     }
     await copyTree(source, ".");
+    await writeAll(agentFiles(name, []));
     return {
       directory,
       name,
@@ -777,10 +879,10 @@ var scaffold = async (options) => {
     }
     await copyTree(from, join("src", feature.source));
   }
-  for (const [target, contents] of Object.entries(generated(name, features))) {
-    await Bun.write(join(directory, target), fill(contents, name, version));
-    written.push(target);
-  }
+  await writeAll({
+    ...generated(name, features),
+    ...agentFiles(name, features)
+  });
   return {
     directory,
     name,
@@ -790,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 };