@mesh-tech/mesh-cli 0.36.0 → 0.37.0

package/dist/src/commands/dev.js

@@ -19,7 +19,11 @@ import { fingerprintWorkflowSource } from '../utils/workflow-fingerprint.js';
 import { buildLaunchCommand, envFileName, waitForPort, writeEnvFile } from './dev-launch.js';
 import { buildLocalDevOutput, detectLocalTenant, ensureLocalPlatformRunning, hasStackBacking, localAppNamespace } from './local/dev-local.js';
 import { ensureAppTenantAuth, ensureSignInApp, registerLocalApp } from './local/auth-provision.js';
-import { localAwsEnv, ensureTemporalNamespace } from './local/seed.js';
+import { localAwsEnv, ensureTemporalNamespace, LOCAL_AWS_CONFIG, LOCAL_ENV } from './local/seed.js';
+import { publishLocalDocs, readLocalPublishDeclaration, unpublishLocalDocs } from './local/publish-docs.js';
+import { actAsEnv, publishLocalHubActAsKey } from './local/act-as-local.js';
+import { ensureLocalApiKey, ensureLocalStaffKey, readLocalKeyDeclaration } from './local/local-api-key.js';
+import { api as zitadelApi, readHubAuth, readSeederPat } from './local/seed-zitadel.js';
 import { composeExternalUp, composeExternalsDown, externalMode, localProbesRemove, parseExternalsSelection, readLocalMocks, seedLocalMock, } from './local/mocks.js';
 import { logShipperPath } from './local/dev-local.js';
 import { writeAppServiceProbes } from './local/stack.js';
@@ -565,9 +569,49 @@ export function buildChildAwsEnv(awsEnv, method, profile, opts) {
     }
     return result;
 }
-function rebaseServiceSrc(src, monorepoRoot) {
+export function readDotEnvFile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).replace(/^export\s+/, '').trim();
+        let value = line.slice(eq + 1).trim();
+        if (value[0] === '"' || value[0] === "'") {
+            const close = value.indexOf(value[0], 1);
+            value = close > 0 ? value.slice(1, close) : value.slice(1);
+        }
+        else {
+            const hash = value.search(/\s#/);
+            if (hash >= 0)
+                value = value.slice(0, hash).trimEnd();
+        }
+        out[key] = value;
+    }
+    return out;
+}
+async function unpublishSessionDocs(localDocs) {
+    if (!localDocs)
+        return;
+    const removed = await unpublishLocalDocs(localDocs.tenant, localDocs.app, LOCAL_AWS_CONFIG);
+    if (removed.length > 0)
+        logInfo(`Took ${localDocs.app}'s docs off the local Hub (${removed.join(', ')}).`);
+}
+export function rebaseServiceSrc(src, monorepoRoot) {
     if (!monorepoRoot)
         return src;
+    if (src === '.' || src === './')
+        return src;
     const rel = monorepoRelativeSrc(src);
     if (rel === null)
         return src;
@@ -1623,6 +1667,7 @@ export function registerDevCommand(program) {
                     dockerDevDown(sessionName);
                     composeExternalsDown(loadSessionState(sessionName)?.composeExternals);
                     localProbesRemove(loadSessionState(sessionName)?.externalProbeFiles);
+                    await unpublishSessionDocs(loadSessionState(sessionName)?.localDocs);
                     removeSessionState(sessionName);
                     logSuccess(`Killed docker dev session: ${sessionName}`);
                 }
@@ -1634,6 +1679,7 @@ export function registerDevCommand(program) {
             if (options.kill) {
                 composeExternalsDown(loadSessionState(sessionName)?.composeExternals);
                 localProbesRemove(loadSessionState(sessionName)?.externalProbeFiles);
+                await unpublishSessionDocs(loadSessionState(sessionName)?.localDocs);
                 try {
                     const devOutput = loadSessionState(sessionName)?.devOutput;
                     if (devOutput) {
@@ -1672,6 +1718,7 @@ export function registerDevCommand(program) {
         if (options.kill) {
             composeExternalsDown(loadSessionState(sessionName)?.composeExternals);
             localProbesRemove(loadSessionState(sessionName)?.externalProbeFiles);
+            await unpublishSessionDocs(loadSessionState(sessionName)?.localDocs);
             if (loadSessionState(sessionName)?.runner === 'docker') {
                 dockerDevDown(sessionName);
                 removeSessionState(sessionName);
@@ -1774,7 +1821,9 @@ export function registerDevCommand(program) {
                 return;
             }
             let signInServices = [];
+            let provisioned;
             let appVersion;
+            let appDisplayName;
             try {
                 const tenant = localTenant;
                 const app = rawDevOutput.app ?? projectName;
@@ -1793,10 +1842,13 @@ export function registerDevCommand(program) {
                     }
                     if (typeof appPkg?.version === 'string')
                         appVersion = appPkg.version;
+                    if (typeof appPkg?.mesh?.displayName === 'string' && appPkg.mesh.displayName) {
+                        appDisplayName = appPkg.mesh.displayName;
+                    }
                 }
                 catch {
                 }
-                await ensureAppTenantAuth({ tenant, app, services: authServices, roles: authRoles });
+                provisioned = await ensureAppTenantAuth({ tenant, app, services: authServices, roles: authRoles });
                 await ensureTemporalNamespace(localAppNamespace(tenant, app));
             }
             catch (err) {
@@ -1828,6 +1880,7 @@ export function registerDevCommand(program) {
                     tenant: localTenant,
                     app: devOutput.app ?? projectName,
                     version: appVersion,
+                    ...(appDisplayName ? { displayName: appDisplayName } : {}),
                     services: Object.keys(devOutput.services),
                     ports: Object.fromEntries(Object.entries(devOutput.services).map(([name, svc]) => [name, svc.port])),
                     kinds: Object.fromEntries(Object.entries(devOutput.services).flatMap(([name, svc]) => svc.kind ? [[name, svc.kind]] : [])),
@@ -1839,6 +1892,100 @@ export function registerDevCommand(program) {
             catch (err) {
                 logWarn(`Local registry registration skipped: ${err instanceof Error ? err.message : err}`);
             }
+            let localDocs;
+            try {
+                const appPkg = JSON.parse(fs.readFileSync(path.join(appRoot, 'package.json'), 'utf-8'));
+                const declaration = readLocalPublishDeclaration(appPkg, appRoot);
+                if (declaration.docs || declaration.authzMetadata || declaration.problems.length > 0) {
+                    const app = devOutput.app ?? projectName;
+                    const serviceNames = Object.keys(devOutput.services).filter((n) => !n.startsWith('mock-'));
+                    const httpService = declaration.docs?.service ?? serviceNames[0];
+                    const service = httpService ? devOutput.services[httpService] : undefined;
+                    if (!httpService || !service?.port) {
+                        logWarn(`mesh.docs names service '${httpService ?? ''}', which this app does not run — docs not published.`);
+                    }
+                    else {
+                        const serviceDir = path.resolve(appRoot, service.src);
+                        const env = service.env ?? (service.env = {});
+                        const serviceEnv = {
+                            ...readDotEnvFile(path.join(serviceDir, '.env')),
+                            ...Object.fromEntries(Object.entries(process.env).filter((e) => typeof e[1] === 'string')),
+                            ...Object.fromEntries(Object.entries(env).map(([k, v]) => [k, v.value])),
+                        };
+                        const published = await publishLocalDocs({
+                            appRoot,
+                            tenant: localTenant,
+                            app,
+                            httpPort: service.port,
+                            serviceEnv,
+                            ...(provisioned
+                                ? { zitadel: { orgId: provisioned.orgId, projectId: provisioned.projectId, issuer: 'http://localhost:8080' } }
+                                : {}),
+                            awsConfig: LOCAL_AWS_CONFIG,
+                            declaration,
+                        });
+                        for (const [key, value] of Object.entries(published.pins))
+                            env[key] = { value };
+                        for (const [key, value] of Object.entries(published.authzEnv))
+                            env[key] = { value };
+                        if (published.sandbox)
+                            env.INTEGRATION_SANDBOX = { value: published.sandbox };
+                        if (published.actAs) {
+                            const publication = await publishLocalHubActAsKey(LOCAL_AWS_CONFIG);
+                            if (!publication) {
+                                logWarn('The local Hub has no machine key yet — try-it cannot reach this app. Run: mesh start');
+                            }
+                            else {
+                                for (const [key, value] of Object.entries(actAsEnv(publication, localTenant, LOCAL_ENV, app))) {
+                                    env[key] = { value };
+                                }
+                                const relays = declaration.docs?.integrationTryIt ?? [];
+                                if (relays.length > 0)
+                                    env.INTEGRATION_TRY_IT_INTEGRATIONS = { value: relays.join(",") };
+                            }
+                        }
+                        if (published.docsPublished) {
+                            localDocs = { tenant: localTenant, app };
+                            logInfo(`Published ${app}'s docs to the local Hub (sandbox: ${published.sandbox}` +
+                                `${published.actAs ? ', try-it on' : ', try-it off'}` +
+                                `${Object.keys(published.pins).length ? `; pinned ${Object.entries(published.pins).map(([k, v]) => `${k}=${v}`).join(' ')}` : ''}).`);
+                        }
+                        if (published.authzPublished) {
+                            logInfo(`Published ${app}'s API-key metadata to the local Hub` +
+                                `${Object.keys(published.authzEnv).length ? ' — its schema is on the local SpiceDB, so key bundles take effect in the app' : ''}.`);
+                            const keyDecl = readLocalKeyDeclaration(appPkg);
+                            const hubProjectId = readHubAuth()?.projectId;
+                            if (keyDecl && hubProjectId) {
+                                try {
+                                    const staffKey = await ensureLocalStaffKey({
+                                        pat: readSeederPat(),
+                                        api: zitadelApi,
+                                        hubProjectId,
+                                        awsConfig: LOCAL_AWS_CONFIG,
+                                    });
+                                    const key = await ensureLocalApiKey({ tenant: localTenant, app, declaration: keyDecl, staffKey });
+                                    logInfo(key.kind === 'minted'
+                                        ? `Minted local API key '${key.name}' for ${app} (${keyDecl.bundles.join(', ') || 'no bundles'}) — try-it runs as it.`
+                                        : `Local API key '${key.name}' for ${app} is active — try-it runs as it.`);
+                                }
+                                catch (err) {
+                                    logWarn(`No local API key for ${app}: ${err instanceof Error ? err.message : err} — mint one on the app's Access tab.`);
+                                }
+                            }
+                            else if (keyDecl) {
+                                logWarn(`No local API key for ${app}: the local Hub is not seeded yet (run: mesh start).`);
+                            }
+                        }
+                        for (const note of published.notes)
+                            logWarn(`docs: ${note}`);
+                        for (const problem of published.problems)
+                            logWarn(`docs source: ${problem}`);
+                    }
+                }
+            }
+            catch (err) {
+                logWarn(`Local docs publishing stopped: ${err instanceof Error ? err.message : err}`);
+            }
             const composeExternals = [];
             const externalProbeFiles = [];
             for (const [name, decl] of Object.entries(selectedMocks)) {
@@ -1913,6 +2060,7 @@ export function registerDevCommand(program) {
                     runner: 'docker',
                     composeExternals,
                     externalProbeFiles,
+                    ...(localDocs ? { localDocs } : {}),
                 });
                 console.log('');
                 logSuccess(`Dev session started (docker): ${sessionName}`);
@@ -1936,6 +2084,7 @@ export function registerDevCommand(program) {
                 runner: 'tmux',
                 composeExternals,
                 externalProbeFiles,
+                ...(localDocs ? { localDocs } : {}),
             });
             return;
         }

package/dist/src/commands/docs.js

@@ -122,6 +122,7 @@ async function buildDocs(configPathArg) {
     }
     logSuccess(`Docs build complete (${generatedSpecs.size} OpenAPI file${generatedSpecs.size === 1 ? "" : "s"})`);
 }
+const DOCS_PREVIEW_PORT = "4410";
 const CLI_REFERENCE_PATH = "docs/portal/generated/cli-reference.md";
 async function renderCliReference() {
     const [{ createProgram }, { extractCliReference, renderCliReferenceMarkdown }] = await Promise.all([
@@ -240,6 +241,38 @@ export function registerDocsCommand(program) {
         const { runDocsServeStatic } = await import("../docs/start.js");
         await runDocsServeStatic(opts);
     })());
+    docs
+        .command("preview")
+        .description("Render one app's docs source locally — its docs.yaml, Markdown guides and OpenAPI reference, as the Hub's Docs tab shows them — with no Hub and no platform. Every problem the deploy would refuse is printed and shown on the page; try-it runs in the Hub only")
+        .argument("<dir>", "the directory that holds docs.yaml, or the docs.yaml file itself")
+        .option("-p, --port <port>", "port to serve on, on localhost (0 picks a free one; a port in use fails)", DOCS_PREVIEW_PORT)
+        .option("-o, --out <file>", "write the assembled docs-source bundle (JSON) to this file and exit — the file HUB_LOCAL_DOCS_SOURCES points a local Hub at")
+        .option("-s, --spec <file>", "the OpenAPI spec to document, overriding docs.yaml's spec — pass the one the deploy reads (the ApiSurface's docs.spec, or its doc package's openapi.json); default: docs.yaml's spec, else openapi.json beside it")
+        .option("--check", "print the problems and exit 1 when there are any, without serving (CI / pre-deploy)", false)
+        .action((dir, opts) => guarded(async () => {
+        const { runDocsPreview } = await import("../docs/preview.js");
+        const ok = await runDocsPreview({ target: dir, port: opts.port, out: opts.out, spec: opts.spec, check: opts.check });
+        if (!ok)
+            process.exitCode = 1;
+    })());
+    docs
+        .command("convert")
+        .description("Write a starter docs.yaml — a native docs source the Hub renders itself — from the inputs of an ApiSurface's site-shaped docs block (spec, pages, landingPage), then assemble it as the deploy does and print every problem left and the ApiSurface edit to make. Exits 1 while problems remain; replaces nothing without --force")
+        .requiredOption("-s, --spec <file>", "the OpenAPI spec the surface documents (the block's docs.spec)")
+        .option("--pages <dir>", "the block's docs.pages directory of Markdown guides")
+        .option("--landing <page>", "the block's docs.landingPage — a file, or a page id under --pages (default: the index page under --pages, when there is one)")
+        .option("--title <title>", "the source's title (default: the spec's info.title)")
+        .option("-o, --out <dir>", "where docs.yaml is written (default: the pages directory's parent, else the spec's directory)")
+        .option("--fix-pages", "rewrite pages for the native rules: a leading # heading becomes the front-matter title, and a landing file outside --pages is copied to <pages>/index.md; .mdx pages are reported, never converted", false)
+        .option("--force", "replace an existing docs.yaml, and a page the landing copy would land on", false)
+        .option("--root <dir>", "the Pulumi program's directory, which the printed ApiSurface edit's paths are relative to (default: the working directory)")
+        .option("--prefix <prefix>", "the block's pages prefix ({ dir, prefix }): the old site served pages under /<prefix>/; the conversion lists the page ids that lose it")
+        .action((opts) => guarded(async () => {
+        const { runDocsConvert } = await import("../docs/convert.js");
+        const ok = await runDocsConvert(opts);
+        if (!ok)
+            process.exitCode = 1;
+    })());
     docs
         .command("list")
         .description("List the published docs versions (each is an @mesh-tech/* baseline)")

package/dist/src/commands/local/act-as-local.d.ts

@@ -0,0 +1,5 @@
+import { type HubActAsExports } from "@mesh-tech/api-registry";
+export declare const LOCAL_OPS_HUB_SECRET_ID = "mesh/local/dev/zitadel/ops-hub";
+export declare function hubActAsPublication(secretString: string): HubActAsExports;
+export declare function publishLocalHubActAsKey(awsConfig: object): Promise<HubActAsExports | undefined>;
+export declare function actAsEnv(publication: HubActAsExports, tenant: string, env: string, surface: string): Record<string, string>;

package/dist/src/commands/local/act-as-local.js

@@ -0,0 +1,41 @@
+import { createPublicKey } from "node:crypto";
+import { actAsAudience, hubActAsPath, parseHubActAsExports } from "@mesh-tech/api-registry";
+import { LOCAL_ENV, LOCAL_TENANT } from "./seed.js";
+export const LOCAL_OPS_HUB_SECRET_ID = "mesh/local/dev/zitadel/ops-hub";
+export function hubActAsPublication(secretString) {
+    const parsed = JSON.parse(secretString);
+    if (typeof parsed.keyId !== "string" || typeof parsed.key !== "string" || typeof parsed.userId !== "string") {
+        throw new Error("the Hub's machine key has no keyId/key/userId");
+    }
+    const jwk = createPublicKey(parsed.key).export({ format: "jwk" });
+    if (jwk.kty !== "RSA" || !jwk.n || !jwk.e)
+        throw new Error("the Hub's machine key is not an RSA key");
+    return parseHubActAsExports({
+        issuer: parsed.userId,
+        keys: [{ kid: parsed.keyId, kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", use: "sig" }],
+    });
+}
+export async function publishLocalHubActAsKey(awsConfig) {
+    const { SecretsManagerClient, GetSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
+    const { SSMClient, PutParameterCommand } = await import("@aws-sdk/client-ssm");
+    const secret = await new SecretsManagerClient(awsConfig)
+        .send(new GetSecretValueCommand({ SecretId: LOCAL_OPS_HUB_SECRET_ID }))
+        .catch(() => null);
+    if (!secret?.SecretString)
+        return undefined;
+    const publication = hubActAsPublication(secret.SecretString);
+    await new SSMClient(awsConfig).send(new PutParameterCommand({
+        Name: hubActAsPath(LOCAL_TENANT, LOCAL_ENV),
+        Type: "String",
+        Overwrite: true,
+        Value: JSON.stringify(publication),
+        Description: "Hub act-as key — the public half of the local Hub's machine key",
+    }));
+    return publication;
+}
+export function actAsEnv(publication, tenant, env, surface) {
+    return {
+        INTEGRATION_ACT_AS_KEYS: JSON.stringify(publication),
+        INTEGRATION_ACT_AS_AUDIENCE: actAsAudience(tenant, env, surface),
+    };
+}

package/dist/src/commands/local/auth-provision.d.ts

@@ -14,6 +14,7 @@ export declare function registerLocalApp(args: AppTenantAuthArgs & {
     ports?: Record<string, number>;
     links?: string[];
     version?: string;
+    displayName?: string;
     kinds?: Record<string, string>;
 }): Promise<string>;
 export declare function reconcileRegistryFromZitadel(): Promise<{

package/dist/src/commands/local/auth-provision.js

@@ -138,6 +138,7 @@ export async function registerLocalApp(args) {
         services: args.services,
         ports: args.ports ?? {},
         ...(args.version ? { version: args.version } : {}),
+        ...(args.displayName ? { displayName: args.displayName } : {}),
         deployedAt: new Date().toISOString(),
     }, "Local run metadata (mesh dev --local)");
     logSuccess(`Registered app in the local registry → ${base}`);

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

@@ -11,6 +11,7 @@ import { LOCAL_AWS_CONFIG, localAwsEnv, seedLocalPlatform, verifyFabric } from "
 import { LOGIN_CONTEXT, readHubAuth, seedMockIdps, seedZitadel, TEST_USERS } from "./seed-zitadel.js";
 import { idpEndpoints, mockIdpComposeEnv, MOCK_OIDC_PORT, MOCK_SAML_PORT } from "./mock-idps.js";
 import { publishHubAuthzCatalog } from "./seed-hub-catalog.js";
+import { removeAllAliasContainers } from "./publish-docs.js";
 import { describePortConflicts, findPortConflicts, hostPortsOf } from "./helpers.js";
 const WAIT_TIMEOUT_MS = 180_000;
 const WAIT_POLL_MS = 3_000;
@@ -313,6 +314,9 @@ export function registerLocalCommands(program) {
         if (foreign && !opts.force) {
             throw new MeshCliError(`The running local platform was started from a different checkout (${foreign}) — another project may be using it.`, { remediation: { command: "mesh stop --force   # stop it anyway" } });
         }
+        const aliases = removeAllAliasContainers();
+        if (aliases.length > 0)
+            logInfo(`Removed ${aliases.length} local docs alias container(s).`);
         const args = ["down"];
         if (opts.destroy)
             args.push("-v");

package/dist/src/commands/local/local-api-key.d.ts

@@ -0,0 +1,44 @@
+export declare const LOCAL_CLI_SECRET_ID = "mesh/local/dev/zitadel/local-cli";
+export interface LocalKeyDeclaration {
+    name: string;
+    bundles: string[];
+    rateLimit: number;
+}
+export declare function readLocalKeyDeclaration(pkg: unknown): LocalKeyDeclaration | undefined;
+export declare function jwtBearerAssertion(key: {
+    keyId: string;
+    key: string;
+    userId: string;
+}, audience: string, nowSeconds?: number): string;
+type ZitadelApi = (pat: string, method: string, apiPath: string, body?: unknown) => Promise<any>;
+export declare function ensureLocalStaffKey(input: {
+    pat: string;
+    api: ZitadelApi;
+    hubProjectId: string;
+    awsConfig: object;
+}): Promise<{
+    keyId: string;
+    key: string;
+    userId: string;
+}>;
+export type LocalKeyOutcome = {
+    kind: "kept";
+    name: string;
+    id: string;
+} | {
+    kind: "minted";
+    name: string;
+    id: string;
+    clientId: string;
+};
+export declare function ensureLocalApiKey(input: {
+    tenant: string;
+    app: string;
+    declaration: LocalKeyDeclaration;
+    staffKey: {
+        keyId: string;
+        key: string;
+        userId: string;
+    };
+}): Promise<LocalKeyOutcome>;
+export {};

package/dist/src/commands/local/local-api-key.js

@@ -0,0 +1,115 @@
+import { createSign, randomUUID } from "node:crypto";
+import { LOCAL_ENV } from "./seed.js";
+export const LOCAL_CLI_SECRET_ID = "mesh/local/dev/zitadel/local-cli";
+const ISSUER = "http://localhost:8080";
+const HUB_API = "http://localhost:4568";
+export function readLocalKeyDeclaration(pkg) {
+    const authz = pkg?.mesh?.authz;
+    if (typeof authz?.metadata !== "string")
+        return undefined;
+    const key = (authz.localKey ?? {});
+    return {
+        name: typeof key.name === "string" && key.name ? key.name : "local-try-it",
+        bundles: Array.isArray(key.bundles) ? key.bundles.filter((b) => typeof b === "string") : [],
+        rateLimit: typeof key.rateLimit === "number" && key.rateLimit > 0 ? key.rateLimit : 600,
+    };
+}
+export function jwtBearerAssertion(key, audience, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const b64 = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+    const header = b64({ alg: "RS256", kid: key.keyId });
+    const payload = b64({ iss: key.userId, sub: key.userId, aud: audience, iat: nowSeconds, exp: nowSeconds + 300 });
+    const signature = createSign("RSA-SHA256").update(`${header}.${payload}`).sign(key.key).toString("base64url");
+    return `${header}.${payload}.${signature}`;
+}
+export async function ensureLocalStaffKey(input) {
+    const { SecretsManagerClient, GetSecretValueCommand, CreateSecretCommand, PutSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
+    const sm = new SecretsManagerClient(input.awsConfig);
+    const ensureGrant = async (userId) => {
+        try {
+            await input.api(input.pat, "POST", `/management/v1/users/${userId}/grants`, {
+                projectId: input.hubProjectId,
+                roleKeys: ["ops"],
+            });
+        }
+        catch (err) {
+            if (err.status !== 409)
+                throw err;
+        }
+    };
+    const existing = await sm.send(new GetSecretValueCommand({ SecretId: LOCAL_CLI_SECRET_ID })).catch(() => null);
+    if (existing?.SecretString) {
+        const kept = JSON.parse(existing.SecretString);
+        await ensureGrant(kept.userId);
+        return kept;
+    }
+    const userName = "mesh-local-cli";
+    const found = await input.api(input.pat, "POST", "/management/v1/users/_search", {
+        queries: [{ userNameQuery: { userName, method: "TEXT_QUERY_METHOD_EQUALS" } }],
+    });
+    let userId = found?.result?.[0]?.id;
+    if (!userId) {
+        const created = await input.api(input.pat, "POST", "/management/v1/users/machine", {
+            userName,
+            name: "mesh CLI (local)",
+            description: "Local staff caller the mesh CLI uses against the local Hub (mesh dev --local)",
+            accessTokenType: "ACCESS_TOKEN_TYPE_JWT",
+        });
+        userId = created?.userId;
+    }
+    if (!userId)
+        throw new Error("the local Zitadel did not create the CLI's staff caller");
+    await ensureGrant(userId);
+    const created = await input.api(input.pat, "POST", `/management/v1/users/${userId}/keys`, { type: "KEY_TYPE_JSON" });
+    if (!created?.keyDetails)
+        throw new Error("the local Zitadel returned no key for the CLI's staff caller");
+    const raw = JSON.parse(Buffer.from(created.keyDetails, "base64").toString("utf8"));
+    const key = { keyId: raw.keyId, key: raw.key, userId: raw.userId };
+    await sm
+        .send(new CreateSecretCommand({ Name: LOCAL_CLI_SECRET_ID, SecretString: JSON.stringify(key) }))
+        .catch(() => sm.send(new PutSecretValueCommand({ SecretId: LOCAL_CLI_SECRET_ID, SecretString: JSON.stringify(key) })));
+    return key;
+}
+async function staffToken(key) {
+    const res = await fetch(`${ISSUER}/oauth/v2/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            assertion: jwtBearerAssertion(key, ISSUER),
+            scope: "openid profile",
+        }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.access_token)
+        throw new Error(`the local Zitadel refused a token: ${body.error_description ?? res.status}`);
+    return body.access_token;
+}
+export async function ensureLocalApiKey(input) {
+    const token = await staffToken(input.staffKey);
+    const base = `${HUB_API}/tenants/${encodeURIComponent(input.tenant)}/environments/${LOCAL_ENV}/api-keys`;
+    const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    const listed = await fetch(`${base}?app=${encodeURIComponent(input.app)}`, { headers });
+    if (!listed.ok)
+        throw new Error(`the local Hub refused the key list (${listed.status}: ${await listed.text()})`);
+    const keys = (await listed.json());
+    const kept = keys.find((k) => k.name === input.declaration.name && k.status === "active");
+    if (kept)
+        return { kind: "kept", name: kept.name, id: kept.id };
+    const res = await fetch(base, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            app: input.app,
+            name: input.declaration.name,
+            rateLimit: input.declaration.rateLimit,
+            idempotencyKey: `mesh-local-${randomUUID()}`,
+            ...(input.declaration.bundles.length
+                ? { assignments: input.declaration.bundles.map((bundle) => ({ bundle, reason: "mesh dev --local try-it key" })) }
+                : {}),
+        }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.id)
+        throw new Error(`the local Hub did not mint the key (${res.status} ${body.code ?? ""}: ${body.error ?? ""})`);
+    return { kind: "minted", name: input.declaration.name, id: body.id, clientId: body.credentials?.clientId ?? "" };
+}

package/dist/src/commands/local/local-spicedb.d.ts

@@ -0,0 +1,95 @@
+export declare const LOCAL_SPICEDB_INSTANCE_ID = "mesh-local";
+export declare const LOCAL_SPICEDB_KEY = "local-dev-key";
+export declare const LOCAL_SPICEDB_KEY_SECRET = "mesh/local/dev/spicedb/preshared-key";
+export interface LocalSpicedbRef {
+    tenant: string;
+    env: string;
+    instanceId: string;
+}
+export declare function localSpicedbInstancePath(tenant: string): string;
+export declare function localSpicedbInstanceValue(): {
+    grpcEndpoint: string;
+    httpEndpoint: string;
+    namespace: string;
+    presharedKeySecretName: string;
+    configSecretName: string;
+    owner: {
+        kind: "shared-stack";
+        name: string;
+    };
+};
+export declare function localSpicedbRef(tenant: string): LocalSpicedbRef;
+export declare function localAuthzServiceEnv(tenant: string, app: string): Record<string, string>;
+export interface ZedSchema {
+    uses: string[];
+    blocks: {
+        name: string;
+        text: string;
+    }[];
+}
+export declare function parseZed(schema: string): ZedSchema;
+export declare function zedBlocks(schema: string): {
+    name: string;
+    text: string;
+}[];
+export declare function mergeZedSchemas(existing: string, incoming: string): string;
+export type LocalSpicedbOwners = Record<string, string>;
+export declare const LOCAL_SPICEDB_OWNERS_SECRET = "mesh/local/dev/spicedb/schema-owners";
+export interface LocalSpicedbConflict {
+    type: string;
+    owner: string;
+}
+export type LocalSpicedbSchemaPlan = {
+    ok: true;
+    schema: string;
+    owners: LocalSpicedbOwners;
+    changed: boolean;
+} | {
+    ok: false;
+    conflicts: LocalSpicedbConflict[];
+};
+export declare function planLocalSpicedbSchema(input: {
+    existing: string;
+    incoming: string;
+    owners: LocalSpicedbOwners;
+    app: string;
+}): LocalSpicedbSchemaPlan;
+export declare class LocalSpicedbConflictError extends Error {
+    readonly app: string;
+    readonly conflicts: LocalSpicedbConflict[];
+    constructor(app: string, conflicts: LocalSpicedbConflict[]);
+}
+export declare function zedOf(value: unknown): string;
+export interface LocalSpicedbIo {
+    readSchema(): Promise<string>;
+    writeSchema(schema: string): Promise<void>;
+    readOwners(): Promise<LocalSpicedbOwners>;
+    writeOwners(owners: LocalSpicedbOwners): Promise<void>;
+    writeSeed(updates: unknown[]): Promise<void>;
+    register(): Promise<void>;
+}
+export declare function localSpicedbIo(tenant: string, awsConfig: object): LocalSpicedbIo;
+export declare function writeLocalSpicedbSchema(app: string, zed: string, io: LocalSpicedbIo): Promise<boolean>;
+export interface LocalSpicedbConnection {
+    instanceRefs: LocalSpicedbRef[];
+    env: Record<string, string>;
+    notes: string[];
+}
+export declare function connectLocalSpicedb(input: {
+    app: string;
+    tenant: string;
+    schema: () => Promise<unknown>;
+    seed?: () => Promise<unknown>;
+    io: LocalSpicedbIo;
+}): Promise<LocalSpicedbConnection>;
+export declare function registerLocalSpicedb(tenant: string, awsConfig: object): Promise<void>;
+export interface LocalSeedRelationship {
+    resource: string;
+    relation: string;
+    subject: string;
+}
+export declare function seedUpdates(value: unknown): {
+    updates: unknown[];
+    problems: string[];
+};
+export declare function writeLocalSpicedbSeed(updates: unknown[]): Promise<void>;