@twobirds/microcomponents 0.4.0 → 0.5.0

package/README.md

@@ -40,17 +40,25 @@ The progress of coding is occasionally being streamed on [twitch](https://twitch
 
 ## MCP Server
 
-An MCP (Model Context Protocol) server ships with this repo so AI assistants can look the library up instead of answering from memory: `microcomponents-mcp-server.ts` at the repo root.
+An MCP (Model Context Protocol) server ships with the package so AI assistants can look the library up instead of answering from memory. The source is `src/mcp/index.ts`, compiled by `tsconfig.mcp.json` to `dist/mcp/index.js` and published with the package, so installing it gives you the executable bin:
 
 ```bash
-pnpm run mcp:run   # start the server on stdio
-pnpm run mcp:dev   # restart it whenever src/ changes
-pnpm run mcp:docs  # regenerate docs/api.json and report undocumented exports
+microcomponents-mcp   # stdio server, straight from the installed package
+```
+
+In a published package the server runs from `dist/mcp` and reads the prebuilt `api.json` and the concept essays that the build step emits next to it. During development it generates the index live from `src/` at startup, so it cannot drift away from the library it documents:
+
+```bash
+pnpm run mcp:dev    # restart it whenever src/ changes
+pnpm run mcp:run    # start it from source on stdio
+pnpm run mcp:docs   # regenerate dist/mcp/api.json and report undocumented exports
 ```
 
 Tools: `list-components`, `get-component-docs`, `search-components`, `get-core-concept`, `get-source-file`, `list-undocumented`.
 
-There is no hand-written API list in the server. The whole index is extracted at startup from the JSDoc blocks of the public exports (the names re-exported by each `src/*/index.ts`), so it can never drift away from the code it documents — and `list-undocumented` tells you when a source file still lacks a doc block. Concept essays are hand-authored markdown, one file per concept under `docs/concepts/`, which is also where the tool's list of available concepts comes from.
+There is no hand-written API list in the server. The whole index is extracted from the JSDoc blocks of the public exports (the names re-exported by each `src/*/index.ts`), so it can never drift away from the code it documents — and `list-undocumented` tells you when a source file still lacks a doc block. Concept essays are hand-authored markdown, one file per concept under `docs/concepts/`, copied into `dist/mcp/concepts` by the build, which is where the tool's list of available concepts comes from.
+
+`get-source-file` reads package-root relative paths (`dist/core/MC.d.ts`, `dist/mcp/concepts/event-system.md`) and refuses any path outside the package sources.
 
 ## CLI
 
@@ -58,45 +66,59 @@ A small command-line tool scaffolds new components so the tag-to-file convention
 
 ```bash
 pnpm run cli -- new my-card --target-html --target-css
-# created my/card.ts
-# created my/card.target.html
-# created my/card.target.css
+# created src/my/card.ts
+# created src/my/card.target.html
+# created src/my/card.target.css
 ```
 
-`--dry-run` prints the plan without touching disk, so you can check the derived paths first:
+Paths are printed as they appear from the current directory, so every line is a file you can open with `ls`. `--dry-run` prints the plan without touching disk, so you can check the derived paths first:
 
 ```bash
 pnpm run cli -- new my-card --target-html --target-css --dry-run
-# would create my/card.ts
-# would create my/card.target.html
-# would create my/card.target.css
+# would create src/my/card.ts
+# would create src/my/card.target.html
+# would create src/my/card.target.css
 ```
 
 `mc create` scaffolds a complete dev environment for a namespace — a Vite dev server serving `src/` straight, a page shell that turns on `autoload(true)`, and a starter component with companion assets:
 
 ```bash
 pnpm run cli -- create --namespace mc --dir mc-app
-# created package.json
-# created src/index.html
-# created src/mc/app.ts
-# created src/mc/app.target.html
-# created src/mc/app.target.css
+# created mc-app/package.json
+# created mc-app/src/index.html
+# created mc-app/src/mc/app.ts
+# created mc-app/src/mc/app.target.html
+# created mc-app/src/mc/app.target.css
 # ...
 # project "mc" created in mc-app/ — run: cd mc-app && pnpm install && pnpm dev
 ```
 
 The namespace (1 to 4 lowercase letters) becomes the `src/<namespace>/` folder and the first segment of every component tag, so `mc` is the home of tags like `<mc-app>`. Because the page shell is the autoload base, `import.meta.url` + the tag-to-path rule resolves `<mc-app>` to `src/mc/app.js` — the compiled starter. `--dir` defaults to the namespace, `--dry-run` prints the plan without touching disk.
 
+The project is written into a folder of its own, so its files are reported under that folder (`mc-app/src/mc/app.ts`) — the path you can find from the directory you ran the command in, not relative to the project root.
+
+Existing files are never overwritten silently: every target is checked before the first write, so a rerun in a populated directory lists the conflicts and touches nothing. `--force` opts into overwriting:
+
+```bash
+pnpm run cli -- create --namespace mc
+# refusing to overwrite 10 existing file(s):
+#         mc/package.json
+#         mc/src/mc/app.ts
+#         ...
+#
+# rerun with --force to overwrite
+```
+
 Once installed from npm the same command is available as `mc`:
 
 ```bash
-mc new my-card [--css] [--html] [--target-html] [--shadow-html] [--target-css] [--shadow-css] [--js] [--dir <path>] [--dry-run]
-mc create --namespace <ns> [--dir <path>] [--dry-run]
+mc new my-card [--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
 ```
 
-`clean` and `check` are thin wrappers around the package.json scripts of the same name, so the scripts remain the single source of truth for what they do — `mc check` type-checks every project context (lib, cli, test, demo, node) and exits with the script's exit code.
+`clean` and `check` are thin wrappers around the package.json scripts of the same name, so the scripts remain the single source of truth for what they do — `mc check` type-checks every project context (lib, cli, mcp, test, demo, node) and exits with the script's exit code.
 
 The scaffold derives the file path from the tag using the same rule the runtime autoload loader uses (`my-card` → `my/card.ts`), names companion assets after the runtime's asset descriptors (`targetHtml` → `card.target.html`), and wires them into a `static assets` declaration. `--js` emits a plain JavaScript file for the rapid-prototyping path.
 

package/dist/cli/create.js

@@ -81,7 +81,7 @@ function packageJson(namespace) {
             typecheck: 'tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.vc.json',
         },
         dependencies: {
-            '@twobirds/microcomponents': '^0.4.0',
+            '@twobirds/microcomponents': '^0.5.0',
         },
         devDependencies: {
             vite: '^8.1.5',

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAiDF,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAmFzD;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED;;;;;;;;;;;;EAYE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0FnF"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAsDF,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAqGzD;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED;;;;;;;;;;;;EAYE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwGnF"}

package/dist/cli/dispatch.js

@@ -16,14 +16,14 @@ 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 } from './writeScaffold.js';
+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>] [--dry-run]
-  mc create --namespace <ns> [--dir <path>] [--dry-run]
+  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
 
@@ -44,7 +44,12 @@ Companion assets:
 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 = {
@@ -56,6 +61,23 @@ const ASSET_FLAGS = {
     '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
@@ -181,6 +203,7 @@ export async function main(argv, run = runScript) {
             js: { type: 'boolean' },
             dir: { type: 'string' },
             namespace: { type: 'string' },
+            force: { type: 'boolean' },
             'dry-run': { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
         },
@@ -204,16 +227,22 @@ export async function main(argv, run = runScript) {
         }
         if (values['dry-run']) {
             const { files } = scaffoldComponent(tag, { assets, js: values.js });
-            for (const file of Object.keys(files).sort())
-                console.log(`would create ${file}`);
+            const root = values.dir ?? 'src';
+            for (const rel of Object.keys(files).sort())
+                console.log(`would create ${createdPath(root, rel)}`);
             return 0;
         }
-        const written = await writeScaffold(tag, values.dir ?? 'src', {
-            assets,
-            js: values.js,
-        });
-        for (const file of written)
-            console.log(`created ${file}`);
+        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') {
@@ -232,13 +261,20 @@ export async function main(argv, run = runScript) {
             return 1;
         }
         if (values['dry-run']) {
-            for (const file of Object.keys(files).sort())
-                console.log(`would create ${file}`);
+            for (const rel of Object.keys(files).sort())
+                console.log(`would create ${createdPath(root, rel)}`);
             return 0;
         }
-        const written = await writeProject(namespace, root);
-        for (const file of written)
-            console.log(`created ${file}`);
+        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;
     }

package/dist/cli/writeScaffold.d.ts

@@ -1,10 +1,36 @@
 /**
-Filesystem side of {@link scaffoldComponent}: writes the generated files under a
-root directory, creating nested folders as needed.
+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`.
 
@@ -15,10 +41,11 @@ 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.
+@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): Promise<string[]>;
+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.
@@ -30,8 +57,10 @@ 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.
+@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): Promise<string[]>;
+export declare function writeProject(namespace: string, root: string, options?: WriteOptions): Promise<string[]>;
 //# sourceMappingURL=writeScaffold.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"writeScaffold.d.ts","sourceRoot":"","sources":["../../src/cli/writeScaffold.ts"],"names":[],"mappings":"AACA;;;;;EAKE;AAIF,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGxE;;;;;;;;;;;;EAYE;AACF,wBAAsB,aAAa,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB;AAED;;;;;;;;;;;;;EAaE;AACF,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrF"}
+{"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

@@ -1,32 +1,73 @@
 // oxlint-disable no-await-in-loop
 /**
-Filesystem side of {@link scaffoldComponent}: writes the generated files under a
-root directory, creating nested folders as needed.
+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';
 /**
-Scaffolds a component onto disk under `root`.
+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
-const written = await writeScaffold('my-card', 'src', { assets: ['css'] });
+// 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 tag - Kebab-case component tag.
-@param root - Directory to scaffold under (e.g. `src`).
-@param options - Which companion files to emit.
+@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.
 */
-export async function writeScaffold(tag, root, options = {}) {
-    const { files } = scaffoldComponent(tag, options);
+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, contents] of Object.entries(files)) {
-        const abs = path.join(root, rel);
+    for (const { rel, abs, contents } of targets) {
         await mkdir(path.dirname(abs), { recursive: true });
         await writeFile(abs, contents, 'utf8');
         written.push(rel);
@@ -34,6 +75,24 @@ export async function writeScaffold(tag, root, options = {}) {
     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.
 
@@ -44,17 +103,12 @@ 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.
+@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) {
+export async function writeProject(namespace, root, options = {}) {
     const { files } = scaffoldProject(namespace);
-    const written = [];
-    for (const [rel, contents] of Object.entries(files)) {
-        const abs = path.join(root, rel);
-        await mkdir(path.dirname(abs), { recursive: true });
-        await writeFile(abs, contents, 'utf8');
-        written.push(rel);
-    }
-    return written;
+    return writeGenerated(files, root, options.force ?? false);
 }