groundwork-method 0.0.1 → 0.10.0

package/dist/src/generators/shared/capabilities.js

@@ -0,0 +1,279 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCapability = loadCapability;
+exports.loadFootprint = loadFootprint;
+exports.applyCapability = applyCapability;
+const devkit_1 = require("@nx/devkit");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const scaffold_helpers_1 = require("./scaffold-helpers");
+/** Repo-root-relative registry dir. Compiled location:
+ *  dist/src/generators/shared/capabilities.js → 4 up = package root. */
+function capabilitiesRoot() {
+    return path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'capabilities');
+}
+function loadCapability(capability) {
+    const file = path.join(capabilitiesRoot(), capability, 'capability.json');
+    if (!fs.existsSync(file)) {
+        throw new Error(`Unknown capability "${capability}" (no ${file}).`);
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+function loadFootprint(capability, provider) {
+    const file = path.join(capabilitiesRoot(), capability, 'providers', provider, 'footprint.json');
+    if (!fs.existsSync(file)) {
+        throw new Error(`Unknown provider "${provider}" for capability "${capability}" (no ${file}).`);
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+/** Add dependency lines to the [project].dependencies array of a pyproject.toml,
+ *  skipping any whose package name is already declared. Idempotent. */
+function injectPyprojectDeps(tree, pyprojectPath, deps) {
+    if (!deps.length || !tree.exists(pyprojectPath))
+        return;
+    let content = tree.read(pyprojectPath, 'utf-8') || '';
+    // Target the [project].dependencies array — the first `dependencies = [` in the
+    // file (optional-dependencies uses `dev = [`, so this match is unambiguous).
+    const open = content.indexOf('dependencies = [');
+    if (open === -1)
+        return;
+    // Scan for the array's matching `]`, tracking bracket depth — a naive
+    // indexOf(']') would land inside a spec like "uvicorn[standard]>=0.29.0".
+    const arrayStart = content.indexOf('[', open);
+    let depth = 0;
+    let close = -1;
+    for (let i = arrayStart; i < content.length; i++) {
+        if (content[i] === '[')
+            depth++;
+        else if (content[i] === ']') {
+            depth--;
+            if (depth === 0) {
+                close = i;
+                break;
+            }
+        }
+    }
+    if (close === -1)
+        return;
+    const block = content.slice(open, close);
+    const pkgName = (spec) => spec.split(/[<>=!~ ]/)[0].trim().toLowerCase();
+    const toAdd = deps.filter((d) => !block.toLowerCase().includes(pkgName(d)));
+    if (!toAdd.length)
+        return;
+    const insertion = toAdd.map((d) => `    "${d}",\n`).join('');
+    content = content.slice(0, close) + insertion + content.slice(close);
+    tree.write(pyprojectPath, content);
+}
+/** Add module requires to the first `require ( ... )` block of a go.mod,
+ *  skipping any whose module path is already present. Idempotent. */
+function injectGoModRequires(tree, goModPath, deps) {
+    if (!deps.length || !tree.exists(goModPath))
+        return;
+    let content = tree.read(goModPath, 'utf-8') || '';
+    const open = content.indexOf('require (');
+    if (open === -1)
+        return;
+    const close = content.indexOf(')', open);
+    if (close === -1)
+        return;
+    const block = content.slice(open, close);
+    const modPath = (spec) => spec.split(/\s+/)[0].trim();
+    const toAdd = deps.filter((d) => !block.includes(modPath(d)));
+    if (!toAdd.length)
+        return;
+    const insertion = toAdd.map((d) => `\t${d}\n`).join('');
+    content = content.slice(0, close) + insertion + content.slice(close);
+    tree.write(goModPath, content);
+}
+/** The module/import path of a Go service, read from go.mod's `module` line. */
+function readGoModule(tree, serviceRoot) {
+    const goMod = `${serviceRoot}/go.mod`;
+    if (!tree.exists(goMod))
+        return '';
+    const m = (tree.read(goMod, 'utf-8') || '').match(/^module\s+(\S+)/m);
+    return m ? m[1] : '';
+}
+/**
+ * The importable package name of a Python service (src-layout: `src/<pkg>`).
+ * Read from pyproject.toml's hatch `packages = ["src/<pkg>"]` so the standalone
+ * add-capability generator learns it from the service on disk — no new option.
+ * Falls back to the lone non-dunder directory under `src/` when the marker is
+ * absent (e.g. a hand-rolled service), and to `''` when undiscoverable.
+ */
+function readPythonPackage(tree, serviceRoot) {
+    const py = `${serviceRoot}/pyproject.toml`;
+    if (tree.exists(py)) {
+        const m = (tree.read(py, 'utf-8') || '').match(/packages\s*=\s*\[\s*["']src\/([A-Za-z0-9_]+)["']/);
+        if (m)
+            return m[1];
+    }
+    const srcDir = `${serviceRoot}/src`;
+    if (tree.exists(srcDir)) {
+        const dirs = (tree.children(srcDir) ?? []).filter((c) => !c.startsWith('__') && tree.children(`${srcDir}/${c}`).length > 0);
+        if (dirs.length === 1)
+            return dirs[0];
+    }
+    return '';
+}
+/** Append env vars (by name, idempotent) to a service's env-example file. */
+function appendEnvExample(tree, envPath, capability, env) {
+    if (!env.length)
+        return;
+    let content = tree.exists(envPath) ? tree.read(envPath, 'utf-8') || '' : '';
+    const missing = env.filter((v) => !new RegExp(`^${v.name}=`, 'm').test(content));
+    if (!missing.length)
+        return;
+    const lines = [`# ${capability} capability`, ...missing.map((v) => `${v.name}=${v.default ?? ''}`)];
+    content = content.replace(/\s*$/, '') + '\n' + lines.join('\n') + '\n';
+    tree.write(envPath, content);
+}
+/**
+ * Inject a provider's container into the workspace docker-compose. The compose
+ * file is at the workspace root (not the service root) and is shared by the whole
+ * stack, exactly like the db/jaeger/redis on-demand injectors — a compose-service
+ * footprint is the capability-driven generalisation of that pattern. Idempotent
+ * by service name. A no-op with a warning when no compose file exists yet
+ * (workspace-dev-cli writes the network-only base before any service generator
+ * runs, so this only misses for a service generated into a bare directory).
+ */
+function injectComposeService(tree, svc) {
+    const COMPOSE = 'docker-compose.yml';
+    if (!tree.exists(COMPOSE)) {
+        console.warn(`applyCapability: ${COMPOSE} not found; skipping compose service "${svc.name}". Run the workspace-dev-cli generator first.`);
+        return;
+    }
+    // require('yaml') resolves at runtime (it is a transitive dep of @nx/devkit and
+    // is what the service generators already use to edit this same file).
+    const yaml = require('yaml');
+    const doc = yaml.parseDocument(tree.read(COMPOSE, 'utf-8') || '');
+    let services = doc.get('services');
+    if (!services) {
+        // createNode so the result is a YAMLMap with .has/.set — a plain {} is not.
+        doc.set('services', doc.createNode({}));
+        services = doc.get('services');
+    }
+    if (!services.has(svc.name)) {
+        services.set(svc.name, doc.createNode(svc.definition));
+    }
+    if (svc.volumes && svc.volumes.length) {
+        let volumes = doc.get('volumes');
+        if (!volumes) {
+            doc.set('volumes', doc.createNode({}));
+            volumes = doc.get('volumes');
+        }
+        for (const v of svc.volumes) {
+            if (!volumes.has(v))
+                volumes.set(v, null);
+        }
+    }
+    tree.write(COMPOSE, doc.toString());
+}
+/**
+ * Materialize a capability+provider into a service: the port, the chosen
+ * adapter (or the `none` stub), the contract test, the provider's stack
+ * dependencies, and its env footprint — plus its operational footprint. An
+ * `env`/`none` footprint is service-local; a `compose-service` footprint injects
+ * the container into the workspace docker-compose and a `runner` footprint
+ * registers a native process with `./dev` (both no-op gracefully when the
+ * workspace file is absent, reported via `materialized`).
+ *
+ * Idempotent: capability-owned files are overwritten with identical content on
+ * re-run; deps and env are added only if absent.
+ */
+function applyCapability(tree, opts) {
+    const { capability, provider, stack, serviceRoot } = opts;
+    const cap = loadCapability(capability);
+    const stackSpec = cap.stacks[stack];
+    if (!stackSpec) {
+        throw new Error(`Capability "${capability}" has no support for stack "${stack}" yet (stacks: ${Object.keys(cap.stacks).join(', ')}).`);
+    }
+    if (!cap.providers.includes(provider)) {
+        throw new Error(`Unknown provider "${provider}" for capability "${capability}" (providers: ${cap.providers.join(', ')}).`);
+    }
+    const footprint = loadFootprint(capability, provider);
+    const root = capabilitiesRoot();
+    // Go templates import the service's module path; resolve it from go.mod.
+    const moduleName = stackSpec.module ? readGoModule(tree, serviceRoot) : '';
+    // Python templates land in the src-layout package `src/<pkg>` and import from
+    // it; resolve the package from the service's pyproject. `__packageName__` in a
+    // capability path (template dir or capability.json) is substituted with it.
+    const packageName = stack === 'python' ? readPythonPackage(tree, serviceRoot) : '';
+    const resolvePath = (p) => p.replace(/__packageName__/g, packageName);
+    const subs = { provider, capability, stack, moduleName, packageName, tmpl: '' };
+    // Port + contract test (capability-owned, provider-agnostic except the test's
+    // `none` branch). generateFiles renders the templated subtree into serviceRoot.
+    (0, devkit_1.generateFiles)(tree, path.join(root, capability, 'stacks', stack), serviceRoot, subs);
+    // Adapter (provider-owned).
+    (0, devkit_1.generateFiles)(tree, path.join(root, capability, 'providers', provider, 'stacks', stack), serviceRoot, subs);
+    // Footprint: deps + env are service-local and handled here. compose/runner are
+    // workspace-level and left to the caller via the returned footprint kind.
+    if (stack === 'python') {
+        injectPyprojectDeps(tree, `${serviceRoot}/pyproject.toml`, footprint.stacks?.python?.dependencies ?? []);
+    }
+    else if (stack === 'go') {
+        injectGoModRequires(tree, `${serviceRoot}/go.mod`, footprint.stacks?.go?.dependencies ?? []);
+    }
+    appendEnvExample(tree, `${serviceRoot}/${stackSpec.envFile || '.env.example'}`, capability, footprint.env ?? []);
+    // Compose-service / runner footprints are workspace-level, not service-level:
+    // they materialise into the shared docker-compose / dev.config.json. This is
+    // the capability-driven form of WS-A's on-demand infra — infrastructure is a
+    // consequence of a provider choice, not a default. Both injectors no-op (with a
+    // warning) when their workspace file is absent, so `materialized` reports
+    // whether the footprint was actually wired or left for the caller to finish.
+    let materialized = footprint.kind === 'env' || footprint.kind === 'none';
+    if (footprint.kind === 'compose-service' && footprint.composeService) {
+        injectComposeService(tree, footprint.composeService);
+        materialized = tree.exists('docker-compose.yml');
+    }
+    else if (footprint.kind === 'runner' && footprint.runner) {
+        (0, scaffold_helpers_1.registerRunner)(tree, footprint.runner);
+        materialized = tree.exists('.dev/dev.config.json');
+    }
+    return {
+        capability,
+        provider,
+        stack,
+        footprint: footprint.kind,
+        wiring: stackSpec.wiring,
+        materialized,
+        files: {
+            port: `${serviceRoot}/${resolvePath(stackSpec.port)}`,
+            adapter: `${serviceRoot}/${resolvePath(stackSpec.adapter)}`,
+            contractTest: `${serviceRoot}/${resolvePath(stackSpec.contractTest)}`,
+        },
+    };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/src/generators/shared/capabilities.js.map

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

package/dist/src/generators/shared/provenance.d.ts

@@ -0,0 +1,2 @@
+import { Tree } from '@nx/devkit';
+export declare function recordGeneratorProvenance(tree: Tree, generator: string, options: Record<string, unknown>): void;

package/dist/src/generators/shared/provenance.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordGeneratorProvenance = recordGeneratorProvenance;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// Generator provenance (upgrade-path plan A2): every generator records what it
+// produced — name, package version, resolved options, file hashes — into the
+// install manifest. The upgrade path reads this to regenerate with the recorded
+// options and reconcile the diff when a generator improves after deploy.
+//
+// Call AFTER formatFiles, as the generator's last tree operation, so the recorded
+// hashes match what lands on disk.
+const MANIFEST_PATH = '.groundwork/config/manifest.json';
+function packageVersion() {
+    // Compiled location: <pkg>/dist/src/generators/shared/provenance.js → 4 up.
+    try {
+        return JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', '..', 'package.json'), 'utf-8')).version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function recordGeneratorProvenance(tree, generator, options) {
+    const files = {};
+    for (const change of tree.listChanges()) {
+        if (change.type === 'DELETE' || change.path === MANIFEST_PATH || !change.content)
+            continue;
+        files[change.path] = crypto.createHash('sha256').update(change.content).digest('hex');
+    }
+    let manifest = { manifest_version: 1, files: {}, generated: {} };
+    if (tree.exists(MANIFEST_PATH)) {
+        try {
+            manifest = JSON.parse(tree.read(MANIFEST_PATH, 'utf-8') || '{}');
+        }
+        catch {
+            /* corrupt manifest — rebuild the generated section, keep nothing */
+        }
+    }
+    if (!manifest.generated)
+        manifest.generated = {};
+    // Key by instance: three go-microservices are three artifacts, not one.
+    const name = typeof options.name === 'string' && options.name ? `:${options.name}` : '';
+    manifest.generated[`${generator}${name}`] = {
+        generator,
+        version: packageVersion(),
+        options,
+        files,
+    };
+    tree.write(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+}
+//# sourceMappingURL=provenance.js.map

package/dist/src/generators/shared/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../../../src/generators/shared/provenance.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,8DAkCC;AA3DD,+CAAiC;AACjC,uCAAyB;AACzB,2CAA6B;AAE7B,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,yEAAyE;AACzE,EAAE;AACF,kFAAkF;AAClF,mCAAmC;AAEnC,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEzD,SAAS,cAAc;IACrB,4EAA4E;IAC5E,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CACf,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CACvF,CAAC,OAAO,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAgB,yBAAyB,CACvC,IAAU,EACV,SAAiB,EACjB,OAAgC;IAEhC,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACxC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,SAAS;QAC3F,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,QAAQ,GAIR,EAAE,gBAAgB,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IACtD,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;IACH,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,SAAS;QAAE,QAAQ,CAAC,SAAS,GAAG,EAAE,CAAC;IAEjD,wEAAwE;IACxE,MAAM,IAAI,GAAG,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,IAAI,EAAE,CAAC,GAAG;QAC1C,SAAS;QACT,OAAO,EAAE,cAAc,EAAE;QACzB,OAAO;QACP,KAAK;KACN,CAAC;IACF,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACtE,CAAC"}

package/dist/src/generators/shared/scaffold-helpers.d.ts

@@ -0,0 +1,72 @@
+import { Tree } from '@nx/devkit';
+/**
+ * Shared helpers used by every service generator (Go, Python, Next.js, ...).
+ *
+ * These were previously copy-pasted into each generator, which meant every
+ * cross-cutting fix had to be applied N times and drifted between languages.
+ * They live here once and are imported by all generators. Anything that is
+ * genuinely language-specific (e.g. the per-service docker-compose entry) stays
+ * in the individual generator.
+ */
+/**
+ * Engineer skills are canon under src/engineer-skills/ and are never installed
+ * at the GroundWork root. When a service is scaffolded they are promoted into
+ * the project's .agents/skills/ so engineers have them immediately available in
+ * their toolchain — this is the only place they become a registered skill.
+ */
+export declare function promoteEngineerSkill(tree: Tree, skillName: string): void;
+/**
+ * Deploy a generator's stack-principle docs into the project's docs/ tree and
+ * register each one in llms.txt.
+ *
+ * - Existing docs on disk are never overwritten (idempotent deploy).
+ * - Every doc that ends up in the tree is registered in llms.txt, whether it
+ *   was just written or already present, so the index stays complete even if
+ *   the files predate llms.txt registration.
+ */
+export declare function deployStackDocs(tree: Tree, docsRoot: string): void;
+/** A native process the generated `./dev` CLI manages directly — a surface app
+ *  (Electron, Flutter, CLI) or a native sidecar. Mirrors the Runner interface in
+ *  the dev CLI bundle (cli-src/src/util/runners.ts); kept in sync by hand. */
+export interface RunnerSpec {
+    name: string;
+    kind?: 'sidecar' | 'surface';
+    cmd: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    health?: unknown;
+    autostart?: boolean;
+}
+/**
+ * Register a native runner in `.dev/dev.config.json` so `./dev`
+ * start/stop/status/logs manage it. Idempotent by `name` (re-running a generator
+ * updates the entry in place rather than duplicating it). A no-op with a warning
+ * when the dev CLI has not been scaffolded yet — workspace-dev-cli runs first in
+ * the scaffold flow, so this only fires for a surface generated standalone.
+ */
+export declare function registerRunner(tree: Tree, runner: RunnerSpec): void;
+/**
+ * The workspace project prefix the dev CLI was generated with, read from
+ * `.dev/dev.config.json`. Used to name the db/jaeger containers consistently
+ * with what `./dev` expects. Falls back to 'workspace' when the config is
+ * absent or unreadable (e.g. a bare workspace before the dev CLI ran).
+ */
+export declare function readProjectPrefix(tree: Tree): string;
+/**
+ * Inject the optional infrastructure a service needs into the shared
+ * docker-compose. Nothing is in the base compose; every backing service is
+ * added here on demand and only once, so a project provisions only the
+ * infrastructure some service actually uses. A workspace with no service that
+ * uses any of these provisions none of them.
+ *
+ * `projectPrefix` names the db container (`<prefix>-db`) so `./dev migrate` can
+ * find it by `docker inspect`; the service is still reachable on the compose
+ * network by its service name `db`.
+ */
+export declare function ensureOptionalInfra(composeDoc: any, servicesMap: any, opts: {
+    usesRedis: boolean;
+    usesPubSub: boolean;
+    usesDb?: boolean;
+    usesTelemetry?: boolean;
+    projectPrefix?: string;
+}): void;