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

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

@@ -0,0 +1,162 @@
+import { readFileSync } from "node:fs";
+import { WELL_KNOWN_FILES } from "./const.js";
+export class DevContainer {
+    key = WELL_KNOWN_FILES.DEVCONTAINER_JSON;
+    _extensions = [];
+    _ports = [];
+    _portAttributes = new Map();
+    _mounts;
+    _workspaceFolder = "/workspace";
+    _postCreateCommand;
+    _updateContentCommand;
+    _postStartCommand;
+    _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)
+        ];
+    }
+    /** In-container path Cursor/VS Code opens (Agents window uses the basename). */ setWorkspaceFolder(folder) {
+        this._workspaceFolder = folder;
+        this._mounts = [
+            this.bindMount(folder)
+        ];
+        return this;
+    }
+    bindMount(target) {
+        return `source=..,target=${target},type=bind,consistency=cached`;
+    }
+    addExtension(...ids) {
+        this._extensions.push(...ids);
+        return this;
+    }
+    forwardPort(...ports) {
+        this._ports.push(...ports);
+        return this;
+    }
+    setPortAttributes(port, attrs) {
+        this._portAttributes.set(port, attrs);
+        return this;
+    }
+    setPostCreateCommand(cmd) {
+        this._postCreateCommand = cmd;
+        return this;
+    }
+    setUpdateContentCommand(cmd) {
+        this._updateContentCommand = cmd;
+        return this;
+    }
+    setPostStartCommand(cmd) {
+        this._postStartCommand = cmd;
+        return this;
+    }
+    setInitializeCommand(cmd) {
+        this._initializeCommand = cmd;
+        return this;
+    }
+    setRemoteUser(user) {
+        this._remoteUser = user;
+        return this;
+    }
+    useCompose() {
+        this._useCompose = true;
+        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";
+            config.service = "devcontainer";
+            config.workspaceFolder = this._workspaceFolder;
+        }
+        if (this._initializeCommand) {
+            config.initializeCommand = this._initializeCommand;
+        }
+        if (this._mounts) {
+            config.mounts = this._mounts;
+        }
+        if (this._extensions.length > 0) {
+            config.customizations = {
+                vscode: {
+                    extensions: this._extensions
+                }
+            };
+        }
+        if (this._ports.length > 0) {
+            config.forwardPorts = this._ports;
+        }
+        if (this._portAttributes.size > 0) {
+            const portsAttributes = {};
+            for (const [port, attrs] of this._portAttributes){
+                portsAttributes[String(port)] = attrs;
+            }
+            config.portsAttributes = portsAttributes;
+        }
+        if (this._postCreateCommand) {
+            config.postCreateCommand = this._postCreateCommand;
+        }
+        if (this._updateContentCommand) {
+            config.updateContentCommand = this._updateContentCommand;
+        }
+        if (this._postStartCommand) {
+            config.postStartCommand = this._postStartCommand;
+        }
+        if (this._remoteUser) {
+            config.remoteUser = this._remoteUser;
+        }
+        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

@@ -0,0 +1,235 @@
+import { readFileSync } from "node:fs";
+import { WELL_KNOWN_FILES } from "./const.js";
+export class DockerStep {
+    key;
+    content;
+    order;
+    constructor(key, content, order = 0){
+        this.key = key;
+        this.content = content;
+        this.order = order;
+    }
+    static run(key, command, order = 0) {
+        return new DockerStep(key, `RUN ${command}`, order);
+    }
+    static raw(key, content, order = 0) {
+        return new DockerStep(key, content, order);
+    }
+    static entrypoint(key, value, order = 0) {
+        const content = typeof value === "string" ? `ENTRYPOINT ${value}` : `ENTRYPOINT ${JSON.stringify(value)}`;
+        return new DockerStep(key, content, order);
+    }
+}
+const StepOrder = {
+    base: 1_000,
+    features: 5_000,
+    user: 9_000,
+    entrypoint: 10_000
+};
+const VSCODE_BOOTLOADER_FIX_BASH_SNIPPET = `if [[ -n "\${NODE_OPTIONS:-}" && "\${NODE_OPTIONS}" == *"bootloader.js"* ]]; then
+    _bootloader_path="$(printf '%s\\n' "$NODE_OPTIONS" | sed -n 's/.*--require[= ]\\([^[:space:]]*bootloader\\.js\\).*/\\1/p')"
+    if [[ -n "\${_bootloader_path}" && ! -f "\${_bootloader_path}" ]]; then
+        _stable_bootloader="$(find /vscode/vscode-server /home/node/.vscode-server/extensions -name "bootloader.js" -path "*/ms-vscode.js-debug/*" 2>/dev/null | head -1)"
+        if [[ -n "\${_stable_bootloader}" ]]; then
+            NODE_OPTIONS="\${NODE_OPTIONS//\${_bootloader_path}/\${_stable_bootloader}}"
+        else
+            NODE_OPTIONS="$(printf '%s\\n' "$NODE_OPTIONS" | sed -E 's#(^| )--require(=| )[[:graph:]]*bootloader\\.js( |$)# #g; s#  +# #g; s#^ ##; s# $##')"
+            unset VSCODE_INSPECTOR_OPTIONS
+        fi
+        export NODE_OPTIONS
+        if [[ -z "$NODE_OPTIONS" ]]; then
+            unset NODE_OPTIONS
+        fi
+    fi
+    unset _bootloader_path _stable_bootloader
+fi`;
+/** Named volume + paths for interactive bash history in app Dev Containers. */ export const commandHistory = {
+    volumeName: "bashhistory",
+    dir: "/commandhistory",
+    fileName: ".bash_history",
+    histFile: "/commandhistory/.bash_history"
+};
+export function withCommandHistory(options) {
+    const historyDir = options?.historyDir ?? commandHistory.dir;
+    const historyFileName = options?.historyFileName ?? commandHistory.fileName;
+    const username = options?.username ?? "node";
+    const order = options?.order ?? StepOrder.base;
+    const historyFile = `${historyDir}/${historyFileName}`;
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.run("history-dir", `mkdir -p ${historyDir} && touch ${historyFile} && chown -R ${username} ${historyDir}`, order)).addStep(DockerStep.raw("history-env", `ENV HISTFILE=${historyFile}`, order + 1)).addStep(DockerStep.raw("history-bashrc", `RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=${historyFile}" \\\n\t&& echo "$SNIPPET" >> "/home/${username}/.bashrc"`, order + 2));
+    };
+}
+export function withNodeUser(options) {
+    const username = options?.username ?? "node";
+    const includeUserInstruction = options?.includeUserInstruction ?? true;
+    const order = options?.order ?? StepOrder.features;
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.raw("arg-username", `ARG USERNAME=${username}`, order));
+        if (includeUserInstruction) {
+            dockerfile.addStep(DockerStep.raw("user", "USER ${USERNAME}", StepOrder.user));
+        }
+    };
+}
+export function withPnpm(options) {
+    const version = options?.version ?? "10";
+    const usernameExpr = options?.usernameExpr ?? "${USERNAME}";
+    const order = options?.order ?? StepOrder.features + 100;
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.run("pnpm-install", `npm install --global npm@latest && npm add --global pnpm@${version}`, order)).addStep(DockerStep.run("pnpm-config", `mkdir -p /home/${usernameExpr}/.config/pnpm /home/${usernameExpr}/.pnpm-store && chown -R ${usernameExpr}:${usernameExpr} /home/${usernameExpr}/.config /home/${usernameExpr}/.pnpm-store && printf "store-dir=/home/${usernameExpr}/.pnpm-store\\n" > /home/${usernameExpr}/.config/pnpm/rc`, order + 1));
+    };
+}
+/**
+ * Client-only (`psql`, etc.). Escalates to root so this also works when layered on
+ * a published base image that already switched to `USER node`.
+ */ export function withPostgresqlClient(options) {
+    const order = options?.order ?? StepOrder.features + 150;
+    const username = options?.username ?? "node";
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.raw("postgresql-client-root", "USER root", order)).addStep(DockerStep.run("postgresql-client", "apt-get update && apt-get install -y --no-install-recommends postgresql-client && rm -rf /var/lib/apt/lists/*", order + 1)).addStep(DockerStep.raw("postgresql-client-user", `USER ${username}`, order + 2));
+    };
+}
+/** GitHub CLI — install before USER switches away from root. */ export function withGithubCli(options) {
+    const order = options?.order ?? StepOrder.features + 140;
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.run("github-cli", "apt-get update && apt-get install -y --no-install-recommends gh && rm -rf /var/lib/apt/lists/*", order));
+    };
+}
+export function withWorkspaceNodeModulesOwnership(options) {
+    const workspaceDir = options?.workspaceDir ?? "/workspace";
+    const usernameExpr = options?.usernameExpr ?? "${USERNAME}";
+    const order = options?.order ?? StepOrder.features + 200;
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.raw("workspace-node-modules", `RUN mkdir -p ${workspaceDir}/node_modules && chown ${usernameExpr}:${usernameExpr} ${workspaceDir}/node_modules`, order));
+    };
+}
+export function withVsCodeJsDebugBootloaderFix(options) {
+    const bashrcPath = options?.bashrcPath ?? "/home/${USERNAME}/.bashrc";
+    const order = options?.order ?? StepOrder.features + 300;
+    return (dockerfile)=>{
+        dockerfile.addStep(DockerStep.raw("vscode-bootloader-fix", [
+            "# VS Code / Cursor js-debug Auto Attach injects --require …/bootloader.js into",
+            "# NODE_OPTIONS. On a fresh Dev Container that path often does not exist yet",
+            "# (workspaceStorage file is only created after toggling Auto Attach), which crashes",
+            "# every Node command. If the injected path is missing, prefer the stable",
+            "# bootloader from the server extension install; otherwise strip the bad require.",
+            `RUN cat <<'EOF' >> "${bashrcPath}"`,
+            VSCODE_BOOTLOADER_FIX_BASH_SNIPPET,
+            "EOF"
+        ].join("\n"), order));
+    };
+}
+export class DockerfileModel {
+    key = WELL_KNOWN_FILES.DOCKERFILE;
+    _steps = new Map();
+    _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;
+    }
+    addLayer(layer, order = StepOrder.features) {
+        if (typeof layer === "string") {
+            const idx = ++this._layerCounter;
+            const key = `layer-run-${idx}`;
+            this._layerWriters.push((dockerfile)=>{
+                dockerfile.addStep(DockerStep.run(key, layer, order + idx));
+            });
+            return this;
+        }
+        this._layerWriters.push(layer);
+        return this;
+    }
+    addStep(step) {
+        this._steps.set(step.key, step);
+        return this;
+    }
+    removeStep(key) {
+        this._steps.delete(key);
+        return this;
+    }
+    entrypoint(value, order = StepOrder.entrypoint) {
+        this.addStep(DockerStep.entrypoint("entrypoint", value, order));
+        return this;
+    }
+    addRunStep(cmd) {
+        return this.addLayer(cmd);
+    }
+    build() {
+        for (const layerWriter of this._layerWriters){
+            layerWriter(this);
+        }
+        const sortedSteps = [
+            ...this._steps.values()
+        ].sort((left, right)=>{
+            if (left.order !== right.order) {
+                return left.order - right.order;
+            }
+            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);
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    registerBaseLayers() {
+    // Generic base model intentionally has no default layers.
+    }
+    files() {
+        return [
+            {
+                filePath: this._existing?.filePath ?? "./Dockerfile",
+                content: this.build()
+            }
+        ];
+    }
+}
+/**
+ * Shared layers for the published `ghcr.io/typesmiths/decohere/devcontainer` image.
+ * Checked in at `projects/devcontainer/Dockerfile` — keep in sync via the unit test.
+ */ export class AppDevContainerBaseImage extends DockerfileModel {
+    registerBaseLayers() {
+        super.registerBaseLayers();
+        this.addLayer(withCommandHistory()).addLayer(withNodeUser()).addLayer(withPnpm()).addLayer(withGithubCli()).addLayer(withWorkspaceNodeModulesOwnership()).addLayer(withVsCodeJsDebugBootloaderFix());
+    }
+}
+/** Generic Dev Container image helpers (history + bootloader) without webapi defaults. */ export class DevContainerImageModel extends DockerfileModel {
+    registerBaseLayers() {
+        super.registerBaseLayers();
+        this.addLayer(withCommandHistory()).addLayer(withVsCodeJsDebugBootloaderFix());
+    }
+    files() {
+        return [
+            {
+                filePath: ".devcontainer/Dockerfile",
+                content: this.build()
+            }
+        ];
+    }
+}

package/es6/src/models/env-file.model.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { WELL_KNOWN_FILES } from "./const.js";
+/**
+ * Accumulates key=value pairs and renders them as a `.env` file.
+ *
+ * Register once in the workspace; features call `addEntry` during their
+ * scaffold phase to contribute environment variables. The final file is
+ * written at render time when `workspace.scaffold()` is called.
+ */ export class EnvFile {
+    key = WELL_KNOWN_FILES.ENV_FILE;
+    _entries = new Map();
+    addEntry(key, value) {
+        this._entries.set(key, value);
+        return this;
+    }
+    hasEntry(key) {
+        return this._entries.has(key);
+    }
+    static fromFile(absolutePath) {
+        const env = new EnvFile();
+        const raw = readFileSync(absolutePath, "utf8");
+        for (const line of raw.split("\n")){
+            const trimmed = line.trim();
+            if (trimmed === "" || trimmed.startsWith("#")) continue;
+            const eq = line.indexOf("=");
+            if (eq <= 0) continue;
+            env.addEntry(line.slice(0, eq).trim(), line.slice(eq + 1));
+        }
+        return env;
+    }
+    files() {
+        if (this._entries.size === 0) return [];
+        const body = [
+            ...this._entries.entries()
+        ].map(([k, v])=>`${k}=${v}`).join("\n");
+        const content = `${body}\n`;
+        return [
+            {
+                filePath: ".env",
+                content
+            }
+        ];
+    }
+}

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

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { WELL_KNOWN_FILES } from "./const.js";
+export class Gitignore {
+    key = WELL_KNOWN_FILES.GITIGNORE;
+    ignoreList = [
+        "node_modules",
+        "dist",
+        ".package",
+        ".pnpm-store",
+        ".env",
+        ".devcontainer/gh.env",
+        ".cursor/codebase-rag.env",
+        ".cursor/mcp.json",
+        ".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)) {
+                this.ignoreList.push(pattern);
+            }
+        }
+        return this;
+    }
+    files() {
+        return [
+            {
+                filePath: ".gitignore",
+                content: `${this.ignoreList.join("\n")}\n`
+            }
+        ];
+    }
+}

package/es6/src/models/launch-json.model.js

@@ -0,0 +1,60 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+export class LaunchJson {
+    apiNames;
+    key = WELL_KNOWN_FILES.LAUNCH_JSON;
+    constructor(apiNames = [
+        "api"
+    ]){
+        this.apiNames = apiNames;
+    }
+    files() {
+        const configurations = [
+            {
+                name: "Build",
+                type: "node",
+                request: "launch",
+                runtimeExecutable: "pnpm",
+                runtimeArgs: [
+                    "build"
+                ],
+                console: "integratedTerminal",
+                cwd: "${workspaceFolder}"
+            }
+        ];
+        const first = this.apiNames[0] ?? "api";
+        const defaultDevArgs = first === "api" && this.apiNames.length === 1 ? [
+            "dev"
+        ] : [
+            "run",
+            `dev:${first}`
+        ];
+        configurations.push(serveConfig("Serve / Dev", defaultDevArgs));
+        for (const apiName of this.apiNames){
+            if (apiName === first && this.apiNames.length === 1 && apiName === "api") continue;
+            configurations.push(serveConfig(`Serve / Dev (${apiName})`, [
+                "run",
+                `dev:${apiName}`
+            ]));
+        }
+        return [
+            {
+                filePath: ".vscode/launch.json",
+                content: JSON.stringify({
+                    version: "0.2.0",
+                    configurations
+                }, null, 2)
+            }
+        ];
+    }
+}
+function serveConfig(name, runtimeArgs) {
+    return {
+        name,
+        type: "node",
+        request: "launch",
+        runtimeExecutable: "pnpm",
+        runtimeArgs,
+        console: "integratedTerminal",
+        cwd: "${workspaceFolder}"
+    };
+}

package/es6/src/models/package-json.model.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { CREATE_VERSION } from "../version.js";
+import { DEFAULT_WEBAPI_NAME, webapiPackageName, webapiPort, webapiReleaseEntry } from "../webapi/const.js";
+import { WELL_KNOWN_FILES } from "./const.js";
+/**
+ * Builder for the root `package.json`.
+ *
+ * Starts with the core API dependencies. Features call `addDependency` /
+ * `addDevDependency` during their scaffold phase to inject their own deps
+ * before `files()` is called at render time.
+ */ export class PackageJson {
+    name;
+    key = WELL_KNOWN_FILES.PACKAGE_JSON;
+    _dependencies;
+    _devDependencies;
+    _scripts;
+    _version = "0.0.1";
+    _type = "module";
+    _rest = {};
+    constructor(name, options){
+        this.name = name;
+        const apiNames = options?.apiNames ?? [
+            DEFAULT_WEBAPI_NAME
+        ];
+        const first = apiNames[0] ?? DEFAULT_WEBAPI_NAME;
+        const startEntry = options?.startEntry ?? webapiReleaseEntry(first);
+        const workspaceName = options?.workspaceName ?? stripApiSuffix(name);
+        const namedOrMany = apiNames.length > 1 || first !== DEFAULT_WEBAPI_NAME;
+        this._scripts = {
+            build: "forge build --configuration release",
+            "build:watch": "forge build --watch",
+            // Release build, then `.package/` in every API (what its Dockerfile copies).
+            package: "pnpm run build && forge package",
+            start: `node ${startEntry}`,
+            dev: namedOrMany ? fluxDevScript(workspaceName, first, webapiPort(0)) : "flux serve --env-file-if-exists .env",
+            "lint:check": "biome check .",
+            typecheck: "forge typecheck",
+            test: "vitest run --passWithNoTests"
+        };
+        for (const [index, apiName] of apiNames.entries()){
+            this._scripts[`start:${apiName}`] = `node ${webapiReleaseEntry(apiName)}`;
+            this._scripts[`package:${apiName}`] = packageScript(workspaceName, apiName);
+            this._scripts[`dev:${apiName}`] = fluxDevScript(workspaceName, apiName, webapiPort(index));
+        }
+        this._dependencies = {
+            "@decohere/http": CREATE_VERSION,
+            "@decohere/crucible": CREATE_VERSION,
+            "@decohere/core": CREATE_VERSION,
+            "@decohere/config": CREATE_VERSION,
+            "@decohere/scribe": CREATE_VERSION,
+            "@decohere/scribe-pino": CREATE_VERSION,
+            "pino-pretty": "^13.0.0",
+            "pino-roll": "^4.0.0"
+        };
+        this._devDependencies = {
+            "@decohere/forge": CREATE_VERSION,
+            "@decohere/cli": CREATE_VERSION,
+            "@types/node": "^24.0.0",
+            typescript: "^6.0.3",
+            "@biomejs/biome": "^2.0.0",
+            vitest: "^3.2.4"
+        };
+    }
+    /** Load an existing root package.json so `webapi add` can merge scripts/deps. */ static fromFile(filePath) {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const pkg = new PackageJson(typeof raw.name === "string" ? raw.name : "app", {
+            apiNames: []
+        });
+        pkg._version = typeof raw.version === "string" ? raw.version : "0.0.1";
+        pkg._type = typeof raw.type === "string" ? raw.type : "module";
+        pkg._scripts = {
+            ...asStringMap(raw.scripts)
+        };
+        pkg._dependencies = {
+            ...asStringMap(raw.dependencies)
+        };
+        pkg._devDependencies = {
+            ...asStringMap(raw.devDependencies)
+        };
+        const reserved = new Set([
+            "name",
+            "version",
+            "type",
+            "scripts",
+            "dependencies",
+            "devDependencies"
+        ]);
+        pkg._rest = Object.fromEntries(Object.entries(raw).filter(([key])=>!reserved.has(key)));
+        return pkg;
+    }
+    addDependency(name, version) {
+        this._dependencies[name] = version;
+        return this;
+    }
+    addDevDependency(name, version) {
+        this._devDependencies[name] = version;
+        return this;
+    }
+    addScript(name, command) {
+        this._scripts[name] = command;
+        return this;
+    }
+    hasScript(name) {
+        return typeof this._scripts[name] === "string";
+    }
+    files() {
+        return [
+            {
+                filePath: "package.json",
+                content: JSON.stringify({
+                    name: this.name,
+                    version: this._version,
+                    type: this._type,
+                    ...this._rest,
+                    scripts: this._scripts,
+                    dependencies: sortStringMap(this._dependencies),
+                    devDependencies: sortStringMap(this._devDependencies)
+                }, null, 2)
+            }
+        ];
+    }
+}
+function stripApiSuffix(name) {
+    return name.endsWith(".api") ? name.slice(0, -".api".length) : name;
+}
+function asStringMap(value) {
+    if (value == null || typeof value !== "object") return {};
+    const result = {};
+    for (const [key, entry] of Object.entries(value)){
+        if (typeof entry === "string") result[key] = entry;
+    }
+    return result;
+}
+/** Stable A→Z key order for package.json dependency maps. */ export function sortStringMap(map) {
+    return Object.fromEntries(Object.entries(map).sort(([left], [right])=>left.localeCompare(right, "en")));
+}
+export function packageScript(workspaceName, apiName) {
+    return `pnpm run build && forge package ${webapiPackageName(workspaceName, apiName)}`;
+}
+function fluxDevScript(workspaceName, apiName, port) {
+    return `PORT=${port} flux serve --env-file-if-exists .env --project ${webapiPackageName(workspaceName, apiName)}`;
+}