@ggui-ai/cli 0.1.0-rc.1

package/dist/blueprint-create.js

@@ -0,0 +1,377 @@
+/**
+ * `ggui blueprint create <scope/name>` — scaffold a new blueprint repo.
+ *
+ * Sibling of `gadget-create.ts`. Blueprints differ from gadgets in two
+ * ways that justify a separate scaffolder (rather than a
+ * kind-discriminated single template):
+ *
+ *   - **Source body** — blueprints are TSX components, not bundled
+ *     hook libraries. The scaffold writes a `src/blueprint.tsx` with
+ *     a minimal React component + a `src/contract.ts` stub that
+ *     declares a `DataContract` for the LLM-driven cache-match path.
+ *   - **Manifest shape** — `ggui.blueprint.json` carries `source`,
+ *     `contract`, `fixtureProps`, `variance`. The scaffold synthesizes
+ *     a working manifest with the inline source body, so an author can
+ *     `cd <dir> && ggui blueprint publish` immediately after generation.
+ *
+ * The scaffold validates the synthesized manifest with
+ * `parseBlueprintManifest` before any write — template regressions
+ * fail LOUD at the scaffolder rather than silently shipping a broken
+ * `ggui.blueprint.json`.
+ *
+ * Kept pure / testable — no `process.exit`, no direct stdout writes.
+ * `blueprint-command.ts` composes this with the real argv + writes
+ * the banner.
+ */
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { GGUI_BLUEPRINT_JSON_FILENAME, parseBlueprintManifest, } from '@ggui-ai/artifact-manifest';
+import { parseScopeName } from './gadget-create.js';
+/** Default version for a freshly scaffolded blueprint. */
+const DEFAULT_VERSION = '0.0.1';
+/** Default visibility — public matches the marketplace's primary path. */
+const DEFAULT_VISIBILITY = 'public';
+/**
+ * Parse the `ggui blueprint create` flag tail. Returns a discriminated
+ * `{error}` vs. successful flags so the caller doesn't throw on user
+ * input.
+ */
+export function parseBlueprintCreateFlags(args) {
+    if (args.length === 0) {
+        return { error: '__help__' };
+    }
+    let scopeName;
+    let dir;
+    let description;
+    let visibility;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h')
+            return { error: '__help__' };
+        if (arg === '--dir') {
+            const value = args[i + 1];
+            if (typeof value !== 'string' || value.length === 0) {
+                return { error: '--dir requires a value' };
+            }
+            dir = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--description') {
+            const value = args[i + 1];
+            if (typeof value !== 'string' || value.length === 0) {
+                return { error: '--description requires a value' };
+            }
+            description = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--visibility') {
+            const value = args[i + 1];
+            if (value !== 'public' && value !== 'private') {
+                return { error: '--visibility must be "public" or "private"' };
+            }
+            visibility = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            return { error: `unknown flag: ${arg}` };
+        }
+        if (scopeName === undefined) {
+            scopeName = arg;
+            continue;
+        }
+        return { error: `unexpected positional argument: ${arg}` };
+    }
+    if (scopeName === undefined) {
+        return { error: 'missing required <scope/name> positional argument' };
+    }
+    const flags = {
+        scopeName,
+        ...(dir !== undefined ? { dir } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(visibility !== undefined ? { visibility } : {}),
+    };
+    return { flags };
+}
+/**
+ * Build the minimal TSX source body the scaffold ships as
+ * `src/blueprint.tsx`. Authors edit this in-place; once the source
+ * stabilizes the publish flow re-reads + inlines it into the manifest's
+ * `source` field at upload time.
+ */
+function buildBlueprintTsx(parsed) {
+    const componentName = toPascalCase(parsed.name);
+    return `/**
+ * ${parsed.scope}/${parsed.name} — ggui blueprint.
+ *
+ * Default-exports a React component the runtime renders against the
+ * declared DataContract. Replace this placeholder with your real UI.
+ */
+export interface ${componentName}Props {
+  readonly title?: string;
+}
+
+export default function ${componentName}(props: ${componentName}Props): JSX.Element {
+  return (
+    <section data-blueprint="${parsed.scope}/${parsed.name}">
+      <h1>{props.title ?? '${parsed.scope}/${parsed.name}'}</h1>
+    </section>
+  );
+}
+`;
+}
+/**
+ * Build the matching `src/contract.ts` stub — a minimal `DataContract`
+ * the blueprint registers under. Authors flesh out `propsSchema` to
+ * match the component's prop shape and add `clientCapabilities` /
+ * `commitSpec` as needed.
+ */
+function buildContractStub(parsed) {
+    return `/**
+ * DataContract for ${parsed.scope}/${parsed.name}. The runtime feeds
+ * the matching props into the default-exported component on render;
+ * the contract's hash also drives cache-match for the cold-gen short-
+ * circuit.
+ */
+export const contract = {
+  schemaVersion: '1' as const,
+  contextSpec: {
+    propsSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+      },
+    },
+  },
+} as const;
+`;
+}
+/** Convert a kebab-case blueprint name → PascalCase component name. */
+function toPascalCase(name) {
+    return name
+        .split('-')
+        .filter((s) => s.length > 0)
+        .map((s) => s[0].toUpperCase() + s.slice(1))
+        .join('');
+}
+/**
+ * Build + validate the {@link BlueprintManifest} BEFORE any write.
+ * A template regression that drifts (e.g. drops `source`) blows up
+ * here, before any file lands on disk, so authors don't see a corrupt
+ * scaffold.
+ */
+export function buildScaffoldManifest(args) {
+    const description = args.description ??
+        `${args.scope}/${args.name} — ggui marketplace blueprint.`;
+    const raw = {
+        kind: 'blueprint',
+        scope: args.scope,
+        name: args.name,
+        version: DEFAULT_VERSION,
+        visibility: args.visibility,
+        source: args.source,
+        description,
+        tags: [],
+    };
+    return parseBlueprintManifest(raw);
+}
+function buildPackageJson(args) {
+    return {
+        name: `${args.scope}/${args.name}`,
+        version: DEFAULT_VERSION,
+        ...(args.description !== undefined ? { description: args.description } : {}),
+        type: 'module',
+        files: ['src', GGUI_BLUEPRINT_JSON_FILENAME, 'README.md'],
+        devDependencies: {
+            typescript: '^5.0.0',
+            '@types/react': '^19.0.0',
+        },
+    };
+}
+function buildReadme(args) {
+    const summary = args.description ??
+        `${args.scope}/${args.name} — ggui marketplace blueprint.`;
+    return `# ${args.scope}/${args.name}
+
+${summary}
+
+## Develop
+
+\`\`\`bash
+pnpm install
+\`\`\`
+
+Edit \`src/blueprint.tsx\` (component body) and \`src/contract.ts\`
+(matching \`DataContract\`).
+
+## Publish
+
+\`\`\`bash
+ggui blueprint publish
+\`\`\`
+
+See [ggui blueprint docs](https://ggui.ai/docs/blueprints) for the full
+marketplace flow.
+`;
+}
+/** Refuse-to-overwrite check, matching gadget-create's posture. */
+async function isDirectoryEmpty(path) {
+    try {
+        const entries = await readdir(path);
+        return { exists: true, empty: entries.length === 0 };
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return { exists: false, empty: true };
+        }
+        throw err;
+    }
+}
+/**
+ * Run the blueprint scaffold end-to-end. Resolves the target dir,
+ * builds + validates the manifest, writes files. Returns a structured
+ * result so the CLI driver can render copy + exit code without
+ * re-deriving paths.
+ */
+export async function runBlueprintCreate(flags, options) {
+    const parsed = parseScopeName(flags.scopeName);
+    if (!parsed) {
+        return {
+            ok: false,
+            code: 'invalid-scope-name',
+            message: `"${flags.scopeName}" is not a valid <scope>/<name>. Expected \`@org/blueprint-name\` (e.g. \`@my-org/login-form\`).`,
+        };
+    }
+    // Blueprint name regex (`^[a-z0-9][a-z0-9_-]{0,63}$`) is enforced by
+    // the manifest schema; a structurally-valid scope/name with an
+    // invalid blueprint slug surfaces at parse time below as
+    // `manifest-invalid`. Bail early on the more obvious mismatches so
+    // the operator sees a crisp message.
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(parsed.name)) {
+        return {
+            ok: false,
+            code: 'invalid-name',
+            message: `"${parsed.name}" is not a valid blueprint name. Expected lowercase alphanum + hyphens / underscores, 1..64 chars, first char alphanumeric (e.g. \`login-form\`).`,
+        };
+    }
+    const { scope, name } = parsed;
+    const visibility = flags.visibility ?? DEFAULT_VISIBILITY;
+    const source = buildBlueprintTsx(parsed);
+    let manifest;
+    try {
+        manifest = buildScaffoldManifest({
+            scope,
+            name,
+            visibility,
+            source,
+            ...(flags.description !== undefined
+                ? { description: flags.description }
+                : {}),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'manifest-invalid',
+            message: err instanceof Error ? err.message : 'failed to validate manifest',
+        };
+    }
+    // `resolve` (not `join`): when `flags.dir` is an absolute path, it must
+    // win over `options.cwd`. `join('/repo', '/tmp/foo')` concatenates to
+    // `/repo/tmp/foo`; `resolve('/repo', '/tmp/foo')` correctly returns
+    // `/tmp/foo`. Relative paths still resolve against cwd.
+    const targetDir = resolve(options.cwd, flags.dir ?? name);
+    let dirState;
+    try {
+        dirState = await isDirectoryEmpty(targetDir);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'fs-error',
+            message: err instanceof Error ? err.message : 'failed to read target dir',
+        };
+    }
+    if (dirState.exists && !dirState.empty) {
+        return {
+            ok: false,
+            code: 'target-not-empty',
+            message: `target directory ${targetDir} is not empty. Refusing to overwrite — choose a different --dir or remove existing files.`,
+        };
+    }
+    try {
+        await mkdir(targetDir, { recursive: true });
+        await mkdir(join(targetDir, 'src'), { recursive: true });
+        const manifestPath = join(targetDir, GGUI_BLUEPRINT_JSON_FILENAME);
+        await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+        const pkg = buildPackageJson({
+            scope,
+            name,
+            ...(flags.description !== undefined
+                ? { description: flags.description }
+                : {}),
+        });
+        await writeFile(join(targetDir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`, 'utf-8');
+        await writeFile(join(targetDir, 'src', 'blueprint.tsx'), source, 'utf-8');
+        await writeFile(join(targetDir, 'src', 'contract.ts'), buildContractStub(parsed), 'utf-8');
+        await writeFile(join(targetDir, 'README.md'), buildReadme({
+            scope,
+            name,
+            ...(flags.description !== undefined
+                ? { description: flags.description }
+                : {}),
+        }), 'utf-8');
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'fs-error',
+            message: err instanceof Error ? err.message : 'failed to write files',
+        };
+    }
+    return {
+        ok: true,
+        targetDir,
+        files: [
+            GGUI_BLUEPRINT_JSON_FILENAME,
+            'package.json',
+            'src/blueprint.tsx',
+            'src/contract.ts',
+            'README.md',
+        ],
+        manifest,
+    };
+}
+export const BLUEPRINT_CREATE_HELP = `ggui blueprint create — scaffold a new blueprint repo
+
+Usage:
+  ggui blueprint create <scope/name> [options]
+
+Arguments:
+  <scope/name>     Required. \`@my-org/login-form\` style identifier.
+                   The scope (with leading \`@\`) becomes the manifest's
+                   \`scope\`; the segment after \`/\` becomes the \`name\`
+                   (must match \`^[a-z0-9][a-z0-9_-]{0,63}$\`).
+
+Options:
+  --dir <path>             Target directory. Defaults to \`./<name>\`.
+  --description <text>     One-line description threaded into the
+                           manifest + README.
+  --visibility <p>         \`public\` (default, sigstore-signed) or
+                           \`private\` (Ed25519-signed, org-only).
+  --help, -h               Show this help.
+
+Output:
+  <dir>/ggui.blueprint.json   Strict-schema manifest (validated before write).
+  <dir>/package.json          Workspace shell.
+  <dir>/src/blueprint.tsx     Default-exported React component stub.
+  <dir>/src/contract.ts       Matching \`DataContract\` stub.
+  <dir>/README.md             One-paragraph orientation.
+
+After scaffold:
+  cd <dir> && pnpm install
+  # implement the component in src/blueprint.tsx, then:
+  ggui blueprint publish     # publishes to the resolved registry.
+`;

package/dist/byok-resolver.d.ts

@@ -0,0 +1,141 @@
+/**
+ * BYOK ("bring your own key") provider-key resolver — the `ggui` CLI's
+ * personal-mode credential plumbing for local UI generation.
+ *
+ * Resolves a {@link ProviderKeyRef} for a given LLM provider through a
+ * deterministic two-step lookup. Used by `buildMcpServerBackend` to
+ * decide whether to call a real provider or fail fast with the
+ * canonical `'no-credentials'` error.
+ *
+ * **Resolution order, locked:**
+ *
+ *   1. **Environment variables** — checked first, always win. The
+ *      env-var names match the conventions every Node ecosystem uses
+ *      so operators who already export them for other tools (Claude
+ *      Code, OpenAI CLI, etc.) get OSS generation working with zero
+ *      extra config:
+ *
+ *        - `anthropic`   → `ANTHROPIC_API_KEY`
+ *        - `google`      → `GOOGLE_API_KEY`, then `GEMINI_API_KEY`
+ *                          (alias — Google publishes both)
+ *        - `openai`      → `OPENAI_API_KEY`
+ *        - `openrouter`  → `OPENROUTER_API_KEY`
+ *        - `bedrock`     → not env-resolvable. Bedrock auth flows
+ *                          through `AWS_*` env / IAM role chain at
+ *                          the SDK level; the resolver returns null
+ *                          and the (future) bedrock adapter pulls
+ *                          from the standard AWS credential chain.
+ *
+ *   2. **`~/.ggui/credentials.json`** — operator-persistent personal
+ *      store. Backed by `PlaintextFileProviderKeyStore` from
+ *      `@ggui-ai/mcp-server-core/plaintext` at the **global** app
+ *      scope. Single-user, single-tenant; multi-app or multi-user
+ *      deployments swap in a different `ProviderKeyStore` binding at
+ *      composition time and bypass this resolver entirely.
+ *
+ * **Explicitly NOT a source:** `ggui.json#secrets` or any other
+ * project-file location. Plaintext secrets in a project file that
+ * gets committed is a footgun, called out in the OSS-split plan
+ * (§2.A). This resolver never reads project config.
+ *
+ * **Failure mode:** missing key returns `null`. Callers map `null` to
+ * the canonical `ProviderError{kind:'no-credentials'}` from
+ * `@ggui-ai/ui-gen/provider-adapter` so OSS surfaces one consistent
+ * structured failure shape regardless of whether the operator never
+ * configured a key vs. configured the wrong provider.
+ */
+import type { LlmProvider, ProviderKeyStore } from '@ggui-ai/mcp-server-core';
+/**
+ * Per-process env interface. Narrow enough that tests can pass a
+ * plain object instead of mutating `process.env` globally — vitest
+ * workers share `process.env` so a clean injection seam matters.
+ */
+export type EnvLike = Readonly<Record<string, string | undefined>>;
+/** App-scope key under which the resolver reads + writes the store. */
+export declare const BYOK_GLOBAL_APP_SCOPE = "global";
+/**
+ * Provider → ordered list of env-var names to check. First non-empty
+ * wins. Single-name tuple for most providers; google has the
+ * `GOOGLE_API_KEY` / `GEMINI_API_KEY` alias pair.
+ *
+ * `bedrock` is intentionally absent — its auth chain lives outside
+ * this resolver (see module JSDoc).
+ */
+export declare const PROVIDER_ENV_NAMES: Readonly<Record<Exclude<LlmProvider, 'bedrock'>, readonly string[]>>;
+/**
+ * Successful resolution. The `source` field is load-bearing — it
+ * lets callers surface "BYOK from env" vs. "BYOK from credentials
+ * file" in operator-facing logs (banner / `ggui auth status` later)
+ * AND lets tests assert the precedence rule deterministically.
+ */
+export interface ByokKeyResolution {
+    readonly key: string;
+    readonly source: 'env' | 'credentials-file';
+    readonly provider: LlmProvider;
+    /**
+     * Which env-var name produced the key (for `source: 'env'`). Lets
+     * the operator-facing banner say "GEMINI_API_KEY" specifically when
+     * that's what fired, instead of a generic "google env".
+     */
+    readonly envName?: string;
+}
+export interface ByokResolverOptions {
+    /**
+     * Env source. Defaults to `process.env`. Tests pass a plain object
+     * so they don't have to mutate `process.env` (which leaks across
+     * vitest's shared worker pool).
+     */
+    readonly env?: EnvLike;
+    /**
+     * Override the credentials-file backed store. Defaults to a
+     * `PlaintextFileProviderKeyStore` reading {@link getCredentialsFile}
+     * — i.e. `~/.ggui/credentials.json` (or `$GGUI_CONFIG_DIR/credentials.json`
+     * when set). Production callers leave this unset; tests inject a
+     * fixture store or `null` to disable the file leg.
+     *
+     * Pass `null` (NOT `undefined`) to explicitly disable the file
+     * lookup. `undefined` triggers the default-store construction.
+     */
+    readonly fileStore?: ProviderKeyStore | null;
+}
+/**
+ * Per-call resolver options. Threaded through the request → handler →
+ * generator chain so the BYOK lookup at gen-time honors the request's
+ * authenticated identity.
+ */
+export interface ByokResolveOptions {
+    /**
+     * The end-user scope to consult AFTER the operator's platform key
+     * (env + credentials-file at scope='global') has been checked and
+     * missed. Operator-first fallback: if the operator set a key, every
+     * user uses it (operator pays). If the operator opted out, each
+     * user's own key (stored at this scope) is consulted.
+     *
+     * Absent or equal to `'global'`: no per-user fallback — only env +
+     * global file are checked. This is the personal-mode default.
+     *
+     * Production callers thread the request's authenticated identity
+     * here (e.g. `userId` for `kind:'user'`, `appId` for `kind:'app'`).
+     */
+    readonly userScope?: string;
+}
+/**
+ * Wire-level resolver type. Returned by {@link createByokResolver};
+ * shaped so call sites can DI a fake without importing the class.
+ */
+export interface ByokResolver {
+    resolve(provider: LlmProvider, opts?: ByokResolveOptions): Promise<ByokKeyResolution | null>;
+}
+/**
+ * Construct a {@link ByokResolver} bound to a specific env + file
+ * store. Returned object is stateless; one resolver instance can
+ * serve many lookups across a process.
+ *
+ * The resolver never throws. Missing key → `null`. Malformed
+ * credentials file → propagates the underlying file store's error
+ * (today: `PlaintextFileProviderKeyStore` throws a "not a valid v1
+ * document" error so the operator gets a clear signal instead of a
+ * silent miss).
+ */
+export declare function createByokResolver(opts?: ByokResolverOptions): ByokResolver;
+//# sourceMappingURL=byok-resolver.d.ts.map

package/dist/byok-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byok-resolver.d.ts","sourceRoot":"","sources":["../src/byok-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EACV,WAAW,EAEX,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAIlC;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEnE,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CACvC,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAM3D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,kBAAkB,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CACL,QAAQ,EAAE,WAAW,EACrB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,GAAE,mBAAwB,GAC7B,YAAY,CA4Ed"}

package/dist/byok-resolver.js

@@ -0,0 +1,89 @@
+import { PlaintextFileProviderKeyStore } from '@ggui-ai/mcp-server-core/plaintext';
+import { getCredentialsFile } from './paths.js';
+/** App-scope key under which the resolver reads + writes the store. */
+export const BYOK_GLOBAL_APP_SCOPE = 'global';
+/**
+ * Provider → ordered list of env-var names to check. First non-empty
+ * wins. Single-name tuple for most providers; google has the
+ * `GOOGLE_API_KEY` / `GEMINI_API_KEY` alias pair.
+ *
+ * `bedrock` is intentionally absent — its auth chain lives outside
+ * this resolver (see module JSDoc).
+ */
+export const PROVIDER_ENV_NAMES = {
+    anthropic: ['ANTHROPIC_API_KEY'],
+    google: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
+    openai: ['OPENAI_API_KEY'],
+    openrouter: ['OPENROUTER_API_KEY'],
+};
+/**
+ * Construct a {@link ByokResolver} bound to a specific env + file
+ * store. Returned object is stateless; one resolver instance can
+ * serve many lookups across a process.
+ *
+ * The resolver never throws. Missing key → `null`. Malformed
+ * credentials file → propagates the underlying file store's error
+ * (today: `PlaintextFileProviderKeyStore` throws a "not a valid v1
+ * document" error so the operator gets a clear signal instead of a
+ * silent miss).
+ */
+export function createByokResolver(opts = {}) {
+    const env = opts.env ?? process.env;
+    const fileStore = opts.fileStore !== undefined
+        ? opts.fileStore
+        : new PlaintextFileProviderKeyStore({ filename: getCredentialsFile() });
+    // File-store helper. Used twice in the fallback chain (once at the
+    // operator's 'global' scope, optionally once at the end-user's
+    // identity scope).
+    const fileLookupAtScope = async (scope, provider) => {
+        if (fileStore === null)
+            return null;
+        const ref = await fileStore.get(scope, provider);
+        if (!ref)
+            return null;
+        return {
+            key: ref.key,
+            source: 'credentials-file',
+            provider,
+        };
+    };
+    return {
+        async resolve(provider, resolveOpts) {
+            // Step 1: env. The PROVIDER_ENV_NAMES table is the locked
+            // mapping; bedrock isn't in it on purpose, so destructuring to
+            // `undefined` gives us the "skip env" path automatically.
+            const envNames = provider === 'bedrock'
+                ? undefined
+                : PROVIDER_ENV_NAMES[provider];
+            if (envNames) {
+                for (const name of envNames) {
+                    const value = env[name];
+                    if (value !== undefined && value.length > 0) {
+                        return {
+                            key: value,
+                            source: 'env',
+                            provider,
+                            envName: name,
+                        };
+                    }
+                }
+            }
+            // Step 2: credentials file at operator's 'global' scope. If the
+            // operator set a key here, every user uses it (operator pays).
+            const globalHit = await fileLookupAtScope(BYOK_GLOBAL_APP_SCOPE, provider);
+            if (globalHit)
+                return globalHit;
+            // Step 3: credentials file at the end-user's identity scope.
+            // Only consulted when the operator opted out of paying (no
+            // global key). The /settings UI under --multi-tenant writes
+            // here.
+            if (resolveOpts?.userScope &&
+                resolveOpts.userScope !== BYOK_GLOBAL_APP_SCOPE) {
+                const userHit = await fileLookupAtScope(resolveOpts.userScope, provider);
+                if (userHit)
+                    return userHit;
+            }
+            return null;
+        },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}