@decohere/scaffold 0.0.1-dev.100

package/es6/src/auth0-configure.command.js

@@ -0,0 +1,14 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { Auth0ConfigureAction } from "./auth0-configure.action.js";
+export class Auth0ConfigureCommand extends DecohereCommand {
+    get actions() {
+        return [
+            Auth0ConfigureAction
+        ];
+    }
+    constructor(name){
+        super(name);
+        this.description("Update Auth0 API permissions and Postman SPA from @Authorize in this workspace");
+        this.option("-d <directory>", "Workspace directory (default: current directory)", ".");
+    }
+}

package/es6/src/auth0-login.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/nexus/cli";
+import { runAuth0Login } from "./webapi/auth0-commands.js";
+export class Auth0LoginAction {
+    async run() {
+        runAuth0Login();
+        return ActionResponse.Success("login");
+    }
+}
+Auth0LoginAction = _ts_decorate([
+    injectable()
+], Auth0LoginAction);

package/es6/src/auth0-login.command.js

@@ -0,0 +1,13 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { Auth0LoginAction } from "./auth0-login.action.js";
+export class Auth0LoginCommand extends DecohereCommand {
+    get actions() {
+        return [
+            Auth0LoginAction
+        ];
+    }
+    constructor(name){
+        super(name);
+        this.description("Authenticate the Auth0 CLI (device URL; tokens persist on the host)");
+    }
+}

package/es6/src/auth0.command.js

@@ -0,0 +1,12 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+export class Auth0Command extends DecohereCommand {
+    constructor(commands, handler){
+        super(Auth0Command);
+        this.description("Log in to Auth0 and update a scaffolded client");
+        this.exitOverride();
+        this.registerSubcommand(commands, handler);
+    }
+    run(_actions, _options) {
+        return this.help();
+    }
+}

package/es6/src/auth0.module.js

@@ -0,0 +1,18 @@
+import { ModuleManifest } from "@decohere/nexus/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 class Auth0Module extends ModuleManifest {
+    id = "auth0";
+    command = Auth0Command;
+    commands = {
+        login: Auth0LoginCommand,
+        configure: Auth0ConfigureCommand
+    };
+    actions = {
+        login: Auth0LoginAction,
+        configure: Auth0ConfigureAction
+    };
+}

package/es6/src/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./program.js";
+void runCli();

package/es6/src/create.command.js

@@ -0,0 +1,12 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+export class CreateCommand extends DecohereCommand {
+    constructor(commands, handler){
+        super(CreateCommand);
+        this.description("Create a new Decohere workspace");
+        this.exitOverride();
+        this.registerSubcommand(commands, handler);
+    }
+    run(_actions, _options) {
+        return this.help();
+    }
+}

package/es6/src/create.module.js

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

package/es6/src/domain/prompt.js

@@ -0,0 +1,41 @@
+import { createInterface } from "node:readline";
+// readline/promises rl.question() has a race condition with piped (non-TTY) stdin
+// in Node ≥ 22: after the first line is read, stdin emits 'end', readline closes,
+// and all subsequent question() calls resolve to "".
+// Fix: use the async-iterator API, which buffers all lines before the close event fires.
+let _rl = null;
+let _lines = null;
+function getLines() {
+    if (_lines == null) {
+        _rl = createInterface({
+            input: process.stdin,
+            terminal: false
+        });
+        _lines = _rl[Symbol.asyncIterator]();
+    }
+    return _lines;
+}
+/** Release stdin so the process can exit after interactive prompts. */ export function closePrompt() {
+    _rl?.close();
+    _rl = null;
+    _lines = null;
+}
+async function readLine(prompt) {
+    process.stdout.write(prompt);
+    const { value, done } = await getLines().next();
+    return done ? "" : value.trim();
+}
+export async function ask(question, fallback = "") {
+    const answer = await readLine(question);
+    return answer || fallback;
+}
+export async function pick(label, items, display) {
+    console.log(label.trimEnd());
+    for (const [i, item] of items.entries()){
+        console.log(`    ${i + 1}. ${display(item)}`);
+    }
+    const answer = await readLine("  > ");
+    const idx = Number.parseInt(answer, 10);
+    if (Number.isNaN(idx) || idx < 1 || idx > items.length) return null;
+    return items[idx - 1];
+}

package/es6/src/index.js

@@ -0,0 +1,9 @@
+export { AddModule } from "./add.module.js";
+export { AddApiAction } from "./add-api.action.js";
+export { Auth0Module } from "./auth0.module.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 { scaffoldApi } from "./webapi/create-api.js";
+export { WebapiAction } from "./webapi.action.js";

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

@@ -0,0 +1,254 @@
+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;
+    _headerComments = [];
+    _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;
+    }
+    /** File-level `#` comments rendered above `name:` / `services:`. */ addHeaderComment(...lines) {
+        this._headerComments.push(...lines);
+        return this;
+    }
+    addService(name, config) {
+        this._services.set(name, config);
+        return this;
+    }
+    files() {
+        return [
+            {
+                filePath: ".devcontainer/docker-compose.yml",
+                content: this.getContent()
+            }
+        ];
+    }
+    addVolume(name) {
+        this._volumes.add(name);
+        return this;
+    }
+    addNetwork(key, network) {
+        this._networks.set(key, network);
+        return this;
+    }
+    /** Append an env_file path to an existing service. */ addEnvFile(serviceName, filePath) {
+        // 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}`);
+        }
+        if (this._headerComments.length > 0) {
+            lines.push("");
+        }
+        if (this._projectName) {
+            lines.push(`name: ${this._projectName}`, "");
+        }
+        lines.push("services:");
+        for (const [name, svc] of this._services){
+            lines.push(`  ${name}:`);
+            if (svc.build) lines.push(`    build: ${svc.build}`);
+            if (svc.image) lines.push(`    image: ${svc.image}`);
+            if (svc.container_name) lines.push(`    container_name: ${svc.container_name}`);
+            if (svc.command) lines.push(`    command: ${svc.command}`);
+            if (svc.user) lines.push(`    user: "${svc.user}"`);
+            if (svc.restart) lines.push(`    restart: ${svc.restart}`);
+            if (svc.profiles && svc.profiles.length > 0) {
+                lines.push("    profiles:");
+                for (const p of svc.profiles)lines.push(`      - ${p}`);
+            }
+            if (svc.env_file && svc.env_file.length > 0) {
+                lines.push("    env_file:");
+                for (const f of svc.env_file)lines.push(`      - ${f}`);
+            }
+            if (svc.environment && Object.keys(svc.environment).length > 0) {
+                lines.push("    environment:");
+                for (const [k, v] of Object.entries(svc.environment)){
+                    lines.push(`      ${k}: ${v}`);
+                }
+            }
+            if (svc.ports && svc.ports.length > 0) {
+                lines.push("    ports:");
+                for (const p of svc.ports)lines.push(`      - "${p}"`);
+            }
+            if (svc.volumes && svc.volumes.length > 0) {
+                lines.push("    volumes:");
+                for (const v of svc.volumes)lines.push(`      - ${v}`);
+            }
+            if (svc.networks && svc.networks.length > 0) {
+                const onlyStrings = svc.networks.every((n)=>typeof n === "string");
+                if (onlyStrings) {
+                    lines.push("    networks:");
+                    for (const n of svc.networks)lines.push(`      - ${n}`);
+                } else {
+                    lines.push("    networks:");
+                    for (const n of svc.networks){
+                        if (typeof n === "string") {
+                            lines.push(`      ${n}:`);
+                        } else {
+                            for (const [netKey, cfg] of Object.entries(n)){
+                                lines.push(`      ${netKey}:`);
+                                if (cfg.aliases && cfg.aliases.length > 0) {
+                                    lines.push("        aliases:");
+                                    for (const a of cfg.aliases)lines.push(`          - ${a}`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            if (svc.depends_on && svc.depends_on.length > 0) {
+                lines.push("    depends_on:");
+                for (const d of svc.depends_on)lines.push(`      - ${d}`);
+            }
+            if (svc.healthcheck) {
+                const hc = svc.healthcheck;
+                lines.push("    healthcheck:");
+                lines.push(`      test: ${JSON.stringify(hc.test)}`);
+                if (hc.interval) lines.push(`      interval: ${hc.interval}`);
+                if (hc.timeout) lines.push(`      timeout: ${hc.timeout}`);
+                if (hc.retries != null) lines.push(`      retries: ${hc.retries}`);
+            }
+        }
+        if (this._networks.size > 0) {
+            lines.push("");
+            lines.push("networks:");
+            for (const [key, net] of this._networks){
+                lines.push(`  ${key}:`);
+                lines.push(`    name: ${net.name}`);
+                if (net.external) lines.push("    external: true");
+            }
+        }
+        if (this._volumes.size > 0) {
+            lines.push("");
+            lines.push("volumes:");
+            for (const v of this._volumes)lines.push(`  ${v}:`);
+        }
+        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/config-yaml.model.js

@@ -0,0 +1,74 @@
+import { readFileSync } from "node:fs";
+/**
+ * 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 class ConfigYaml {
+    key;
+    filePath;
+    _sections = [];
+    constructor(key, filePath, baseContent){
+        this.key = key;
+        this.filePath = filePath;
+        this._sections.push(baseContent);
+    }
+    addSection(yaml) {
+        this._sections.push(yaml);
+        return this;
+    }
+    /** True when a datasource with this `name:` already appears in the file. */ hasDataSource(name) {
+        return this._sections.join("\n").includes(`name: ${name}\n`);
+    }
+    hasDataSources() {
+        return this._sections.join("\n").includes("dataSources:");
+    }
+    /**
+	 * 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) {
+        const current = this._sections.join("\n");
+        this._sections.length = 0;
+        this._sections.push(injectYamlDataSource(current, item));
+        return this;
+    }
+    static fromFile(key, relativePath, absolutePath) {
+        const content = readFileSync(absolutePath, "utf8");
+        return new ConfigYaml(key, relativePath, content);
+    }
+    files() {
+        return [
+            {
+                filePath: this.filePath,
+                content: this._sections.join("\n")
+            }
+        ];
+    }
+}
+/** Insert a YAML list item under `dataSources:`; append a new `database:` block if missing. */ export function injectYamlDataSource(yaml, item) {
+    const block = item.replace(/\n$/, "");
+    if (!yaml.includes("dataSources:")) {
+        const prefix = yaml.trimEnd();
+        const section = `database:\n  dataSources:\n${block}\n`;
+        return prefix.length > 0 ? `${prefix}\n\n${section}` : section;
+    }
+    const lines = yaml.split("\n");
+    const dsIndex = lines.findIndex((line)=>/^\s*dataSources:\s*$/.test(line));
+    if (dsIndex < 0) {
+        return `${yaml.trimEnd()}\n\ndatabase:\n  dataSources:\n${block}\n`;
+    }
+    let insertAt = lines.length;
+    for(let i = dsIndex + 1; i < lines.length; i++){
+        if (/^[A-Za-z]/.test(lines[i] ?? "")) {
+            insertAt = i;
+            break;
+        }
+    }
+    const insertLines = block.split("\n");
+    if (insertAt < lines.length && lines[insertAt - 1] !== "") {
+        insertLines.push("");
+    }
+    lines.splice(insertAt, 0, ...insertLines);
+    return lines.join("\n");
+}

package/es6/src/models/const.js

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

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;
+}