@mesh-tech/mesh-cli 0.1.1 → 0.12.0

package/dist/src/utils/build-info.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI provenance for `mesh --version` (MESH-2479).
+ *
+ * A stale shim / stale global install is invisible when --version prints only
+ * the package version — two different checkouts (or a source tree vs a
+ * published dist) can share "0.5.1". This resolves WHERE the running CLI
+ * came from (TypeScript source vs published dist) plus the commit/build date,
+ * so "am I running the code I think I am?" is answerable from one command.
+ *
+ * Source layout: bin/mesh.ts runs under tsx from the repo — commit/date come
+ * from git at call time. Dist layout: the published package ships
+ * dist/build-info.json written by scripts/build-for-publish.ts.
+ */
+export interface CliRuntimeInfo {
+    version: string;
+    mode: "source" | "dist";
+    commit?: string;
+    builtAt?: string;
+}
+/** Pure: a module path under a `dist/` segment is the published build. */
+export declare function detectRuntimeMode(modulePath: string): "source" | "dist";
+/** Pure: one-line version string with provenance, e.g.
+ * `0.5.1 (source @ abc1234 2026-07-30)` or
+ * `0.5.1 (published build 2026-07-28, commit abc1234)`. */
+export declare function formatVersionLine(info: CliRuntimeInfo): string;
+/** Resolve the running CLI's version + provenance. Never throws.
+ * `vcs: false` skips the git spawns in source mode (version + mode only) —
+ * commit/date cost two synchronous `git` runs, too slow to pay on every
+ * invocation when nothing will print them. */
+export declare function resolveCliRuntime(opts?: {
+    vcs?: boolean;
+}): CliRuntimeInfo;
+//# sourceMappingURL=build-info.d.ts.map

package/dist/src/utils/build-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-info.d.ts","sourceRoot":"","sources":["../../../src/utils/build-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAEvE;AAED;;2DAE2D;AAC3D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAS9D;AAmBD;;;8CAG8C;AAC9C,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,CA8C1E"}

package/dist/src/utils/build-info.js

@@ -0,0 +1,102 @@
+/**
+ * CLI provenance for `mesh --version` (MESH-2479).
+ *
+ * A stale shim / stale global install is invisible when --version prints only
+ * the package version — two different checkouts (or a source tree vs a
+ * published dist) can share "0.5.1". This resolves WHERE the running CLI
+ * came from (TypeScript source vs published dist) plus the commit/build date,
+ * so "am I running the code I think I am?" is answerable from one command.
+ *
+ * Source layout: bin/mesh.ts runs under tsx from the repo — commit/date come
+ * from git at call time. Dist layout: the published package ships
+ * dist/build-info.json written by scripts/build-for-publish.ts.
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+/** Pure: a module path under a `dist/` segment is the published build. */
+export function detectRuntimeMode(modulePath) {
+    return modulePath.split(/[\\/]/).includes("dist") ? "dist" : "source";
+}
+/** Pure: one-line version string with provenance, e.g.
+ * `0.5.1 (source @ abc1234 2026-07-30)` or
+ * `0.5.1 (published build 2026-07-28, commit abc1234)`. */
+export function formatVersionLine(info) {
+    if (info.mode === "source") {
+        const at = [info.commit, info.builtAt].filter(Boolean).join(" ");
+        return `${info.version} (source${at ? ` @ ${at}` : ""})`;
+    }
+    const built = info.builtAt ? ` ${info.builtAt.slice(0, 10)}` : "";
+    const commit = info.commit ? `, commit ${info.commit}` : "";
+    const detail = built || commit ? `${built}${commit}` : " — build metadata unavailable";
+    return `${info.version} (published build${detail})`;
+}
+/** Walk up from `startDir` to the @mesh-tech/mesh-cli package root. */
+function findCliPackageRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+            if (pkg.name === "@mesh-tech/mesh-cli")
+                return dir;
+        }
+        catch {
+            // keep walking
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Resolve the running CLI's version + provenance. Never throws.
+ * `vcs: false` skips the git spawns in source mode (version + mode only) —
+ * commit/date cost two synchronous `git` runs, too slow to pay on every
+ * invocation when nothing will print them. */
+export function resolveCliRuntime(opts) {
+    const vcs = opts?.vcs ?? true;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const mode = detectRuntimeMode(here);
+    const root = findCliPackageRoot(here);
+    let version = "0.0.0";
+    if (root) {
+        try {
+            version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8")).version ?? version;
+        }
+        catch {
+            // fall through with the placeholder
+        }
+    }
+    const info = { version, mode };
+    if (!root)
+        return info;
+    if (mode === "dist") {
+        try {
+            const meta = JSON.parse(fs.readFileSync(path.join(root, "dist", "build-info.json"), "utf-8"));
+            info.commit = meta.commit;
+            info.builtAt = meta.builtAt;
+        }
+        catch {
+            // pre-MESH-2479 publishes have no build-info.json
+        }
+        return info;
+    }
+    if (!vcs)
+        return info;
+    try {
+        const git = (args) => execFileSync("git", args, {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        info.commit = git(["rev-parse", "--short", "HEAD"]);
+        info.builtAt = git(["log", "-1", "--format=%cs"]);
+    }
+    catch {
+        // not a git checkout (e.g. exported source) — version + mode still print
+    }
+    return info;
+}
+//# sourceMappingURL=build-info.js.map

package/dist/src/utils/build-info.js.map

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

package/dist/src/utils/capture-history.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Serialize a fetched Temporal workflow history into the replay-fixture JSON
+ * shape — the same canonical proto3-JSON `{ events: [...] }` that
+ * `@mesh-tech/agent-sdk`'s `replay/history-io.ts` `historyToFixture` produces,
+ * so a captured file replays via `replayFixture` (which rehydrates it with
+ * `historyFromJSON`) for LOCAL debugging. Captured PRODUCTION histories are
+ * never committed (they contain real, decrypted customer/conversation data —
+ * see the CLI's do-not-commit warning); only synthetic goldens live in
+ * `packages/agent-sdk/src/replay/fixtures/`.
+ *
+ * We reuse `@temporalio/common`'s `historyToJSON` directly (the exact helper
+ * agent-sdk's history-io uses) rather than importing `@mesh-tech/agent-sdk`:
+ * the CLI has no reason to pull in the whole worker/replay stack, and keeping
+ * the dependency pointed at the shared Temporal library guarantees the output
+ * round-trips through `historyFromJSON`.
+ *
+ * The one thing a *real* history needs that a synthetic golden fixture doesn't:
+ * its payloads are ENCRYPTED (the worker's AES-GCM codec). `historyToJSON`
+ * would just base64 the ciphertext, which `replayFixture`'s plaintext converter
+ * can't decode. So before serializing we walk every Payload in the history and
+ * replace each encrypted one with its decrypted inner Payload — yielding a
+ * plaintext fixture identical in shape to a codec-free golden capture.
+ */
+import type { RawPayloadDecrypter } from "./temporal-codec.js";
+/**
+ * Walk an arbitrary history-event tree and decrypt every encrypted Payload in
+ * place, using `decrypt` to turn an encrypted Payload into its plaintext inner
+ * Payload. Payloads the decrypter reports as non-encrypted (`null`) are left
+ * untouched. Returns the number of payloads that were decrypted.
+ *
+ * The `{ metadata, data }` heuristic mirrors Temporal's own `fixPayloads` in
+ * `@temporalio/common/lib/proto-utils`, so it identifies exactly the nodes
+ * proto3-JSON treats as payloads. Once a node is a Payload we do NOT recurse
+ * into it (its metadata values are bytes, not nested payloads).
+ */
+export declare function decryptHistoryPayloads(node: unknown, decrypt: RawPayloadDecrypter): Promise<number>;
+/** Result of {@link serializeHistoryToFixture}. */
+export interface CaptureResult {
+    /** The parsed proto3-JSON fixture object (drop-in for `replayFixture`). */
+    fixture: unknown;
+    /** Total events serialized. */
+    eventCount: number;
+    /** How many encrypted payloads were decrypted (0 when no decrypter given). */
+    decryptedPayloads: number;
+}
+/**
+ * Turn an ordered list of raw history events into a replay fixture object.
+ *
+ * @param events - Raw proto-decoded history events, in order (as yielded by the
+ *   CLI's `iterHistoryEvents` over `getWorkflowExecutionHistory`).
+ * @param decrypter - Optional raw payload decrypter. When provided, every
+ *   encrypted payload in the history is decrypted in place before serialization
+ *   so the fixture is replayable with a plaintext converter. When omitted, the
+ *   payloads are serialized as-is (ciphertext, base64-encoded).
+ *
+ * `historyToJSON` runs its input through protobuf `History.fromObject`, so a
+ * plain `{ events }` object of raw events is accepted directly; it returns a
+ * proto3-JSON *string* which we parse back to a structured object (the same
+ * `JSON.parse(historyToJSON(...))` round-trip `historyToFixture` performs).
+ */
+export declare function serializeHistoryToFixture(events: unknown[], decrypter?: RawPayloadDecrypter): Promise<CaptureResult>;
+//# sourceMappingURL=capture-history.d.ts.map

package/dist/src/utils/capture-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-history.d.ts","sourceRoot":"","sources":["../../../src/utils/capture-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAc,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAqB3E;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,OAAO,EAAE,EACjB,SAAS,CAAC,EAAE,mBAAmB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAUxB"}

package/dist/src/utils/capture-history.js

@@ -0,0 +1,94 @@
+/**
+ * Serialize a fetched Temporal workflow history into the replay-fixture JSON
+ * shape — the same canonical proto3-JSON `{ events: [...] }` that
+ * `@mesh-tech/agent-sdk`'s `replay/history-io.ts` `historyToFixture` produces,
+ * so a captured file replays via `replayFixture` (which rehydrates it with
+ * `historyFromJSON`) for LOCAL debugging. Captured PRODUCTION histories are
+ * never committed (they contain real, decrypted customer/conversation data —
+ * see the CLI's do-not-commit warning); only synthetic goldens live in
+ * `packages/agent-sdk/src/replay/fixtures/`.
+ *
+ * We reuse `@temporalio/common`'s `historyToJSON` directly (the exact helper
+ * agent-sdk's history-io uses) rather than importing `@mesh-tech/agent-sdk`:
+ * the CLI has no reason to pull in the whole worker/replay stack, and keeping
+ * the dependency pointed at the shared Temporal library guarantees the output
+ * round-trips through `historyFromJSON`.
+ *
+ * The one thing a *real* history needs that a synthetic golden fixture doesn't:
+ * its payloads are ENCRYPTED (the worker's AES-GCM codec). `historyToJSON`
+ * would just base64 the ciphertext, which `replayFixture`'s plaintext converter
+ * can't decode. So before serializing we walk every Payload in the history and
+ * replace each encrypted one with its decrypted inner Payload — yielding a
+ * plaintext fixture identical in shape to a codec-free golden capture.
+ */
+// Explicit `.js` — this package publishes native ESM, so the compiled dist
+// must use a fully-specified specifier or Node throws ERR_MODULE_NOT_FOUND at
+// runtime (MESH-2262). tsx tolerates the extensionless form; node does not.
+import { historyToJSON } from "@temporalio/common/lib/proto-utils.js";
+function isPayload(value) {
+    return (value != null &&
+        typeof value === "object" &&
+        "metadata" in value &&
+        "data" in value);
+}
+/**
+ * Walk an arbitrary history-event tree and decrypt every encrypted Payload in
+ * place, using `decrypt` to turn an encrypted Payload into its plaintext inner
+ * Payload. Payloads the decrypter reports as non-encrypted (`null`) are left
+ * untouched. Returns the number of payloads that were decrypted.
+ *
+ * The `{ metadata, data }` heuristic mirrors Temporal's own `fixPayloads` in
+ * `@temporalio/common/lib/proto-utils`, so it identifies exactly the nodes
+ * proto3-JSON treats as payloads. Once a node is a Payload we do NOT recurse
+ * into it (its metadata values are bytes, not nested payloads).
+ */
+export async function decryptHistoryPayloads(node, decrypt) {
+    if (node == null || typeof node !== "object")
+        return 0;
+    if (isPayload(node)) {
+        const inner = await decrypt(node);
+        if (inner === null)
+            return 0; // not encrypted — leave as-is
+        // Replace the encrypted envelope with the decrypted inner payload's bytes.
+        node.metadata = inner.metadata ?? {};
+        node.data = inner.data ?? new Uint8Array(0);
+        return 1;
+    }
+    let count = 0;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            count += await decryptHistoryPayloads(item, decrypt);
+    }
+    else {
+        for (const value of Object.values(node)) {
+            count += await decryptHistoryPayloads(value, decrypt);
+        }
+    }
+    return count;
+}
+/**
+ * Turn an ordered list of raw history events into a replay fixture object.
+ *
+ * @param events - Raw proto-decoded history events, in order (as yielded by the
+ *   CLI's `iterHistoryEvents` over `getWorkflowExecutionHistory`).
+ * @param decrypter - Optional raw payload decrypter. When provided, every
+ *   encrypted payload in the history is decrypted in place before serialization
+ *   so the fixture is replayable with a plaintext converter. When omitted, the
+ *   payloads are serialized as-is (ciphertext, base64-encoded).
+ *
+ * `historyToJSON` runs its input through protobuf `History.fromObject`, so a
+ * plain `{ events }` object of raw events is accepted directly; it returns a
+ * proto3-JSON *string* which we parse back to a structured object (the same
+ * `JSON.parse(historyToJSON(...))` round-trip `historyToFixture` performs).
+ */
+export async function serializeHistoryToFixture(events, decrypter) {
+    let decryptedPayloads = 0;
+    if (decrypter) {
+        for (const event of events) {
+            decryptedPayloads += await decryptHistoryPayloads(event, decrypter);
+        }
+    }
+    const fixture = JSON.parse(historyToJSON({ events }));
+    return { fixture, eventCount: events.length, decryptedPayloads };
+}
+//# sourceMappingURL=capture-history.js.map

package/dist/src/utils/capture-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-history.js","sourceRoot":"","sources":["../../../src/utils/capture-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AActE,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,CACL,KAAK,IAAI,IAAI;QACb,OAAO,KAAK,KAAK,QAAQ;QACzB,UAAU,IAAI,KAAK;QACnB,MAAM,IAAI,KAAK,CAChB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAa,EACb,OAA4B;IAE5B,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IAEvD,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAkB,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC,CAAC,8BAA8B;QAC5D,2EAA2E;QAC3E,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5C,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,KAAK,IAAI,MAAM,sBAAsB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAA+B,CAAC,EAAE,CAAC;YACnE,KAAK,IAAI,MAAM,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAYD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAiB,EACjB,SAA+B;IAE/B,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,iBAAiB,IAAI,MAAM,sBAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,EAAW,CAAC,CAAY,CAAC;IAC1E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC;AACnE,CAAC"}

package/dist/src/utils/deploy-preflight.d.ts

@@ -0,0 +1,52 @@
+/** A `@mesh-tech/*` dep whose installed version differs from the lockfile's. */
+export interface DepMismatch {
+    name: string;
+    /** Version the lockfile says should be installed. */
+    expected: string;
+    /** Version actually resolvable in node_modules, or null if not installed. */
+    installed: string | null;
+}
+/** pulumi ops that EVALUATE the program (a stale install can produce a wrong plan). */
+export declare const PROGRAM_EVAL_OPS: Set<string>;
+/** Env escape hatch — set truthy to skip the preflight (e.g. deliberate local link testing). */
+export declare const SKIP_ENV = "MESH_SKIP_DEPLOY_PREFLIGHT";
+/**
+ * A lockfile `version:` is checkable only when it's a concrete published version.
+ * `link:…`/`file:…` (dev-link pnpmfile, local tarballs) point at live source and
+ * are never stale; anything not starting with a digit isn't a comparable version.
+ * Peer/patch suffixes (`1.0.1(react@18)`) are stripped to the bare version.
+ */
+export declare function normalizeLockVersion(raw: unknown): string | null;
+/**
+ * Pure: extract the gated (`@mesh-tech/*`), concretely-versioned deps for one
+ * importer of a parsed pnpm-lock document → `{ name: expectedVersion }`.
+ *
+ * Handles the pnpm v9 shape (`{ specifier, version }` per dep) and the older flat
+ * shape (`name: "1.0.1"`). Unknown importer → `{}` (nothing checkable).
+ */
+export declare function extractImporterMeshVersions(lockDoc: unknown, importerRel: string): Record<string, string>;
+/**
+ * Pure: diff the lockfile's expected versions against the installed ones. A dep
+ * is a mismatch when the installed version differs (or it isn't installed).
+ */
+export declare function diffLockVsInstalled(expected: Record<string, string>, installed: Record<string, string | null>): DepMismatch[];
+/** Walk up from `startDir` to the nearest directory containing a `pnpm-lock.yaml`. */
+export declare function findPnpmLock(startDir: string): string | null;
+/**
+ * Check that the `@mesh-tech/*` deps installed in `appRoot`'s `node_modules` match
+ * what the pnpm lockfile says. Returns the list of mismatches (empty = fresh), or
+ * `null` when the check does not apply (no lockfile — not a pnpm repo, or the
+ * monorepo running without one). IO wrapper around the pure helpers above.
+ */
+export declare function checkDeployDepsFresh(appRoot: string): DepMismatch[] | null;
+/** Human-readable stale-deps report (mirrors the stale-dist detector's style). */
+export declare function formatStaleDepsError(mismatches: DepMismatch[]): string;
+/**
+ * Gate a `mesh deploy` invocation: if `op` evaluates the pulumi program and the
+ * deploy repo's `node_modules` is stale vs the lockfile, print the fix and exit
+ * non-zero BEFORE pulumi runs. No-op for non-evaluating ops, a fresh install, a
+ * non-pnpm repo, or when the skip env is set. Kept side-effecting (log + exit) so
+ * `deploy.ts` stays a thin wiring layer; the decision logic is pure above.
+ */
+export declare function assertDeployDepsFresh(appRoot: string, op: string): void;
+//# sourceMappingURL=deploy-preflight.d.ts.map

package/dist/src/utils/deploy-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-preflight.d.ts","sourceRoot":"","sources":["../../../src/utils/deploy-preflight.ts"],"names":[],"mappings":"AAyBA,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,aAA6D,CAAC;AAE3F,gGAAgG;AAChG,eAAO,MAAM,QAAQ,+BAA+B,CAAC;AAMrD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIhE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GACvC,WAAW,EAAE,CAOf;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS5D;AAwBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,IAAI,CAqB1E;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,MAAM,CAqBtE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAOvE"}

package/dist/src/utils/deploy-preflight.js

@@ -0,0 +1,183 @@
+/**
+ * Deploy preflight — guard `mesh deploy` (pulumi up/preview/destroy/refresh) in a
+ * DEPLOY repo against a stale `node_modules` (MESH-2266).
+ *
+ * The hazard: a teammate pulls a `@mesh-tech/*` version bump (package.json +
+ * pnpm-lock.yaml move together in the commit) but forgets `pnpm install`, so
+ * `node_modules` still links the OLD version. The pulumi program then evaluates
+ * OLD component code and produces a plan that DELETES resources the new code would
+ * keep — the exact incident that showed `VpnJoinBroker` (+~40 resources) as a
+ * delete on mesh-dev when node_modules lagged the 1.0.1 bump. This is the same
+ * stale-artifact class as the monorepo stale-dist detector (MESH-2019) and the
+ * canonical CLI (MESH-2261), one layer up with higher stakes.
+ *
+ * The check is cheap and precise: compare each `@mesh-tech/*` version the LOCKFILE
+ * says should be installed against what is ACTUALLY installed in `node_modules`.
+ * A mismatch means `pnpm install` hasn't run since the lockfile changed. We only
+ * gate program-EVALUATING ops (a stale install can't corrupt `whoami`/`stack
+ * output`), and source-linked deps (`link:`/`file:`/dev-link pnpmfile) are skipped
+ * — they are intentionally pointed at live source and never "stale".
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { logWarn } from './log.js';
+/** Package-name prefixes whose version drift changes the pulumi plan. */
+const GATED_PREFIXES = ['@mesh-tech/'];
+/** pulumi ops that EVALUATE the program (a stale install can produce a wrong plan). */
+export const PROGRAM_EVAL_OPS = new Set(['up', 'preview', 'destroy', 'refresh', 'import']);
+/** Env escape hatch — set truthy to skip the preflight (e.g. deliberate local link testing). */
+export const SKIP_ENV = 'MESH_SKIP_DEPLOY_PREFLIGHT';
+function isGated(name) {
+    return GATED_PREFIXES.some((p) => name.startsWith(p));
+}
+/**
+ * A lockfile `version:` is checkable only when it's a concrete published version.
+ * `link:…`/`file:…` (dev-link pnpmfile, local tarballs) point at live source and
+ * are never stale; anything not starting with a digit isn't a comparable version.
+ * Peer/patch suffixes (`1.0.1(react@18)`) are stripped to the bare version.
+ */
+export function normalizeLockVersion(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const bare = raw.split('(')[0].trim();
+    return /^\d/.test(bare) ? bare : null;
+}
+/**
+ * Pure: extract the gated (`@mesh-tech/*`), concretely-versioned deps for one
+ * importer of a parsed pnpm-lock document → `{ name: expectedVersion }`.
+ *
+ * Handles the pnpm v9 shape (`{ specifier, version }` per dep) and the older flat
+ * shape (`name: "1.0.1"`). Unknown importer → `{}` (nothing checkable).
+ */
+export function extractImporterMeshVersions(lockDoc, importerRel) {
+    const out = {};
+    const importers = lockDoc?.importers;
+    const importer = importers?.[importerRel];
+    if (!importer)
+        return out;
+    for (const group of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const deps = importer[group];
+        if (!deps)
+            continue;
+        for (const [name, entry] of Object.entries(deps)) {
+            if (!isGated(name))
+                continue;
+            const raw = typeof entry === 'string' ? entry : entry?.version;
+            const version = normalizeLockVersion(raw);
+            if (version)
+                out[name] = version;
+        }
+    }
+    return out;
+}
+/**
+ * Pure: diff the lockfile's expected versions against the installed ones. A dep
+ * is a mismatch when the installed version differs (or it isn't installed).
+ */
+export function diffLockVsInstalled(expected, installed) {
+    const out = [];
+    for (const [name, exp] of Object.entries(expected)) {
+        const got = installed[name] ?? null;
+        if (got !== exp)
+            out.push({ name, expected: exp, installed: got });
+    }
+    return out;
+}
+/** Walk up from `startDir` to the nearest directory containing a `pnpm-lock.yaml`. */
+export function findPnpmLock(startDir) {
+    let dir = startDir;
+    for (;;) {
+        const candidate = join(dir, 'pnpm-lock.yaml');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Read the installed version of `name` from `fromDir`'s `node_modules`, or null.
+ *
+ * Reads `node_modules/<name>/package.json` DIRECTLY (following pnpm's symlink into
+ * the store) rather than `require.resolve(`${name}/package.json`)`: Node's exports
+ * gate throws `ERR_PACKAGE_PATH_NOT_EXPORTED` for the many `@mesh-tech/*` packages
+ * whose `exports` omit `./package.json` (e.g. `tsconfig`, `pulumi-utils`) — which
+ * would return null → a FALSE "stale" hard-stop on a correctly-installed repo that
+ * `pnpm install` can't clear. A plain read sidesteps the gate and stays scoped to
+ * THIS importer's node_modules instead of walking up to a hoisted copy owned by
+ * another importer (MESH-2266 review).
+ */
+function readInstalledVersion(fromDir, name) {
+    try {
+        const pkgPath = join(fromDir, 'node_modules', name, 'package.json');
+        const version = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+        return typeof version === 'string' ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check that the `@mesh-tech/*` deps installed in `appRoot`'s `node_modules` match
+ * what the pnpm lockfile says. Returns the list of mismatches (empty = fresh), or
+ * `null` when the check does not apply (no lockfile — not a pnpm repo, or the
+ * monorepo running without one). IO wrapper around the pure helpers above.
+ */
+export function checkDeployDepsFresh(appRoot) {
+    const lockPath = findPnpmLock(appRoot);
+    if (!lockPath)
+        return null;
+    let lockDoc;
+    try {
+        lockDoc = parseYaml(readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        // Don't block the deploy on our own parse failure — but a silently-disabled
+        // safety guard is worse than a noisy one, so surface that the check is off.
+        logWarn(`deploy preflight: could not parse ${lockPath} — skipping the stale-node_modules check.`);
+        return null;
+    }
+    const importerRel = relative(dirname(lockPath), appRoot) || '.';
+    const expected = extractImporterMeshVersions(lockDoc, importerRel);
+    const names = Object.keys(expected);
+    if (names.length === 0)
+        return [];
+    const installed = {};
+    for (const name of names)
+        installed[name] = readInstalledVersion(appRoot, name);
+    return diffLockVsInstalled(expected, installed);
+}
+/** Human-readable stale-deps report (mirrors the stale-dist detector's style). */
+export function formatStaleDepsError(mismatches) {
+    const lines = [
+        `✗ ${mismatches.length} @mesh-tech/* dep${mismatches.length === 1 ? '' : 's'} in node_modules ` +
+            `do not match the lockfile — run pnpm install before deploying:`,
+        '',
+    ];
+    for (const m of mismatches) {
+        lines.push(`  • ${m.name} — installed ${m.installed ?? '(missing)'}, lockfile wants ${m.expected}`);
+    }
+    lines.push('', '  A stale node_modules makes pulumi evaluate OLD component code and can plan to', '  DELETE resources the current code would keep (MESH-2266). Fix:', '', '      pnpm install', '', `  To bypass this check (rarely correct): ${SKIP_ENV}=1 mesh deploy …`);
+    return lines.join('\n');
+}
+/**
+ * Gate a `mesh deploy` invocation: if `op` evaluates the pulumi program and the
+ * deploy repo's `node_modules` is stale vs the lockfile, print the fix and exit
+ * non-zero BEFORE pulumi runs. No-op for non-evaluating ops, a fresh install, a
+ * non-pnpm repo, or when the skip env is set. Kept side-effecting (log + exit) so
+ * `deploy.ts` stays a thin wiring layer; the decision logic is pure above.
+ */
+export function assertDeployDepsFresh(appRoot, op) {
+    if (!PROGRAM_EVAL_OPS.has(op))
+        return;
+    if (process.env[SKIP_ENV])
+        return;
+    const mismatches = checkDeployDepsFresh(appRoot);
+    if (!mismatches || mismatches.length === 0)
+        return;
+    process.stderr.write(formatStaleDepsError(mismatches) + '\n');
+    process.exit(1);
+}
+//# sourceMappingURL=deploy-preflight.js.map

package/dist/src/utils/deploy-preflight.js.map

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

package/dist/src/utils/errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared CLI error type with structured remediation.
+ *
+ * Every failure along the golden path should tell the user the exact `mesh`
+ * command (or doc) that fixes it. Remediation strings must be commands or
+ * docs — never "ask <person>".
+ */
+export interface Remediation {
+    /** Exact command that fixes the failure, e.g. "mesh login trabian-dev" */
+    command?: string;
+    /** Documentation URL or repo-relative doc path with more context */
+    docs?: string;
+    /** Whether the owning command can apply this fix itself via --fix */
+    autoFixable?: boolean;
+}
+export interface MeshCliErrorOptions {
+    remediation?: Remediation;
+    /** Process exit code (default 1) */
+    exitCode?: number;
+    cause?: unknown;
+}
+export declare class MeshCliError extends Error {
+    readonly remediation?: Remediation;
+    readonly exitCode: number;
+    constructor(message: string, options?: MeshCliErrorOptions);
+}
+/**
+ * Render an error's BODY — the message plus its "→ run: <command>" /
+ * "→ see: <docs>" remediation lines, with no leading severity glyph.
+ *
+ * Use this when the caller supplies its own glyph: a recovery path that logs a
+ * refusal through `logWarn` (which prefixes ⚠) and carries on would otherwise
+ * print "⚠ ✗ …". The remediation lines are the part that must survive — they
+ * name the corrupt file to delete.
+ */
+export declare function renderErrorBody(err: unknown): string;
+/**
+ * Render an error for humans. MeshCliError gets its remediation appended as
+ * "→ run: <command>" / "→ see: <docs>" lines; anything else renders its message.
+ */
+export declare function renderError(err: unknown): string;
+/**
+ * Render an error as JSON for agents. Same structure as the human output:
+ * { error, remediation?: { command?, docs?, autoFixable? } }.
+ */
+export declare function renderErrorJson(err: unknown): string;
+/**
+ * Print a command's `--json` payload — the single machine-readable document on
+ * stdout — and record that it happened.
+ *
+ * A command that emits a payload and *then* throws (the `mesh init` doctor
+ * throws by design whenever a check fails) used to produce TWO concatenated
+ * JSON documents on stdout, because `handleCliError` appended `{"error":…}`.
+ * Two documents is not JSON: `mesh init app-tenant --json | jq` failed to parse
+ * on exactly the failure path a script cares about. Routing every payload
+ * through here lets the handler know stdout is already spoken for.
+ */
+export declare function emitJsonPayload(payload: unknown): void;
+/** True once a command has written its `--json` payload to stdout. */
+export declare function hasEmittedJsonPayload(): boolean;
+/** Test seam — the flag is module state, so specs have to be able to clear it. */
+export declare function resetJsonPayloadEmitted(): void;
+/**
+ * Top-level handler for bin/mesh.ts. Prints the error (JSON when the
+ * invocation asked for --json anywhere, since per-command flags aren't
+ * parsed once dispatch has failed) and exits with the error's code.
+ *
+ * When the command already emitted a `--json` payload, that payload IS the
+ * machine surface — and it says strictly more than this error would (the
+ * doctor's payload carries `ok:false` plus a per-check `fix` command). So the
+ * error goes to stderr as human diagnostics and stdout keeps exactly one
+ * parseable document.
+ */
+export declare function handleCliError(err: unknown): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;CAM/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAWpD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQpD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGtD;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAQlD"}