@extension.dev/mcp 6.2.0 → 6.4.0

package/dist/src/lib/carrier.d.ts

@@ -1,73 +1,21 @@
-/**
- * The Extension.dev Live Preview carrier, bundled prebuilt in this package
- * under extensions/live-preview/<engine>. extension_dev materializes it into
- * the project's ./extensions folder (which Extension.js auto-scans and loads
- * as a companion next to the user's extension), so the dev browser comes up
- * carrier-equipped: web pages the carrier allowlists (inspect.extension.dev,
- * localhost) can then watch the session's real-lane trace and pair with it.
- */
 export declare const CARRIER_DIR_NAME = "extension-dev-live-preview";
 export declare const CARRIER_EXTENSION_ID = "ibppeifnekhjjjmpjfiobccjlicbmgcb";
-/** Where the carrier lands inside a project. */
 export declare function carrierPath(projectPath: string): string;
-/** True only for a directory carrying our marker, i.e. ours to delete. */
 export declare function isManagedCarrier(projectPath: string): boolean;
 export type CarrierRemoval = {
     removed: boolean;
     path: string;
-    /** Present when something was there but was NOT ours to touch. */
     note?: string;
 };
-/**
- * Remove the carrier from a project, marker-guarded.
- *
- * The trace swarm's most release-dangerous finding was that a debugging flag
- * leaves a permanent companion extension in the project: it survived
- * extension_stop, Extension.js auto-scans ./extensions, and the first
- * `git add -A` vendors it. Nothing removed it, ever. Stop and build both call
- * this now, and `extension_dev carrier: true` puts it back on demand.
- */
 export declare function removeCarrier(projectPath: string): CarrierRemoval;
-/**
- * Keep the carrier out of the user's commits. The scaffolder runs `git init`
- * with no initial commit, so the first `git add -A` in a project that ever ran
- * with carrier: true vendors 460K of somebody else's extension.
- * Returns the line added, or null when nothing needed doing.
- */
 export declare function ensureCarrierIgnored(projectPath: string): string | null;
 export type CarrierMaterialization = {
     loaded: boolean;
     path?: string;
     note: string;
-    /** The .gitignore entry this run added, when it added one. */
     gitignored?: string;
-    /**
-     * What the carrier lane CANNOT do, stated at the moment it is handed over.
-     * The trace swarm's top finding was that the real lane's boundaries were
-     * discoverable only by experiment: 14 personas independently filed the
-     * carrier-identity scoping as a severe bug, and 10 more expected the trace
-     * to show their own extension's calls. Both are honest constraints; neither
-     * was written down anywhere the caller would look.
-     */
     limitations?: string[];
-    /**
-     * The graduation path, stated next to the shared-identity limitation so the
-     * caller is not left at a dead end. The carrier lane is the SHARED real lane
-     * (calls run as the carrier); but the guest is ALREADY loaded as itself in
-     * this same session, so its OWN storage, identity and messaging are reached by
-     * driving the guest directly with the control verbs, not the carrier bridge.
-     * This is the agent-lane twin of the inspect Trace tab's "load as your own
-     * extension" affordance: here the extension is already loaded, so graduating
-     * means targeting it, not launching it.
-     */
     graduation?: string;
-    /**
-     * How to actually DRIVE the real lane. Seven personas reached a
-     * permanently empty trace and concluded the feature was broken, because
-     * nothing in the 33 tool schemas, this note, or the rendered page named the
-     * carrier's extension id or its message envelopes. Every persona that did
-     * reach the real lane used out-of-band knowledge of the emulator source.
-     */
     bridgeProtocol?: {
         carrierExtensionId: string;
         allowedOrigins: string;
@@ -75,9 +23,4 @@ export type CarrierMaterialization = {
         example: string;
     };
 };
-/**
- * Copy the bundled carrier into <projectPath>/extensions/<CARRIER_DIR_NAME>.
- * Refuses to touch an existing directory that lacks our marker file (it is
- * the user's, not ours); otherwise replaces it so version updates propagate.
- */
 export declare function materializeCarrier(projectPath: string, browser: string): CarrierMaterialization;

package/dist/src/lib/credentials.d.ts

@@ -1,14 +1,10 @@
 export interface StoredCredentials {
     version: 1;
-    /** The HMAC access token the publish path sends as `Bearer`. */
     token: string;
     workspaceSlug: string;
     projectSlug: string;
-    /** Token expiry as unix epoch seconds (0 if unknown). */
     expiresAt: number;
-    /** Platform base URL the token was minted against. */
     api: string;
-    /** Which device flow minted this token: extension.dev-gated or GitHub-direct. */
     provider?: "extensiondev" | "github";
 }
 export declare function credentialsPath(): string;
@@ -18,9 +14,4 @@ export declare function clearCredentials(): {
     cleared: boolean;
     path: string;
 };
-/**
- * Return stored credentials only if the token has not expired. Used by the
- * publish token resolution so an expired local token falls through cleanly to
- * "no token" instead of producing a 401 from the platform.
- */
 export declare function readValidCredentials(nowSeconds?: number): StoredCredentials | null;

package/dist/src/lib/device-flow.d.ts

@@ -23,12 +23,6 @@ export type DevicePollResult = {
     reason: "pending" | "denied" | "expired" | "error";
     message?: string;
 };
-/**
- * Poll the extension.dev token endpoint until approved or the budget runs out.
- * The budget is kept under the MCP client request timeout; the tool re-invokes
- * with the same deviceCode to keep waiting (idempotent), mirroring the GitHub
- * poll's two-phase contract.
- */
 export declare function pollDeviceToken(args: {
     apiBase: string;
     path: string;

package/dist/src/lib/github-device.d.ts

@@ -2,9 +2,7 @@ export interface DeviceCodeStart {
     deviceCode: string;
     userCode: string;
     verificationUri: string;
-    /** Minimum seconds to wait between polls. */
     interval: number;
-    /** Seconds until the device code expires. */
     expiresIn: number;
 }
 export type PollResult = {
@@ -22,13 +20,6 @@ export declare function startDeviceCode(args: {
     scope?: string;
     fetchImpl?: FetchImpl;
 }): Promise<DeviceCodeStart>;
-/**
- * Poll for the access token until the budget elapses. A budget shorter than
- * the device-code lifetime lets a caller (e.g. an MCP tool that must return
- * promptly) poll in bounded slices and report "pending" between calls; a long
- * budget (a blocking CLI) waits the whole time. Returns `pending` only on
- * budget exhaustion; `expired`/`denied` are terminal.
- */
 export declare function pollForToken(args: {
     clientId: string;
     deviceCode: string;

package/dist/src/lib/guest-load-oracle.d.ts

@@ -11,16 +11,6 @@ export type GuestLoadCheck = {
     cdpPort?: number;
     reason: string;
 };
-/**
- * The BUGS_TO_FIX §83 oracle: ask the BROWSER whether the guest actually loaded,
- * instead of trusting the engine's ready.json. Chrome refusing --load-extension
- * is invisible to every engine surface (ready.json stamps status:ready, empty
- * logs), so the only trustworthy "did the guest load" signal is a
- * chrome-extension:// target in the browser's own CDP /json list. The engine's
- * devtools companion is always present and is not the guest; a NON-companion
- * extension target is. Never throws: an unreachable endpoint returns
- * checked:false so callers can degrade instead of failing.
- */
 export declare function verifyGuestLoaded(projectPath: string, browser: string, options?: {
     waitMs?: number;
     timeoutMs?: number;

package/dist/src/lib/login-flow.d.ts

@@ -1,22 +1,7 @@
 import { type StoredCredentials } from "./credentials";
-/**
- * The platform clamps CLI token TTL to at most 7 days (server-owned; this
- * client only states the truth). Every token surface repeats it so CI authors
- * learn the rotation contract up front instead of from a 401 a week after
- * wiring the pipeline. Links the console's Access tokens page when the
- * project is known.
- */
 export declare function tokenTtlNote(workspaceSlug?: string, projectSlug?: string): string;
 type FetchImpl = typeof fetch;
 export declare function resolveApiBase(api?: string): string;
-/**
- * Validate the platform base URL BEFORE we attach a bearer token to a request to
- * it. SECURITY: the `api` arg / EXTENSION_DEV_API_URL is operator-supplied, but a
- * hostile value (e.g. via prompt-injection in the client) could redirect the
- * token to an attacker. The access token must never leave over plaintext or go to
- * an arbitrary scheme, so we require https -- allowing http only for localhost
- * dev. Returns the normalized base (no trailing slash) or an error message.
- */
 export declare function safeApiBase(raw: string): {
     ok: true;
     base: string;
@@ -25,10 +10,6 @@ export declare function safeApiBase(raw: string): {
     message: string;
 };
 export interface LoginConfig {
-    /**
-     * "extensiondev": the extension.dev-gated device flow (branded /device, GitHub
-     * federated server-side). "github": the legacy GitHub-direct device flow.
-     */
     provider: "extensiondev" | "github";
     clientId: string;
     scope: string;
@@ -36,29 +17,12 @@ export interface LoginConfig {
     deviceTokenUrl: string;
     verificationUri: string;
 }
-/**
- * Resolve how the device flow should authenticate. The server's public config
- * picks the provider (extension.dev-gated once its device endpoints are live,
- * else GitHub-direct). EXTENSION_DEV_GITHUB_CLIENT_ID forces the GitHub flow
- * (useful when pointing at a self-hosted platform).
- */
 export declare function fetchLoginConfig(apiBase: string, fetchImpl?: FetchImpl): Promise<LoginConfig>;
-/**
- * Persist a `{ token, expiresAt, workspaceSlug, projectSlug }` response (the
- * shape returned by BOTH the GitHub exchange endpoint and the extension.dev
- * device/token endpoint) to the local credentials file. Records which provider
- * minted it.
- */
 export declare function persistTokenResponse(args: {
     apiBase: string;
     data: Record<string, unknown>;
     provider: "extensiondev" | "github";
 }): StoredCredentials;
-/**
- * Trade a verified GitHub user token for a project-scoped access token and
- * write it to the local credentials file. Returns the stored credentials
- * (token included for the caller's in-memory use; never logged).
- */
 export declare function exchangeAndPersist(args: {
     apiBase: string;
     githubToken: string;

package/dist/src/lib/preview-upload.d.ts

@@ -0,0 +1,33 @@
+type FetchImpl = typeof fetch;
+export interface PreviewUploadFile {
+    path: string;
+    content: string;
+    encoding: "utf8" | "base64";
+}
+export interface PreviewUploadResult {
+    artifactId: string;
+    previewUrl: string;
+    zipUrl?: string;
+    revokeUrl?: string;
+    expiresAt?: string;
+}
+export type PreviewUploadOutcome = {
+    ok: true;
+    data: PreviewUploadResult;
+} | {
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+    };
+};
+export declare function collectDistFiles(distDir: string): PreviewUploadFile[];
+export declare function uploadPreview(options: {
+    distDir: string;
+    manifest: Record<string, unknown>;
+    browser: string;
+    api?: string;
+    token?: string;
+    fetchImpl?: FetchImpl;
+}): Promise<PreviewUploadOutcome>;
+export {};

package/dist/src/lib/project-ignore.d.ts

@@ -0,0 +1,10 @@
+export type ProjectIgnoreState = "added" | "already-ignored" | "not-a-repo" | "failed";
+export interface ProjectIgnoreOutcome {
+    state: ProjectIgnoreState;
+    entry: string;
+}
+export declare function ensureProjectIgnored(projectPath: string, options: {
+    entry: string;
+    aliases?: string[];
+    comment: string;
+}): ProjectIgnoreOutcome;

package/dist/src/lib/publish.d.ts

@@ -1,14 +1,9 @@
 type FetchImpl = typeof fetch;
-/** Resolve the access token: EXTENSION_DEV_TOKEN env first, then the login creds file. */
 export declare function resolveToken(): string;
 export interface PublishOptions {
-    /** Share-link lifetime in hours (1-168, platform default 24). */
     ttlHours?: number;
-    /** Pin the share URL to a specific build sha. */
     buildSha?: string;
-    /** Platform base URL (defaults to https://www.extension.dev or EXTENSION_DEV_API_URL). */
     api?: string;
-    /** Explicit token; defaults to resolveToken(). */
     token?: string;
     fetchImpl?: FetchImpl;
 }
@@ -22,10 +17,5 @@ export type PublishResult = {
         message: string;
     };
 };
-/**
- * Publish the project the token is scoped to and return the platform
- * response (shareUrl, visibility, ...). The publish target is identified by
- * the token's claims (workspaceSlug/projectSlug), so no project path is sent.
- */
 export declare function publish(options?: PublishOptions): Promise<PublishResult>;
 export {};

package/dist/src/lib/registry-access.d.ts

@@ -0,0 +1,29 @@
+import type { ProjectRef } from "./registry";
+export type AccessGrant = {
+    status: "ok";
+    token: string;
+    expiresAt: number;
+} | {
+    status: "public";
+} | {
+    status: "no-credential";
+} | {
+    status: "denied";
+    httpStatus?: number;
+    message: string;
+};
+export interface AccessTokenCacheOptions {
+    fetchImpl?: typeof fetch;
+    nowSeconds?: () => number;
+}
+export declare class RegistryAccessTokens {
+    private readonly cache;
+    private readonly fetchImpl;
+    private readonly nowSeconds;
+    constructor(options?: AccessTokenCacheOptions);
+    peek(ref: ProjectRef): string;
+    get(ref: ProjectRef, apiHint?: string): Promise<AccessGrant>;
+    private mint;
+}
+export declare const defaultRegistryAccessTokens: RegistryAccessTokens;
+export declare function withAccessToken(url: string, token: string): string;

package/dist/src/lib/registry.d.ts

@@ -1,42 +1,20 @@
+import { type RegistryAccessTokens } from "./registry-access";
 import { type Origins } from "@extension.dev/urls/origins";
 export declare const REGISTRY_BASE_DEFAULT: string;
-/**
- * Resolve the fleet origins from the MCP's env vars, once per call. Console,
- * registry, and media all DERIVE from the platform base (`EXTENSION_DEV_API_URL`
- * or a per-tool `api`): point that at a local stack and every dashboard link the
- * MCP hands back follows to the dev host (`console.extension.localhost`) instead
- * of silently pointing at prod. Explicit per-host env vars still win. Falls back
- * to production when nothing is set. The dev-derivation lives in
- * `@extension.dev/urls` so it stays identical to what the apps resolve.
- */
 export declare function mcpOrigins(apiHint?: string): Origins;
-/** Base origin of the console dashboard, dev-aware (no trailing slash). */
 export declare function consoleBase(apiHint?: string): string;
 export declare function registryBase(): string;
 export interface ProjectRef {
     workspace: string;
     project: string;
 }
-/**
- * Resolve which project registry reads should target: explicit overrides
- * first, then the stored login's workspace/project slugs. Returns null when
- * neither names a project (e.g. token came from EXTENSION_DEV_TOKEN and no
- * login was ever stored).
- */
 export declare function resolveProjectRef(overrides?: {
     workspace?: string;
     project?: string;
 }): ProjectRef | null;
-/** URL of a file under the project's `_extension-dev/` registry directory. */
 export declare function registryFileUrl(ref: ProjectRef, file: string): string;
-/**
- * Console page URL for the project (builds, releases/new, stores, ...). The
- * origin is dev-aware; the path comes from the shared route contract so a
- * console route rename is caught in one place. Pass `apiHint` (a tool's `api`
- * arg) so the link matches that call's environment; otherwise it follows
- * `EXTENSION_DEV_API_URL`/`EXTENSION_DEV_CONSOLE_URL`.
- */
 export declare function consoleProjectUrl(ref: ProjectRef | null, page: string, apiHint?: string): string;
+export declare function userlandProjectUrl(ref: ProjectRef | null, page?: string, apiHint?: string): string;
 export type RegistryFetchResult<T> = {
     ok: true;
     json: T;
@@ -45,27 +23,19 @@ export type RegistryFetchResult<T> = {
     status?: number;
     message: string;
 };
-/**
- * Fetch a registry JSON file. Never throws: 404s (private or never-built
- * projects), network failures, and non-JSON bodies all come back as
- * `{ok:false}` so callers can degrade honestly instead of crashing the verb.
- */
-export declare function fetchRegistryJson<T = unknown>(url: string, fetchImpl?: typeof fetch): Promise<RegistryFetchResult<T>>;
+export declare function fetchRegistryJson<T = unknown>(url: string, fetchImpl?: typeof fetch, options?: {
+    ref?: ProjectRef | null;
+    api?: string;
+    tokens?: RegistryAccessTokens;
+}): Promise<RegistryFetchResult<T>>;
 export interface ChannelEntry {
     channel: string;
     sha: string;
     buildId?: string;
     version?: string;
-    /** ISO timestamp parsed from the channel row when the writer recorded one. */
     promotedAt?: string;
     description?: string;
 }
-/**
- * Normalize the registry's channels.json (a map of channel -> row) into a
- * list. `promotedAt` is not a first-class field in the file today; the
- * promote workflow stamps it into the description ("Promoted from X on
- * <ISO>"), so it is parsed back out when present.
- */
 export declare function parseChannels(json: unknown): ChannelEntry[];
 export interface BuildIndexItem {
     sha: string;
@@ -78,13 +48,5 @@ export interface BuildIndexItem {
     timestamp?: string;
     browsers?: string[];
 }
-/** Normalize `_extension-dev/builds/index.json` items (schemaVersion 3). */
 export declare function parseBuildIndex(json: unknown): BuildIndexItem[];
-/**
- * Derive the project mirror repo's Actions URL from any GitHub run URL the
- * registry exposes (stores/status.json carries one from the mirror's own
- * runs: https://github.com/extensiondev/<ownerGithubId>--<projectId>/actions/
- * runs/<id>). Only trusts the extensiondev org so a user-source-repo run URL
- * (build.json's runUrl) is never mistaken for the mirror.
- */
 export declare function mirrorActionsUrlFromRunUrl(runUrl: unknown): string | null;

package/dist/src/lib/share-record.d.ts

@@ -0,0 +1,26 @@
+import { type ProjectIgnoreState } from "./project-ignore";
+export declare const SHARE_STATE_DIR = ".extension.dev";
+export declare const SHARE_RECORD_FILE = "shared-previews.json";
+export interface SharedPreviewEntry {
+    sharedAt: string;
+    previewUrl: string;
+    artifactId: string;
+    revokeUrl?: string;
+    expiresAt?: string;
+    zipUrl?: string;
+    name?: string;
+    version?: string;
+    browser?: string;
+    distDir?: string;
+}
+export interface ShareRecordOutcome {
+    recorded: boolean;
+    path: string;
+    entries?: number;
+    gitignored?: ProjectIgnoreState;
+    preserved?: string;
+    note: string;
+    warning?: string;
+}
+export declare function sharedPreviewsPath(projectPath: string): string;
+export declare function recordSharedPreview(projectPath: string, entry: SharedPreviewEntry): ShareRecordOutcome;

package/dist/src/lib/vendor/chrome-theme/chrome-theme-color-math.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Exact TypeScript ports of the Chromium color math used by the browser
+ * theme pipeline (ui/gfx/color_utils.cc, refs/heads/main, cached under
+ * parity/chromium-src-cache, fetched 2026-07-04).
+ *
+ * Every function mirrors its Chromium namesake so the theme resolver can
+ * reproduce Chrome's derived colors bit-for-bit. When editing, re-read the
+ * cited source instead of "fixing" the math: several rules (HSL lightness
+ * shift in RGB space, the luminance midpoint, alpha normalization) are
+ * deliberately not the textbook versions.
+ */
+export interface RgbaColor {
+    r: number;
+    g: number;
+    b: number;
+    /** 0..255, like SkColor. */
+    a: number;
+}
+/** HSL tint triple; -1 in a channel means "leave unchanged". */
+export interface HslTint {
+    h: number;
+    s: number;
+    l: number;
+}
+/** color_utils.cc:35 g_darkest_color = gfx::kGoogleGrey900. */
+export declare const DARKEST_COLOR: RgbaColor;
+/**
+ * color_utils.cc:40 g_luminance_midpoint: the luminance where white and
+ * kGoogleGrey900 contrast equally. IsDark() pivots here, NOT at 0.5.
+ */
+export declare const LUMINANCE_MIDPOINT = 0.211692036;
+/** color_utils.cc kMinimumReadableContrastRatio. */
+export declare const MINIMUM_READABLE_CONTRAST_RATIO = 4.5;
+export declare function rgba(r: number, g: number, b: number, a?: number): RgbaColor;
+export declare function parseHexColor(hex: string): RgbaColor;
+export declare function toHexColor(color: RgbaColor): string;
+/** base::ClampRound for the 0..255 channel domain. */
+export declare function clampRound(value: number): number;
+/** color_utils.cc:425 GetRelativeLuminance4f. */
+export declare function relativeLuminance(color: RgbaColor): number;
+/** color_utils.cc:412 GetContrastRatio (luminance form). */
+export declare function contrastRatioFromLuminance(a: number, b: number): number;
+/** color_utils.cc:402 GetContrastRatio. */
+export declare function contrastRatio(a: RgbaColor, b: RgbaColor): number;
+/** color_utils.cc:617 IsDark: luminance below the grey900/white midpoint. */
+export declare function isDarkChromium(color: RgbaColor): boolean;
+/** color_utils.cc:621 GetColorWithMaxContrast: white or kGoogleGrey900. */
+export declare function getColorWithMaxContrast(color: RgbaColor): RgbaColor;
+/** color_utils.cc:625 GetEndpointColorWithMinContrast. */
+export declare function getEndpointColorWithMinContrast(color: RgbaColor): RgbaColor;
+/** color_utils.cc:436 SkColorToHSL. */
+export declare function skColorToHsl(color: RgbaColor): HslTint;
+/** color_utils.cc:467 HSLToSkColor. */
+export declare function hslToSkColor(hsl: HslTint, alpha: number): RgbaColor;
+/** color_utils.cc:518 MakeHSLShiftValid: out-of-range channels become -1. */
+export declare function makeHslShiftValid(tint: HslTint): HslTint;
+/** A tint that leaves the color unchanged. */
+export declare const HSL_NO_TINT: HslTint;
+/**
+ * color_utils.cc:534 HSLShift, Chrome's tint operation. NOT a plain HSL
+ * replacement: hue is replaced, saturation is scaled around 0.5, and the
+ * lightness shift happens in RGB space ("in the style of popular image
+ * editors").
+ */
+export declare function hslShift(color: RgbaColor, shift: HslTint): RgbaColor;
+/**
+ * color_utils.cc:581 AlphaBlend(float): weights each side by its own alpha
+ * times the blend factor (a foreground with alpha participates less).
+ */
+export declare function alphaBlend(foreground: RgbaColor, background: RgbaColor, alpha: number): RgbaColor;
+/** color_utils.cc:612 GetResultingPaintColor: composite fg over opaque bg. */
+export declare function getResultingPaintColor(foreground: RgbaColor, background: RgbaColor): RgbaColor;
+export interface BlendResult {
+    alpha: number;
+    color: RgbaColor;
+}
+/**
+ * color_utils.cc:647 BlendForMinContrast: binary-search the smallest blend
+ * of the target foreground into the default foreground that reaches
+ * `targetContrastRatio` against `background`.
+ */
+export declare function blendForMinContrast(defaultForeground: RgbaColor, background: RgbaColor, highContrastForeground?: RgbaColor, targetContrastRatio?: number): BlendResult;
+/** browser_theme_pack.cc:605 IsColorGrayscale: channel range under 9. */
+export declare function isColorGrayscale(color: RgbaColor): boolean;