auklet 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,207 @@
+# auklet
+
+Build utilities for TypeScript packages and module CSS output.
+
+## Features
+
+- Build JavaScript/TypeScript package output with the bundled tsdown config.
+- Generate package-level and module-level CSS entries.
+- Infer component style dependencies from source imports.
+- Generate theme and external style entry files.
+- Provide a Vite dev plugin for virtual package CSS entries.
+- Watch source/config changes and rebuild module CSS output.
+
+## Requirements
+
+- Node.js `>=22`
+- pnpm `10.27.0`
+
+## CLI
+
+The package exposes both `auk` and `auklet` commands.
+
+```bash
+pnpm auk --help
+pnpm auk build
+pnpm auk build-js
+pnpm auk build-css
+pnpm auk build-css --watch
+pnpm auk dev
+```
+
+Commands:
+
+- `build` removes `dist`, builds JavaScript output, then builds CSS output.
+- `build-js` runs tsdown with the default auklet tsdown config unless a config flag is passed.
+- `build-css` generates module CSS output.
+- `build-css --watch` watches source/config files and rebuilds CSS.
+- `dev` runs JavaScript and CSS watch tasks together.
+
+## Configuration
+
+Create `auklet.config.ts` in the package root:
+
+```ts
+import type { AukletConfig } from 'auklet';
+
+export const config: AukletConfig = {
+  sourceDir: 'src',
+  outputDir: 'dist',
+  themes: {
+    light: './src/themes/light.css',
+    dark: './src/themes/dark.css',
+  },
+  cssDependencies: {
+    '@scope/ui': {
+      global: '/style.css',
+      component: ['/components/**.css'],
+    },
+    '@scope/theme': {
+      global: '/style.css',
+      themes: {
+        light: '/themes/light.css',
+        dark: '/themes/dark.css',
+      },
+    },
+  },
+  build: {
+    formats: ['esm', 'cjs'],
+    modules: true,
+    tsconfig: 'tsconfig.json',
+  },
+};
+```
+
+### CSS Options
+
+- `sourceDir`: source directory relative to the package root. Defaults to `src`.
+- `outputDir`: build output directory relative to the package root. Defaults to `dist`.
+- `themes`: package theme style entries.
+- `cssDependencies`: external package style dependencies.
+
+Each `cssDependencies` entry may define:
+
+- `global`: package-level style dependency.
+- `themes`: theme style dependency map.
+- `component`: glob-like component style rules used to infer style imports from source imports.
+
+### Build Options
+
+- `formats`: package bundle formats: `esm`, `cjs`, or `iife`.
+- `banner`: custom bundle banner.
+- `externals`: additional external packages.
+- `modules`: whether to generate unbundled `dist/es` and `dist/lib` output.
+- `tsconfig`: TypeScript config path relative to the package root.
+
+## CSS Output
+
+`build-css` generates package and module style entries under the output directory.
+
+Typical output includes:
+
+```text
+dist/
+  index.css
+  es/
+    style/
+      index.css
+      module.css
+      external.css
+      themes/
+        light.css
+        dark.css
+    components/
+      Button/
+        index.css
+        style/index.css
+  lib/
+    ...
+```
+
+Important entry semantics:
+
+- `index.css`: package-level aggregate CSS.
+- `style/index.css`: package style entry for a specific output format.
+- `style/module.css`: current package module styles.
+- `style/external.css`: external style entries.
+- `components/*/style/index.css`: component-level style entry.
+- `themes/*.css`: theme style entry.
+
+## Vite Plugin
+
+Use `aukletCssPlugin` in Vite dev mode to load virtual package CSS entries.
+
+```ts
+import { aukletCssPlugin } from 'auklet';
+
+export default {
+  plugins: [aukletCssPlugin()],
+};
+```
+
+The plugin resolves package CSS ids such as:
+
+```ts
+import '@scope/app/style.css';
+import '@scope/app/components/Button.css';
+import '@scope/app/themes/light.css';
+```
+
+## Programmatic API
+
+```ts
+import {
+  ModuleCssBuilder,
+  ModuleCssWatcher,
+  aukletCssPlugin,
+  loadAukletConfig,
+  runTsdown,
+} from 'auklet';
+
+const aukletConfig = await loadAukletConfig(process.cwd());
+
+await new ModuleCssBuilder({
+  packageRoot: process.cwd(),
+  aukletConfig,
+}).build();
+```
+
+Public exports include:
+
+- `ModuleCssBuilder`
+- `ModuleCssWatcher`
+- `aukletCssPlugin`
+- `loadAukletConfig`
+- `resolveAukletConfigModule`
+- `createTsdownArgs`
+- `runTsdown`
+- related TypeScript types
+
+## Development
+
+```bash
+pnpm i
+pnpm run test
+pnpm run typecheck
+pnpm run build
+pnpm run format
+```
+
+Notes:
+
+- `pnpm run build` rewrites `dist`.
+- `pnpm run format` formats `bin`, `src`, and `dist`.
+- `TESTING.md` defines the testing architecture and style rules for future changes.
+
+## Testing
+
+Tests are organized into:
+
+- `src/__tests__/e2e`: project-level output structure and dependency-chain tests.
+- `src/__tests__/css`: module/API tests for CSS and style logic.
+- `src/__tests__/fixtures`: shared virtual project and style structure helpers.
+- `src/__tests__/build`: tsdown/build config tests.
+
+Temporary test projects are created under `src/__tests__/.tmp/` and ignored by git.
+
+Read `TESTING.md` before adding or changing tests.

package/bin/entry.cjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+const minimist = require('minimist');
+
+const runBuildCss = async (args) => {
+  const shouldWatch = args.includes('--watch') || args.includes('-w');
+  const { loadAukletConfig } = await import('../dist/configLoader.js');
+  const aukletConfig = await loadAukletConfig(process.cwd(), {
+    cacheBust: shouldWatch,
+  });
+
+  if (shouldWatch) {
+    const { ModuleCssWatcher } = await import(
+      '../dist/css/watch/moduleCssWatcher.js'
+    );
+    const watcher = new ModuleCssWatcher({ aukletConfig, logger: console });
+    await watcher.watch();
+    const close = () => {
+      watcher
+        .close()
+        .catch(console.error)
+        .finally(() => process.exit(0));
+    };
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+    await new Promise(() => {});
+    return 0;
+  }
+
+  const { ModuleCssBuilder } = await import(
+    '../dist/css/production/moduleCssBuilder.js'
+  );
+  const builder = new ModuleCssBuilder({ aukletConfig, logger: console });
+  await builder.build();
+  return 0;
+};
+
+const runBuildJs = async (args) => {
+  const { runTsdown } = await import('../dist/build/runTsdown.js');
+  return runTsdown(args, { cwd: process.cwd() });
+};
+
+const runBuild = async (args) => {
+  fs.rmSync(path.join(process.cwd(), 'dist'), {
+    recursive: true,
+    force: true,
+  });
+
+  const jsExitCode = await runBuildJs(args);
+  if (jsExitCode) return jsExitCode;
+
+  return runBuildCss([]);
+};
+
+const runDev = async () => {
+  const { execa } = await import('execa');
+  const { createTsdownArgs } = await import('../dist/build/runTsdown.js');
+  const entries = [
+    createTsdownArgs(['--watch']),
+    [path.resolve(__dirname, './entry.cjs'), 'build-css', '--watch'],
+  ];
+  const processes = entries.map((args) =>
+    execa(process.execPath, args, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      reject: false,
+    }),
+  );
+
+  const close = () => {
+    for (const item of processes) {
+      item.kill('SIGTERM');
+    }
+  };
+
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+
+  for (const item of processes) {
+    item.then((result) => {
+      if (result.exitCode) close();
+    });
+  }
+
+  const results = await Promise.all(processes);
+  const failed = results.find((result) => result.exitCode);
+  return failed?.exitCode ?? 0;
+};
+
+const argv = minimist(process.argv.slice(2), {
+  boolean: ['help'],
+  alias: {
+    h: 'help',
+  },
+});
+const [command, ...args] = argv._;
+const commandIndex = process.argv.indexOf(command);
+const commandArgs =
+  commandIndex >= 0 ? process.argv.slice(commandIndex + 1) : args;
+
+if (argv.help || !command) {
+  console.log('Usage: auk <command>');
+  console.log('');
+  console.log('Commands:');
+  console.log('  build     Build package JavaScript and CSS output');
+  console.log('  build-js  Build package JavaScript output with tsdown');
+  console.log('  build-css  Build package module CSS output, supports --watch');
+  console.log('  dev       Watch package JavaScript and CSS output');
+  process.exit(argv.help ? 0 : 1);
+}
+
+const runners = {
+  build: runBuild,
+  'build-js': runBuildJs,
+  'build-css': runBuildCss,
+  dev: runDev,
+};
+
+const runner = runners[command];
+
+if (runner) {
+  runner(commandArgs)
+    .then((exitCode) => {
+      process.exit(exitCode ?? 0);
+    })
+    .catch((error) => {
+      console.error(error);
+      process.exit(1);
+    });
+  return;
+}
+
+console.error(`Unknown auk command: ${command}`);
+process.exit(1);

package/dist/build/runTsdown.d.ts

@@ -0,0 +1,8 @@
+export type RunTsdownOptions = {
+  cwd?: string;
+};
+export declare function createTsdownArgs(args: Array<string>): string[];
+export declare function runTsdown(
+  args: Array<string>,
+  options?: RunTsdownOptions,
+): Promise<number>;

package/dist/build/runTsdown.js

@@ -0,0 +1,36 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { execa } from 'execa';
+const require = createRequire(import.meta.url);
+const tsdownRunFile = require.resolve('tsdown/run');
+const currentExtension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+const defaultConfigFile = fileURLToPath(
+  new URL(`./tsdownConfig.${currentExtension}`, import.meta.url),
+);
+const hasConfigArg = (args) => {
+  return args.some(
+    (arg, index) =>
+      arg === '--no-config' ||
+      arg === '-c' ||
+      arg === '--config' ||
+      arg.startsWith('--config=') ||
+      args[index - 1] === '-c' ||
+      args[index - 1] === '--config',
+  );
+};
+export function createTsdownArgs(args) {
+  const tsdownArgs = hasConfigArg(args)
+    ? args
+    : ['--config', defaultConfigFile, ...args];
+  return [tsdownRunFile, ...tsdownArgs];
+}
+export async function runTsdown(args, options = {}) {
+  var _a, _b;
+  const tsdownArgs = createTsdownArgs(args);
+  const result = await execa(process.execPath, tsdownArgs, {
+    cwd: (_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd(),
+    stdio: 'inherit',
+    reject: false,
+  });
+  return (_b = result.exitCode) !== null && _b !== void 0 ? _b : 0;
+}

package/dist/build/tsdownConfig.d.ts

@@ -0,0 +1,12 @@
+import { type UserConfig } from 'tsdown/config';
+import type { AukletConfig, PackageBuildFormat } from '#auklet/types';
+export type TsdownFormat = PackageBuildFormat;
+export declare function defineKernelPackageConfigFromOptions(
+  packageRoot?: string,
+  config?: AukletConfig,
+): Array<UserConfig>;
+export declare function defineKernelPackageConfigFromFile(
+  packageRoot?: string,
+): Promise<Array<UserConfig>>;
+declare const _default: Promise<UserConfig[]>;
+export default _default;

package/dist/build/tsdownConfig.js

@@ -0,0 +1,223 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { defineConfig } from 'tsdown/config';
+import { loadAukletConfig } from '#auklet/configLoader';
+const formatMap = {
+  cjs: '.cjs',
+  iife: '.global.js',
+  esm: ['.js', '.mjs'],
+};
+const getExternal = (names) => {
+  const external = new Set();
+  for (const name of names) {
+    external.add(name);
+    external.add(`${name}/*`);
+  }
+  return [...external];
+};
+const getPackageExternal = (pkg, options) => {
+  var _a, _b, _c;
+  return getExternal([
+    ...Object.keys((_a = pkg.dependencies) !== null && _a !== void 0 ? _a : {}),
+    ...Object.keys(
+      (_b = pkg.peerDependencies) !== null && _b !== void 0 ? _b : {},
+    ),
+    ...((_c = options.externals) !== null && _c !== void 0 ? _c : []),
+  ]);
+};
+const getPeerExternal = (pkg, options) => {
+  var _a, _b;
+  return [
+    ...new Set([
+      ...Object.keys(
+        (_a = pkg.peerDependencies) !== null && _a !== void 0 ? _a : {},
+      ),
+      ...((_b = options.externals) !== null && _b !== void 0 ? _b : []),
+    ]),
+  ];
+};
+const getDependencyGlobalName = (name) => {
+  return name
+    .replace(/^@/, '')
+    .split(/[/-]/g)
+    .filter(Boolean)
+    .map((label) => label[0].toUpperCase() + label.slice(1))
+    .join('');
+};
+const getIifeGlobals = (context) => {
+  return Object.fromEntries(
+    context.peerExternal.map((name) => [name, getDependencyGlobalName(name)]),
+  );
+};
+const getIifeAlwaysBundle = (context) => {
+  const names = new Set(context.dependencyNames);
+  if (context.peerExternal.includes('react')) {
+    names.add('react/jsx-runtime');
+    names.add('react/jsx-dev-runtime');
+  }
+  return [...names];
+};
+const getGlobalName = (pkg) => {
+  var _a;
+  return (
+    (_a = pkg === null || pkg === void 0 ? void 0 : pkg.name) !== null &&
+    _a !== void 0
+      ? _a
+      : ''
+  )
+    .replace(/@/g, '')
+    .split(/[/-]/g)
+    .map((label) => label[0].toUpperCase() + label.slice(1))
+    .join('');
+};
+const findWorkspaceTsconfig = (packageRoot) => {
+  let current = packageRoot;
+  while (true) {
+    const tsconfig = path.join(current, 'tsconfig.json');
+    if (fs.existsSync(tsconfig)) return tsconfig;
+    const parent = path.dirname(current);
+    if (parent === current) return path.join(packageRoot, 'tsconfig.json');
+    current = parent;
+  }
+};
+const createBuildContext = (packageRoot, options) => {
+  var _a, _b;
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+  );
+  const banner =
+    (_a = options.banner) !== null && _a !== void 0
+      ? _a
+      : '/*!\n' +
+        ` * ${pkg.name}.js v${pkg.version}\n` +
+        (pkg.author
+          ? ` * (c) 2026-${new Date().getFullYear()} ${pkg.author}\n`
+          : '') +
+        ' */';
+  return {
+    packageRoot,
+    tsconfig: options.tsconfig
+      ? path.resolve(packageRoot, options.tsconfig)
+      : findWorkspaceTsconfig(packageRoot),
+    pkg,
+    dependencyNames: Object.keys(
+      (_b = pkg.dependencies) !== null && _b !== void 0 ? _b : {},
+    ),
+    packageExternal: getPackageExternal(pkg, options),
+    peerExternal: getPeerExternal(pkg, options),
+    globalName: getGlobalName(pkg),
+    banner,
+  };
+};
+const createCommonConfig = (context, deps) => {
+  return {
+    cwd: context.packageRoot,
+    clean: false,
+    sourcemap: false,
+    tsconfig: context.tsconfig,
+    target: 'es2018',
+    platform: 'browser',
+    deps,
+    define: {
+      __TEST__: 'false',
+      __VERSION__: JSON.stringify(context.pkg.version),
+      __DEV__:
+        '(typeof process !== "undefined" ? (process.env?.NODE_ENV !== "production") : false)',
+    },
+  };
+};
+const createBundleConfigs = (context, formats) => {
+  const outputConfigs = [];
+  for (const format of formats) {
+    const extnames = formatMap[format];
+    for (const extname of Array.isArray(extnames) ? extnames : [extnames]) {
+      outputConfigs.push({ format, extname });
+    }
+  }
+  return outputConfigs.map(({ format, extname }) => {
+    const deps =
+      format === 'iife'
+        ? {
+            neverBundle: context.peerExternal,
+            alwaysBundle: getIifeAlwaysBundle(context),
+            onlyBundle: false,
+          }
+        : {
+            neverBundle: context.packageExternal,
+          };
+    return {
+      ...createCommonConfig(context, deps),
+      entry: ['src/index.ts'],
+      format,
+      globalName: context.globalName,
+      outDir: 'dist',
+      dts: false,
+      treeshake: true,
+      banner: context.banner,
+      outExtensions: () => ({
+        js: extname,
+      }),
+      outputOptions: {
+        entryFileNames: `[name]${extname}`,
+        chunkFileNames: `[name]-[hash]${extname}`,
+        globals: format === 'iife' ? getIifeGlobals(context) : {},
+      },
+    };
+  });
+};
+const createModuleConfig = (commonConfig, format, outDir) => {
+  return {
+    ...commonConfig,
+    entry: [
+      'src/**/*.ts',
+      'src/**/*.tsx',
+      '!src/**/*.d.ts',
+      '!src/**/__tests__/**',
+      '!src/**/*.spec.ts',
+      '!src/**/*.spec.tsx',
+    ],
+    format,
+    outDir,
+    dts: true,
+    unbundle: true,
+    outExtensions: () => ({
+      js: '.js',
+      dts: '.d.ts',
+    }),
+  };
+};
+const createModuleConfigs = (context) => {
+  const commonConfig = createCommonConfig(context, {
+    neverBundle: context.packageExternal,
+  });
+  return [
+    createModuleConfig(commonConfig, 'esm', 'dist/es'),
+    createModuleConfig(commonConfig, 'cjs', 'dist/lib'),
+  ];
+};
+export function defineKernelPackageConfigFromOptions(
+  packageRoot = process.cwd(),
+  config = {},
+) {
+  var _a, _b;
+  const buildOptions = (_a = config.build) !== null && _a !== void 0 ? _a : {};
+  const formats =
+    (_b = buildOptions.formats) !== null && _b !== void 0
+      ? _b
+      : ['cjs', 'esm', 'iife'];
+  const context = createBuildContext(packageRoot, buildOptions);
+  const bundleConfigs = createBundleConfigs(context, formats);
+  const moduleConfigs = buildOptions.modules
+    ? createModuleConfigs(context)
+    : [];
+  return [...bundleConfigs, ...moduleConfigs];
+}
+export async function defineKernelPackageConfigFromFile(
+  packageRoot = process.cwd(),
+) {
+  const config = await loadAukletConfig(packageRoot, { cacheBust: true });
+  return defineKernelPackageConfigFromOptions(packageRoot, config);
+}
+export default defineKernelPackageConfigFromFile(process.cwd()).then((config) =>
+  defineConfig(config),
+);

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { CssDependencyGroup } from '#auklet/types';
+export declare const aukletConfigFile = 'auklet.config.ts';
+export declare const aukletDefaultCssDependencyConfig: CssDependencyGroup;

package/dist/config.js

@@ -0,0 +1,9 @@
+export const aukletConfigFile = 'auklet.config.ts';
+export const aukletDefaultCssDependencyConfig = {
+  global: '/style.css',
+  component: ['/pages/**.css', '/components/**.css'],
+  themes: {
+    dark: '/themes/dark.css',
+    light: '/themes/light.css',
+  },
+};

package/dist/configLoader.d.ts

@@ -0,0 +1,8 @@
+import type { AukletConfig, LoadAukletConfigOptions } from '#auklet/types';
+export declare function resolveAukletConfigModule(
+  module: Record<string, unknown>,
+): AukletConfig;
+export declare function loadAukletConfig(
+  packageRoot: string,
+  options?: LoadAukletConfigOptions,
+): Promise<AukletConfig>;