@twobirds/microcomponents 0.9.0 → 0.10.1

package/dist/cli/dispatch.js

@@ -1,316 +0,0 @@
-/**
-Command dispatcher for the `mc` CLI.
-
-Kept free of any top-level side effects so the routing can be unit-tested:
-`index.ts` is the thin executable entry that calls {@link main}, while this
-module only exports the logic. Commands that wrap a package.json script
-(`clean`, `check`) are deliberately thin — they delegate to the script so the
-script stays the single source of truth. When the current project defines no
-such script, the CLI runs its own implementation against the current project,
-so the command works in any consumer project.
-
-@module CLI/Dispatch
-*/
-import { spawn } from 'node:child_process';
-import { parseArgs } from 'node:util';
-import { readFile, rm } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-import { writeScaffold, writeProject, displayPath } from './writeScaffold.js';
-import { scaffoldComponent } from './scaffold.js';
-import { scaffoldProject } from './create.js';
-const USAGE = `mc — Micro Components build tools
-
-Usage:
-  mc new <tag> [--css] [--html] [--target-html] [--shadow-html] [--target-css] [--shadow-css] [--js] [--dir <path>] [--force] [--dry-run]
-  mc create --namespace <ns> [--dir <path>] [--force] [--dry-run]
-  mc clean
-  mc check
-  mc --version
-  mc --help
-
-Commands:
-  new <tag>   Scaffold a micro component (e.g. mc new my-card --target-html --target-css)
-  create      Create a dev environment (e.g. mc create --namespace mc --dir mc-app)
-  clean       Remove build artifacts (dist, public, build, coverage)
-  check       Type-check every project (lib, cli, test, demo, node)
-
-Companion assets:
-  --css           document-level stylesheet (CSS custom properties / design tokens)
-  --html          unvariant light-DOM template
-  --target-html   template applied to target.innerHTML
-  --shadow-html   template applied to shadowRoot.innerHTML
-  --target-css    document-level styles scoped to the host tag
-  --shadow-css    styles injected into the shadow root
-
-Other options:
-  --js         emit plain JavaScript instead of TypeScript
-  --dir <path> scaffold root (default: src)
-  --force      overwrite files that already exist
-  --dry-run    print what would be written; touch nothing on disk
-  --version    print the version of the package the CLI ships in (-v)
-  --help       print this text (-h)
-
-Created paths are printed as they appear from the current directory. mc create writes
-a whole project into a folder of its own (default: the namespace), so its files show
-up under that folder, e.g. mc-app/src/mc/app.ts.
-`;
-// Map CLI flags to the runtime's camelCase asset descriptors.
-const ASSET_FLAGS = {
-    css: 'css',
-    html: 'html',
-    'target-html': 'targetHtml',
-    'shadow-html': 'shadowHtml',
-    'target-css': 'targetCss',
-    'shadow-css': 'shadowCss',
-};
-/**
-A scaffolded file as it appears from the current directory: the file `rel` under
-`root`, resolved and made readable. `mc create` writes a project into a folder of
-its own, so `src/mc/app.ts` under `mc-app` prints as `mc-app/src/mc/app.ts` — the
-path the user can find with `ls`.
-
-@example
-```ts
-createdPath('mc-app', 'src/mc/app.ts');
-createdPath('src', 'my/card.ts');
-```
-@param root - Scaffold root the file is written under.
-@param rel - Path of the file relative to `root`.
-*/
-function createdPath(root, rel) {
-    return displayPath(path.resolve(root, rel));
-}
-/**
-Spawns a command and resolves with its exit code.
-
-@example
-```ts
-const code = await spawnProcess('pnpm', ['run', 'clean']);
-```
-@param command - Executable to spawn.
-@param args - Arguments to pass.
-@param cwd - Working directory (defaults to the current one).
-*/
-function spawnProcess(command, args, cwd) {
-    return new Promise((resolve) => {
-        const child = spawn(command, args, { stdio: 'inherit', cwd });
-        child.on('exit', (code) => resolve(code ?? 1));
-    });
-}
-/**
-Whether the package.json in the current directory declares `script` in its
-"scripts". Consumers get this check so `mc clean`/`mc check` can fall back to
-the CLI's own implementation when the project defines no such script.
-
-@example
-```ts
-const ok = await hasScript('clean');
-```
-@param script - Script name to look up.
-*/
-async function hasScript(script) {
-    try {
-        const pkg = JSON.parse(await readFile(path.join(process.cwd(), 'package.json'), 'utf8'));
-        return typeof pkg?.scripts?.[script] === 'string';
-    }
-    catch {
-        return false;
-    }
-}
-/** Build artifacts to remove, relative to the project root. */
-const CLEAN_DIRS = ['dist', 'public', 'build', 'coverage'];
-/**
-Removes build artifacts in the current project.
-
-@example
-```ts
-const code = await cleanSelf();
-```
-@param cwd - Project root (defaults to the current directory).
-*/
-async function cleanSelf(cwd = process.cwd()) {
-    await Promise.all(CLEAN_DIRS.map(async (dir) => {
-        const abs = path.join(cwd, dir);
-        if (existsSync(abs)) {
-            await rm(abs, { recursive: true, force: true });
-            console.log(`removed ${dir}/`);
-        }
-    }));
-    return 0;
-}
-/**
-Type-checks the current project with its own `tsconfig.json`.
-
-@example
-```ts
-const code = await checkSelf();
-```
-@param cwd - Project root (defaults to the current directory).
-*/
-async function checkSelf(cwd = process.cwd()) {
-    const config = path.join(cwd, 'tsconfig.json');
-    if (!existsSync(config)) {
-        console.error('mc check: no tsconfig.json in the current project');
-        return 1;
-    }
-    return spawnProcess('pnpm', ['exec', 'tsc', '--noEmit', '-p', 'tsconfig.json'], cwd);
-}
-/**
-The version of the package the CLI ships in, read from its package.json. Two
-levels above `dist/cli` (and above `src/cli` when tsx runs the source) is the
-package root, so the CLI reports the version it was installed with, not the
-version of the project it is run in.
-
-@example
-```ts
-const version = await readVersion();
-```
-@param pkgPath - package.json to read (defaults to the package root of this CLI).
-*/
-async function readVersion(pkgPath = path.join(import.meta.dirname, '..', '..', 'package.json')) {
-    const { version } = JSON.parse(await readFile(pkgPath, 'utf8'));
-    return version;
-}
-/**
-Runs a package.json script through pnpm and resolves with its exit code.
-
-Thin wrappers like `clean` and `check` delegate here so the script — not the
-CLI — remains the single source of truth for what each command does. If the
-current project defines no such script, the CLI runs its own implementation
-against the current project, so the command works in any consumer project.
-
-@example
-```ts
-const code = await runScript('check');
-```
-*/
-export async function runScript(script) {
-    if (await hasScript(script)) {
-        return spawnProcess('pnpm', ['run', script]);
-    }
-    if (script === 'clean')
-        return cleanSelf();
-    if (script === 'check')
-        return checkSelf();
-    console.error(`mc: no "${script}" script in the current project`);
-    return 1;
-}
-/**
-Parses `argv` and routes it to the matching command, returning a process exit
-code. `run` is injectable so the script-wrapping commands can be tested without
-spawning anything.
-
-@example
-```ts
-const code = await main(['clean'], async (script) => {
-    console.log(`would run ${script}`);
-    return 0;
-});
-```
-@example
-```ts
-const code = await main(['--version']);
-```
-*/
-export async function main(argv, run = runScript) {
-    const { values, positionals } = parseArgs({
-        args: argv,
-        allowPositionals: true,
-        options: {
-            css: { type: 'boolean' },
-            html: { type: 'boolean' },
-            'target-html': { type: 'boolean' },
-            'shadow-html': { type: 'boolean' },
-            'target-css': { type: 'boolean' },
-            'shadow-css': { type: 'boolean' },
-            js: { type: 'boolean' },
-            dir: { type: 'string' },
-            namespace: { type: 'string' },
-            force: { type: 'boolean' },
-            'dry-run': { type: 'boolean' },
-            help: { type: 'boolean', short: 'h' },
-            version: { type: 'boolean', short: 'v' },
-        },
-    });
-    const command = positionals[0];
-    if (values.version) {
-        console.log(await readVersion());
-        return 0;
-    }
-    if (values.help || !command) {
-        console.log(USAGE);
-        return 0;
-    }
-    if (command === 'new') {
-        const tag = positionals[1];
-        if (!tag) {
-            console.error('mc new: missing component tag (e.g. mc new my-card)');
-            return 1;
-        }
-        const assets = [];
-        const flags = values;
-        for (const [flag, kind] of Object.entries(ASSET_FLAGS)) {
-            if (flags[flag])
-                assets.push(kind);
-        }
-        if (values['dry-run']) {
-            const { files } = scaffoldComponent(tag, { assets, js: values.js });
-            const root = values.dir ?? 'src';
-            for (const rel of Object.keys(files).sort())
-                console.log(`would create ${createdPath(root, rel)}`);
-            return 0;
-        }
-        const root = values.dir ?? 'src';
-        let written;
-        try {
-            written = await writeScaffold(tag, root, { assets, js: values.js, force: values.force });
-        }
-        catch (e) {
-            console.error(e.message);
-            return 1;
-        }
-        for (const rel of written)
-            console.log(`created ${createdPath(root, rel)}`);
-        return 0;
-    }
-    if (command === 'create') {
-        const namespace = values.namespace;
-        if (!namespace) {
-            console.error('mc create: missing --namespace (e.g. mc create --namespace mc)');
-            return 1;
-        }
-        const root = values.dir ?? namespace;
-        let files;
-        try {
-            ({ files } = scaffoldProject(namespace));
-        }
-        catch (e) {
-            console.error(e.message);
-            return 1;
-        }
-        if (values['dry-run']) {
-            for (const rel of Object.keys(files).sort())
-                console.log(`would create ${createdPath(root, rel)}`);
-            return 0;
-        }
-        let written;
-        try {
-            written = await writeProject(namespace, root, { force: values.force });
-        }
-        catch (e) {
-            console.error(e.message);
-            return 1;
-        }
-        for (const rel of written)
-            console.log(`created ${createdPath(root, rel)}`);
-        console.log(`\nproject "${namespace}" created in ${root}/ — run: cd ${root} && pnpm install && pnpm dev`);
-        return 0;
-    }
-    if (command === 'clean')
-        return run('clean');
-    if (command === 'check')
-        return run('check');
-    console.error(`mc: unknown command "${command}"\n\n${USAGE}`);
-    return 1;
-}

package/dist/cli/scaffold.js

@@ -1,109 +0,0 @@
-/**
-Scaffolding for new micro components.
-
-Pure, filesystem-free logic: given a tag name it returns the files to write and
-their contents. The tag-to-path rule is not re-derived here — it comes from
-{@link tagPath}, the same primitive the runtime autoload loader uses, so the
-scaffold and the runtime can never disagree about where a component lives.
-
-Companion assets follow the runtime's variant convention (see `loadAssets` /
-`processAssets`): a camelCase descriptor maps to a dotted filename, e.g.
-`'targetHtml'` → `{path}.target.html`, `'shadowCss'` → `{path}.shadow.css`, and
-the unvariant `'css'` → `{path}.css` (the document-level stylesheet where CSS
-custom properties / design tokens live).
-
-@module CLI/Scaffold
-*/
-import { tagPath } from '../utils/resolveComponentPath.js';
-// Custom element names must be lowercase kebab-case and contain at least one
-// hyphen (defineCE rejects hyphenless tags), with no empty segments.
-const TAG_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
-/**
-Whether a string is a valid micro component tag name.
-
-@example
-```ts
-console.log(isValidComponentTag('my-card'));
-console.log(isValidComponentTag('mycard'));
-```
-*/
-export function isValidComponentTag(tag) {
-    return TAG_RE.test(tag);
-}
-/**
-Builds the files for a new micro component from its tag name.
-
-@example
-```ts
-const { className, files } = scaffoldComponent('my-card', {
-    assets: ['targetHtml', 'targetCss'],
-});
-console.log(className);
-console.log(Object.keys(files));
-```
-@param tag - Kebab-case component tag, e.g. `my-card`.
-@param options - Which companion assets to emit and whether to use `.js`.
-@throws If `tag` is not a valid custom element name.
-*/
-export function scaffoldComponent(tag, options = {}) {
-    if (!isValidComponentTag(tag)) {
-        throw new Error(`invalid component tag "${tag}": must be kebab-case with at least one hyphen (e.g. "my-card")`);
-    }
-    const className = tag
-        .split('-')
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join('');
-    const ext = options.js ? 'js' : 'ts';
-    const ctorParam = options.js ? 'target' : 'target: HTMLElement';
-    const base = tagPath(tag);
-    const assets = [...new Set(options.assets ?? [])];
-    const files = {};
-    files[`${base}.${ext}`] = componentSource(tag, ctorParam, assets);
-    for (const kind of assets) {
-        files[assetFile(tag, kind)] = assetSource(kind, tag);
-    }
-    return { files, className };
-}
-// Mirrors loadAssets' parseAsset: camelCase variant+ext → dotted filename,
-// plain ext → single extension. Reuses tagPath so scaffold and runtime agree.
-function assetFile(tag, kind) {
-    const m = kind.match(/^([a-z]+)([A-Z][a-z]*)$/);
-    const suffix = m ? `.${m[1]}.${m[2].toLowerCase()}` : `.${kind.toLowerCase()}`;
-    return `${tagPath(tag)}${suffix}`;
-}
-function componentSource(tag, ctorParam, assets) {
-    const lines = [
-        `import { DC, defineCE } from '@twobirds/microcomponents';`,
-        ``,
-        `/**`,
-        `\`${tag}\` — describe what this micro component does.`,
-        ``,
-        `@example`,
-        '```html',
-        `<${tag}></${tag}>`,
-        '```',
-        `*/`,
-        `defineCE(`,
-        `\t'${tag}',`,
-        `\tclass extends DC {`,
-    ];
-    if (assets.length) {
-        lines.push(`\t\tstatic assets = [${assets.map((a) => `'${a}'`).join(', ')}];`);
-    }
-    lines.push(`\t\tconstructor(${ctorParam}) {`, `\t\t\tsuper(target);`, `\t\t}`, `\t}`, `);`, ``);
-    return lines.join('\n');
-}
-function assetSource(kind, tag) {
-    switch (kind) {
-        case 'css':
-            // Document-level global stylesheet — the home of CSS custom properties.
-            return [':root {', '\t/* design tokens (CSS custom properties) */', '}', ''].join('\n');
-        case 'targetCss':
-            return [`${tag} {`, '\tdisplay: block;', '}', ''].join('\n');
-        case 'shadowCss':
-            return [':host {', '\tdisplay: block;', '}', ''].join('\n');
-        default:
-            // html / targetHtml / shadowHtml
-            return '<slot></slot>\n';
-    }
-}

package/dist/cli/writeScaffold.js

@@ -1,114 +0,0 @@
-// oxlint-disable no-await-in-loop
-/**
-Filesystem side of {@link scaffoldComponent} and {@link scaffoldProject}: writes the
-generated files under a root directory, creating nested folders as needed.
-
-Existing files are never overwritten silently: every target is checked before the
-first write, so a rerun in a populated directory reports the conflicts and touches
-nothing. `force` opts into overwriting.
-
-@module CLI/Scaffold
-*/
-import { existsSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { scaffoldComponent } from './scaffold.js';
-import { scaffoldProject } from './create.js';
-/**
-The path of a target file as it appears from the current working directory.
-`mc create` writes a project into a folder of its own, so a path relative to the
-project root cannot be found from the directory the command ran in: this turns
-`src/mc/app.ts` under `mc-app/` into `mc-app/src/mc/app.ts`. Falls back to the
-absolute path when the target lies outside the current directory, so the log never
-prints `../../..` chains.
-
-@example
-```ts
-// in a directory containing mc-app/src/mc/app.ts
-displayPath(path.resolve('mc-app', 'src/mc/app.ts'));
-displayPath('/tmp/mc-app/package.json');
-```
-@param abs - Absolute path of the target file.
-@group CLI
-*/
-export function displayPath(abs) {
-    const rel = path.relative(process.cwd(), abs);
-    return rel.startsWith('..') ? abs : rel;
-}
-/**
-Writes generated files under `root`, creating nested folders as needed, and reports
-the written paths relative to `root`.
-
-@example
-```ts
-const written = await writeGenerated({ 'my/card.ts': 'source' }, 'src', false);
-console.log(written);
-```
-@param files - Files to write, keyed by path relative to `root`.
-@param root - Directory to write under (`src` for a component, `mc-app` for a project).
-@param force - Overwrite files that already exist.
-@returns The written file paths, relative to `root`.
-@throws If any target file exists and `force` is false. Nothing is written in that case.
-*/
-async function writeGenerated(files, root, force) {
-    const targets = Object.entries(files).map(([rel, contents]) => ({
-        rel,
-        abs: path.resolve(root, rel),
-        contents,
-    }));
-    if (!force) {
-        const conflicts = targets
-            .filter((target) => existsSync(target.abs))
-            .map((t) => displayPath(t.abs));
-        if (conflicts.length) {
-            throw new Error(`refusing to overwrite ${conflicts.length} existing file(s):\n${conflicts
-                .map((file) => `\t${file}`)
-                .join('\n')}\n\nrerun with --force to overwrite`);
-        }
-    }
-    const written = [];
-    for (const { rel, abs, contents } of targets) {
-        await mkdir(path.dirname(abs), { recursive: true });
-        await writeFile(abs, contents, 'utf8');
-        written.push(rel);
-    }
-    return written;
-}
-/**
-Scaffolds a component onto disk under `root`.
-
-@example
-```ts
-const written = await writeScaffold('my-card', 'src', { assets: ['css'] });
-console.log(written);
-```
-@param tag - Kebab-case component tag.
-@param root - Directory to scaffold under (e.g. `src`).
-@param options - Which companion files to emit, and whether to overwrite existing ones.
-@returns The written file paths, relative to `root`.
-@throws If a target file exists and `force` is false.
-*/
-export async function writeScaffold(tag, root, options = {}) {
-    const { files } = scaffoldComponent(tag, options);
-    return writeGenerated(files, root, options.force ?? false);
-}
-/**
-Filesystem side of {@link scaffoldProject}: writes a complete dev environment for a
-namespace under a project root, creating nested folders as needed.
-
-@example
-```ts
-const written = await writeProject('mc', 'mc-app');
-console.log(written);
-```
-@param namespace - 1 to 4 lowercase letters.
-@param root - Directory to create the project in (e.g. `mc-app`).
-@param options - Whether to overwrite existing files.
-@returns The written file paths, relative to `root`.
-@throws If `namespace` is not 1 to 4 lowercase letters, or a target file exists and
-`force` is false.
-*/
-export async function writeProject(namespace, root, options = {}) {
-    const { files } = scaffoldProject(namespace);
-    return writeGenerated(files, root, options.force ?? false);
-}