@twobirds/microcomponents 0.4.1 → 0.6.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
 
@@ -101,16 +109,31 @@ pnpm run cli -- create --namespace mc
 # rerun with --force to overwrite
 ```
 
-Once installed from npm the same command is available as `mc`:
+Once installed from npm the same command is available as `mc` (and as `microcomponents`, the same executable under the package name):
 
 ```bash
 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
+mc --version
 ```
 
-`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. `mc --version` (`-v`) prints the version of the package the CLI ships in, read from its own package.json, so it reports the installed library, not the version of the project the command runs in.
+
+Nothing has to be installed to run it once — `npx` fetches the package into its own cache and runs the bin from there:
+
+```bash
+npx @twobirds/microcomponents mc --help
+npx @twobirds/microcomponents new my-card --target-html --target-css --dry-run
+```
+
+`npx <package>` alone has no bin name to run, so npm picks the bin whose key matches the unscoped package name — that is why `bin` lists `microcomponents` next to `mc`. With `-p` the package is named explicitly and the word after it is read as the bin name, so `mc` and the MCP server can be started by name:
+
+```bash
+npx -p @twobirds/microcomponents mc new my-card --target-html --target-css
+npx -p @twobirds/microcomponents microcomponents-mcp
+```
 
 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.1',
+            '@twobirds/microcomponents': '^0.6.0',
         },
         devDependencies: {
             vite: '^8.1.5',

package/dist/cli/dispatch.d.ts

@@ -38,6 +38,10 @@ const code = await main(['clean'], async (script) => {
     return 0;
 });
 ```
+@example
+```ts
+const code = await main(['--version']);
+```
 */
 export declare function main(argv: string[], run?: Runner): Promise<number>;
 //# sourceMappingURL=dispatch.d.ts.map

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;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"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AA0DF,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAwHzD;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED;;;;;;;;;;;;;;;;EAgBE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8GnF"}

package/dist/cli/dispatch.js

@@ -26,6 +26,8 @@ Usage:
   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)
@@ -46,6 +48,8 @@ Other options:
   --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
@@ -153,6 +157,22 @@ async function checkSelf(cwd = process.cwd()) {
     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
@@ -188,6 +208,10 @@ const code = await main(['clean'], async (script) => {
     return 0;
 });
 ```
+@example
+```ts
+const code = await main(['--version']);
+```
 */
 export async function main(argv, run = runScript) {
     const { values, positionals } = parseArgs({
@@ -206,9 +230,14 @@ export async function main(argv, run = runScript) {
             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;