@twobirds/microcomponents 0.3.0 → 0.4.1

package/dist/cli/dispatch.js

@@ -0,0 +1,287 @@
+/**
+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
+
+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
+
+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);
+}
+/**
+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;
+});
+```
+*/
+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' },
+        },
+    });
+    const command = positionals[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/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+Executable entry point of the `mc` CLI (package.json "bin").
+
+Deliberately thin: all parsing and routing lives in {@link main} so it can be
+unit-tested without spawning a process. This module only feeds `process.argv`
+in and pushes the resulting exit code out.
+
+@module CLI/Index
+*/
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;EAQE"}

package/dist/cli/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+Executable entry point of the `mc` CLI (package.json "bin").
+
+Deliberately thin: all parsing and routing lives in {@link main} so it can be
+unit-tested without spawning a process. This module only feeds `process.argv`
+in and pushes the resulting exit code out.
+
+@module CLI/Index
+*/
+import { main } from './dispatch.js';
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli/scaffold.d.ts

@@ -0,0 +1,68 @@
+/**
+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
+*/
+/**
+Companion asset kinds, mirroring the camelCase descriptors the runtime loads.
+
+- `css` — document-level global stylesheet (CSS custom properties / design tokens).
+- `targetCss` — document-level styles scoped to the host tag.
+- `shadowCss` — styles injected into the shadow root.
+- `html` — unvariant light-DOM template.
+- `targetHtml` — light-DOM template applied to `target.innerHTML`.
+- `shadowHtml` — template applied to `shadowRoot.innerHTML`.
+*/
+export type AssetKind = 'css' | 'targetCss' | 'shadowCss' | 'html' | 'targetHtml' | 'shadowHtml';
+/** Options controlling which files a scaffold emits. */
+export interface ScaffoldOptions {
+    /** Companion assets to emit and wire into `static assets`. */
+    assets?: AssetKind[];
+    /** Emit a plain `.js` file instead of `.ts` (rapid-prototyping path). */
+    js?: boolean;
+}
+/** Result of {@link scaffoldComponent}. */
+export interface ScaffoldResult {
+    /** Files to write, keyed by path relative to the scaffold root (e.g. `my/card.ts`). */
+    files: Record<string, string>;
+    /** The PascalCase class name derived from the tag. */
+    className: string;
+}
+/**
+Whether a string is a valid micro component tag name.
+
+@example
+```ts
+console.log(isValidComponentTag('my-card'));
+console.log(isValidComponentTag('mycard'));
+```
+*/
+export declare function isValidComponentTag(tag: string): boolean;
+/**
+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 declare function scaffoldComponent(tag: string, options?: ScaffoldOptions): ScaffoldResult;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/cli/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/cli/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AAIF;;;;;;;;;EASE;AACF,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,WAAW,GAAG,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC;AAEjG,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC/B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAC;CACb;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC9B,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;EAQE;AACF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;EAcE;AACF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAuB5F"}

package/dist/cli/scaffold.js

@@ -0,0 +1,109 @@
+/**
+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.d.ts

@@ -0,0 +1,66 @@
+/**
+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 { type ScaffoldOptions } from './scaffold.js';
+/** Whether files that already exist may be overwritten. */
+export interface WriteOptions {
+    force?: boolean;
+}
+/**
+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 declare function displayPath(abs: string): string;
+/**
+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 declare function writeScaffold(tag: string, root: string, options?: ScaffoldOptions & WriteOptions): Promise<string[]>;
+/**
+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 declare function writeProject(namespace: string, root: string, options?: WriteOptions): Promise<string[]>;
+//# sourceMappingURL=writeScaffold.d.ts.map

package/dist/cli/writeScaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeScaffold.d.ts","sourceRoot":"","sources":["../../src/cli/writeScaffold.ts"],"names":[],"mappings":"AACA;;;;;;;;;EASE;AAKF,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGxE,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAE5B,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;EAgBE;AACF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C;AAmDD;;;;;;;;;;;;;EAaE;AACF,wBAAsB,aAAa,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAe,GAAG,YAAiB,GAC1C,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB;AAED;;;;;;;;;;;;;;;EAeE;AACF,wBAAsB,YAAY,CACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB"}

package/dist/cli/writeScaffold.js

@@ -0,0 +1,114 @@
+// 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);
+}