@decohere/scaffold 0.0.1-dev.92 → 0.0.1-dev.93

package/commonjs/src/models/compose.model.js

@@ -8,6 +8,8 @@ Object.defineProperty(exports, "DockerCompose", {
         return DockerCompose;
     }
 });
+const _nodefs = require("node:fs");
+const _yaml = require("yaml");
 const _const = require("./const.js");
 class DockerCompose {
     key = _const.WELL_KNOWN_FILES.DOCKER_COMPOSE;
@@ -16,6 +18,19 @@ class DockerCompose {
     _services = new Map();
     _volumes = new Set();
     _networks = new Map();
+    _envFiles = [];
+    _existing;
+    /** Load an existing compose file so `decohere add api` can merge into it. */ static fromFile(absolutePath) {
+        const compose = new DockerCompose();
+        compose._existing = (0, _yaml.parseDocument)((0, _nodefs.readFileSync)(absolutePath, "utf8"));
+        return compose;
+    }
+    /** True when the service is defined (in the loaded file or added since). */ hasService(name) {
+        return this._services.has(name) || this._existing?.hasIn([
+            "services",
+            name
+        ]) === true;
+    }
     /** Compose project name (`name:` top-level) — isolates containers/volumes. */ setProjectName(name) {
         this._projectName = name;
         return this;
@@ -45,14 +60,23 @@ class DockerCompose {
         return this;
     }
     /** Append an env_file path to an existing service. */ addEnvFile(serviceName, filePath) {
-        const svc = this._services.get(serviceName);
+        // A service already in the loaded file wins over an `addService` of the same name.
+        const svc = this._existing?.hasIn([
+            "services",
+            serviceName
+        ]) ? undefined : this._services.get(serviceName);
         if (svc) svc.env_file = [
             ...svc.env_file ?? [],
             filePath
         ];
+        else this._envFiles.push([
+            serviceName,
+            filePath
+        ]);
         return this;
     }
     getContent() {
+        if (this._existing) return this.mergeIntoExisting(this._existing);
         const lines = [];
         for (const comment of this._headerComments){
             lines.push(comment.startsWith("#") ? comment : `# ${comment}`);
@@ -145,4 +169,90 @@ class DockerCompose {
         }
         return `${lines.join("\n")}\n`;
     }
+    mergeIntoExisting(doc) {
+        if (!(0, _yaml.isMap)(doc.contents)) throw new Error("docker-compose.yml is not a YAML mapping");
+        for (const line of this._headerComments){
+            const text = line.replace(/^#\s?/, "");
+            const before = doc.commentBefore ?? "";
+            if (!before.includes(text)) doc.commentBefore = before ? `${before}\n ${text}` : ` ${text}`;
+        }
+        for (const [name, svc] of this._services){
+            if (!doc.hasIn([
+                "services",
+                name
+            ])) doc.setIn([
+                "services",
+                name
+            ], doc.createNode(toComposeYaml(svc)));
+        }
+        for (const [service, path] of this._envFiles){
+            if (!doc.hasIn([
+                "services",
+                service
+            ])) continue;
+            const envFiles = doc.getIn([
+                "services",
+                service,
+                "env_file"
+            ]);
+            if ((0, _yaml.isSeq)(envFiles)) {
+                if (!envFiles.items.some((item)=>String(item) === path)) envFiles.add(path);
+            } else if (envFiles == null) {
+                doc.setIn([
+                    "services",
+                    service,
+                    "env_file"
+                ], doc.createNode([
+                    path
+                ]));
+            } else if (String(envFiles) !== path) {
+                doc.setIn([
+                    "services",
+                    service,
+                    "env_file"
+                ], doc.createNode([
+                    String(envFiles),
+                    path
+                ]));
+            }
+        }
+        for (const [key, network] of this._networks){
+            if (!doc.hasIn([
+                "networks",
+                key
+            ])) doc.setIn([
+                "networks",
+                key
+            ], doc.createNode(network));
+        }
+        for (const volume of this._volumes){
+            if (!doc.hasIn([
+                "volumes",
+                volume
+            ])) doc.setIn([
+                "volumes",
+                volume
+            ], null);
+        }
+        return doc.toString({
+            lineWidth: 0
+        });
+    }
+}
+/** Plain compose YAML shape for a service (networks with aliases become a map). */ function toComposeYaml(svc) {
+    const { networks, ...rest } = svc;
+    if (!networks || networks.length === 0) return rest;
+    if (networks.every((n)=>typeof n === "string")) return {
+        ...rest,
+        networks
+    };
+    const networkMap = {};
+    for (const network of networks){
+        if (typeof network === "string") networkMap[network] = null;
+        else Object.assign(networkMap, network);
+    }
+    return {
+        ...rest,
+        networks: networkMap
+    };
 }

package/commonjs/src/models/dev-container.model.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "DevContainer", {
         return DevContainer;
     }
 });
+const _nodefs = require("node:fs");
 const _const = require("./const.js");
 class DevContainer {
     key = _const.WELL_KNOWN_FILES.DEVCONTAINER_JSON;
@@ -22,6 +23,19 @@ class DevContainer {
     _initializeCommand;
     _remoteUser = "node";
     _useCompose = false;
+    _existing;
+    /**
+	 * Load an existing devcontainer.json so `decohere add api` can merge into it.
+	 * Only extensions, forwarded ports and port attributes are merged; everything else is kept.
+	 */ static fromFile(absolutePath) {
+        const devContainer = new DevContainer();
+        try {
+            devContainer._existing = JSON.parse((0, _nodefs.readFileSync)(absolutePath, "utf8"));
+        } catch (error) {
+            throw new Error(`Can't update ${absolutePath}: it isn't plain JSON (${error.message}). Remove any comments or trailing commas and try again.`);
+        }
+        return devContainer;
+    }
     constructor(){
         this._mounts = [
             this.bindMount(this._workspaceFolder)
@@ -74,6 +88,33 @@ class DevContainer {
         return this;
     }
     files() {
+        const config = this._existing ? this.mergeIntoExisting(this._existing) : this.build();
+        return [
+            {
+                filePath: ".devcontainer/devcontainer.json",
+                content: JSON.stringify(config, null, 2)
+            }
+        ];
+    }
+    mergeIntoExisting(existing) {
+        const config = structuredClone(existing);
+        if (this._extensions.length > 0) {
+            const customizations = objectAt(config, "customizations");
+            const vscode = objectAt(customizations, "vscode");
+            vscode.extensions = union(vscode.extensions, this._extensions);
+        }
+        if (this._ports.length > 0) {
+            config.forwardPorts = union(config.forwardPorts, this._ports);
+        }
+        if (this._portAttributes.size > 0) {
+            const attributes = objectAt(config, "portsAttributes");
+            for (const [port, attrs] of this._portAttributes){
+                attributes[String(port)] ??= attrs;
+            }
+        }
+        return config;
+    }
+    build() {
         const config = {};
         if (this._useCompose) {
             config.dockerComposeFile = "docker-compose.yml";
@@ -115,11 +156,17 @@ class DevContainer {
         if (this._remoteUser) {
             config.remoteUser = this._remoteUser;
         }
-        return [
-            {
-                filePath: ".devcontainer/devcontainer.json",
-                content: JSON.stringify(config, null, 2)
-            }
-        ];
+        return config;
     }
 }
+/** The object at `parent[key]`, created when missing. */ function objectAt(parent, key) {
+    parent[key] ??= {};
+    return parent[key];
+}
+function union(existing, additions) {
+    const items = Array.isArray(existing) ? [
+        ...existing
+    ] : [];
+    for (const item of additions)if (!items.includes(item)) items.push(item);
+    return items;
+}

package/commonjs/src/models/docker-image.model.js

@@ -46,6 +46,7 @@ _export(exports, {
         return withWorkspaceNodeModulesOwnership;
     }
 });
+const _nodefs = require("node:fs");
 const _const = require("./const.js");
 class DockerStep {
     key;
@@ -168,10 +169,22 @@ class DockerfileModel {
     _layerWriters = [];
     _fromImage;
     _layerCounter = 0;
+    _existing;
     constructor(baseImage){
         this._fromImage = baseImage;
         this.registerBaseLayers();
     }
+    /**
+	 * Load an existing Dockerfile so `decohere add api` can append feature layers.
+	 * The new steps are appended as one block, unless the file already contains it.
+	 */ static fromFile(absolutePath, filePath) {
+        const dockerfile = new DockerfileModel("");
+        dockerfile._existing = {
+            content: (0, _nodefs.readFileSync)(absolutePath, "utf8"),
+            filePath
+        };
+        return dockerfile;
+    }
     from(baseImage) {
         this._fromImage = baseImage;
         return this;
@@ -207,9 +220,6 @@ class DockerfileModel {
         for (const layerWriter of this._layerWriters){
             layerWriter(this);
         }
-        const lines = [
-            `FROM ${this._fromImage}`
-        ];
         const sortedSteps = [
             ...this._steps.values()
         ].sort((left, right)=>{
@@ -218,6 +228,16 @@ class DockerfileModel {
             }
             return left.key.localeCompare(right.key, "en");
         });
+        if (this._existing) {
+            // All or nothing: skipping one step of a layer (e.g. its `USER root`) would break the rest.
+            const { content } = this._existing;
+            const block = sortedSteps.map((step)=>step.content).join("\n\n");
+            if (block === "" || content.includes(block)) return content;
+            return `${content.replace(/\n*$/, "\n")}\n${block}\n`;
+        }
+        const lines = [
+            `FROM ${this._fromImage}`
+        ];
         for (const step of sortedSteps){
             lines.push("", step.content);
         }
@@ -229,7 +249,7 @@ class DockerfileModel {
     files() {
         return [
             {
-                filePath: "./Dockerfile",
+                filePath: this._existing?.filePath ?? "./Dockerfile",
                 content: this.build()
             }
         ];

package/commonjs/src/models/gitignore.model.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "Gitignore", {
         return Gitignore;
     }
 });
+const _nodefs = require("node:fs");
 const _const = require("./const.js");
 class Gitignore {
     key = _const.WELL_KNOWN_FILES.GITIGNORE;
@@ -22,6 +23,11 @@ class Gitignore {
         ".DS_Store",
         "logs"
     ];
+    /** Load an existing .gitignore so `decohere add api` appends instead of replacing. */ static fromFile(absolutePath) {
+        const gitignore = new Gitignore();
+        gitignore.ignoreList = (0, _nodefs.readFileSync)(absolutePath, "utf8").replace(/\n+$/, "").split("\n");
+        return gitignore;
+    }
     add(...patterns) {
         for (const pattern of patterns){
             if (!this.ignoreList.includes(pattern)) {

package/commonjs/src/webapi/create-api.js

@@ -100,14 +100,7 @@ function createWorkspace(targetDir, projectName, apiNames) {
     }).addVolume("webapi-node-modules").addVolume(_dockerimagemodel.commandHistory.volumeName);
     const installCmd = "bash .devcontainer/post-create.sh";
     const devContainer = new _devcontainermodel.DevContainer().setWorkspaceFolder(workspaceRoot).addExtension("biomejs.biome", "vitest.explorer").setInitializeCommand("bash .devcontainer/initialize.sh").setPostCreateCommand(installCmd).setUpdateContentCommand(installCmd).setPostStartCommand("bash .devcontainer/post-start.sh").useCompose();
-    for (const [index, apiName] of apiNames.entries()){
-        const port = (0, _const1.webapiPort)(index);
-        devContainer.forwardPort(port);
-        devContainer.setPortAttributes(port, {
-            label: apiName === _const1.DEFAULT_WEBAPI_NAME ? "API" : apiName,
-            requireLocalPort: true
-        });
-    }
+    forwardApiPorts(devContainer, apiNames, 0);
     // Workspace-level models (repo root)
     monoRepo.addModel(compose);
     monoRepo.addModel(devContainer);
@@ -221,6 +214,19 @@ function createAddWorkspace(targetDir, projectName, apiNames) {
     monoRepo.addModel((0, _nodefs.existsSync)((0, _nodepath.join)(targetDir, ".env")) ? _envfilemodel.EnvFile.fromFile((0, _nodepath.join)(targetDir, ".env")) : new _envfilemodel.EnvFile());
     monoRepo.addModel((0, _nodefs.existsSync)((0, _nodepath.join)(targetDir, "config/config.yaml")) ? _configyamlmodel.ConfigYaml.fromFile(_const.WELL_KNOWN_FILES.CONFIG_YAML, "config/config.yaml", (0, _nodepath.join)(targetDir, "config/config.yaml")) : new _configyamlmodel.ConfigYaml(_const.WELL_KNOWN_FILES.CONFIG_YAML, "config/config.yaml", ""));
     monoRepo.addModel((0, _nodefs.existsSync)((0, _nodepath.join)(targetDir, "config/config.dev.yaml")) ? _configyamlmodel.ConfigYaml.fromFile(_const.WELL_KNOWN_FILES.CONFIG_DEV_YAML, "config/config.dev.yaml", (0, _nodepath.join)(targetDir, "config/config.dev.yaml")) : new _configyamlmodel.ConfigYaml(_const.WELL_KNOWN_FILES.CONFIG_DEV_YAML, "config/config.dev.yaml", ""));
+    // Load the workspace files features merge into, so e.g. --database on a workspace
+    // created without one adds the Postgres service instead of only the db:* scripts.
+    const compose = loadIfExists(targetDir, ".devcontainer/docker-compose.yml", (path)=>_composemodel.DockerCompose.fromFile(path));
+    if (compose) monoRepo.addModel(compose);
+    const devContainer = loadIfExists(targetDir, ".devcontainer/devcontainer.json", (path)=>_devcontainermodel.DevContainer.fromFile(path));
+    if (devContainer) {
+        forwardApiPorts(devContainer, apiNames, existing.length);
+        monoRepo.addModel(devContainer);
+    }
+    const devImage = loadIfExists(targetDir, ".devcontainer/Dockerfile", (path)=>_dockerimagemodel.DockerfileModel.fromFile(path, ".devcontainer/Dockerfile"));
+    if (devImage) monoRepo.addModel(devImage);
+    const gitignore = loadIfExists(targetDir, ".gitignore", (path)=>_gitignoremodel.Gitignore.fromFile(path));
+    if (gitignore) monoRepo.addModel(gitignore);
     for (const [offset, apiName] of apiNames.entries()){
         const port = (0, _const1.webapiPort)(existing.length + offset);
         pkg.addScript(`start:${apiName}`, `node ${(0, _const1.webapiReleaseEntry)(apiName)}`);
@@ -241,3 +247,17 @@ function addApiProject(monoRepo, workspaceName, apiName) {
     apiProject.addFile(new _samplefilesmodel.SampleServiceModel());
     monoRepo.addProject(apiProject);
 }
+function forwardApiPorts(devContainer, apiNames, firstIndex) {
+    for (const [offset, apiName] of apiNames.entries()){
+        const port = (0, _const1.webapiPort)(firstIndex + offset);
+        devContainer.forwardPort(port);
+        devContainer.setPortAttributes(port, {
+            label: apiName === _const1.DEFAULT_WEBAPI_NAME ? "API" : apiName,
+            requireLocalPort: true
+        });
+    }
+}
+function loadIfExists(targetDir, relativePath, load) {
+    const absolutePath = (0, _nodepath.join)(targetDir, relativePath);
+    return (0, _nodefs.existsSync)(absolutePath) ? load(absolutePath) : undefined;
+}

package/commonjs/src/webapi/features/database.feature.js

@@ -289,7 +289,8 @@ function scaffold(workspace, options) {
     const devContainer = workspace.getModel(_const.WELL_KNOWN_FILES.DEVCONTAINER_JSON);
     const compose = workspace.getModel(_const.WELL_KNOWN_FILES.DOCKER_COMPOSE);
     const networkKey = name;
-    if (compose) {
+    // Skip when the workspace already runs Postgres (`decohere add api` on a database workspace).
+    if (compose && !compose.hasService("postgres")) {
         // One shared instance. Each API owns a database on it (created at bootstrap).
         // Point `{PREFIX}_DB_HOST` / `{PREFIX}_DB_PORT` at another server to split later.
         // Custom image: sync bootstrap role password on every start (initdb.d is once-only).

package/commonjs/src/webapi/models/production-dockerfile.model.js

@@ -81,7 +81,9 @@ COPY package.json ./
 COPY pnpm-lock.yaml* ./
 COPY tsconfig.json biome.json ./
 COPY config ./config
-COPY ${projectDir} ./${projectDir}
+# Every package under projects/ — the API imports workspace libraries (e.g. *.domain).
+# Forge builds them all into dist/; only dist/ (not source) reaches the run image.
+COPY projects ./projects
 
 ${renderPnpmInstall("all")}
 
@@ -136,8 +138,8 @@ RUN --mount=type=secret,id=npm_token,required=false \\
 }
 function dockerignoreContent() {
     return [
-        "node_modules",
-        "dist",
+        "**/node_modules",
+        "**/dist",
         ".git",
         ".devcontainer",
         ".vscode",

package/es6/src/models/compose.model.js

@@ -1,8 +1,12 @@
+import { readFileSync } from "node:fs";
+import { isMap, isSeq, parseDocument } from "yaml";
 import { WELL_KNOWN_FILES } from "./const.js";
 /**
  * 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 class DockerCompose {
     key = WELL_KNOWN_FILES.DOCKER_COMPOSE;
     _projectName;
@@ -10,6 +14,19 @@ import { WELL_KNOWN_FILES } from "./const.js";
     _services = new Map();
     _volumes = new Set();
     _networks = new Map();
+    _envFiles = [];
+    _existing;
+    /** Load an existing compose file so `decohere add api` can merge into it. */ static fromFile(absolutePath) {
+        const compose = new DockerCompose();
+        compose._existing = parseDocument(readFileSync(absolutePath, "utf8"));
+        return compose;
+    }
+    /** True when the service is defined (in the loaded file or added since). */ hasService(name) {
+        return this._services.has(name) || this._existing?.hasIn([
+            "services",
+            name
+        ]) === true;
+    }
     /** Compose project name (`name:` top-level) — isolates containers/volumes. */ setProjectName(name) {
         this._projectName = name;
         return this;
@@ -39,14 +56,23 @@ import { WELL_KNOWN_FILES } from "./const.js";
         return this;
     }
     /** Append an env_file path to an existing service. */ addEnvFile(serviceName, filePath) {
-        const svc = this._services.get(serviceName);
+        // A service already in the loaded file wins over an `addService` of the same name.
+        const svc = this._existing?.hasIn([
+            "services",
+            serviceName
+        ]) ? undefined : this._services.get(serviceName);
         if (svc) svc.env_file = [
             ...svc.env_file ?? [],
             filePath
         ];
+        else this._envFiles.push([
+            serviceName,
+            filePath
+        ]);
         return this;
     }
     getContent() {
+        if (this._existing) return this.mergeIntoExisting(this._existing);
         const lines = [];
         for (const comment of this._headerComments){
             lines.push(comment.startsWith("#") ? comment : `# ${comment}`);
@@ -139,4 +165,90 @@ import { WELL_KNOWN_FILES } from "./const.js";
         }
         return `${lines.join("\n")}\n`;
     }
+    mergeIntoExisting(doc) {
+        if (!isMap(doc.contents)) throw new Error("docker-compose.yml is not a YAML mapping");
+        for (const line of this._headerComments){
+            const text = line.replace(/^#\s?/, "");
+            const before = doc.commentBefore ?? "";
+            if (!before.includes(text)) doc.commentBefore = before ? `${before}\n ${text}` : ` ${text}`;
+        }
+        for (const [name, svc] of this._services){
+            if (!doc.hasIn([
+                "services",
+                name
+            ])) doc.setIn([
+                "services",
+                name
+            ], doc.createNode(toComposeYaml(svc)));
+        }
+        for (const [service, path] of this._envFiles){
+            if (!doc.hasIn([
+                "services",
+                service
+            ])) continue;
+            const envFiles = doc.getIn([
+                "services",
+                service,
+                "env_file"
+            ]);
+            if (isSeq(envFiles)) {
+                if (!envFiles.items.some((item)=>String(item) === path)) envFiles.add(path);
+            } else if (envFiles == null) {
+                doc.setIn([
+                    "services",
+                    service,
+                    "env_file"
+                ], doc.createNode([
+                    path
+                ]));
+            } else if (String(envFiles) !== path) {
+                doc.setIn([
+                    "services",
+                    service,
+                    "env_file"
+                ], doc.createNode([
+                    String(envFiles),
+                    path
+                ]));
+            }
+        }
+        for (const [key, network] of this._networks){
+            if (!doc.hasIn([
+                "networks",
+                key
+            ])) doc.setIn([
+                "networks",
+                key
+            ], doc.createNode(network));
+        }
+        for (const volume of this._volumes){
+            if (!doc.hasIn([
+                "volumes",
+                volume
+            ])) doc.setIn([
+                "volumes",
+                volume
+            ], null);
+        }
+        return doc.toString({
+            lineWidth: 0
+        });
+    }
+}
+/** Plain compose YAML shape for a service (networks with aliases become a map). */ function toComposeYaml(svc) {
+    const { networks, ...rest } = svc;
+    if (!networks || networks.length === 0) return rest;
+    if (networks.every((n)=>typeof n === "string")) return {
+        ...rest,
+        networks
+    };
+    const networkMap = {};
+    for (const network of networks){
+        if (typeof network === "string") networkMap[network] = null;
+        else Object.assign(networkMap, network);
+    }
+    return {
+        ...rest,
+        networks: networkMap
+    };
 }

package/es6/src/models/dev-container.model.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { WELL_KNOWN_FILES } from "./const.js";
 export class DevContainer {
     key = WELL_KNOWN_FILES.DEVCONTAINER_JSON;
@@ -12,6 +13,19 @@ export class DevContainer {
     _initializeCommand;
     _remoteUser = "node";
     _useCompose = false;
+    _existing;
+    /**
+	 * Load an existing devcontainer.json so `decohere add api` can merge into it.
+	 * Only extensions, forwarded ports and port attributes are merged; everything else is kept.
+	 */ static fromFile(absolutePath) {
+        const devContainer = new DevContainer();
+        try {
+            devContainer._existing = JSON.parse(readFileSync(absolutePath, "utf8"));
+        } catch (error) {
+            throw new Error(`Can't update ${absolutePath}: it isn't plain JSON (${error.message}). Remove any comments or trailing commas and try again.`);
+        }
+        return devContainer;
+    }
     constructor(){
         this._mounts = [
             this.bindMount(this._workspaceFolder)
@@ -64,6 +78,33 @@ export class DevContainer {
         return this;
     }
     files() {
+        const config = this._existing ? this.mergeIntoExisting(this._existing) : this.build();
+        return [
+            {
+                filePath: ".devcontainer/devcontainer.json",
+                content: JSON.stringify(config, null, 2)
+            }
+        ];
+    }
+    mergeIntoExisting(existing) {
+        const config = structuredClone(existing);
+        if (this._extensions.length > 0) {
+            const customizations = objectAt(config, "customizations");
+            const vscode = objectAt(customizations, "vscode");
+            vscode.extensions = union(vscode.extensions, this._extensions);
+        }
+        if (this._ports.length > 0) {
+            config.forwardPorts = union(config.forwardPorts, this._ports);
+        }
+        if (this._portAttributes.size > 0) {
+            const attributes = objectAt(config, "portsAttributes");
+            for (const [port, attrs] of this._portAttributes){
+                attributes[String(port)] ??= attrs;
+            }
+        }
+        return config;
+    }
+    build() {
         const config = {};
         if (this._useCompose) {
             config.dockerComposeFile = "docker-compose.yml";
@@ -105,11 +146,17 @@ export class DevContainer {
         if (this._remoteUser) {
             config.remoteUser = this._remoteUser;
         }
-        return [
-            {
-                filePath: ".devcontainer/devcontainer.json",
-                content: JSON.stringify(config, null, 2)
-            }
-        ];
+        return config;
     }
 }
+/** The object at `parent[key]`, created when missing. */ function objectAt(parent, key) {
+    parent[key] ??= {};
+    return parent[key];
+}
+function union(existing, additions) {
+    const items = Array.isArray(existing) ? [
+        ...existing
+    ] : [];
+    for (const item of additions)if (!items.includes(item)) items.push(item);
+    return items;
+}

package/es6/src/models/docker-image.model.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { WELL_KNOWN_FILES } from "./const.js";
 export class DockerStep {
     key;
@@ -123,10 +124,22 @@ export class DockerfileModel {
     _layerWriters = [];
     _fromImage;
     _layerCounter = 0;
+    _existing;
     constructor(baseImage){
         this._fromImage = baseImage;
         this.registerBaseLayers();
     }
+    /**
+	 * Load an existing Dockerfile so `decohere add api` can append feature layers.
+	 * The new steps are appended as one block, unless the file already contains it.
+	 */ static fromFile(absolutePath, filePath) {
+        const dockerfile = new DockerfileModel("");
+        dockerfile._existing = {
+            content: readFileSync(absolutePath, "utf8"),
+            filePath
+        };
+        return dockerfile;
+    }
     from(baseImage) {
         this._fromImage = baseImage;
         return this;
@@ -162,9 +175,6 @@ export class DockerfileModel {
         for (const layerWriter of this._layerWriters){
             layerWriter(this);
         }
-        const lines = [
-            `FROM ${this._fromImage}`
-        ];
         const sortedSteps = [
             ...this._steps.values()
         ].sort((left, right)=>{
@@ -173,6 +183,16 @@ export class DockerfileModel {
             }
             return left.key.localeCompare(right.key, "en");
         });
+        if (this._existing) {
+            // All or nothing: skipping one step of a layer (e.g. its `USER root`) would break the rest.
+            const { content } = this._existing;
+            const block = sortedSteps.map((step)=>step.content).join("\n\n");
+            if (block === "" || content.includes(block)) return content;
+            return `${content.replace(/\n*$/, "\n")}\n${block}\n`;
+        }
+        const lines = [
+            `FROM ${this._fromImage}`
+        ];
         for (const step of sortedSteps){
             lines.push("", step.content);
         }
@@ -184,7 +204,7 @@ export class DockerfileModel {
     files() {
         return [
             {
-                filePath: "./Dockerfile",
+                filePath: this._existing?.filePath ?? "./Dockerfile",
                 content: this.build()
             }
         ];

package/es6/src/models/gitignore.model.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { WELL_KNOWN_FILES } from "./const.js";
 export class Gitignore {
     key = WELL_KNOWN_FILES.GITIGNORE;
@@ -12,6 +13,11 @@ export class Gitignore {
         ".DS_Store",
         "logs"
     ];
+    /** Load an existing .gitignore so `decohere add api` appends instead of replacing. */ static fromFile(absolutePath) {
+        const gitignore = new Gitignore();
+        gitignore.ignoreList = readFileSync(absolutePath, "utf8").replace(/\n+$/, "").split("\n");
+        return gitignore;
+    }
     add(...patterns) {
         for (const pattern of patterns){
             if (!this.ignoreList.includes(pattern)) {

package/es6/src/webapi/create-api.js

@@ -4,7 +4,7 @@ import { DockerCompose } from "../models/compose.model.js";
 import { ConfigYaml } from "../models/config-yaml.model.js";
 import { WELL_KNOWN_FILES } from "../models/const.js";
 import { DevContainer } from "../models/dev-container.model.js";
-import { commandHistory, withWorkspaceNodeModulesOwnership } from "../models/docker-image.model.js";
+import { commandHistory, DockerfileModel, withWorkspaceNodeModulesOwnership } from "../models/docker-image.model.js";
 import { EnvFile } from "../models/env-file.model.js";
 import { Gitignore } from "../models/gitignore.model.js";
 import { LaunchJson } from "../models/launch-json.model.js";
@@ -80,14 +80,7 @@ function createWorkspace(targetDir, projectName, apiNames) {
     }).addVolume("webapi-node-modules").addVolume(commandHistory.volumeName);
     const installCmd = "bash .devcontainer/post-create.sh";
     const devContainer = new DevContainer().setWorkspaceFolder(workspaceRoot).addExtension("biomejs.biome", "vitest.explorer").setInitializeCommand("bash .devcontainer/initialize.sh").setPostCreateCommand(installCmd).setUpdateContentCommand(installCmd).setPostStartCommand("bash .devcontainer/post-start.sh").useCompose();
-    for (const [index, apiName] of apiNames.entries()){
-        const port = webapiPort(index);
-        devContainer.forwardPort(port);
-        devContainer.setPortAttributes(port, {
-            label: apiName === DEFAULT_WEBAPI_NAME ? "API" : apiName,
-            requireLocalPort: true
-        });
-    }
+    forwardApiPorts(devContainer, apiNames, 0);
     // Workspace-level models (repo root)
     monoRepo.addModel(compose);
     monoRepo.addModel(devContainer);
@@ -201,6 +194,19 @@ function createAddWorkspace(targetDir, projectName, apiNames) {
     monoRepo.addModel(existsSync(join(targetDir, ".env")) ? EnvFile.fromFile(join(targetDir, ".env")) : new EnvFile());
     monoRepo.addModel(existsSync(join(targetDir, "config/config.yaml")) ? ConfigYaml.fromFile(WELL_KNOWN_FILES.CONFIG_YAML, "config/config.yaml", join(targetDir, "config/config.yaml")) : new ConfigYaml(WELL_KNOWN_FILES.CONFIG_YAML, "config/config.yaml", ""));
     monoRepo.addModel(existsSync(join(targetDir, "config/config.dev.yaml")) ? ConfigYaml.fromFile(WELL_KNOWN_FILES.CONFIG_DEV_YAML, "config/config.dev.yaml", join(targetDir, "config/config.dev.yaml")) : new ConfigYaml(WELL_KNOWN_FILES.CONFIG_DEV_YAML, "config/config.dev.yaml", ""));
+    // Load the workspace files features merge into, so e.g. --database on a workspace
+    // created without one adds the Postgres service instead of only the db:* scripts.
+    const compose = loadIfExists(targetDir, ".devcontainer/docker-compose.yml", (path)=>DockerCompose.fromFile(path));
+    if (compose) monoRepo.addModel(compose);
+    const devContainer = loadIfExists(targetDir, ".devcontainer/devcontainer.json", (path)=>DevContainer.fromFile(path));
+    if (devContainer) {
+        forwardApiPorts(devContainer, apiNames, existing.length);
+        monoRepo.addModel(devContainer);
+    }
+    const devImage = loadIfExists(targetDir, ".devcontainer/Dockerfile", (path)=>DockerfileModel.fromFile(path, ".devcontainer/Dockerfile"));
+    if (devImage) monoRepo.addModel(devImage);
+    const gitignore = loadIfExists(targetDir, ".gitignore", (path)=>Gitignore.fromFile(path));
+    if (gitignore) monoRepo.addModel(gitignore);
     for (const [offset, apiName] of apiNames.entries()){
         const port = webapiPort(existing.length + offset);
         pkg.addScript(`start:${apiName}`, `node ${webapiReleaseEntry(apiName)}`);
@@ -221,3 +227,17 @@ function addApiProject(monoRepo, workspaceName, apiName) {
     apiProject.addFile(new SampleServiceModel());
     monoRepo.addProject(apiProject);
 }
+function forwardApiPorts(devContainer, apiNames, firstIndex) {
+    for (const [offset, apiName] of apiNames.entries()){
+        const port = webapiPort(firstIndex + offset);
+        devContainer.forwardPort(port);
+        devContainer.setPortAttributes(port, {
+            label: apiName === DEFAULT_WEBAPI_NAME ? "API" : apiName,
+            requireLocalPort: true
+        });
+    }
+}
+function loadIfExists(targetDir, relativePath, load) {
+    const absolutePath = join(targetDir, relativePath);
+    return existsSync(absolutePath) ? load(absolutePath) : undefined;
+}

package/es6/src/webapi/features/database.feature.js

@@ -279,7 +279,8 @@ function scaffold(workspace, options) {
     const devContainer = workspace.getModel(WELL_KNOWN_FILES.DEVCONTAINER_JSON);
     const compose = workspace.getModel(WELL_KNOWN_FILES.DOCKER_COMPOSE);
     const networkKey = name;
-    if (compose) {
+    // Skip when the workspace already runs Postgres (`decohere add api` on a database workspace).
+    if (compose && !compose.hasService("postgres")) {
         // One shared instance. Each API owns a database on it (created at bootstrap).
         // Point `{PREFIX}_DB_HOST` / `{PREFIX}_DB_PORT` at another server to split later.
         // Custom image: sync bootstrap role password on every start (initdb.d is once-only).

package/es6/src/webapi/models/production-dockerfile.model.js

@@ -72,7 +72,9 @@ COPY package.json ./
 COPY pnpm-lock.yaml* ./
 COPY tsconfig.json biome.json ./
 COPY config ./config
-COPY ${projectDir} ./${projectDir}
+# Every package under projects/ — the API imports workspace libraries (e.g. *.domain).
+# Forge builds them all into dist/; only dist/ (not source) reaches the run image.
+COPY projects ./projects
 
 ${renderPnpmInstall("all")}
 
@@ -127,8 +129,8 @@ RUN --mount=type=secret,id=npm_token,required=false \\
 }
 function dockerignoreContent() {
     return [
-        "node_modules",
-        "dist",
+        "**/node_modules",
+        "**/dist",
         ".git",
         ".devcontainer",
         ".vscode",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/scaffold",
-  "version": "0.0.1-dev.92",
+  "version": "0.0.1-dev.93",
   "description": "Decohere project scaffolder (runs inside ghcr.io/typesmiths/decohere/create)",
   "keywords": [
     "decohere",
@@ -22,10 +22,11 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/crucible": "0.0.1-dev.92",
-    "@decohere/nexus": "0.0.1-dev.92",
+    "@decohere/crucible": "0.0.1-dev.93",
+    "@decohere/nexus": "0.0.1-dev.93",
     "commander": "^13.1.0",
-    "openapi-to-postmanv2": "^5.0.0"
+    "openapi-to-postmanv2": "^5.0.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {},
   "decohere": {

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

@@ -39,6 +39,8 @@ export type ComposeNetwork = {
  * 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;
@@ -47,6 +49,12 @@ export declare class DockerCompose implements KeyedModel {
     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:`. */
@@ -61,4 +69,5 @@ export declare class DockerCompose implements KeyedModel {
     /** Append an env_file path to an existing service. */
     addEnvFile(serviceName: string, filePath: string): this;
     getContent(): string;
+    private mergeIntoExisting;
 }

package/types/src/models/dev-container.model.d.ts

@@ -24,6 +24,12 @@ export declare class DevContainer implements KeyedModel {
     private _initializeCommand?;
     private _remoteUser;
     private _useCompose;
+    private _existing;
+    /**
+     * Load an existing devcontainer.json so `decohere add api` can merge into it.
+     * Only extensions, forwarded ports and port attributes are merged; everything else is kept.
+     */
+    static fromFile(absolutePath: string): DevContainer;
     constructor();
     /** In-container path Cursor/VS Code opens (Agents window uses the basename). */
     setWorkspaceFolder(folder: string): this;
@@ -38,4 +44,6 @@ export declare class DevContainer implements KeyedModel {
     setRemoteUser(user: string): this;
     useCompose(): this;
     files(): SourceFile[];
+    private mergeIntoExisting;
+    private build;
 }

package/types/src/models/docker-image.model.d.ts

@@ -59,7 +59,13 @@ export declare class DockerfileModel implements KeyedModel {
     private readonly _layerWriters;
     private _fromImage;
     private _layerCounter;
+    private _existing;
     constructor(baseImage: string);
+    /**
+     * Load an existing Dockerfile so `decohere add api` can append feature layers.
+     * The new steps are appended as one block, unless the file already contains it.
+     */
+    static fromFile(absolutePath: string, filePath: string): DockerfileModel;
     from(baseImage: string): this;
     addLayer(layer: LayerWriter | string, order?: 5000): this;
     addStep(step: DockerStep): this;

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

@@ -2,6 +2,8 @@ import type { KeyedModel, SourceFile } from "./source-file.js";
 export declare class Gitignore implements KeyedModel {
     readonly key: string;
     private ignoreList;
+    /** Load an existing .gitignore so `decohere add api` appends instead of replacing. */
+    static fromFile(absolutePath: string): Gitignore;
     add(...patterns: string[]): this;
     files(): SourceFile[];
 }