@ggui-ai/cli 0.1.0-rc.1

package/dist/internal/artifact-uninstall.d.ts

@@ -0,0 +1,30 @@
+import type { ArtifactKind } from './artifact-install.js';
+export declare function buildUninstallHelp(kind: ArtifactKind): string;
+export interface ParsedArtifactUninstallFlags {
+    readonly kind: ArtifactKind;
+    readonly artifactId: string;
+    readonly version: string;
+}
+export type ParsedArtifactUninstall = ParsedArtifactUninstallFlags | {
+    readonly error: string;
+};
+export declare function parseArtifactUninstallFlags(kind: ArtifactKind, args: readonly string[]): ParsedArtifactUninstall;
+export interface ArtifactUninstallDeps {
+    readonly cwd: string;
+    readonly stdout?: (s: string) => void;
+    readonly stderr?: (s: string) => void;
+}
+export interface ArtifactUninstallResult {
+    readonly exitCode: number;
+    /** `true` when a directory was actually removed. `false` on idempotent no-ops. */
+    readonly removed: boolean;
+    /**
+     * `true` when `INSTALLED_BLUEPRINTS_GLOB` was stripped from
+     * `ggui.json#blueprints.include` (i.e. no installed-blueprints
+     * subdirs remained). `false` when the glob was kept (other installs
+     * still on disk) or wasn't present to begin with.
+     */
+    readonly globRemoved: boolean;
+}
+export declare function runArtifactUninstall(flags: ParsedArtifactUninstallFlags, deps: ArtifactUninstallDeps): Promise<ArtifactUninstallResult>;
+//# sourceMappingURL=artifact-uninstall.d.ts.map

package/dist/internal/artifact-uninstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-uninstall.d.ts","sourceRoot":"","sources":["../../src/internal/artifact-uninstall.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAM1D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA4B7D;AAMD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,uBAAuB,GAC/B,4BAA4B,GAC5B;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/B,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,uBAAuB,CAwCzB;AAMD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,4BAA4B,EACnC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CAmFlC"}

package/dist/internal/artifact-uninstall.js

@@ -0,0 +1,205 @@
+/**
+ * `ggui blueprint uninstall <scope/name>@<version>`.
+ *
+ * Reverse of `runArtifactInstall`'s on-disk materialization. Removes
+ * `.ggui/installed-blueprints/<scope-bare>__<name>__<version>/`
+ * from the project root and — when this was the LAST remaining
+ * installed-blueprint subdir — strips the `INSTALLED_BLUEPRINTS_GLOB`
+ * entry from `ggui.json#blueprints.include` so a future `ggui serve`
+ * doesn't walk an empty glob.
+ *
+ * What this does NOT touch:
+ *
+ *   - **The runtime cache row.** The install-to-cache bridge is
+ *     per-scope idempotent within a single server lifetime; the row
+ *     stays in the `vectorStore` until the operator restarts
+ *     `ggui serve`. Sqlite-backed stores survive restart too. A
+ *     restart is the documented step to reclaim the cache slot.
+ *   - **The marketplace registry.** Uninstall is purely local; the
+ *     published artifact is unaffected. Registry-side withdrawal is a
+ *     separate operation.
+ *   - **`ggui.json#blueprints.include` entries that aren't the
+ *     installed-blueprints glob.** Hand-authored UI globs survive
+ *     verbatim; only the install-managed glob is auto-removed when
+ *     no installed-blueprints subdirs remain.
+ *
+ * Posture: idempotent. Uninstalling a blueprint that was never
+ * installed succeeds with exit code 0 and a stderr note — operators
+ * shouldn't be punished for re-running the command.
+ */
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { findGguiJson, readGguiJson, writeGguiJson, } from './ggui-json.js';
+import { blueprintInstallSubdir, INSTALLED_BLUEPRINTS_GLOB, INSTALLED_BLUEPRINTS_SUBDIR, } from './artifact-install.js';
+/* -------------------------------------------------------------------------- */
+/* Help text                                                                  */
+/* -------------------------------------------------------------------------- */
+export function buildUninstallHelp(kind) {
+    const noun = kind === 'blueprint' ? 'blueprint' : 'gadget';
+    const verb = `ggui ${noun} uninstall`;
+    return `${verb} — remove a marketplace-installed ${noun} from this project.
+
+Usage:
+  ${verb} <scope/name>@<version> [options]
+
+Arguments:
+  <scope/name>@<version>    Full install identifier. Same shape as install.
+
+Options:
+  --help                    Show this help.
+
+Behavior:
+  - Removes \`.ggui/installed-blueprints/<scope-bare>__<name>__<version>/\` from disk.
+  - When this was the LAST installed-blueprint subdir, strips the
+    \`${INSTALLED_BLUEPRINTS_GLOB}\` entry from \`ggui.json#blueprints.include\`.
+    Other globs in the include list are preserved verbatim.
+  - Idempotent: uninstalling a never-installed identifier exits 0
+    with a stderr note. Re-runs are safe.
+
+Caveats:
+  - The runtime cache row stays warm until the next \`ggui serve\` restart
+    (the install-to-cache bridge is per-scope idempotent within a server
+    lifetime). Restart to reclaim the cache slot.
+  - This is local-only. The published marketplace artifact is unchanged.
+`;
+}
+export function parseArtifactUninstallFlags(kind, args) {
+    let positional;
+    for (const arg of args) {
+        if (arg === '--help' || arg === '-h') {
+            return { error: '__help__' };
+        }
+        if (arg.startsWith('--')) {
+            return { error: `unknown flag: ${arg}` };
+        }
+        if (positional === undefined) {
+            positional = arg;
+            continue;
+        }
+        return { error: `unexpected positional argument: ${arg}` };
+    }
+    if (positional === undefined) {
+        return {
+            error: 'missing positional argument: <scope/name>@<version> (e.g. @my-org/notepad@1.0.0)',
+        };
+    }
+    const lastAt = positional.lastIndexOf('@');
+    if (lastAt <= 0) {
+        return {
+            error: `invalid uninstall identifier: ${positional} — expected <scope/name>@<version>`,
+        };
+    }
+    const artifactId = positional.slice(0, lastAt);
+    const version = positional.slice(lastAt + 1);
+    if (!artifactId.startsWith('@') || artifactId.indexOf('/') === -1) {
+        return {
+            error: `invalid artifactId: ${artifactId} — expected \`@scope/name\``,
+        };
+    }
+    if (version.length === 0) {
+        return {
+            error: `invalid version: empty (expected SemVer after \`@\`)`,
+        };
+    }
+    return { kind, artifactId, version };
+}
+export async function runArtifactUninstall(flags, deps) {
+    const verb = `ggui ${flags.kind} uninstall`;
+    const stdout = deps.stdout ?? ((s) => void process.stdout.write(s));
+    const stderr = deps.stderr ?? ((s) => void process.stderr.write(s));
+    const gguiPath = findGguiJson(deps.cwd);
+    if (gguiPath === null) {
+        stderr(`${verb}: no ggui.json found in ${deps.cwd} or any ancestor (up to 8 levels).\n`);
+        return { exitCode: 2, removed: false, globRemoved: false };
+    }
+    const loaded = readGguiJson(gguiPath);
+    if ('error' in loaded) {
+        stderr(`${verb}: ${loaded.error}\n`);
+        return { exitCode: 2, removed: false, globRemoved: false };
+    }
+    const gguiJson = loaded.value;
+    const projectRoot = gguiPath.slice(0, gguiPath.lastIndexOf('/'));
+    const scope = flags.artifactId.slice(1, flags.artifactId.indexOf('/'));
+    const name = flags.artifactId.slice(flags.artifactId.indexOf('/') + 1);
+    const subdir = blueprintInstallSubdir({
+        scope: `@${scope}`,
+        name,
+        version: flags.version,
+    });
+    const installDir = join(projectRoot, INSTALLED_BLUEPRINTS_SUBDIR, subdir);
+    let removed = false;
+    if (existsSync(installDir)) {
+        try {
+            rmSync(installDir, { recursive: true, force: true });
+            removed = true;
+            stdout(`removed: ${installDir}\n`);
+        }
+        catch (err) {
+            stderr(`${verb}: failed to remove ${installDir}: ${err instanceof Error ? err.message : String(err)}\n`);
+            return { exitCode: 1, removed: false, globRemoved: false };
+        }
+    }
+    else {
+        stderr(`${verb}: ${flags.artifactId}@${flags.version} is not installed at ${installDir} — nothing to remove.\n`);
+    }
+    // Auto-cleanup of the include glob: only when zero installed-
+    // blueprint subdirs remain. The base directory's continued existence
+    // doesn't matter — we walk it for a non-empty subdir list (the
+    // INSTALLED_BLUEPRINTS_GLOB matches `<subdir>/ggui.ui.json`, so the
+    // absence of any subdir means the glob matches nothing).
+    const installRoot = join(projectRoot, INSTALLED_BLUEPRINTS_SUBDIR);
+    let remainingSubdirs = 0;
+    if (existsSync(installRoot)) {
+        try {
+            remainingSubdirs = readdirSync(installRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
+        }
+        catch {
+            // If we can't enumerate the dir, leave the glob alone — better
+            // than risk-stripping an include the operator still relies on.
+            remainingSubdirs = Number.POSITIVE_INFINITY;
+        }
+    }
+    let globRemoved = false;
+    if (remainingSubdirs === 0) {
+        if (removeBlueprintGlob(gguiJson)) {
+            writeGguiJson(gguiPath, gguiJson);
+            globRemoved = true;
+            stdout(`removed glob from ggui.json#blueprints.include (no installed blueprints remain)\n`);
+        }
+    }
+    if (removed || globRemoved) {
+        stdout(`\nUninstall complete.\n`);
+    }
+    return { exitCode: 0, removed, globRemoved };
+}
+/**
+ * Strip `INSTALLED_BLUEPRINTS_GLOB` from `gguiJson.blueprints.include`
+ * when present. Returns `true` when a write is needed. Leaves the
+ * `blueprints` block intact when it still contains other include
+ * entries — operator-authored UI globs are preserved.
+ */
+function removeBlueprintGlob(gguiJson) {
+    const blueprints = gguiJson['blueprints'];
+    if (blueprints === undefined ||
+        typeof blueprints !== 'object' ||
+        blueprints === null ||
+        Array.isArray(blueprints)) {
+        return false;
+    }
+    const blueprintsObj = blueprints;
+    const include = blueprintsObj['include'];
+    if (!Array.isArray(include))
+        return false;
+    const idx = include.indexOf(INSTALLED_BLUEPRINTS_GLOB);
+    if (idx === -1)
+        return false;
+    include.splice(idx, 1);
+    // When the include list is now empty AND no other blueprints-block
+    // fields are present, remove the whole block so the manifest stays
+    // tidy. Operator-edited blueprints blocks with additional fields
+    // survive — we only touch the install-managed glob.
+    if (include.length === 0 && Object.keys(blueprintsObj).length === 1) {
+        delete gguiJson['blueprints'];
+    }
+    return true;
+}

package/dist/internal/auth-cache.d.ts

@@ -0,0 +1,40 @@
+/** v1 on-disk shape. */
+export interface RegistryTokenDocument {
+    readonly version: 1;
+    /** Full registry origin (e.g. `https://dev.registry.sandbox.ggui.ai`). */
+    readonly registry: string;
+    /** Cognito IdToken — sent as `Authorization: Bearer <idToken>`. */
+    readonly idToken: string;
+    /** Cognito AccessToken — surfaced separately for handlers that need it. */
+    readonly accessToken: string;
+    /** Cognito RefreshToken — used to mint fresh id/access tokens. */
+    readonly refreshToken: string;
+    /** Unix epoch SECONDS — past this, the id token is rejected by the registry. */
+    readonly expiresAt: number;
+    /** Username the tokens belong to (informational; for `--whoami` reuse). */
+    readonly username: string;
+    /** ISO 8601 timestamp this document was written. */
+    readonly writtenAt: string;
+}
+/**
+ * Compute the on-disk path for a registry's token cache. Pure (no
+ * IO) so callers can derive the path before existence checks.
+ */
+export declare function getRegistryTokenPath(registryUrl: string): string;
+/**
+ * Load a cached token document. Returns null when missing OR
+ * malformed — callers treat both as "need to log in".
+ */
+export declare function loadRegistryToken(registryUrl: string): RegistryTokenDocument | null;
+/**
+ * Atomically write the document with mode `0o600`. write-temp +
+ * rename pattern so a crash mid-write doesn't strand a partial doc.
+ */
+export declare function saveRegistryToken(doc: RegistryTokenDocument): void;
+/**
+ * Decide whether a cached document is still usable for the next
+ * request. Subtracts a 60-second safety margin so we don't race a
+ * boundary expiry that the registry would refuse.
+ */
+export declare function isTokenFresh(doc: RegistryTokenDocument, nowSeconds?: number): boolean;
+//# sourceMappingURL=auth-cache.d.ts.map

package/dist/internal/auth-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-cache.d.ts","sourceRoot":"","sources":["../../src/internal/auth-cache.ts"],"names":[],"mappings":"AA6BA,wBAAwB;AACxB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,GAClB,qBAAqB,GAAG,IAAI,CAiB9B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,qBAAqB,GAAG,IAAI,CA4BlE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,qBAAqB,EAC1B,UAAU,GAAE,MAAsC,GACjD,OAAO,CAET"}

package/dist/internal/auth-cache.js

@@ -0,0 +1,133 @@
+/**
+ * Per-registry JWT cache for `ggui gadget publish`.
+ *
+ * Layout: `~/.ggui/auth/<registry-hostname>/token.json`. One file per
+ * registry hostname so an operator who publishes to a dev sandbox
+ * AND production doesn't paper over one session with the other. The
+ * hostname is the directory name (no path component leaks into disk
+ * names) — full URL is captured inside the document.
+ *
+ * Document version is `1`. Bumped on breaking-change shape edits;
+ * loaders that see `version > 1` refuse rather than mis-parse.
+ *
+ * **Distinct from `~/.ggui/auth.json`.** That file holds the
+ * `api.ggui.ai` device-flow session for hosted-key management. The
+ * registry tokens here are a SEPARATE auth surface (different IdP,
+ * different audience), so they live in a parallel namespace.
+ */
+import { URL } from 'node:url';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getConfigDir } from '../paths.js';
+/**
+ * Compute the on-disk path for a registry's token cache. Pure (no
+ * IO) so callers can derive the path before existence checks.
+ */
+export function getRegistryTokenPath(registryUrl) {
+    const host = safeHostname(registryUrl);
+    return join(getConfigDir(), 'auth', host, 'token.json');
+}
+/**
+ * Load a cached token document. Returns null when missing OR
+ * malformed — callers treat both as "need to log in".
+ */
+export function loadRegistryToken(registryUrl) {
+    const path = getRegistryTokenPath(registryUrl);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRegistryTokenDocument(decoded))
+        return null;
+    return decoded;
+}
+/**
+ * Atomically write the document with mode `0o600`. write-temp +
+ * rename pattern so a crash mid-write doesn't strand a partial doc.
+ */
+export function saveRegistryToken(doc) {
+    const target = getRegistryTokenPath(doc.registry);
+    const dir = dirname(target);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    else {
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // best-effort on Windows
+        }
+    }
+    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+    renameSync(tmp, target);
+    try {
+        chmodSync(target, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Decide whether a cached document is still usable for the next
+ * request. Subtracts a 60-second safety margin so we don't race a
+ * boundary expiry that the registry would refuse.
+ */
+export function isTokenFresh(doc, nowSeconds = Math.floor(Date.now() / 1000)) {
+    return doc.expiresAt - nowSeconds > 60;
+}
+// ---------------------------------------------------------------------------
+// internal
+// ---------------------------------------------------------------------------
+function isRegistryTokenDocument(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const r = x;
+    return (r['version'] === 1 &&
+        typeof r['registry'] === 'string' &&
+        typeof r['idToken'] === 'string' &&
+        typeof r['accessToken'] === 'string' &&
+        typeof r['refreshToken'] === 'string' &&
+        typeof r['expiresAt'] === 'number' &&
+        typeof r['username'] === 'string' &&
+        typeof r['writtenAt'] === 'string');
+}
+/**
+ * Extract a filesystem-safe hostname from a registry URL. Replaces
+ * non-alphanumeric chars with `-` so the result is always a valid
+ * directory name on every supported OS.
+ */
+function safeHostname(registryUrl) {
+    let host;
+    try {
+        host = new URL(registryUrl).hostname;
+    }
+    catch {
+        // Caller validated earlier; if we got here with a bogus URL the
+        // cleanest thing is to refuse the path entirely.
+        throw new Error(`auth-cache: invalid registry URL: ${registryUrl}`);
+    }
+    return host.replace(/[^a-z0-9.-]/gi, '-');
+}

package/dist/internal/auth-strategy.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Vendor-neutral auth strategy for marketplace CLI verbs
+ * (`ggui {gadget,blueprint} publish`).
+ *
+ * Two strategies — explicit `--auth=bearer` for self-hosted and local
+ * registries, and the (default) hosted-auth flow for the cloud
+ * registry. The default flow is implemented behind a vendor-neutral
+ * function name (`acquireHostedAuthJwt`) so this surface never names
+ * any specific identity provider; the underlying implementation in
+ * `artifact-publish` calls the cloud's hosted auth provider.
+ *
+ * The public surface (this file, its consumers, and the CLI help
+ * text) stays vendor-neutral.
+ *
+ * @example
+ * ```ts
+ * import { parseAuthFlags, acquireAuthToken } from './internal/auth-strategy.js';
+ *
+ * const authFlags = parseAuthFlags(args);
+ * const jwt = await acquireAuthToken({
+ *   flags: authFlags,
+ *   env: process.env,
+ *   registryUrl,
+ *   acquireHostedAuthJwt,
+ * });
+ * ```
+ */
+/**
+ * Parsed `--auth=<mode>` + `--token <token>` flags. Vendor-neutral.
+ *
+ * `auth: undefined` means "use the default (hosted auth via the
+ * registry)". The only public flag value is `'bearer'`.
+ */
+export interface AuthFlags {
+    /** Auth mode. Only `'bearer'` is admitted as a public value; absent
+     * means "default = hosted auth via the configured registry". */
+    readonly auth?: 'bearer';
+    /** Explicit bearer token. Used only when `auth === 'bearer'`. */
+    readonly token?: string;
+}
+/**
+ * Help-text fragment for the auth flags, inlined into each subcommand's
+ * help block. Vendor-neutral copy — never name the identity provider.
+ */
+export declare const AUTH_HELP_FRAGMENT = "Auth:\n  --auth=bearer        Use a bearer token (for self-hosted or local\n                       registries). Pair with --token <token> or set\n                       GGUI_REGISTRY_TOKEN in the environment.\n  --token <token>      Bearer token (paired with --auth=bearer).\n  (default)            Hosted auth via the configured registry \u2014\n                       no flag needed; the CLI prompts for credentials\n                       on first publish and caches the resulting\n                       session at ~/.ggui/auth/<registry-host>/token.json.\n";
+/**
+ * Pop the auth-related flags out of an argv-like list, returning the
+ * parsed flags + the residual args (so subcommand parsers can keep
+ * their own flag loops simple). Returns `{ error }` on usage failure.
+ *
+ * Accepts both `--auth bearer` / `--auth=bearer` forms, and similarly
+ * `--token <value>` / `--token=<value>`.
+ */
+export declare function parseAuthFlags(args: readonly string[]): {
+    flags: AuthFlags;
+    rest: readonly string[];
+} | {
+    error: string;
+};
+/**
+ * Hosted-auth callback shape. Vendor-neutral by design — the caller
+ * injects the actual implementation (which today calls the cloud
+ * registry's hosted auth vendor).
+ *
+ * Returns the bearer JWT the CLI sends as `Authorization: Bearer <jwt>`.
+ */
+export type HostedAuthAcquirer = (deps: {
+    readonly registryUrl: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+}) => Promise<string>;
+/**
+ * Acquire the auth token to send to the registry. Routes:
+ *
+ *   - `flags.auth === 'bearer'` → use `flags.token` || `GGUI_REGISTRY_TOKEN`
+ *   - otherwise → call `acquireHostedAuthJwt`
+ *
+ * Throws (with an operator-readable message) when bearer auth is
+ * selected but no token is supplied; the message names the env var so
+ * the operator can fix it without reading help.
+ */
+export declare function acquireAuthToken(deps: {
+    readonly flags: AuthFlags;
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+    readonly registryUrl: string;
+    readonly acquireHostedAuthJwt: HostedAuthAcquirer;
+}): Promise<string>;
+//# sourceMappingURL=auth-strategy.d.ts.map

package/dist/internal/auth-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy.d.ts","sourceRoot":"","sources":["../../src/internal/auth-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;oEACgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,sjBAS9B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAuDnE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEtB;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,kBAAkB,CAAC;CACnD,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB"}

package/dist/internal/auth-strategy.js

@@ -0,0 +1,132 @@
+/**
+ * Vendor-neutral auth strategy for marketplace CLI verbs
+ * (`ggui {gadget,blueprint} publish`).
+ *
+ * Two strategies — explicit `--auth=bearer` for self-hosted and local
+ * registries, and the (default) hosted-auth flow for the cloud
+ * registry. The default flow is implemented behind a vendor-neutral
+ * function name (`acquireHostedAuthJwt`) so this surface never names
+ * any specific identity provider; the underlying implementation in
+ * `artifact-publish` calls the cloud's hosted auth provider.
+ *
+ * The public surface (this file, its consumers, and the CLI help
+ * text) stays vendor-neutral.
+ *
+ * @example
+ * ```ts
+ * import { parseAuthFlags, acquireAuthToken } from './internal/auth-strategy.js';
+ *
+ * const authFlags = parseAuthFlags(args);
+ * const jwt = await acquireAuthToken({
+ *   flags: authFlags,
+ *   env: process.env,
+ *   registryUrl,
+ *   acquireHostedAuthJwt,
+ * });
+ * ```
+ */
+/**
+ * Help-text fragment for the auth flags, inlined into each subcommand's
+ * help block. Vendor-neutral copy — never name the identity provider.
+ */
+export const AUTH_HELP_FRAGMENT = `Auth:
+  --auth=bearer        Use a bearer token (for self-hosted or local
+                       registries). Pair with --token <token> or set
+                       GGUI_REGISTRY_TOKEN in the environment.
+  --token <token>      Bearer token (paired with --auth=bearer).
+  (default)            Hosted auth via the configured registry —
+                       no flag needed; the CLI prompts for credentials
+                       on first publish and caches the resulting
+                       session at ~/.ggui/auth/<registry-host>/token.json.
+`;
+/**
+ * Pop the auth-related flags out of an argv-like list, returning the
+ * parsed flags + the residual args (so subcommand parsers can keep
+ * their own flag loops simple). Returns `{ error }` on usage failure.
+ *
+ * Accepts both `--auth bearer` / `--auth=bearer` forms, and similarly
+ * `--token <value>` / `--token=<value>`.
+ */
+export function parseAuthFlags(args) {
+    let auth;
+    let token;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--auth' || arg.startsWith('--auth=')) {
+            const eq = arg.indexOf('=');
+            let value;
+            if (eq !== -1) {
+                value = arg.slice(eq + 1);
+            }
+            else {
+                const next = args[i + 1];
+                if (typeof next !== 'string' || next.length === 0) {
+                    return { error: '--auth requires a value' };
+                }
+                value = next;
+                i += 1;
+            }
+            if (value !== 'bearer') {
+                return { error: `--auth must be "bearer" (got "${value}")` };
+            }
+            auth = value;
+            continue;
+        }
+        if (arg === '--token' || arg.startsWith('--token=')) {
+            const eq = arg.indexOf('=');
+            let value;
+            if (eq !== -1) {
+                value = arg.slice(eq + 1);
+            }
+            else {
+                const next = args[i + 1];
+                if (typeof next !== 'string' || next.length === 0) {
+                    return { error: '--token requires a value' };
+                }
+                value = next;
+                i += 1;
+            }
+            token = value;
+            continue;
+        }
+        rest.push(arg);
+    }
+    return {
+        flags: {
+            ...(auth !== undefined ? { auth } : {}),
+            ...(token !== undefined ? { token } : {}),
+        },
+        rest,
+    };
+}
+/**
+ * Acquire the auth token to send to the registry. Routes:
+ *
+ *   - `flags.auth === 'bearer'` → use `flags.token` || `GGUI_REGISTRY_TOKEN`
+ *   - otherwise → call `acquireHostedAuthJwt`
+ *
+ * Throws (with an operator-readable message) when bearer auth is
+ * selected but no token is supplied; the message names the env var so
+ * the operator can fix it without reading help.
+ */
+export async function acquireAuthToken(deps) {
+    if (deps.flags.auth === 'bearer') {
+        const fromFlag = deps.flags.token;
+        const fromEnv = deps.env['GGUI_REGISTRY_TOKEN'];
+        const token = typeof fromFlag === 'string' && fromFlag.length > 0
+            ? fromFlag
+            : typeof fromEnv === 'string' && fromEnv.length > 0
+                ? fromEnv
+                : undefined;
+        if (token === undefined) {
+            throw new Error('bearer auth requires --token <value> or GGUI_REGISTRY_TOKEN');
+        }
+        return token;
+    }
+    return deps.acquireHostedAuthJwt({
+        registryUrl: deps.registryUrl,
+        env: deps.env,
+        cwd: deps.cwd,
+    });
+}