@moewolf/moe-icons-cli 0.0.1

package/dist/project/config.js

@@ -0,0 +1,353 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "jsonc-parser";
+import { catalog, findCatalogIcon, findCatalogStyleGroup, } from "../catalog/catalog.js";
+export const SUPPORTED_FILENAMES = [
+    "moeicons.config.jsonc",
+    "moeicons.config.json",
+    "moeicons.config.ts",
+    "moeicons.config.js",
+];
+export function findConfigFile(root) {
+    for (const name of SUPPORTED_FILENAMES) {
+        if (existsSync(join(root, name)))
+            return join(root, name);
+    }
+    return undefined;
+}
+function parseJsonc(text) {
+    const errors = [];
+    const value = parse(text, errors, {
+        allowTrailingComma: true,
+        disallowComments: false,
+    });
+    return { value, errors };
+}
+function flattenIcons(value) {
+    if (Array.isArray(value) && value.every((item) => typeof item === "string"))
+        return value;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("icons must be an array or prefix-group object");
+    }
+    const groups = value;
+    const result = [];
+    for (const prefix of Object.keys(groups).sort()) {
+        const group = groups[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;
+}
+const ALLOWED_COMMON_KEYS = new Set([
+    "schemaVersion",
+    "tier",
+    "outputDir",
+    "defaultTheme",
+    "themes",
+    "icons",
+    "missingIconPolicy",
+]);
+const ALLOWED_THEME_KEYS = new Set([
+    "styleGroup",
+    "styles",
+    "format",
+    "imageSize",
+    "defaultSize",
+    "strokeWidth",
+    "className",
+]);
+function asRecord(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("config must be an object");
+    return raw;
+}
+function requireCommonConfigFields(obj, sourceCatalog) {
+    const warnings = [];
+    if (obj.tier !== "free" && obj.tier !== "pro")
+        throw new Error("tier must be free or pro");
+    const tier = obj.tier;
+    if (typeof obj.outputDir !== "string" || obj.outputDir.length === 0)
+        throw new Error("outputDir is required");
+    if (typeof obj.defaultTheme !== "string" || obj.defaultTheme.length === 0)
+        throw new Error("defaultTheme is required");
+    if (typeof obj.themes !== "object" || obj.themes === null || Array.isArray(obj.themes)) {
+        throw new Error("themes must be an object");
+    }
+    if (obj.missingIconPolicy !== undefined &&
+        obj.missingIconPolicy !== "fallback" &&
+        obj.missingIconPolicy !== "error") {
+        throw new Error(`missingIconPolicy must be "fallback" or "error"`);
+    }
+    const themes = {};
+    for (const [name, value] of Object.entries(obj.themes)) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new Error(`theme ${name} is invalid`);
+        const theme = value;
+        // Reject unknown theme fields.
+        for (const key of Object.keys(theme)) {
+            if (!ALLOWED_THEME_KEYS.has(key))
+                throw new Error(`unknown field "${key}" in theme "${name}"`);
+        }
+        if (typeof theme.styleGroup !== "string")
+            throw new Error(`theme ${name}.styleGroup is required`);
+        const group = findCatalogStyleGroup(theme.styleGroup, sourceCatalog);
+        if (!group)
+            throw new Error(`unknown style group "${theme.styleGroup}"`);
+        if (!group.tiers.includes(tier)) {
+            throw new Error(`style group "${group.id}" is not available in ${tier} tier`);
+        }
+        // styles[] is deprecated — still accepted for migration but warns.
+        if (Array.isArray(theme.styles) && theme.styles.length > 0) {
+            warnings.push(`theme "${name}": "styles" is deprecated and has no effect; remove it from your config`);
+        }
+        const format = typeof theme.format === "string" ? theme.format : undefined;
+        if (format !== undefined && format !== "svg" && format !== "webp" && format !== "png") {
+            throw new Error(`theme ${name}.format is invalid`);
+        }
+        const imageSize = typeof theme.imageSize === "number" ? theme.imageSize : undefined;
+        if (imageSize !== undefined && ![64, 128, 256, 512].includes(imageSize)) {
+            throw new Error(`theme ${name}.imageSize is invalid`);
+        }
+        if (group.type !== "bitmap" &&
+            ((format !== undefined && format !== "svg") || imageSize !== undefined)) {
+            throw new Error(`SVG theme ${name} cannot define bitmap options`);
+        }
+        if (group.type === "bitmap" && format !== undefined && !group.formats.includes(format)) {
+            throw new Error(`format ${format} is unavailable for ${group.id}`);
+        }
+        if (group.type === "bitmap" &&
+            imageSize !== undefined &&
+            !group.imageSizes.includes(imageSize)) {
+            throw new Error(`imageSize ${imageSize} is unavailable for ${group.id}`);
+        }
+        themes[name] = {
+            styleGroup: theme.styleGroup,
+            ...(format !== undefined ? { format } : {}),
+            ...(imageSize !== undefined ? { imageSize: imageSize } : {}),
+            ...(typeof theme.defaultSize === "number" ? { defaultSize: theme.defaultSize } : {}),
+            ...(typeof theme.strokeWidth === "number" ? { strokeWidth: theme.strokeWidth } : {}),
+            ...(typeof theme.className === "string" ? { className: theme.className } : {}),
+        };
+    }
+    if (!(obj.defaultTheme in themes))
+        throw new Error(`defaultTheme "${obj.defaultTheme}" is not defined`);
+    const icons = flattenIcons(obj.icons);
+    for (const iconId of icons)
+        if (!findCatalogIcon(iconId, sourceCatalog))
+            throw new Error(`unknown icon "${iconId}"`);
+    return {
+        warnings,
+        tier,
+        outputDir: obj.outputDir,
+        defaultTheme: obj.defaultTheme,
+        themes,
+        icons,
+        ...(obj.missingIconPolicy !== undefined
+            ? { missingIconPolicy: obj.missingIconPolicy }
+            : {}),
+    };
+}
+function normalizeTarget(value) {
+    if (value === "react" || value === "vue" || value === "vanilla" || value === "assets") {
+        return value;
+    }
+    throw new Error("target must be react, vue, vanilla, or assets");
+}
+/** Validate a schema version 2 config: target is required, framework is rejected. */
+function validateV2Config(raw, sourceCatalog) {
+    const obj = asRecord(raw);
+    if (obj.framework !== undefined)
+        throw new Error('framework is only supported in schemaVersion 1; use target');
+    for (const key of Object.keys(obj)) {
+        if (!ALLOWED_COMMON_KEYS.has(key) && key !== "target") {
+            throw new Error(`unknown config field "${key}"`);
+        }
+    }
+    if (obj.target === undefined)
+        throw new Error("target is required");
+    const target = normalizeTarget(obj.target);
+    const common = requireCommonConfigFields(obj, sourceCatalog);
+    return {
+        config: {
+            schemaVersion: 2,
+            tier: common.tier,
+            target,
+            outputDir: common.outputDir,
+            defaultTheme: common.defaultTheme,
+            themes: common.themes,
+            icons: common.icons,
+            ...(common.missingIconPolicy !== undefined
+                ? { missingIconPolicy: common.missingIconPolicy }
+                : {}),
+        },
+        warnings: common.warnings,
+    };
+}
+/** Validate a legacy schema version 1 config: framework is required, target is rejected. */
+function validateV1Config(raw, sourceCatalog) {
+    const obj = asRecord(raw);
+    for (const key of Object.keys(obj)) {
+        if (!ALLOWED_COMMON_KEYS.has(key) && key !== "framework") {
+            throw new Error(`unknown config field "${key}"`);
+        }
+    }
+    if (obj.target !== undefined)
+        throw new Error("v1 config cannot set target; migrate to schemaVersion 2");
+    if (obj.framework !== "react" && obj.framework !== "vue")
+        throw new Error("framework must be react or vue");
+    const common = requireCommonConfigFields(obj, sourceCatalog);
+    return {
+        config: {
+            schemaVersion: 2,
+            tier: common.tier,
+            target: obj.framework,
+            outputDir: common.outputDir,
+            defaultTheme: common.defaultTheme,
+            themes: common.themes,
+            icons: common.icons,
+            ...(common.missingIconPolicy !== undefined
+                ? { missingIconPolicy: common.missingIconPolicy }
+                : {}),
+        },
+        warnings: common.warnings,
+    };
+}
+export function readMoeiconsConfig(root, sourceCatalog = catalog) {
+    const configPath = findConfigFile(root);
+    if (!configPath)
+        return { kind: "missing" };
+    if (!configPath.endsWith(".json") && !configPath.endsWith(".jsonc")) {
+        return {
+            kind: "invalid",
+            message: "TS/JS config requires transpilation; use moeicons.config.jsonc",
+        };
+    }
+    const parsed = parseJsonc(readFileSync(configPath, "utf8"));
+    if (parsed.errors.length > 0 || parsed.value === undefined)
+        return { kind: "invalid", message: `cannot parse ${configPath}` };
+    const version = typeof parsed.value === "object" && parsed.value !== null && !Array.isArray(parsed.value)
+        ? parsed.value.schemaVersion
+        : undefined;
+    if (typeof version !== "number") {
+        return { kind: "invalid", message: "schemaVersion must be 1 or 2" };
+    }
+    if (version !== 1 && version !== 2)
+        return { kind: "unsupported", version };
+    try {
+        if (version === 1) {
+            const validated = validateV1Config(parsed.value, sourceCatalog);
+            validated.warnings.unshift('config schema v1 migrated "framework" to "target"');
+            return { kind: "ok", config: validated.config, warnings: validated.warnings };
+        }
+        const validated = validateV2Config(parsed.value, sourceCatalog);
+        return { kind: "ok", config: validated.config, warnings: validated.warnings };
+    }
+    catch (error) {
+        return { kind: "invalid", message: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Resolve the canonical v2 target from either a normalized v2 or legacy v1 input. */
+function targetFromInput(current) {
+    if ("target" in current)
+        return current.target;
+    return current.framework;
+}
+export function mergeMoeiconsConfig(current, patch) {
+    return {
+        schemaVersion: 2,
+        tier: patch.tier ?? current.tier,
+        target: patch.target ?? targetFromInput(current),
+        outputDir: patch.outputDir ?? current.outputDir,
+        defaultTheme: patch.defaultTheme ?? current.defaultTheme,
+        themes: patch.themes ?? current.themes,
+        icons: patch.icons ?? current.icons,
+        ...(patch.missingIconPolicy !== undefined
+            ? { missingIconPolicy: patch.missingIconPolicy }
+            : current.missingIconPolicy !== undefined
+                ? { missingIconPolicy: current.missingIconPolicy }
+                : {}),
+    };
+}
+export function createMoeiconsConfig(options) {
+    const tier = options.tier ?? "free";
+    return {
+        schemaVersion: 2,
+        tier,
+        target: options.target ?? options.framework ?? "react",
+        outputDir: options.outputDir ?? "src/moeicons",
+        defaultTheme: "outline",
+        themes: options.themes ?? {
+            outline: { styleGroup: "moe-outline", className: "text-zinc-700" },
+        },
+        icons: options.icons ?? [],
+        missingIconPolicy: "fallback",
+    };
+}
+/** Render the editable, grouped JSONC skeleton used by `init`. */
+export function renderMoeiconsConfigJsonc(options) {
+    const tier = options.tier ?? "free";
+    const target = options.target ?? options.framework ?? "react";
+    // Collect style groups available for this tier, ordered by id.
+    const availableGroups = catalog.styleGroups
+        .filter((g) => g.tiers.includes(tier))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const defaultThemeName = "outline";
+    // Build theme entries: one per available SVG group (bitmap groups get their
+    // own entry with format/imageSize annotations).
+    const themeLines = [];
+    for (const group of availableGroups) {
+        const themeName = group.id.replace(/^moe-/, "");
+        if (group.type === "bitmap") {
+            // List available format/imageSize combinations as inline comments.
+            const formatsComment = `// format options: ${group.formats.join(", ")}`;
+            const sizesComment = `// imageSize options: ${group.imageSizes.join(", ")}`;
+            themeLines.push(`    // ${themeName} — bitmap style (${group.id})`, `    // ${formatsComment}`, `    // ${sizesComment}`, `    // ${JSON.stringify(themeName)}: {`, `    //   "styleGroup": ${JSON.stringify(group.id)},`, `    //   "format": "webp",`, `    //   "imageSize": 256`, `    // },`);
+        }
+        else {
+            themeLines.push(`    ${JSON.stringify(themeName)}: {`, `      "styleGroup": ${JSON.stringify(group.id)}`, `    },`);
+        }
+    }
+    // Collect icons: only those available in at least one style group of this tier,
+    // grouped by prefix and default-selected (all selected).
+    const tierGroupIds = new Set(availableGroups.map((g) => g.id));
+    const groups = new Map();
+    for (const icon of catalog.icons) {
+        if (!icon.availableIn.some((sg) => tierGroupIds.has(sg)))
+            continue;
+        const ids = groups.get(icon.prefix) ?? [];
+        ids.push(icon.id);
+        groups.set(icon.prefix, ids);
+    }
+    const iconLines = [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .flatMap(([prefix, ids]) => [
+        `    // ${prefix} icons`,
+        `    ${JSON.stringify(prefix)}: [`,
+        ...ids.map((id) => `      ${JSON.stringify(id)},`),
+        "    ],",
+    ]);
+    return [
+        "{",
+        `  "schemaVersion": 2,`,
+        `  "tier": ${JSON.stringify(tier)},`,
+        `  "target": ${JSON.stringify(target)},`,
+        `  "outputDir": "src/moeicons",`,
+        `  "defaultTheme": ${JSON.stringify(defaultThemeName)},`,
+        '  "themes": {',
+        ...themeLines,
+        `    // Set defaultTheme above to one of: ${availableGroups
+            .filter((g) => g.type !== "bitmap")
+            .map((g) => JSON.stringify(g.id.replace(/^moe-/, "")))
+            .join(", ")}`,
+        "  },",
+        "  // Comment out individual IDs or a complete prefix group to exclude it.",
+        '  "icons": {',
+        ...iconLines,
+        "  },",
+        '  "missingIconPolicy": "fallback"',
+        "}",
+        "",
+    ].join("\n");
+}

package/dist/project/detect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Project/workspace/package-manager detection. Detection never writes and never
+ * guesses; ambiguous cases are errors that require selection.
+ */
+export type PackageManager = "npm" | "pnpm" | "yarn" | "unknown";
+export interface DetectedProject {
+    /** Absolute path to the directory containing package.json. */
+    readonly root: string;
+    readonly packageManager: PackageManager;
+    /** Workspace members if this root declares workspaces. */
+    readonly workspaceMembers: readonly string[];
+    readonly framework: "react" | "vue" | "unknown";
+}
+/** Walk upward from startDir to find the nearest package.json. */
+export declare function findProjectRoot(startDir: string): string | undefined;
+/**
+ * Detect the package manager by lockfile precedence: pnpm-lock.yaml, then
+ * yarn.lock, then package-lock.json. Conflicting lockfiles are an error.
+ */
+export declare function detectPackageManager(root: string): PackageManager;
+/** Read npm/pnpm workspace declarations. */
+export declare function detectWorkspace(root: string): readonly string[];
+/** Detect project at startDir, returning root + workspace members. */
+export declare function detectProject(startDir: string): DetectedProject | undefined;
+/** Confirm a target is inside a selected workspace and not node_modules. */
+export declare function assertWritableProject(root: string, target: string, workspaceMembers: readonly string[]): string[];

package/dist/project/detect.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname, parse } from "node:path";
+/** Walk upward from startDir to find the nearest package.json. */
+export function findProjectRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(join(dir, "package.json"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function readJsonSafe(file) {
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof raw === "object" && raw !== null)
+            return raw;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Detect the package manager by lockfile precedence: pnpm-lock.yaml, then
+ * yarn.lock, then package-lock.json. Conflicting lockfiles are an error.
+ */
+export function detectPackageManager(root) {
+    const hasPnpm = existsSync(join(root, "pnpm-lock.yaml"));
+    const hasYarn = existsSync(join(root, "yarn.lock"));
+    const hasNpm = existsSync(join(root, "package-lock.json"));
+    const present = [hasPnpm, hasYarn, hasNpm].filter(Boolean).length;
+    if (present > 1) {
+        // conflict: caller must ask the user to choose, never guess
+        return "unknown";
+    }
+    if (hasPnpm)
+        return "pnpm";
+    if (hasYarn)
+        return "yarn";
+    if (hasNpm)
+        return "npm";
+    return "unknown";
+}
+/** Read npm/pnpm workspace declarations. */
+export function detectWorkspace(root) {
+    const packageJson = readJsonSafe(join(root, "package.json"));
+    if (packageJson) {
+        const workspaces = packageJson.workspaces;
+        if (typeof workspaces === "string")
+            return [workspaces];
+        if (Array.isArray(workspaces)) {
+            return workspaces.filter((w) => typeof w === "string");
+        }
+    }
+    if (existsSync(join(root, "pnpm-workspace.yaml"))) {
+        const content = readFileSync(join(root, "pnpm-workspace.yaml"), "utf8");
+        const lines = content
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => !l.startsWith("#") && l.length > 0);
+        const packages = lines
+            .filter((l) => !l.startsWith("packages:"))
+            .map((l) => l.replace(/^\s*-\s*/, "").replace(/["']/g, "").trim())
+            .filter((l) => l.length > 0);
+        return packages;
+    }
+    return [];
+}
+/** Detect project at startDir, returning root + workspace members. */
+export function detectProject(startDir) {
+    const root = findProjectRoot(startDir);
+    if (!root)
+        return undefined;
+    const packageManager = detectPackageManager(root);
+    const workspaceMembers = detectWorkspace(root);
+    const pkg = readJsonSafe(join(root, "package.json"));
+    const dependencyNames = new Set([
+        ...Object.keys(pkg?.dependencies ?? {}),
+        ...Object.keys(pkg?.devDependencies ?? {}),
+    ]);
+    const hasReact = dependencyNames.has("react");
+    const hasVue = dependencyNames.has("vue");
+    const framework = hasReact === hasVue ? "unknown" : hasVue ? "vue" : "react";
+    return { root, packageManager, workspaceMembers, framework };
+}
+/** Confirm a target is inside a selected workspace and not node_modules. */
+export function assertWritableProject(root, target, workspaceMembers) {
+    const errors = [];
+    if (target.split(/[\\/]/).includes("node_modules")) {
+        errors.push("target must not be inside node_modules");
+    }
+    if (workspaceMembers.length > 0) {
+        const resolvedRoot = parse(root).root;
+        const inside = workspaceMembers.some((member) => target.startsWith(join(root, member)) || target === root);
+        if (!inside) {
+            errors.push(`target is outside the selected workspace at ${resolvedRoot}`);
+        }
+    }
+    return errors;
+}

package/dist/project/install-metadata.d.ts

@@ -0,0 +1,29 @@
+export interface InstallMetadata {
+    readonly schemaVersion: 1;
+    readonly artifactVersion: string;
+    readonly tier: "free" | "pro";
+    readonly target: "react" | "vue" | "vanilla" | "assets";
+    readonly descriptorSha256: string;
+    readonly artifactSha256: string;
+    readonly catalogSha256: string;
+    readonly installedAt: string;
+    readonly managedFiles: Readonly<Record<string, string>>;
+    /** Verified target subtree hash/size recorded at install time. */
+    readonly targetSha256?: string;
+    readonly targetFileCount?: number;
+    readonly targetByteCount?: number;
+}
+export type InstalledResourceState = {
+    readonly kind: "ok";
+    readonly metadata: InstallMetadata;
+} | {
+    readonly kind: "missing";
+    readonly message: string;
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+};
+export declare function sha256Bytes(value: string | Uint8Array): string;
+export declare function parseInstallMetadata(raw: string): InstallMetadata | undefined;
+export declare function serializeInstallMetadata(metadata: InstallMetadata): string;
+export declare function readInstalledResourceState(projectRoot: string, expectedTier?: "free" | "pro"): InstalledResourceState;

package/dist/project/install-metadata.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const SHA256 = /^[a-f0-9]{64}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-(?:alpha|beta))?$/;
+const UTC_RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+export function sha256Bytes(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function safeManagedPath(path) {
+    return (path.length > 0 &&
+        !path.startsWith("/") &&
+        !/^[A-Za-z]:/.test(path) &&
+        !path.includes("\\") &&
+        !path.split("/").includes(".."));
+}
+export function parseInstallMetadata(raw) {
+    try {
+        const value = JSON.parse(raw);
+        const allowed = new Set([
+            "schemaVersion",
+            "artifactVersion",
+            "tier",
+            "target",
+            "descriptorSha256",
+            "artifactSha256",
+            "catalogSha256",
+            "installedAt",
+            "managedFiles",
+            "targetSha256",
+            "targetFileCount",
+            "targetByteCount",
+        ]);
+        if (Object.keys(value).some((key) => !allowed.has(key)) || value.schemaVersion !== 1)
+            return undefined;
+        if (typeof value.artifactVersion !== "string" || !VERSION.test(value.artifactVersion))
+            return undefined;
+        if (value.tier !== "free" && value.tier !== "pro")
+            return undefined;
+        if (!["react", "vue", "vanilla", "assets"].includes(value.target))
+            return undefined;
+        if (typeof value.descriptorSha256 !== "string" || !SHA256.test(value.descriptorSha256))
+            return undefined;
+        if (typeof value.artifactSha256 !== "string" || !SHA256.test(value.artifactSha256))
+            return undefined;
+        if (typeof value.catalogSha256 !== "string" || !SHA256.test(value.catalogSha256))
+            return undefined;
+        if (value.targetSha256 !== undefined &&
+            (typeof value.targetSha256 !== "string" || !SHA256.test(value.targetSha256)))
+            return undefined;
+        if (value.targetFileCount !== undefined &&
+            (typeof value.targetFileCount !== "number" || !Number.isSafeInteger(value.targetFileCount)))
+            return undefined;
+        if (value.targetByteCount !== undefined &&
+            (typeof value.targetByteCount !== "number" || !Number.isSafeInteger(value.targetByteCount)))
+            return undefined;
+        if (typeof value.installedAt !== "string" ||
+            !UTC_RFC3339.test(value.installedAt) ||
+            Number.isNaN(Date.parse(value.installedAt)))
+            return undefined;
+        if (typeof value.managedFiles !== "object" ||
+            value.managedFiles === null ||
+            Array.isArray(value.managedFiles))
+            return undefined;
+        const managedFiles = value.managedFiles;
+        if (Object.keys(managedFiles).length === 0 ||
+            Object.entries(managedFiles).some(([path, hash]) => !safeManagedPath(path) || typeof hash !== "string" || !SHA256.test(hash)))
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function serializeInstallMetadata(metadata) {
+    return `${JSON.stringify(metadata, null, 2)}\n`;
+}
+export function readInstalledResourceState(projectRoot, expectedTier) {
+    const metadataPath = join(projectRoot, ".moeicons", "install-metadata.json");
+    if (!existsSync(metadataPath))
+        return {
+            kind: "missing",
+            message: "managed install metadata is missing; run repair or reinstall",
+        };
+    const metadata = parseInstallMetadata(readFileSync(metadataPath, "utf8"));
+    if (!metadata)
+        return {
+            kind: "invalid",
+            message: "managed install metadata is invalid; run repair or reinstall",
+        };
+    if (expectedTier && metadata.tier !== expectedTier)
+        return {
+            kind: "invalid",
+            message: `installed tier ${metadata.tier} does not match config tier ${expectedTier}`,
+        };
+    for (const [relative, expectedHash] of Object.entries(metadata.managedFiles)) {
+        const path = join(projectRoot, relative);
+        if (!existsSync(path))
+            return { kind: "invalid", message: `managed file is missing: ${relative}` };
+        const actual = sha256Bytes(readFileSync(path));
+        if (actual !== expectedHash)
+            return { kind: "invalid", message: `managed file was modified: ${relative}` };
+    }
+    const catalogHash = metadata.managedFiles[".moeicons/catalog.json"];
+    if (!catalogHash || catalogHash !== metadata.catalogSha256)
+        return { kind: "invalid", message: "catalog hash does not match managed metadata" };
+    return { kind: "ok", metadata };
+}