@mesh-tech/mesh-cli 0.20.1 → 0.20.3

package/dist/src/commands/local/hub-local.js

@@ -1,14 +1,3 @@
-/**
- * Local Hub image builder (`mesh start --with-hub`) — the interim path
- * until the hub pipeline publishes pullable container images (design §11).
- *
- * Resolves the published @mesh-tech/hub tarball with the user's registry
- * auth (mesh registry login), extracts it, and docker-builds two images
- * from the prebuilt dists it ships (api/dist → mesh-local-hub-api,
- * ui/build → mesh-local-hub-ui). The CodeArtifact token enters the build
- * as a BuildKit secret and never lands in a layer. Idempotent: images are
- * keyed by the package version and rebuilt only when missing.
- */
 import { execFile, execFileSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
@@ -22,8 +11,6 @@ import { meshCacheDir } from "../../utils/cache-home.js";
 const execFileAsync = promisify(execFile);
 const HUB_PACKAGE = "@mesh-tech/hub";
 export const HUB_IMAGES = ["mesh-local-hub-api", "mesh-local-hub-ui"];
-/** Bump when stack/hub/Dockerfile.* change — forces a rebuild of images
- * already cached for the same published hub version. */
 const LOCAL_IMAGE_REV = "r2";
 function cacheDir() {
     return meshCacheDir("hub-local");
@@ -44,12 +31,7 @@ function imageExists(tag) {
         return false;
     }
 }
-/** Tag referenced by docker-compose.hub.yml — bump alongside Dockerfile.auth. */
 const HUB_AUTH_IMAGE = "mesh-local-hub-auth:v7.7.1-r1";
-/**
- * Build the Hub's oauth2-proxy image (hosted sidecar + loopback issuer
- * forward). Public base images only — no registry auth involved.
- */
 export function ensureHubAuthImage() {
     if (imageExists(HUB_AUTH_IMAGE))
         return;
@@ -58,16 +40,10 @@ export function ensureHubAuthImage() {
     execFileSync("docker", ["build", "-f", path.join(hubStackDir, "Dockerfile.auth"), "-t", HUB_AUTH_IMAGE, hubStackDir], { stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, DOCKER_BUILDKIT: "1" } });
     logSuccess(`Built ${HUB_AUTH_IMAGE}`);
 }
-/** Registry auth present? (Needed only to BUILD hub images, not to run them.) */
 export function hasRegistryAuth() {
     const p = path.join(os.homedir(), ".npmrc");
     return fs.existsSync(p) && fs.readFileSync(p, "utf-8").includes("codeartifact");
 }
-/**
- * Newest hub version whose images already exist locally — lets `mesh start`
- * include the Hub by default with no network and no registry auth. Returns
- * undefined when no built images are present.
- */
 export function localHubVersion() {
     const versions = HUB_IMAGES.map((name) => {
         try {
@@ -84,13 +60,8 @@ export function localHubVersion() {
     const shared = versions[0].filter((v) => v.endsWith(`-${LOCAL_IMAGE_REV}`) && versions.every((list) => list.includes(v)));
     if (shared.length === 0)
         return undefined;
-    // Highest semver wins (numeric-aware compare handles the -rN suffix).
     return shared.sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).at(-1);
 }
-/** `npm pack` the published hub tarball into the cache; returns its path +
- * version. Falls back to the newest cached tarball when the registry is
- * unreachable (offline / expired token). Async so the heartbeat can fill
- * silence during the fetch — a first run's slowest, quietest step. */
 async function fetchTarball() {
     const dir = cacheDir();
     logInfo(`Resolving ${HUB_PACKAGE} from the registry…`);
@@ -108,8 +79,6 @@ async function fetchTarball() {
             .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
             .at(-1);
         if (!cached) {
-            // Map npm's E401 ("try npm login") to the Mesh fix — npm login can
-            // never mint a CodeArtifact token (MESH-2479).
             if (authFailure) {
                 throw new MeshCliError(`The registry rejected the ${HUB_PACKAGE} tarball fetch (E401 Unauthorized) — your CodeArtifact token is expired or invalid. (npm's "try npm login" advice does not apply to this registry.)`, { remediation: { command: REGISTRY_LOGIN_FIX }, cause: err });
             }
@@ -128,13 +97,6 @@ async function fetchTarball() {
         heartbeat.stop();
     }
 }
-/**
- * Pure: decide what `mesh start --with-hub` does given the registry probe
- * and any already-built local images. Only a *refresh* needs the registry —
- * already-built images run without it, so an expired/missing token degrades
- * to those (with the fixing command) instead of hard-failing a path that
- * works offline (MESH-2479).
- */
 export function planWithHubRefresh(probeState, builtVersion) {
     if (probeState !== "expired" && probeState !== "missing")
         return { action: "refresh" };
@@ -154,10 +116,6 @@ export function planWithHubRefresh(probeState, builtVersion) {
         remediation: REGISTRY_LOGIN_FIX,
     };
 }
-/**
- * Ensure the two local hub images exist; build them from the tarball when
- * missing. Returns the hub version (used as the compose image tag).
- */
 export async function ensureHubImages() {
     const npmrc = npmrcPath();
     const { tarball, version: packageVersion } = await fetchTarball();
@@ -193,32 +151,12 @@ export async function ensureHubImages() {
     }
     return version;
 }
-// ── the Hub's compiled authz catalog ─────────────────────────────────────────
-/** Where the packed Hub ships its compiled authz catalog (`compile-authz.ts`). */
 export const HUB_COMPILED_AUTHZ_REL = "api/dist/authz/compiled.json";
-/**
- * The cached tarball a local image version was built from, or null for a
- * from-source build (`<version>-src`), which never has one.
- *
- * @example
- * ```typescript
- * tarballNameForImageVersion("2.2.0-r2"); // => "mesh-tech-hub-2.2.0.tgz"
- * tarballNameForImageVersion("2.2.0-src"); // => null
- * ```
- */
 export function tarballNameForImageVersion(version) {
     if (version.endsWith("-src"))
         return null;
     return `mesh-tech-hub-${version.replace(/-r\d+$/, "")}.tgz`;
 }
-/**
- * Read the compiled authz catalog of the Hub whose images `mesh start` runs.
- *
- * The staged build context (`context-<version>/`) carries it after a build; when
- * the images already existed nothing was staged, so the one file is extracted
- * from the cached tarball on demand. Returns null for a Hub that ships no
- * catalog (published before 2.1.0) — the caller says so and moves on.
- */
 export function readHubCompiledAuthz(version) {
     const context = path.join(cacheDir(), `context-${version}`);
     const file = path.join(context, HUB_COMPILED_AUTHZ_REL);
@@ -241,15 +179,6 @@ export function readHubCompiledAuthz(version) {
         return null;
     return { zed: parsed.zed, metadata: parsed.metadata };
 }
-// ── from-source build (`mesh start --hub-from-source`) ──────────────────────
-/**
- * The workspace's default pnpm catalog, as `{ dependency: range }`.
- *
- * Nested manifests inside the packed Hub (`api/package.json`, `ui/package.json`)
- * reference shared versions as `catalog:`. pnpm resolves that on publish for the
- * package's OWN manifest only — the nested ones ship the literal `catalog:`, and
- * `npm install` inside the image rejects it with `EUNSUPPORTEDPROTOCOL`.
- */
 export function readWorkspaceCatalog(repoRoot) {
     const text = fs.readFileSync(path.join(repoRoot, "pnpm-workspace.yaml"), "utf-8");
     const marker = "\ncatalog:\n";
@@ -258,7 +187,6 @@ export function readWorkspaceCatalog(repoRoot) {
         return {};
     const catalog = {};
     for (const line of text.slice(at + marker.length).split("\n")) {
-        // The block ends at the first line that is neither indented nor blank.
         if (line.trim() !== "" && !/^\s/.test(line))
             break;
         const m = /^\s+"?([^":\s]+)"?:\s*"?([^"\s#]+)"?/.exec(line);
@@ -267,28 +195,6 @@ export function readWorkspaceCatalog(repoRoot) {
     }
     return catalog;
 }
-/**
- * Make an extracted Hub tarball installable by plain `npm` inside the image.
- *
- * Two rewrites, both on the NESTED manifests the Dockerfiles copy:
- *
- *  - `catalog:` → the range the workspace catalog pins.
- *  - `workspace:*` dependencies are DROPPED. Every deployed Hub entrypoint is
- *    bundled by `esm-bundle`, so no `@mesh-tech/*`
- *    or `@libs/*` import survives into `api/dist` / `ui/build` — installing them
- *    would fetch PUBLISHED copies that nothing imports, and for a package being
- *    changed in this checkout that published copy is precisely the wrong code.
- *  - `devDependencies` are DROPPED wholesale. Both Dockerfiles install with
- *    `--omit=dev`, so nothing in the image ever needs them — but npm still
- *    resolves them into the ideal tree before omitting, and the Hub's dev set
- *    (vitest, tsx, the React Router toolchain) trips a peer-conflict crash in
- *    the image's npm 10 (`Cannot read properties of null (reading 'edgesOut')`
- *    in arborist's `#loadPeerSet`) that fails the build before a single layer
- *    is written. Reproduced on the normalized `api/package.json` alone; the
- *    same manifest installs clean without the block.
- *
- * Returns the manifests it touched, for the caller to log.
- */
 export function normalizeHubManifests(contextDir, catalog) {
     const DEP_FIELDS = ["dependencies", "optionalDependencies", "peerDependencies"];
     const touched = [];
@@ -333,19 +239,6 @@ export function normalizeHubManifests(contextDir, catalog) {
     }
     return touched;
 }
-/**
- * Build the local Hub images from THIS checkout instead of the registry.
- *
- * `mesh start`'s Hub normally comes from the published `@mesh-tech/hub` tarball,
- * which makes it the one environment where a Hub change cannot be exercised
- * before it ships. This packs `apps/hub` exactly as a release would — same
- * `files` allowlist, same Dockerfiles — so the containerized Hub, its auth proxy
- * and its login flow all stay identical; only the code inside changes.
- *
- * Images are tagged `<version>-src` so they can never be mistaken for, or reused
- * as, a published build, and are rebuilt every call: the whole point is to pick
- * up working-tree changes.
- */
 export async function buildHubImagesFromSource(repoRoot) {
     const hubDir = path.join(repoRoot, "apps", "hub");
     if (!fs.existsSync(path.join(hubDir, "package.json"))) {
@@ -365,9 +258,6 @@ export async function buildHubImagesFromSource(repoRoot) {
     const context = path.join(cacheDir(), `context-${version}`);
     fs.rmSync(context, { recursive: true, force: true });
     fs.mkdirSync(context, { recursive: true });
-    // `pnpm pack` applies the package's own `files` allowlist, so the context is
-    // byte-for-byte what a release would ship — not a hand-assembled copy that
-    // could omit something the published path includes.
     await execFileAsync("pnpm", ["pack", "--pack-destination", context], { cwd: hubDir, maxBuffer: 64 * 1024 * 1024 });
     const tarball = fs.readdirSync(context).find((f) => f.endsWith(".tgz"));
     if (!tarball)
@@ -390,4 +280,3 @@ export async function buildHubImagesFromSource(repoRoot) {
     }
     return version;
 }
-//# sourceMappingURL=hub-local.js.map

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

@@ -1,18 +1,5 @@
-/**
- * mesh start / stop / status — the full-local Mesh platform.
- *
- * mesh start [--no-seed]   Bring up the local platform (docker compose) and
- *                          seed tenant `local` / env `dev` on first boot.
- * mesh stop [--destroy]    Stop the stack; --destroy also removes volumes
- *                          (resets databases and seeds).
- * mesh status [--json]     Per-service health, endpoints, and ports.
- *
- * Everything here works with zero AWS credentials, zero VPN, and zero Pulumi
- * state — Docker is the only prerequisite.
- */
 import { Command } from "commander";
 import { type ServiceStatus, type StackEndpoint } from "./stack.js";
-/** Injectable seams so tests can drive the wait loop without Docker. */
 export interface WaitForStackIo {
     probe: (endpoint: StackEndpoint) => Promise<boolean>;
     services: () => ServiceStatus[];
@@ -20,4 +7,3 @@ export interface WaitForStackIo {
 }
 export declare function waitForStack(io?: WaitForStackIo): Promise<void>;
 export declare function registerLocalCommands(program: Command): void;
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,15 +1,3 @@
-/**
- * mesh start / stop / status — the full-local Mesh platform.
- *
- * mesh start [--no-seed]   Bring up the local platform (docker compose) and
- *                          seed tenant `local` / env `dev` on first boot.
- * mesh stop [--destroy]    Stop the stack; --destroy also removes volumes
- *                          (resets databases and seeds).
- * mesh status [--json]     Per-service health, endpoints, and ports.
- *
- * Everything here works with zero AWS credentials, zero VPN, and zero Pulumi
- * state — Docker is the only prerequisite.
- */
 import * as fs from "fs";
 import * as path from "path";
 import chalk from "chalk";
@@ -24,7 +12,6 @@ import { LOGIN_CONTEXT, readHubAuth, seedZitadel, TEST_USERS } from "./seed-zita
 import { publishHubAuthzCatalog } from "./seed-hub-catalog.js";
 const WAIT_TIMEOUT_MS = 180_000;
 const WAIT_POLL_MS = 3_000;
-/** The one crash message, so both wait loops stay on the same remediation. */
 function crashError(crashed) {
     return new MeshCliError(`Service(s) exited during startup: ${crashed.map((s) => s.name).join(", ")}`, {
         remediation: {
@@ -51,13 +38,6 @@ export async function waitForStack(io = {
             }
         }
         pending = stillDown;
-        // Surface hard failures on EVERY round, including the one that would end
-        // the wait: not every container has a STACK_ENDPOINTS entry, so with all
-        // probes answering first try an endpoint-less service (blackbox-exporter,
-        // temporal-admin-tools) could exit during startup unseen.
-        // The Hub overlay has not been brought up yet (that happens after the
-        // seed, below), so its containers are excluded — an `exited` hub-api
-        // here is a leftover from a previous run, not this run's crash.
         const crashed = crashedServices(io.services(), {
             overlayServices: io.overlayServices(),
             overlayStarted: false,
@@ -76,8 +56,6 @@ export async function waitForStack(io = {
 function printEndpoints(hubRunning) {
     console.log("");
     if (hubRunning) {
-        // The Hub is the front door — the same operations dashboard customers
-        // use against the hosted platform. Everything else is plumbing.
         console.log(chalk.bold.cyan("★ Mesh Hub — your operations dashboard (start here)"));
         console.log(`  ${"Hub UI".padEnd(34)} ${chalk.bold.cyan(`http://localhost:${hubPort()}`)}`);
         console.log(`  ${"".padEnd(34)} ${chalk.dim("sign in: admin@local.mesh or dev@local.mesh / LocalDev1!")}`);
@@ -110,15 +88,6 @@ function printEndpoints(hubRunning) {
     console.log("");
     logInfo("Next: `mesh dev` in an apps repo wires services to this stack automatically.");
 }
-/**
- * The mesh-platform checkout `--hub-from-source` builds from.
- *
- * The cwd wins when it sits inside a checkout, so running `mesh start` from an
- * app directory of the monorepo still builds that monorepo's Hub. Otherwise the
- * CLI's own location decides, which resolves correctly for `pnpm exec mesh` in a
- * worktree and lands somewhere without `apps/hub` for a global install — where
- * the builder refuses with a message naming the requirement.
- */
 function repoRootForHubSource() {
     for (let dir = process.cwd();;) {
         if (fs.existsSync(path.join(dir, "apps", "hub", "package.json")))
@@ -141,12 +110,6 @@ export function registerLocalCommands(program) {
         .option("--takeover", "re-own a stack that another checkout started (may recreate shared containers with THIS checkout's config)", false)
         .action(async (opts) => {
         ensureDockerAvailable();
-        // The stack is machine-wide; a `start` from a checkout whose compose
-        // config differs recreates shared containers out from under whatever
-        // is running against them (another project's `mesh dev` session, a
-        // Hub under development, …). Tenant/app work never needs `start`
-        // against an already-running stack — `mesh dev --local` deploys
-        // tenant-scoped only.
         const foreign = stackOwnedElsewhere();
         if (foreign && !opts.takeover) {
             throw new MeshCliError(`The local platform is already running, started from a different checkout:\n  ${foreign}\n` +
@@ -160,23 +123,12 @@ export function registerLocalCommands(program) {
         if (foreign && opts.takeover) {
             logWarn(`Taking over the running stack (previously driven from ${foreign}).`);
         }
-        // The Hub is the platform's front door, so it's part of the default
-        // stack: use already-built images when present; build from the
-        // published tarball when registry auth allows; otherwise start
-        // without it and say exactly how to enable it. --with-hub forces a
-        // registry resolve (picks up newly published hub versions).
         let hubVersion;
         if (opts.hub) {
             if (opts.hubFromSource) {
-                // Deliberately ahead of the registry arms: from-source never consults
-                // CodeArtifact for the Hub itself, so a stale token is irrelevant here.
                 hubVersion = await buildHubImagesFromSource(repoRootForHubSource());
             }
             else if (opts.withHub) {
-                // Auth preflight (MESH-2479): the tarball fetch + image build run
-                // for minutes — verify the CodeArtifact token BEFORE that work.
-                // Only a refresh needs the registry: with already-built images a
-                // bad token degrades to them instead of failing an offline path.
                 const probe = await probeRegistryToken();
                 const plan = planWithHubRefresh(probe.state, localHubVersion());
                 if (plan.action === "fail") {
@@ -195,8 +147,6 @@ export function registerLocalCommands(program) {
                 if (!hubVersion && hasRegistryAuth()) {
                     const probe = await probeRegistryToken();
                     if (probe.state === "expired") {
-                        // Keep `mesh start`'s Docker-only promise: degrade to a
-                        // hub-less stack, but say exactly how to get the Hub back.
                         logWarn(`CodeArtifact token is expired — starting without the Hub. Fix: ${REGISTRY_LOGIN_FIX}, then: mesh start --with-hub`);
                     }
                     else {
@@ -211,16 +161,7 @@ export function registerLocalCommands(program) {
             }
         }
         logInfo("Starting the local Mesh platform (docker compose project: mesh-local)…");
-        // Base stack first; the Hub joins AFTER seeding so its oauth2-proxy
-        // gets the seeded client credentials and hub-api never caches a
-        // pre-seed (empty) registry view.
         await composeStreamed(["up", "-d"]);
-        // Deterministic cache bust for the bind-mounted observability configs:
-        // `up -d` only recreates a container whose compose spec changed, and
-        // Prometheus re-reads prometheus.yml on restart/SIGHUP only. A CLI
-        // upgrade that edits observability/*.yml would otherwise leave a
-        // running stack on the OLD scrape config (and blackbox on old modules)
-        // — silently, since a misrouted probe just reports probe_success 0.
         compose(["restart", "prometheus", "blackbox-exporter"], { inherit: true });
         await waitForStack();
         let hubAuth = readHubAuth();
@@ -230,9 +171,6 @@ export function registerLocalCommands(program) {
             logInfo("Seeding Zitadel (Platform project, Mesh CLI app, Hub auth, test users)…");
             const zitadel = await seedZitadel(LOCAL_AWS_CONFIG);
             hubAuth = zitadel.hubAuth;
-            // The Hub's role catalog: what Users → Roles / Permissions render and what
-            // the create-user form offers. The hosted platform publishes it from
-            // MeshHub; locally it comes from the catalog the Hub images were built with.
             if (hubVersion) {
                 const compiled = readHubCompiledAuthz(hubVersion);
                 if (compiled) {
@@ -243,9 +181,6 @@ export function registerLocalCommands(program) {
                     logWarn(`Hub v${hubVersion} ships no compiled role catalog (api/dist/authz/compiled.json) — Users → Roles will be empty. Hub ≥ 2.1.0 publishes one.`);
                 }
             }
-            // Zitadel is the auth source of truth — mirror every provisioned
-            // app tenant/app into the registry so the Hub shows them even if
-            // the app hasn't been run since it was provisioned.
             try {
                 const reconciled = await reconcileRegistryFromZitadel();
                 if (reconciled.tenants.length > 0) {
@@ -265,10 +200,6 @@ export function registerLocalCommands(program) {
             if (!hubAuth) {
                 logWarn("Hub auth is not seeded yet (started with --no-seed?) — Hub sign-in needs one seeded run: mesh start");
             }
-            // The redirect URI for a non-default port is registered during
-            // seeding (reconcileHubRedirectUris) — skipping the seed with a new
-            // port reproduces the "redirect_uri is missing in the client
-            // configuration" login failure.
             if (!opts.seed && hubPort() !== DEFAULT_HUB_PORT) {
                 logWarn(`--no-seed with MESH_HUB_PORT=${hubPort()}: this port's redirect URI is registered during seeding — if Hub sign-in fails with "redirect_uri is missing in the client configuration", re-run without --no-seed.`);
             }
@@ -281,14 +212,8 @@ export function registerLocalCommands(program) {
             }
             await composeStreamed(["up", "-d"], { hub: true, env: hubEnv });
             if (opts.seed) {
-                // Deterministic cache bust: hub-api holds its tenants view for 5
-                // minutes and this run's seed/reconcile may have changed it.
                 compose(["restart", "hub-api"], { hub: true, env: hubEnv });
             }
-            // From here the overlay HAS been started, so an exited hub service is
-            // a real crash again — same message, same remediation as the base
-            // stack's. (Without this the loop would spin out its 60 attempts and
-            // then claim the endpoint was up.)
             const overlayServices = hubOverlayServices();
             for (const endpoint of hubEndpoints()) {
                 logInfo(`Waiting for ${endpoint.label}…`);
@@ -349,17 +274,9 @@ export function registerLocalCommands(program) {
                 remediation: { command: "mesh start" },
             });
         }
-        // `status` never started anything, so "is the Hub overlay part of this
-        // run?" can only be read off the containers: at least one overlay
-        // service actually running. Everything Hub-related keys off that — an
-        // overlay container left `exited` by a previous run (a Docker restart,
-        // a laptop sleep) is "not started", not "crashed".
         const overlayServices = hubOverlayServices();
         const overlayStarted = hubOverlayRunning(services, overlayServices);
         const notStarted = (s) => !overlayStarted && overlayServices.has(s.name) && s.state === "exited";
-        // A *running* hub-api, not merely a hub-api container: a leftover
-        // exited one from a previous run would otherwise make status probe Hub
-        // endpoints that were never meant to be up and report them down.
         const hasHub = hubApiRunning(services);
         const endpoints = hasHub ? [...STACK_ENDPOINTS, ...hubEndpoints()] : STACK_ENDPOINTS;
         const probes = await Promise.all(endpoints.map(async (endpoint) => ({
@@ -368,8 +285,6 @@ export function registerLocalCommands(program) {
             url: endpoint.url,
             up: await probeEndpoint(endpoint),
         })));
-        // The P0 gate: with the fabric up, the 8 KB Advanced-tier round-trip
-        // must pass on every status check, not just at seed time.
         let fabric = null;
         if (probes.find((p) => p.service === "ministack")?.up) {
             try {
@@ -425,4 +340,3 @@ export function registerLocalCommands(program) {
         }
     });
 }
-//# sourceMappingURL=index.js.map