@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/config-package/generated/validate-config.cjs

@@ -0,0 +1,293 @@
+'use strict';
+
+// Canonical config object validator / in-memory migrator.
+//
+// Reads a parsed config value (already JSONC-decoded by the caller) in schema
+// v1/v2/v3, validates fields, and normalizes to an in-memory v3 model. Higher
+// versions are `unsupported` with zero writes. Path fields must be POSIX
+// relative and reject absolute paths, `..`, NUL and backslash escapes.
+
+const VERSION = 3;
+
+const ALLOWED_COMMON_KEYS = new Set([
+  'schemaVersion',
+  'tier',
+  'target',
+  'outputDir',
+  'defaultTheme',
+  'themes',
+  'icons',
+  'missingIconPolicy',
+  'downloadMode',
+  'integration',
+]);
+
+const ALLOWED_THEME_KEYS = new Set([
+  'styleGroup',
+  'icons',
+  'styles',
+  'format',
+  'imageSize',
+  'defaultSize',
+  'strokeWidth',
+  'className',
+]);
+
+const TARGETS = new Set(['react', 'vue', 'vanilla', 'assets']);
+const ADAPTERS = new Set([
+  'vite-react',
+  'next-app',
+  'next-pages',
+  'vite-vue',
+  'nuxt',
+  'vanilla',
+  'assets-only',
+]);
+const FORMATS = new Set(['svg', 'webp', 'png']);
+const IMAGE_SIZES = new Set([64, 128, 256, 512]);
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function fail(message) {
+  return { ok: false, kind: 'invalid', message };
+}
+
+function unsupported(version) {
+  return { ok: false, kind: 'unsupported', version };
+}
+
+/** Reject absolute paths, `..`, NUL and backslash escapes (POSIX relative only). */
+function checkPath(value, field) {
+  if (typeof value !== 'string' || value.length === 0) {
+    return fail(`${field} must be a non-empty string`);
+  }
+  if (value.includes('\0') || value.includes('\\')) {
+    return fail(`${field} must be a POSIX relative path (no backslash/NUL)`);
+  }
+  if (value.startsWith('/') || /^[A-Za-z]:/.test(value)) {
+    return fail(`${field} must be relative, not absolute`);
+  }
+  const segments = value.split('/');
+  if (segments.some((seg) => !seg || seg === '..' || seg === '.')) {
+    return fail(`${field} must not contain '.' or '..' segments`);
+  }
+  if (field === 'outputDir' && ['.git', '.moeicons', 'node_modules'].includes(segments[0])) {
+    return fail('outputDir cannot use a project control directory');
+  }
+  if (field === 'outputDir' && !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(value)) {
+    return fail('outputDir must use ASCII letters, digits, _, -, and safe dotted child segments');
+  }
+  return null;
+}
+
+function flattenIcons(value) {
+  if (Array.isArray(value) && value.every((item) => typeof item === 'string')) return value;
+  if (!isRecord(value)) {
+    throw new Error('icons must be an array or prefix-group object');
+  }
+  const result = [];
+  for (const prefix of Object.keys(value).sort()) {
+    const group = value[prefix];
+    if (!Array.isArray(group) || !group.every((item) => typeof item === 'string')) {
+      throw new Error(`icons.${prefix} must be an array of icon IDs`);
+    }
+    result.push(...group);
+  }
+  return result;
+}
+
+function findGroup(id, catalog) {
+  return (catalog.styleGroups || []).find((g) => g.id === id);
+}
+
+function findIcon(id, catalog) {
+  return (catalog.icons || []).find((icon) => icon.id === id);
+}
+
+/** Validate + normalize into the v3 in-memory model. */
+function validateConfig(raw, catalog) {
+  if (!isRecord(raw)) return fail('config must be an object');
+  const version = raw.schemaVersion;
+  if (typeof version !== 'number') return fail('schemaVersion must be a number');
+  if (version !== 1 && version !== 2 && version !== 3) return unsupported(version);
+
+  // Common unknown-field rejection per version.
+  for (const key of Object.keys(raw)) {
+    if (!ALLOWED_COMMON_KEYS.has(key)) {
+      if (key === 'framework' && version === 1) continue;
+      return fail(`unknown config field "${key}"`);
+    }
+  }
+
+  if (raw.tier !== 'free' && raw.tier !== 'pro') return fail('tier must be free or pro');
+  if (typeof raw.outputDir !== 'string' || raw.outputDir.length === 0) {
+    return fail('outputDir is required');
+  }
+
+  const pathCheck = checkPath(raw.outputDir, 'outputDir');
+  if (pathCheck) return pathCheck;
+
+  let target;
+  if (version === 1) {
+    if (raw.framework !== 'react' && raw.framework !== 'vue') {
+      return fail('framework must be react or vue (schema v1)');
+    }
+    target = raw.framework;
+  } else {
+    if (!TARGETS.has(raw.target)) return fail('target must be react, vue, vanilla, or assets');
+    target = raw.target;
+  }
+
+  if (typeof raw.defaultTheme !== 'string' || raw.defaultTheme.length === 0) {
+    return fail('defaultTheme is required');
+  }
+  if (raw.downloadMode !== undefined && !['auto', 'icons', 'full'].includes(raw.downloadMode)) return fail('downloadMode must be "auto", "icons" or "full"');
+  if (
+    raw.missingIconPolicy !== undefined &&
+    raw.missingIconPolicy !== 'fallback' &&
+    raw.missingIconPolicy !== 'error'
+  ) {
+    return fail('missingIconPolicy must be "fallback" or "error"');
+  }
+  if (!isRecord(raw.themes)) return fail('themes must be an object');
+
+  const themes = {};
+  const themeNames = new Map();
+  for (const [name, value] of Object.entries(raw.themes)) {
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name)) {
+      return fail(`theme key "${name}" must be lowercase kebab-case`);
+    }
+    const internalName = name.replace(/-/g, '').toLowerCase();
+    if (themeNames.has(internalName)) {
+      return fail(`theme keys "${themeNames.get(internalName)}" and "${name}" generate the same identifier`);
+    }
+    themeNames.set(internalName, name);
+    if (!isRecord(value)) return fail(`theme ${name} is invalid`);
+    for (const key of Object.keys(value)) {
+      if (!ALLOWED_THEME_KEYS.has(key)) return fail(`unknown field "${key}" in theme "${name}"`);
+    }
+    const group = findGroup(value.styleGroup, catalog);
+    if (!group) return fail(`unknown style group "${value.styleGroup}"`);
+    if (!group.tiers.includes(raw.tier)) {
+      return fail(`style group "${group.id}" is not available in ${raw.tier} tier`);
+    }
+    if (value.format !== undefined && typeof value.format !== 'string') return fail(`theme ${name}.format is invalid`);
+    if (value.imageSize !== undefined && typeof value.imageSize !== 'number') return fail(`theme ${name}.imageSize is invalid`);
+    if (value.defaultSize !== undefined && (typeof value.defaultSize !== 'number' || !Number.isFinite(value.defaultSize) || value.defaultSize <= 0)) return fail(`theme ${name}.defaultSize must be a positive finite number`);
+    if (value.strokeWidth !== undefined && (typeof value.strokeWidth !== 'number' || !Number.isFinite(value.strokeWidth) || value.strokeWidth < 0)) return fail(`theme ${name}.strokeWidth must be a nonnegative finite number`);
+    if (value.className !== undefined && typeof value.className !== 'string') return fail(`theme ${name}.className must be a string`);
+    if (value.icons !== undefined && (!Array.isArray(value.icons) || value.icons.some((id) => typeof id !== 'string') || new Set(value.icons).size !== value.icons.length)) {
+      return fail(`theme ${name}.icons must be an array of unique icon IDs`);
+    }
+    const format = typeof value.format === 'string' ? value.format : undefined;
+    if (format !== undefined && !FORMATS.has(format)) return fail(`theme ${name}.format is invalid`);
+    const imageSize = typeof value.imageSize === 'number' ? value.imageSize : undefined;
+    if (imageSize !== undefined && !IMAGE_SIZES.has(imageSize)) {
+      return fail(`theme ${name}.imageSize is invalid`);
+    }
+    if (
+      group.type !== 'bitmap' &&
+      ((format !== undefined && format !== 'svg') || imageSize !== undefined)
+    ) {
+      return fail(`SVG theme ${name} cannot define bitmap options`);
+    }
+    if (
+      group.type === 'bitmap' &&
+      format !== undefined &&
+      !(group.formats || []).includes(format)
+    ) {
+      return fail(`format ${format} is unavailable for ${group.id}`);
+    }
+    if (
+      group.type === 'bitmap' &&
+      imageSize !== undefined &&
+      !(group.imageSizes || []).includes(imageSize)
+    ) {
+      return fail(`imageSize ${imageSize} is unavailable for ${group.id}`);
+    }
+    themes[name] = {
+      styleGroup: value.styleGroup,
+      ...(value.icons !== undefined ? { icons: [...value.icons] } : {}),
+      ...(format !== undefined ? { format } : {}),
+      ...(imageSize !== undefined ? { imageSize } : {}),
+      ...(typeof value.defaultSize === 'number' ? { defaultSize: value.defaultSize } : {}),
+      ...(typeof value.strokeWidth === 'number' ? { strokeWidth: value.strokeWidth } : {}),
+      ...(typeof value.className === 'string' ? { className: value.className } : {}),
+    };
+  }
+  if (!(raw.defaultTheme in themes)) {
+    return fail(`defaultTheme "${raw.defaultTheme}" is not defined`);
+  }
+
+  let icons;
+  try {
+    icons = flattenIcons(raw.icons);
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+  for (const iconId of icons) {
+    if (!findIcon(iconId, catalog)) return fail(`unknown icon "${iconId}"`);
+  }
+  for (const [name, theme] of Object.entries(themes)) {
+    for (const iconId of theme.icons || []) {
+      if (!icons.includes(iconId)) return fail(`theme ${name}.icons contains unregistered icon "${iconId}"; add it to project icons first`);
+    }
+  }
+
+  let integration;
+  if (raw.integration !== undefined) {
+    if (!isRecord(raw.integration)) return fail('integration must be an object');
+    for (const key of Object.keys(raw.integration)) {
+      if (!['adapter', 'entry', 'style'].includes(key)) {
+        return fail(`unknown integration field "${key}"`);
+      }
+    }
+    if (!ADAPTERS.has(raw.integration.adapter)) {
+      return fail(`integration.adapter is not a supported adapter`);
+    }
+    if (raw.integration.adapter !== 'assets-only') {
+      const entry = checkPath(raw.integration.entry, 'integration.entry');
+      if (entry) return entry;
+    } else if (raw.integration.entry !== undefined) {
+      const entry = checkPath(raw.integration.entry, 'integration.entry');
+      if (entry) return entry;
+    }
+    if (raw.integration.style !== undefined) {
+      const style = checkPath(raw.integration.style, 'integration.style');
+      if (style) return style;
+    }
+    integration = {
+      adapter: raw.integration.adapter,
+      ...(raw.integration.entry !== undefined ? { entry: raw.integration.entry } : {}),
+      ...(raw.integration.style !== undefined ? { style: raw.integration.style } : {}),
+    };
+  }
+
+  return {
+    ok: true,
+    warnings:
+      version === 1
+        ? ['config schema v1 migrated "framework" to "target"']
+        : version === 2
+          ? ['config schema v2 normalized to in-memory v3']
+          : [],
+    config: {
+      schemaVersion: VERSION,
+      tier: raw.tier,
+      target,
+      outputDir: raw.outputDir,
+      defaultTheme: raw.defaultTheme,
+      themes,
+      icons,
+      ...(raw.downloadMode !== undefined ? { downloadMode: raw.downloadMode } : {}),
+      ...(raw.missingIconPolicy !== undefined
+        ? { missingIconPolicy: raw.missingIconPolicy }
+        : {}),
+      ...(integration !== undefined ? { integration } : {}),
+    },
+  };
+}
+
+module.exports = { validateConfig, VERSION, ADAPTERS };

package/dist/config-package/generated-config.d.ts

@@ -0,0 +1,32 @@
+export interface GeneratedRenderOptions {
+    target?: "react" | "vue" | "vanilla" | "assets";
+    framework?: "react" | "vue";
+    tier?: "free" | "pro";
+    fullCatalog?: boolean;
+    catalog: unknown;
+    integration?: {
+        adapter: string;
+        entry?: string;
+        style?: string;
+    };
+}
+export interface GeneratedConfigPackage {
+    renderMoeiconsConfigJsonc(options: GeneratedRenderOptions): string;
+    validateConfig(raw: unknown, catalog: unknown): {
+        ok: boolean;
+        kind?: string;
+        message?: string;
+        version?: number;
+        warnings?: string[];
+        config?: unknown;
+    };
+    VERSION: number;
+}
+/**
+ * Load the code-library canonical config-package modules that were synced into
+ * `src/config-package/generated/`. The generated copy is committed with
+ * SOURCE.json (code-library commit + file digests) and copied to dist at build
+ * time so both tests (src) and the packaged CLI (dist) resolve the same
+ * relative path.
+ */
+export declare function loadGeneratedConfigPackage(): GeneratedConfigPackage;

package/dist/config-package/generated-config.js

@@ -0,0 +1,19 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+/**
+ * Load the code-library canonical config-package modules that were synced into
+ * `src/config-package/generated/`. The generated copy is committed with
+ * SOURCE.json (code-library commit + file digests) and copied to dist at build
+ * time so both tests (src) and the packaged CLI (dist) resolve the same
+ * relative path.
+ */
+export function loadGeneratedConfigPackage() {
+    const root = dirname(fileURLToPath(import.meta.url));
+    const renderPath = join(root, "..", "config-package", "generated", "render-config.cjs");
+    const validatePath = join(root, "..", "config-package", "generated", "validate-config.cjs");
+    const renderer = require(renderPath);
+    const validator = require(validatePath);
+    return { ...renderer, ...validator };
+}

package/dist/core/auth.d.ts

@@ -23,10 +23,34 @@ export type SessionStatus = {
 };
 /** Probe existing credentials without prompting for or creating fallback storage. */
 export declare function runSessionStatusUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<SessionStatus>;
+export type MoeiconsEnvironment = "production" | "local";
+export interface AuthEnvironment {
+    readonly mode: MoeiconsEnvironment;
+    readonly label: string;
+    readonly apiBaseUrl: string;
+    readonly websiteOrigin: string;
+    readonly auth0Issuer: string;
+    readonly auth0ClientId: string;
+}
+/**
+ * H5: resolve a single coherent auth environment. `MOEICONS_ENV` may declare
+ * `local` or `production`; when set it must agree with the endpoints. Loopback
+ * HTTP is only allowed for local, and the API/website must not be mixed across
+ * environments so a dev token can never be written to production (or vice versa).
+ */
+export declare function resolveAuthEnvironment(env: Record<string, string | undefined>): AuthEnvironment;
+/** H5: human-readable environment label for `login`/`account` output. */
+export declare function describeAuthEnvironment(context: CommandContext): string;
 export declare function runLoginUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<ReturnType<typeof redactSession>>;
 /** Internal authenticated transport credential; adapters must never render it. */
 export declare function runAccessTokenUseCase(context: CommandContext, deps?: AuthUseCaseDependencies, forceRefresh?: boolean): Promise<string>;
 export declare function runAccountUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<ReturnType<typeof redactSession>>;
+/** Remote Worker entitlement lookup (H2); never guesses a plan from scope. */
+export declare function runRemoteAccountUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<{
+    tier: string;
+    entitlementStatus: string;
+    validUntil: string | null;
+} | undefined>;
 export declare function runLogoutUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<{
     revoked: boolean;
 }>;

package/dist/core/auth.js

@@ -3,8 +3,9 @@ import { createFileTokenStore, createSystemTokenStore, redactSession } from "../
 import { openBrowser } from "../auth/open-browser.js";
 import { requestJson } from "../api/client.js";
 import { CliError } from "../errors/index.js";
-const API_BASE_URL = "https://api.moeicons.com";
-const WEBSITE_ORIGIN = "https://moeicons.com";
+const DEFAULT_API_BASE_URL = "https://api.moeicons.com";
+const DEFAULT_WEBSITE_ORIGIN = "https://moeicons.com";
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
 function existingStore(context, deps) {
     return deps.tokenStore ?? (context.env.MOEICONS_DISABLE_SYSTEM_KEYCHAIN === "1" ? undefined : (deps.systemTokenStore ?? createSystemTokenStore)()) ??
         (context.env.MOEICONS_TOKEN_STORE_DIR ? (deps.fileTokenStore ?? ((rootDir) => createFileTokenStore(rootDir ? { rootDir } : {})))(context.env.MOEICONS_TOKEN_STORE_DIR) : undefined);
@@ -53,20 +54,101 @@ async function selectStore(context, deps) {
         throw new CliError("AUTH_ERROR", "login requires secure credential storage");
     return (deps.fileTokenStore ?? ((rootDir) => createFileTokenStore(rootDir ? { rootDir } : {})))(context.env.MOEICONS_TOKEN_STORE_DIR);
 }
+function assertTrustedHttpBase(value, envName) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new CliError("VALIDATION_ERROR", `${envName} is not a valid URL`);
+    }
+    const loopback = parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+    if (parsed.protocol !== "https:" && !loopback) {
+        throw new CliError("VALIDATION_ERROR", `${envName} must be https or loopback http`);
+    }
+    return value.replace(/\/$/, "");
+}
+function isLoopbackHttp(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * H5: resolve a single coherent auth environment. `MOEICONS_ENV` may declare
+ * `local` or `production`; when set it must agree with the endpoints. Loopback
+ * HTTP is only allowed for local, and the API/website must not be mixed across
+ * environments so a dev token can never be written to production (or vice versa).
+ */
+export function resolveAuthEnvironment(env) {
+    const apiBaseUrl = assertTrustedHttpBase(env.MOEICONS_API_BASE_URL ?? DEFAULT_API_BASE_URL, "MOEICONS_API_BASE_URL");
+    const websiteOrigin = assertTrustedHttpBase(env.MOEICONS_WEBSITE_ORIGIN ?? DEFAULT_WEBSITE_ORIGIN, "MOEICONS_WEBSITE_ORIGIN");
+    const apiLoopback = isLoopbackHttp(apiBaseUrl);
+    const websiteLoopback = isLoopbackHttp(websiteOrigin);
+    if (apiLoopback !== websiteLoopback) {
+        throw new CliError("VALIDATION_ERROR", "MOEICONS_API_BASE_URL and MOEICONS_WEBSITE_ORIGIN must both be loopback (local) or both be non-loopback (production)");
+    }
+    const declared = env.MOEICONS_ENV;
+    if (declared !== undefined && declared !== "local" && declared !== "production") {
+        throw new CliError("VALIDATION_ERROR", "MOEICONS_ENV must be local or production");
+    }
+    const inferred = apiLoopback ? "local" : "production";
+    if (declared && declared !== inferred) {
+        throw new CliError("VALIDATION_ERROR", `MOEICONS_ENV=${declared} conflicts with configured endpoints (${inferred})`);
+    }
+    const mode = declared ?? inferred;
+    // H5: the Auth0 issuer receives refresh tokens, so it must match the mode.
+    const auth0Issuer = env.MOEICONS_AUTH0_ISSUER ?? "";
+    if (auth0Issuer) {
+        assertTrustedHttpBase(auth0Issuer, "MOEICONS_AUTH0_ISSUER");
+        const issuerLoopback = isLoopbackHttp(auth0Issuer);
+        if (mode === "local" && !issuerLoopback) {
+            throw new CliError("VALIDATION_ERROR", "local MOEICONS_AUTH0_ISSUER must be loopback http");
+        }
+        if (mode === "production" && issuerLoopback) {
+            throw new CliError("VALIDATION_ERROR", "production MOEICONS_AUTH0_ISSUER must be https");
+        }
+    }
+    return {
+        mode,
+        label: mode === "local" ? "local (dev)" : "production",
+        apiBaseUrl,
+        websiteOrigin,
+        auth0Issuer,
+        auth0ClientId: env.MOEICONS_AUTH0_CLIENT_ID ?? "",
+    };
+}
 function auth0Config(context) {
+    const resolved = resolveAuthEnvironment(context.env);
     return {
-        apiBaseUrl: API_BASE_URL,
-        websiteOrigin: WEBSITE_ORIGIN,
-        auth0Issuer: context.env.MOEICONS_AUTH0_ISSUER ?? "",
-        auth0ClientId: context.env.MOEICONS_AUTH0_CLIENT_ID ?? "",
+        apiBaseUrl: resolved.apiBaseUrl,
+        websiteOrigin: resolved.websiteOrigin,
+        auth0Issuer: resolved.auth0Issuer,
+        auth0ClientId: resolved.auth0ClientId,
     };
 }
+/** H5: human-readable environment label for `login`/`account` output. */
+export function describeAuthEnvironment(context) {
+    return resolveAuthEnvironment(context.env).label;
+}
 export async function runLoginUseCase(context, deps = {}) {
     const tokenStore = await selectStore(context, deps);
-    const request = deps.request ?? ((path, options) => requestJson({ baseUrl: API_BASE_URL }, path, { ...options, retries: options.method === "GET" ? 3 : 0 }));
+    const apiBaseUrl = auth0Config(context).apiBaseUrl;
+    const request = deps.request ??
+        ((path, options) => requestJson({ baseUrl: apiBaseUrl }, path, {
+            ...options,
+            retries: options.method === "GET" || options.method === "DELETE" ? 3 : 0,
+            ...(options.stage ? { stage: `login ${options.stage}` } : {}),
+        }));
+    // H4 test seam: loopback acceptance runs headless. Production never sets this.
+    const browserOpener = deps.openBrowser ??
+        (context.env.MOEICONS_NO_BROWSER === "1" ? () => Promise.resolve() : openBrowser);
     const session = await loginWithDeviceSession(auth0Config(context), {
         request,
-        openBrowser: deps.openBrowser ?? openBrowser,
+        openBrowser: browserOpener,
         sleep: deps.sleep ?? ((milliseconds, signal) => new Promise((resolve, reject) => {
             const timer = setTimeout(resolve, milliseconds);
             signal?.addEventListener("abort", () => { clearTimeout(timer); reject(new CliError("CANCELLED", "login cancelled")); }, { once: true });
@@ -105,6 +187,43 @@ export async function runAccessTokenUseCase(context, deps = {}, forceRefresh = f
 export async function runAccountUseCase(context, deps = {}) {
     return redactSession((await activeSession(context, deps)).session);
 }
+/** Remote Worker entitlement lookup (H2); never guesses a plan from scope. */
+export async function runRemoteAccountUseCase(context, deps = {}) {
+    const apiBaseUrl = auth0Config(context).apiBaseUrl;
+    const doFetch = deps.fetch ?? fetch;
+    let session;
+    try {
+        session = (await activeSession(context, deps)).session;
+    }
+    catch {
+        throw new CliError("AUTH_ERROR", "not logged in");
+    }
+    const call = async (token) => doFetch(`${apiBaseUrl}/v1/cli/account`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` },
+        signal: context.signal,
+    });
+    let response = await call(session.accessToken);
+    // 401 => refresh exactly once and retry (H2 point 6).
+    if (response.status === 401) {
+        const refreshed = await runAccessTokenUseCase(context, deps, true);
+        response = await call(refreshed);
+    }
+    if (response.status === 403) {
+        // no/expired entitlement: caller still has a valid account; report free.
+        return { tier: "free", entitlementStatus: "none", validUntil: null };
+    }
+    if (!response.ok) {
+        throw new CliError("NETWORK_ERROR", `account lookup failed with ${response.status}`);
+    }
+    const value = (await response.json());
+    if (typeof value.tier !== "string" ||
+        typeof value.entitlementStatus !== "string" ||
+        (value.validUntil !== null && typeof value.validUntil !== "string")) {
+        throw new CliError("VALIDATION_ERROR", "invalid account response");
+    }
+    return { tier: value.tier, entitlementStatus: value.entitlementStatus, validUntil: value.validUntil ?? null };
+}
 export async function runLogoutUseCase(context, deps = {}) {
     const store = existingStore(context, deps);
     if (!store)

package/dist/core/bitmap-assets.d.ts

@@ -1,16 +1,30 @@
 import { type ResourceVariant } from "./resource-variant.js";
 export interface SelectedBitmapAsset {
-    /** POSIX path relative to outputDir, e.g. assets/moe-cute-3d-webp-256/ui-search.webp */
+    /** POSIX path relative to outputDir, e.g. assets/example-bitmap-style-256-webp/ui-search.webp */
     readonly destRel: string;
     readonly bytes: Uint8Array;
     readonly resourceVariantId: string;
     readonly iconId: string;
 }
+export interface MatchBitmapOptions {
+    /**
+     * Media contract of the archive being read. Defaults to 2 (canonical actual
+     * directory names). Set to 1 to read frozen v1 artifacts through the explicit
+     * legacy parser; the two parsers are never mixed.
+     */
+    readonly mediaContractVersion?: 1 | 2;
+    /** Exact variant/icon pairs, used when a missing theme falls back to another group. */
+    readonly requestedPairs?: readonly {
+        readonly variantId: string;
+        readonly iconId: string;
+    }[];
+}
 /**
- * Identify a bitmap file inside a free/pro archive by parsing a directory
- * segment as resourceVariantId (G2, from the right). Never scans for a mid-path `-3d`.
+ * Identify a bitmap file at its canonical archive location
+ * `assets/<resourceVariantId>/<iconId>.<format>`. v2 uses controlled keyword
+ * tokens; v1 uses the explicit legacy `<group>-<format>-<size>` branch.
  */
-export declare function matchArchiveBitmapFile(archivePath: string): {
+export declare function matchArchiveBitmapFile(archivePath: string, options?: MatchBitmapOptions): {
     readonly variant: ResourceVariant;
     readonly iconId: string;
 } | undefined;
@@ -26,4 +40,4 @@ export type SelectBitmapAssetsResult = {
  * Keep only archive files that belong to the requested variants and selected
  * icons. Other sizes/formats stay in the tarball/cache and are not written.
  */
-export declare function selectBitmapVariantAssets(archiveFiles: Readonly<Record<string, Uint8Array>>, variants: readonly ResourceVariant[], iconIds: readonly string[]): SelectBitmapAssetsResult;
+export declare function selectBitmapVariantAssets(archiveFiles: Readonly<Record<string, Uint8Array>>, variants: readonly ResourceVariant[], iconIds: readonly string[], options?: MatchBitmapOptions): SelectBitmapAssetsResult;