@mesh-tech/mesh-cli 0.1.1 → 0.12.1

package/dist/src/commands/local/mocks.js

@@ -0,0 +1,756 @@
+/**
+ * `mesh dev --externals` (alias `--mock`) — external-service realizations
+ * for a local dev session (MESH-1885, design C4).
+ *
+ * Apps DECLARE how each external dependency is realized locally in the root
+ * package.json under `mesh.externals` (legacy key `mesh.mocks` still read).
+ * Every declaration runs in exactly one of three MODES:
+ *
+ *   mock   — the service is MIMICKED: no real instance exists locally or
+ *            remotely. Realized from an OpenAPI spec (`openapi` → Prism
+ *            mock server) or a hand-written mock process (`src`).
+ *   local  — a LOCAL VERSION of the real service runs on this machine,
+ *            e.g. a vendor-shaped database replica. Realized from a docker
+ *            compose file (`compose` + published `port`).
+ *   remote — the session connects to the ACTUAL external service: either
+ *            the vendor's real endpoint with inline `credentials` (e.g. a
+ *            sandbox), or the external service as configured in the app's
+ *            tenant environment (`remote.env`, e.g. dev — credentials are
+ *            pulled from that environment's secret).
+ *
+ *   "mesh": {
+ *     "externals": {
+ *       "plaid-db": {                         // ── local (default) ──
+ *         "mode": "local",
+ *         "compose": "libs/plaid-db/docker/docker-compose.yml",
+ *         "port": 1433,                       // REQUIRED: the published port
+ *         "probe": "tcp",                     // non-HTTP uptime probe
+ *         "external": "plaid-db",
+ *         "credentials": {                    // {{host}}/{{port}} → localhost:1433
+ *           "host": "{{host}}", "port": "{{port}}",
+ *           "name": "Plaid_Clean", "username": "sa",
+ *           "password": "{{env:PLAID_DB_PASSWORD}}"
+ *         },
+ *         "remote": { "env": "dev" }          // `--externals plaid-db=remote`
+ *       },                                    //   pulls the dev-configured secret
+ *       "plaid": {                            // ── remote ──
+ *         "mode": "remote",
+ *         "external": "plaid",                // the vendor's REAL sandbox
+ *         "displayName": "Plaid",             // the Hub shows the real name…
+ *         "type": "api",                      // …and the integration type
+ *         "docs": "https://plaid.com/docs/api/",  // vendor reference docs
+ *         "credentials": {
+ *           "endpoint": "https://sandbox.plaid.com",
+ *           "client_id": "{{env:PLAID_CLIENT_ID}}",
+ *           "secret": "{{env:PLAID_SECRET}}"
+ *         }
+ *       },
+ *       "vendorpay": {                        // ── mock ──
+ *         "mode": "mock",
+ *         "openapi": "api/docs/spec/openapi.json",  // spec → Prism emulation
+ *         "external": "vendorpay",
+ *         "credentials": { "baseUrl": "{{url}}", "apiKey": "mock" }
+ *       }
+ *     }
+ *   }
+ *
+ * `mode` picks the DEFAULT; a declaration may carry more than one
+ * realization (e.g. compose + remote.env) and the CLI overrides per
+ * external at run time: `mesh dev --externals plaid-db=remote,plaid`.
+ * Declarations without `mode` infer it from their fields (compose → local,
+ * openapi/src → mock, sandbox/credentials-only → remote), so pre-mode
+ * declarations keep working (`sandbox: true` is a deprecated alias for
+ * mode remote).
+ *
+ * All credential values support `{{env:VAR}}` interpolation from the
+ * developer's environment, so real secrets (sandbox keys, DB passwords)
+ * never land in package.json.
+ *
+ * Realization: mock externals join the SAME orchestration as services named
+ * mock-{name} (ports, env files, tmux windows, Loki log pipeline); local
+ * externals come up via `docker compose up -d --wait` before the app's
+ * services and are torn down on `mesh dev --kill`; remote externals spawn
+ * nothing. In every mode the ExternalService credential secret is seeded at
+ * mesh/{tenant}/{env}/external/{name} so the app's resolveCredentials()
+ * path runs UNCHANGED, the vendor is registered in the local Hub's
+ * external-services view, and a blackbox uptime probe watches the
+ * realization — remote endpoints included.
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { logInfo, logSuccess, logWarn } from "../../utils/log.js";
+import { MeshCliError } from "../../utils/errors.js";
+import { LOCAL_ENV, LOCAL_AWS_CONFIG } from "./seed.js";
+import { probeTcp, upsertLocalSecret } from "./helpers.js";
+import { localProbesDir } from "./stack.js";
+const EXTERNAL_MODES = ["mock", "local", "remote"];
+const DECL_DOCS = { docs: 'package.json → "mesh": { "externals": { … } }' };
+/**
+ * Resolve + validate an external's mode: explicit `mode` (or the one
+ * inferred from the realization fields), checked against the fields that
+ * mode needs. Pre-mode declarations infer: compose → local, openapi/src →
+ * mock, sandbox/credentials-only → remote.
+ */
+export function externalMode(name, decl) {
+    const mode = decl.mode ??
+        (decl.compose
+            ? "local"
+            : decl.openapi || decl.src
+                ? "mock"
+                : decl.sandbox || decl.credentials || decl.remote
+                    ? "remote"
+                    : undefined);
+    if (!mode || !EXTERNAL_MODES.includes(mode)) {
+        throw new MeshCliError(`External '${name}': cannot determine mode — set "mode" to mock | local | remote (or declare openapi/src, compose, or credentials).`, { remediation: DECL_DOCS });
+    }
+    if (mode === "local") {
+        if (!decl.compose) {
+            throw new MeshCliError(`External '${name}': local mode requires "compose" — the docker compose file running the local version of the service.`, { remediation: DECL_DOCS });
+        }
+        if (typeof decl.port !== "number") {
+            throw new MeshCliError(`External '${name}': local (compose) mode requires "port" — the port the compose file publishes on localhost.`, { remediation: DECL_DOCS });
+        }
+    }
+    if (mode === "mock" && !decl.openapi && !decl.src) {
+        throw new MeshCliError(`External '${name}': mock mode emulates the service — declare "openapi" (spec → Prism mock) or "src" (mock process).`, { remediation: DECL_DOCS });
+    }
+    if (mode === "remote" && !remoteInlineCredentials(decl) && !decl.external) {
+        throw new MeshCliError(`External '${name}': remote mode needs a credential source — inline "credentials", "remote": { "env": … }, or "external" (pulls that environment's configured secret).`, { remediation: DECL_DOCS });
+    }
+    return mode;
+}
+/**
+ * Parse a `--externals` value — a comma-separated list of `name` or
+ * `name=mode` entries. An explicit mode overrides that declaration's
+ * default FOR THIS RUN; a bare name keeps the declared default.
+ *
+ * Names are returned in the order typed, de-duplicated (the last mode
+ * given for a name wins, so `--externals plaid,plaid=remote` is remote).
+ */
+export function parseExternalsSelection(input) {
+    const names = [];
+    const overrides = new Map();
+    for (const entry of input.split(",").map((s) => s.trim()).filter(Boolean)) {
+        const [rawName, mode, ...rest] = entry.split("=").map((s) => s.trim());
+        const name = rawName ?? "";
+        if (!name) {
+            throw new MeshCliError(`Bad --externals entry '${entry}' — expected name or name=mode with mode ∈ ${EXTERNAL_MODES.join(" | ")}.`, { remediation: { command: "mesh dev --externals plaid-db=remote,plaid" } });
+        }
+        if (mode !== undefined) {
+            if (rest.length > 0 || !EXTERNAL_MODES.includes(mode)) {
+                throw new MeshCliError(`Bad --externals entry '${entry}' — expected name or name=mode with mode ∈ ${EXTERNAL_MODES.join(" | ")}.`, { remediation: { command: "mesh dev --externals plaid-db=remote,plaid" } });
+            }
+            overrides.set(name, mode);
+        }
+        if (!names.includes(name))
+            names.push(name);
+    }
+    return { names, overrides };
+}
+/**
+ * The inline credential template a remote-mode run should use, if any:
+ * `remote.credentials` always wins; top-level `credentials` count only when
+ * the declaration has no local/mock realization (otherwise they are that
+ * realization's template, full of {{host}}/{{port}} tokens that only mean
+ * something against a local endpoint).
+ */
+export function remoteInlineCredentials(decl) {
+    if (decl.remote?.credentials)
+        return decl.remote.credentials;
+    if (decl.credentials && !decl.compose && !decl.openapi && !decl.src)
+        return decl.credentials;
+    return undefined;
+}
+/** Whether this declaration runs as a mock-{name} service in the dev
+ * orchestration (mock mode) vs outside it (local compose / remote). */
+export function isServiceMode(name, decl) {
+    return externalMode(name, decl) === "mock";
+}
+/**
+ * Interpolate one credential value: {{url}}/{{host}}/{{port}} from the
+ * stand-in's endpoint, {{env:VAR}} from the developer's environment
+ * (missing env vars are a hard error — a half-seeded secret is worse).
+ */
+export function interpolateCredentialValue(raw, endpoint, env = process.env) {
+    let value = raw.replace(/\{\{env:([A-Za-z_][A-Za-z0-9_]*)\}\}/g, (_, name) => {
+        const resolved = env[name];
+        if (resolved === undefined) {
+            throw new MeshCliError(`Credential value references {{env:${name}}} but ${name} is not set in your environment.`, { remediation: { command: `export ${name}=…  # then re-run mesh dev` } });
+        }
+        return resolved;
+    });
+    if (endpoint) {
+        value = value
+            .replaceAll("{{url}}", endpoint.url)
+            .replaceAll("{{host}}", endpoint.host)
+            .replaceAll("{{port}}", String(endpoint.port));
+    }
+    return value;
+}
+/** The Prism mock command for an openapi-mode declaration. `$PORT` expands
+ * in the service's launch shell (tmux and docker runners both source the
+ * env file), so port reallocation keeps working. */
+export function openapiMockCommand(decl) {
+    return (decl.command ?? [
+        "npx",
+        "-y",
+        "@stoplight/prism-cli@5",
+        "mock",
+        "-p",
+        "$PORT",
+        "-h",
+        "0.0.0.0",
+        decl.openapi,
+    ]);
+}
+/** Compose-mode project name — pinned so `--kill` can tear down exactly
+ * what `up` created, regardless of the compose file's own `name:`. */
+export function composeProjectName(sessionName, mockName) {
+    return `mesh-ext-${sessionName}-${mockName}`.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+}
+/** Wait until the external's published port accepts TCP (bounded). */
+async function waitForPort(port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await probeTcp(port, { timeoutMs: 2000 }))
+            return true;
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    return false;
+}
+/**
+ * Decide how to realize a compose external, given what already exists.
+ *
+ * OWNERSHIP FIRST: a port probe can't tell WHO serves the port, and the
+ * ordinary flow re-runs `mesh dev` against a session whose compose externals
+ * are deliberately left running. Adopting there would drop the ref from
+ * session state and permanently orphan the checkout's own container, so our
+ * own realization takes the normal `up` path (idempotent, ref re-recorded)
+ * and only a foreign one is adopted.
+ *
+ * IDENTITY SECOND: a foreign publisher is only adopted when it is a service
+ * THIS compose file defines. Well-known ports (1433/5432/22) are exactly
+ * where a native install or an unrelated container turns up, and adopting one
+ * silently seeds the app's credentials against the wrong database.
+ */
+export async function planComposeExternal(composeFile, project, port, probes) {
+    if (probes.ownsRunning(composeFile, project))
+        return { action: "up" };
+    if (await probes.portServed(port)) {
+        const publisher = probes.portPublisher(composeFile, port);
+        if (!publisher || !publisher.definedByFile) {
+            return { action: "conflict", ...(publisher ? { container: publisher.container } : {}) };
+        }
+        return { action: "adopt-served", container: publisher.container };
+    }
+    // Pinned container_name held by a STOPPED container from another checkout/
+    // project would make `up` fail with a name conflict — start that container
+    // instead. (A RUNNING one is caught by the port probe above.)
+    const foreign = probes.foreignPinned(composeFile, project);
+    if (foreign)
+        return { action: "adopt-stopped", container: foreign };
+    return { action: "up" };
+}
+/** Real docker/network probes — replaced in tests. */
+const dockerProbes = {
+    ownsRunning: ownsRunningRealization,
+    portServed: (port) => probeTcp(port, { timeoutMs: 2000 }),
+    foreignPinned: foreignPinnedContainer,
+    portPublisher: composeFilePortPublisher,
+};
+/**
+ * Bring a compose-mode external up (idempotent; waits for healthchecks —
+ * vendor DBs restoring seed data can take a while, hence the timeout).
+ *
+ * ADOPTION: the same external is often realized by more than one checkout —
+ * e.g. a vendor-DB compose ported from a legacy repo pins `container_name`
+ * and a host port, so whichever checkout created it first blocks every other
+ * `docker compose up` (name + port conflicts). An external service is by
+ * definition outside the app, so if ANOTHER checkout already serves its
+ * published port — or left a stopped container holding the pinned name —
+ * this ADOPTS that realization instead of failing: skip/`docker start`, wait
+ * for the port, and return undefined so `--kill` never tears down what
+ * another checkout owns. Our OWN realization is never adopted (see
+ * `planComposeExternal`) — it stays recorded so `--kill` still cleans it up,
+ * and a publisher this compose file doesn't define is never adopted either
+ * (it would seed the app's credentials against the wrong service).
+ */
+export async function composeExternalUp(appRoot, sessionName, name, decl, probes = dockerProbes) {
+    const composeFile = path.resolve(appRoot, decl.compose);
+    if (!fs.existsSync(composeFile)) {
+        throw new MeshCliError(`External '${name}': compose file not found at ${composeFile}.`, {
+            remediation: { docs: 'package.json → "mesh": { "externals": { … } }' },
+        });
+    }
+    const project = composeProjectName(sessionName, name);
+    const plan = await planComposeExternal(composeFile, project, decl.port, probes);
+    if (plan.action === "conflict") {
+        throw new MeshCliError(`External '${name}': localhost:${decl.port} is already served by ${plan.container ? `container '${plan.container}'` : "a process outside docker"}, which ${decl.compose} does not define — refusing to seed '${name}' credentials against it.`, {
+            remediation: {
+                command: `docker ps --filter publish=${decl.port}   # stop it, or change the declared port`,
+            },
+        });
+    }
+    if (plan.action === "adopt-served") {
+        logInfo(`External '${name}' already served on localhost:${decl.port} by container '${plan.container}' — adopting it (started outside this checkout; \`mesh dev --kill\` won't touch it).`);
+        return undefined;
+    }
+    if (plan.action === "adopt-stopped") {
+        const { container } = plan;
+        logInfo(`External '${name}': container '${container}' exists from another checkout — starting and adopting it.`);
+        execFileSync("docker", ["start", container], { stdio: ["ignore", "ignore", "inherit"] });
+        if (!(await waitForPort(decl.port, 300_000))) {
+            throw new MeshCliError(`External '${name}': adopted container '${container}' never served localhost:${decl.port}.`, { remediation: { command: `docker logs ${container}   # then: docker rm -f ${container} and re-run` } });
+        }
+        return undefined;
+    }
+    execFileSync("docker", ["compose", "-p", project, "-f", composeFile, "up", "-d", "--wait", "--wait-timeout", "300"], { stdio: ["ignore", "inherit", "inherit"] });
+    return { name, composeFile, project };
+}
+/** Whether OUR compose project already has a container running for this file.
+ * `docker compose ps` (running only) covers services WITHOUT a pinned
+ * `container_name` too, which the label-inspect path below structurally
+ * cannot — an unpinned service of ours is just `<project>-<svc>-1`. */
+function ownsRunningRealization(composeFile, project) {
+    try {
+        const out = execFileSync("docker", ["compose", "-p", project, "-f", composeFile, "ps", "--format", "json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        // Compose emits either a JSON array or NDJSON depending on version;
+        // "has any row" is all we need from it.
+        return out.length > 0 && out !== "[]";
+    }
+    catch {
+        // ps hiccup — treat as "not ours" and let the normal paths decide.
+        return false;
+    }
+}
+/** The compose file's rendered service map, or undefined when it can't be
+ * rendered (docker missing / bad file — callers decide what that means). */
+function composeServices(composeFile) {
+    try {
+        const config = JSON.parse(execFileSync("docker", ["compose", "-f", composeFile, "config", "--format", "json"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }));
+        const services = config?.services;
+        return services && typeof services === "object" ? services : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function portPublisher(port) {
+    try {
+        const out = execFileSync("docker", [
+            "ps",
+            "--filter",
+            `publish=${port}`,
+            "--format",
+            '{{.Names}}\t{{.Image}}\t{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.service"}}',
+        ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+        const line = out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean)[0];
+        if (!line)
+            return undefined;
+        const [container, image, project, service] = line.split("\t");
+        if (!container)
+            return undefined;
+        return {
+            container,
+            image: image || undefined,
+            project: project || undefined,
+            service: service || undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the container publishing the declared port is a service THIS
+ * compose file defines — the evidence adoption requires. Matches on the
+ * pinned `container_name`, or on the compose service name (cross-checked
+ * against the image when both sides declare one, so an unrelated project's
+ * service that happens to be called `db` isn't mistaken for ours). */
+function composeFileOwns(composeFile, publisher) {
+    if (!publisher)
+        return false;
+    const services = composeServices(composeFile);
+    if (!services)
+        return false; // no identity evidence — don't adopt
+    for (const [key, svc] of Object.entries(services)) {
+        if (svc?.container_name && svc.container_name === publisher.container)
+            return true;
+        if (publisher.service && publisher.service === key) {
+            if (!svc?.image || !publisher.image || svc.image === publisher.image)
+                return true;
+        }
+    }
+    return false;
+}
+/** `ComposeExternalProbes.portPublisher` — who serves the declared port, and
+ * whether this compose file defines it. Undefined when docker publishes
+ * nothing there (a native process on the port, or no docker at all), which
+ * `planComposeExternal` treats as a conflict rather than an adoption. */
+function composeFilePortPublisher(composeFile, port) {
+    const publisher = portPublisher(port);
+    if (!publisher)
+        return undefined;
+    return { container: publisher.container, definedByFile: composeFileOwns(composeFile, publisher) };
+}
+/** Find a container holding a `container_name` this compose file pins, when
+ * it belongs to a different compose project (another checkout's realization
+ * of the same external). Returns the container name, or undefined. */
+function foreignPinnedContainer(composeFile, project) {
+    // config render hiccup — fall through to the normal `up`, which reports
+    // real errors itself.
+    for (const svc of Object.values(composeServices(composeFile) ?? {})) {
+        const pinned = svc?.container_name;
+        if (!pinned)
+            continue;
+        try {
+            const owner = execFileSync("docker", ["inspect", pinned, "--format", '{{ index .Config.Labels "com.docker.compose.project" }}'], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+            if (owner !== project)
+                return pinned;
+        }
+        catch {
+            // no container by that name — nothing to adopt for this service
+        }
+    }
+    return undefined;
+}
+/** Tear down compose-mode externals recorded in session state. Volumes are
+ * kept (vendor DB data survives sessions, like the cloud external it
+ * stands in for); best-effort per project. */
+export function composeExternalsDown(refs) {
+    for (const ref of refs ?? []) {
+        try {
+            execFileSync("docker", ["compose", "-p", ref.project, "-f", ref.composeFile, "down", "--remove-orphans"], {
+                stdio: ["ignore", "inherit", "inherit"],
+            });
+        }
+        catch {
+            /* best effort — the file may be gone or docker down */
+        }
+    }
+}
+/** Same heuristic the schema seed uses: which credential keys are secret. */
+const SECRET_KEY_RE = /key|secret|password|token/i;
+/** Read the app's declared externals (root package.json → mesh.externals;
+ * legacy key mesh.mocks still read, externals wins on name collision). */
+export function readLocalMocks(appRoot) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(appRoot, "package.json"), "utf-8"));
+        const mocks = pkg?.mesh?.mocks;
+        const externals = pkg?.mesh?.externals;
+        return {
+            ...(mocks && typeof mocks === "object" ? mocks : {}),
+            ...(externals && typeof externals === "object" ? externals : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function externalSecretPath(tenant, external) {
+    return `mesh/${tenant}/${LOCAL_ENV}/external/${external}`;
+}
+/**
+ * Pull an external service's credentials as configured in the app's tenant
+ * environment (the CLOUD platform, not the local fabric) — secret
+ * mesh/{tenant}/{env}/external/{name}, read with the developer's ambient
+ * AWS credentials (AWS_PROFILE / SSO session for that tenant's account).
+ * When the shell carries no AWS identity at all, `profile` (from the
+ * declaration; MESH_AWS_PROFILE overrides) names the profile to use — the
+ * same convention repo pull scripts follow.
+ */
+export async function fetchRemoteExternalCredentials(tenant, env, external, profile) {
+    const secretId = `mesh/${tenant}/${env}/external/${external}`;
+    const region = process.env.MESH_PLATFORM_REGION ?? process.env.AWS_REGION ?? "us-east-2";
+    const fallbackProfile = !process.env.AWS_ACCESS_KEY_ID && !process.env.AWS_PROFILE
+        ? (process.env.MESH_AWS_PROFILE ?? profile)
+        : undefined;
+    try {
+        const { SecretsManagerClient, GetSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
+        // The SDK's default chain reads AWS_PROFILE at first resolution — scope
+        // the fallback to this client's call (no ambient identity to clobber).
+        if (fallbackProfile)
+            process.env.AWS_PROFILE = fallbackProfile;
+        const sm = new SecretsManagerClient({ region });
+        let res;
+        try {
+            res = await sm.send(new GetSecretValueCommand({ SecretId: secretId }));
+        }
+        finally {
+            if (fallbackProfile)
+                delete process.env.AWS_PROFILE;
+        }
+        const parsed = JSON.parse(res.SecretString ?? "{}");
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("secret value is not a JSON object");
+        }
+        return Object.fromEntries(Object.entries(parsed).map(([key, v]) => [key, String(v)]));
+    }
+    catch (err) {
+        throw new MeshCliError(`External '${external}': could not pull remote credentials from the ${env} environment (${secretId}, region ${region}): ${err instanceof Error ? err.message : err}`, {
+            remediation: {
+                command: `AWS_PROFILE=<${tenant}-${env} profile> mesh dev …   # or set "remote": { "profile": … } on the declaration / MESH_AWS_PROFILE`,
+            },
+        });
+    }
+}
+/** The prober runs inside the stack: anything addressed at the developer
+ * host must go through host.docker.internal. */
+function hostForProber(target) {
+    return target.replace(/\b(?:localhost|127\.0\.0\.1)\b/, "host.docker.internal");
+}
+/**
+ * A credential's endpoint value as an HTTP probe target, or undefined when
+ * it isn't one. Credentials pulled from a tenant secret carry whatever the
+ * vendor configured — a JDBC/ODBC connection string, an `sftp://` URL, or
+ * an http URL with embedded userinfo. Anything non-http(s) falls through to
+ * the tcp branch, and userinfo is stripped: the target is written to a
+ * plaintext probe file and relabeled into Prometheus' `instance` label, so
+ * a password in it would leak into every `probe_*` series.
+ */
+function httpProbeUrl(raw) {
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return undefined;
+    parsed.username = "";
+    parsed.password = "";
+    return hostForProber(parsed.toString());
+}
+/** Reachability target for a non-HTTP integration, derived from its
+ * credentials: a host/port pair (databases, SFTP) or an S3 bucket endpoint
+ * (probed via TCP — no SDK or credentials needed, the technique CSP's
+ * network lib used). */
+function derivedTcpTarget(creds) {
+    if (creds.host && creds.port)
+        return `${hostForProber(creds.host)}:${creds.port}`;
+    if (creds.bucket)
+        return `${creds.bucket}.s3.${creds.region || "us-east-1"}.amazonaws.com:443`;
+    return undefined;
+}
+/** The blackbox probe target for a realization, by mode: local/mock
+ * stand-ins are probed on the host (the prober runs inside the stack →
+ * host.docker.internal); remote externals are probed at their REAL
+ * endpoint, so the Hub shows actual vendor reachability. Every integration
+ * gets AT LEAST a reachability check when its credentials expose a target:
+ * an HTTP endpoint, a host(:port), or an S3 bucket (probed via TCP to the
+ * bucket endpoint — no SDK/credentials needed, the same technique CSP's
+ * network lib used). Undefined = nothing probeable in the credentials.
+ *
+ * Target and module come from ONE decision here so they can't drift: a
+ * misrouted probe just reports probe_success 0, indistinguishable from a
+ * genuinely down service. `tcp` yields host:port with no scheme/path and
+ * routes the scrape to blackbox's tcp_connect (the scrape config's default
+ * stays http_2xx); `http` GETs the target and expects 2xx. */
+export function resolveProbeTarget(mode, decl, endpoint, creds) {
+    if (mode === "remote") {
+        // The endpoint comes from a TENANT SECRET, so it may be anything a
+        // vendor credential carries — a JDBC/ODBC connection string, or a URL
+        // with userinfo. Only a real http(s) URL is probeable, and its
+        // credentials must never reach the probe file (world-readable) or the
+        // Prometheus `instance` label.
+        const url = httpProbeUrl(creds.endpoint ?? creds.url ?? creds.baseUrl);
+        // Reachability fallbacks for non-HTTP integrations: host:port
+        // (databases, SFTP) or the S3 bucket endpoint (object storage).
+        const tcpTarget = derivedTcpTarget(creds);
+        if (decl.probe === "tcp" || (!url && tcpTarget)) {
+            if (!tcpTarget && decl.probe === "tcp") {
+                logWarn(`External '${decl.external ?? ""}': probe: "tcp" declared but the remote credentials carry no host/port (or bucket) to probe — no uptime probe registered.`);
+            }
+            return tcpTarget ? { target: tcpTarget, module: "tcp_connect" } : undefined;
+        }
+        // Remote endpoints rarely expose /health — default to the endpoint
+        // root (Plaid's sandbox, for one, answers 200 there).
+        return url ? { target: url.replace(/\/+$/, "") + (decl.healthPath ?? "") } : undefined;
+    }
+    if (!endpoint)
+        return undefined;
+    if (decl.probe === "tcp") {
+        return { target: `host.docker.internal:${endpoint.port}`, module: "tcp_connect" };
+    }
+    return {
+        target: hostForProber(endpoint.url).replace(/\/+$/, "") + (decl.healthPath ?? "/health"),
+    };
+}
+/** Hub display name: explicit `displayName`, else the external name
+ * title-cased on word boundaries ("plaid-db" → "Plaid Db"). */
+export function externalDisplayName(name, decl) {
+    return (decl.displayName ??
+        name
+            .split(/[-_\s]+/)
+            .filter(Boolean)
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(" "));
+}
+/** Normalize the decl's `docs` (string URL or {url, provider}) for the meta. */
+export function externalDocs(decl) {
+    if (!decl.docs)
+        return undefined;
+    return typeof decl.docs === "string" ? { url: decl.docs } : decl.docs;
+}
+/** Prometheus file_sd target file for one external's uptime probe. One
+ * file per (tenant, app, external) so a session's probes can be removed on
+ * `--kill` without touching another app's. */
+export function localProbeFile(tenant, app, external) {
+    return path.join(localProbesDir(), `${tenant}-${app}-${external}.json`);
+}
+/** Drop probe target files (best effort). Called on `mesh dev --kill` so
+ * Prometheus stops scraping stand-ins that no longer exist — otherwise the
+ * Hub shows an integration down for a session that isn't running. */
+export function localProbesRemove(files) {
+    for (const file of files ?? []) {
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch {
+            /* best effort — the cache dir may be gone */
+        }
+    }
+}
+/**
+ * Wire a realization into the platform: seed the external-service
+ * credential secret and register the vendor in the local Hub's
+ * external-services view — the same shapes ExternalService exports in the
+ * cloud. `endpoint` is the local stand-in's address (absent in remote
+ * mode — the credentials carry the real endpoint).
+ *
+ * Returns the probe target file this realization registered, if any, so the
+ * caller can record it in session state and remove it on `--kill`.
+ */
+export async function seedLocalMock(args) {
+    const { tenant, app, name, decl, endpoint } = args;
+    if (!decl.external)
+        return undefined;
+    const mode = externalMode(name, decl);
+    // Credential values by mode: local/mock interpolate the declared template
+    // against the stand-in's endpoint; remote uses inline credentials or
+    // pulls the tenant environment's configured secret.
+    let value;
+    if (mode === "remote") {
+        const inline = remoteInlineCredentials(decl);
+        value = inline
+            ? Object.fromEntries(Object.entries(inline).map(([key, raw]) => [
+                key,
+                interpolateCredentialValue(raw, undefined),
+            ]))
+            : await fetchRemoteExternalCredentials(tenant, decl.remote?.env ?? "dev", decl.external, decl.remote?.profile);
+    }
+    else {
+        if (!decl.credentials)
+            return undefined;
+        value = Object.fromEntries(Object.entries(decl.credentials).map(([key, raw]) => [
+            key,
+            interpolateCredentialValue(raw, endpoint),
+        ]));
+    }
+    const secretName = externalSecretPath(tenant, decl.external);
+    await upsertLocalSecret(secretName, value);
+    // The .config mirror — non-secret fields only. This is what the Hub's
+    // credential views READ (the main secret is runtime-only by design), so
+    // baseUrl etc. display in the Integrations detail page.
+    await upsertLocalSecret(`${secretName}/.config`, Object.fromEntries(Object.entries(value).filter(([key]) => !SECRET_KEY_RE.test(key))));
+    // Hub discovery — the same per-stack shapes ExternalService exports in the
+    // cloud (/apps/{app}/stacks/{stack}/external-services/{name}/…).
+    const { SSMClient, PutParameterCommand } = await import("@aws-sdk/client-ssm");
+    const ssm = new SSMClient(LOCAL_AWS_CONFIG);
+    const base = `/mesh-platform/${tenant}/${LOCAL_ENV}/apps/${app}/stacks/local/external-services/${decl.external}`;
+    await ssm.send(new PutParameterCommand({
+        Name: `${base}/meta`,
+        Type: "String",
+        Overwrite: true,
+        Value: JSON.stringify({
+            name: decl.external,
+            // The integration keeps its REAL name in the Hub ("Plaid", not a
+            // generated phrase); the description leads with it too, so display
+            // heuristics that promote description heads still land on the name.
+            displayName: externalDisplayName(name, decl),
+            type: decl.type ?? "other",
+            description: mode === "local"
+                ? `${externalDisplayName(name, decl)} — local replica via mesh dev (docker compose)`
+                : mode === "remote"
+                    ? remoteInlineCredentials(decl)
+                        ? `${externalDisplayName(name, decl)} — remote service (vendor credentials)`
+                        : `${externalDisplayName(name, decl)} — remote service (${decl.remote?.env ?? "dev"} environment credentials)`
+                    : `${externalDisplayName(name, decl)} — emulated by mesh dev (mock)`,
+            secretPrefix: secretName,
+            ...(externalDocs(decl) ? { docs: externalDocs(decl) } : {}),
+        }),
+        Description: `External service registration (local mock ${name})`,
+    }));
+    await ssm.send(new PutParameterCommand({
+        Name: `${base}/credentials`,
+        Type: "String",
+        Overwrite: true,
+        Value: JSON.stringify({
+            fields: Object.fromEntries(Object.keys(value).map((key) => [
+                key,
+                { type: "field", name: key, description: "", secret: SECRET_KEY_RE.test(key), optional: false },
+            ])),
+            keyedBy: null,
+        }),
+        Description: `External service credential schema (local mock ${name})`,
+    }));
+    // Blackbox probe target (Prometheus file_sd) — the local analog of the
+    // Probe CR ExternalService creates in the cloud, with the SAME label set,
+    // so probe_success drives the Hub's health/uptime views unchanged.
+    // Local/mock stand-ins are probed on the host; remote externals at their
+    // real endpoint (host:port via the tcp_connect module for non-HTTP
+    // externals — the __probe_module label routes the module through the
+    // scrape config's relabeling, and "__"-prefixed labels drop after
+    // relabeling so it never pollutes the stored series).
+    const probe = resolveProbeTarget(mode, decl, endpoint, value);
+    await ssm.send(new PutParameterCommand({
+        Name: `${base}/healthCheck`,
+        Type: "String",
+        Overwrite: true,
+        Value: JSON.stringify({ intervalSeconds: 30, timeoutSeconds: 10, hasCustomCheck: false, hasProbe: !!probe }),
+        Description: `External service health check config (local mock ${name})`,
+    }));
+    // The file and `hasProbe` must never disagree: a realization that no
+    // longer resolves a probe target drops the file it wrote on a previous
+    // run, or Prometheus keeps scraping the old target forever.
+    const probeFile = localProbeFile(tenant, app, decl.external);
+    if (probe) {
+        fs.writeFileSync(probeFile, JSON.stringify([
+            {
+                targets: [probe.target],
+                labels: {
+                    type: "external-service",
+                    tenant,
+                    env: LOCAL_ENV,
+                    app,
+                    external_service: decl.external,
+                    target: decl.external,
+                    // "__"-prefixed labels drop after relabeling, so the module
+                    // selector never pollutes the stored series.
+                    ...(probe.module ? { __probe_module: probe.module } : {}),
+                },
+            },
+        ], null, 2));
+    }
+    else {
+        localProbesRemove([probeFile]);
+    }
+    const endpointShown = endpoint?.url ??
+        value.endpoint ??
+        value.url ??
+        value.baseUrl ??
+        (value.host ? `${value.host}${value.port ? `:${value.port}` : ""}` : "credentials");
+    logSuccess(`External '${name}' wired (${mode}): ${secretName} → ${endpointShown}` +
+        ` (Hub registration${probe ? " + uptime probe" : ""})`);
+    return probe ? probeFile : undefined;
+}
+//# sourceMappingURL=mocks.js.map