@twobirds/microcomponents 0.4.0 → 0.4.1

package/README.md

@@ -58,40 +58,54 @@ 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
 ```

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.4.1',
         },
         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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"description": "Micro Components",
 	"keywords": [
 		"PWA",