@dotcom-tool-kit/base 4.0.0-beta.0

package/lib/base.d.ts

@@ -0,0 +1,11 @@
+import { typeSymbol } from './symbols';
+import { Validated } from '@dotcom-tool-kit/validated';
+export declare abstract class Base {
+    static version: string;
+    version: string;
+    static get [typeSymbol](): symbol;
+    get [typeSymbol](): symbol;
+    static is<T extends Base>(objectToCheck: any): objectToCheck is T;
+    static isCompatible<T extends Base>(objectToCheck: unknown): Validated<T>;
+}
+//# sourceMappingURL=base.d.ts.map

package/lib/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,UAAU,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,SAAS,EAAkB,MAAM,4BAA4B,CAAA;AAOtE,8BAAsB,IAAI;IACxB,MAAM,CAAC,OAAO,SAAU;IACxB,OAAO,SAAU;IAEjB,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,MAAM,CAEhC;IAED,IAAI,CAAC,UAAU,CAAC,IAAI,MAAM,CAEzB;IAGD,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,IAAI,EAAE,aAAa,EAAE,GAAG,GAAG,aAAa,IAAI,CAAC;IAIjE,MAAM,CAAC,YAAY,CAAC,CAAC,SAAS,IAAI,EAAE,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;CA6B1E"}

package/lib/base.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Base = void 0;
+const tslib_1 = require("tslib");
+const logger_1 = require("@dotcom-tool-kit/logger");
+const path_1 = tslib_1.__importDefault(require("path"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const symbols_1 = require("./symbols");
+const validated_1 = require("@dotcom-tool-kit/validated");
+const semver_1 = tslib_1.__importDefault(require("semver"));
+const packageJsonPath = path_1.default.resolve(__dirname, '../package.json');
+const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf8'));
+const version = packageJson.version;
+class Base {
+    constructor() {
+        this.version = version;
+    }
+    static get [symbols_1.typeSymbol]() {
+        return symbols_1.baseSymbol;
+    }
+    get [symbols_1.typeSymbol]() {
+        return symbols_1.baseSymbol;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static is(objectToCheck) {
+        return objectToCheck[symbols_1.typeSymbol] === this[symbols_1.typeSymbol];
+    }
+    static isCompatible(objectToCheck) {
+        if (!this.is(objectToCheck)) {
+            return (0, validated_1.invalid)([
+                `${logger_1.styles.plugin('@dotcom-tool-kit/base')} type symbol is missing, make sure that this object derives from the ${logger_1.styles.code('Task')} or ${logger_1.styles.code('Hook')} class defined by the plugin`
+            ]);
+        }
+        // an 'objectToCheck' from a plugin is compatible with this CLI if its
+        // version is semver-compatible with the @dotcom-tool-kit/base included by
+        // the CLI (which is what's calling this). so, prepend ^ to our version,
+        // and check our version satisfies that.
+        // this lets e.g. a CLI that includes types@2.2.0 load any plugin
+        // that depends on any higher minor version of types.
+        const range = `^${this.version}`;
+        if (semver_1.default.satisfies(objectToCheck.version, range)) {
+            return (0, validated_1.valid)(objectToCheck);
+        }
+        else {
+            return (0, validated_1.invalid)([
+                `object is from an outdated version of ${logger_1.styles.plugin('@dotcom-tool-kit/base')}, make sure you're using at least version ${logger_1.styles.heading(this.version)} of the plugin`
+            ]);
+        }
+    }
+}
+exports.Base = Base;
+Base.version = version;

package/lib/hook.d.ts

@@ -0,0 +1,31 @@
+import type { Logger } from 'winston';
+import { Base } from './base';
+import { typeSymbol } from './symbols';
+import type { z } from 'zod';
+import type { Plugin } from '@dotcom-tool-kit/plugin';
+import { Conflict } from '@dotcom-tool-kit/conflict';
+export interface HookInstallation<Options = Record<string, unknown>> {
+    options: Options;
+    plugin: Plugin;
+    forHook: string;
+    hookConstructor: HookConstructor;
+}
+export declare abstract class Hook<Options extends z.ZodTypeAny = z.ZodTypeAny, State = void> extends Base {
+    id: string;
+    options: z.output<Options>;
+    logger: Logger;
+    installGroup?: string;
+    static get [typeSymbol](): symbol;
+    get [typeSymbol](): symbol;
+    static mergeChildInstallations(plugin: Plugin, childInstallations: (HookInstallation | Conflict<HookInstallation>)[]): (HookInstallation | Conflict<HookInstallation>)[];
+    static overrideChildInstallations(plugin: Plugin, parentInstallation: HookInstallation, _childInstallations: (HookInstallation | Conflict<HookInstallation>)[]): (HookInstallation | Conflict<HookInstallation>)[];
+    constructor(logger: Logger, id: string, options: z.output<Options>);
+    abstract isInstalled(): Promise<boolean>;
+    abstract install(state?: State): Promise<State>;
+    commitInstall(_state: State): Promise<void>;
+}
+export type HookConstructor = {
+    new (logger: Logger, id: string, options: z.output<z.ZodTypeAny>): Hook<z.ZodTypeAny, unknown>;
+};
+export type HookClass = HookConstructor & typeof Hook;
+//# sourceMappingURL=hook.d.ts.map

package/lib/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAc,UAAU,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAc,MAAM,2BAA2B,CAAA;AAEhE,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,eAAe,CAAA;CACjC;AAED,8BAAsB,IAAI,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAE,SAAQ,IAAI;IAsC7D,EAAE,EAAE,MAAM;IAAS,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IArChF,MAAM,EAAE,MAAM,CAAA;IAKd,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,MAAM,CAEhC;IAED,IAAI,CAAC,UAAU,CAAC,IAAI,MAAM,CAEzB;IAED,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,GACpE,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE;IAWpD,MAAM,CAAC,0BAA0B,CAC/B,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,gBAAgB,EACpC,mBAAmB,EAAE,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,GACrE,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE;gBAIxC,MAAM,EAAE,MAAM,EAAS,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IAKhF,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IACzC,aAAa,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlD;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;CAC/F,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,OAAO,IAAI,CAAA"}

package/lib/hook.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hook = void 0;
+const base_1 = require("./base");
+const symbols_1 = require("./symbols");
+const conflict_1 = require("@dotcom-tool-kit/conflict");
+class Hook extends base_1.Base {
+    static get [symbols_1.typeSymbol]() {
+        return symbols_1.hookSymbol;
+    }
+    get [symbols_1.typeSymbol]() {
+        return symbols_1.hookSymbol;
+    }
+    static mergeChildInstallations(plugin, childInstallations) {
+        return [
+            {
+                plugin,
+                conflicting: childInstallations.flatMap((installation) => (0, conflict_1.isConflict)(installation) ? installation.conflicting : installation)
+            }
+        ];
+    }
+    static overrideChildInstallations(plugin, parentInstallation, _childInstallations) {
+        return [parentInstallation];
+    }
+    constructor(logger, id, options) {
+        super();
+        this.id = id;
+        this.options = options;
+        this.logger = logger.child({ hook: this.constructor.name });
+    }
+    async commitInstall(_state) {
+        return;
+    }
+}
+exports.Hook = Hook;

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from './base';
+export * from './hook';
+export * from './init';
+export * from './task';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA"}

package/lib/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./base"), exports);
+tslib_1.__exportStar(require("./hook"), exports);
+tslib_1.__exportStar(require("./init"), exports);
+tslib_1.__exportStar(require("./task"), exports);

package/lib/init.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from 'winston';
+import { typeSymbol } from './symbols';
+import { Base } from './base';
+export declare abstract class Init extends Base {
+    logger: Logger;
+    constructor(logger: Logger);
+    static get [typeSymbol](): symbol;
+    get [typeSymbol](): symbol;
+    abstract init(): Promise<void>;
+}
+export type InitConstructor = {
+    new (logger: Logger): Init;
+};
+export type InitClass = InitConstructor & typeof Init;
+//# sourceMappingURL=init.d.ts.map

package/lib/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAc,UAAU,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAE7B,8BAAsB,IAAK,SAAQ,IAAI;IACrC,MAAM,EAAE,MAAM,CAAA;gBAEF,MAAM,EAAE,MAAM;IAK1B,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,MAAM,CAEhC;IAED,IAAI,CAAC,UAAU,CAAC,IAAI,MAAM,CAEzB;IAED,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAC/B;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,OAAO,IAAI,CAAA"}

package/lib/init.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Init = void 0;
+const symbols_1 = require("./symbols");
+const base_1 = require("./base");
+class Init extends base_1.Base {
+    constructor(logger) {
+        super();
+        this.logger = logger.child({ hook: this.constructor.name });
+    }
+    static get [symbols_1.typeSymbol]() {
+        return symbols_1.initSymbol;
+    }
+    get [symbols_1.typeSymbol]() {
+        return symbols_1.initSymbol;
+    }
+}
+exports.Init = Init;

package/lib/symbols.d.ts

@@ -0,0 +1,6 @@
+export declare const typeSymbol: unique symbol;
+export declare const baseSymbol: unique symbol;
+export declare const taskSymbol: unique symbol;
+export declare const hookSymbol: unique symbol;
+export declare const initSymbol: unique symbol;
+//# sourceMappingURL=symbols.d.ts.map

package/lib/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../src/symbols.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,UAAU,eAAuC,CAAA;AAG9D,eAAO,MAAM,UAAU,eAA4C,CAAA;AACnE,eAAO,MAAM,UAAU,eAA4C,CAAA;AACnE,eAAO,MAAM,UAAU,eAA4C,CAAA;AACnE,eAAO,MAAM,UAAU,eAA4C,CAAA"}

package/lib/symbols.js

@@ -0,0 +1,14 @@
+"use strict";
+// uses Symbol.for, not Symbol, so that they're compatible across different
+// @dotcom-tool-kit/base instances
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initSymbol = exports.hookSymbol = exports.taskSymbol = exports.baseSymbol = exports.typeSymbol = void 0;
+// TODO these symbols say '@dotcom-tool-kit/types' because they used to live
+// in that package. changing that would be a backwards compatibility nightmare
+// used as the name for the property we use to identify classes
+exports.typeSymbol = Symbol.for('@dotcom-tool-kit/types');
+// used to identify the Base, Task and Hook classes
+exports.baseSymbol = Symbol.for('@dotcom-tool-kit/types/base');
+exports.taskSymbol = Symbol.for('@dotcom-tool-kit/types/task');
+exports.hookSymbol = Symbol.for('@dotcom-tool-kit/types/hook');
+exports.initSymbol = Symbol.for('@dotcom-tool-kit/types/init');

package/lib/task.d.ts

@@ -0,0 +1,27 @@
+import type { z } from 'zod';
+import { Base } from './base';
+import { typeSymbol } from './symbols';
+import type { Logger } from 'winston';
+type Default<T, D> = T extends undefined ? D : T;
+export declare abstract class Task<Options extends {
+    plugin?: z.ZodTypeAny;
+    task?: z.ZodTypeAny;
+} = Record<never, never>> extends Base {
+    id: string;
+    pluginOptions: z.output<Default<Options['plugin'], z.ZodObject<Record<string, never>>>>;
+    options: z.output<Default<Options['task'], z.ZodObject<Record<string, never>>>>;
+    static get [typeSymbol](): symbol;
+    get [typeSymbol](): symbol;
+    logger: Logger;
+    constructor(logger: Logger, id: string, pluginOptions: z.output<Default<Options['plugin'], z.ZodObject<Record<string, never>>>>, options: z.output<Default<Options['task'], z.ZodObject<Record<string, never>>>>);
+    abstract run(files?: string[]): Promise<void>;
+}
+export type TaskConstructor = {
+    new <O extends {
+        plugin: z.ZodTypeAny;
+        task: z.ZodTypeAny;
+    }>(logger: Logger, id: string, pluginOptions: Partial<z.infer<O['plugin']>>, options: Partial<z.infer<O['task']>>): Task<O>;
+};
+export type TaskClass = TaskConstructor & typeof Task;
+export {};
+//# sourceMappingURL=task.d.ts.map

package/lib/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAc,UAAU,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,CAAC,GAAG,CAAC,CAAA;AAEhD,8BAAsB,IAAI,CACxB,OAAO,SAAS;IACd,MAAM,CAAC,EAAE,CAAC,CAAC,UAAU,CAAA;IACrB,IAAI,CAAC,EAAE,CAAC,CAAC,UAAU,CAAA;CACpB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACxB,SAAQ,IAAI;IAaH,EAAE,EAAE,MAAM;IACV,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACvF,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAdxF,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,MAAM,CAEhC;IAED,IAAI,CAAC,UAAU,CAAC,IAAI,MAAM,CAEzB;IAED,MAAM,EAAE,MAAM,CAAA;gBAGZ,MAAM,EAAE,MAAM,EACP,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EACvF,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAMxF,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAC9C;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,SAAS;QAAE,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,UAAU,CAAA;KAAE,EACzD,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC5C,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACnC,IAAI,CAAC,CAAC,CAAC,CAAA;CACX,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,OAAO,IAAI,CAAA"}

package/lib/task.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Task = void 0;
+const base_1 = require("./base");
+const symbols_1 = require("./symbols");
+class Task extends base_1.Base {
+    static get [symbols_1.typeSymbol]() {
+        return symbols_1.taskSymbol;
+    }
+    get [symbols_1.typeSymbol]() {
+        return symbols_1.taskSymbol;
+    }
+    constructor(logger, id, pluginOptions, options) {
+        super();
+        this.id = id;
+        this.pluginOptions = pluginOptions;
+        this.options = options;
+        this.logger = logger.child({ task: id });
+    }
+}
+exports.Task = Task;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dotcom-tool-kit/base",
+  "version": "4.0.0-beta.0",
+  "description": "",
+  "main": "lib",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@dotcom-tool-kit/conflict": "2.0.0-beta.0",
+    "@dotcom-tool-kit/validated": "2.0.0-beta.0",
+    "semver": "^7.5.4",
+    "winston": "^3.11.0"
+  },
+  "devDependencies": {
+    "@dotcom-tool-kit/logger": "4.0.0-beta.0",
+    "@dotcom-tool-kit/plugin": "2.0.0-beta.0",
+    "winston": "^3.11.0",
+    "zod": "^3.22.4"
+  },
+  "peerDependencies": {
+    "zod": "^3.22.4"
+  }
+}

package/src/base.ts

@@ -0,0 +1,58 @@
+import { styles as s } from '@dotcom-tool-kit/logger'
+import path from 'path'
+import fs from 'fs'
+import { baseSymbol, typeSymbol } from './symbols'
+import { Validated, invalid, valid } from '@dotcom-tool-kit/validated'
+import semver from 'semver'
+
+const packageJsonPath = path.resolve(__dirname, '../package.json')
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+const version: string = packageJson.version
+
+export abstract class Base {
+  static version = version
+  version = version
+
+  static get [typeSymbol](): symbol {
+    return baseSymbol
+  }
+
+  get [typeSymbol](): symbol {
+    return baseSymbol
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static is<T extends Base>(objectToCheck: any): objectToCheck is T {
+    return objectToCheck[typeSymbol] === this[typeSymbol]
+  }
+
+  static isCompatible<T extends Base>(objectToCheck: unknown): Validated<T> {
+    if (!this.is(objectToCheck)) {
+      return invalid([
+        `${s.plugin(
+          '@dotcom-tool-kit/base'
+        )} type symbol is missing, make sure that this object derives from the ${s.code('Task')} or ${s.code(
+          'Hook'
+        )} class defined by the plugin`
+      ])
+    }
+
+    // an 'objectToCheck' from a plugin is compatible with this CLI if its
+    // version is semver-compatible with the @dotcom-tool-kit/base included by
+    // the CLI (which is what's calling this). so, prepend ^ to our version,
+    // and check our version satisfies that.
+
+    // this lets e.g. a CLI that includes types@2.2.0 load any plugin
+    // that depends on any higher minor version of types.
+    const range = `^${this.version}`
+    if (semver.satisfies(objectToCheck.version, range)) {
+      return valid(objectToCheck as T)
+    } else {
+      return invalid([
+        `object is from an outdated version of ${s.plugin(
+          '@dotcom-tool-kit/base'
+        )}, make sure you're using at least version ${s.heading(this.version)} of the plugin`
+      ])
+    }
+  }
+}

package/src/hook.ts

@@ -0,0 +1,69 @@
+import type { Logger } from 'winston'
+import { Base } from './base'
+import { hookSymbol, typeSymbol } from './symbols'
+import type { z } from 'zod'
+import type { Plugin } from '@dotcom-tool-kit/plugin'
+import { Conflict, isConflict } from '@dotcom-tool-kit/conflict'
+
+export interface HookInstallation<Options = Record<string, unknown>> {
+  options: Options
+  plugin: Plugin
+  forHook: string
+  hookConstructor: HookConstructor
+}
+
+export abstract class Hook<Options extends z.ZodTypeAny = z.ZodTypeAny, State = void> extends Base {
+  logger: Logger
+  // This field is used to collect hooks that share state when running their
+  // install methods. All hooks in the same group will run their install method
+  // one after the other, and then their commitInstall method will be run with
+  // the collected state.
+  installGroup?: string
+
+  static get [typeSymbol](): symbol {
+    return hookSymbol
+  }
+
+  get [typeSymbol](): symbol {
+    return hookSymbol
+  }
+
+  static mergeChildInstallations(
+    plugin: Plugin,
+    childInstallations: (HookInstallation | Conflict<HookInstallation>)[]
+  ): (HookInstallation | Conflict<HookInstallation>)[] {
+    return [
+      {
+        plugin,
+        conflicting: childInstallations.flatMap((installation) =>
+          isConflict(installation) ? installation.conflicting : installation
+        )
+      }
+    ]
+  }
+
+  static overrideChildInstallations(
+    plugin: Plugin,
+    parentInstallation: HookInstallation,
+    _childInstallations: (HookInstallation | Conflict<HookInstallation>)[]
+  ): (HookInstallation | Conflict<HookInstallation>)[] {
+    return [parentInstallation]
+  }
+
+  constructor(logger: Logger, public id: string, public options: z.output<Options>) {
+    super()
+    this.logger = logger.child({ hook: this.constructor.name })
+  }
+
+  abstract isInstalled(): Promise<boolean>
+  abstract install(state?: State): Promise<State>
+  async commitInstall(_state: State): Promise<void> {
+    return
+  }
+}
+
+export type HookConstructor = {
+  new (logger: Logger, id: string, options: z.output<z.ZodTypeAny>): Hook<z.ZodTypeAny, unknown>
+}
+
+export type HookClass = HookConstructor & typeof Hook

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './base'
+export * from './hook'
+export * from './init'
+export * from './task'

package/src/init.ts

@@ -0,0 +1,28 @@
+import type { Logger } from 'winston'
+import { initSymbol, typeSymbol } from './symbols'
+import { Base } from './base'
+
+export abstract class Init extends Base {
+  logger: Logger
+
+  constructor(logger: Logger) {
+    super()
+    this.logger = logger.child({ hook: this.constructor.name })
+  }
+
+  static get [typeSymbol](): symbol {
+    return initSymbol
+  }
+
+  get [typeSymbol](): symbol {
+    return initSymbol
+  }
+
+  abstract init(): Promise<void>
+}
+
+export type InitConstructor = {
+  new (logger: Logger): Init
+}
+
+export type InitClass = InitConstructor & typeof Init

package/src/symbols.ts

@@ -0,0 +1,14 @@
+// uses Symbol.for, not Symbol, so that they're compatible across different
+// @dotcom-tool-kit/base instances
+
+// TODO these symbols say '@dotcom-tool-kit/types' because they used to live
+// in that package. changing that would be a backwards compatibility nightmare
+
+// used as the name for the property we use to identify classes
+export const typeSymbol = Symbol.for('@dotcom-tool-kit/types')
+
+// used to identify the Base, Task and Hook classes
+export const baseSymbol = Symbol.for('@dotcom-tool-kit/types/base')
+export const taskSymbol = Symbol.for('@dotcom-tool-kit/types/task')
+export const hookSymbol = Symbol.for('@dotcom-tool-kit/types/hook')
+export const initSymbol = Symbol.for('@dotcom-tool-kit/types/init')

package/src/task.ts

@@ -0,0 +1,46 @@
+import type { z } from 'zod'
+import { Base } from './base'
+import { taskSymbol, typeSymbol } from './symbols'
+import type { Logger } from 'winston'
+
+type Default<T, D> = T extends undefined ? D : T
+
+export abstract class Task<
+  Options extends {
+    plugin?: z.ZodTypeAny
+    task?: z.ZodTypeAny
+  } = Record<never, never>
+> extends Base {
+  static get [typeSymbol](): symbol {
+    return taskSymbol
+  }
+
+  get [typeSymbol](): symbol {
+    return taskSymbol
+  }
+
+  logger: Logger
+
+  constructor(
+    logger: Logger,
+    public id: string,
+    public pluginOptions: z.output<Default<Options['plugin'], z.ZodObject<Record<string, never>>>>,
+    public options: z.output<Default<Options['task'], z.ZodObject<Record<string, never>>>>
+  ) {
+    super()
+    this.logger = logger.child({ task: id })
+  }
+
+  abstract run(files?: string[]): Promise<void>
+}
+
+export type TaskConstructor = {
+  new <O extends { plugin: z.ZodTypeAny; task: z.ZodTypeAny }>(
+    logger: Logger,
+    id: string,
+    pluginOptions: Partial<z.infer<O['plugin']>>,
+    options: Partial<z.infer<O['task']>>
+  ): Task<O>
+}
+
+export type TaskClass = TaskConstructor & typeof Task

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../tsconfig.settings.json",
+  "references": [
+    {
+      "path": "../conflict"
+    },
+    {
+      "path": "../logger"
+    },
+    {
+      "path": "../plugin"
+    },
+    {
+      "path": "../validated"
+    }
+  ],
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src"
+  }
+}