@kb-labs/devkit 2.119.0-canary.8c5512847 → 2.119.0-canary.b20fd4a5b

package/assets/claude/claude-md-snippet.test.ts

@@ -2,9 +2,8 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 
-// kb-create merges this snippet into a fresh project's CLAUDE.md during
-// install (tools/kb-create/internal/claude/claudemd.go), so a stale command
-// here reaches every new user's onboarding doc verbatim.
+// The platform onboarding surface consumes this snippet during project setup;
+// keep it independent from the launcher's V2 artifact application boundary.
 const snippetPath = fileURLToPath(new URL('./CLAUDE.md.snippet', import.meta.url))
 const snippet = readFileSync(snippetPath, 'utf8')
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kb-labs/devkit",
   "description": "Shared developer toolkit for KB Labs projects: TS/ESLint/Prettier/Vitest/Tsup presets and reusable GitHub Actions.",
-  "version": "2.119.0-canary.8c5512847",
+  "version": "2.119.0-canary.b20fd4a5b",
   "type": "module",
   "license": "MIT",
   "exports": {
@@ -39,11 +39,13 @@
     "./tsup/node.js": "./tsup/node.js",
     "./tsup/react-lib.js": "./tsup/react-lib.js",
     "./tsup/sdk.js": "./tsup/sdk.js",
+    "./tsup/css-modules-plugin.js": "./tsup/css-modules-plugin.js",
     "./tsup/node": "./tsup/node.js",
     "./tsup/react-lib": "./tsup/react-lib.js",
     "./tsup/bin": "./tsup/bin.js",
     "./tsup/sdk": "./tsup/sdk.js",
     "./tsup/dual": "./tsup/dual.js",
+    "./tsup/css-modules-plugin": "./tsup/css-modules-plugin.js",
     "./agents/": "./agents/",
     "./assets/": "./assets/",
     "./assets/claude/manifest.json": "./assets/claude/manifest.json",
@@ -114,12 +116,15 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-unused-imports": "^4.1.4",
     "glob": "^11.0.0",
+    "postcss": "^8.5.23",
+    "postcss-modules": "^9.0.1",
     "yaml": "^2.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.3.3",
     "@vitest/coverage-istanbul": "^4.1.4",
     "@vitest/coverage-v8": "^3.2.4",
+    "esbuild": "^0.28.1",
     "eslint": "^9.35.0",
     "eslint-plugin-filenames-simple": "^0.9.0",
     "eslint-plugin-sonarjs": "^4.0.3",
@@ -131,7 +136,7 @@
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.44.0",
     "vitest": "^3.2.6",
-    "@kb-labs/devkit": "2.119.0-canary.8c5512847"
+    "@kb-labs/devkit": "2.119.0-canary.b20fd4a5b"
   },
   "engines": {
     "node": ">=22.0.0",

package/tsup/css-modules-plugin.js

@@ -0,0 +1,86 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import postcss from 'postcss';
+import postcssModules from 'postcss-modules';
+
+/**
+ * esbuild plugin: real CSS Modules for tsup-built libraries.
+ *
+ * esbuild has no built-in CSS Modules support — a bare `import styles from
+ * './x.module.css'` under tsup/esbuild always resolves to `{}` (see
+ * infra/devkit/tsup/react-lib.js). This plugin processes `.module.css`
+ * files through postcss-modules so `styles.foo` resolves to a real,
+ * collision-safe class name, and the scoped CSS still gets bundled into
+ * the package's output stylesheet.
+ *
+ * Naming matches the Studio host's native Rspack CSS Modules convention
+ * (`type: 'css/auto'`, `exportsConvention: 'as-is'` in studio/app/rspack.config.mjs)
+ * as closely as a different bundler allows: keys stay as-authored (no
+ * camelCasing), values are `<local>_<hash>` so class names stay readable
+ * in devtools while still being scoped per file.
+ *
+ * Virtual resolved paths deliberately do NOT end in `.css` (they carry a
+ * `?kb-css-modules-*` suffix instead). tsup registers its own postcss
+ * onLoad handler for `/\.css$/` with no namespace restriction, and
+ * esbuild's namespace-less onLoad filters match every namespace, not just
+ * `file` — so a path that still looked like `*.module.css` after being
+ * moved into our namespace was silently intercepted by tsup's handler
+ * before this plugin ever got a chance to run.
+ */
+export function cssModulesPlugin() {
+  /** @type {Map<string, { css: string, tokens: Record<string, string> }>} */
+  const cache = new Map();
+
+  async function process(filePath) {
+    const cached = cache.get(filePath);
+    if (cached) {
+      return cached;
+    }
+    const source = await readFile(filePath, 'utf8');
+    let tokens = {};
+    const result = await postcss([
+      postcssModules({
+        getJSON(_from, json) {
+          tokens = json;
+        },
+        generateScopedName: '[local]_[hash:base64:5]',
+      }),
+    ]).process(source, { from: filePath, map: false });
+    const entry = { css: result.css, tokens };
+    cache.set(filePath, entry);
+    return entry;
+  }
+
+  return {
+    name: 'kb-css-modules',
+    setup(build) {
+      build.onResolve({ filter: /\.module\.css$/ }, (args) => ({
+        path: `${path.isAbsolute(args.path) ? args.path : path.join(args.resolveDir, args.path)}?kb-css-modules-tokens`,
+        namespace: 'kb-css-modules-tokens',
+      }));
+
+      build.onLoad({ filter: /\?kb-css-modules-tokens$/, namespace: 'kb-css-modules-tokens' }, async (args) => {
+        const realPath = args.path.replace(/\?kb-css-modules-tokens$/, '');
+        const { tokens } = await process(realPath);
+        return {
+          // Side-effect import pulls in the scoped CSS via the paired
+          // virtual-css namespace below; this module only exports tokens.
+          contents: `import ${JSON.stringify(`${realPath}?kb-css-modules-css`)};\nexport default ${JSON.stringify(tokens)};`,
+          loader: 'js',
+          resolveDir: path.dirname(realPath),
+        };
+      });
+
+      build.onResolve({ filter: /\?kb-css-modules-css$/ }, (args) => ({
+        path: args.path,
+        namespace: 'kb-css-modules-css',
+      }));
+
+      build.onLoad({ filter: /\?kb-css-modules-css$/, namespace: 'kb-css-modules-css' }, async (args) => {
+        const realPath = args.path.replace(/\?kb-css-modules-css$/, '');
+        const { css } = await process(realPath);
+        return { contents: css, loader: 'css', resolveDir: path.dirname(realPath) };
+      });
+    },
+  };
+}

package/tsup/css-modules-plugin.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import * as esbuild from 'esbuild';
+import { cssModulesPlugin } from './css-modules-plugin.js';
+
+/**
+ * Regression coverage for infra/devkit/tsup/css-modules-plugin.js.
+ *
+ * Every scenario here is a real failure this plugin went through before it
+ * worked (see docs/adr/0040-real-css-modules-for-tsup-built-libraries.md):
+ * esbuild not touching `.module.css` at all (empty token map), and — the
+ * subtle one — tsup's own bundled postcss onLoad handler racing this
+ * plugin's onLoad and winning because esbuild's namespace-less filters
+ * match every namespace, not just `file`.
+ */
+
+const dirs: string[] = [];
+
+function makeFixtureDir(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'kb-css-modules-test-'));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (dirs.length) {
+    rmSync(dirs.pop()!, { recursive: true, force: true });
+  }
+});
+
+/** Mimics tsup's bundled postcss plugin: an onLoad for /\.css$/ with no namespace filter. */
+const competingNamespaceLessCssLoader: esbuild.Plugin = {
+  name: 'competing-css-loader',
+  setup(build) {
+    build.onLoad({ filter: /\.css$/ }, async (args) => {
+      const { readFile } = await import('node:fs/promises');
+      return { contents: await readFile(args.path, 'utf8'), loader: 'css' };
+    });
+  },
+};
+
+async function bundle(dir: string, extraPlugins: esbuild.Plugin[] = []) {
+  const result = await esbuild.build({
+    entryPoints: [path.join(dir, 'entry.js')],
+    bundle: true,
+    write: false,
+    outdir: path.join(dir, 'out'),
+    format: 'esm',
+    plugins: [...extraPlugins, cssModulesPlugin()],
+  });
+  const js = result.outputFiles.find((f) => f.path.endsWith('.js'))!.text;
+  const css = result.outputFiles.find((f) => f.path.endsWith('.css'))?.text ?? '';
+  return { js, css };
+}
+
+describe('cssModulesPlugin', () => {
+  it('resolves styles.<class> to a real, non-empty scoped class name', async () => {
+    const dir = makeFixtureDir();
+    writeFileSync(path.join(dir, 'entry.js'), `
+      import styles from './x.module.css';
+      export const cls = styles.foo;
+    `);
+    writeFileSync(path.join(dir, 'x.module.css'), `.foo { color: red; }`);
+
+    const { js, css } = await bundle(dir);
+
+    // The pre-fix behavior: esbuild has no CSS Modules support, so a bare
+    // `.module.css` default import resolves to `{}` and every className is
+    // silently undefined at runtime.
+    expect(js).not.toContain('= {};');
+    expect(js).toMatch(/var \w+_default = \{\s*"foo":\s*"foo_[\w-]+"\s*\};/);
+
+    const match = js.match(/"foo":\s*"(foo_[\w-]+)"/);
+    expect(match).not.toBeNull();
+    const scopedName = match![1];
+
+    expect(css).toContain(`.${scopedName} {`);
+    expect(css).not.toContain('.foo {'); // original literal selector must not survive unscoped
+  });
+
+  it('keeps :global(...) selectors as real, unscoped Ant Design class names', async () => {
+    const dir = makeFixtureDir();
+    writeFileSync(path.join(dir, 'entry.js'), `
+      import styles from './btn.module.css';
+      export const cls = styles.uiButton;
+    `);
+    writeFileSync(
+      path.join(dir, 'btn.module.css'),
+      `.uiButton:global(.ant-btn-primary) { color: blue; }`,
+    );
+
+    const { css } = await bundle(dir);
+
+    // The real (unscoped) Ant Design class must appear verbatim so it still
+    // matches Ant Design's actual rendered DOM class.
+    expect(css).toContain('.ant-btn-primary');
+    // ...while the local part of the same compound selector is still scoped.
+    expect(css).not.toMatch(/\.uiButton(?!_\w)/);
+  });
+
+  it('rewrites @keyframes and their animation-name reference to the same scoped name', async () => {
+    const dir = makeFixtureDir();
+    writeFileSync(path.join(dir, 'entry.js'), `import './anim.module.css';`);
+    writeFileSync(
+      path.join(dir, 'anim.module.css'),
+      `
+      .spin { animation: spin 1s linear infinite; }
+      @keyframes spin { from { transform: rotate(0); } to { transform: rotate(360deg); } }
+      `,
+    );
+
+    const { css } = await bundle(dir);
+
+    const keyframesMatch = css.match(/@keyframes (spin_[\w-]+)/);
+    expect(keyframesMatch).not.toBeNull();
+    const scopedKeyframesName = keyframesMatch![1];
+
+    expect(css).toContain(`animation: ${scopedKeyframesName} 1s linear infinite;`);
+  });
+
+  it('still resolves real tokens when a namespace-less onLoad(/\\.css$/) plugin runs first', async () => {
+    // Regression test for the actual bug hit while building this plugin:
+    // tsup registers a `.css` onLoad with no namespace restriction, ahead of
+    // any user esbuildPlugins. esbuild's namespace-less onLoad filters match
+    // every namespace — not just `file` — so an earlier version of this
+    // plugin that resolved `.module.css` into a custom namespace, but kept a
+    // path that still *looked* like `*.module.css`, was silently intercepted
+    // by that competing handler before ever reaching postcss-modules.
+    const dir = makeFixtureDir();
+    writeFileSync(path.join(dir, 'entry.js'), `
+      import styles from './race.module.css';
+      export const cls = styles.foo;
+    `);
+    writeFileSync(path.join(dir, 'race.module.css'), `.foo { color: green; }`);
+
+    const { js } = await bundle(dir, [competingNamespaceLessCssLoader]);
+
+    expect(js).not.toContain('= {};');
+    expect(js).toMatch(/"foo":\s*"foo_[\w-]+"/);
+  });
+
+  it('produces stable, deterministic scoped names across repeated builds of the same file', async () => {
+    const dir = makeFixtureDir();
+    writeFileSync(path.join(dir, 'entry.js'), `
+      import styles from './stable.module.css';
+      export const cls = styles.foo;
+    `);
+    writeFileSync(path.join(dir, 'stable.module.css'), `.foo { color: red; }`);
+
+    const first = await bundle(dir);
+    const second = await bundle(dir);
+
+    const extract = (js: string) => js.match(/"foo":\s*"(foo_[\w-]+)"/)?.[1];
+    expect(extract(first.js)).toBe(extract(second.js));
+  });
+});

package/tsup/react-lib.js

@@ -1,4 +1,5 @@
 import { defineConfig } from 'tsup'
+import { cssModulesPlugin } from './css-modules-plugin.js'
 
 export default defineConfig({
   entry: ['src/index.ts'],
@@ -14,6 +15,10 @@ export default defineConfig({
   splitting: false,
   skipNodeModulesBundle: true,
   shims: false,
+  // esbuild has no built-in CSS Modules support (`import styles from './x.module.css'`
+  // otherwise resolves to `{}`) — see css-modules-plugin.js for why and how this
+  // matches the Studio host's Rspack CSS Modules convention.
+  esbuildPlugins: [cssModulesPlugin()],
   ignoreWatch: [
     '**/node_modules/**',
     '**/dist/**',