@mesh-tech/mesh-cli 0.20.1 → 0.20.3

package/dist/src/utils/registry-identity.d.ts

@@ -1,109 +1,29 @@
-/**
- * The ONE identity behind `@mesh-tech` package access.
- *
- * Every reader of the registry — `pnpm install`, `mesh create-app`,
- * `mesh docs start`, the Hub image build under `mesh start` — talks to the same
- * CodeArtifact domain, and that domain is owned by exactly one Mesh platform:
- * `dev.platform.meshtech.io`. So the registry has a single, global identity
- * (issuer + CLI client id + broker URL) that never depends on which tenant
- * platform, if any, the developer deploys to.
- *
- * This module keeps that identity separate from platform contexts:
- *
- * - The domain comes from the compiled-in first-party alias table and nowhere
- *   else — not an argument, not an environment variable, not an unpinned
- *   config value. That is the same trust anchor `mesh login` relies on, so the
- *   ≥2-dot anti-phishing guard stays intact.
- * - The Zitadel session for the registry is cached under a **reserved**
- *   credential key (`registry`) that no `<tenant>.<env>` context can collide
- *   with, and `mesh login` / `mesh logout` refuse it.
- * - A developer who already signed in to the registry's own platform
- *   (`mesh login mesh.dev`) is reused rather than sent through the browser a
- *   second time: any cached session whose issuer matches the registry's counts.
- *
- * Nothing here touches `~/.npmrc` or the broker — that is `mesh registry
- * login`'s job. This module only answers "who is the registry?" and "do I hold
- * a session for it?".
- */
 import { MeshCliError } from "./errors.js";
-/**
- * The first-party alias of the platform that owns the `@mesh-tech` registry.
- * The alias is the key in `FIRST_PARTY_CONTEXTS`; the domain is looked up
- * from that reviewed table, never typed here twice.
- */
 export declare const REGISTRY_ALIAS = "mesh.dev";
-/** The pinned domain anonymous discovery runs against, e.g. `dev.platform.meshtech.io`. */
 export declare const REGISTRY_DOMAIN: string;
-/**
- * The reserved context name the registry session and identity are cached under
- * in `credentials.json` / `config.json`. Deliberately has no dot, so it can
- * never parse as a `<tenant>.<env>` platform context.
- */
 export declare const REGISTRY_CREDENTIAL_KEY: string;
-/** True when a context name is the reserved registry key. */
 export declare function isReservedRegistryContext(context: string): boolean;
-/** What the registry's platform publishes about itself, plus when we fetched it. */
 export interface RegistryIdentity {
-    /** Zitadel issuer URL for the registry's platform. */
     issuer: string;
-    /** The CLI's OIDC client id on that issuer. */
     clientId: string;
-    /** The `registry-auth` broker that exchanges an id token for a CodeArtifact grant. */
     registryBroker: string;
-    /** ISO timestamp of the discovery that produced this record. */
     discoveredAt: string;
 }
-/** Raised when the registry's identity cannot be resolved (offline, endpoint down). */
 export declare class RegistryIdentityError extends MeshCliError {
     constructor(detail: string);
 }
-/**
- * Resolve the registry's identity: the cached record under the reserved key,
- * or a fresh anonymous HTTPS discovery on the pinned domain which is then
- * cached there. `refresh: true` skips the cache.
- *
- * Never consults SSM and never takes the domain from anything but the alias
- * table. Throws `RegistryIdentityError` when discovery is impossible and
- * nothing is cached.
- *
- * @example
- * const { registryBroker } = await resolveRegistryIdentity();
- * // → "https://registry-auth.dev.platform.meshtech.io"
- */
 export declare function resolveRegistryIdentity(opts?: {
     refresh?: boolean;
 }): Promise<RegistryIdentity>;
-/**
- * The cached contexts whose session can stand in for the registry's: the
- * reserved key first, then the registry's own alias and domain — but only
- * when the cached config for that name points at the SAME issuer, so a
- * pre-repoint `mesh.dev` entry (a different platform) is never mistaken for
- * the registry. With no known issuer (nothing discovered yet) only the
- * reserved key counts: a guess about which platform session "is" the
- * registry is the mistake this function exists to prevent.
- *
- * Pure over the two files' contents; exported for tests.
- */
 export declare function registrySessionCandidates(issuer: string | null, configs?: Record<string, {
     issuer?: string;
 } | undefined>, credentials?: Record<string, unknown>): string[];
-/** A live registry session and the context key it is cached under. */
 export interface RegistrySession {
-    /** Which `credentials.json` entry holds the session (reserved key, alias, or domain). */
     context: string;
     email: string;
     expiresAt: string;
 }
-/**
- * The registry session as cached right now — no refresh, no network. Null when
- * no candidate context holds an unexpired token.
- *
- * @example
- * const s = readRegistrySession();
- * if (s) console.log(`signed in as ${s.email}`);
- */
 export declare function readRegistrySession(): RegistrySession | null;
-/** Why `ensureRegistrySession` could not produce a session. */
 export type RegistrySessionFailure = {
     ok: false;
     reason: "no-identity";
@@ -120,86 +40,17 @@ export type RegistrySessionFailure = {
 export type RegistrySessionResult = ({
     ok: true;
 } & RegistrySession) | RegistrySessionFailure;
-/**
- * Get a valid Zitadel session for the registry's issuer, signing in when
- * there is none.
- *
- * Reuses ANY cached session whose issuer matches — a developer already signed
- * in to `mesh.dev` gets no second browser trip — refreshing an expired one
- * through its refresh token first. Only when no candidate can be refreshed
- * does it run the sign-in (browser PKCE, or device code with `device: true`
- * or in a remote/non-TTY environment) and store the result under the
- * reserved key.
- *
- * `interactive: false` means "cached or nothing": callers that cannot open a
- * browser or print a device code get `no-tty` back instead of a hung prompt.
- *
- * @example
- * const session = await ensureRegistrySession({ interactive: true });
- * if (session.ok) console.log(session.email);
- */
 export declare function ensureRegistrySession(opts: {
     device?: boolean;
     interactive: boolean;
 }): Promise<RegistrySessionResult>;
-/**
- * The Zitadel project-role names a session token carries, sorted.
- *
- * Empty for a token with no roles claim and for anything that does not parse
- * as a JWT — a caller comparing two of these treats "unreadable" as "no roles
- * to compare", which is the safe reading for a token the broker will refuse
- * anyway.
- *
- * @example
- * registryTokenRoles(idToken); // → ["registry:read"]
- */
 export declare function registryTokenRoles(idToken: string | null | undefined): string[];
-/** What a re-mint of the registry session produced. */
 export interface RegistryRemint {
-    /** A new token was minted through the refresh token and cached. */
     reminted: boolean;
-    /** The new token carries a different role set than the one it replaced. */
     rolesChanged: boolean;
 }
-/**
- * Re-mint the registry session's token so a role granted after the sign-in
- * reaches the broker. Roles ride in a Zitadel token from the moment it is
- * issued: a still-valid session keeps presenting the roles it had at sign-in
- * until it is re-minted.
- *
- * `rolesChanged` is the field a retry turns on. A re-mint that comes back with
- * the same roles presents the broker with the same authorization facts, so
- * asking again can only buy a second round trip to the same answer.
- *
- * @returns `{ reminted: false, rolesChanged: false }` when there is no
- *   session, no refresh token, or the issuer refuses the exchange.
- * @example
- * if ((await refreshRegistrySession("registry")).rolesChanged) retryTheBroker();
- */
 export declare function refreshRegistrySession(context: string): Promise<RegistryRemint>;
-/**
- * Forget the registry: the session AND the pinned identity record, so the
- * next `mesh registry login` re-discovers the registry from the pinned
- * domain. Clears the reserved key only — a platform session under `mesh.dev`
- * that happened to double as the registry's is a platform login and stays.
- *
- * @example
- * clearRegistrySession(); // `mesh registry logout`
- */
 export declare function clearRegistrySession(): void;
-/**
- * True when two identity records disagree on anything that matters for a
- * broker call — the signal that a re-discovery is worth a retry.
- *
- * @example
- * identityChanged(a, { ...a, registryBroker: "https://moved" }); // → true
- */
 export declare function identityChanged(before: RegistryIdentity, after: RegistryIdentity): boolean;
-/**
- * Human-readable time left on a session, e.g. `11h 42m`; `expired` when the
- * expiry has passed. Pure; exported for the status line's test.
- */
 export declare function describeSessionExpiry(expiresAt: string, now?: number): string;
-/** Log the one-line identity banner `mesh registry login` opens with. */
 export declare function logRegistryIdentity(identity: RegistryIdentity): void;
-//# sourceMappingURL=registry-identity.d.ts.map

package/dist/src/utils/registry-identity.js

@@ -1,43 +1,10 @@
-/**
- * The ONE identity behind `@mesh-tech` package access.
- *
- * Every reader of the registry — `pnpm install`, `mesh create-app`,
- * `mesh docs start`, the Hub image build under `mesh start` — talks to the same
- * CodeArtifact domain, and that domain is owned by exactly one Mesh platform:
- * `dev.platform.meshtech.io`. So the registry has a single, global identity
- * (issuer + CLI client id + broker URL) that never depends on which tenant
- * platform, if any, the developer deploys to.
- *
- * This module keeps that identity separate from platform contexts:
- *
- * - The domain comes from the compiled-in first-party alias table and nowhere
- *   else — not an argument, not an environment variable, not an unpinned
- *   config value. That is the same trust anchor `mesh login` relies on, so the
- *   ≥2-dot anti-phishing guard stays intact.
- * - The Zitadel session for the registry is cached under a **reserved**
- *   credential key (`registry`) that no `<tenant>.<env>` context can collide
- *   with, and `mesh login` / `mesh logout` refuse it.
- * - A developer who already signed in to the registry's own platform
- *   (`mesh login mesh.dev`) is reused rather than sent through the browser a
- *   second time: any cached session whose issuer matches the registry's counts.
- *
- * Nothing here touches `~/.npmrc` or the broker — that is `mesh registry
- * login`'s job. This module only answers "who is the registry?" and "do I hold
- * a session for it?".
- */
 import { clearContextConfig, clearCredentials, decodeJwtPayload, discoverConfigFromWellKnown, forceRefreshToken, getContextConfig, getValidToken, readAllContextConfigs, readAllCredentials, readCredentials, runLoginFlow, tokenStillValid, writeContextConfig, RESERVED_REGISTRY_CONTEXT, } from "../commands/login.js";
 import { projectRoleKeys } from "./aws-auth.js";
 import { firstPartyDomainFor } from "./first-party-contexts.js";
 import { deriveRegistryBroker } from "./registry-broker.js";
 import { MeshCliError } from "./errors.js";
 import { logInfo } from "./log.js";
-/**
- * The first-party alias of the platform that owns the `@mesh-tech` registry.
- * The alias is the key in `FIRST_PARTY_CONTEXTS`; the domain is looked up
- * from that reviewed table, never typed here twice.
- */
 export const REGISTRY_ALIAS = "mesh.dev";
-/** The pinned domain anonymous discovery runs against, e.g. `dev.platform.meshtech.io`. */
 export const REGISTRY_DOMAIN = (() => {
     const domain = firstPartyDomainFor(REGISTRY_ALIAS);
     if (!domain) {
@@ -45,17 +12,10 @@ export const REGISTRY_DOMAIN = (() => {
     }
     return domain;
 })();
-/**
- * The reserved context name the registry session and identity are cached under
- * in `credentials.json` / `config.json`. Deliberately has no dot, so it can
- * never parse as a `<tenant>.<env>` platform context.
- */
 export const REGISTRY_CREDENTIAL_KEY = RESERVED_REGISTRY_CONTEXT;
-/** True when a context name is the reserved registry key. */
 export function isReservedRegistryContext(context) {
     return context === REGISTRY_CREDENTIAL_KEY;
 }
-/** Raised when the registry's identity cannot be resolved (offline, endpoint down). */
 export class RegistryIdentityError extends MeshCliError {
     constructor(detail) {
         super(`Could not resolve the Mesh package registry (${detail}).\n` +
@@ -76,19 +36,6 @@ function toIdentity(cfg) {
         discoveredAt: cfg.discoveredAt ?? new Date(0).toISOString(),
     };
 }
-/**
- * Resolve the registry's identity: the cached record under the reserved key,
- * or a fresh anonymous HTTPS discovery on the pinned domain which is then
- * cached there. `refresh: true` skips the cache.
- *
- * Never consults SSM and never takes the domain from anything but the alias
- * table. Throws `RegistryIdentityError` when discovery is impossible and
- * nothing is cached.
- *
- * @example
- * const { registryBroker } = await resolveRegistryIdentity();
- * // → "https://registry-auth.dev.platform.meshtech.io"
- */
 export async function resolveRegistryIdentity(opts = {}) {
     if (!opts.refresh) {
         const cached = toIdentity(getContextConfig(REGISTRY_CREDENTIAL_KEY));
@@ -109,17 +56,6 @@ export async function resolveRegistryIdentity(opts = {}) {
     writeContextConfig(REGISTRY_CREDENTIAL_KEY, stored);
     return identity;
 }
-/**
- * The cached contexts whose session can stand in for the registry's: the
- * reserved key first, then the registry's own alias and domain — but only
- * when the cached config for that name points at the SAME issuer, so a
- * pre-repoint `mesh.dev` entry (a different platform) is never mistaken for
- * the registry. With no known issuer (nothing discovered yet) only the
- * reserved key counts: a guess about which platform session "is" the
- * registry is the mistake this function exists to prevent.
- *
- * Pure over the two files' contents; exported for tests.
- */
 export function registrySessionCandidates(issuer, configs = readAllContextConfigs(), credentials = readAllCredentials()) {
     const names = issuer ? [REGISTRY_CREDENTIAL_KEY, REGISTRY_ALIAS, REGISTRY_DOMAIN] : [REGISTRY_CREDENTIAL_KEY];
     return names.filter((name) => {
@@ -131,14 +67,6 @@ export function registrySessionCandidates(issuer, configs = readAllContextConfig
         return issuer ? cfg.issuer === issuer : true;
     });
 }
-/**
- * The registry session as cached right now — no refresh, no network. Null when
- * no candidate context holds an unexpired token.
- *
- * @example
- * const s = readRegistrySession();
- * if (s) console.log(`signed in as ${s.email}`);
- */
 export function readRegistrySession() {
     const identity = toIdentity(getContextConfig(REGISTRY_CREDENTIAL_KEY));
     for (const context of registrySessionCandidates(identity?.issuer ?? null)) {
@@ -149,24 +77,6 @@ export function readRegistrySession() {
     }
     return null;
 }
-/**
- * Get a valid Zitadel session for the registry's issuer, signing in when
- * there is none.
- *
- * Reuses ANY cached session whose issuer matches — a developer already signed
- * in to `mesh.dev` gets no second browser trip — refreshing an expired one
- * through its refresh token first. Only when no candidate can be refreshed
- * does it run the sign-in (browser PKCE, or device code with `device: true`
- * or in a remote/non-TTY environment) and store the result under the
- * reserved key.
- *
- * `interactive: false` means "cached or nothing": callers that cannot open a
- * browser or print a device code get `no-tty` back instead of a hung prompt.
- *
- * @example
- * const session = await ensureRegistrySession({ interactive: true });
- * if (session.ok) console.log(session.email);
- */
 export async function ensureRegistrySession(opts) {
     let identity;
     try {
@@ -190,8 +100,6 @@ export async function ensureRegistrySession(opts) {
             detail: "no registry session is cached and this run cannot open a sign-in",
         };
     }
-    // The reserved key gets the registry's identity as its config so the
-    // ordinary token machinery (refresh included) works for it unchanged.
     const stored = getContextConfig(REGISTRY_CREDENTIAL_KEY);
     if (!stored) {
         writeContextConfig(REGISTRY_CREDENTIAL_KEY, {
@@ -200,8 +108,6 @@ export async function ensureRegistrySession(opts) {
             registryBroker: identity.registryBroker,
         });
     }
-    // Said here, not by the caller: only now is it known that no cached session
-    // could be refreshed, so this line never precedes a silent refresh.
     logInfo(opts.device
         ? "No registry session — sign in with the device code below…"
         : "No registry session — opening your browser to sign in… (headless? use --device)");
@@ -222,17 +128,6 @@ export async function ensureRegistrySession(opts) {
         expiresAt: creds.expiresAt,
     };
 }
-/**
- * The Zitadel project-role names a session token carries, sorted.
- *
- * Empty for a token with no roles claim and for anything that does not parse
- * as a JWT — a caller comparing two of these treats "unreadable" as "no roles
- * to compare", which is the safe reading for a token the broker will refuse
- * anyway.
- *
- * @example
- * registryTokenRoles(idToken); // → ["registry:read"]
- */
 export function registryTokenRoles(idToken) {
     if (!idToken)
         return [];
@@ -243,21 +138,6 @@ export function registryTokenRoles(idToken) {
         return [];
     }
 }
-/**
- * Re-mint the registry session's token so a role granted after the sign-in
- * reaches the broker. Roles ride in a Zitadel token from the moment it is
- * issued: a still-valid session keeps presenting the roles it had at sign-in
- * until it is re-minted.
- *
- * `rolesChanged` is the field a retry turns on. A re-mint that comes back with
- * the same roles presents the broker with the same authorization facts, so
- * asking again can only buy a second round trip to the same answer.
- *
- * @returns `{ reminted: false, rolesChanged: false }` when there is no
- *   session, no refresh token, or the issuer refuses the exchange.
- * @example
- * if ((await refreshRegistrySession("registry")).rolesChanged) retryTheBroker();
- */
 export async function refreshRegistrySession(context) {
     const before = registryTokenRoles(readCredentials(context)?.idToken);
     const idToken = await forceRefreshToken(context);
@@ -267,35 +147,15 @@ export async function refreshRegistrySession(context) {
     const same = after.length === before.length && after.every((role, i) => role === before[i]);
     return { reminted: true, rolesChanged: !same };
 }
-/**
- * Forget the registry: the session AND the pinned identity record, so the
- * next `mesh registry login` re-discovers the registry from the pinned
- * domain. Clears the reserved key only — a platform session under `mesh.dev`
- * that happened to double as the registry's is a platform login and stays.
- *
- * @example
- * clearRegistrySession(); // `mesh registry logout`
- */
 export function clearRegistrySession() {
     clearCredentials(REGISTRY_CREDENTIAL_KEY);
     clearContextConfig(REGISTRY_CREDENTIAL_KEY);
 }
-/**
- * True when two identity records disagree on anything that matters for a
- * broker call — the signal that a re-discovery is worth a retry.
- *
- * @example
- * identityChanged(a, { ...a, registryBroker: "https://moved" }); // → true
- */
 export function identityChanged(before, after) {
     return (before.issuer !== after.issuer ||
         before.clientId !== after.clientId ||
         before.registryBroker !== after.registryBroker);
 }
-/**
- * Human-readable time left on a session, e.g. `11h 42m`; `expired` when the
- * expiry has passed. Pure; exported for the status line's test.
- */
 export function describeSessionExpiry(expiresAt, now = Date.now()) {
     const ms = new Date(expiresAt).getTime() - now;
     if (!(ms > 0))
@@ -305,15 +165,12 @@ export function describeSessionExpiry(expiresAt, now = Date.now()) {
     const m = totalMinutes % 60;
     return h > 0 ? `${h}h ${m}m` : `${m}m`;
 }
-/** Log the one-line identity banner `mesh registry login` opens with. */
 export function logRegistryIdentity(identity) {
     let host = identity.registryBroker;
     try {
         host = new URL(identity.registryBroker).host;
     }
     catch {
-        // keep the raw value when it is not a URL
     }
     logInfo(`Mesh package registry: mesh-platform (broker ${host})`);
 }
-//# sourceMappingURL=registry-identity.js.map

package/dist/src/utils/scaffold-versions.d.ts

@@ -1,57 +1,16 @@
-/**
- * Dependency versions written into a scaffolded app.
- *
- * Why this exists
- * ───────────────
- * `mesh create-app --primitives` renders the fragment templates, and those
- * package.json files have to install in TWO very different places:
- *
- *   - inside this monorepo → `workspace:*` + `catalog:` (link local source)
- *   - inside a standalone tenant-apps repo → concrete, published ranges
- *
- * The standalone branch takes a caret range on the CURRENT published line,
- * resolved from the registry at scaffold time. The baked value below is a
- * floor, used only when that lookup can't run (offline, no registry auth
- * yet, CI) — not the answer.
- */
-/**
- * The `@mesh-tech/*` package whose published version defines the lockstep
- * group's current line. The publishable packages move together, so one lookup
- * answers for all of them. `@mesh-tech/esm-bundle` versions independently, so
- * it gets its own entry.
- */
 export declare const SCAFFOLD_PACKAGE_LINES: {
     readonly "@mesh-tech/app-kit": "^1.45.0";
     readonly "@mesh-tech/esm-bundle": "^0.1.1";
 };
 export type ScaffoldPackage = keyof typeof SCAFFOLD_PACKAGE_LINES;
-/**
- * Toolchain devDependencies for the standalone branch. These mirror the
- * workspace catalog in `pnpm-workspace.yaml` (which the published CLI cannot
- * read); `test/scaffold-versions.test.ts` fails if the two drift apart.
- */
 export declare const SCAFFOLD_TOOLCHAIN: {
     readonly "@types/node": "^24.2.1";
     readonly tsx: "^4.20.4";
     readonly typescript: "^5.9.2";
 };
-/** True for a caret range on a prerelease/build-metadata version (`^0.0.0-dev.1`). */
 export declare function isPrerelease(range: string): boolean;
-/** Pure: `1.45.1` → `^1.45.1`. Returns null for anything that isn't x.y.z. */
 export declare function toCaretRange(version: string): string | null;
-/**
- * Ask the registry for a package's current published line, as a caret range.
- * `cwd` matters: the target repo's `.npmrc` is what maps `@mesh-tech` to
- * CodeArtifact. Any failure (offline, 401, npm missing) falls back silently —
- * a scaffold must never hard-fail on a version lookup.
- *
- * A prerelease answer is refused here rather than in `toCaretRange`, which
- * stays a pure format check. Most published `@mesh-tech/*` versions are
- * `0.0.0-dev.<timestamp>.<sha>` snapshots; a `latest` that ever lands on one
- * would otherwise pin every future scaffold to a single dev build.
- */
 export declare function resolvePublishedRange(pkg: ScaffoldPackage, cwd: string): {
     range: string;
     resolved: boolean;
 };
-//# sourceMappingURL=scaffold-versions.d.ts.map

package/dist/src/utils/scaffold-versions.js

@@ -1,60 +1,20 @@
-/**
- * Dependency versions written into a scaffolded app.
- *
- * Why this exists
- * ───────────────
- * `mesh create-app --primitives` renders the fragment templates, and those
- * package.json files have to install in TWO very different places:
- *
- *   - inside this monorepo → `workspace:*` + `catalog:` (link local source)
- *   - inside a standalone tenant-apps repo → concrete, published ranges
- *
- * The standalone branch takes a caret range on the CURRENT published line,
- * resolved from the registry at scaffold time. The baked value below is a
- * floor, used only when that lookup can't run (offline, no registry auth
- * yet, CI) — not the answer.
- */
 import { execFileSync } from "child_process";
-/**
- * The `@mesh-tech/*` package whose published version defines the lockstep
- * group's current line. The publishable packages move together, so one lookup
- * answers for all of them. `@mesh-tech/esm-bundle` versions independently, so
- * it gets its own entry.
- */
 export const SCAFFOLD_PACKAGE_LINES = {
     "@mesh-tech/app-kit": "^1.45.0",
     "@mesh-tech/esm-bundle": "^0.1.1",
 };
-/**
- * Toolchain devDependencies for the standalone branch. These mirror the
- * workspace catalog in `pnpm-workspace.yaml` (which the published CLI cannot
- * read); `test/scaffold-versions.test.ts` fails if the two drift apart.
- */
 export const SCAFFOLD_TOOLCHAIN = {
     "@types/node": "^24.2.1",
     tsx: "^4.20.4",
     typescript: "^5.9.2",
 };
-/** True for a caret range on a prerelease/build-metadata version (`^0.0.0-dev.1`). */
 export function isPrerelease(range) {
     return /[-+]/.test(range.replace(/^\^/, ""));
 }
-/** Pure: `1.45.1` → `^1.45.1`. Returns null for anything that isn't x.y.z. */
 export function toCaretRange(version) {
     const trimmed = version.trim();
     return /^\d+\.\d+\.\d+(?:[-+].*)?$/.test(trimmed) ? `^${trimmed}` : null;
 }
-/**
- * Ask the registry for a package's current published line, as a caret range.
- * `cwd` matters: the target repo's `.npmrc` is what maps `@mesh-tech` to
- * CodeArtifact. Any failure (offline, 401, npm missing) falls back silently —
- * a scaffold must never hard-fail on a version lookup.
- *
- * A prerelease answer is refused here rather than in `toCaretRange`, which
- * stays a pure format check. Most published `@mesh-tech/*` versions are
- * `0.0.0-dev.<timestamp>.<sha>` snapshots; a `latest` that ever lands on one
- * would otherwise pin every future scaffold to a single dev build.
- */
 export function resolvePublishedRange(pkg, cwd) {
     try {
         const out = execFileSync("npm", ["view", pkg, "version"], {
@@ -68,8 +28,6 @@ export function resolvePublishedRange(pkg, cwd) {
             return { range, resolved: true };
     }
     catch {
-        // fall through to the baked floor
     }
     return { range: SCAFFOLD_PACKAGE_LINES[pkg], resolved: false };
 }
-//# sourceMappingURL=scaffold-versions.js.map

package/dist/src/utils/socks-forward.d.ts

@@ -1,40 +1,16 @@
-/**
- * A minimal SOCKS5 CONNECT forwarder: listens on a local TCP port and pipes
- * each client connection through a SOCKS5 proxy (no-auth) to a fixed target.
- *
- * Presents the same plain `localhost:PORT` contract the SSM tunnels give today,
- * so an app (e.g. a Temporal gRPC client) connects with no proxy awareness —
- * the SOCKS5 proxy is the userspace-Tailscale daemon (MESH-2040 / MESH-2036).
- */
 import * as net from "node:net";
-/** `"10.0.137.203"` → `[10,0,137,203]`; throws on anything that isn't IPv4. */
 export declare function ipv4ToBytes(ip: string): number[];
-/** SOCKS5 CONNECT request for an IPv4 target (VER, CMD=CONNECT, RSV, ATYP=IPv4, addr, port). */
 export declare function socks5ConnectRequest(ip: string, port: number): Buffer;
-/** Interpret the SOCKS5 reply code (byte 1 of the CONNECT reply). */
 export declare function interpretSocksReply(code: number): {
     ok: boolean;
     message: string;
 };
 export interface ForwarderOptions {
-    /** Local TCP port to listen on (0 = ephemeral, useful in tests). */
     listenPort: number;
     socksHost?: string;
     socksPort: number;
     targetIp: string;
     targetPort: number;
-    /**
-     * Observes server errors — above all a bind failure (`EADDRINUSE`). The
-     * forwarder still never crashes the process, but the error must not be
-     * INVISIBLE: an unbound forwarder whose port is held by a foreign process is
-     * the silent-dead-tunnel class (MESH-2407), so callers record it and the
-     * ownership handshake reports the port as not-listening.
-     */
     onError?: (err: NodeJS.ErrnoException) => void;
 }
-/**
- * Create (and start) a forwarder server. Each inbound client is spliced to
- * `targetIp:targetPort` via a SOCKS5 CONNECT through `socksHost:socksPort`.
- */
 export declare function createForwarder(opts: ForwarderOptions): net.Server;
-//# sourceMappingURL=socks-forward.d.ts.map

package/dist/src/utils/socks-forward.js

@@ -1,13 +1,4 @@
-/**
- * A minimal SOCKS5 CONNECT forwarder: listens on a local TCP port and pipes
- * each client connection through a SOCKS5 proxy (no-auth) to a fixed target.
- *
- * Presents the same plain `localhost:PORT` contract the SSM tunnels give today,
- * so an app (e.g. a Temporal gRPC client) connects with no proxy awareness —
- * the SOCKS5 proxy is the userspace-Tailscale daemon (MESH-2040 / MESH-2036).
- */
 import * as net from "node:net";
-/** `"10.0.137.203"` → `[10,0,137,203]`; throws on anything that isn't IPv4. */
 export function ipv4ToBytes(ip) {
     const parts = ip.split(".");
     if (parts.length !== 4)
@@ -20,7 +11,6 @@ export function ipv4ToBytes(ip) {
         return n;
     });
 }
-/** SOCKS5 CONNECT request for an IPv4 target (VER, CMD=CONNECT, RSV, ATYP=IPv4, addr, port). */
 export function socks5ConnectRequest(ip, port) {
     return Buffer.from([0x05, 0x01, 0x00, 0x01, ...ipv4ToBytes(ip), (port >> 8) & 0xff, port & 0xff]);
 }
@@ -35,21 +25,16 @@ const SOCKS_REPLY_MESSAGES = {
     7: "command not supported",
     8: "address type not supported",
 };
-/** Interpret the SOCKS5 reply code (byte 1 of the CONNECT reply). */
 export function interpretSocksReply(code) {
     return { ok: code === 0, message: SOCKS_REPLY_MESSAGES[code] ?? `unknown SOCKS reply ${code}` };
 }
-/**
- * Create (and start) a forwarder server. Each inbound client is spliced to
- * `targetIp:targetPort` via a SOCKS5 CONNECT through `socksHost:socksPort`.
- */
 export function createForwarder(opts) {
     const socksHost = opts.socksHost ?? "127.0.0.1";
     const server = net.createServer((client) => {
         const up = net.connect(opts.socksPort, socksHost);
         let buf = Buffer.alloc(0);
-        let phase = 0; // 0=await method-select, 1=await connect reply, 2=streaming
-        up.on("connect", () => up.write(Buffer.from([0x05, 0x01, 0x00]))); // greet, no-auth
+        let phase = 0;
+        up.on("connect", () => up.write(Buffer.from([0x05, 0x01, 0x00])));
         up.on("data", (d) => {
             if (phase === 2)
                 return;
@@ -80,18 +65,10 @@ export function createForwarder(opts) {
         });
         client.on("error", () => up.destroy());
         up.on("error", () => client.destroy());
-        // A cleanly-closed client (clean FIN, no "error") must still tear down the
-        // upstream SOCKS→target leg — otherwise a probe that connects then closes
-        // strands a real VPC-target connection until the target times out.
         client.on("close", () => up.destroy());
         up.on("close", () => client.destroy());
     });
-    // A bind failure (e.g. the port is already held by an SSM tunnel) must not
-    // crash the process running this forwarder — but it must be OBSERVED, not
-    // swallowed: the runner records it and ownership checks fail the port.
-    // Attach before listen() so the error is caught.
     server.on("error", (err) => opts.onError?.(err));
     server.listen(opts.listenPort, "127.0.0.1");
     return server;
 }
-//# sourceMappingURL=socks-forward.js.map