@mesh-tech/mesh-cli 0.20.1 → 0.20.3

package/dist/src/commands/local/mocks.d.ts

@@ -1,231 +1,50 @@
-/**
- * `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.
- */
 export interface LocalMockDecl {
-    /** Default mode for this external: "mock" (emulate via openapi/src),
-     * "local" (docker compose local version), "remote" (the actual service).
-     * Inferred from the realization fields when omitted; overridable per run
-     * with `mesh dev --externals name=mode`. */
     mode?: ExternalMode;
-    /** Mock mode: directory (relative to app root) with a package.json `dev`
-     * script — a hand-written mock process. */
     src?: string;
-    /** Local mode: docker compose file (relative to app root) running a local
-     * version of the external service — e.g. a vendor-shaped database
-     * replica. `mesh dev` runs `docker compose up -d --wait` before the
-     * app's services and `docker compose down` on `--kill`. Requires `port`. */
     compose?: string;
-    /** Mock mode: OpenAPI spec file (relative to app root); the CLI emulates
-     * the service with a Prism mock server (`npx @stoplight/prism-cli mock`)
-     * as mock-{name}. */
     openapi?: string;
-    /** @deprecated alias for `mode: "remote"` (with inline credentials). */
     sandbox?: boolean;
-    /** Remote-mode credential source. When the external runs in remote mode,
-     * its credentials come from (first match): `remote.credentials` (inline,
-     * env-interpolated), the top-level `credentials` if this declaration has
-     * no local/mock realization (a pure-remote declaration), or the external
-     * service configured in the app's tenant environment `remote.env`
-     * (default "dev") — secret mesh/{tenant}/{env}/external/{name}, read
-     * with the developer's ambient AWS credentials. `remote.profile` names
-     * the AWS profile for that pull when the shell carries no AWS identity
-     * (no AWS_ACCESS_KEY_ID / AWS_PROFILE); the MESH_AWS_PROFILE env var
-     * overrides it — the same convention repo pull scripts use. */
     remote?: {
         env?: string;
         credentials?: Record<string, string>;
         profile?: string;
     };
-    /** Human-facing integration name shown in the Hub (e.g. "Plaid",
-     * "Unit21"). @default the external name title-cased ("plaid-db" →
-     * "Plaid Db"). */
     displayName?: string;
-    /** Vendor reference documentation for the integration, linked from the
-     * Hub — a URL string or `{ url, provider }`.
-     * @example "https://plaid.com/docs/api/" */
     docs?: string | {
         url: string;
         provider?: string;
     };
-    /** Fixed port; omitted = auto-allocated after the app's services.
-     * REQUIRED in local (compose) mode — the compose file's published port. */
     port?: number;
-    /** Launch command (default: ["pnpm", "dev"]; openapi mocks synthesize a
-     * Prism command) */
     command?: string[];
-    /** Extra env for the mock process */
     env?: Record<string, string>;
-    /** ExternalService name this declaration realizes */
     external?: string;
-    /** Credential JSON seeded into the external secret (the local/mock
-     * realization's template; also the remote source for pure-remote
-     * declarations). Tokens: "{{url}}" → the stand-in's URL, "{{host}}"/
-     * "{{port}}" → its host/port, and "{{env:VAR}}" → the developer's
-     * environment (all modes). */
     credentials?: Record<string, string>;
-    /** Integration type shown in the Hub — api, database, object_storage,
-     * sftp, banking_core, … (@default "other"). Display only; derived
-     * reachability probes key off the credential fields themselves (a
-     * `bucket` credential probes TCP to the bucket endpoint regardless of
-     * the declared type). */
     type?: string;
-    /** Health endpoint path probed by the platform's blackbox exporter
-     * (uptime in the Hub). @default "/health" for local/mock realizations;
-     * remote endpoints default to probing the endpoint root ("") since
-     * vendors rarely expose /health. */
     healthPath?: string;
-    /** Blackbox probe module. "http" (default) GETs the health URL and
-     * expects 2xx; "tcp" only checks the port accepts connections — REQUIRED
-     * for non-HTTP externals (databases, SFTP, …) whose uptime would
-     * otherwise always read down. */
     probe?: "http" | "tcp";
 }
-/** The three ways an external service exists in a local dev session. */
 export type ExternalMode = "mock" | "local" | "remote";
-/**
- * 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 declare function externalMode(name: string, decl: LocalMockDecl): ExternalMode;
-/** A parsed `--externals` selection: the externals named, and the per-run
- * mode overrides typed alongside them (`plaid-db=remote`). */
 export interface ExternalsSelection {
     names: string[];
     overrides: Map<string, ExternalMode>;
 }
-/**
- * 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 declare function parseExternalsSelection(input: string): ExternalsSelection;
-/**
- * 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 declare function remoteInlineCredentials(decl: LocalMockDecl): Record<string, string> | undefined;
-/** Whether this declaration runs as a mock-{name} service in the dev
- * orchestration (mock mode) vs outside it (local compose / remote). */
 export declare function isServiceMode(name: string, decl: LocalMockDecl): boolean;
-/** Endpoint tokens available to credential interpolation. */
 export interface MockEndpoint {
     url: string;
     host: string;
     port: number;
 }
-/**
- * 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 declare function interpolateCredentialValue(raw: string, endpoint: MockEndpoint | undefined, env?: NodeJS.ProcessEnv): string;
-/** 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 declare function openapiMockCommand(decl: LocalMockDecl): string[];
-/** Compose-mode project name — pinned so `--kill` can tear down exactly
- * what `up` created, regardless of the compose file's own `name:`. */
 export declare function composeProjectName(sessionName: string, mockName: string): string;
-/** A compose-mode external recorded in session state for teardown. */
 export interface ComposeExternalRef {
     name: string;
     composeFile: string;
     project: string;
 }
-/** What an existing realization of a compose external means for this run.
- *  - `up`            → nothing foreign in the way (or the realization is OURS):
- *                      normal idempotent `up`, ref recorded for `--kill`.
- *  - `adopt-served`  → ANOTHER realization of THIS compose file already serves
- *                      the declared port.
- *  - `adopt-stopped` → a stopped container from another compose project holds
- *                      a `container_name` this file pins.
- *  - `conflict`      → the port is served by something this compose file does
- *                      not define (a native database, an unrelated container).
- *                      Never adopted: the app's credentials would be seeded
- *                      against the wrong service. */
 export type ComposeExternalPlan = {
     action: "up";
 } | {
@@ -238,119 +57,32 @@ export type ComposeExternalPlan = {
     action: "conflict";
     container?: string;
 };
-/** The docker/network lookups `planComposeExternal` needs, injectable so the
- * branch table is unit-testable without a docker daemon. */
 export interface ComposeExternalProbes {
-    /** Is a container of OUR compose project already running for this file? */
     ownsRunning(composeFile: string, project: string): boolean;
-    /** Does anything accept TCP on the declared port? */
     portServed(port: number): Promise<boolean>;
-    /** A pinned `container_name` held by a DIFFERENT compose project. */
     foreignPinned(composeFile: string, project: string): string | undefined;
-    /** Who publishes `port`, and is it a service THIS compose file defines?
-     * Undefined when nothing in docker publishes it (a native process, or no
-     * docker at all) — which is itself disqualifying for adoption. */
     portPublisher(composeFile: string, port: number): {
         container: string;
         definedByFile: boolean;
     } | undefined;
 }
-/**
- * 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 declare function planComposeExternal(composeFile: string, project: string, port: number, probes: ComposeExternalProbes): Promise<ComposeExternalPlan>;
-/**
- * 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 declare function composeExternalUp(appRoot: string, sessionName: string, name: string, decl: LocalMockDecl, probes?: ComposeExternalProbes): Promise<ComposeExternalRef | 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 declare function composeExternalsDown(refs: ComposeExternalRef[] | undefined): void;
-/** Read the app's declared externals (root package.json → mesh.externals;
- * legacy key mesh.mocks still read, externals wins on name collision). */
 export declare function readLocalMocks(appRoot: string): Record<string, LocalMockDecl>;
 export declare function externalSecretPath(tenant: string, external: string): string;
-/**
- * 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 declare function fetchRemoteExternalCredentials(tenant: string, env: string, external: string, profile?: string): Promise<Record<string, string>>;
-/** 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 declare function resolveProbeTarget(mode: ExternalMode, decl: LocalMockDecl, endpoint: MockEndpoint | undefined, creds: Record<string, string>): {
     target: string;
     module?: "tcp_connect";
 } | undefined;
-/** Hub display name: explicit `displayName`, else the external name
- * title-cased on word boundaries ("plaid-db" → "Plaid Db"). */
 export declare function externalDisplayName(name: string, decl: LocalMockDecl): string;
-/** Normalize the decl's `docs` (string URL or {url, provider}) for the meta. */
 export declare function externalDocs(decl: LocalMockDecl): {
     url: string;
     provider?: string;
 } | undefined;
-/** 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 declare function localProbeFile(tenant: string, app: string, external: string): string;
-/** 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 declare function localProbesRemove(files: string[] | undefined): void;
-/**
- * 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 declare function seedLocalMock(args: {
     tenant: string;
     app: string;
@@ -358,4 +90,3 @@ export declare function seedLocalMock(args: {
     decl: LocalMockDecl;
     endpoint?: MockEndpoint;
 }): Promise<string | undefined>;
-//# sourceMappingURL=mocks.d.ts.map