@spicetify/kit 0.1.0 → 0.3.0

package/dist/check.js

@@ -13,6 +13,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { resolveModuleDir } from "./build.js";
+import { checkExternalStdlibBoundary } from "./stdlib-boundary.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.
@@ -89,15 +90,15 @@ export function checkSource(rel, text, options = {}) {
             });
         }
         // A second React instance breaks hooks/context identity (one-React
-        // rule). expose/React.ts is stdlib's sanctioned single source and is
-        // exempt.
+        // rule). The public stdlib barrel and the build-time bare-specifier shim
+        // both resolve to the client's captured instance.
         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",
+                message: "import React from stdlib's public barrel or the bare 'react' shim, never a second copy",
                 file: at,
             });
         }
@@ -256,11 +257,14 @@ export function checkModule(dir) {
         ];
     }
     findings.push(...checkMetadata(meta));
+    findings.push(...checkExternalStdlibBoundary(dir, 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 }));
+        // The stdlib-boundary audit above owns ambient-client findings for full
+        // modules. Keep checkSource's standalone compatibility API but avoid a
+        // duplicate warning here.
+        findings.push(...checkSource(path.relative(dir, file), text, { clientCapabilities: false }));
     }
     return findings;
 }

package/dist/create.js

@@ -15,6 +15,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { KIT_DEPENDENCY_RANGE } from "./version.js";
 // The stdlib range a fresh module declares tracks the stdlib it will compile
 // against: the vendored copy in a published kit, the workspace copy in the
 // monorepo. A hardcoded literal here went stale once (^0.3.0 outlived the
@@ -77,8 +78,7 @@ export default async function (ctx: ModuleRuntimeContext) {
         return `${header}
 import { client, createRegistrar } from "/modules/stdlib/mod.ts";
 import type { ModuleRuntimeContext } from "/modules/stdlib/mod.ts";
-import { React } from "/modules/stdlib/src/expose/React.ts";
-import { NavLink } from "/modules/stdlib/src/registers/navlink.tsx";
+import { NavLink, React } from "/modules/stdlib/mod.ts";
 import { Button } from "/modules/stdlib/lib/primitives.js";
 import { nowPlaying } from "./logic.ts";
 
@@ -104,9 +104,7 @@ export default async function (ctx: ModuleRuntimeContext) {
     return `${header}
 import { client, createRegistrar } from "/modules/stdlib/mod.ts";
 import type { ModuleRuntimeContext } from "/modules/stdlib/mod.ts";
-import { React } from "/modules/stdlib/src/expose/React.ts";
-import { Platform } from "/modules/stdlib/src/expose/Platform.ts";
-import { TopbarRightButton } from "/modules/stdlib/src/registers/topbarRightButton.tsx";
+import { Platform, React } from "/modules/stdlib/mod.ts";
 import { nowPlaying } from "./logic.ts";
 
 const ROUTE = "${route}";
@@ -123,10 +121,11 @@ const Page = () => (
 export default async function (ctx: ModuleRuntimeContext) {
 	const registrar = createRegistrar(ctx);
 
-	registrar.register(
-		"topbarRightButton",
-		<TopbarRightButton label="${name}" icon={ICON} onClick={() => Platform.getHistory().push(ROUTE)} />,
-	);
+	registrar.placeButton("topbar-right", {
+		label: "${name}",
+		icon: ICON,
+		onClick: () => Platform.getHistory().push(ROUTE),
+	});
 	registrar.registerRoute(ROUTE, <Page />);
 }
 `;
@@ -270,7 +269,7 @@ notification       = 1C1C30
                 dev: "spicetify-kit dev .",
                 check: "spicetify-kit check .",
             },
-            devDependencies: { "@spicetify/kit": "^0.1.0" },
+            devDependencies: { "@spicetify/kit": KIT_DEPENDENCY_RANGE },
         }, null, "\t")}\n`);
         writeFileSync(path.join(dir, ".gitignore"), "node_modules/\ndist/\n");
     }
@@ -374,7 +373,7 @@ export async function load(ctx: ModuleRuntimeContext) {
                 test: 'node --test "test/*.test.mts"',
             },
             devDependencies: {
-                "@spicetify/kit": "^0.1.0",
+                "@spicetify/kit": KIT_DEPENDENCY_RANGE,
                 "@types/react": "^18",
                 "@types/react-dom": "^18",
                 "happy-dom": "^20",

package/dist/from-theme.js

@@ -13,6 +13,7 @@
  */
 import { cpSync, existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { KIT_DEPENDENCY_RANGE } from "./version.js";
 const USAGE = 'spicetify-kit from-theme <classic-theme-dir> [--name <id>] [--author "..."] [--bare]';
 export async function runFromTheme(argv, cwd = process.cwd()) {
     const source = argv.find((a) => !a.startsWith("--"));
@@ -76,7 +77,7 @@ export async function runFromTheme(argv, cwd = process.cwd()) {
                 dev: "spicetify-kit dev .",
             },
             devDependencies: {
-                "@spicetify/kit": "^0.1.0",
+                "@spicetify/kit": KIT_DEPENDENCY_RANGE,
             },
         }, null, "\t")}\n`);
         writeFileSync(path.join(dir, ".gitignore"), "node_modules/\ndist/\n");

package/dist/stdlib-boundary.js

@@ -0,0 +1,259 @@
+/*
+ * Copyright (C) 2026 spicetify
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+export const STDLIB_BOUNDARY_WARNING_RULES = ["ambient-client", "client-dom", "direct-map"];
+const SOURCE_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".ts", ".tsx"]);
+const STYLE_EXTENSIONS = new Set([".css", ".scss"]);
+const PUBLIC_STDLIB_IMPORT = /^\/modules\/stdlib\/(?:mod\.(?:js|ts)|lib\/primitives(?:-classes|-vanilla)?\.(?:js|ts|tsx))$/;
+const CLIENT_DOM_PATTERN = /(?:^|[^A-Za-z0-9_-])(?:Root__|main-[A-Za-z]|player-controls__|playback-progressbar|npv-)|\[data-testid(?:=|\])/;
+const posix = (value) => value.split(path.sep).join("/");
+const lineAt = (text, index) => text.slice(0, index).split("\n").length;
+// Preserve string contents and character offsets while removing comments, so
+// imports/selectors still match and diagnostics retain their original line.
+function withoutComments(text) {
+    let out = "";
+    let state = "code";
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const next = text[i + 1];
+        if (state === "line") {
+            if (char === "\n") {
+                state = "code";
+                out += char;
+            }
+            else
+                out += " ";
+            continue;
+        }
+        if (state === "block") {
+            if (char === "*" && next === "/") {
+                out += "  ";
+                i++;
+                state = "code";
+            }
+            else
+                out += char === "\n" ? "\n" : " ";
+            continue;
+        }
+        if (state === "code") {
+            if (char === "/" && next === "/") {
+                out += "  ";
+                i++;
+                state = "line";
+                continue;
+            }
+            if (char === "/" && next === "*") {
+                out += "  ";
+                i++;
+                state = "block";
+                continue;
+            }
+            if (char === "'")
+                state = "single";
+            else if (char === '"')
+                state = "double";
+            else if (char === "`")
+                state = "template";
+            out += char;
+            continue;
+        }
+        out += char;
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if ((state === "single" && char === "'") ||
+            (state === "double" && char === '"') ||
+            (state === "template" && char === "`")) {
+            state = "code";
+        }
+    }
+    return out;
+}
+function firstMatch(source, pattern) {
+    pattern.lastIndex = 0;
+    return pattern.exec(source);
+}
+export function inspectStdlibBoundaryFile(file, text) {
+    const extension = path.extname(file);
+    if (!SOURCE_EXTENSIONS.has(extension) && !STYLE_EXTENSIONS.has(extension))
+        return [];
+    const normalizedFile = posix(file);
+    const source = withoutComments(text);
+    const findings = [];
+    if (SOURCE_EXTENSIONS.has(extension)) {
+        const imports = /(?:\bfrom\s*|\bimport\s*(?:\(\s*)?)["'](\/modules\/stdlib\/[^"']+)["']/g;
+        for (const match of source.matchAll(imports)) {
+            if (PUBLIC_STDLIB_IMPORT.test(match[1]))
+                continue;
+            findings.push({
+                file: normalizedFile,
+                line: lineAt(source, match.index),
+                rule: "private-stdlib-import",
+                detail: `${match[1]} is private; import through /modules/stdlib/mod.js or the primitives kit`,
+            });
+        }
+        const ambient = firstMatch(source, /\bSpicetify\s*(?:\?\.|\.)|\b(?:globalThis|window)\s*\.\s*Spicetify\b/);
+        if (ambient) {
+            findings.push({
+                file: normalizedFile,
+                line: lineAt(source, ambient.index),
+                rule: "ambient-client",
+                detail: "imports should use stdlib's typed client capability instead of ambient Spicetify.*",
+            });
+        }
+        const directMap = firstMatch(source, /\bMAP\s*\./);
+        if (directMap) {
+            findings.push({
+                file: normalizedFile,
+                line: lineAt(source, directMap.index),
+                rule: "direct-map",
+                detail: "MAP.* is direct client coupling; prefer a semantic stdlib surface",
+            });
+        }
+    }
+    const clientDom = firstMatch(source, CLIENT_DOM_PATTERN);
+    if (clientDom) {
+        findings.push({
+            file: normalizedFile,
+            line: lineAt(source, clientDom.index),
+            rule: "client-dom",
+            detail: "Spotify-owned DOM selectors should be isolated and documented",
+        });
+    }
+    return findings;
+}
+function parseExceptions(meta) {
+    const configured = meta.stdlibBoundary;
+    if (configured === undefined)
+        return { exceptions: [], findings: [] };
+    const invalid = (message) => ({
+        severity: "error",
+        rule: "metadata.stdlib-boundary",
+        message,
+        file: "metadata.json",
+    });
+    if (typeof configured !== "object" || configured === null || Array.isArray(configured)) {
+        return { exceptions: [], findings: [invalid("stdlibBoundary must be an object")] };
+    }
+    const values = configured.exceptions;
+    if (!Array.isArray(values)) {
+        return { exceptions: [], findings: [invalid("stdlibBoundary.exceptions must be an array")] };
+    }
+    const exceptions = [];
+    const findings = [];
+    const allowedRules = new Set([
+        ...STDLIB_BOUNDARY_WARNING_RULES,
+        "missing-stdlib-dependency",
+    ]);
+    for (const [index, value] of values.entries()) {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            findings.push(invalid(`stdlibBoundary.exceptions[${index}] must be an object`));
+            continue;
+        }
+        const candidate = value;
+        const validFile = typeof candidate.file === "string" &&
+            candidate.file.length > 0 &&
+            !candidate.file.includes("\\") &&
+            !path.posix.isAbsolute(candidate.file) &&
+            path.posix.normalize(candidate.file) === candidate.file &&
+            !candidate.file.startsWith("../");
+        const validRules = Array.isArray(candidate.rules) &&
+            candidate.rules.length > 0 &&
+            candidate.rules.every((rule) => typeof rule === "string" && allowedRules.has(rule));
+        if (!validFile || !validRules || typeof candidate.reason !== "string" || !candidate.reason.trim()) {
+            findings.push(invalid(`stdlibBoundary.exceptions[${index}] needs a normalized relative file, supported rules, and a reason`));
+            continue;
+        }
+        exceptions.push(candidate);
+    }
+    return { exceptions, findings };
+}
+function boundaryFiles(root) {
+    const files = [];
+    const walk = (directory) => {
+        for (const entry of readdirSync(directory)) {
+            if (["assets", "dist", "node_modules", "public"].includes(entry))
+                continue;
+            const full = path.join(directory, entry);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else if (!/\.test\.[cm]?[jt]sx?$/.test(entry))
+                files.push(full);
+        }
+    };
+    walk(root);
+    return files;
+}
+export function checkExternalStdlibBoundary(root, metadata) {
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
+        return [];
+    const meta = metadata;
+    const parsed = parseExceptions(meta);
+    const out = [...parsed.findings];
+    const entries = meta.entries;
+    if (typeof entries?.js !== "string" || meta.name === "stdlib")
+        return out;
+    const isTheme = meta.kind === "theme" || (Array.isArray(meta.tags) && meta.tags.some((tag) => tag === "theme"));
+    const dependencies = meta.dependencies;
+    const missingDependency = !isTheme &&
+        typeof dependencies === "object" &&
+        dependencies !== null &&
+        !Array.isArray(dependencies) &&
+        typeof dependencies.stdlib !== "string";
+    const sources = boundaryFiles(root).flatMap((absolute) => {
+        const file = posix(path.relative(root, absolute));
+        return inspectStdlibBoundaryFile(file, readFileSync(absolute, "utf8"));
+    });
+    const exceptionAllows = (file, rule) => parsed.exceptions.some((item) => item.file === file && item.rules.includes(rule));
+    if (missingDependency && !exceptionAllows("metadata.json", "missing-stdlib-dependency")) {
+        out.push({
+            severity: "error",
+            rule: "stdlib-boundary.dependency",
+            message: "executable modules must declare a direct stdlib dependency",
+            file: "metadata.json",
+        });
+    }
+    for (const finding of sources) {
+        if (finding.rule === "private-stdlib-import") {
+            out.push({
+                severity: "error",
+                rule: "stdlib-boundary.private-import",
+                message: finding.detail,
+                file: `${finding.file}:${finding.line}`,
+            });
+        }
+        else if (!isTheme && !exceptionAllows(finding.file, finding.rule)) {
+            out.push({
+                severity: "warn",
+                rule: `stdlib-boundary.${finding.rule}`,
+                message: `${finding.detail}; document an exception only when the coupling is intrinsic`,
+                file: `${finding.file}:${finding.line}`,
+            });
+        }
+    }
+    for (const exception of parsed.exceptions) {
+        for (const rule of exception.rules) {
+            const present = rule === "missing-stdlib-dependency"
+                ? exception.file === "metadata.json" && missingDependency
+                : sources.some((finding) => finding.file === exception.file && finding.rule === rule);
+            if (!present) {
+                out.push({
+                    severity: "error",
+                    rule: "stdlib-boundary.stale-exception",
+                    message: `${exception.file} no longer has ${rule}; remove the exception`,
+                    file: "metadata.json",
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/version.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+// Kept in lockstep with package.json by release-please. Scaffolds must depend
+// on the kit version that generated them, especially across pre-1.0 minors.
+export const KIT_VERSION = "0.3.0"; // x-release-please-version
+export const KIT_DEPENDENCY_RANGE = `^${KIT_VERSION}`;

package/package.json

@@ -1,49 +1,53 @@
 {
-  "name": "@spicetify/kit",
-  "version": "0.1.0",
-  "description": "Developer kit for spicetify v3 modules: scaffold, build, hot-push, and pack",
-  "license": "GPL-3.0-or-later",
-  "homepage": "https://github.com/spicetify/modules#readme",
-  "bugs": {
-    "url": "https://github.com/spicetify/modules/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/spicetify/modules.git",
-    "directory": "packages/kit"
-  },
-  "type": "module",
-  "bin": {
-    "spicetify-kit": "bin/spicetify-kit.js"
-  },
-  "exports": {
-    ".": "./dist/cli.js",
-    "./create": "./dist/create.js",
-    "./build": "./dist/build.js",
-    "./dev": "./dist/dev.js",
-    "./pack": "./dist/pack.js",
-    "./from-theme": "./dist/from-theme.js",
-    "./check": "./dist/check.js",
-    "./vault": "./dist/vault.js",
-    "./install": "./dist/install.js"
-  },
-  "files": [
-    "bin",
-    "dist",
-    "vendor"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "rolldown": "^1.2.0",
-    "sass-embedded": "^1.80.0"
-  },
-  "scripts": {
-    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
-    "test": "node --test \"test/*.test.mts\""
-  }
-}
+	"name": "@spicetify/kit",
+	"version": "0.3.0",
+	"description": "Developer kit for spicetify v3 modules: scaffold, build, hot-push, and pack",
+	"license": "GPL-3.0-or-later",
+	"homepage": "https://github.com/spicetify/modules#readme",
+	"bugs": {
+		"url": "https://github.com/spicetify/modules/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spicetify/modules.git",
+		"directory": "packages/kit"
+	},
+	"type": "module",
+	"bin": {
+		"spicetify-kit": "bin/spicetify-kit.js"
+	},
+	"exports": {
+		".": "./dist/cli.js",
+		"./create": "./dist/create.js",
+		"./build": "./dist/build.js",
+		"./dev": "./dist/dev.js",
+		"./pack": "./dist/pack.js",
+		"./from-theme": "./dist/from-theme.js",
+		"./check": "./dist/check.js",
+		"./vault": "./dist/vault.js",
+		"./install": "./dist/install.js"
+	},
+	"files": [
+		"bin",
+		"dist",
+		"vendor"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"spicetify": {
+		"stdlibVersion": "1.10.1"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "node --test \"test/*.test.mts\"",
+		"prepack": "node scripts/sync-vendor.ts && tsc -p tsconfig.build.json"
+	},
+	"dependencies": {
+		"rolldown": "^1.2.0",
+		"sass-embedded": "^1.80.0"
+	}
+}