@ggui-ai/cli 0.1.0-rc.1

package/dist/internal/artifact-publish.js

@@ -0,0 +1,1141 @@
+/**
+ * Shared publish core for `ggui gadget publish` and `ggui blueprint publish`.
+ *
+ * An internal helper that both kind-discriminated router files
+ * (`gadget-command.ts` + `blueprint-command.ts`) delegate to. The CLI
+ * verb's `kind` parameter is enforced against the on-disk manifest's
+ * `kind` discriminator — a `ggui gadget publish` in a directory with
+ * `ggui.blueprint.json` (or vice versa) prints a friendly redirect
+ * pointing at the correct verb instead of trying to publish.
+ *
+ * Walks the operator-facing flow end-to-end:
+ *
+ *   1. Resolve registry URL — `--registry` flag, then `GGUI_REGISTRY`
+ *      env, then the nearest `ggui.json#registry`. No fallback to a
+ *      hardcoded default — operators MUST opt into a registry
+ *      explicitly so a typo doesn't accidentally publish to prod.
+ *   2. Load + validate `ggui.gadget.json` / `ggui.blueprint.json` in CWD;
+ *      enforce that the manifest kind matches the verb the operator typed.
+ *   3. (Gadgets only) bundle the entry via esbuild (ESM / es2022 /
+ *      platform=neutral) with manifest.peerDeps + react family
+ *      hoisted to externals.
+ *   4. Authenticate — either `--auth=bearer` (explicit token for self-
+ *      hosted / local registries) OR the default hosted-auth flow via
+ *      the configured registry. The hosted-auth implementation here
+ *      talks to the cloud registry's hosted identity provider, but
+ *      the public-surface naming stays vendor-neutral (see
+ *      `./auth-strategy.ts`).
+ *   5. Conformance preflight — POST `/conformance/check` with the
+ *      manifest + bundle text. Fail-fast so a malformed bundle
+ *      doesn't hit S3.
+ *   6. Sign the bundle (gadget) or canonical manifest (blueprint)
+ *      with the operator's Ed25519 private key. Generate the
+ *      keypair on first publish + print the public-key id for
+ *      registry-side registration.
+ *   7. POST `/publish` with `{manifest, bundle?, bundleSha384?, signature}`.
+ *   8. Print the install command operators paste into their
+ *      `ggui.json` consumers.
+ *
+ * `--dry-run` runs steps 1-5 and prints what would be uploaded; no
+ * POST happens.
+ *
+ * **HTTP contract (locked).**
+ *
+ *   POST <registry>/publish
+ *     Headers: `Authorization: Bearer <jwt>`, `Content-Type: application/json`
+ *     Body   : { manifest, bundle?, bundleSha384?, signature }
+ *     201    : { artifactId, version, manifestUrl, bundleUrl?, signatureUrl?, installCommand }
+ *     400    : { code: 'version_exists' | 'unknown_key' | 'conformance_failed' | … , message }
+ *     401    : auth bad
+ *     501    : endpoint stubbed
+ *
+ *   POST <registry>/conformance/check
+ *     Headers: `Authorization: Bearer <jwt>`, `Content-Type: application/json`
+ *     Body   : { manifest, bundle? }
+ *     200    : { ok: true }
+ *     200    : { ok: false, issues: [{code, message, path?}] }
+ *     5xx    : transient — caller retries or surfaces
+ */
+import { build as esbuild } from 'esbuild';
+// Cloud-internal hosted-auth implementation. The vendor SDK is named
+// here because this is the leaf implementation file the OSS-facing
+// `acquireHostedAuthJwt` wraps; the public surface (CLI flags, help
+// text, README, the auth-strategy module) is vendor-neutral.
+import { CognitoIdentityProviderClient, InitiateAuthCommand, } from '@aws-sdk/client-cognito-identity-provider';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { URL } from 'node:url';
+import { GGUI_BLUEPRINT_JSON_FILENAME, GGUI_GADGET_JSON_FILENAME, parseBlueprintManifest, parseGadgetManifest, } from '@ggui-ai/artifact-manifest';
+import { canonicalJson, derivePublicKeyId, generateEd25519Keypair, publicKeyFromPrivate, signBundleEd25519, signBundleSigstore, } from '@ggui-ai/gadget-signing';
+import { resolveOidcToken, OidcResolutionError, } from './oidc-token.js';
+import { sha384 } from '@noble/hashes/sha512.js';
+import { isTokenFresh, loadRegistryToken, saveRegistryToken, } from './auth-cache.js';
+import { getPrivateKeyPath, hasKeypair, readPrivateKey, scopeOf, writePrivateKey, } from './key-store.js';
+import { acquireAuthToken, parseAuthFlags, AUTH_HELP_FRAGMENT, } from './auth-strategy.js';
+/**
+ * Build verb-specific help text. Takes the `kind` so the rendered
+ * lines say `ggui gadget publish` / `ggui blueprint publish` rather
+ * than a generic placeholder.
+ */
+export function buildPublishHelp(kind) {
+    const verb = `ggui ${kind} publish`;
+    return `${verb} — push a ${kind} to the marketplace registry
+
+Usage:
+  ${verb} [--registry <url>] [--dry-run] [--key <path>] [--identity-token <jwt>] [--auth=bearer [--token <token>]]
+
+Options:
+  --registry <url>   Registry to publish to. Precedence:
+                       1. --registry flag
+                       2. GGUI_REGISTRY env
+                       3. ggui.json#registry (nearest, walking up from CWD)
+                     No hardcoded default — operators must opt in.
+
+  --dry-run          Run validation, bundling, auth, and conformance
+                     preflight; skip the POST. Prints what would be
+                     uploaded.
+
+  --key <path>       Path to a 32-byte Ed25519 private key. Used to sign
+                     **private** ${kind}s. Default:
+                       ~/.ggui/keys/<scope>/private.key
+
+  --identity-token <jwt>
+                     OIDC identity token used to sign **public** ${kind}s
+                     via sigstore (cosign keyless). If absent, the CLI
+                     resolves a token from (in order):
+                       1. GGUI_OIDC_TOKEN env
+                       2. GitHub Actions ambient OIDC
+                       3. interactive browser flow (TTY only)
+
+${AUTH_HELP_FRAGMENT}
+`;
+}
+/**
+ * Parse argv tail (excluding `ggui {gadget,blueprint} publish`) into
+ * flags. Pure — no IO. Returned `error` is a single-line
+ * operator-facing string. The `--auth` + `--token` flags are peeled
+ * out via {@link parseAuthFlags} so the publish flag loop stays
+ * focused on its own surface.
+ */
+export function parseArtifactPublishFlags(args) {
+    // First, peel off the auth-related flags.
+    const authParsed = parseAuthFlags(args);
+    if ('error' in authParsed) {
+        return { dryRun: false, help: false, error: authParsed.error };
+    }
+    const authFlags = authParsed.flags;
+    const rest = authParsed.rest;
+    let registry;
+    let dryRun = false;
+    let key;
+    let identityToken;
+    let help = false;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (arg === '--registry') {
+            const value = rest[i + 1];
+            if (typeof value !== 'string' || value.length === 0) {
+                return { dryRun, help, error: '--registry requires a value' };
+            }
+            registry = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--key') {
+            const value = rest[i + 1];
+            if (typeof value !== 'string' || value.length === 0) {
+                return { dryRun, help, error: '--key requires a value' };
+            }
+            key = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--identity-token' || (typeof arg === 'string' && arg.startsWith('--identity-token='))) {
+            // Accept both `--identity-token <jwt>` and `--identity-token=<jwt>`.
+            const eq = typeof arg === 'string' ? arg.indexOf('=') : -1;
+            let value;
+            if (eq !== -1 && typeof arg === 'string') {
+                value = arg.slice(eq + 1);
+            }
+            else {
+                value = rest[i + 1];
+                i += 1;
+            }
+            if (typeof value !== 'string' || value.length === 0) {
+                return { dryRun, help, error: '--identity-token requires a value' };
+            }
+            identityToken = value;
+            continue;
+        }
+        return { dryRun, help, error: `unknown flag: ${arg}` };
+    }
+    return {
+        ...(registry !== undefined ? { registry } : {}),
+        dryRun,
+        ...(key !== undefined ? { key } : {}),
+        ...(identityToken !== undefined ? { identityToken } : {}),
+        ...(authFlags.auth !== undefined || authFlags.token !== undefined
+            ? { auth: authFlags }
+            : {}),
+        help,
+    };
+}
+// ---------------------------------------------------------------------------
+// orchestration
+// ---------------------------------------------------------------------------
+/**
+ * Run the publish flow. Pure entry point — all IO + network is
+ * threaded through injectable seams in `opts` so tests are
+ * deterministic.
+ *
+ * `opts.kind` is the verb the operator typed; manifest-kind mismatch
+ * (e.g. `ggui gadget publish` in a directory with `ggui.blueprint.json`)
+ * surfaces a friendly redirect at step 2 + exits non-zero.
+ */
+export async function runArtifactPublish(opts) {
+    const verb = `ggui ${opts.kind} publish`;
+    const cwd = opts.cwd ?? process.cwd();
+    const stdout = opts.stdout ?? ((s) => void process.stdout.write(s));
+    const stderr = opts.stderr ?? ((s) => void process.stderr.write(s));
+    const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    // ---- step 1: resolve registry URL ----
+    const registryRes = resolveRegistryUrl({ flag: opts.registry, env: process.env, cwd });
+    if (!registryRes.ok) {
+        stderr(`${verb}: ${registryRes.message}\n`);
+        return { ok: false, exitCode: 1, error: { code: 'no_registry_resolved', message: registryRes.message } };
+    }
+    const registryUrl = registryRes.url;
+    stdout(`registry: ${registryUrl} (${registryRes.source})\n`);
+    // ---- step 2: load manifest ----
+    const manifestRes = loadManifest(cwd);
+    if (!manifestRes.ok) {
+        stderr(`${verb}: ${manifestRes.error.message}\n`);
+        if (manifestRes.error.code === 'manifest_invalid' && manifestRes.error.details) {
+            stderr(`  ${manifestRes.error.details}\n`);
+        }
+        return { ok: false, exitCode: 1, error: manifestRes.error };
+    }
+    const { manifest, manifestPath } = manifestRes;
+    // ---- step 2a: enforce verb / manifest kind alignment ----
+    if (manifest.kind !== opts.kind) {
+        const foundFile = manifest.kind === 'blueprint'
+            ? GGUI_BLUEPRINT_JSON_FILENAME
+            : GGUI_GADGET_JSON_FILENAME;
+        const correctVerb = `ggui ${manifest.kind} publish`;
+        const message = `this is a ${manifest.kind} repo (found ${foundFile}).\n` +
+            `Run \`${correctVerb}\` instead.`;
+        stderr(`${verb}: ${message}\n`);
+        return {
+            ok: false,
+            exitCode: 1,
+            error: { code: 'manifest_kind_mismatch', message },
+        };
+    }
+    stdout(`manifest: ${manifest.kind} ${`${manifest.scope}/${manifest.name}`}@${manifest.version}\n`);
+    // ---- step 3: bundle (gadgets only) ----
+    let bundleBytes;
+    let bundleSha384;
+    if (manifest.kind === 'gadget') {
+        const bundleRes = await bundleGadget(manifest, dirname(manifestPath));
+        if (!bundleRes.ok) {
+            stderr(`${verb}: bundle failed — ${bundleRes.error}\n`);
+            return { ok: false, exitCode: 1, error: { code: 'bundle_failed', message: bundleRes.error } };
+        }
+        bundleBytes = bundleRes.bytes;
+        // Base64-encoded sha384 — wire format the publish handler verifies
+        // against its own server-side hash.
+        bundleSha384 = Buffer.from(sha384(bundleBytes)).toString('base64');
+        stdout(`bundle: ${bundleBytes.length} bytes · sha384=${bundleSha384.slice(0, 12)}…\n`);
+    }
+    // ---- step 4: authenticate ----
+    // Two paths:
+    //   --auth=bearer → token from flag or GGUI_REGISTRY_TOKEN
+    //   default       → hosted auth via the configured registry (cloud)
+    let jwt;
+    const authFlags = opts.auth ?? {};
+    try {
+        jwt = await acquireAuthToken({
+            flags: authFlags,
+            env: process.env,
+            cwd,
+            registryUrl,
+            acquireHostedAuthJwt: async (deps) => {
+                const hosted = await acquireHostedAuthJwt({
+                    registryUrl: deps.registryUrl,
+                    env: deps.env,
+                    cwd: deps.cwd,
+                    hostedAuthClient: opts.hostedAuthClient,
+                    prompt: opts.prompt,
+                    now,
+                });
+                if (!hosted.ok) {
+                    throw new HostedAuthError(hosted.error);
+                }
+                stdout(`auth: ${hosted.fromCache ? 'cached' : 'fresh'} JWT for ${hosted.token.username}\n`);
+                return hosted.token.idToken;
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof HostedAuthError) {
+            stderr(`${verb}: ${err.payload.message}\n`);
+            return { ok: false, exitCode: 1, error: err.payload };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        stderr(`${verb}: ${msg}\n`);
+        return { ok: false, exitCode: 1, error: { code: 'auth_failed', message: msg } };
+    }
+    if (authFlags.auth === 'bearer') {
+        stdout(`auth: bearer token (length=${jwt.length})\n`);
+    }
+    // ---- step 5: conformance preflight ----
+    const preflightRes = await runConformancePreflight({
+        registryUrl,
+        jwt,
+        manifest,
+        bundleBytes,
+        fetchImpl,
+    });
+    if (!preflightRes.ok) {
+        stderr(`${verb}: conformance preflight failed\n`);
+        if (preflightRes.error.code === 'conformance_failed' && preflightRes.error.issues) {
+            for (const issue of preflightRes.error.issues) {
+                stderr(`  - ${issue.code}: ${issue.message}${issue.path ? ` (${issue.path})` : ''}\n`);
+            }
+        }
+        else {
+            stderr(`  ${preflightRes.error.message}\n`);
+        }
+        return { ok: false, exitCode: 1, error: preflightRes.error };
+    }
+    stdout(`conformance: ok\n`);
+    // ---- step 6 + 7: sign — branched on manifest.visibility ----
+    //
+    // `private` → Ed25519 keypair signing (existing path: load/generate
+    // a 32-byte private key at ~/.ggui/keys/<scope>/private.key, sign
+    // the bundle hash, ship the publicKeyId for the registry's
+    // AuthorKeys lookup).
+    //
+    // `public`  → sigstore keyless signing (Fulcio cert + Rekor inclusion
+    // proof). Needs a short-lived OIDC token resolved from one of four
+    // sources (flag → env → GH-Actions → interactive browser).
+    const signaturePayload = manifest.kind === 'gadget'
+        ? bundleBytes
+        : new TextEncoder().encode(canonicalJson(manifest));
+    let signature;
+    if (manifest.visibility === 'private') {
+        const keyRes = await loadOrGenerateKey({
+            artifactId: `${manifest.scope}/${manifest.name}`,
+            keyFlag: opts.key,
+            stdout,
+        });
+        if (!keyRes.ok) {
+            stderr(`${verb}: ${keyRes.error.message}\n`);
+            return { ok: false, exitCode: 1, error: keyRes.error };
+        }
+        signature = await signBundleEd25519({
+            bundleBytes: signaturePayload,
+            privateKey: keyRes.privateKey,
+            publicKeyId: keyRes.publicKeyId,
+        });
+        stdout(`signature: ${signature.algorithm} · ${keyRes.publicKeyId}\n`);
+    }
+    else {
+        // public → sigstore keyless. Resolve OIDC first.
+        let oidc;
+        try {
+            oidc = await resolveOidcToken({
+                ...(opts.identityToken !== undefined
+                    ? { identityTokenFlag: opts.identityToken }
+                    : {}),
+                env: process.env,
+                isTty: process.stdout.isTTY === true,
+                stdout,
+            });
+        }
+        catch (err) {
+            const message = err instanceof OidcResolutionError ? err.message : err instanceof Error ? err.message : String(err);
+            const oidcCode = err instanceof OidcResolutionError ? err.code : undefined;
+            stderr(`${verb}: ${message}\n`);
+            return {
+                ok: false,
+                exitCode: 1,
+                error: {
+                    code: 'oidc_resolution_failed',
+                    message,
+                    ...(oidcCode !== undefined ? { oidcCode } : {}),
+                },
+            };
+        }
+        stdout(`signature: sigstore (OIDC source=${oidc.source})\n`);
+        signature = await signBundleSigstore({
+            bundleBytes: signaturePayload,
+            identityToken: oidc.token,
+        });
+        stdout(`signature: ${signature.algorithm} ok\n`);
+    }
+    // ---- step 8: POST (or skip for dry-run) ----
+    if (opts.dryRun) {
+        stdout(`dry-run: would POST to ${registryUrl}/publish\n`);
+        stdout(`dry-run: ${`${manifest.scope}/${manifest.name}`}@${manifest.version}\n`);
+        return {
+            ok: true,
+            exitCode: 0,
+            success: {
+                artifactId: `${manifest.scope}/${manifest.name}`,
+                version: manifest.version,
+                manifestUrl: '(dry-run — no manifestUrl)',
+                installCommand: `ggui ${opts.kind} install ${`${manifest.scope}/${manifest.name}`}@${manifest.version} --registry=${registryUrl}`,
+                registryUrl,
+                dryRun: true,
+            },
+        };
+    }
+    const publishRes = await postPublish({
+        registryUrl,
+        jwt,
+        manifest,
+        bundleBytes,
+        bundleSha384,
+        signature,
+        fetchImpl,
+    });
+    if (!publishRes.ok) {
+        stderr(`${verb}: ${publishRes.error.message}\n`);
+        return { ok: false, exitCode: 1, error: publishRes.error };
+    }
+    // ---- step 9: success ----
+    stdout(`\npublished: ${publishRes.body.artifactId}@${publishRes.body.version}\n`);
+    stdout(`manifest:  ${publishRes.body.manifestUrl}\n`);
+    if (publishRes.body.bundleUrl)
+        stdout(`bundle:    ${publishRes.body.bundleUrl}\n`);
+    if (publishRes.body.signatureUrl)
+        stdout(`signature: ${publishRes.body.signatureUrl}\n`);
+    stdout(`\nInstall:\n  ${publishRes.body.installCommand}\n`);
+    return {
+        ok: true,
+        exitCode: 0,
+        success: {
+            artifactId: publishRes.body.artifactId,
+            version: publishRes.body.version,
+            manifestUrl: publishRes.body.manifestUrl,
+            ...(publishRes.body.bundleUrl !== undefined ? { bundleUrl: publishRes.body.bundleUrl } : {}),
+            ...(publishRes.body.signatureUrl !== undefined ? { signatureUrl: publishRes.body.signatureUrl } : {}),
+            installCommand: publishRes.body.installCommand,
+            registryUrl,
+            dryRun: false,
+        },
+    };
+}
+export function resolveRegistryUrl(opts) {
+    if (opts.flag && opts.flag.length > 0) {
+        if (!isValidUrl(opts.flag)) {
+            return {
+                ok: false,
+                message: `--registry value is not a valid URL: ${opts.flag}`,
+            };
+        }
+        return { ok: true, url: stripTrailingSlash(opts.flag), source: 'flag' };
+    }
+    const envValue = opts.env['GGUI_REGISTRY'];
+    if (envValue && envValue.length > 0) {
+        if (!isValidUrl(envValue)) {
+            return {
+                ok: false,
+                message: `GGUI_REGISTRY is not a valid URL: ${envValue}`,
+            };
+        }
+        return { ok: true, url: stripTrailingSlash(envValue), source: 'env' };
+    }
+    const ggui = findAndReadGguiJsonRegistry(opts.cwd);
+    if (ggui.found) {
+        if (!isValidUrl(ggui.registry)) {
+            return {
+                ok: false,
+                message: `ggui.json#registry at ${ggui.path} is not a valid URL: ${ggui.registry}`,
+            };
+        }
+        return { ok: true, url: stripTrailingSlash(ggui.registry), source: 'ggui.json' };
+    }
+    return {
+        ok: false,
+        message: 'no registry resolved. Set one of:\n' +
+            '  --registry <url>\n' +
+            '  GGUI_REGISTRY env var\n' +
+            '  "registry": "<url>" in the nearest ggui.json',
+    };
+}
+/**
+ * Walk up from `startDir` looking for the nearest `ggui.json` with a
+ * top-level `registry` string field. Returns the first match.
+ *
+ * This is intentionally hand-rolled (not via `@ggui-ai/project-config`)
+ * because the schema there has not grown a typed `registry` field yet;
+ * until it does, the field is read opportunistically without forcing a
+ * parallel schema migration.
+ */
+function findAndReadGguiJsonRegistry(startDir) {
+    let dir = resolve(startDir);
+    for (let i = 0; i <= 16; i++) {
+        const candidate = join(dir, 'ggui.json');
+        if (existsSync(candidate)) {
+            const raw = readFileSync(candidate, 'utf8');
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // Malformed — fall through; the operator's `ggui serve` will
+                // raise a friendlier error than we can synthesize here.
+                return { found: false };
+            }
+            const registry = extractRegistryField(parsed);
+            if (typeof registry === 'string' && registry.length > 0) {
+                return { found: true, registry, path: candidate };
+            }
+            return { found: false };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { found: false };
+}
+function extractRegistryField(x) {
+    if (typeof x !== 'object' || x === null)
+        return undefined;
+    return x.registry;
+}
+function isValidUrl(s) {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'http:' || u.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+function loadManifest(cwd) {
+    const gadgetPath = join(cwd, GGUI_GADGET_JSON_FILENAME);
+    const blueprintPath = join(cwd, GGUI_BLUEPRINT_JSON_FILENAME);
+    const hasGadget = existsSync(gadgetPath);
+    const hasBlueprint = existsSync(blueprintPath);
+    if (hasGadget && hasBlueprint) {
+        return {
+            ok: false,
+            error: {
+                code: 'manifest_invalid',
+                message: `both ${GGUI_GADGET_JSON_FILENAME} and ${GGUI_BLUEPRINT_JSON_FILENAME} present in CWD — only one allowed per repo`,
+            },
+        };
+    }
+    if (!hasGadget && !hasBlueprint) {
+        return {
+            ok: false,
+            error: {
+                code: 'manifest_missing',
+                message: `no ${GGUI_GADGET_JSON_FILENAME} or ${GGUI_BLUEPRINT_JSON_FILENAME} in ${cwd}`,
+            },
+        };
+    }
+    const path = hasGadget ? gadgetPath : blueprintPath;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'manifest_invalid',
+                message: `${path} is not valid JSON`,
+                details: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+    try {
+        const manifest = hasGadget ? parseGadgetManifest(parsed) : parseBlueprintManifest(parsed);
+        return { ok: true, manifest, manifestPath: path };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'manifest_invalid',
+                message: `${path} failed schema validation`,
+                details: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+}
+async function bundleGadget(manifest, manifestDir) {
+    const entry = isAbsolute(manifest.bundle)
+        ? manifest.bundle
+        : join(manifestDir, manifest.bundle);
+    if (!existsSync(entry)) {
+        return { ok: false, error: `entry not found: ${entry}` };
+    }
+    // React + jsx-runtime are always external — gadget consumers
+    // bring their own React. peerDeps keys add to that base set.
+    const externals = new Set([
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        'react/jsx-dev-runtime',
+        ...(manifest.peerDeps ? Object.keys(manifest.peerDeps) : []),
+    ]);
+    try {
+        const result = await esbuild({
+            entryPoints: [entry],
+            bundle: true,
+            format: 'esm',
+            target: 'es2022',
+            platform: 'neutral',
+            minify: false,
+            write: false,
+            external: [...externals],
+            logLevel: 'silent',
+        });
+        if (result.outputFiles.length !== 1) {
+            return {
+                ok: false,
+                error: `esbuild produced ${result.outputFiles.length} files; expected 1`,
+            };
+        }
+        return { ok: true, bytes: new Uint8Array(result.outputFiles[0].contents) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Sentinel error that lets the bearer/hosted strategy router surface
+ * a structured `PublishError` without leaking through `throw any`.
+ */
+class HostedAuthError extends Error {
+    payload;
+    constructor(payload) {
+        super(payload.message);
+        this.payload = payload;
+    }
+}
+export async function acquireHostedAuthJwt(opts) {
+    // 1. Cached?
+    const cached = loadRegistryToken(opts.registryUrl);
+    if (cached && cached.registry === opts.registryUrl && isTokenFresh(cached, opts.now())) {
+        return { ok: true, token: cached, fromCache: true };
+    }
+    // 2. Need auth config (Cognito pool id + client id). Personal
+    // credentials never go in source-controlled ggui.json: auth config
+    // lives in env vars or a user-level secret store. No fallback to
+    // project config.
+    const authConfig = resolveCognitoConfig(opts.env);
+    if (!authConfig) {
+        return {
+            ok: false,
+            error: {
+                code: 'auth_config_missing',
+                message: 'registry hosted-auth config missing. Either:\n' +
+                    '  - pass --auth=bearer --token <token> (for self-hosted / local registries), or\n' +
+                    '  - set GGUI_REGISTRY_COGNITO_POOL_ID + GGUI_REGISTRY_COGNITO_APP_CLIENT_ID in your environment.',
+            },
+        };
+    }
+    // 3. Refresh-token path (cache exists but expired)
+    if (cached && cached.refreshToken) {
+        const refreshed = await tryRefresh({
+            ...(opts.hostedAuthClient ? { hostedAuthClient: opts.hostedAuthClient } : {}),
+            authConfig,
+            refreshToken: cached.refreshToken,
+            registryUrl: opts.registryUrl,
+            username: cached.username,
+            now: opts.now,
+        });
+        if (refreshed.ok) {
+            saveRegistryToken(refreshed.token);
+            return { ok: true, token: refreshed.token, fromCache: false };
+        }
+        // refresh failed — fall through to password flow
+    }
+    // 4. Password flow
+    const promptFn = opts.prompt ?? defaultPrompt;
+    let username;
+    let password;
+    try {
+        username = await promptFn('Registry username: ');
+        password = await promptFn('Registry password: ', { hidden: true });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'auth_failed',
+                message: `prompt failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    const idp = opts.hostedAuthClient ?? new CognitoIdentityProviderClient({});
+    const auth = await runUserPasswordAuth({
+        hostedAuthClient: idp,
+        authConfig,
+        username,
+        password,
+    });
+    if (!auth.ok) {
+        return { ok: false, error: { code: 'auth_failed', message: auth.error } };
+    }
+    const token = {
+        version: 1,
+        registry: opts.registryUrl,
+        idToken: auth.idToken,
+        accessToken: auth.accessToken,
+        refreshToken: auth.refreshToken,
+        expiresAt: opts.now() + auth.expiresIn,
+        username,
+        writtenAt: new Date().toISOString(),
+    };
+    saveRegistryToken(token);
+    return { ok: true, token, fromCache: false };
+}
+/**
+ * Resolve Cognito auth config from environment variables only.
+ *
+ * `ggui.json` is source-controlled, so personal credentials never go
+ * in git. The publish CLI's auth config comes exclusively from the
+ * canonical env-var pair:
+ *
+ *   `GGUI_REGISTRY_COGNITO_POOL_ID` + `GGUI_REGISTRY_COGNITO_APP_CLIENT_ID`
+ *
+ * The `GGUI_REGISTRY_` prefix matches other registry-scoped vars
+ * (`GGUI_REGISTRY_TOKEN`, `GGUI_REGISTRY`). There is deliberately no
+ * unprefixed `GGUI_COGNITO_*` fallback — a second accepted form would
+ * re-introduce env-var ambiguity.
+ *
+ * No project-config fallback. Operators who want per-project auth
+ * pinning use a per-project `.envrc` (direnv) or shell wrapper.
+ */
+function resolveCognitoConfig(env) {
+    const poolId = env['GGUI_REGISTRY_COGNITO_POOL_ID'];
+    const appClientId = env['GGUI_REGISTRY_COGNITO_APP_CLIENT_ID'];
+    if (poolId && appClientId) {
+        return { poolId, appClientId };
+    }
+    return null;
+}
+async function runUserPasswordAuth(opts) {
+    const input = {
+        AuthFlow: 'USER_PASSWORD_AUTH',
+        ClientId: opts.authConfig.appClientId,
+        AuthParameters: {
+            USERNAME: opts.username,
+            PASSWORD: opts.password,
+        },
+    };
+    try {
+        const cmd = new InitiateAuthCommand(input);
+        const res = await opts.hostedAuthClient.send(cmd);
+        return extractAuthResult(res);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function tryRefresh(opts) {
+    const idp = opts.hostedAuthClient ?? new CognitoIdentityProviderClient({});
+    const input = {
+        AuthFlow: 'REFRESH_TOKEN_AUTH',
+        ClientId: opts.authConfig.appClientId,
+        AuthParameters: {
+            REFRESH_TOKEN: opts.refreshToken,
+        },
+    };
+    try {
+        const res = await idp.send(new InitiateAuthCommand(input));
+        const extracted = extractAuthResult(res);
+        if (!extracted.ok)
+            return { ok: false, error: extracted.error };
+        // Cognito's REFRESH_TOKEN flow returns a new RefreshToken only
+        // when rotation is enabled on the pool. When absent, reuse the
+        // existing refresh token (still valid until its TTL).
+        const refreshToken = extracted.refreshToken.length > 0 ? extracted.refreshToken : opts.refreshToken;
+        return {
+            ok: true,
+            token: {
+                version: 1,
+                registry: opts.registryUrl,
+                idToken: extracted.idToken,
+                accessToken: extracted.accessToken,
+                refreshToken,
+                expiresAt: opts.now() + extracted.expiresIn,
+                username: opts.username,
+                writtenAt: new Date().toISOString(),
+            },
+        };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function extractAuthResult(res) {
+    const result = res.AuthenticationResult;
+    if (!result) {
+        return {
+            ok: false,
+            error: `Cognito did not return AuthenticationResult (challenge=${res.ChallengeName ?? 'none'})`,
+        };
+    }
+    if (typeof result.IdToken !== 'string' ||
+        typeof result.AccessToken !== 'string' ||
+        typeof result.ExpiresIn !== 'number') {
+        return {
+            ok: false,
+            error: 'Cognito AuthenticationResult missing IdToken/AccessToken/ExpiresIn',
+        };
+    }
+    return {
+        ok: true,
+        idToken: result.IdToken,
+        accessToken: result.AccessToken,
+        refreshToken: typeof result.RefreshToken === 'string' ? result.RefreshToken : '',
+        expiresIn: result.ExpiresIn,
+    };
+}
+async function defaultPrompt(label, opts = {}) {
+    // Minimal stdin reader. For hidden mode we toggle the TTY's `echo`
+    // off. The dependency-injected `prompt` in `runGadgetPublish` is
+    // the test seam — this is the fallback for real CLI use.
+    process.stdout.write(label);
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        throw new Error('stdin is not a TTY — pass --registry / set GGUI_REGISTRY and use a non-interactive auth path');
+    }
+    stdin.setEncoding('utf8');
+    if (opts.hidden) {
+        stdin.setRawMode(true);
+    }
+    let buf = '';
+    for await (const chunk of stdin) {
+        for (const ch of chunk) {
+            if (ch === '\r' || ch === '\n') {
+                if (opts.hidden)
+                    stdin.setRawMode(false);
+                process.stdout.write('\n');
+                return buf;
+            }
+            if (ch === '') {
+                // Ctrl-C — propagate via throw so the caller exits cleanly.
+                if (opts.hidden)
+                    stdin.setRawMode(false);
+                throw new Error('prompt cancelled');
+            }
+            if (ch === '' || ch === '\b') {
+                buf = buf.slice(0, -1);
+                continue;
+            }
+            buf += ch;
+            if (!opts.hidden)
+                process.stdout.write(ch);
+        }
+    }
+    if (opts.hidden)
+        stdin.setRawMode(false);
+    return buf;
+}
+async function runConformancePreflight(opts) {
+    const url = `${opts.registryUrl}/conformance/check`;
+    const body = JSON.stringify({
+        manifest: opts.manifest,
+        ...(opts.bundleBytes !== undefined
+            ? { bundle: Buffer.from(opts.bundleBytes).toString('base64') }
+            : {}),
+    });
+    let res;
+    try {
+        res = await opts.fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${opts.jwt}`,
+            },
+            body,
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'conformance_failed',
+                message: `network error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (!res.ok) {
+        let text = '';
+        try {
+            text = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        return {
+            ok: false,
+            error: {
+                code: 'conformance_failed',
+                message: `HTTP ${res.status} from /conformance/check${text ? `: ${text.slice(0, 200)}` : ''}`,
+            },
+        };
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'conformance_failed',
+                message: `response was not JSON: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    const parsedShape = parseConformanceResponse(parsed);
+    if (!parsedShape) {
+        return {
+            ok: false,
+            error: {
+                code: 'conformance_failed',
+                message: 'unrecognized conformance response shape',
+            },
+        };
+    }
+    if (parsedShape.ok === true) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        error: {
+            code: 'conformance_failed',
+            message: 'manifest/bundle failed conformance checks',
+            issues: parsedShape.issues,
+        },
+    };
+}
+function parseConformanceResponse(x) {
+    if (typeof x !== 'object' || x === null)
+        return null;
+    const r = x;
+    if (r.ok === true)
+        return { ok: true };
+    if (r.ok === false) {
+        if (!Array.isArray(r.issues))
+            return { ok: false, issues: [] };
+        const issues = [];
+        for (const entry of r.issues) {
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const e = entry;
+            if (typeof e.code !== 'string' || typeof e.message !== 'string')
+                continue;
+            issues.push({
+                code: e.code,
+                message: e.message,
+                ...(typeof e.path === 'string' ? { path: e.path } : {}),
+            });
+        }
+        return { ok: false, issues };
+    }
+    return null;
+}
+async function loadOrGenerateKey(opts) {
+    const scope = scopeOf(opts.artifactId);
+    if (opts.keyFlag) {
+        if (!existsSync(opts.keyFlag)) {
+            return {
+                ok: false,
+                error: {
+                    code: 'key_missing',
+                    message: `--key path not found: ${opts.keyFlag}`,
+                },
+            };
+        }
+        const privateKey = readPrivateKey(opts.keyFlag);
+        if (!privateKey) {
+            return {
+                ok: false,
+                error: {
+                    code: 'key_missing',
+                    message: `--key path could not be read: ${opts.keyFlag}`,
+                },
+            };
+        }
+        return {
+            ok: true,
+            privateKey,
+            publicKeyId: derivePublicKeyId(await publicKeyFromPrivate(privateKey)),
+        };
+    }
+    const defaultPath = getPrivateKeyPath(scope);
+    if (!hasKeypair(scope)) {
+        // First-publish path — generate + persist + print public-key id
+        // so the operator can register it with the registry's
+        // author-keys endpoint.
+        const fresh = await generateEd25519Keypair();
+        writePrivateKey(scope, fresh.privateKey, fresh.publicKey);
+        opts.stdout(`key: generated new keypair at ${defaultPath}\n` +
+            `key: publicKeyId=${fresh.publicKeyId}\n` +
+            `key: first-publish — register this public key with the registry by running \`ggui keys register --scope ${scope}\` if the registry returns \`unknown_key\`.\n`);
+        return {
+            ok: true,
+            privateKey: fresh.privateKey,
+            publicKeyId: fresh.publicKeyId,
+        };
+    }
+    const privateKey = readPrivateKey(defaultPath);
+    if (!privateKey) {
+        return {
+            ok: false,
+            error: {
+                code: 'key_missing',
+                message: `${defaultPath} exists but could not be read`,
+            },
+        };
+    }
+    return {
+        ok: true,
+        privateKey,
+        publicKeyId: derivePublicKeyId(await publicKeyFromPrivate(privateKey)),
+    };
+}
+async function postPublish(opts) {
+    const url = `${opts.registryUrl}/publish`;
+    const body = JSON.stringify({
+        manifest: opts.manifest,
+        ...(opts.bundleBytes !== undefined
+            ? {
+                bundle: Buffer.from(opts.bundleBytes).toString('base64'),
+                bundleSha384: opts.bundleSha384,
+            }
+            : {}),
+        signature: opts.signature,
+    });
+    let res;
+    try {
+        res = await opts.fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${opts.jwt}`,
+            },
+            body,
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'publish_failed',
+                message: `network error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (res.status === 501) {
+        return {
+            ok: false,
+            error: {
+                code: 'publish_stubbed',
+                message: `publish endpoint not yet live for ${opts.registryUrl} (HTTP 501).`,
+            },
+        };
+    }
+    if (res.status === 201) {
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: {
+                    code: 'publish_failed',
+                    message: `201 but response was not JSON: ${err instanceof Error ? err.message : String(err)}`,
+                    httpStatus: 201,
+                },
+            };
+        }
+        const body = parsePublishResponse(parsed);
+        if (!body) {
+            return {
+                ok: false,
+                error: {
+                    code: 'publish_failed',
+                    message: '201 but response body shape was not recognized',
+                    httpStatus: 201,
+                },
+            };
+        }
+        return { ok: true, body };
+    }
+    // Surface structured error codes when present.
+    let serverCode;
+    let message = `HTTP ${res.status}`;
+    try {
+        const parsed = await res.json();
+        if (typeof parsed === 'object' && parsed !== null) {
+            const r = parsed;
+            if (typeof r.code === 'string')
+                serverCode = r.code;
+            if (typeof r.message === 'string')
+                message = `${message}: ${r.message}`;
+        }
+    }
+    catch {
+        // ignore — fall back to status text
+    }
+    return {
+        ok: false,
+        error: {
+            code: 'publish_failed',
+            message,
+            httpStatus: res.status,
+            ...(serverCode !== undefined ? { serverCode } : {}),
+        },
+    };
+}
+function parsePublishResponse(x) {
+    if (typeof x !== 'object' || x === null)
+        return null;
+    const r = x;
+    if (typeof r.artifactId !== 'string' ||
+        typeof r.version !== 'string' ||
+        typeof r.manifestUrl !== 'string' ||
+        typeof r.installCommand !== 'string') {
+        return null;
+    }
+    return {
+        artifactId: r.artifactId,
+        version: r.version,
+        manifestUrl: r.manifestUrl,
+        installCommand: r.installCommand,
+        ...(typeof r.bundleUrl === 'string' ? { bundleUrl: r.bundleUrl } : {}),
+        ...(typeof r.signatureUrl === 'string' ? { signatureUrl: r.signatureUrl } : {}),
+    };
+}