@mesh-tech/mesh-cli 0.44.0 → 0.45.0

package/dist/src/utils/workstation-machine.js

@@ -0,0 +1,282 @@
+import { execFileSync } from "node:child_process";
+import { X509Certificate } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { logInfo } from "./log.js";
+import { readWorkstationIdentity, workstationDir } from "./workstation-routes.js";
+export function readCredentialProcess(configText, profile) {
+    let inSection = false;
+    for (const line of configText.split("\n")) {
+        const header = /^\s*\[(.+)\]\s*$/.exec(line);
+        if (header) {
+            inSection = header[1].trim() === `profile ${profile}` || header[1].trim() === profile;
+            continue;
+        }
+        const kv = /^\s*credential_process\s*=\s*(.+?)\s*$/.exec(line);
+        if (inSection && kv)
+            return kv[1];
+    }
+    return undefined;
+}
+export function credentialProgram(command) {
+    return command.split(/\s+/)[0];
+}
+export function credentialProcessProblem(command, deps) {
+    if (!command)
+        return "the profile has no credential_process (run mesh login <platform> --export --role <roleArn>)";
+    const program = credentialProgram(command);
+    if (!path.isAbsolute(program))
+        return `its program "${program}" is not an absolute path`;
+    if (!deps.exists(program))
+        return `its program ${program} does not exist`;
+    if (deps.isInsideGitTree(program)) {
+        return `its program ${program} is inside a git checkout, and stops working when that checkout is removed`;
+    }
+    return undefined;
+}
+export function isInsideGitTree(p) {
+    let dir = path.dirname(path.resolve(p));
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".git")))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+export function rewriteCredentialProgram(configText, profile, cli) {
+    let inSection = false;
+    let rewritten = false;
+    const lines = configText.split("\n").map((line) => {
+        const header = /^\s*\[(.+)\]\s*$/.exec(line);
+        if (header) {
+            inSection = header[1].trim() === `profile ${profile}` || header[1].trim() === profile;
+            return line;
+        }
+        const kv = /^(\s*credential_process\s*=\s*)(\S+)(.*)$/.exec(line);
+        if (inSection && kv) {
+            rewritten = true;
+            return `${kv[1]}${cli}${kv[3]}`;
+        }
+        return line;
+    });
+    if (!rewritten)
+        throw new Error(`no credential_process in [profile ${profile}]`);
+    return lines.join("\n");
+}
+export const LAUNCH_AGENT_LABEL = "tech.mesh.workstation-proxy";
+export const LAUNCH_AGENTS_MACOS_ONLY = "LaunchAgents are macOS-only; run mesh workstation proxy in the foreground (or under your own service manager)";
+export function launchAgentsSupported(platform = process.platform) {
+    return platform === "darwin";
+}
+export function launchAgentSearchPath(installerPath, execPath) {
+    const entries = [
+        ...(installerPath ?? "").split(":"),
+        path.dirname(execPath),
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+    ].filter((p) => path.isAbsolute(p) && !p.split(path.sep).includes("node_modules"));
+    return [...new Set(entries)].join(":");
+}
+function xml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function renderLaunchAgent(args) {
+    const program = [args.caddy, "run", "--watch", "--config", args.caddyfile, "--adapter", "caddyfile"];
+    const env = Object.entries(args.env)
+        .map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`)
+        .join("\n");
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        `\t<key>Label</key>\n\t<string>${LAUNCH_AGENT_LABEL}</string>`,
+        `\t<key>ProgramArguments</key>\n\t<array>\n${program.map((a) => `\t\t<string>${xml(a)}</string>`).join("\n")}\n\t</array>`,
+        `\t<key>WorkingDirectory</key>\n\t<string>${xml(args.dir)}</string>`,
+        `\t<key>EnvironmentVariables</key>\n\t<dict>\n${env}\n\t</dict>`,
+        "\t<key>RunAtLoad</key>\n\t<true/>",
+        "\t<key>KeepAlive</key>\n\t<true/>",
+        `\t<key>StandardOutPath</key>\n\t<string>${xml(path.join(args.dir, "proxy.log"))}</string>`,
+        `\t<key>StandardErrorPath</key>\n\t<string>${xml(path.join(args.dir, "proxy.log"))}</string>`,
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+export function certificateExpiry(dir, domain) {
+    const certs = path.join(dir, "caddy", "certificates");
+    let best;
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.name === `wildcard_.${domain}.crt`) {
+                const expiry = new Date(new X509Certificate(fs.readFileSync(p)).validTo);
+                if (!best || expiry > best)
+                    best = expiry;
+            }
+        }
+    };
+    walk(certs);
+    return best;
+}
+export function workstationWarnings(args) {
+    const warnings = [];
+    if (args.certExpiry) {
+        const days = Math.floor((args.certExpiry.getTime() - args.now.getTime()) / 86_400_000);
+        if (days < 14)
+            warnings.push(`The certificate expires in ${days} day(s) and has not renewed: check proxy.log.`);
+    }
+    if (args.credentialProblem)
+        warnings.push(`The proxy's AWS profile will not renew the certificate: ${args.credentialProblem}.`);
+    else if (!args.credentialOk) {
+        warnings.push("The proxy's AWS profile yields no credentials (mesh login expired?): renewals fail until you log in again.");
+    }
+    return warnings;
+}
+export function discoveryRecordName(name, platform) {
+    return `_mesh-workstation.${name}.${platform.replace(/\.$/, "")}`.toLowerCase();
+}
+export function parseDiscoveryRecord(text) {
+    const fields = new Map();
+    for (const part of text.trim().split(/\s+/)) {
+        const eq = part.indexOf("=");
+        if (eq > 0)
+            fields.set(part.slice(0, eq), part.slice(eq + 1));
+    }
+    if (fields.get("v") !== "1")
+        return `unknown discovery record version (${fields.get("v") ?? "none"})`;
+    const roleArn = fields.get("role") ?? "";
+    const zoneId = fields.get("zone") ?? "";
+    const region = fields.get("region") ?? "";
+    if (!/^arn:aws:iam::\d{12}:role\/[\w+=,.@/-]+$/.test(roleArn))
+        return `"${roleArn}" is not an IAM role ARN`;
+    if (!/^Z[A-Z0-9]{1,32}$/.test(zoneId))
+        return `"${zoneId}" is not a Route 53 zone id`;
+    if (!/^[a-z]{2}(-[a-z]+)+-\d$/.test(region))
+        return `"${region}" is not an AWS region`;
+    return { roleArn, zoneId, region };
+}
+export function caddyDownloadUrl(platform, arch) {
+    const goArch = arch === "x64" ? "amd64" : arch;
+    return `https://caddyserver.com/api/download?os=${platform}&arch=${goArch}&p=${encodeURIComponent("github.com/caddy-dns/route53")}`;
+}
+export function caddyHasRoute53(listModulesOutput) {
+    return listModulesOutput.split("\n").some((l) => l.trim() === "dns.providers.route53");
+}
+export function shimFallsBackToGlobal(shimText) {
+    return shimText.includes("canonical launcher shim") && shimText.includes("Not in a workspace: exec the next");
+}
+export function zoneCandidates(platform) {
+    const labels = platform.replace(/\.$/, "").toLowerCase().split(".");
+    return labels.slice(0, -1).map((_, i) => labels.slice(i).join("."));
+}
+export const RENEWAL_OVERDUE_DAYS = 28;
+export function healthCheckDue(stamp, now) {
+    if (!stamp)
+        return true;
+    const at = Date.parse(stamp.checkedAt);
+    return !Number.isFinite(at) || now.getTime() - at >= 86_400_000;
+}
+export function loginContextOf(command) {
+    return command ? /\slogin\s+("?)([^\s"]+)\1/.exec(command)?.[2] : undefined;
+}
+export function renewalWarnings(args) {
+    const days = args.certExpiry ? Math.floor((args.certExpiry.getTime() - args.now.getTime()) / 86_400_000) : undefined;
+    const expires = days === undefined ? "" : ` (certificate expires in ${days} day${days === 1 ? "" : "s"})`;
+    const login = args.loginContext ? `mesh login ${args.loginContext}` : "the profile's mesh login";
+    if (!args.credentialOk)
+        return [`Workstation certificate renewal is failing: run ${login}${expires}`];
+    if (days !== undefined && days < RENEWAL_OVERDUE_DAYS) {
+        return [`Workstation certificate has not renewed${expires}: check ~/.config/mesh/workstation/proxy.log`];
+    }
+    return [];
+}
+const STATIC_AWS_VARS = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"];
+export function proxyEnv(base, proxy) {
+    const env = { ...base };
+    for (const key of STATIC_AWS_VARS)
+        delete env[key];
+    env.AWS_REGION = proxy.region;
+    if (proxy.awsProfile)
+        env.AWS_PROFILE = proxy.awsProfile;
+    if (proxy.awsConfigFile)
+        env.AWS_CONFIG_FILE = proxy.awsConfigFile;
+    return env;
+}
+export function awsConfigFileOf(proxy) {
+    return proxy.awsConfigFile ?? path.join(os.homedir(), ".aws", "config");
+}
+export function profileYieldsCredentials(proxy, timeoutMs = 60_000) {
+    if (!proxy.awsProfile)
+        return true;
+    const command = readCredentialProcess(fs.readFileSync(awsConfigFileOf(proxy), "utf8"), proxy.awsProfile);
+    if (!command)
+        return false;
+    try {
+        const out = execFileSync("/bin/sh", ["-c", command], {
+            env: proxyEnv(process.env, proxy),
+            cwd: os.homedir(),
+            timeout: timeoutMs,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return typeof JSON.parse(out.toString()).AccessKeyId === "string";
+    }
+    catch {
+        return false;
+    }
+}
+export function workstationRenewalWarnings(now = new Date()) {
+    try {
+        const dir = workstationDir();
+        const identity = readWorkstationIdentity(dir);
+        if (!identity?.proxy)
+            return [];
+        const proxy = identity.proxy;
+        const stampFile = path.join(dir, "health.json");
+        let stamp;
+        try {
+            stamp = JSON.parse(fs.readFileSync(stampFile, "utf8"));
+        }
+        catch {
+            stamp = undefined;
+        }
+        if (healthCheckDue(stamp, now)) {
+            logInfo("Checking the workstation's certificate credentials…");
+            stamp = { checkedAt: now.toISOString(), credentialOk: profileYieldsCredentials(proxy, 20_000) };
+            fs.writeFileSync(stampFile, JSON.stringify(stamp) + "\n");
+        }
+        let command;
+        if (proxy.awsProfile) {
+            try {
+                command = readCredentialProcess(fs.readFileSync(awsConfigFileOf(proxy), "utf8"), proxy.awsProfile);
+            }
+            catch {
+                command = undefined;
+            }
+        }
+        return renewalWarnings({
+            now,
+            certExpiry: certificateExpiry(dir, identity.domain),
+            credentialOk: stamp.credentialOk,
+            loginContext: loginContextOf(command),
+        });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/utils/workstation-routes.d.ts

@@ -0,0 +1,77 @@
+export interface WorkstationIdentity {
+    name: string;
+    domain: string;
+    proxy?: WorkstationProxyConfig;
+}
+export interface WorkstationProxyConfig {
+    zoneId: string;
+    region: string;
+    awsProfile?: string;
+    awsConfigFile?: string;
+    caddy?: string;
+}
+export interface WorkstationRoute {
+    hostname: string;
+    port: number;
+    session?: string;
+}
+export declare function workstationDir(): string;
+export declare function readWorkstationIdentity(dir?: string): WorkstationIdentity | undefined;
+export declare function serviceRouteLabel(args: {
+    app: string;
+    service: string;
+    route?: string | false;
+}): string | undefined;
+export declare function worktreeRouteSuffix(wt: {
+    isPrimary: boolean;
+    slug: string;
+}, explicit?: string): string;
+export declare function sessionRouteLabel(label: string, suffix: string): string;
+export declare function planSessionRoutes(args: {
+    identity: WorkstationIdentity;
+    app: string;
+    services: Record<string, {
+        port: number;
+        command?: string[];
+        route?: string | false;
+    }>;
+    suffix: string;
+}): Array<{
+    service: string;
+    hostname: string;
+    port: number;
+}>;
+export declare function renderRouteFile(route: WorkstationRoute): string;
+export declare function parseRouteFile(text: string): WorkstationRoute | undefined;
+export declare function listRoutes(dir?: string): Array<WorkstationRoute & {
+    file: string;
+}>;
+export declare function removeSessionRoutes(session: string, dir?: string): string[];
+export interface SessionRouteResult {
+    urls: Record<string, string>;
+    written: Array<{
+        service: string;
+        hostname: string;
+        port: number;
+    }>;
+    conflicts: Array<{
+        service: string;
+        hostname: string;
+        port: number;
+        heldBy: string;
+        heldPort: number;
+    }>;
+}
+export declare function writeSessionRoutes(session: string, planned: Array<{
+    service: string;
+    hostname: string;
+    port: number;
+}>, dir?: string): SessionRouteResult;
+export declare function renderWorkstationCaddyfile(identity: WorkstationIdentity & {
+    proxy: WorkstationProxyConfig;
+}, dir: string): string;
+export declare function usableRouteUrls(planned: Array<{
+    service: string;
+    hostname: string;
+    port: number;
+}>, dir?: string): Record<string, string>;

package/dist/src/utils/workstation-routes.js

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const LABEL_MAX = 63;
+const SESSION_MARKER = "# mesh dev session: ";
+export function workstationDir() {
+    return process.env.MESH_WORKSTATION_DIR || path.join(os.homedir(), ".config", "mesh", "workstation");
+}
+export function readWorkstationIdentity(dir = workstationDir()) {
+    const file = path.join(dir, "workstation.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const identity = JSON.parse(raw);
+    if (typeof identity.name !== "string" || typeof identity.domain !== "string" || !identity.domain.startsWith(`${identity.name}.`)) {
+        throw new Error(`${file}: needs a name and a domain under it, e.g. {"name":"mbp","domain":"mbp.example.com"}`);
+    }
+    return identity;
+}
+function toLabel(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export function serviceRouteLabel(args) {
+    if (args.route === false)
+        return undefined;
+    const named = args.service === args.app || args.service.startsWith(`${args.app}-`);
+    return toLabel(args.route ?? (named ? args.service : `${args.app}-${args.service}`)) || undefined;
+}
+export function worktreeRouteSuffix(wt, explicit) {
+    if (explicit !== undefined)
+        return toLabel(explicit);
+    if (wt.isPrimary)
+        return "";
+    const short = wt.slug
+        .replace(/^(feature|feat|fix|chore|bugfix|hotfix|refactor|lab|spike)-/, "")
+        .replace(/(-[0-9a-f]{8,})+$/, "");
+    return toLabel(short) || toLabel(wt.slug);
+}
+export function sessionRouteLabel(label, suffix) {
+    if (!suffix)
+        return label.slice(0, LABEL_MAX).replace(/-+$/, "");
+    const room = LABEL_MAX - label.length - 1;
+    if (room < 1)
+        return label.slice(0, LABEL_MAX).replace(/-+$/, "");
+    return `${label}-${suffix.slice(0, room).replace(/-+$/, "")}`;
+}
+export function planSessionRoutes(args) {
+    const routes = [];
+    for (const [service, s] of Object.entries(args.services)) {
+        if (!s.port || !s.command?.length)
+            continue;
+        const label = serviceRouteLabel({ app: args.app, service, route: s.route });
+        if (!label)
+            continue;
+        routes.push({ service, hostname: `${sessionRouteLabel(label, args.suffix)}.${args.identity.domain}`, port: s.port });
+    }
+    return routes;
+}
+export function renderRouteFile(route) {
+    const matcher = `route-${route.hostname.replaceAll(".", "_")}`;
+    return [
+        route.session
+            ? `${SESSION_MARKER}${route.session}`
+            : "# Written by WorkstationRoute (Pulumi). Removed on destroy; edits are overwritten on up.",
+        `@${matcher} host ${route.hostname}`,
+        `handle @${matcher} {`,
+        `\treverse_proxy 127.0.0.1:${route.port}`,
+        "}",
+        "",
+    ].join("\n");
+}
+export function parseRouteFile(text) {
+    const hostname = /^@\S+ host (\S+)$/m.exec(text)?.[1];
+    const port = Number(/reverse_proxy 127\.0\.0\.1:(\d+)/.exec(text)?.[1]);
+    if (!hostname || !port)
+        return undefined;
+    const session = text.split("\n").find((l) => l.startsWith(SESSION_MARKER))?.slice(SESSION_MARKER.length).trim();
+    return { hostname, port, ...(session ? { session } : {}) };
+}
+function routesDir(dir) {
+    return path.join(dir, "routes");
+}
+export function listRoutes(dir = workstationDir()) {
+    let names;
+    try {
+        names = fs.readdirSync(routesDir(dir)).filter((n) => n.endsWith(".caddy"));
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((name) => {
+        const file = path.join(routesDir(dir), name);
+        const route = parseRouteFile(fs.readFileSync(file, "utf8"));
+        return route ? [{ ...route, file }] : [];
+    });
+}
+export function removeSessionRoutes(session, dir = workstationDir()) {
+    const removed = [];
+    for (const route of listRoutes(dir)) {
+        if (route.session !== session)
+            continue;
+        fs.rmSync(route.file, { force: true });
+        removed.push(route.hostname);
+    }
+    return removed;
+}
+export function writeSessionRoutes(session, planned, dir = workstationDir()) {
+    removeSessionRoutes(session, dir);
+    const held = new Map(listRoutes(dir).map((r) => [r.hostname, r]));
+    const result = { urls: {}, written: [], conflicts: [] };
+    fs.mkdirSync(routesDir(dir), { recursive: true });
+    for (const route of planned) {
+        const other = held.get(route.hostname);
+        if (other) {
+            if (other.port === route.port)
+                result.urls[route.service] = `https://${route.hostname}`;
+            else
+                result.conflicts.push({
+                    ...route,
+                    heldBy: other.session ? `session ${other.session}` : "the stack",
+                    heldPort: other.port,
+                });
+            continue;
+        }
+        const file = path.join(routesDir(dir), `${route.hostname}.caddy`);
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, renderRouteFile({ hostname: route.hostname, port: route.port, session }));
+        fs.renameSync(tmp, file);
+        result.written.push(route);
+        result.urls[route.service] = `https://${route.hostname}`;
+    }
+    return result;
+}
+export function renderWorkstationCaddyfile(identity, dir) {
+    return [
+        "# Written by `mesh workstation init`. Routes live in routes/; this file rarely changes.",
+        "{",
+        "\tadmin 127.0.0.1:2119",
+        `\tstorage file_system ${path.join(dir, "caddy")}`,
+        "\tskip_install_trust",
+        "\tauto_https disable_redirects",
+        "\tservers {",
+        "\t\tprotocols h1 h2",
+        "\t}",
+        "}",
+        "",
+        `*.${identity.domain}:443 {`,
+        "\ttls {",
+        "\t\tdns route53 {",
+        `\t\t\thosted_zone_id ${identity.proxy.zoneId}`,
+        `\t\t\tregion ${identity.proxy.region}`,
+        "\t\t\twait_for_route53_sync true",
+        "\t\t}",
+        "\t\tpropagation_delay 60s",
+        "\t\tpropagation_timeout 5m",
+        "\t}",
+        "\t@offnet not remote_ip 100.64.0.0/10 fd7a:115c:a1e0::/48 127.0.0.0/8 ::1",
+        "\thandle @offnet {",
+        "\t\tabort",
+        "\t}",
+        `\timport ${path.join(routesDir(dir), "*.caddy")}`,
+        "\thandle {",
+        '\t\trespond "No service is routed at {host}" 404',
+        "\t}",
+        "}",
+        "",
+    ].join("\n");
+}
+export function usableRouteUrls(planned, dir = workstationDir()) {
+    const byHost = new Map(listRoutes(dir).map((r) => [r.hostname, r]));
+    return Object.fromEntries(planned.filter((p) => byHost.get(p.hostname)?.port === p.port).map((p) => [p.service, `https://${p.hostname}`]));
+}

package/fragments/base/README.md.hbs

@@ -2,6 +2,9 @@
 
 A Mesh app for tenant `{{tenant}}`. The Pulumi program is `index.ts`; run it
 locally with `mesh dev`, deploy it with `mesh deploy up`.
+
+On a machine set up with `mesh workstation init`, `mesh dev` serves each service
+at its own HTTPS name; `route: false` on a Service leaves it out.
 {{#if service}}
 
 The API's docs are `api/openapi.json` and the guides in `docs/pages/`, arranged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "CLI for Mesh platform development utilities",
   "type": "module",
   "license": "UNLICENSED",
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "@mesh-tech/agent-contracts": "0.7.0",
-    "@mesh-tech/tsconfig": "2.62.0",
+    "@mesh-tech/tsconfig": "2.63.0",
     "@mesh-tech/workflow-viz": "0.3.4",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",

package/skills/mesh/SKILL.md

@@ -175,7 +175,8 @@ Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/me
 | `mesh registry` | `login [context]`, `logout`, `status`, `publish` | CodeArtifact auth → refreshes `~/.npmrc` token (12h) + adds `@mesh-tech` scope to project `.npmrc` + **strips an unscoped CodeArtifact `registry=` line from `~/.npmrc`** (after writing `~/.npmrc.bak-<ts>`) — that line is what a raw CodeArtifact sign-in *without* `--namespace @mesh-tech` leaves behind, and it makes CodeArtifact your DEFAULT registry so every *public* install 401s at the 12h expiry. Skipped under `--ci`, where the unscoped login is deliberate. `status` probes the registry rather than grepping the file: expired/missing token or a hijack exits 1, an unreachable registry warns and exits 0. **Step 0 is the Zitadel-gated broker:** the registry is ONE global identity (`utils/registry-identity.ts`, seeded from the compiled-in first-party alias table, session cached under the reserved key `registry`), so no context is needed — `mesh registry login` signs in to the registry's issuer if nothing is cached (browser; `--device` when headless; reuses a `mesh.dev` session on the same issuer) and POSTs the id token to the platform's `registry-auth` service, which returns a CodeArtifact read token minted with its OWN AWS identity — so this path needs no AWS account, CLI or profile at all. It writes the same two `~/.npmrc` lines the AWS path does. Falls back to the AWS chain when the platform publishes no broker, when the broker is unreachable, or with `--no-broker`; a 403 (a valid Mesh account without the `registry:read` role) is fatal and does **not** fall through. `--publish` and `--profile` deliberately skip the broker — both are AWS-identity paths. `--profile mesh-dev` auto-runs the AWS SSO login when the session is stale. `mesh login` never touches the registry (it prints a one-line pointer to `mesh registry login` when the machine has no registry access); `logout` clears the registry session only. A `[context]` on the read path is ignored with a notice; it still selects the SSM export for `--publish`. `login --publish` assumes the registry's publisher role (from `--role` or the registry SSM export); `publish` pushes package snapshots. | `login`: `--device`, `--no-broker`, `--profile <sso>`, `--role <arn>`, `--ci`, `--skip-npmrc`, `--publish`; `publish`: `--snapshot` |
 | `mesh db` | `connect`, `credentials`(alias `creds`), `env`, `psql`, `exec <command...>` | Access tenant DBs through an SSM bastion tunnel. `env` prints `export`s for `eval`; `exec` runs a command with `DATABASE_URL` injected. Outside an app directory pass `-t` and `-e` together — detection fails closed. | `-t/--tenant`, `-e/--env`, `-a/--app`, `--app-tenant`, `--app-stage`; `exec` also: `--secret <arn>`, `--ssl <require\|no-verify\|disable>`, `--port <n>` |
 | `mesh deploy ...` | passthrough | Runs `pulumi` with the stack's `mesh:deployerRole` assumed. Unknown opts/args pass through; defaults to `up` if no subcommand. | `-s/--stack <name>` (stripped before pulumi `up`); everything else → pulumi (`preview`, `up --yes`, `destroy`, `stack output …`) |
-| `mesh dev` | `logs <service>`, `restart <service>`, `list`, `test-user [name]` | Two modes. **Tethered** (deployed stack): reads the Pulumi stack dev output, opens tunnels, injects Secrets Manager secrets; needs VPN/AWS creds. **Local** (`--local`, auto when the app has no `Pulumi.yaml`): synthesizes services from the app layout (subdirs with a `dev` script, plus a synthesized `dg dev` webserver when the app root is a Dagster workspace — `dg.toml`, or `[tool.dg]` in `pyproject.toml`; such an app runs with zero package.json services — see `docs/guides/local-dagster.md`) and wires them to the `mesh start` platform (Temporal `local-dev`, app DB, Zitadel, ministack via `AWS_ENDPOINT_URL`) — zero AWS/VPN/Pulumi. `--externals` (local mode; `--mock` is an alias) also realizes the app's declared external services (package.json → `mesh.externals`; legacy `mesh.mocks` still read). Each declaration runs in one of three MODES — `mock` (the service is emulated: `openapi` → a Prism mock server from a spec, or `src` → a mock process), `local` (a local version of the real service: a `compose` file + published `port`, e.g. a vendor-shaped DB — up `--wait` before the app's services; a realization another checkout already started is **adopted** instead of failing — declared port already served **by a container this compose file defines** → adopt as-is (a publisher the file doesn't define — a native install or unrelated container — is a hard **conflict**, never adopted, since credentials would seed against the wrong service); a stopped foreign container holding the compose `container_name` → `docker start` + adopt — so startup order across checkouts doesn't matter; adopted externals stay out of session state and `--kill` tears down only externals this session created, volumes kept), `remote` (connect to the ACTUAL service: inline vendor `credentials`, or the credentials the app's tenant environment is configured with via `remote.env`). A declaration may carry SEVERAL realizations; `mode` picks the default and `--externals name=mode` overrides it per run (`--externals plaid-db=remote,plaid`). Remote externals get a blackbox uptime probe against their real endpoint. Failing to realize a remote external is fatal only when you named it; a bare `--externals` warns and keeps going, so the local loop still works with no AWS identity. Every realization seeds its ExternalService credential secret (`{{url}}`/`{{host}}`/`{{port}}` from the stand-in's endpoint, `{{env:VAR}}` from the shell) so `resolveCredentials()` runs the deployed code path against the stand-in. Runners: tmux (default) or `--runner docker` (CI/headless — services run as a docker compose project with host networking; parity `--status`/`--kill`/`logs`/`restart`). | root: `--local`, `--externals [name[=mode],…]` (alias `--mock`), `--runner <tmux\|docker>`, `--app <path>`, `--stage`, `--headless`, `--kill`, `--status`, `--json`, `--session <name>`, `--profile <sso>`; `logs`: `--tail <n>`; `test-user`: `--tenant/--env/--region` |
+| `mesh dev` | `logs <service>`, `restart <service>`, `list`, `test-user [name]` | Two modes. **Tethered** (deployed stack): reads the Pulumi stack dev output, opens tunnels, injects Secrets Manager secrets; needs VPN/AWS creds. **Local** (`--local`, auto when the app has no `Pulumi.yaml`): synthesizes services from the app layout (subdirs with a `dev` script, plus a synthesized `dg dev` webserver when the app root is a Dagster workspace — `dg.toml`, or `[tool.dg]` in `pyproject.toml`; such an app runs with zero package.json services — see `docs/guides/local-dagster.md`) and wires them to the `mesh start` platform (Temporal `local-dev`, app DB, Zitadel, ministack via `AWS_ENDPOINT_URL`) — zero AWS/VPN/Pulumi. `--externals` (local mode; `--mock` is an alias) also realizes the app's declared external services (package.json → `mesh.externals`; legacy `mesh.mocks` still read). Each declaration runs in one of three MODES — `mock` (the service is emulated: `openapi` → a Prism mock server from a spec, or `src` → a mock process), `local` (a local version of the real service: a `compose` file + published `port`, e.g. a vendor-shaped DB — up `--wait` before the app's services; a realization another checkout already started is **adopted** instead of failing — declared port already served **by a container this compose file defines** → adopt as-is (a publisher the file doesn't define — a native install or unrelated container — is a hard **conflict**, never adopted, since credentials would seed against the wrong service); a stopped foreign container holding the compose `container_name` → `docker start` + adopt — so startup order across checkouts doesn't matter; adopted externals stay out of session state and `--kill` tears down only externals this session created, volumes kept), `remote` (connect to the ACTUAL service: inline vendor `credentials`, or the credentials the app's tenant environment is configured with via `remote.env`). A declaration may carry SEVERAL realizations; `mode` picks the default and `--externals name=mode` overrides it per run (`--externals plaid-db=remote,plaid`). Remote externals get a blackbox uptime probe against their real endpoint. Failing to realize a remote external is fatal only when you named it; a bare `--externals` warns and keeps going, so the local loop still works with no AWS identity. Every realization seeds its ExternalService credential secret (`{{url}}`/`{{host}}`/`{{port}}` from the stand-in's endpoint, `{{env:VAR}}` from the shell) so `resolveCredentials()` runs the deployed code path against the stand-in. Runners: tmux (default) or `--runner docker` (CI/headless — services run as a docker compose project with host networking; parity `--status`/`--kill`/`logs`/`restart`). **On a workstation** (a machine set up with `mesh workstation init`), each service with a command and a port is also served at `https://<app>-<service>[-<worktree>].<machine domain>` through the machine's proxy, gets that URL as `MESH_DEV_PUBLIC_URL`, and loses its route on `--kill`; `--route-suffix` picks the worktree suffix, and a Service's `route: false` leaves it out. At launch it warns when the machine's certificate renewal will fail (no credentials from the renewal profile, or fewer than 28 days left). | root: `--local`, `--externals [name[=mode],…]` (alias `--mock`), `--runner <tmux\|docker>`, `--app <path>`, `--stage`, `--headless`, `--kill`, `--status`, `--json`, `--session <name>`, `--profile <sso>`, `--route-suffix <name>`; `logs`: `--tail <n>`; `test-user`: `--tenant/--env/--region` |
+| `mesh workstation` | `init`, `proxy`, `status`, `routes` | Opt-in HTTPS names on a developer's own machine for the services it runs: nothing happens without `~/.config/mesh/workstation/workstation.json`. `init` makes the machine a workstation — given `--name` and `--platform`, it discovers the Route 53 zone, region and certificate role from the public TXT record `_mesh-workstation.<name>.<platform>`, writes its own renewal profile, reuses or downloads a Caddy with the Route 53 DNS module, and signs in once. `proxy` runs that Caddy in the foreground (a wildcard certificate by ACME DNS-01, every route file imported, only tailnet and loopback clients accepted); `--install` runs it as a macOS LaunchAgent, `--uninstall` removes it, `--print` shows the Caddyfile and command. `status` checks the proxy, the certificate and the renewal credentials. `routes` lists the names served; `--prune` drops routes of `mesh dev` sessions that are gone. | `init`: `--name <host>`, `--platform <domain>` (or `--domain`/`--zone-id`/`--region`), `--aws-profile`, `--aws-config-file`, `--caddy <path>`, `--cli <path>`, `--force`; `proxy`: `--install`, `--uninstall`, `--print`; `routes`: `--prune`, `--json` |
 | `mesh start` / `mesh stop` / `mesh status` | — | Full-local Mesh platform via docker compose (project `mesh-local`, assets ship in the CLI package): Postgres, Temporal (+UI), Zitadel, SpiceDB, ministack (local AWS fabric: SSM/Secrets/S3 registry; also seeds a general-purpose `mesh-local-data` bucket with sample data — see `docs/guides/local-dagster.md`), memcached, OpenSearch, a **local mailbox** (Mailpit — SMTP :1025 wired into Zitadel, inbox at http://localhost:8025, so user-activation and password-reset mail is testable locally instead of vanishing), **and the hosted observability backends** (OTel collector + Loki + Tempo + Prometheus — the Hub's logs/traces/metrics views run unchanged). Seeds tenant `local`/env `dev` on first boot and reconciles every Zitadel-provisioned app tenant into the registry. **No AWS creds, VPN, or Pulumi state needed — Docker only.** The **Hub is included by default** — three overlay services, `hub-api` + `hub-ui` + `hub-auth` (an oauth2-proxy; it is what binds the front-door port and proxies to `hub-ui`, so front-door 401s/redirect loops are in ITS logs, not `hub-api`'s) — the front door at http://localhost:9000 — `MESH_HUB_PORT=<port>` publishes it elsewhere when 9000 is taken; export it for `mesh status` too (images build once from the published @mesh-tech/hub tarball; needs `mesh registry login` the first time; `--no-hub` opts out). Auth contract: `--with-hub` refreshes to the latest published hub after preflighting the CodeArtifact token — with an expired/missing token it falls back to the already-built local images (warn + fixing command), or fails fast naming `mesh registry login --profile mesh-dev` when none exist; the default (no-flag) path with an expired/missing token starts hub-less and names the same fix. `--hub-from-source` sidesteps the registry entirely — it builds the Hub images from THIS checkout's `apps/hub`, which is the only way to run an unpublished Hub change in the containerized stack. `--with-idps` adds two mock identity providers (SAML + OIDC) and federates the local Zitadel with BOTH, which is how enterprise SSO gets exercised without a cloud tenant — the two-provider shape is deliberate, since the instance login policy carries a LIST of IdPs and the failure worth catching is a second federation evicting the first (`docs/guides/local-federation.md`). Its two host ports (4569 SAML, 5556 OIDC — 5556 is Dex's own default) join the start-up port preflight only when the flag is passed, and `mesh status` lists both mocks once they are running. Non-TTY runs (CI, agents, piped output) get an `[HH:MM:SS]` prefix on every step line plus a heartbeat during long fetches/builds — `MESH_LOG_TIMESTAMPS=1/0` forces the prefix on/off (default: on when stderr is not a TTY). | `start`: `--no-seed`, `--no-hub`, `--with-hub`, `--hub-from-source`, `--with-idps`, `--takeover`, `--skip-port-check`; `stop`: `--destroy` (drops volumes/seeds), `--force`; `status`: `--json` |
 | `mesh hub` | `dev` | One-command local Hub over a running dev-local stack. Launches the CURRENT-CODE Hub (apps/hub api+ui from a mesh-platform checkout) pointed at an existing `mesh dev` session — auto-assembles `HUB_TENANT`/`HUB_SCOPE_ENV`/`HUB_SCOPE_TENANTS` (session platform context), `TEMPORAL_ADDRESS` (session tunnel), `AWS_*` (session scratch profile), `DEV_USER_*`+`DEV_USER_TOKEN_URL` (session dev identity; starts its own token-server if the session predates it, so tokens stay fresh past ~1h). Refuses to launch with an empty tenant scope (which the Hub renders as silently blank). Runs in tmux session `mesh-hub-dev-<api-port>`, so several local Hubs coexist once each is given an API port of its own (both ports default the same in every worktree). | `dev`: `--session <name>`, `--tenants <csv>`, `--port` (or `MESH_HUB_DEV_PORT`, default 9000; the containerized `mesh start` Hub uses the separate `MESH_HUB_PORT`), `--api-port` (or `MESH_HUB_DEV_API_PORT`, default 3002; also names the tmux session), `--platform-dir <dir>` (or `MESH_PLATFORM_DIR`), `--print-env`, `--kill` |
 | `mesh create-app` | — | Scaffold a tenant app. Composable mode (primitives) or legacy template mode. Interactive when TTY + missing flags. Run at the root of an **empty** `{tenant}-mesh-apps` git clone (a `.git` with no `package.json`/`apps/`/`tenants/` and no enclosing pnpm workspace), it first generates the repo-level shape — `pnpm-workspace.yaml` over `apps/*`, private root `package.json`, scoped-registry `.npmrc`, base `tsconfig.json`, `.gitignore`, `README.md`, `apps/` — then scaffolds the app. Never overwrites an existing file. | `--tenant`, `--name`, `--primitives <csv>` (`service,database,temporal,bucket,events,email`), `--template <workflow\|api-auth\|api-role-gating\|external-service>`, `--test` (writes to `tests/tenants/`) |
@@ -194,7 +195,7 @@ Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/me
 | `mesh workflow` | `extract-ir <path>`, `inventory <path>`, `lint-process <path>` | `extract-ir`: parse Temporal workflow TS source → WorkflowIR graph (nodes+edges); prints JSON, uploads to S3, or writes the same files to a directory (so a package can ship IR it extracted at build time). A directory's `*.test.ts`/`*.spec.ts`/`*.d.ts` files are skipped. `inventory`: the as-built `{workflowType, commands, queries, activities}` the process lint diffs against. `lint-process`: parse + conformance-lint a process artifact against that inventory; exits 1 on any error-severity finding. | `extract-ir`: `--app <name>`, `--upload <bucket>`, `--out <dir>` (`--upload` and `--out` each need `--app`); `extract-ir`/`lint-process`: `--process <path>` (else a sibling `process/*.process.json` is discovered); `lint-process`: `--predicates <csv>`, `--selectors <csv>` — the CLI cannot execute the worker's registries, so without a flag those findings are skipped (a note is printed) while every other rule still runs |
 | `mesh site` | `publish <name> <dir>`, `versions <name>`, `rollback <name> <version>` | Publish a built directory as an OAuth-protected static site served by Studio, content-addressed and incremental: `publish` walks and hashes the tree, uploads only the blobs the site does not already hold, then commits a version and points the site at it; `versions` lists what has been published, newest first; `rollback` points the site back at an earlier version. Three stateless calls against the agent-api, so a run that dies partway leaves nothing to clean up. | all: `--target <name>`, `--api-url <url>`, `--context <ctx>`; `publish`: `--version-id <id>`, `--no-activate` (publish without pointing the site at it) |
 | `mesh vcs` | `clone <repo> [dest]`, `get <repo> <path>`, `propose`, `rm <repo> <paths...>`, `proposals`/`show`/`diff`/`approve`/`reject`/`comment`/`request-changes`, `drafts <list\|show\|create\|submit\|discard>` | Versioned content repos (`mesh.vcs`). Repos are real git repos over smart HTTP but **read-only** — every change goes through a proposal. `clone` wires the bearer auth header into the clone; `propose` submits the working tree (binary content is base64-encoded from the bytes, not the extension, so images survive intact); **`rm` proposes deletions of files or folders with no clone at all**, and `--dry-run` lists what would go without proposing anything. | all: `--url <base>`, `--token <t>`, `--context <ctx>`; `propose`: `-m/--message`, `--revise <id>`, `--merge-parent <sha>`; `rm`: `-m/--message`, `--dry-run` |
-| `mesh temporal` | `describe <wfId> [runId]`, `history <wfId> [runId]`, `recover-conversation <wfId> [runId]`, `capture-history <wfId> [runId]` | Inspect Temporal workflows for the current app/stack; reconstruct an agent conversation transcript from durable history when the worker can't replay it; capture a full history to a local replay fixture. | shared: `--stack`, `--address`, `--namespace`; `history`: `-n/--limit <200>`, `-f/--follow`, `--no-compact`, `-p/--show-payloads` (decrypts via `TEMPORAL_ENCODING_KEY` from the K8s secret); `recover-conversation`: `--out <path>`, `--json`, `--snapshot` (structured `{conversationId,messages,artifacts,focus}` blob); `capture-history`: `--out <path>` (default `~/.mesh/replay-histories/<wfId>.json`, do not commit) | <!-- skill-lint-disable-next-line — row documents the mesh-owned kubectl wrappers; the backticked `aws eks get-token` describes what the CLI runs internally, not an operator step -->
+| `mesh temporal` | `list`, `describe <wfId> [runId]`, `history <wfId> [runId]`, `recover-conversation <wfId> [runId]`, `capture-history <wfId> [runId]` | Inspect Temporal workflows for the current app/stack: `list` finds them through visibility (by type, status, parent, or any visibility query), and `history` names each event from the Temporal SDK's own event enum; reconstruct an agent conversation transcript from durable history when the worker can't replay it; capture a full history to a local replay fixture. | shared: `--stack`, `--address`, `--namespace`; `list`: `--type <workflowType>`, `--status <status>`, `--parent <workflowId>`, `--query <visibilityQuery>` (AND-ed with the flags), `-n/--limit <20>`, `--json`; `history`: `-n/--limit <200>`, `-f/--follow`, `--no-compact`, `-p/--show-payloads` (decrypts via `TEMPORAL_ENCODING_KEY` from the K8s secret); `recover-conversation`: `--out <path>`, `--json`, `--snapshot` (structured `{conversationId,messages,artifacts,focus}` blob); `capture-history`: `--out <path>` (default `~/.mesh/replay-histories/<wfId>.json`, do not commit) | <!-- skill-lint-disable-next-line — row documents the mesh-owned kubectl wrappers; the backticked `aws eks get-token` describes what the CLI runs internally, not an operator step -->
 | `mesh kubectl` / `mesh logs` / `mesh exec` | `kubectl [args…]`, `logs [service\|deployment/x\|k=v]`, `exec <service> -- <cmd>` | Cluster access for a **deployed** app — debug CrashLoops/logs without broader creds. Assumes the app's `mesh:deployerRole`, builds a session kubeconfig from the platform `eks` SSM export (`aws eks get-token` — no `eks:DescribeCluster` / `~/.kube/config` needed), shells out to kubectl. Defaults the namespace to the app's own (deployer RBAC is tenant-namespace-scoped). **Use `--stack <name>` to target the deployed stack (e.g. `dev`, not `dev-local`).** | `--stack <name>`; `logs`: `-f/--follow`, `--tail <200>`, `-c/--container`, `--previous`; `exec`: `-c/--container` |
 
 ## Core workflows

package/skills/mesh/references/worktrees.md

@@ -2,7 +2,10 @@
 
 Run the **same plain `mesh dev`** from each worktree's app dir — there is nothing special to
 configure. `mesh dev` derives a deterministic token from the worktree path and threads it through
-the tmux session name, the tmpdir session-state + env-file dir and the Temporal task-queue suffix, so
+the tmux session name, the tmpdir session-state + env-file dir and the Temporal task-queue suffix —
+and, on a workstation (`mesh workstation init`), the HTTPS route names, which become
+`<app>-<service>-<worktree>` (the worktree's slug without its branch-type prefix or trailing hash;
+`--route-suffix <name>` overrides it; the primary checkout gets no suffix) — so
 two worktrees don't kill each other's session — as long as their directory basenames differ, since the
 session name carries the worktree's sanitized basename, not the hash. The reserved **service-port
 block is derived from (worktree, app)**, not the worktree alone — a repo can hold several apps whose