@decohere/scaffold 0.0.1-dev.18 → 0.0.1-dev.20261105.46

package/es6/src/webapi/postman/openapi-to-postman.js

@@ -0,0 +1,179 @@
+async function convertAsync(data, options) {
+    // Loaded here, not at the top: the converter pulls in about 700 modules (lodash, faker, ajv,
+    // …), which every scaffolder run paid for even with `--postman none`.
+    const { default: converter } = await import("openapi-to-postmanv2");
+    return new Promise((resolve, reject)=>{
+        converter.convert({
+            type: "json",
+            data
+        }, options, (err, result)=>{
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve(result);
+        });
+    });
+}
+/** Convert an OpenAPI document to a Postman Collection v2.1 via openapi-to-postmanv2. */ export async function openApiToPostmanCollection(document) {
+    const result = await convertAsync(document, {
+        folderStrategy: "Tags",
+        requestNameSource: "Fallback",
+        includeAuthInfoInExample: false
+    });
+    if (!result.result || result.output?.[0]?.data == null) {
+        throw new Error(result.reason ?? "openapi-to-postmanv2 conversion failed");
+    }
+    return result.output[0].data;
+}
+/**
+ * Overlay Auth0 OAuth2 (PKCE) collection auth and fix Local View-friendly URLs.
+ * Route items come from OpenAPI; auth/env remain hand-authored.
+ */ export function applyPostmanAuthOverlay(collection, projectName, auth, options) {
+    const next = {
+        ...collection,
+        info: {
+            ...collection.info,
+            name: `${projectName} WebAPI`,
+            description: options.description,
+            schema: collection.info.schema ?? "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+        }
+    };
+    if (auth?.auth0Domain) {
+        next.auth = {
+            type: "oauth2",
+            oauth2: [
+                {
+                    key: "grant_type",
+                    value: "authorization_code_with_pkce",
+                    type: "string"
+                },
+                {
+                    key: "authUrl",
+                    value: "https://{{auth0Domain}}/authorize?audience={{auth0Audience}}",
+                    type: "string"
+                },
+                {
+                    key: "accessTokenUrl",
+                    value: "https://{{auth0Domain}}/oauth/token",
+                    type: "string"
+                },
+                {
+                    key: "clientId",
+                    value: "{{auth0ClientId}}",
+                    type: "string"
+                },
+                {
+                    key: "scope",
+                    value: options.scopes,
+                    type: "string"
+                },
+                {
+                    key: "redirect_uri",
+                    value: options.callbacks[0],
+                    type: "string"
+                },
+                {
+                    key: "useBrowser",
+                    value: "true",
+                    type: "boolean"
+                },
+                {
+                    key: "addTokenTo",
+                    value: "header",
+                    type: "string"
+                },
+                {
+                    key: "challengeAlgorithm",
+                    value: "S256",
+                    type: "string"
+                },
+                {
+                    key: "client_authentication",
+                    value: "body",
+                    type: "string"
+                },
+                {
+                    key: "clientSecret",
+                    value: "",
+                    type: "string"
+                },
+                {
+                    key: "tokenName",
+                    value: `${projectName} Access Token`,
+                    type: "string"
+                }
+            ]
+        };
+    }
+    next.item = rewriteCollectionItems(collection.item ?? [], {
+        markListAnonymous: true
+    });
+    return next;
+}
+function rewriteCollectionItems(items, opts) {
+    return items.map((item)=>{
+        if (item.item != null) {
+            return {
+                ...item,
+                item: rewriteCollectionItems(item.item, opts)
+            };
+        }
+        const request = item.request;
+        if (request == null) {
+            return item;
+        }
+        const method = (request.method ?? "GET").toUpperCase();
+        const rawUrl = requestUrlRaw(request);
+        const nextRequest = {
+            ...request,
+            url: toPostmanUrl(rawUrl)
+        };
+        // List Hello stays anonymous (matches scaffold AllowAnonymous on GET /hello).
+        if (opts.markListAnonymous && method === "GET" && normalizePath(rawUrl) === "/hello" && !rawUrl.includes("/:")) {
+            nextRequest.auth = {
+                type: "noauth"
+            };
+        }
+        return {
+            ...item,
+            request: nextRequest
+        };
+    });
+}
+function requestUrlRaw(request) {
+    const url = request.url;
+    if (typeof url === "string") {
+        return url;
+    }
+    if (url?.raw) {
+        return url.raw;
+    }
+    const host = url?.host?.[0] ?? "{{baseUrl}}";
+    const path = (url?.path ?? []).join("/");
+    return path ? `${host}/${path}` : host;
+}
+/** OpenAPI `{id}` → Postman `:id`, without touching `{{variables}}`. */ export function openApiPathParamsToColon(url) {
+    return url.replace(/(?<!\{)\{([A-Za-z_][\w]*)\}(?!\})/g, ":$1");
+}
+function normalizePath(rawUrl) {
+    const withoutBase = rawUrl.replace(/\{\{baseUrl\}\}/g, "").split("?")[0] ?? "";
+    const withSlash = withoutBase.startsWith("/") ? withoutBase : `/${withoutBase}`;
+    return openApiPathParamsToColon(withSlash);
+}
+/** Prefer Postman template URL shape used by existing Local View / API uploads. */ function toPostmanUrl(rawUrl) {
+    let pathPart = rawUrl.replace(/\{\{baseUrl\}\}/g, "");
+    if (!pathPart.startsWith("/")) {
+        pathPart = `/${pathPart}`;
+    }
+    // openapi-to-postman uses {id}; Local View / prior collections use :id
+    pathPart = openApiPathParamsToColon(pathPart);
+    const segments = pathPart.split("/").filter(Boolean);
+    return {
+        raw: `{{baseUrl}}${pathPart}`,
+        host: [
+            "{{baseUrl}}"
+        ],
+        path: segments
+    };
+}

package/es6/src/webapi/workspace-readme.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { WELL_KNOWN_FILES } from "../models/const.js";
+import { apiNameFromProjectDir, listExistingApiNames } from "./api-name.js";
+/** Pure renderer — keep feature sections short and copy-paste ready. */ export function renderWorkspaceReadme(input) {
+    const { projectName, apiNames, hasPostgres, hasAuth0, hasPostman } = input;
+    const apis = apiNames.length > 0 ? apiNames : [
+        "api"
+    ];
+    const lines = [
+        `# ${projectName}`,
+        "",
+        "Decohere web API workspace. Scaffolded with [`@decohere/create`](https://www.npmjs.com/package/@decohere/create).",
+        "",
+        "## Get started",
+        "",
+        "1. Open this folder in VS Code / Cursor.",
+        "2. **Reopen in Container** (or rebuild the Dev Container).",
+        "   Host `initialize.sh` and container `post-start.sh` ask y/N (TTY only) before npm auth or codebase RAG MCP.",
+        "   Skip or decline; missing TTY skips. RAG credentials land in `.cursor/` (gitignored).",
+        "3. Install dependencies if needed:",
+        "",
+        "```bash",
+        "pnpm install",
+        "```",
+        "",
+        "## Develop",
+        "",
+        "```bash",
+        "pnpm dev              # Flux HMR (first API)",
+        "pnpm start            # run the compiled first API",
+        "pnpm run build        # forge release build",
+        "pnpm run package      # release build + .package/ for each API (what Docker copies)"
+    ];
+    for (const name of apis){
+        lines.push(`pnpm run dev:${name}     # HMR for ${name}`);
+        lines.push(`pnpm run start:${name}   # production entry for ${name}`);
+    }
+    lines.push("```", "");
+    lines.push("## Logging", "", "In development, Scribe uses pino-pretty and rolling files under `logs/` (gitignored).", "When `NODE_ENV=production`, the process writes structured JSON to stdout and does not rotate files.", "Ship and retain those streams outside the app (platform logs, a sidecar, or a log agent) so shipping can change without rebuilding.", "", "Override roll path and rotation without changing app code:", "`SCRIBE_LOG_FILE`, `SCRIBE_LOG_SIZE`, `SCRIBE_LOG_FREQUENCY`, `SCRIBE_LOG_KEEP`.", "", 'Opt into in-process pretty or roll in production only with `{ when: "always" }` on `scribe.withPinoPretty` / `scribe.withPinoRoll`.', "");
+    if (hasPostgres) {
+        lines.push("## Database", "", "Postgres runs via Dev Container Compose:", "", "```bash", "pnpm db:up", "pnpm db:down", "pnpm db:reset", "```", "");
+    }
+    lines.push("## Deploy", "", "Each API has its own `projects/<name>/Dockerfile`. It copies `.package/`, which `forge package`", "writes before Docker runs: the API's compiled code, the workspace libraries it imports, and", "a plain `node_modules` of the third-party packages it uses (no symlinks). The image build", "installs nothing and needs no npm token.", "", "```bash", "pnpm run package         # release build, then .package/ in every API", `docker build -t ${projectName} projects/api`, "```", "", "One API: `pnpm run package:<name>`, then `docker build projects/<name>`.", "A host that builds from a git clone does not have `.package/`; build and push the image", "from CI instead (`forge docker` after `pnpm run package`).", "");
+    lines.push("## Add another API", "", "```bash", "decohere add api <name>", "```", "", "Example: `decohere add api billing`", "");
+    if (hasAuth0) {
+        lines.push("## Auth0", "", "JWT auth is wired from `.env` (`AUTH0_ISSUER_BASE_URL`, `AUTH0_AUDIENCE`).", 'After you add a controller, `@Authorize("read", "Invoice")` becomes the Auth0 permission `read:Invoice`.', "Sync the Auth0 API, admin grants, and Postman token scopes without re-scaffolding:", "", "```bash", "npx @decohere/create auth0 login      # once / when the CLI token expires", "npx @decohere/create auth0 configure  # after new @Authorize decorators", "```", "");
+    }
+    if (hasPostman) {
+        lines.push("## Postman", "", "Open this **project root** in Postman Local View (Files → Open folder), not the `postman/` subfolder.", "Select the Local environment, then Authorization → Get New Access Token when Auth0 is enabled.", "");
+    }
+    lines.push("## More", "", "- Package docs: https://www.npmjs.com/package/@decohere/create", "- After `decohere add api`, this README is refreshed so scripts and APIs stay accurate.", "");
+    return `${lines.join("\n")}`;
+}
+export function resolveWorkspaceReadmeInput(workspace, options) {
+    const newNames = workspace.getProjects().map((project)=>apiNameFromProjectDir(project.dir));
+    const apiNames = options.add ? mergeApiNames(listExistingApiNames(workspace.targetDir), newNames) : newNames;
+    const pkg = workspace.getModel(WELL_KNOWN_FILES.PACKAGE_JSON);
+    const env = workspace.getModel(WELL_KNOWN_FILES.ENV_FILE);
+    const hasPostgres = options.databaseProvider === "postgres/typeorm" || Boolean(pkg?.hasScript("db:up"));
+    const hasAuth0 = options.authProvider === "auth0" || Boolean(env?.hasEntry("AUTH0_ISSUER_BASE_URL"));
+    const hasPostman = options.postmanProvider === "local" || options.postmanProvider === "api" || existsSync(join(workspace.targetDir, "postman")) || existsSync(join(workspace.targetDir, ".postman"));
+    return {
+        projectName: workspace.name,
+        apiNames,
+        hasPostgres,
+        hasAuth0,
+        hasPostman
+    };
+}
+export function writeWorkspaceReadme(workspace, options) {
+    const content = renderWorkspaceReadme(resolveWorkspaceReadmeInput(workspace, options));
+    workspace.addFile({
+        files: ()=>[
+                {
+                    filePath: "README.md",
+                    content
+                }
+            ]
+    });
+}
+function mergeApiNames(existing, added) {
+    const seen = new Set(existing);
+    return [
+        ...existing,
+        ...added.filter((name)=>!seen.has(name))
+    ];
+}

package/es6/src/webapi.action.js

@@ -0,0 +1,18 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { injectable } from "@decohere/crucible/decorators";
+import { ActionResponse } from "@decohere/devkit/cli";
+import { runScaffoldApi, toApiOptions } from "./webapi/cli-options.js";
+export class WebapiAction {
+    async run(options) {
+        await runScaffoldApi(toApiOptions(options.directory, options));
+        return ActionResponse.Success("webapi");
+    }
+}
+WebapiAction = _ts_decorate([
+    injectable()
+], WebapiAction);

package/es6/src/webapi.command.js

@@ -0,0 +1,33 @@
+import { DecohereCommand } from "@decohere/devkit/cli";
+import { addWebapiFeatureOptions, collectName } from "./webapi/cli-options.js";
+import { WebapiAction } from "./webapi.action.js";
+export class WebapiCommand extends DecohereCommand {
+    get actions() {
+        return [
+            WebapiAction
+        ];
+    }
+    constructor(name){
+        super(name);
+        this.description("Scaffold a web API workspace");
+        this.argument("[directory]", "Target directory (default: -d or current directory)");
+        this.option("-d <directory>", "Target directory (default: current directory)", ".");
+        this.option("--name <slug>", "API name under projects/ (repeatable; default: api)", collectName, []);
+        addWebapiFeatureOptions(this);
+    }
+    /**
+	 * Commander passes positional args before options when `[directory]` is declared.
+	 * ModuleFactory expects `(opts, cmd)` — stash the directory on the command.
+	 */ action(fn) {
+        return super.action((...args)=>{
+            const cmd = args.at(-1);
+            const first = args[0];
+            const hasPositional = typeof first === "string" || first === undefined;
+            const opts = hasPositional ? args[1] : args[0];
+            if (typeof first === "string" && first !== "") {
+                cmd.setOptionValue("directory", first);
+            }
+            return fn(opts, cmd);
+        });
+    }
+}

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@decohere/scaffold",
-  "version": "0.0.1-dev.18",
-  "decohere": {
-    "dockerImageRepository": "ghcr.io/typesmiths/decohere/create",
-    "devcontainerImageRepository": "ghcr.io/typesmiths/decohere/devcontainer"
-  },
+  "version": "0.0.1-dev.20261105.46",
   "description": "Decohere project scaffolder (runs inside ghcr.io/typesmiths/decohere/create)",
   "keywords": [
     "decohere",
     "scaffold"
   ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/scaffold#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/scaffold"
+  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -26,10 +31,15 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/crucible": "0.0.1-dev.5",
-    "@decohere/nexus": "0.0.1-dev.5",
+    "@decohere/crucible": "0.0.1-dev.20261105.46",
+    "@decohere/devkit": "0.0.1-dev.20261105.46",
     "commander": "^13.1.0",
-    "openapi-to-postmanv2": "^5.0.0"
+    "openapi-to-postmanv2": "^5.0.0",
+    "yaml": "^2.9.1"
   },
-  "devDependencies": {}
+  "devDependencies": {},
+  "decohere": {
+    "dockerImageRepository": "ghcr.io/typesmiths/decohere/create",
+    "devcontainerImageRepository": "ghcr.io/typesmiths/decohere/devcontainer"
+  }
 }

package/types/src/add-api.action.d.ts

@@ -0,0 +1,13 @@
+import { type Action, ActionResponse } from "@decohere/devkit/cli";
+export type AddApiOptions = {
+    apiName?: string;
+    d?: string;
+    database?: string;
+    auth?: string;
+    postman?: string;
+    yes?: boolean;
+    install?: string;
+};
+export declare class AddApiAction implements Action<AddApiOptions> {
+    run(options: AddApiOptions): Promise<ActionResponse>;
+}

package/types/src/add-api.command.d.ts

@@ -0,0 +1,7 @@
+import { DecohereCommand } from "@decohere/devkit/cli";
+import { AddApiAction } from "./add-api.action.js";
+export declare class AddApiCommand extends DecohereCommand {
+    get actions(): (typeof AddApiAction)[];
+    constructor(name: string);
+    action(fn: (...args: unknown[]) => void | Promise<void>): this;
+}

package/types/src/add.command.d.ts

@@ -0,0 +1,6 @@
+import type { Actions } from "@decohere/devkit/cli";
+import { type CommandHandler, type CommandResponse, type CommandType, DecohereCommand } from "@decohere/devkit/cli";
+export declare class AddCommand extends DecohereCommand {
+    constructor(commands: Record<string, CommandType>, handler: CommandHandler);
+    run(_actions: Actions, _options: never): Promise<CommandResponse>;
+}

package/types/src/add.module.d.ts

@@ -0,0 +1,14 @@
+import { ModuleManifest } from "@decohere/devkit/cli";
+import { AddCommand } from "./add.command.js";
+import { AddApiAction } from "./add-api.action.js";
+import { AddApiCommand } from "./add-api.command.js";
+export declare class AddModule extends ModuleManifest {
+    readonly id = "add";
+    readonly command: typeof AddCommand;
+    readonly commands: {
+        api: typeof AddApiCommand;
+    };
+    readonly actions: {
+        api: typeof AddApiAction;
+    };
+}

package/types/src/auth0-configure.action.d.ts

@@ -0,0 +1,7 @@
+import { type Action, ActionResponse } from "@decohere/devkit/cli";
+export type Auth0ConfigureOptions = {
+    d?: string;
+};
+export declare class Auth0ConfigureAction implements Action<Auth0ConfigureOptions> {
+    run(options: Auth0ConfigureOptions): Promise<ActionResponse>;
+}

package/types/src/auth0-configure.command.d.ts

@@ -0,0 +1,6 @@
+import { DecohereCommand } from "@decohere/devkit/cli";
+import { Auth0ConfigureAction } from "./auth0-configure.action.js";
+export declare class Auth0ConfigureCommand extends DecohereCommand {
+    get actions(): (typeof Auth0ConfigureAction)[];
+    constructor(name: string);
+}

package/types/src/auth0-login.action.d.ts

@@ -0,0 +1,4 @@
+import { type Action, ActionResponse } from "@decohere/devkit/cli";
+export declare class Auth0LoginAction implements Action {
+    run(): Promise<ActionResponse>;
+}

package/types/src/auth0-login.command.d.ts

@@ -0,0 +1,6 @@
+import { DecohereCommand } from "@decohere/devkit/cli";
+import { Auth0LoginAction } from "./auth0-login.action.js";
+export declare class Auth0LoginCommand extends DecohereCommand {
+    get actions(): (typeof Auth0LoginAction)[];
+    constructor(name: string);
+}

package/types/src/auth0.command.d.ts

@@ -0,0 +1,6 @@
+import type { Actions } from "@decohere/devkit/cli";
+import { type CommandHandler, type CommandResponse, type CommandType, DecohereCommand } from "@decohere/devkit/cli";
+export declare class Auth0Command extends DecohereCommand {
+    constructor(commands: Record<string, CommandType>, handler: CommandHandler);
+    run(_actions: Actions, _options: never): Promise<CommandResponse>;
+}

package/types/src/auth0.module.d.ts

@@ -0,0 +1,18 @@
+import { ModuleManifest } from "@decohere/devkit/cli";
+import { Auth0Command } from "./auth0.command.js";
+import { Auth0ConfigureAction } from "./auth0-configure.action.js";
+import { Auth0ConfigureCommand } from "./auth0-configure.command.js";
+import { Auth0LoginAction } from "./auth0-login.action.js";
+import { Auth0LoginCommand } from "./auth0-login.command.js";
+export declare class Auth0Module extends ModuleManifest {
+    readonly id = "auth0";
+    readonly command: typeof Auth0Command;
+    readonly commands: {
+        login: typeof Auth0LoginCommand;
+        configure: typeof Auth0ConfigureCommand;
+    };
+    readonly actions: {
+        login: typeof Auth0LoginAction;
+        configure: typeof Auth0ConfigureAction;
+    };
+}

package/types/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/src/create.command.d.ts

@@ -0,0 +1,6 @@
+import type { Actions } from "@decohere/devkit/cli";
+import { type CommandHandler, type CommandResponse, type CommandType, DecohereCommand } from "@decohere/devkit/cli";
+export declare class CreateCommand extends DecohereCommand {
+    constructor(commands: Record<string, CommandType>, handler: CommandHandler);
+    run(_actions: Actions, _options: never): Promise<CommandResponse>;
+}

package/types/src/create.module.d.ts

@@ -0,0 +1,14 @@
+import { ModuleManifest } from "@decohere/devkit/cli";
+import { CreateCommand } from "./create.command.js";
+import { WebapiAction } from "./webapi.action.js";
+import { WebapiCommand } from "./webapi.command.js";
+export declare class CreateModule extends ModuleManifest {
+    readonly id = "create";
+    readonly command: typeof CreateCommand;
+    readonly commands: {
+        webapi: typeof WebapiCommand;
+    };
+    readonly actions: {
+        webapi: typeof WebapiAction;
+    };
+}

package/types/src/domain/prompt.d.ts

@@ -0,0 +1,4 @@
+/** Release stdin so the process can exit after interactive prompts. */
+export declare function closePrompt(): void;
+export declare function ask(question: string, fallback?: string): Promise<string>;
+export declare function pick<T>(label: string, items: T[], display: (item: T) => string): Promise<T | null>;

package/{src/index.ts → types/src/index.d.ts}

@@ -1,6 +1,10 @@
 export { AddModule } from "./add.module.js";
 export type { AddApiOptions } from "./add-api.action.js";
 export { AddApiAction } from "./add-api.action.js";
+export { Auth0Module } from "./auth0.module.js";
+export type { Auth0ConfigureOptions } from "./auth0-configure.action.js";
+export { Auth0ConfigureAction } from "./auth0-configure.action.js";
+export { Auth0LoginAction } from "./auth0-login.action.js";
 export { CreateModule } from "./create.module.js";
 export { runCli } from "./program.js";
 export type { ApiOptions } from "./webapi/create-api.js";

package/types/src/models/compose.model.d.ts

@@ -0,0 +1,73 @@
+import type { KeyedModel } from "./source-file.js";
+export type ComposeNetworkRef = string | {
+    /** Network key under `networks:` on this service */
+    [networkKey: string]: {
+        aliases?: string[];
+    };
+};
+export interface ComposeHealthcheck {
+    test: string[];
+    interval?: string;
+    timeout?: string;
+    retries?: number;
+}
+export interface ComposeService {
+    build?: string;
+    image?: string;
+    container_name?: string;
+    /** Quoted in YAML (`0:0` must not parse as a number). */
+    user?: string;
+    env_file?: string[];
+    environment?: Record<string, string>;
+    ports?: string[];
+    volumes?: string[];
+    command?: string;
+    restart?: string;
+    depends_on?: string[];
+    /** Compose profiles (service only starts when profile is enabled). */
+    profiles?: string[];
+    /** Attach to compose networks (string name or map with aliases). */
+    networks?: ComposeNetworkRef[];
+    healthcheck?: ComposeHealthcheck;
+}
+export type ComposeNetwork = {
+    /** Fixed Docker network name (shareable across compose projects). */
+    name: string;
+    external?: boolean;
+};
+/**
+ * Live builder for `docker-compose.yml`.
+ *
+ * Features call `addService` / `addVolume` / `addNetwork` in their scaffold phases.
+ * Loaded with `fromFile` (`decohere add api`), additions merge into the existing file:
+ * services, networks and volumes already there are left untouched, comments kept.
+ */
+export declare class DockerCompose implements KeyedModel {
+    readonly key: string;
+    private _projectName;
+    private readonly _headerComments;
+    private readonly _services;
+    private readonly _volumes;
+    private readonly _networks;
+    private readonly _envFiles;
+    private _existing;
+    /** Load an existing compose file so `decohere add api` can merge into it. */
+    static fromFile(absolutePath: string): DockerCompose;
+    /** True when the service is defined (in the loaded file or added since). */
+    hasService(name: string): boolean;
+    /** Compose project name (`name:` top-level) — isolates containers/volumes. */
+    setProjectName(name: string): this;
+    /** File-level `#` comments rendered above `name:` / `services:`. */
+    addHeaderComment(...lines: string[]): this;
+    addService(name: string, config: ComposeService): this;
+    files(): {
+        filePath: string;
+        content: string;
+    }[];
+    addVolume(name: string): this;
+    addNetwork(key: string, network: ComposeNetwork): this;
+    /** Append an env_file path to an existing service. */
+    addEnvFile(serviceName: string, filePath: string): this;
+    getContent(): string;
+    private mergeIntoExisting;
+}

package/types/src/models/config-yaml.model.d.ts

@@ -0,0 +1,27 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+/**
+ * Builder for a YAML config file (e.g. config/config.yaml or config/config.dev.yaml).
+ *
+ * Starts with a base section passed to the constructor. Features call
+ * `addSection(yaml)` during their scaffold phase to append their own block.
+ * `files()` joins all sections with a blank line separator.
+ */
+export declare class ConfigYaml implements KeyedModel {
+    readonly key: string;
+    private readonly filePath;
+    private readonly _sections;
+    constructor(key: string, filePath: string, baseContent: string);
+    addSection(yaml: string): this;
+    /** True when a datasource with this `name:` already appears in the file. */
+    hasDataSource(name: string): boolean;
+    hasDataSources(): boolean;
+    /**
+     * Insert a `dataSources` list item. Used by `webapi add` so we do not write a
+     * second top-level `database:` key (YAML last-key-wins).
+     */
+    appendDataSource(item: string): this;
+    static fromFile(key: string, relativePath: string, absolutePath: string): ConfigYaml;
+    files(): SourceFile[];
+}
+/** Insert a YAML list item under `dataSources:`; append a new `database:` block if missing. */
+export declare function injectYamlDataSource(yaml: string, item: string): string;

package/types/src/models/const.d.ts

@@ -0,0 +1,20 @@
+export declare const WELL_KNOWN_FILES: {
+    VSCODE_SETTINGS: string;
+    LAUNCH_JSON: string;
+    DOCKER_COMPOSE: string;
+    DEVCONTAINER_JSON: string;
+    DOCKERFILE: string;
+    PRODUCTION_DOCKERFILE: string;
+    GITHUB_CI: string;
+    PACKAGE_JSON: string;
+    API_PACKAGE_JSON: string;
+    TSCONFIG: string;
+    VITEST_CONFIG: string;
+    MAIN_TS: string;
+    CONTROLLER_TS: string;
+    CONFIG_YAML: string;
+    CONFIG_DEV_YAML: string;
+    GITIGNORE: string;
+    AUTH_CONFIG: string;
+    ENV_FILE: string;
+};