@zokugun/artifact 0.3.0 → 0.4.0

package/README.md

@@ -7,10 +7,15 @@
 [![License](https://img.shields.io/badge/donate-liberapay-green)](https://liberapay.com/daiyam/donate)
 [![License](https://img.shields.io/badge/donate-paypal-green)](https://paypal.me/daiyam99)
 
-`artifact` is a command-line interface which allows you:
-- to boilerplate your project from multiple packages
-- to merge the duplicated configuration files found across the packages
-- to keep your configurations up to date
+`artifact` is a CLI for boilerplating your project by composing reusable config packages, merging overlapping files, and keeping every artifact in sync with a single update command.
+
+Why artifact
+------------
+
+- Compose curated configuration packages ("artifacts") published on npm and mix several of them into a single repo.
+- Merge overlapping files intelligently using the built-in routes/steps pipeline.
+- Keep artifacts synchronized by running `artifact update`, optionally in CI with `--verbose` for traceability.
+- Support variant-aware installs and branch overlays so packages can expose multiple flavors while staying DRY.
 
 Mergeable Files
 ---------------
@@ -20,66 +25,148 @@ Mergeable Files
 - `*.yaml`
 - `*ignore`
 - `*rc` (YAML, JSON or JSONC)
+- `*.config.ts`
 
-Getting Started
----------------
+Installation
+------------
 
-With [node](http://nodejs.org) previously installed:
+Choose the install mode that fits your workflow:
 
-    npm install -g @zokugun/artifact
+- **Global CLI** (recommended when you apply artifacts across many repos):
 
+	```bash
+	npm install -g @zokugun/artifact
+	```
 
-Add the configuration packages:
+- **Project-local CLI** (handy for repo-specific automation):
 
-```
-artifact add @daiyam/lang-js @daiyam/lang-ts @daiyam/npm-ts
-```
+	```bash
+	npm install -D @zokugun/artifact
+	npx artifact --help
+	```
+
+Artifact requires [Node.js](http://nodejs.org) 18+.
+
+Quick Start
+-----------
+
+1. **Install the CLI** (globally or locally as shown in [Installation](#installation)).
+2. **Add the artifacts you want to compose**:
+
+	```bash
+	artifact add @daiyam/lang-js @daiyam/lang-ts @daiyam/npm @daiyam/npm-ts
+	```
+
+	The command above installs the following packages:
+	- [@daiyam/artifact-lang-js](https://github.com/daiyam/artifact-configs/tree/master/packages/lang-js)
+	- [@daiyam/artifact-lang-ts](https://github.com/daiyam/artifact-configs/tree/master/packages/lang-ts)
+	- [@daiyam/artifact-npm](https://github.com/daiyam/artifact-configs/tree/master/packages/npm)
+	- [@daiyam/artifact-npm-ts](https://github.com/daiyam/artifact-configs/tree/master/packages/npm-ts)
+
+3. **Inspect the git diff** created by the install. Keep overrides you like, discard unwanted changes, then rerun `artifact update` whenever upstream packages change.
+
+Artifacts published to npm must be prefixed with `artifact-`.
+
+Command Reference
+-----------------
+
+### `artifact add`
+
+Registers and applies one or more artifacts in the current project.
+
+- Syntax: `artifact add <artifact...> [options]`
+- Useful flags: `-v, --verbose` to show detailed install output.
+- Artifacts are stored in a `.artifactrc*` so subsequent updates know which packages to pull.
+
+`<artifact>` can be `name` or `name:variant`.
 
- With the previous command, `artifact` will pull the following packages:
-- [@daiyam/artifact-lang-js](https://github.com/daiyam/artifact-configs/tree/master/packages/lang-js)
-- [@daiyam/artifact-lang-ts](https://github.com/daiyam/artifact-configs/tree/master/packages/lang-ts)
-- [@daiyam/artifact-npm-ts](https://github.com/daiyam/artifact-configs/tree/master/packages/npm-ts)
+### `artifact list` / `artifact l`
 
-Like `yeoman`, a configuration package must be prefixed with `artifact-`.
+Shows the artifacts currently tracked in `.artifactrc*`, including versions and, when available, requested variants.
 
-Configuration Package
----------------------
+- Syntax: `artifact list`
+- Alias: `artifact l`
+- Output: prints each artifact as `name@version:variant`.
+
+### `artifact update` / `artifact up`
+
+Applies or refreshes the files provided by each installed artifact. Re-run it whenever upstream packages change.
+
+- Syntax: `artifact update [options]`
+- Alias: `artifact up`
+- Advanced: pass `-v, --verbose` for an execution trace of routes, variants, and branches.
+- Artifact authors can control how updates behave via `.artifactrc` files shipped inside their artifacts.
+
+#### Best practices
+
+Inspect the git diff after running to keep intentional overrides and drop unwanted changes.
+
+Core Concepts
+-------------
+
+The next sections dive deeper into the primitives that make `artifact` powerful: templating, variants, and branch overlays.
+
+Artifact Layout
+---------------
 
 The configuration/boilerplate files must be put inside the folder `configs`.
 
-For example, the package [@daiyam/artifact-lang-js](https://github.com/daiyam/artifact-configs/tree/master/packages/lang-js):
+For example, the package [@daiyam/artifact-npm-cli-ts](https://github.com/daiyam/artifact-configs/tree/master/packages/npm-cli-ts):
 
 ```
-artifact-configs/lang-js/
+npm-cli-ts/
   ├── configs/
-  │  ├── .commitlintrc.yml
-  │  ├── .editorconfig
-  │  ├── .lintstagedrc
-  │  ├── gitignore
+  │  ├── bin/
+  │  │  └── #[[package.json.name]]
+  │  ├── bin/
+  │  │  ├── command/
+  │  │  │  └── hello.ts
+  │  │  └── cli.ts
+  │  ├── npmignore                  // => .npmignore
   │  ├── package.json
-  │  └── ...
   ├── LICENSE
   ├── package.json
   └── README.md
 ```
 
-Update
-------
+Looking to build your own artifact? See [Authoring artifacts](docs/authoring-artifacts.md) for a step-by-step authoring guide.
 
-Update your configurations with the command:
+Templating
+----------
 
-```
-artifact update
-```
+During installs and updates, `artifact` runs every text file (and file name) through a template engine.
+Anywhere you place `#[[path/to/file.ext.property]]`, the engine:
+- loads that JSON/YAML file from the target project,
+- reads the property,
+- and substitutes the value—perfect for wiring the target's `package.json.name`, license, or runtime settings into generated files.
+
+You can also emit timestamps with helpers like `#[[date.utc]]`.
+
+Read [docs/templating.md](docs/templating.md) for full syntax.
+
+Variants
+--------
+
+Variants let an artifact expose multiple named flavors of its configuration (for example `14`, `20`, `stable`, `next`).
+Consumers can request a variant in their install config, while package authors declare defaults and remap keys via `.artifactrc`.
+
+See [docs/variants.md](docs/variants.md) for a full walkthrough, including examples of how to structure the `variants` folder.
+
+Branches
+--------
 
-It is **recommended** to review the changes and manually revert any bad changes.
+Branches are lightweight conditional overlays that live under `branches/[artifactName]` (or `[artifactName:variant]`).
+They activate only when the matching artifact (and optional variant) is present, letting you ship targeted tweaks like per-language `.nvmrc` files without duplicating whole packages.
 
-Furthermore, a configuration package can control how to apply an update via the file `.artifactrc`.
+Learn more in [docs/branches.md](docs/branches.md), including matching rules and best practices for layering branches after variants.
 
-Yeoman
-------
+More Documentation
+------------------
 
-`artifact` can be used in a yeoman generator. Ex: [@daiyam/generator-new-project](https://github.com/daiyam/generator-new-project)
+- [Authoring artifacts](docs/authoring-artifacts.md)
+- [Templating guide](docs/templating.md)
+- [Variants guide](docs/variants.md)
+- [Branches guide](docs/branches.md)
 
 Donations
 ---------

package/lib/cli.js

@@ -7,7 +7,9 @@ const commander_1 = require("commander");
 const package_json_1 = __importDefault(require("../package.json"));
 const commands_1 = require("./commands");
 const program = new commander_1.Command();
-program.version(package_json_1.default.version);
+program
+    .version(package_json_1.default.version, '-V, --version')
+    .description(package_json_1.default.description);
 program
     .command('add')
     .description('add an artifact to the current project')
@@ -16,7 +18,13 @@ program
     .action(commands_1.add);
 program
     .command('update')
-    .description('update the current project using the installed artifact')
+    .description('update the current project using the installed artifacts')
     .option('-v, --verbose', 'output more details')
+    .alias('up')
     .action(commands_1.update);
+program
+    .command('list')
+    .description('list the installed artifacts in the project')
+    .alias('l')
+    .action(commands_1.list);
 program.parse();

package/lib/commands/add.js

@@ -14,31 +14,34 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.add = void 0;
 const process_1 = __importDefault(require("process"));
+const ansi_colors_1 = require("ansi-colors");
 const npm_1 = __importDefault(require("npm"));
+const ora_1 = __importDefault(require("ora"));
 const pacote_1 = __importDefault(require("pacote"));
 const tempy_1 = __importDefault(require("tempy"));
-const config_1 = require("../config");
+const configs_1 = require("../configs");
 const steps_1 = require("../steps");
-const commonFlow = (0, steps_1.composeSteps)(steps_1.steps.readIncomingPackage, steps_1.steps.validateNotPresentPackage, steps_1.steps.readFiles, steps_1.steps.readEditorConfig, steps_1.steps.replaceTemplates, steps_1.steps.mergeTextFiles, steps_1.steps.insertFinalNewLine, steps_1.steps.applyFormatting, steps_1.steps.copyBinaryFiles, steps_1.steps.writeTextFiles);
-function expandSpec(spec) {
-    if (spec.includes('/')) {
-        const [scope, name] = spec.split('/');
-        if (name.startsWith('artifact-')) {
-            return spec;
-        }
-        else {
-            return `${scope}/artifact-${name}`;
-        }
-    }
-    else {
-        if (spec.startsWith('artifact-')) {
-            return spec;
-        }
-        else {
-            return `artifact-${spec}`;
-        }
-    }
-} // }}}
+const resolve_request_1 = require("../utils/resolve-request");
+const { mainFlow } = (0, steps_1.composeSteps)([
+    steps_1.steps.readIncomingPackage,
+    steps_1.steps.validateNotPresentPackage,
+    steps_1.steps.readIncomingConfig,
+    steps_1.steps.executeFirstBlock,
+], [
+    steps_1.steps.readIncomingConfig,
+    steps_1.steps.configureBranches,
+    steps_1.steps.configureInstallFileActions,
+    steps_1.steps.readFiles,
+    steps_1.steps.readEditorConfig,
+    steps_1.steps.replaceTemplates,
+    steps_1.steps.mergeTextFiles,
+    steps_1.steps.insertFinalNewLine,
+    steps_1.steps.applyFormatting,
+    steps_1.steps.copyBinaryFiles,
+    steps_1.steps.writeTextFiles,
+    steps_1.steps.removeFiles,
+    steps_1.steps.executeNextBlock,
+]);
 function add(specs, inputOptions) {
     var _a, _b, _c;
     return __awaiter(this, void 0, void 0, function* () {
@@ -50,12 +53,15 @@ function add(specs, inputOptions) {
             skip: (_b = inputOptions === null || inputOptions === void 0 ? void 0 : inputOptions.skip) !== null && _b !== void 0 ? _b : false,
             verbose: (_c = inputOptions === null || inputOptions === void 0 ? void 0 : inputOptions.verbose) !== null && _c !== void 0 ? _c : false,
         };
-        const [config, configStats] = yield (0, config_1.readConfig)(targetPath);
+        const { config, configStats } = yield (0, configs_1.readInstallConfig)(targetPath);
         for (const spec of specs) {
+            const request = (0, resolve_request_1.resolveRequest)(spec);
+            const spinner = (0, ora_1.default)(`${ansi_colors_1.cyan.bold(request.name)}`).start();
             const dir = tempy_1.default.directory();
-            const pkgResult = yield pacote_1.default.extract(expandSpec(spec), dir, { registry });
+            const pkgResult = yield pacote_1.default.extract(request.name, dir, { registry });
             if (!pkgResult.resolved) {
                 if (options.force || options.skip) {
+                    spinner.fail();
                     if (options.verbose) {
                         console.log(`The artifact '${spec}' couldn't be found, skipping...`);
                     }
@@ -65,26 +71,14 @@ function add(specs, inputOptions) {
                     throw new Error(pkgResult.from);
                 }
             }
-            const flowResult = yield commonFlow(targetPath, dir, config, options);
-            if (!flowResult) {
+            const flowResult = yield mainFlow(targetPath, dir, request, config, options);
+            if (!flowResult || !flowResult.result) {
+                spinner.succeed();
                 continue;
             }
-            const { name, version } = flowResult.incomingPackage;
-            let nf = true;
-            for (const artifact of config.artifacts) {
-                if (artifact.name === name) {
-                    artifact.version = version;
-                    nf = false;
-                    break;
-                }
-            }
-            if (nf) {
-                config.artifacts.push({
-                    name,
-                    version,
-                });
-            }
-            yield (0, config_1.writeConfig)(config, configStats, flowResult.formats, targetPath, options);
+            (0, configs_1.updateInstallConfig)(config, flowResult.result);
+            yield (0, configs_1.writeInstallConfig)(config, configStats, flowResult.formats, targetPath, options);
+            spinner.succeed();
         }
     });
 }

package/lib/commands/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.update = exports.add = void 0;
+exports.update = exports.list = exports.add = void 0;
 var add_1 = require("./add");
 Object.defineProperty(exports, "add", { enumerable: true, get: function () { return add_1.add; } });
+var list_1 = require("./list");
+Object.defineProperty(exports, "list", { enumerable: true, get: function () { return list_1.list; } });
 var update_1 = require("./update");
 Object.defineProperty(exports, "update", { enumerable: true, get: function () { return update_1.update; } });

package/lib/commands/list.js

@@ -0,0 +1,47 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.list = void 0;
+const process_1 = __importDefault(require("process"));
+const lodash_1 = require("lodash");
+const configs_1 = require("../configs");
+function formatVariant(artifact) {
+    var _a;
+    const variant = Array.isArray(artifact.requires) ? (_a = (0, lodash_1.last)(artifact.requires)) !== null && _a !== void 0 ? _a : '' : '';
+    if (variant.length > 0) {
+        return `:${variant}`;
+    }
+    else {
+        return '';
+    }
+}
+function list() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const targetPath = process_1.default.env.INIT_CWD;
+        const { config, configStats } = yield (0, configs_1.readInstallConfig)(targetPath);
+        const artifacts = Object.entries(config.artifacts);
+        if (artifacts.length === 0) {
+            console.log('No artifacts have been installed.');
+        }
+        else {
+            console.log(`List of installed artifacts (${configStats.name}):\n`);
+            for (const [name, artifact] of artifacts) {
+                const version = artifact.version ? `@${artifact.version}` : '';
+                console.log(`- ${name}${version}${formatVariant(artifact)}`);
+            }
+        }
+        console.log();
+    });
+}
+exports.list = list;

package/lib/commands/update.js

@@ -15,14 +15,34 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.update = void 0;
 const process_1 = __importDefault(require("process"));
 const ansi_colors_1 = require("ansi-colors");
+const lodash_1 = require("lodash");
 const npm_1 = __importDefault(require("npm"));
 const ora_1 = __importDefault(require("ora"));
 const pacote_1 = __importDefault(require("pacote"));
 const tempy_1 = __importDefault(require("tempy"));
-const config_1 = require("../config");
+const configs_1 = require("../configs");
 const steps_1 = require("../steps");
 const dev_null_1 = require("../utils/dev-null");
-const commonFlow = (0, steps_1.composeSteps)(steps_1.steps.readIncomingPackage, steps_1.steps.validateNewerPackage, steps_1.steps.readIncomingConfig, steps_1.steps.validateUpdatability, steps_1.steps.readFiles, steps_1.steps.readEditorConfig, steps_1.steps.mergeTextFiles, steps_1.steps.insertFinalNewLine, steps_1.steps.applyFormatting, steps_1.steps.copyBinaryFiles, steps_1.steps.writeTextFiles);
+const { mainFlow } = (0, steps_1.composeSteps)([
+    steps_1.steps.readIncomingPackage,
+    steps_1.steps.validateNewerPackage,
+    steps_1.steps.readIncomingConfig,
+    steps_1.steps.executeFirstBlock,
+], [
+    steps_1.steps.readIncomingConfig,
+    steps_1.steps.configureBranches,
+    steps_1.steps.configureUpdateFileActions,
+    steps_1.steps.readFiles,
+    steps_1.steps.readEditorConfig,
+    steps_1.steps.replaceTemplates,
+    steps_1.steps.mergeTextFiles,
+    steps_1.steps.insertFinalNewLine,
+    steps_1.steps.applyFormatting,
+    steps_1.steps.copyBinaryFiles,
+    steps_1.steps.writeTextFiles,
+    steps_1.steps.removeFiles,
+    steps_1.steps.executeNextBlock,
+]);
 function update(inputOptions) {
     var _a, _b;
     return __awaiter(this, void 0, void 0, function* () {
@@ -36,16 +56,16 @@ function update(inputOptions) {
             skip: false,
             verbose: (_b = inputOptions === null || inputOptions === void 0 ? void 0 : inputOptions.verbose) !== null && _b !== void 0 ? _b : false,
         };
-        const [config, configStats] = yield (0, config_1.readConfig)(targetPath);
-        for (const artifact of config.artifacts) {
-            const spinner = (0, ora_1.default)(`${ansi_colors_1.cyan.bold(artifact.name)}`).start();
+        const { config, configStats } = yield (0, configs_1.readInstallConfig)(targetPath);
+        for (const [name, artifact] of Object.entries(config.artifacts)) {
+            const spinner = (0, ora_1.default)(`${ansi_colors_1.cyan.bold(name)}`).start();
             const dir = tempy_1.default.directory();
-            const pkgResult = yield pacote_1.default.extract(artifact.name, dir, { registry });
+            const pkgResult = yield pacote_1.default.extract(name, dir, { registry });
             if (!pkgResult.resolved) {
                 if (options.force) {
                     spinner.fail();
                     if (options.verbose) {
-                        console.log(`The artifact '${artifact.name}' couldn't be found, skipping...`);
+                        console.log(`The artifact '${name}' couldn't be found, skipping...`);
                     }
                     continue;
                 }
@@ -53,19 +73,14 @@ function update(inputOptions) {
                     throw new Error(pkgResult.from);
                 }
             }
-            const flowResult = yield commonFlow(targetPath, dir, config, options);
-            if (!flowResult) {
+            const request = artifact.requires ? { name, variant: (0, lodash_1.last)(artifact.requires) } : { name };
+            const flowResult = yield mainFlow(targetPath, dir, request, config, options);
+            if (!flowResult || !flowResult.result) {
                 spinner.succeed();
                 continue;
             }
-            const { name, version } = flowResult.incomingPackage;
-            for (const artifact of config.artifacts) {
-                if (artifact.name === name) {
-                    artifact.version = version;
-                    break;
-                }
-            }
-            yield (0, config_1.writeConfig)(config, configStats, flowResult.formats, targetPath, options);
+            (0, configs_1.updateInstallConfig)(config, flowResult.result);
+            yield (0, configs_1.writeInstallConfig)(config, configStats, flowResult.formats, targetPath, options);
             spinner.succeed();
         }
     });

package/lib/compositors/compose.js

@@ -1,11 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compose = void 0;
-const has_1 = __importDefault(require("lodash/has"));
-const without_1 = __importDefault(require("lodash/without"));
+const lodash_1 = require("lodash");
 function apply(map, keys, current, incoming, result) {
     var _a, _b;
     if (keys.length === 0) {
@@ -15,8 +11,8 @@ function apply(map, keys, current, incoming, result) {
     for (const key of keys) {
         const currentValue = current[key];
         const transform = (_b = map[key]) !== null && _b !== void 0 ? _b : map.$$default;
-        if (!transform || !(0, has_1.default)(incoming, key) || ignores.includes(key)) {
-            if (currentValue !== undefined) {
+        if (!transform || !(0, lodash_1.has)(incoming, key) || ignores.includes(key)) {
+            if (!(0, lodash_1.isNil)(currentValue)) {
                 result[key] = currentValue;
             }
             continue;
@@ -31,15 +27,15 @@ function apply(map, keys, current, incoming, result) {
 }
 function compose(map) {
     return ({ current, incoming, filters }) => {
-        if (incoming === undefined) {
+        if ((0, lodash_1.isNil)(incoming)) {
             return current !== null && current !== void 0 ? current : {};
         }
-        if (current === undefined || typeof current !== typeof incoming) {
+        if ((0, lodash_1.isNil)(current) || typeof current !== typeof incoming) {
             return incoming;
         }
         const currentKeys = Object.keys(current);
         const incomingKeys = Object.keys(incoming);
-        const newKeys = (0, without_1.default)(incomingKeys, ...currentKeys);
+        const newKeys = (0, lodash_1.without)(incomingKeys, ...currentKeys);
         if (filters) {
             const result = Object.assign({}, current);
             apply(map, filters, current, incoming, result);

package/lib/configs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./install"), exports);
+__exportStar(require("./package"), exports);

package/lib/configs/install/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateInstallConfig = exports.writeInstallConfig = exports.readInstallConfig = void 0;
+var read_install_config_1 = require("./read-install-config");
+Object.defineProperty(exports, "readInstallConfig", { enumerable: true, get: function () { return read_install_config_1.readInstallConfig; } });
+var write_install_config_1 = require("./write-install-config");
+Object.defineProperty(exports, "writeInstallConfig", { enumerable: true, get: function () { return write_install_config_1.writeInstallConfig; } });
+var update_install_config_1 = require("./update-install-config");
+Object.defineProperty(exports, "updateInstallConfig", { enumerable: true, get: function () { return update_install_config_1.updateInstallConfig; } });