auklet 0.0.19 → 0.0.20

package/README.md

@@ -5,103 +5,133 @@
 
 </div>
 
-<h1></h1>
+auklet is a build tool for TypeScript packages. It wraps `tsdown` for
+JavaScript output, generates CSS style entries for package/module/theme output,
+provides module CSS auto imports, and includes a Vite dev plugin for virtual
+package CSS.
 
-auklet is a build tool for TypeScript packages. It generates JavaScript and
-TypeScript output through `tsdown`, and also provides CSS style entry builds,
-module style auto imports, and a Vite dev plugin for virtual package CSS.
+It is designed for:
 
-## Features
+- single-package TypeScript libraries;
+- single-package component libraries;
+- pnpm monorepo TypeScript libraries;
+- pnpm monorepo component packages.
 
-- Generate TypeScript package bundles, IIFE output, and unbundled module output.
-- Generate package-level, module-level, theme, and external CSS entries.
-- Infer module CSS dependencies from `.tsx` imports and re-exports.
-- Turn package CSS imports into virtual CSS modules in Vite dev mode.
-- Support single-package component libraries, single-package libraries,
-  monorepo component packages, and monorepo libraries.
-- Watch source/config/style changes and rebuild CSS output.
-
-## Requirements
+Requirements:
 
 - Node.js `>=22`
-
-## Project Shapes
-
-auklet supports four project shapes:
-
-- single-package component library;
-- single-package TypeScript library;
-- monorepo component packages;
-- monorepo TypeScript libraries.
-
-Production build commands always run from the **current package root**, whether
-that package lives in a monorepo or not:
-
-```bash
-auk build
-auk build-js
-auk build-css
-```
-
-Vite dev mode is provided by `aukletStylePlugin`, which exposes virtual CSS
-entries. The plugin defaults to single-package mode. If a workspace demo/app
-needs to work with multiple packages at the same time, enable monorepo mode
-explicitly.
+- pnpm for publish and owner workflows
 
 ## Quick Start
 
-### Single-Package Component Library
+`auklet.config.ts` is optional. Without it, auklet uses `src` as source,
+`dist` as output, no module output, and default JavaScript formats.
 
-Add `auklet.config.ts` in the package root:
+For a component package, a minimal config usually looks like this:
 
 ```ts
 import type { AukletConfig } from 'auklet';
 
 export const config: AukletConfig = {
-  source: 'src',
-  output: 'dist',
   modules: true,
 };
 ```
 
-Then import CSS entries from the current package:
+Build JavaScript and CSS output:
+
+```bash
+auk build
+```
+
+Import generated CSS entries from the package:
 
 ```ts
 import '@scope/ui/style.css';
 import '@scope/ui/components/Button.css';
 ```
 
-See the "Vite Plugin" section for dev plugin setup.
+Use the Vite plugin during local development:
+
+```ts
+import { aukletStylePlugin } from 'auklet';
+
+export default {
+  plugins: [aukletStylePlugin()],
+};
+```
 
 ## CLI
 
-The package exposes both `auk` and `auklet` commands:
+The package exposes both `auk` and `auklet`.
+
+| Command                 | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| `auk dev`               | Watch JavaScript and CSS output together.                             |
+| `auk build`             | Remove configured output, then build JavaScript and CSS.              |
+| `auk build-js`          | Run tsdown with auklet's built-in config unless `--config` is passed. |
+| `auk build-js --watch`  | Pass watch mode through to tsdown.                                    |
+| `auk build-css`         | Generate CSS output only.                                             |
+| `auk build-css --watch` | Watch source/config/style files and rebuild CSS.                      |
+| `auk publish`           | Run the pnpm-based publish workflow.                                  |
+| `auk owner add <user>`  | Add npm owners through pnpm.                                          |
+
+Build and dev commands can override package config for one run:
 
 ```bash
-pnpm auk --help
-pnpm auk dev
-pnpm auk build
-pnpm auk build-js
-pnpm auk build-js --watch
-pnpm auk build-css
-pnpm auk build-css --watch
+auk build --source source --output build --modules
+auk build --build.formats esm,cjs
+auk build --build.target es2022
+auk build --build.platform node
+auk build --build.tsconfig tsconfig.build.json
 ```
 
-Commands:
+Supported build override flags:
+
+| Flag                          | Description                                  |
+| ----------------------------- | -------------------------------------------- |
+| `--source <dir>`              | Source directory.                            |
+| `--output <dir>`              | Output directory.                            |
+| `--modules`                   | Enable unbundled module output.              |
+| `--no-modules`                | Disable unbundled module output.             |
+| `--build.formats <formats>`   | Comma-separated `cjs`, `esm`, and/or `iife`. |
+| `--build.target <target>`     | JavaScript target passed to tsdown.          |
+| `--build.platform <platform>` | `node`, `neutral`, or `browser`.             |
+| `--build.tsconfig <file>`     | TypeScript config file.                      |
+
+Config precedence:
+
+```text
+CLI flags > auklet.config.ts > auklet defaults
+```
+
+`build-js` passes unknown flags through to tsdown. Auklet build override flags
+cannot be combined with tsdown custom config flags:
+
+```bash
+# not allowed
+auk build-js --source source --config tsdown.config.ts
+auk build-js --output build -c tsdown.config.ts
+auk build-js --modules --no-config
+```
+
+When `--config`, `-c`, or `--no-config` is used, tsdown owns the full build
+config. Use `auklet.config.ts` or tsdown config code directly instead of auklet
+CLI overrides.
+
+Publish controls stay on CLI flags:
 
-- `dev`: starts JavaScript watch and CSS watch together.
-- `build`: removes the configured `output` directory, then builds JavaScript and
-  CSS output.
-- `build-js`: runs tsdown. If no `--config` is passed, auklet uses its built-in
-  tsdown config.
-- `build-js --watch`: passes `--watch` through to tsdown and watches JS/TS
-  builds.
-- `build-css`: generates CSS output.
-- `build-css --watch`: watches source/config/style files and rebuilds CSS.
+```bash
+auk publish --filter @scope/ui
+auk publish --version patch --dry-run
+auk publish --no-format
+```
+
+`--no-format` disables auklet's publish output formatter for that run. It is not
+configured in `package.json`.
 
-## Configuration Example
+## Configuration
 
-Create `auklet.config.ts` in the package root:
+`auklet.config.ts` is loaded from the current package root:
 
 ```ts
 import type { AukletConfig } from 'auklet';
@@ -128,239 +158,30 @@ export const config: AukletConfig = {
 };
 ```
 
-## Configuration Reference
-
-The full `auklet.config.ts` shape is:
-
-```ts
-import type { UserConfig } from 'tsdown/config';
-
-export interface AukletConfig {
-  /**
-   * Source directory, relative to the current package root.
-   *
-   * @default 'src'
-   */
-  source?: string;
-
-  /**
-   * Build output directory, relative to the current package root.
-   *
-   * `auk build` removes this directory before generating JavaScript and CSS
-   * output again.
-   *
-   * @default 'dist'
-   */
-  output?: string;
-
-  /**
-   * Whether to generate unbundled module output.
-   *
-   * When enabled, auklet generates module output such as `dist/es` and
-   * `dist/lib`. Module-level CSS output follows the same switch.
-   *
-   * @default false
-   */
-  modules?: boolean;
-
-  /**
-   * Style build configuration.
-   *
-   * @default { themes: {}, dependencies: {} }
-   */
-  styles?: {
-    /**
-     * Theme style entries for the current package.
-     *
-     * The key is the theme name, and the value is a style file path relative to
-     * the current package root.
-     *
-     * @example
-     * {
-     *   light: './src/themes/light.css',
-     *   dark: './src/themes/dark.css',
-     * }
-     *
-     * @default {}
-     */
-    themes?: Record<string, string>;
-
-    /**
-     * External package style dependencies.
-     *
-     * The key is the dependency package name, and the value describes style
-     * entry rules for that package.
-     *
-     * @default {}
-     */
-    dependencies?: Record<
-      string,
-      {
-        /**
-         * Package-level style entry from the dependency package.
-         *
-         * This participates in package style and external style generation for
-         * the current package.
-         *
-         * @default undefined
-         */
-        entry?: string | string[];
-
-        /**
-         * Theme style entries from the dependency package.
-         *
-         * The key should match a theme name in the current package, and the
-         * value is the corresponding theme entry in the dependency package.
-         *
-         * @default undefined
-         */
-        themes?: Record<string, string>;
-
-        /**
-         * Module CSS auto import rules.
-         *
-         * The field name remains `components` for compatibility with common
-         * component-library usage. The rule itself is not limited to
-         * components; paths such as `/pages/**.css` or `/blocks/**.css` are also
-         * valid.
-         *
-         * @default undefined
-         */
-        components?: string | string[];
-      }
-    >;
-  };
-
-  /**
-   * JavaScript/TypeScript build configuration.
-   */
-  build?: {
-    /**
-     * Package-level bundle formats.
-     *
-     * @default ['cjs', 'esm', 'iife']
-     */
-    formats?: Array<'cjs' | 'esm' | 'iife'>;
-
-    /**
-     * JavaScript compilation target passed to tsdown.
-     *
-     * Bundle, IIFE, and module output use the same target.
-     *
-     * @default 'es2020'
-     */
-    target?: string | string[] | false;
-
-    /**
-     * Runtime platform for the build target.
-     *
-     * @default 'neutral'
-     */
-    platform?: 'node' | 'neutral' | 'browser';
-
-    /**
-     * Custom bundle banner.
-     *
-     * When omitted, auklet generates one from package name/version/author.
-     *
-     * @default undefined
-     */
-    banner?: string;
-
-    /**
-     * Additional external package names.
-     *
-     * These are combined with package.json dependencies and peerDependencies
-     * before being passed to tsdown.
-     *
-     * @default []
-     */
-    externals?: string[];
-
-    /**
-     * Path aliases passed to tsdown `alias`.
-     *
-     * This applies to both bundle output and module output.
-     *
-     * @default {}
-     */
-    alias?: Record<string, string>;
-
-    /**
-     * Package.json entry field resolution order for bundle output.
-     *
-     * This is passed to rolldown `resolve.mainFields`. When omitted, auklet
-     * only sets `['browser', 'module', 'main']` for IIFE bundles.
-     *
-     * @default undefined
-     */
-    mainFields?: string[];
-
-    /**
-     * Global names for IIFE externals.
-     *
-     * This is passed to tsdown `output.globals` and overrides the global names
-     * auklet infers from package names.
-     *
-     * @default {}
-     */
-    globals?: Record<string, string>;
-
-    /**
-     * TypeScript config file path, relative to the current package root.
-     *
-     * When omitted, auklet searches upward from the current package root for
-     * the nearest `tsconfig.json`.
-     *
-     * @default undefined
-     */
-    tsconfig?: string;
-
-    /**
-     * Final tsdown config hook.
-     *
-     * auklet calls this after generating each tsdown config, allowing users to
-     * make final adjustments.
-     *
-     * @default undefined
-     */
-    configureTsdown?: (
-      config: UserConfig,
-      context: {
-        /**
-         * Build output kind for the current config.
-         *
-         * `bundle` means package-level bundle/IIFE output.
-         * `module` means unbundled module output generated by `modules: true`.
-         */
-        kind: 'bundle' | 'module';
-
-        /**
-         * Output format for the current config.
-         */
-        format: 'cjs' | 'esm' | 'iife';
-
-        /**
-         * Current package root.
-         */
-        packageRoot: string;
-
-        /**
-         * Current package build output directory.
-         */
-        output: string;
-
-        /**
-         * Current package.json name.
-         */
-        packageName?: string;
-      },
-    ) => UserConfig;
-  };
-}
-```
-
-A common component-library dependency rule looks like this:
+Configuration reference:
+
+| Path                                  | Default                  | Description                                                                                                                 |
+| ------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `source`                              | `'src'`                  | Source directory relative to the current package root.                                                                      |
+| `output`                              | `'dist'`                 | Build output directory. `auk build` removes it before rebuilding.                                                           |
+| `modules`                             | `false`                  | Generate unbundled module JS output and module-level CSS output.                                                            |
+| `styles.themes`                       | `{}`                     | Current package theme entries, keyed by theme name. Values are paths relative to the current package root.                  |
+| `styles.dependencies`                 | `{}`                     | External package style rules, keyed by dependency package name.                                                             |
+| `styles.dependencies[pkg].entry`      | `undefined`              | Package-level style entry or entries from the dependency package.                                                           |
+| `styles.dependencies[pkg].themes`     | `undefined`              | Theme entries from the dependency package, keyed by current package theme name.                                             |
+| `styles.dependencies[pkg].components` | `undefined`              | Module CSS auto import rules. The name is historical; rules can point to paths such as `/pages/**.css` or `/blocks/**.css`. |
+| `build.formats`                       | `['cjs', 'esm', 'iife']` | Package-level bundle formats.                                                                                               |
+| `build.target`                        | `'es2020'`               | JavaScript target passed to tsdown.                                                                                         |
+| `build.platform`                      | `'neutral'`              | Runtime platform: `node`, `neutral`, or `browser`.                                                                          |
+| `build.banner`                        | generated                | Custom bundle banner.                                                                                                       |
+| `build.externals`                     | `[]`                     | Extra external package names combined with package dependencies.                                                            |
+| `build.alias`                         | `{}`                     | Path aliases passed to tsdown.                                                                                              |
+| `build.mainFields`                    | IIFE only                | Package entry field resolution order for bundle output.                                                                     |
+| `build.globals`                       | `{}`                     | Global names for IIFE externals.                                                                                            |
+| `build.tsconfig`                      | nearest `tsconfig.json`  | TypeScript config path relative to package root.                                                                            |
+| `build.configureTsdown`               | `undefined`              | Final hook for each generated tsdown config.                                                                                |
+
+Common dependency rule:
 
 ```ts
 {
@@ -373,12 +194,24 @@ A common component-library dependency rule looks like this:
 }
 ```
 
-## CSS Auto Import
+`configureTsdown` receives the generated tsdown config and a context:
+
+```ts
+type ConfigureTsdownContext = {
+  kind: 'bundle' | 'module';
+  format: 'cjs' | 'esm' | 'iife';
+  packageRoot: string;
+  output: string;
+  packageName?: string;
+};
+```
+
+## CSS Conventions And Limits
 
 CSS auto import only scans `.tsx` files. `.ts` and `.d.ts` files do not
-participate in CSS auto import.
+participate.
 
-Supported syntax:
+Supported source syntax:
 
 ```tsx
 import { Button } from '@scope/ui';
@@ -403,28 +236,35 @@ final exported component names, so it cannot infer CSS paths safely.
 
 Inference rules:
 
-- Package-root named imports use the imported name. For example,
-  `import { Button } from '@scope/ui'` tries to generate
+- Package-root named imports use the imported name. For example, `Button` from
+  `@scope/ui` tries `@scope/ui/components/Button.css`.
+- Local aliases do not affect package-root inference. `Button as UIButton`
+  still uses `Button`.
+- Deep imports use the import path. `@scope/ui/components/Button` tries
   `@scope/ui/components/Button.css`.
-- Local aliases do not affect package-root import inference. For example,
-  `import { Button as UIButton } from '@scope/ui'` still uses `Button`.
-- Deep imports use the import path. For example,
-  `import { Anything } from '@scope/ui/components/Button'` tries to generate
-  `@scope/ui/components/Button.css`.
-- If the inferred CSS file does not exist, auklet skips it and does not generate
-  an invalid import.
-- If JavaScript auto inference and handwritten source CSS `@import` point to the
-  same file, auklet dedupes the import.
+- Missing inferred CSS files are skipped.
+- Duplicate imports inferred from JS and handwritten source CSS are deduped.
 
 Same-package source imports can be resolved through:
 
-- relative paths, such as `../Button`;
+- relative paths such as `../Button`;
 - `package.json#imports`, preferring the `source` condition;
 - `tsconfig.json` `compilerOptions.paths`.
 
 Only candidates resolved into the current package `source` directory are treated
 as same-package CSS dependencies.
 
+`build-css` handles CSS entry generation and simple `@import` expansion. It does
+not aim to replace a full CSS toolchain. In particular, keep these boundaries in
+mind:
+
+- It does not process preprocessors such as Sass or Less.
+- It does not implement CSS Modules.
+- It does not perform URL rebasing.
+- It does not evaluate conditional CSS import semantics beyond auklet's style
+  entry rules.
+- It expects source CSS files and package/style paths to exist on disk.
+
 ## CSS Output
 
 `build-css` generates package-level `index.css` when source styles exist.
@@ -473,10 +313,7 @@ output is not a completely empty file.
 into virtual CSS modules. It only applies to the Vite dev server; production
 builds still use `auk build` or `auk build-css`.
 
-### Single-Package Mode
-
-The plugin defaults to single-package mode. Vite root is treated as the current
-package root:
+Single-package mode is the default:
 
 ```ts
 import { aukletStylePlugin } from 'auklet';
@@ -486,19 +323,8 @@ export default {
 };
 ```
 
-This is equivalent to:
-
-```ts
-aukletStylePlugin({ mode: 'package' });
-```
-
-Single-package mode is intended for running a Vite demo directly from a
-component-library package root.
-
-### Monorepo Mode
-
-Use monorepo mode when a demo/app lives in a workspace and needs to work with
-multiple workspace packages at the same time:
+Use monorepo mode when a workspace demo/app needs to work with multiple
+workspace packages:
 
 ```ts
 import { aukletStylePlugin } from 'auklet';
@@ -508,28 +334,14 @@ export default {
 };
 ```
 
-`mode: 'monorepo'` walks upward from Vite root to find `pnpm-workspace.yaml`,
-then scans workspace packages.
-
-### Plugin Options
+Primary options:
 
-```ts
-export type AukletStylePluginOptions = {
-  mode?: 'package' | 'monorepo';
-  root?: string;
-};
-```
+| Option | Default     | Description                                                                                                                                         |
+| ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode` | `'package'` | `'package'` treats Vite root as the package root. `'monorepo'` finds `pnpm-workspace.yaml` upward from Vite root and reads pnpm workspace packages. |
+| `root` | inferred    | Custom graph root. Usually unnecessary.                                                                                                             |
 
-- `mode: 'package'`: default. Vite root is the current package root. This is
-  intended for single-package component libraries.
-- `mode: 'monorepo'`: walks upward from Vite root to find `pnpm-workspace.yaml`
-  and scans workspace packages.
-- `root`: custom graph root. This is usually unnecessary; use it only when a
-  monorepo root cannot be inferred automatically.
-
-### Supported CSS Imports
-
-The plugin resolves package CSS ids such as:
+Supported dev CSS imports:
 
 ```ts
 import '@scope/app/style.css';
@@ -539,13 +351,10 @@ import '@scope/app/components/Button.css';
 import '@scope/app/themes/light.css';
 ```
 
-### Dependency Resolution
-
 In dev mode, workspace package style dependencies keep using auklet virtual CSS
 recursion so style changes across packages can be tracked. Third-party CSS
 dependencies are resolved from the package root that declares them and emitted
-as Vite `/@fs/...` imports, avoiding lost `node_modules` resolution context from
-virtual modules.
+as Vite `/@fs/...` imports.
 
 ## Build Constants
 
@@ -561,58 +370,37 @@ Vitest uses test-friendly values with the same names: `__DEV__` is `true`,
 
 ## Programmatic API
 
-```ts
-import {
-  ModuleStyleBuilder,
-  ModuleStyleWatcher,
-  aukletStylePlugin,
-  loadAukletConfig,
-  runTsdown,
-} from 'auklet';
-
-const aukletConfig = await loadAukletConfig(process.cwd());
-
-await new ModuleStyleBuilder({
-  packageRoot: process.cwd(),
-  aukletConfig,
-}).build();
-```
+The root package entry exposes the Vite plugin, configuration helpers, and a
+small set of build helpers used by projects that need to compose auklet
+programmatically. Publish and owner workflows remain CLI/internal implementation
+details.
 
 Public exports include:
 
-- `ModuleStyleBuilder`
-- `ModuleStyleWatcher`
 - `aukletStylePlugin`
 - `loadAukletConfig`
-- `resolveAukletConfigModule`
-- `createTsdownArgs`
 - `runTsdown`
-- related TypeScript types
+- `defineKernelPackageConfigFromFile`
+- `defineKernelPackageConfigFromOptions`
+- `runAukletCli`
+- `AukletStylePluginOptions`
+- `AukletConfig`
+- `PackageBuildOptions`
+- `StyleOptions`
+- related user-facing TypeScript types
 
 ## Development
 
 ```bash
 pnpm i
-pnpm run test
-pnpm run typecheck
-pnpm run build
+pnpm test
+pnpm typecheck
+pnpm build
 pnpm run format
 ```
 
 Notes:
 
-- `pnpm run build` rewrites `dist`.
+- `pnpm build` rewrites `dist`.
 - `pnpm run format` formats `bin`, `src`, `dist`, `examples`, and related files.
 - Read `TESTING.md` before changing tests.
-
-## Testing
-
-Tests are organized into:
-
-- `src/__tests__/e2e`: project-level output structure and dependency-chain tests.
-- `src/__tests__/css`: CSS/style module and API tests.
-- `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.