@webda/create 0.0.0-stage → 4.0.0-beta.5

package/agent/skills/webda-services/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: webda-services
+description: Use when adding or changing a Webda service, its parameters, its lifecycle or when wiring it in webda.config.json
+---
+
+# Webda services
+
+## When to use
+
+Behaviour that is not about a single model: integrations, scheduled work, computations across models. Model-specific behaviour belongs on the model.
+
+## Pattern
+
+A service lives in `src/services/<name>.service.ts`, has a parameters class (the file must be named `*.service.ts`: the build fails on a service file without that suffix), and the `@WebdaModda` JSDoc tag so the compiler registers it. It is enabled in `webda.config.json` under `services`, where its parameters are set.
+
+```ts
+import { Service, useLog } from "@webda/core";
+
+export class ReminderServiceParameters extends Service.Parameters {
+  /**
+   * Hours before a reminder is sent
+   * @minimum 1
+   */
+  delayHours: number = 24;
+}
+
+/**
+ * Sends reminders for open tasks
+ *
+ * @WebdaModda
+ */
+export class ReminderService<T extends ReminderServiceParameters = ReminderServiceParameters> extends Service<T> {
+  static Parameters = ReminderServiceParameters;
+
+  /**
+   * Validate configuration; synchronous, called before init
+   */
+  resolve(): this {
+    super.resolve();
+    useLog("INFO", "Reminder delay", this.parameters.delayHours);
+    return this;
+  }
+
+  /**
+   * Open connections or start timers
+   */
+  async init(): Promise<this> {
+    await super.init();
+    return this;
+  }
+
+  /**
+   * Release what init created
+   */
+  async stop(): Promise<void> {
+    await super.stop();
+  }
+}
+```
+
+```json
+{
+  "services": {
+    "ReminderService": { "type": "ReminderService", "delayHours": 12 }
+  }
+}
+```
+
+Lifecycle: constructor → `resolve()` (configuration, dependencies) → `init()` (connections) → running → `stop()`.
+
+Another service is reached with `useService("ReminderService")`. Expose a method to clients with `@Operation()` (see `webda-operations`).
+
+## Common mistakes
+
+```text
+new ReminderService(...)                → never instantiate services; declare them in webda.config.json
+Hardcoded URLs, credentials, delays     → parameters in webda.config.json
+console.log                              → useLog("INFO", ...)
+Forgetting @WebdaModda                  → the type is unknown in webda.config.json
+```
+
+## Verify
+
+`npm run build`, then `npm run debug` and check the service starts in the logs; add a test (see `webda-testing`).
+
+## Reference
+
+https://docs.webda.io
+
+Written for Webda 4.0.0-beta.

package/agent/skills/webda-stores/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: webda-stores
+description: Use when reading or writing model data, querying models, or choosing or switching the store (memory, file, MongoDB, PostgreSQL) of a Webda app
+---
+
+# Webda stores and data access
+
+## When to use
+
+Reading, writing or querying models, reacting to data changes, or changing where the data is stored.
+
+## Pattern
+
+Code never talks to a store: it uses the model. The store is configuration.
+
+```ts
+import { useLog } from "@webda/core";
+import { UuidModel, useRepository } from "@webda/models";
+
+export class Note extends UuidModel {
+  text!: string;
+  archived!: boolean;
+}
+
+export async function examples() {
+  const note = await Note.create({ text: "Hello", archived: false });
+  const loaded = await Note.ref(note.getUUID()).get();
+  await Note.ref(note.getUUID()).patch({ archived: true });
+  const { results, continuationToken } = await Note.query("archived = false ORDER BY text LIMIT 10");
+  const same = await Note.query("text = ?", [loaded.text]);
+  for await (const item of Note.iterate("archived = true")) {
+    await item.delete();
+  }
+  useRepository(Note).on("Created", event => useLog("INFO", "Note created", event));
+  return { results, continuationToken, same };
+}
+```
+
+Pass user input as query parameters (`?` or `:name`), never by building the query string.
+
+The default store is the `Registry` service. To switch, replace it in `webda.config.json` and add the package:
+
+| Store            | Package           | `Registry` configuration                                   | Connection                                               |
+| ---------------- | ----------------- | ---------------------------------------------------------- | -------------------------------------------------------- |
+| memory (default) | `@webda/core`     | none (persisted to `.registry`)                            |                                                          |
+| files            | `@webda/fs`       | `{ "type": "Webda/FileStore", "folder": "./data" }`        |                                                          |
+| MongoDB          | `@webda/mongo`    | `{ "type": "Webda/MongoStore", "collection": "registry" }` | `WEBDA_MONGO_URL`                                        |
+| PostgreSQL       | `@webda/postgres` | `{ "type": "Webda/PostgresStore", "table": "registry" }`   | `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` |
+
+## Common mistakes
+
+```text
+@Inject("Registry") store; store.save(...)  → Model.create / Model.ref(id).patch / Model.query
+`text = '${input}'` in a query               → Note.query("text = ?", [input])
+Credentials in webda.config.json             → environment variables (.env.example)
+```
+
+## Verify
+
+`npm test`. For MongoDB or PostgreSQL, start the database (`docker compose up -d`) and `cp .env.example .env`: tests load `.env` automatically; for `npm run debug` or `npm run serve`, export the variables first (`set -a; . ./.env; set +a`).
+
+## Reference
+
+https://docs.webda.io
+
+Written for Webda 4.0.0-beta.

package/agent/skills/webda-testing/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: webda-testing
+description: Use when writing, running or fixing tests of a Webda app, its models, services or operations
+---
+
+# Testing a Webda app
+
+## When to use
+
+Adding tests for a model, a service or an operation, or fixing a failing test.
+
+## Pattern
+
+Tests are vitest files in `test/*.spec.ts`, written as classes with `@suite` and `@test` from `@webda/test`. `npm test` builds first (`pretest`), because the app is loaded from `lib/` and `webda.module.json`.
+
+```ts
+import { suite, test } from "@webda/test";
+import * as assert from "node:assert";
+import { resolve } from "node:path";
+import { TestApplication, WebdaApplicationTest } from "@webda/core/lib/test/index.js";
+import { useModel, useService } from "@webda/core";
+
+const appDir = resolve(import.meta.dirname, "..");
+
+class AppTestApplication extends TestApplication {
+  getNamespace() {
+    return "MyApp";
+  }
+
+  filterModule(_filename: string): boolean {
+    return true;
+  }
+}
+
+@suite
+class NoteTest extends WebdaApplicationTest {
+  getTestConfiguration(): string {
+    return appDir;
+  }
+
+  getApplication() {
+    return new AppTestApplication(this.getTestConfiguration());
+  }
+
+  @test
+  async createsANote() {
+    const Note = useModel<any>("MyApp/Note");
+    const note = await Note.create({ text: "Hello", archived: false });
+    assert.strictEqual((await Note.ref(note.getUUID()).get()).text, "Hello");
+  }
+
+  @test
+  async callsAService() {
+    const greeting = (useService("GreetingService" as any) as any).greet("Ada");
+    assert.strictEqual(greeting, "Hello Ada");
+  }
+}
+```
+
+- Get models with `useModel("<Namespace>/<Model>")` and services with `useService("<name>")`: importing classes from `src/` gives different class objects than the ones the app loaded from `lib/`.
+- `getNamespace()` returns the `webda.namespace` of `package.json`.
+- By default the test replaces the `Registry` store with an in-memory one. Override `async tweakApp() {}` to keep `webda.config.json` as is (then make assertions on data the test creates, since the store keeps data between runs).
+
+## Common mistakes
+
+```text
+import { Note } from "../src/models/Note.model.js"  → useModel("MyApp/Note")
+Running vitest without building                      → npm test (runs webdac build first)
+Assertions on global counts with a persistent store  → assert on records created by the test
+```
+
+## Verify
+
+`npm test`.
+
+## Reference
+
+https://docs.webda.io
+
+Written for Webda 4.0.0-beta.

package/lib/agents.d.ts

@@ -0,0 +1,21 @@
+import type { Store, Transport } from "./options.js";
+/**
+ * Lines describing the generated app for the "This app" section of AGENTS.md
+ * @param options - selected store and transports
+ * @param options.store - selected store backend
+ * @param options.transports - selected transport protocols
+ * @returns one line per aspect
+ */
+export declare function describeApp(options: {
+    store: Store;
+    transports: Transport[];
+}): string[];
+/**
+ * Fill the `<!-- WEBDA:APP -->` marker of the AGENTS.md template
+ * @param template - AGENTS.md template content
+ * @param appLines - bullet lines from `describeApp`
+ * @param notes - overlay notes, one paragraph each
+ * @returns AGENTS.md content
+ */
+export declare function renderAgentsMd(template: string, appLines: string[], notes: string[]): string;
+//# sourceMappingURL=agents.d.ts.map

package/lib/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAcrD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,SAAS,EAAE,CAAA;CAAE,GAAG,MAAM,EAAE,CAExF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAM5F"}

package/lib/agents.js

@@ -0,0 +1,33 @@
+const MARKER = "<!-- WEBDA:APP -->";
+const STORE_LINES = {
+    memory: "Store: in memory (`Webda/MemoryStore`), persisted to `.registry` between runs",
+    file: "Store: JSON files (`Webda/FileStore`) in `./data`",
+    mongodb: "Store: MongoDB (`Webda/MongoStore`), connection from `WEBDA_MONGO_URL`",
+    postgres: "Store: PostgreSQL (`Webda/PostgresStore`), connection from `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`"
+};
+const TRANSPORT_LABELS = { rest: "REST", graphql: "GraphQL", grpc: "gRPC", mcp: "MCP" };
+/**
+ * Lines describing the generated app for the "This app" section of AGENTS.md
+ * @param options - selected store and transports
+ * @param options.store - selected store backend
+ * @param options.transports - selected transport protocols
+ * @returns one line per aspect
+ */
+export function describeApp(options) {
+    return [STORE_LINES[options.store], `Transports: ${options.transports.map(t => TRANSPORT_LABELS[t]).join(", ")}`];
+}
+/**
+ * Fill the `<!-- WEBDA:APP -->` marker of the AGENTS.md template
+ * @param template - AGENTS.md template content
+ * @param appLines - bullet lines from `describeApp`
+ * @param notes - overlay notes, one paragraph each
+ * @returns AGENTS.md content
+ */
+export function renderAgentsMd(template, appLines, notes) {
+    if (!template.includes(MARKER)) {
+        throw new Error(`AGENTS.md template has no ${MARKER} marker`);
+    }
+    const section = [appLines.map(line => `- ${line}`).join("\n"), ...notes].join("\n\n");
+    return template.replace(MARKER, section);
+}
+//# sourceMappingURL=agents.js.map

package/lib/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,oBAAoB,CAAC;AAEpC,MAAM,WAAW,GAA0B;IACzC,MAAM,EAAE,+EAA+E;IACvF,IAAI,EAAE,mDAAmD;IACzD,OAAO,EAAE,wEAAwE;IACjF,QAAQ,EACN,qHAAqH;CACxH,CAAC;AAEF,MAAM,gBAAgB,GAA8B,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAEnH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAkD;IAC5E,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,eAAe,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,QAAkB,EAAE,KAAe;IAClF,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,SAAS,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtF,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/lib/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/lib/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/lib/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { defaultDeps, main } from "./index.js";
+process.exitCode = await main(await defaultDeps());
+//# sourceMappingURL=bin.js.map

package/lib/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,WAAW,EAAE,CAAC,CAAC"}

package/lib/compose.d.ts

@@ -0,0 +1,32 @@
+import type { Store, Transport } from "./options.js";
+import type { FileMap, Template } from "./template.js";
+/**
+ * The templates cannot be combined; a bug in the templates, not user input
+ */
+export declare class ComposeError extends Error {
+}
+/**
+ * Overlay folders to apply, in order: store first, then transports
+ * @param store - selected store; `memory` needs no overlay
+ * @param transports - selected transports; `rest` is part of the base
+ * @returns overlay folder names under `templates/features/`
+ */
+export declare function overlayNames(store: Store, transports: Transport[]): string[];
+export interface Composed {
+    files: FileMap;
+    packageJson: Record<string, any>;
+    config: Record<string, any>;
+    agentNotes: string[];
+}
+/**
+ * Apply overlays on top of the base template
+ * @param base - base app
+ * @param overlays - overlays in application order
+ * @param options - `rest: false` removes the base `RESTService`
+ * @param options.rest - whether to include REST service
+ * @returns merged files, package.json, configuration and agent notes
+ */
+export declare function compose(base: Template, overlays: Template[], options: {
+    rest: boolean;
+}): Composed;
+//# sourceMappingURL=compose.d.ts.map

package/lib/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEvD;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAI1C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAG5E;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,QAAQ,CAuBlG"}

package/lib/compose.js

@@ -0,0 +1,51 @@
+import { deepMerge } from "./merge.js";
+/**
+ * The templates cannot be combined; a bug in the templates, not user input
+ */
+export class ComposeError extends Error {
+}
+const TRANSPORT_OVERLAYS = ["graphql", "grpc", "mcp"];
+/**
+ * Overlay folders to apply, in order: store first, then transports
+ * @param store - selected store; `memory` needs no overlay
+ * @param transports - selected transports; `rest` is part of the base
+ * @returns overlay folder names under `templates/features/`
+ */
+export function overlayNames(store, transports) {
+    const names = store === "memory" ? [] : [`store-${store}`];
+    return [...names, ...TRANSPORT_OVERLAYS.filter(name => transports.includes(name))];
+}
+/**
+ * Apply overlays on top of the base template
+ * @param base - base app
+ * @param overlays - overlays in application order
+ * @param options - `rest: false` removes the base `RESTService`
+ * @param options.rest - whether to include REST service
+ * @returns merged files, package.json, configuration and agent notes
+ */
+export function compose(base, overlays, options) {
+    const files = new Map(base.files);
+    const owner = new Map();
+    let packageJson = base.packageJson;
+    let config = base.config;
+    const agentNotes = [];
+    for (const overlay of overlays) {
+        for (const [path, content] of overlay.files) {
+            if (owner.has(path)) {
+                throw new ComposeError(`Overlays "${owner.get(path)}" and "${overlay.name}" both write ${path}`);
+            }
+            owner.set(path, overlay.name);
+            files.set(path, content);
+        }
+        packageJson = deepMerge(packageJson, overlay.packageJson);
+        config = deepMerge(config, overlay.config);
+        if (overlay.agents.trim())
+            agentNotes.push(overlay.agents.trim());
+    }
+    if (!options.rest && config.services) {
+        config = structuredClone(config);
+        delete config.services.RESTService;
+    }
+    return { files, packageJson, config, agentNotes };
+}
+//# sourceMappingURL=compose.js.map

package/lib/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;CAAG;AAE1C,MAAM,kBAAkB,GAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,UAAuB;IAChE,MAAM,KAAK,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACrF,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,QAAoB,EAAE,OAA0B;IACtF,MAAM,KAAK,GAAY,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,IAAI,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IACnC,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACzB,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAC5C,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,YAAY,CAAC,aAAa,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,IAAI,gBAAgB,IAAI,EAAE,CAAC,CAAC;YACnG,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YAC9B,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QACD,WAAW,GAAG,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1D,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AACpD,CAAC"}

package/lib/generate.d.ts

@@ -0,0 +1,39 @@
+import { CreateOptions } from "./options.js";
+import { FileMap } from "./template.js";
+import { VersionResolver } from "./versions.js";
+/** npm 10 (bundled with Node 22) crashes resolving the optional peers of vitest/vite */
+export declare const NPMRC = "# npm 10 crashes on the optional peer dependencies of vitest/vite: safe to remove with npm >= 11\nlegacy-peer-deps=true\n";
+/**
+ * Rename `_gitignore` files and replace `__TOKEN__` placeholders
+ * @param files - generated files
+ * @param tokens - token name (without underscores) → value
+ * @returns a new map
+ */
+export declare function finalizePaths(files: FileMap, tokens: Record<string, string>): FileMap;
+/**
+ * Fail when `dir` exists and is not empty
+ * @param dir - target directory
+ */
+export declare function checkTarget(dir: string): void;
+/**
+ * Compose the application files in memory
+ * @param input - options, template folders and version resolver
+ * @param input.options - application creation options
+ * @param input.templatesDir - path to template directories
+ * @param input.agentDir - path to agent directory
+ * @param input.resolveVersion - function to resolve package versions
+ * @returns relative path → content
+ */
+export declare function generate(input: {
+    options: CreateOptions;
+    templatesDir: string;
+    agentDir: string;
+    resolveVersion: VersionResolver;
+}): Promise<FileMap>;
+/**
+ * Write generated files under `dir`
+ * @param dir - target directory, created when missing
+ * @param files - relative path → content
+ */
+export declare function writeFiles(dir: string, files: FileMap): Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/lib/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAA+B,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,OAAO,EAA0B,MAAM,eAAe,CAAC;AAChE,OAAO,EAAiB,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/D,wFAAwF;AACxF,eAAO,MAAM,KAAK,8HAEjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAWrF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAO7C;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE;IACpC,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,eAAe,CAAC;CACjC,GAAG,OAAO,CAAC,OAAO,CAAC,CAuBnB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3E"}

package/lib/generate.js

@@ -0,0 +1,85 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { describeApp, renderAgentsMd } from "./agents.js";
+import { compose, overlayNames } from "./compose.js";
+import { OptionsError, toPackageName } from "./options.js";
+import { loadTemplate, readTree } from "./template.js";
+import { applyVersions } from "./versions.js";
+/** npm 10 (bundled with Node 22) crashes resolving the optional peers of vitest/vite */
+export const NPMRC = `# npm 10 crashes on the optional peer dependencies of vitest/vite: safe to remove with npm >= 11
+legacy-peer-deps=true
+`;
+/**
+ * Rename `_gitignore` files and replace `__TOKEN__` placeholders
+ * @param files - generated files
+ * @param tokens - token name (without underscores) → value
+ * @returns a new map
+ */
+export function finalizePaths(files, tokens) {
+    const out = new Map();
+    for (const [path, content] of files) {
+        const finalPath = path.replace(/(^|\/)_gitignore$/, "$1.gitignore");
+        let finalContent = content;
+        for (const [name, value] of Object.entries(tokens)) {
+            finalContent = finalContent.replaceAll(`__${name}__`, value);
+        }
+        out.set(finalPath, finalContent);
+    }
+    return out;
+}
+/**
+ * Fail when `dir` exists and is not empty
+ * @param dir - target directory
+ */
+export function checkTarget(dir) {
+    if (existsSync(dir) && !statSync(dir).isDirectory()) {
+        throw new OptionsError(`${dir} exists and is not a directory`);
+    }
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        throw new OptionsError(`${dir} already exists and is not empty`);
+    }
+}
+/**
+ * Compose the application files in memory
+ * @param input - options, template folders and version resolver
+ * @param input.options - application creation options
+ * @param input.templatesDir - path to template directories
+ * @param input.agentDir - path to agent directory
+ * @param input.resolveVersion - function to resolve package versions
+ * @returns relative path → content
+ */
+export async function generate(input) {
+    const { options, templatesDir, agentDir } = input;
+    const base = await loadTemplate(join(templatesDir, "base"), "base");
+    const overlays = await Promise.all(overlayNames(options.store, options.transports).map(name => loadTemplate(join(templatesDir, "features", name), name)));
+    const composed = compose(base, overlays, { rest: options.transports.includes("rest") });
+    const appName = toPackageName(basename(options.dir));
+    const pkg = composed.packageJson;
+    applyVersions(pkg, input.resolveVersion);
+    const files = new Map(composed.files);
+    files.set("package.json", JSON.stringify(pkg, null, 2) + "\n");
+    if (options.pm === "npm")
+        files.set(".npmrc", NPMRC);
+    files.set("webda.config.json", JSON.stringify(composed.config, null, 2) + "\n");
+    const agentsTemplate = await readFile(join(agentDir, "AGENTS.md"), "utf8");
+    files.set("AGENTS.md", renderAgentsMd(agentsTemplate, describeApp(options), composed.agentNotes));
+    files.set("CLAUDE.md", await readFile(join(agentDir, "CLAUDE.md"), "utf8"));
+    for (const [path, content] of await readTree(join(agentDir, "skills"))) {
+        files.set(`.agents/skills/${path}`, content);
+    }
+    return finalizePaths(files, { APP_NAME: appName, NAMESPACE: options.namespace });
+}
+/**
+ * Write generated files under `dir`
+ * @param dir - target directory, created when missing
+ * @param files - relative path → content
+ */
+export async function writeFiles(dir, files) {
+    for (const [path, content] of files) {
+        const full = join(dir, path);
+        await mkdir(dirname(full), { recursive: true });
+        await writeFile(full, content);
+    }
+}
+//# sourceMappingURL=generate.js.map

package/lib/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+import { Runner } from "./install.js";
+import { Prompter } from "./prompts.js";
+export interface MainDeps {
+    argv: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    interactive: boolean;
+    prompter: Prompter;
+    run: Runner;
+    log: (message: string) => void;
+    templatesDir: string;
+    agentDir: string;
+    versions: Record<string, string>;
+}
+/**
+ * Run the CLI
+ * @param deps - environment, injectable for tests
+ * @returns process exit code
+ */
+export declare function main(deps: MainDeps): Promise<number>;
+/**
+ * Dependencies for a real run
+ * @returns deps using the process, clack prompts and the packaged templates
+ */
+export declare function defaultDeps(): Promise<MainDeps>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgC,MAAM,EAAe,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAiB,QAAQ,EAAkB,MAAM,cAAc,CAAC;AAGvE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAYD;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAqD1D;AAED;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CAcrD"}