@dunx/create-app 3.0.2 → 3.0.3

package/README.md

@@ -21,11 +21,18 @@ bun run start     # http://localhost:3000/greetings
 | 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`       |                    | Accepted and ignored; nothing here ever prompts    |
+| `--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`**.
+
 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
 a directory you just made.
@@ -49,7 +56,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

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/{chunk-nn9ekg83.js → chunk-x7s3axkt.js}

@@ -318,6 +318,112 @@ 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\` - the entry point
+- \`src/bootstrap.ts\` - builds the app; shared by \`start\` and the tests
+- \`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.
+`;
+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 start        # http://localhost:3000
+bun test
+bun run typecheck
+${hasJobs ? `bun run worker      # drains the queues; the web process does not
+` : ""}\`\`\`
+
+## 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.
 `;
@@ -751,12 +857,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 +890,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,

package/dist/cli.js

@@ -7,11 +7,21 @@ import {
   featureNames,
   impliedBy,
   scaffold
-} from "./chunk-nn9ekg83.js";
+} from "./chunk-x7s3axkt.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
 import { relative } from "path";
+
+// src/stdin.ts
+var readLine = async () => {
+  for await (const line of console) {
+    return typeof line === "string" ? line.trim() : "";
+  }
+  return "";
+};
+
+// src/cli.ts
 var USAGE = `Scaffold a new dunx application.
 
   bunx @dunx/create-app <directory> [options]
@@ -82,8 +92,7 @@ ${featureList()}
 `);
   console.log("Names or numbers, comma separated. `all` for everything.");
   process.stdout.write("> ");
-  const line = (await console[Symbol.asyncIterator]().next()).value;
-  const answer = typeof line === "string" ? line.trim() : "";
+  const answer = await readLine();
   if (answer === "")
     return [];
   if (answer === "all")

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   TEMPLATES,
   VERSION_PLACEHOLDER,
   scaffold
-} from "./chunk-nn9ekg83.js";
+} from "./chunk-x7s3axkt.js";
 export {
   ScaffoldError,
   TEMPLATES,

package/dist/stdin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One line of stdin, with the iteration ended before the value comes back.
+ *
+ * `console[Symbol.asyncIterator]().next()` on its own leaves stdin referenced for
+ * the life of the process: the scaffold wrote its files, printed the next steps and
+ * then sat there until the user pressed Ctrl+C. Ending the iteration runs the
+ * iterator's `return()`, which releases the handle, so the process exits on its own.
+ * Measured on Bun 1.4.0 - docs/bun-apis.md, "One line of stdin keeps the process
+ * alive".
+ *
+ * A function rather than a class because it is the whole module: no state, no
+ * configuration, and nothing to hold between calls.
+ */
+export declare const readLine: () => Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/create-app",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Scaffold a new dunx application - bunx @dunx/create-app my-api",
   "keywords": [
     "bun",