@spicetify/kit 0.1.0

package/bin/spicetify-kit.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+await main(process.argv.slice(2));

package/dist/build.js

@@ -0,0 +1,335 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * build - bundle v3 modules for the spicetify modular runtime.
+ *
+ * Bundles each module with rolldown (TS/TSX), compiles SCSS entries, and
+ * writes <out>/<name>@<version>/ with metadata.json and the
+ * spicetify-module.json sidecar. Modules ship MAP-intact: class
+ * references are remapped at apply/install time against the exact
+ * installed classmap, so one build serves every supported Spotify
+ * version.
+ */
+import { rolldown } from "rolldown";
+import * as sass from "sass-embedded";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { checkModule } from "./check.js";
+import { generateClassmapDts, loadConfig, resolveClassmap } from "./classmap.js";
+const EXTERNALS = [/^https?:\/\//];
+// Runtime URLs the react family resolves to (see the resolveId plugin).
+// react-dom/server has no client instance to share, so it stays on esm.sh;
+// nothing imports it at boot.
+const REACT_RUNTIME_URLS = {
+    react: "/modules/stdlib/src/expose/react-shim.js",
+    "react/jsx-runtime": "/modules/stdlib/src/expose/jsx-runtime.js",
+    "react-dom": "/modules/stdlib/src/expose/react-dom-shim.js",
+    "react-dom/client": "/modules/stdlib/src/expose/react-dom-shim.js",
+    "react-dom/server": "https://esm.sh/react-dom@18.3.1/server",
+};
+const USAGE = `spicetify-kit build [module...] [--classmap <key|path>] [--out <dir>]
+
+  module...        module folders to build; a folder containing
+                   metadata.json is a module, otherwise it is resolved
+                   inside --modules (default: all modules in ./modules,
+                   or the current directory when it is itself a module)
+  --classmap, -c   classmap key (e.g. 1020094; fetched from the published
+                   spicetify/classmaps repo and cached when not present
+                   locally) or a direct path to a classmap json
+  --out, -o        output dir (default: ./dist)
+  --modules, -m    modules dir (default: ./modules)
+  --no-check       skip the module-standard check (error-tier findings
+                   otherwise abort the build)
+  --watch          rebuild a single module on change (no hot-push)
+  --refresh        force a classmap refetch, bypassing vendored/cache`;
+export function readMetadata(dir) {
+    return JSON.parse(readFileSync(path.join(dir, "metadata.json"), "utf8"));
+}
+// A watch event should trigger a rebuild unless it is the generated
+// classmap.d.ts (reacting to it loops) or a dotfile.
+export function shouldRebuildOnChange(file) {
+    return !!file && !file.endsWith(".d.ts") && !file.startsWith(".");
+}
+async function buildJs(inputDir, outputDir, tree, cwd) {
+    // Multi-entry: mod.ts (when present) is the module's public barrel and
+    // gets a stable facade at the dist root so OTHER modules can import it
+    // at runtime (e.g. /modules/stdlib/mod.js).
+    const input = { index: path.join(inputDir, "index.ts") };
+    const barrel = path.join(inputDir, "mod.ts");
+    if (existsSync(barrel))
+        input.mod = barrel;
+    // Tree modules are runtime libraries: every source file becomes an
+    // entry so dependent modules can deep-import any path, not just what
+    // the module's own graph happens to reach.
+    if (tree) {
+        const SKIP_DIRS = new Set(["node_modules", "assets", "public"]);
+        const SKIP_FILES = new Set(["CODEGEN.ts"]);
+        const addTreeEntries = (dir) => {
+            for (const entry of readdirSync(dir)) {
+                const full = path.join(dir, entry);
+                if (statSync(full).isDirectory()) {
+                    if (!SKIP_DIRS.has(entry))
+                        addTreeEntries(full);
+                }
+                else if (/\.tsx?$/.test(entry) && !entry.endsWith(".d.ts") && !SKIP_FILES.has(entry)) {
+                    const name = path.relative(inputDir, full).replace(/\.tsx?$/, "");
+                    input[name] ??= full;
+                }
+            }
+        };
+        addTreeEntries(inputDir);
+    }
+    const bundle = await rolldown({
+        input,
+        external: [...EXTERNALS, /^\/modules\//],
+        transform: {
+            jsx: {
+                // Emit "react/jsx-runtime" so the plugin below externalizes it
+                // to the stdlib-local runtime.
+                importSource: "react",
+            },
+        },
+        // One React rule, enforced at resolution: npm-style react specifiers
+        // become external runtime URLs into stdlib's client-instance shims,
+        // never bundled copies. This must be a resolveId plugin, not a
+        // resolve.alias entry — externals are tested on the raw specifier, so
+        // an aliased runtime URL is followed on to the local source file and
+        // inlined into every module (which is how the jsx runtime briefly
+        // dragged stdlib's React capture into each built .tsx module).
+        plugins: [
+            {
+                name: "react-runtime-urls",
+                resolveId: (source) => REACT_RUNTIME_URLS[source] ? { id: REACT_RUNTIME_URLS[source], external: true } : null,
+            },
+        ],
+        resolve: {
+            extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".json"],
+            alias: {
+                "/modules": [path.join(cwd, "modules")],
+            },
+        },
+    });
+    await bundle.write({
+        dir: outputDir,
+        format: "esm",
+        sourcemap: true,
+        preserveModules: tree,
+        // Leaf modules ship as one chunk: local installs run entries through
+        // blob URLs, where relative chunk imports cannot resolve.
+        ...(!tree && Object.keys(input).length === 1 ? { codeSplitting: false } : {}),
+    });
+    // Staged modules serve .js; sources import "/modules/*.ts" URLs.
+    const rewriteRuntimeTs = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            const full = path.join(dir, entry);
+            if (statSync(full).isDirectory()) {
+                rewriteRuntimeTs(full);
+            }
+            else if (entry.endsWith(".js")) {
+                const content = readFileSync(full, "utf8");
+                const rewritten = content.replace(/"(\/modules\/[^"]+)\.tsx?"/g, '"$1.js"');
+                if (rewritten !== content)
+                    writeFileSync(full, rewritten);
+            }
+        }
+    };
+    rewriteRuntimeTs(outputDir);
+}
+function buildCss(inputDir, outputDir) {
+    const scss = path.join(inputDir, "index.scss");
+    const css = path.join(inputDir, "index.css");
+    if (existsSync(scss)) {
+        const result = sass.compile(scss, { style: "compressed" });
+        writeFileSync(path.join(outputDir, "index.css"), result.css);
+    }
+    else if (existsSync(css)) {
+        cpSync(css, path.join(outputDir, "index.css"));
+    }
+}
+function copyAssets(inputDir, outputDir) {
+    for (const entry of readdirSync(inputDir)) {
+        if (["assets", "public"].includes(entry)) {
+            cpSync(path.join(inputDir, entry), path.join(outputDir, entry), { recursive: true });
+        }
+    }
+}
+// buildModule builds a single module dir into outDir and returns the dist
+// path. The classmap resolution is passed in so multi-module runs and the
+// dev loop resolve it once.
+export async function buildModule(inputDir, outDir, resolved, cwd, opts = {}) {
+    const metadata = readMetadata(inputDir);
+    const identifier = `${metadata.name}@${metadata.version}`;
+    // The standard's error tier is enforced at build (KTD4): error-tier
+    // findings abort before any dist output, warnings print and continue.
+    // "warn" (the dev loop) never blocks; "off" is --no-check.
+    const check = opts.check ?? "enforce";
+    if (check !== "off") {
+        const findings = checkModule(inputDir);
+        for (const f of findings) {
+            const tag = f.severity === "error" ? "error" : "warn ";
+            console.error(`  ${tag} [${f.rule}] ${f.file ?? ""}  ${f.message}`);
+        }
+        const errors = findings.filter((f) => f.severity === "error");
+        if (check === "enforce" && errors.length) {
+            throw new Error(`${metadata.name}: ${errors.length} error-tier finding(s) against the module standard; ` +
+                "fix them, or build with --no-check.");
+        }
+    }
+    const outputDir = path.join(outDir, identifier);
+    rmSync(outputDir, { recursive: true, force: true });
+    mkdirSync(outputDir, { recursive: true });
+    console.log(`stitch ${identifier}`);
+    // Theme modules are css-only: no js entry means nothing to bundle.
+    if (metadata.entries.js)
+        await buildJs(inputDir, outputDir, metadata.tree ?? false, cwd);
+    buildCss(inputDir, outputDir);
+    copyAssets(inputDir, outputDir);
+    // The loader applies color schemes from a color.ini shipped with the
+    // module (sections become switchable schemes).
+    if (existsSync(path.join(inputDir, "color.ini"))) {
+        cpSync(path.join(inputDir, "color.ini"), path.join(outputDir, "color.ini"));
+    }
+    const classmap = JSON.parse(readFileSync(resolved.path, "utf8"));
+    writeFileSync(path.join(inputDir, "classmap.d.ts"), generateClassmapDts(classmap));
+    writeFileSync(path.join(outputDir, "metadata.json"), JSON.stringify(metadata, null, 2) + "\n");
+    writeFileSync(path.join(outputDir, "spicetify-module.json"), JSON.stringify({ installed_version: metadata.version, classmap_base: resolved.key, allow_stale: false }, null, 2) + "\n");
+    console.log(`  -> ${outputDir}`);
+    return outputDir;
+}
+function parseArgs(argv) {
+    const out = {
+        targets: [],
+        classmap: null,
+        outDir: null,
+        modulesDir: null,
+        noCheck: false,
+        refresh: false,
+        watch: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => argv[++i];
+        switch (a) {
+            case "--no-check":
+                out.noCheck = true;
+                break;
+            case "--refresh":
+                out.refresh = true;
+                break;
+            case "--watch":
+                out.watch = true;
+                break;
+            case "--classmap":
+            case "-c":
+                out.classmap = next();
+                break;
+            case "--out":
+            case "-o":
+                out.outDir = path.resolve(next());
+                break;
+            case "--modules":
+            case "-m":
+                out.modulesDir = path.resolve(next());
+                break;
+            case "--help":
+            case "-h":
+                console.log(USAGE);
+                process.exit(0);
+            default:
+                if (a.startsWith("-"))
+                    throw new Error(`unknown flag: ${a}`);
+                out.targets.push(a);
+        }
+    }
+    return out;
+}
+// Sibling content roots next to the modules dir: the org repo splits
+// content by kind (modules/, themes/, snippets/) purely for repo
+// navigation; the runtime namespace stays /modules/<id> regardless.
+export function contentRoots(modulesDir) {
+    const siblings = ["themes", "snippets"].map((name) => path.join(path.dirname(modulesDir), name));
+    return [modulesDir, ...siblings.filter((dir) => existsSync(dir))];
+}
+// resolveModuleDir accepts a module folder directly (metadata.json
+// present) or a name inside any content root.
+export function resolveModuleDir(target, modulesDir, cwd) {
+    const direct = path.resolve(cwd, target);
+    if (existsSync(path.join(direct, "metadata.json")))
+        return direct;
+    for (const root of contentRoots(modulesDir)) {
+        const nested = path.join(root, target);
+        if (existsSync(path.join(nested, "metadata.json")))
+            return nested;
+    }
+    throw new Error(`no metadata.json under ${direct} or ${contentRoots(modulesDir).join(", ")}`);
+}
+export async function runBuild(argv, cwd = process.cwd()) {
+    const args = parseArgs(argv);
+    const config = loadConfig(cwd);
+    const resolved = await resolveClassmap({ flag: args.classmap, config, cwd, refresh: args.refresh });
+    if (!resolved.path)
+        throw new Error("no classmap found (pass --classmap <key|path>)");
+    console.log(`classmap: ${resolved.path}${resolved.key ? ` (key ${resolved.key})` : ""}`);
+    const modulesDir = args.modulesDir ?? (config.modulesDir ? path.resolve(cwd, config.modulesDir) : path.join(cwd, "modules"));
+    const outDir = args.outDir ?? (config.outDir ? path.resolve(cwd, config.outDir) : path.join(cwd, "dist"));
+    let targets = args.targets;
+    if (!targets.length) {
+        if (existsSync(path.join(cwd, "metadata.json"))) {
+            targets = ["."];
+        }
+        else if (existsSync(modulesDir)) {
+            // Batch build spans every content root; targets are paths, so
+            // a same-named dir in two roots resolves unambiguously.
+            targets = contentRoots(modulesDir).flatMap((root) => readdirSync(root)
+                .filter((d) => statSync(path.join(root, d)).isDirectory())
+                .map((d) => path.join(root, d)));
+        }
+        else {
+            throw new Error(`nothing to build: no metadata.json in ${cwd} and no ${modulesDir}`);
+        }
+    }
+    // --watch rebuilds a single module on change (no hot-push), for authors who
+    // cannot use the CDP dev loop. It never blocks: a failed build logs and the
+    // watcher keeps running.
+    if (args.watch) {
+        const moduleDir = resolveModuleDir(targets[0], modulesDir, cwd);
+        const rebuild = async () => {
+            try {
+                await buildModule(moduleDir, outDir, resolved, cwd, { check: args.noCheck ? "off" : "warn" });
+            }
+            catch (e) {
+                console.error(`[build] ${e.message}`);
+            }
+        };
+        await rebuild();
+        console.log(`[build] watching ${moduleDir} (ctrl-c to stop)`);
+        let timer;
+        let loggedDts = false;
+        watch(moduleDir, { recursive: true }, (_e, file) => {
+            if (!file)
+                return;
+            // The build regenerates classmap.d.ts into the source dir; reacting
+            // to it would loop. Note the skip once so it is not a mystery.
+            if (file.endsWith(".d.ts")) {
+                if (!loggedDts) {
+                    console.log("[build] ignoring generated classmap.d.ts changes");
+                    loggedDts = true;
+                }
+                return;
+            }
+            if (file.startsWith("."))
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => void rebuild(), 200);
+        });
+        await new Promise(() => { });
+        return;
+    }
+    for (const target of targets) {
+        await buildModule(resolveModuleDir(target, modulesDir, cwd), outDir, resolved, cwd, {
+            check: args.noCheck ? "off" : "enforce",
+        });
+    }
+}

package/dist/check.js

@@ -0,0 +1,284 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * check - audit a module against the Spicetify Module Standard
+ * (docs/module-standard.md). Advisory by design: it reports findings and
+ * exits 0, so it guides without blocking. The rules split into a few
+ * reliably-checkable structural facts (metadata schema, the entry shim)
+ * and heuristic nudges (likely-hardcoded hashed classnames, a second
+ * React copy, hand-rolled shared chrome) that flag the common footguns.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { resolveModuleDir } from "./build.js";
+const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
+// The shape of a client webpack hash: a separator-free alphanumeric token,
+// 8+ chars, mixed case (real module classes are lower-kebab, e.g.
+// spicetify-button). Such a token must be a MAP.* reference the CLI
+// remaps, not a hardcoded literal that dies on the next client update.
+const isHashyClass = (token) => token.length >= 8 && /^[A-Za-z0-9]+$/.test(token) && /[a-z]/.test(token) && /[A-Z]/.test(token);
+// checkMetadata validates the metadata.json contract. Structural, so these
+// are the one place check emits errors rather than warnings.
+export function checkMetadata(meta) {
+    const out = [];
+    const err = (rule, message) => out.push({ severity: "error", rule, message, file: "metadata.json" });
+    if (typeof meta !== "object" || meta === null) {
+        err("metadata.shape", "metadata.json must be a JSON object");
+        return out;
+    }
+    const m = meta;
+    if (typeof m.name !== "string" || !/^[a-z][a-z0-9-]*$/.test(m.name)) {
+        err("metadata.name", "name must be a kebab-case string (it is the module identifier)");
+    }
+    if (typeof m.version !== "string" || !SEMVER.test(m.version)) {
+        err("metadata.version", "version must be semver (e.g. 1.0.0)");
+    }
+    if (typeof m.description !== "string")
+        err("metadata.description", "description must be a string");
+    if (!Array.isArray(m.authors))
+        err("metadata.authors", "authors must be an array");
+    if (typeof m.entries !== "object" || m.entries === null) {
+        err("metadata.entries", "entries must be an object with js and/or css");
+    }
+    if (typeof m.dependencies !== "object" || m.dependencies === null) {
+        err("metadata.dependencies", "dependencies must be an object (use {} for none)");
+    }
+    if ("hasMixins" in m && typeof m.hasMixins !== "boolean") {
+        err("metadata.hasMixins", "hasMixins must be a boolean when present");
+    }
+    return out;
+}
+function readSources(dir) {
+    const out = [];
+    const skip = new Set(["node_modules", "dist", "assets", "public"]);
+    const walk = (d) => {
+        for (const entry of readdirSync(d)) {
+            const full = path.join(d, entry);
+            if (statSync(full).isDirectory()) {
+                if (!skip.has(entry))
+                    walk(full);
+            }
+            else if (/\.tsx?$/.test(entry) && !entry.endsWith(".d.ts") && !/\.test\.[cm]?tsx?$/.test(entry)) {
+                out.push({ file: full, text: readFileSync(full, "utf8") });
+            }
+        }
+    };
+    walk(dir);
+    return out;
+}
+// checkSource runs the heuristic, per-file rules. Warnings only.
+export function checkSource(rel, text, options = {}) {
+    const out = [];
+    const lines = text.split("\n");
+    lines.forEach((line, i) => {
+        const at = `${rel}:${i + 1}`;
+        const trimmed = line.trimStart();
+        const isComment = trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*");
+        const isClientAdapter = /(^|\/)client\.ts$/.test(rel);
+        if (options.clientCapabilities !== false &&
+            !isComment &&
+            !isClientAdapter &&
+            /\b(?:globalThis\.)?Spicetify(?:\?\.|\.)/.test(line)) {
+            out.push({
+                severity: "warn",
+                rule: "client-capabilities",
+                message: "import the typed client capability surface from stdlib instead of reading the ambient Spicetify global",
+                file: at,
+            });
+        }
+        // A second React instance breaks hooks/context identity (one-React
+        // rule). expose/React.ts is stdlib's sanctioned single source and is
+        // exempt.
+        if (/from\s+['"]https?:\/\/[^'"]*react[^'"]*['"]/.test(line) &&
+            !line.includes("jsx-runtime") &&
+            !/expose\/React/.test(rel)) {
+            out.push({
+                severity: "warn",
+                rule: "one-react",
+                message: "import React from stdlib's expose or the bare 'react' shim, never a second copy",
+                file: at,
+            });
+        }
+        // className string that looks like a raw client hash.
+        if (/class[nN]ame/.test(line)) {
+            for (const q of line.matchAll(/['"]([A-Za-z0-9]+)['"]/g)) {
+                if (isHashyClass(q[1])) {
+                    out.push({
+                        severity: "warn",
+                        rule: "map-intact",
+                        message: `"${q[1]}" looks like a hardcoded client hash; reference it via MAP.* so the CLI remaps it per version`,
+                        file: at,
+                    });
+                }
+            }
+        }
+        // Hand-rolled SHARED chrome (a kit primitive exists for it) instead
+        // of the component kit. Store-specific classes are not flagged.
+        if (/\b(createElement|el)\(\s*['"](select|input|button|textarea)['"]\s*,\s*['"](spicetify-select|spicetify-searchbar|spicetify-button)\b/.test(line)) {
+            out.push({
+                severity: "warn",
+                rule: "use-the-kit",
+                message: "build shared chrome from the kit (Button/Select/TextInput/...) instead of hand-rolling it",
+                file: at,
+            });
+        }
+        // A hand-rolled context-menu row, in any form (className=, a template
+        // literal, an el() call). The kit's MenuItem owns Spotify's menu-item
+        // class via MENU_ITEM_CLASS, so modules never name it directly; the
+        // kit's own source is the one legitimate home for the literal.
+        if (/main-contextMenu-menuItemButton/.test(line) && !/primitives/.test(rel)) {
+            out.push({
+                severity: "warn",
+                rule: "use-the-kit",
+                message: "render context-menu rows with the kit's MenuItem instead of hardcoding main-contextMenu-menuItemButton",
+                file: at,
+            });
+        }
+    });
+    return out;
+}
+function checkEntryShim(dir, meta) {
+    // css-only modules (themes) declare no js entry, so there is no loader
+    // shim to require; enforcing it would fail every theme build (R4).
+    if (!meta.entries?.js)
+        return [];
+    const index = path.join(dir, "index.ts");
+    if (!existsSync(index)) {
+        return [
+            {
+                severity: "error",
+                rule: "entry-shim",
+                message: "missing index.ts entry (should defer to ./mod.js so module code loads only once deps are up)",
+                file: "index.ts",
+            },
+        ];
+    }
+    const text = readFileSync(index, "utf8");
+    if (!/import\(["']\.\/mod\.js["']\)|export\s+(async\s+)?function\s+(load|preload|mixin)/.test(text)) {
+        return [
+            {
+                severity: "warn",
+                rule: "entry-shim",
+                message: "index.ts should export load/preload/mixin (typically deferring to ./mod.js)",
+                file: "index.ts",
+            },
+        ];
+    }
+    return [];
+}
+// checkStructure runs the modularity rules the standard implies but the
+// original ports predate: importable exports, a client-free logic core, and
+// tests. Warnings only — a ratchet, not a flag day: `create` scaffolds all
+// three, so new modules start clean while ports surface their drift.
+export function checkStructure(dir, meta) {
+    // css-only themes have no logic to structure or test.
+    if (!meta.entries?.js)
+        return [];
+    const out = [];
+    const skip = new Set(["node_modules", "dist", "assets", "public"]);
+    let hasTests = false;
+    const walk = (d) => {
+        for (const entry of readdirSync(d)) {
+            const full = path.join(d, entry);
+            if (statSync(full).isDirectory()) {
+                if (!skip.has(entry))
+                    walk(full);
+            }
+            else if (entry.endsWith(".test.mts")) {
+                hasTests = true;
+            }
+        }
+    };
+    walk(dir);
+    if (!hasTests) {
+        out.push({
+            severity: "warn",
+            rule: "tests",
+            message: "no *.test.mts anywhere in the module; the standard expects testable logic in a client-free file with colocated node --test coverage",
+        });
+    }
+    const sources = readSources(dir).filter(({ file }) => path.basename(file) !== "index.ts");
+    if (!sources.length)
+        return out;
+    // Structural rules exist to break up monoliths, not to tax small DOM-glue
+    // ports: a 30-line theme toggle has no core worth extracting, and live
+    // verification covers it. Below the floor all three rules stay silent.
+    const totalLines = sources.reduce((n, { text }) => n + text.split("\n").length, 0);
+    if (totalLines < 200) {
+        return out.filter((f) => f.rule !== "tests");
+    }
+    const hasNamedExport = sources.some(({ text }) => /^export (const|let|function|class|async function) /m.test(text));
+    if (!hasNamedExport) {
+        out.push({
+            severity: "warn",
+            rule: "exportable-logic",
+            message: "nothing importable: every declaration sits behind the default export, so no unit can be imported or tested. Hoist logic to top-level named exports",
+        });
+    }
+    const clientRef = /\b(?:Spicetify|client)\.|\bMAP\./;
+    const hasPureFile = sources.some(({ text }) => !clientRef.test(text));
+    if (!hasPureFile) {
+        out.push({
+            severity: "warn",
+            rule: "pure-core",
+            message: "no client-free source file: every file references Spicetify or MAP. Move parsers/decisions into a dependency-free file (see store/catalog.ts) so they can run under node --test",
+        });
+    }
+    return out;
+}
+export function checkModule(dir) {
+    const findings = [];
+    const metaPath = path.join(dir, "metadata.json");
+    if (!existsSync(metaPath)) {
+        return [
+            {
+                severity: "error",
+                rule: "metadata.missing",
+                message: "no metadata.json — not a module",
+                file: "metadata.json",
+            },
+        ];
+    }
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(metaPath, "utf8"));
+    }
+    catch (e) {
+        return [
+            {
+                severity: "error",
+                rule: "metadata.parse",
+                message: `metadata.json is not valid JSON: ${e.message}`,
+                file: "metadata.json",
+            },
+        ];
+    }
+    findings.push(...checkMetadata(meta));
+    findings.push(...checkEntryShim(dir, meta));
+    findings.push(...checkStructure(dir, meta));
+    const enforceClientBoundary = meta.kind === "extension";
+    for (const { file, text } of readSources(dir)) {
+        findings.push(...checkSource(path.relative(dir, file), text, { clientCapabilities: enforceClientBoundary }));
+    }
+    return findings;
+}
+export async function runCheck(argv, cwd = process.cwd()) {
+    const target = argv.find((a) => !a.startsWith("--")) ?? ".";
+    const modulesDir = path.join(cwd, "modules");
+    const dir = resolveModuleDir(target, modulesDir, cwd);
+    const findings = checkModule(dir);
+    const name = path.basename(dir);
+    if (!findings.length) {
+        console.log(`✓ ${name}: golden — no standard findings`);
+        return;
+    }
+    const errors = findings.filter((f) => f.severity === "error").length;
+    const warns = findings.length - errors;
+    for (const f of findings) {
+        const tag = f.severity === "error" ? "error" : "warn ";
+        console.log(`  ${tag} [${f.rule}] ${f.file ?? ""}  ${f.message}`);
+    }
+    console.log(`\n${name}: ${errors} error(s), ${warns} warning(s) against the module standard (advisory).`);
+}