dotcom-tool-kit 3.5.0 → 4.0.0-beta.0

package/bin/run

@@ -1,22 +1,32 @@
 #!/usr/bin/env node
 
+/* eslint-disable @typescript-eslint/no-var-requires --
+ * this is raw CJS so the lint doesn't apply
+ */
+
 const argv = require('minimist')(process.argv.slice(2), {
   boolean: ['help', 'install', 'listPlugins'],
   '--': true
 })
 
-const { runTasks, showHelp, installHooks, listPlugins } = require('../lib')
 const { rootLogger, styles } = require('@dotcom-tool-kit/logger')
 
 async function main() {
   try {
     if (argv.install) {
+      const installHooks = require('../lib/install').default
       await installHooks(rootLogger)
     } else if (argv.listPlugins) {
+      const { listPlugins } = require('../lib')
       await listPlugins(rootLogger)
+    } else if (argv.printConfig) {
+      const { printConfig } = require('../lib')
+      await printConfig(rootLogger)
     } else if (argv.help || argv._.length === 0) {
+      const showHelp = require('../lib/help').default
       await showHelp(rootLogger, argv._)
     } else {
+      const { runTasks } = require('../lib')
       if (argv['--'].length > 0) {
         // The `--` in a command such as `dotcom-tool-kit test:staged --`
         // delineates between hooks and file patterns. For example, when the

package/lib/config/hash.d.ts

@@ -0,0 +1,6 @@
+import { ValidConfig } from '@dotcom-tool-kit/config';
+import { Logger } from 'winston';
+export declare function fileHash(path: string): Promise<string>;
+export declare function updateHashes(config: ValidConfig): Promise<void>;
+export declare function hasConfigChanged(logger: Logger, config: ValidConfig): Promise<boolean>;
+//# sourceMappingURL=hash.d.ts.map

package/lib/config/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/config/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAIrD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEhC,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAY5D;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrE;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAiB5F"}

package/lib/config/hash.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasConfigChanged = exports.updateHashes = exports.fileHash = void 0;
+const state_1 = require("@dotcom-tool-kit/state");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+async function fileHash(path) {
+    const hashFunc = (0, node_crypto_1.createHash)('sha512');
+    try {
+        hashFunc.update(await (0, promises_1.readFile)(path));
+        return hashFunc.digest('base64');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return 'n/a';
+        }
+        else {
+            throw error;
+        }
+    }
+}
+exports.fileHash = fileHash;
+async function updateHashes(config) {
+    const hashes = Object.fromEntries(await Promise.all(['.toolkitrc.yml', ...config.hookManagedFiles].map(async (path) => [path, await fileHash(path)])));
+    (0, state_1.writeState)('install', hashes);
+}
+exports.updateHashes = updateHashes;
+async function hasConfigChanged(logger, config) {
+    const hashes = (0, state_1.readState)('install');
+    if (!hashes) {
+        return true;
+    }
+    for (const path of ['.toolkitrc.yml', ...config.hookManagedFiles]) {
+        const newHash = await fileHash(path);
+        const prevHash = hashes[path];
+        if (newHash !== prevHash) {
+            logger.debug(`hash for path ${path} has changed, running hook checks`);
+            return true;
+        }
+    }
+    return false;
+}
+exports.hasConfigChanged = hasConfigChanged;

package/lib/config/validate-plugins.d.ts

@@ -0,0 +1,4 @@
+import type { RawConfig, ValidPluginsConfig } from '@dotcom-tool-kit/config';
+import { Validated } from '@dotcom-tool-kit/validated';
+export declare function validatePlugins(config: RawConfig): Validated<ValidPluginsConfig>;
+//# sourceMappingURL=validate-plugins.d.ts.map

package/lib/config/validate-plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-plugins.d.ts","sourceRoot":"","sources":["../../src/config/validate-plugins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAmB,MAAM,4BAA4B,CAAA;AAEvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAKhF"}

package/lib/config/validate-plugins.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePlugins = void 0;
+const validated_1 = require("@dotcom-tool-kit/validated");
+function validatePlugins(config) {
+    const validatedPlugins = (0, validated_1.reduceValidated)(Object.entries(config.plugins).map(([id, plugin]) => plugin.map((p) => [id, p])));
+    return validatedPlugins.map((plugins) => ({ ...config, plugins: Object.fromEntries(plugins) }));
+}
+exports.validatePlugins = validatePlugins;

package/lib/config.d.ts

@@ -1,59 +1,7 @@
 import type { Logger } from 'winston';
-import type { HookTask } from './hook';
-import { Conflict } from './conflict';
-import { TaskClass, Hook, Plugin, Validated } from '@dotcom-tool-kit/types';
-import { Options as SchemaOptions } from '@dotcom-tool-kit/types/lib/schema';
-export interface PluginOptions {
-    options: Record<string, unknown>;
-    plugin: Plugin;
-    forPlugin: Plugin;
-}
-export interface RawConfig {
-    root: string;
-    plugins: {
-        [id: string]: Validated<Plugin>;
-    };
-    resolvedPlugins: Set<Plugin>;
-    tasks: {
-        [id: string]: TaskClass | Conflict<TaskClass>;
-    };
-    hookTasks: {
-        [id: string]: HookTask | Conflict<HookTask>;
-    };
-    options: {
-        [id: string]: PluginOptions | Conflict<PluginOptions> | undefined;
-    };
-    hooks: {
-        [id: string]: Hook<unknown> | Conflict<Hook<unknown>>;
-    };
-}
-export type ValidPluginsConfig = Omit<RawConfig, 'plugins'> & {
-    plugins: {
-        [id: string]: Plugin;
-    };
-};
-export type ValidPluginOptions<Id extends keyof SchemaOptions> = Omit<PluginOptions, 'options'> & {
-    options: SchemaOptions[Id];
-};
-export type ValidOptions = {
-    [Id in keyof SchemaOptions]: ValidPluginOptions<Id>;
-};
-export type ValidConfig = Omit<ValidPluginsConfig, 'tasks' | 'hookTasks' | 'options' | 'hooks'> & {
-    tasks: {
-        [id: string]: TaskClass;
-    };
-    hookTasks: {
-        [id: string]: HookTask;
-    };
-    options: ValidOptions;
-    hooks: {
-        [id: string]: Hook<unknown>;
-    };
-};
+import { RawConfig, ValidConfig, ValidPluginsConfig } from '@dotcom-tool-kit/config';
 export declare const createConfig: () => RawConfig;
-export declare function validateConfig(config: ValidPluginsConfig, logger: Logger): ValidConfig;
-export declare function validatePlugins(config: RawConfig): Validated<ValidPluginsConfig>;
-export declare function checkInstall(config: ValidConfig): Promise<void>;
+export declare function validateConfig(config: ValidPluginsConfig): ValidConfig;
 export declare function loadConfig(logger: Logger, options?: {
     validate?: true;
 }): Promise<ValidConfig>;

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAUrC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAiBpF,eAAO,MAAM,YAAY,QAAO,SAgB9B,CAAA;AAEF,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,WAAW,CAiGtE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAC/F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA"}

package/lib/config.js

@@ -1,124 +1,90 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadConfig = exports.checkInstall = exports.validatePlugins = exports.validateConfig = exports.createConfig = void 0;
+exports.loadConfig = exports.validateConfig = exports.createConfig = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const plugin_1 = require("./plugin");
-const conflict_1 = require("./conflict");
+const conflict_1 = require("@dotcom-tool-kit/conflict");
 const error_1 = require("@dotcom-tool-kit/error");
-const types_1 = require("@dotcom-tool-kit/types");
-const schema_1 = require("@dotcom-tool-kit/types/lib/schema");
 const messages_1 = require("./messages");
+const validate_plugins_1 = require("./config/validate-plugins");
+const options_1 = require("./plugin/options");
 const coreRoot = path_1.default.resolve(__dirname, '../');
 const createConfig = () => ({
     root: coreRoot,
     plugins: {},
-    resolvedPlugins: new Set(),
+    resolutionTrackers: {
+        resolvedPluginOptions: new Set(),
+        substitutedPlugins: new Set(),
+        resolvedPlugins: new Set(),
+        reducedInstallationPlugins: new Set()
+    },
     tasks: {},
-    hookTasks: {},
-    options: {},
-    hooks: {}
+    commandTasks: {},
+    pluginOptions: {},
+    taskOptions: {},
+    hooks: {},
+    inits: [],
+    hookManagedFiles: new Set()
 });
 exports.createConfig = createConfig;
-async function asyncFilter(items, predicate) {
-    const results = await Promise.all(items.map(async (item) => ({ item, keep: await predicate(item) })));
-    return results.filter(({ keep }) => keep).map(({ item }) => item);
-}
-function validateConfig(config, logger) {
+function validateConfig(config) {
     const validConfig = config;
-    const hookTaskConflicts = (0, conflict_1.findConflicts)(Object.values(config.hookTasks));
-    const hookConflicts = (0, conflict_1.findConflicts)(Object.values(config.hooks));
-    const taskConflicts = (0, conflict_1.findConflicts)(Object.values(config.tasks));
-    const optionConflicts = (0, conflict_1.findConflicts)(Object.values(config.options));
-    const definedHookTaskConflicts = hookTaskConflicts.filter((conflict) => {
+    const commandTaskConflicts = (0, conflict_1.findConflicts)(Object.values(config.commandTasks));
+    const hookConflicts = (0, conflict_1.findConflictingEntries)(config.hooks);
+    const taskConflicts = (0, conflict_1.findConflictingEntries)(config.tasks);
+    const pluginOptionConflicts = (0, conflict_1.findConflicts)(Object.values(config.pluginOptions));
+    const taskOptionConflicts = (0, conflict_1.findConflicts)(Object.values(config.taskOptions));
+    const definedCommandTaskConflicts = commandTaskConflicts.filter((conflict) => {
         return conflict.conflicting[0].id in config.hooks;
     });
     let shouldThrow = false;
-    const error = new error_1.ToolKitConflictError('There are problems with your Tool Kit configuration.', hookTaskConflicts.map((conflict) => ({
-        hook: conflict.conflicting[0].id,
-        conflictingTasks: conflict.conflicting.flatMap((hook) => hook.tasks.map((task) => ({ task, plugin: hook.plugin.id })))
+    const error = new error_1.ToolKitConflictError('There are problems with your Tool Kit configuration.', commandTaskConflicts.map((conflict) => ({
+        command: conflict.conflicting[0].id,
+        conflictingTasks: conflict.conflicting.flatMap((command) => command.tasks.map((task) => ({ task: task.task, plugin: command.plugin.id })))
     })));
     error.details = '';
     if (hookConflicts.length > 0 ||
-        definedHookTaskConflicts.length > 0 ||
+        definedCommandTaskConflicts.length > 0 ||
         taskConflicts.length > 0 ||
-        optionConflicts.length > 0) {
+        pluginOptionConflicts.length > 0 ||
+        taskOptionConflicts.length > 0) {
         shouldThrow = true;
         if (hookConflicts.length) {
             error.details += (0, messages_1.formatHookConflicts)(hookConflicts);
         }
-        if (definedHookTaskConflicts.length) {
-            error.details += (0, messages_1.formatHookTaskConflicts)(definedHookTaskConflicts);
+        if (definedCommandTaskConflicts.length) {
+            error.details += (0, messages_1.formatCommandTaskConflicts)(definedCommandTaskConflicts);
         }
         if (taskConflicts.length) {
             error.details += (0, messages_1.formatTaskConflicts)(taskConflicts);
         }
-        if (optionConflicts.length) {
-            error.details += (0, messages_1.formatOptionConflicts)(optionConflicts);
-        }
-    }
-    const configuredHookTasks = (0, conflict_1.withoutConflicts)(Object.values(config.hookTasks));
-    const definedHookIds = new Set(Object.keys(config.hooks));
-    const undefinedHookTasks = configuredHookTasks.filter((hookTask) => {
-        // we only care about undefined hooks that were configured by the app, not default config from plugins
-        const fromApp = hookTask.plugin.root === process.cwd();
-        const hookDefined = definedHookIds.has(hookTask.id);
-        return fromApp && !hookDefined;
-    });
-    if (undefinedHookTasks.length > 0) {
-        shouldThrow = true;
-        error.details += (0, messages_1.formatUndefinedHookTasks)(undefinedHookTasks, Array.from(definedHookIds));
-    }
-    const invalidOptions = [];
-    for (const [id, plugin] of Object.entries(config.plugins)) {
-        const pluginId = id;
-        const pluginOptions = config.options[pluginId];
-        if (pluginOptions && (0, conflict_1.isConflict)(pluginOptions)) {
-            continue;
-        }
-        const pluginSchema = schema_1.Schemas[pluginId];
-        if (!pluginSchema) {
-            logger.silly(`skipping validation of ${pluginId} plugin as no schema can be found`);
-            continue;
-        }
-        const result = pluginSchema.safeParse(pluginOptions?.options ?? {});
-        if (result.success) {
-            // Set up options entry for plugins that don't have options specified
-            // explicitly. They could still have default options that are set by zod.
-            if (!pluginOptions) {
-                // TypeScript struggles with this type as it sees one side as
-                // `Foo<a | b | c>` and the other as `Foo<a> | Foo<b> | Foo<c>` for
-                // some reason (something to do with the record indexing) and it can't
-                // unify them. But they are equivalent so let's force it with a cast.
-                config.options[pluginId] = {
-                    options: result.data,
-                    plugin: config.plugins['app root'],
-                    forPlugin: plugin
-                }; // eslint-disable-line @typescript-eslint/no-explicit-any
-            }
-            else {
-                pluginOptions.options = result.data;
-            }
+        if (pluginOptionConflicts.length) {
+            error.details += (0, messages_1.formatPluginOptionConflicts)(pluginOptionConflicts);
         }
-        else {
-            invalidOptions.push([id, result.error]);
+        if (taskOptionConflicts.length) {
+            error.details += (0, messages_1.formatTaskOptionConflicts)(taskOptionConflicts);
         }
     }
-    if (invalidOptions.length > 0) {
+    const unusedPluginOptions = Object.entries(config.pluginOptions)
+        .filter(([, option]) => option && !(0, conflict_1.isConflict)(option) && !option.forPlugin && option.plugin.root === process.cwd())
+        .map(([id]) => id);
+    if (unusedPluginOptions.length > 0) {
         shouldThrow = true;
-        error.details += (0, messages_1.formatInvalidOptions)(invalidOptions);
+        error.details += (0, messages_1.formatUnusedPluginOptions)(unusedPluginOptions, Object.keys(config.plugins));
     }
-    const unusedOptions = Object.entries(config.options)
-        .filter(([, option]) => option && !(0, conflict_1.isConflict)(option) && !option.forPlugin && option.plugin.root === process.cwd())
+    const unusedTaskOptions = Object.entries(config.taskOptions)
+        .filter(([, option]) => option && !(0, conflict_1.isConflict)(option) && !option.task && option.plugin.root === process.cwd())
         .map(([id]) => id);
-    if (unusedOptions.length > 0) {
+    if (unusedTaskOptions.length > 0) {
         shouldThrow = true;
-        error.details += (0, messages_1.formatUnusedOptions)(unusedOptions, Object.keys(config.plugins));
+        error.details += (0, messages_1.formatUnusedTaskOptions)(unusedTaskOptions, Object.keys(config.tasks));
     }
-    const missingTasks = configuredHookTasks
-        .map((hook) => ({
-        hook,
-        tasks: hook.tasks.filter((id) => !config.tasks[id])
+    const configuredCommandTasks = (0, conflict_1.withoutConflicts)(Object.values(config.commandTasks));
+    const missingTasks = configuredCommandTasks
+        .map((command) => ({
+        command,
+        tasks: command.tasks.filter((task) => !config.tasks[task.task])
     }))
         .filter(({ tasks }) => tasks.length > 0);
     if (missingTasks.length > 0) {
@@ -131,42 +97,25 @@ function validateConfig(config, logger) {
     return validConfig;
 }
 exports.validateConfig = validateConfig;
-function validatePlugins(config) {
-    const validatedPlugins = (0, types_1.reduceValidated)(Object.entries(config.plugins).map(([id, plugin]) => (0, types_1.mapValidated)(plugin, (p) => [id, p])));
-    return (0, types_1.mapValidated)(validatedPlugins, (plugins) => ({ ...config, plugins: Object.fromEntries(plugins) }));
-}
-exports.validatePlugins = validatePlugins;
-async function checkInstall(config) {
-    const definedHooks = (0, conflict_1.withoutConflicts)(Object.values(config.hooks));
-    const uninstalledHooks = await asyncFilter(definedHooks, async (hook) => {
-        return !(await hook.check());
-    });
-    if (uninstalledHooks.length > 0) {
-        const error = new error_1.ToolKitError('There are problems with your Tool Kit installation.');
-        error.details = (0, messages_1.formatUninstalledHooks)(uninstalledHooks);
-        throw error;
-    }
-}
-exports.checkInstall = checkInstall;
 async function loadConfig(logger, { validate = true } = {}) {
     const config = (0, exports.createConfig)();
     // start loading config and child plugins, starting from the consumer app directory
     const rootPlugin = await (0, plugin_1.loadPlugin)('app root', config, logger);
-    if (!rootPlugin.valid) {
-        const error = new error_1.ToolKitError('root plugin was not valid!');
-        error.details = rootPlugin.reasons.join('\n\n');
-        throw error;
-    }
-    const validRootPlugin = rootPlugin.value;
-    const validatedPluginConfig = validatePlugins(config);
-    if (!validatedPluginConfig.valid) {
-        const error = new error_1.ToolKitError('config was not valid!');
-        error.details = validatedPluginConfig.reasons.join('\n\n');
+    const validRootPlugin = rootPlugin.unwrap('root plugin was not valid!');
+    const validatedPluginConfig = (0, validate_plugins_1.validatePlugins)(config);
+    const validPluginConfig = validatedPluginConfig.unwrap('config was not valid!');
+    // collate root plugin and descendent hooks, options etc into config
+    // start with options so we can substitute resolved values into other parts
+    // of the config
+    (0, plugin_1.resolvePluginOptions)(validRootPlugin, validPluginConfig);
+    const invalidOptions = (0, options_1.validatePluginOptions)(logger, validPluginConfig);
+    if (invalidOptions.length > 0 && validate) {
+        const error = new error_1.ToolKitError('There are problems with your plugin options.');
+        error.details = (0, messages_1.formatInvalidOptions)(invalidOptions);
         throw error;
     }
-    const validPluginConfig = validatedPluginConfig.value;
-    // collate root plugin and descendent hooks, options etc into config
+    (0, options_1.substituteOptionTags)(validRootPlugin, validPluginConfig);
     (0, plugin_1.resolvePlugin)(validRootPlugin, validPluginConfig, logger);
-    return validate ? validateConfig(validPluginConfig, logger) : config;
+    return validate ? validateConfig(validPluginConfig) : config;
 }
 exports.loadConfig = loadConfig;

package/lib/fetch.d.ts

@@ -0,0 +1,2 @@
+export declare const shouldDisableNativeFetch: () => boolean;
+//# sourceMappingURL=fetch.d.ts.map

package/lib/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,wBAAwB,QAAO,OAY3C,CAAA"}

package/lib/fetch.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldDisableNativeFetch = void 0;
+const options_1 = require("@dotcom-tool-kit/options");
+// function that plugins can check if they need to implement their own logic to
+// disable Node 18's native fetch
+const shouldDisableNativeFetch = () => {
+    // disable Node 18's native fetch if the Node runtime supports it (older
+    // runtimes don't support the flag, implying they also don't use native
+    // fetch) and the user hasn't opted out of the behaviour
+    return (
+    /* eslint-disable-next-line @typescript-eslint/no-non-null-assertion --
+     * the root plugin has default options and it always exists so is always
+     * defined
+     **/
+    !(0, options_1.getOptions)('app root').allowNativeFetch &&
+        process.allowedNodeEnvironmentFlags.has('--no-experimental-fetch'));
+};
+exports.shouldDisableNativeFetch = shouldDisableNativeFetch;

package/lib/help.d.ts

@@ -1,3 +1,3 @@
 import type { Logger } from 'winston';
-export default function showHelp(logger: Logger, hooks: string[]): Promise<void>;
+export default function showHelp(logger: Logger, commands: string[]): Promise<void>;
 //# sourceMappingURL=help.d.ts.map

package/lib/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC,wBAA8B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiErF"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AA4ErC,wBAA8B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CxF"}

package/lib/help.js

@@ -1,54 +1,87 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
 const config_1 = require("./config");
 const options_1 = require("@dotcom-tool-kit/options");
 const logger_1 = require("@dotcom-tool-kit/logger");
-async function showHelp(logger, hooks) {
+const yaml_1 = tslib_1.__importDefault(require("yaml"));
+const endent_1 = tslib_1.__importDefault(require("endent"));
+const toolKitIntro = logger_1.styles.box((0, endent_1.default) `
+    Tool Kit is modern, maintainable & modular developer tooling for FT.com projects.
+    ${logger_1.styles.URL('https://github.com/financial-times/dotcom-tool-kit')}
+  `, { title: `🧰 ${logger_1.styles.title(`welcome to ${logger_1.styles.app('Tool Kit')}!`)}` });
+const formatTask = ({ task, options }) => (0, endent_1.default) `
+  ${logger_1.styles.task(task)}${Object.keys(options).length > 0
+    ? ` ${logger_1.styles.dim('with options:')}
+    ${yaml_1.default.stringify(options).trim()}`
+    : ''}`;
+const formatCommandTasks = (config, commands) => logger_1.styles.box((0, endent_1.default) `
+  ${logger_1.styles.help(`${logger_1.styles.command('commands')} run Tool Kit tasks with ${logger_1.styles.code('npx dotcom-tool-kit $command')}, or via configuration installed by hooks in your repository.`)}
+  ${commands
+    .filter((command) => config.commandTasks[command])
+    .map((command) => formatCommandTask(command, config.commandTasks[command]))
+    .join('\n')}
+
+`, {
+    title: '⛭ ' + logger_1.styles.title('available commands')
+});
+const formatCommandTask = (command, { tasks, plugin }) => (0, endent_1.default) `
+  ${logger_1.styles.groupHeader(logger_1.styles.command(command))}
+  ${tasks.length
+    ? (0, endent_1.default) `
+        ${logger_1.styles.info(`${plugin.id !== 'app root' ? `from plugin ${logger_1.styles.plugin(plugin.id)}. ` : ''}runs tasks:`)}
+        ${tasks.map((task) => `  - ${formatTask(task)}`).join('\n')}
+      `
+    : logger_1.styles.warning(`no tasks configured to run for ${logger_1.styles.command(command)}`)}
+`;
+const formatHooks = (config) => logger_1.styles.box((0, endent_1.default) `
+  ${logger_1.styles.help(`${logger_1.styles.hook('hooks')} manage configuration files in your repository, for running Tool Kit commands.`)}
+  ${Object.entries(config.hooks)
+    .map(([hook, entryPoint]) => {
+    const managesFiles = entryPoint.plugin.rcFile?.installs[hook].managesFiles ?? [];
+    return (0, endent_1.default) `
+        ${logger_1.styles.groupHeader(logger_1.styles.hook(hook))}
+        ${logger_1.styles.info((0, endent_1.default) `
+          from plugin ${logger_1.styles.plugin(entryPoint.plugin.id)}
+        `)}
+        ${managesFiles.length ? 'manages files:' : ''}
+        ${managesFiles.map((file) => `  - ${logger_1.styles.filepath(file)}`).join('\n')}
+      `;
+})
+    .join('\n')}
+`, { title: logger_1.styles.title('🎣 installed hooks') });
+async function showHelp(logger, commands) {
     const config = await (0, config_1.loadConfig)(logger);
-    if (hooks.length === 0) {
-        hooks = Object.keys(config.hooks).sort();
+    const printAllCommands = commands.length === 0;
+    if (printAllCommands) {
+        commands = Object.keys(config.commandTasks).sort();
     }
-    for (const pluginOptions of Object.values(config.options)) {
+    for (const pluginOptions of Object.values(config.pluginOptions)) {
         if (pluginOptions.forPlugin) {
             (0, options_1.setOptions)(pluginOptions.forPlugin.id, pluginOptions.options);
         }
     }
-    await (0, config_1.checkInstall)(config);
-    const missingHooks = hooks.filter((hook) => !config.hooks[hook]);
-    logger.info(`
-🧰 ${logger_1.styles.title(`welcome to ${logger_1.styles.app('Tool Kit')}!`)}
-
-Tool Kit is modern, maintainable & modular developer tooling for FT.com projects.
-
-${logger_1.styles.URL('https://github.com/financial-times/dotcom-tool-kit')}
-
-${logger_1.styles.ruler()}
-${Object.keys(config.hooks).length === 0
-        ? `there are no hooks available. you'll need to install plugins that define hooks to be able to run Tool Kit tasks.`
-        : logger_1.styles.dim(hooks.length === 0
-            ? 'available hooks'
-            : `help for ${hooks.length - missingHooks.length} ${hooks.length - missingHooks.length > 1 ? 'hooks' : 'hook'}`)}:
-`);
-    for (const hook of hooks) {
-        const Hook = config.hooks[hook];
-        if (Hook) {
-            const tasks = config.hookTasks[hook];
-            /* eslint-disable @typescript-eslint/no-explicit-any -- Object.constructor does not consider static properties */
-            logger.info(`${logger_1.styles.heading(hook)}
-${Hook.constructor.description ? Hook.constructor.description + '\n' : ''}
-${tasks && tasks.tasks.length
-                ? `runs ${tasks.tasks.length > 1 ? 'these tasks' : 'this task'}:
-${tasks.tasks
-                    .map((task) => `- ${logger_1.styles.task(task)} ${logger_1.styles.dim(config.tasks[task].description)}`)
-                    .join('\n')}`
-                : logger_1.styles.dim('no tasks configured to run on this hook.')}
-${logger_1.styles.ruler()}
-`);
-            /*eslint-enable @typescript-eslint/no-explicit-any */
-        }
+    logger.info(toolKitIntro);
+    const definedCommands = commands.filter((command) => config.commandTasks[command]);
+    const missingCommands = commands.filter((command) => !config.commandTasks[command]);
+    if (printAllCommands && Object.keys(config.hooks).length) {
+        logger.info(formatHooks(config));
+    }
+    if (Object.keys(config.commandTasks).length === 0) {
+        logger.warn(logger_1.styles.warning((0, endent_1.default) `
+          there are no commands available. add some commands by defining them in your ${logger_1.styles.filepath('.toolkitrc.yml')} or installing plugins that define commands.
+        `));
+    }
+    else if (definedCommands.length > 0) {
+        logger.info(formatCommandTasks(config, definedCommands));
     }
-    if (missingHooks.length) {
-        logger.warn(`no such ${missingHooks.length > 1 ? 'hooks' : 'hook'} ${missingHooks.map(logger_1.styles.hook).join(', ')}`);
+    else if (missingCommands.length) {
+        logger.warn(logger_1.styles.error((0, endent_1.default) `
+      no such ${missingCommands.length > 1 ? 'commands' : 'command'} ${missingCommands
+            .map((id) => logger_1.styles.command(id))
+            .join(', ')}
+    `));
     }
+    logger.info('\n');
 }
 exports.default = showHelp;

package/lib/index.d.ts

@@ -1,7 +1,6 @@
 import type { Logger } from 'winston';
-export declare const shouldDisableNativeFetch: () => boolean;
-export declare function runTasks(logger: Logger, hooks: string[], files?: string[]): Promise<void>;
+export { runTasks } from './tasks';
+export { shouldDisableNativeFetch } from './fetch';
 export declare function listPlugins(logger: Logger): Promise<void>;
-export { default as showHelp } from './help';
-export { default as installHooks } from './install';
+export declare function printConfig(logger: Logger): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAWrC,eAAO,MAAM,wBAAwB,QAAO,OAY3C,CAAA;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyF/F;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/D;AAED,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAC5C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAIrC,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAClC,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAElD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/D;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/D"}