@quadnix/octo-build 0.0.17 → 0.1.0

package/dist/resources/octo-v1.schema.json

@@ -81,6 +81,9 @@
               {
                 "additionalProperties": false,
                 "properties": {
+                  "reportDir": {
+                    "type": "string"
+                  },
                   "type": {
                     "const": "HtmlReportEventListener",
                     "type": "string"
@@ -92,6 +95,13 @@
               {
                 "additionalProperties": false,
                 "properties": {
+                  "colorize": {
+                    "type": "boolean"
+                  },
+                  "level": {
+                    "enum": ["debug", "error", "fatal", "info", "silent", "trace", "warn"],
+                    "type": "string"
+                  },
                   "type": {
                     "const": "LoggingEventListener",
                     "type": "string"
@@ -149,31 +159,88 @@
               "type": "object"
             }
           ]
-        },
-        "transactionOptions": {
-          "additionalProperties": false,
-          "properties": {
-            "yieldModelDiffs": {
-              "default": false,
-              "type": "boolean"
+        }
+      },
+      "required": ["stateProvider"],
+      "type": "object"
+    },
+    "tags": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "scope": {
+            "additionalProperties": false,
+            "properties": {
+              "moduleId": {
+                "type": "string"
+              }
             },
-            "yieldModelTransaction": {
-              "default": false,
-              "type": "boolean"
+            "type": "object"
+          },
+          "tags": {
+            "additionalProperties": {
+              "type": "string"
+            },
+            "type": "object"
+          }
+        },
+        "required": ["tags"],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "terraform": {
+      "additionalProperties": false,
+      "properties": {
+        "providers": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "accountId": {
+                "type": "string"
+              },
+              "accountName": {
+                "type": "string"
+              },
+              "providerType": {
+                "type": "string"
+              },
+              "regionId": {
+                "type": "string"
+              },
+              "setRegionAttribute": {
+                "type": "boolean"
+              },
+              "spec": {
+                "type": "object"
+              }
             },
-            "yieldResourceDiffs": {
-              "default": false,
-              "type": "boolean"
+            "required": ["accountId", "providerType", "regionId"],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "requiredProviders": {
+          "additionalProperties": {
+            "additionalProperties": false,
+            "properties": {
+              "minVersion": {
+                "type": "string"
+              },
+              "source": {
+                "type": "string"
+              }
             },
-            "yieldResourceTransaction": {
-              "default": false,
-              "type": "boolean"
-            }
+            "required": ["source"],
+            "type": "object"
           },
           "type": "object"
+        },
+        "requiredVersion": {
+          "type": "string"
         }
       },
-      "required": ["stateProvider"],
+      "required": ["providers", "requiredProviders", "requiredVersion"],
       "type": "object"
     },
     "version": {
@@ -181,7 +248,7 @@
       "type": "number"
     }
   },
-  "required": ["imports", "modules", "settings", "version"],
+  "required": ["imports", "modules", "settings", "terraform", "version"],
   "title": "Octo V1 Definition Schema",
   "type": "object"
 }

package/dist/utilities/definition/yaml/yaml-definition.utility.d.ts

@@ -1,10 +1,34 @@
-import { type Constructable, LocalEncryptionStateProvider, LocalStateProvider, TestStateProvider } from '@quadnix/octo';
+import { type Constructable, LocalEncryptionStateProvider, LocalStateProvider, type Octo, TestStateProvider } from '@quadnix/octo';
 import type { HtmlReportEventListener } from '@quadnix/octo-event-listeners/html-report';
 import type { LoggingEventListener } from '@quadnix/octo-event-listeners/logging';
+/**
+ * Reads `octo.yml` and turns each section into the values {@link Octo} is booted with.
+ */
 export declare class YamlDefinitionUtility {
     private readonly definition;
+    /**
+     * The directory holding the definition file. Everything the definition names by relative path is
+     * resolved against this, not against `process.cwd()`: `octo run-action` is invoked by terraform
+     * from inside a terragrunt cache directory, so the cwd there is neither the project nor stable.
+     */
+    private readonly definitionDir;
+    /**
+     * @param definitionFilePath Path to the definition file.
+     * @throws If the file is unreadable, or fails schema validation.
+     */
     constructor(definitionFilePath: string);
+    /**
+     * Substitutes `${env.KEY}` references in a value with what the definition's `env` block declares.
+     *
+     * Arrays and objects are walked, because a module input is as nested as its schema: a reference
+     * can sit inside a list of images, or a key of an object, as readily as at the top level.
+     *
+     * @throws If a value holds one of its own ancestors, which no substitution over it terminates on.
+     */
     resolveEnvironmentValue<T>(value: unknown): T;
+    /**
+     * Imports the hook callbacks the definition names, in the shape {@link Octo.registerHooks} takes.
+     */
     resolveHooks(): Promise<{
         postCommitHooks?: {
             handle: any;
@@ -29,19 +53,35 @@ export declare class YamlDefinitionUtility {
             handle: any;
         }[];
     }>;
+    /**
+     * Imports every module class the definition's `imports` block names.
+     */
     resolveImports(): Promise<{
         className: Constructable<any>;
     }[]>;
-    resolveListeners(): Promise<{
+    /**
+     * @param logDestination Where the logging listener writes. `run-action` passes `stderr`, because
+     * terraform's `data "external"` protocol requires that command's stdout to carry only the response
+     * JSON.
+     */
+    resolveListeners({ logDestination }?: {
+        logDestination?: 'stderr' | 'stdout';
+    }): Promise<{
         args?: unknown[];
         metadata?: Record<string, string>;
         type: Constructable<HtmlReportEventListener | LoggingEventListener>;
     }[]>;
+    /**
+     * Pairs each `modules` entry with its imported class, and resolves its inputs.
+     */
     resolveModules(imports: Awaited<ReturnType<YamlDefinitionUtility['resolveImports']>>): {
         moduleClass: Constructable<any>;
         moduleId: string;
         moduleInputs: Record<string, unknown>;
     }[];
+    /**
+     * Builds the {@link IStateProvider} the definition asks for.
+     */
     resolveStateProvider(): {
         type: LocalEncryptionStateProvider;
     } | {
@@ -49,14 +89,62 @@ export declare class YamlDefinitionUtility {
     } | {
         type: TestStateProvider;
     };
-    resolveTransactionOptions(): {
-        appLockId: string | undefined;
-        enableResourceCapture: boolean;
-        enableResourceValidation: boolean;
-        yieldModelDiffs: boolean;
-        yieldModelTransaction: boolean;
-        yieldResourceDiffs: boolean;
-        yieldResourceTransaction: boolean;
+    /**
+     * The tag registrations the definition declares, in the shape {@link Octo.registerTags} takes.
+     *
+     * A `scope` naming a `moduleId` reaches that module's resources; an absent or empty one reaches
+     * every resource of the run.
+     */
+    resolveTags(): Parameters<Octo['registerTags']>[0];
+    /**
+     * The terraform version, required providers, and provider blocks the definition declares.
+     */
+    resolveTerraformOptions(): {
+        providers: {
+            accountId: string;
+            accountName: string | undefined;
+            providerType: string;
+            regionId: string;
+            setRegionAttribute: boolean | undefined;
+            spec: Record<string, unknown>;
+        }[];
+        requiredProviders: Record<string, {
+            minVersion?: string;
+            source: string;
+        }>;
+        requiredVersion: string;
     };
+    /**
+     * Substitutes one `${env.KEY}` reference with what the definition's `env` block declares for that
+     * key, read in the kind the block gives it. Anything holding no reference is returned as it came.
+     */
+    private resolveEnvironmentReference;
+    /**
+     * Resolves a definition-file import specifier to something `import()` can load.
+     *
+     * A relative path resolves against the **definition file's own directory**. It cannot resolve
+     * against the current working directory: terraform invokes `octo run-action` from inside a
+     * terragrunt cache directory, so a definition saying `./dist/index.js` - which is what every
+     * generated app says - would be looked for under the cache and never found.
+     *
+     * A bare specifier resolves against the **user's project root**, not octo-build's own install
+     * directory - node would otherwise resolve it from wherever octo-build happens to live. A flat
+     * `node_modules` hides that; a linked store does not, and there the user's own dependencies are
+     * invisible.
+     */
+    private resolveImportPath;
+    /**
+     * Walks a value, substituting every `${env.KEY}` reference it holds at any depth.
+     *
+     * `ancestors` is the chain currently being walked rather than everything already seen. A YAML
+     * anchor used in two places points one node at two parents, which resolves twice and is no cycle;
+     * a node reappearing beneath itself is one, and walking it never ends.
+     *
+     * @throws If a value holds one of its own ancestors.
+     */
+    private resolveNestedEnvironmentValue;
+    /**
+     * Checks the definition against `octo-v1.schema.json`.
+     */
     private validateDefinition;
 }

package/dist/utilities/definition/yaml/yaml-definition.utility.js

@@ -1,13 +1,22 @@
 import { existsSync, readFileSync } from 'fs';
+import { createRequire } from 'module';
 import { dirname, join, resolve } from 'path';
-import { fileURLToPath } from 'url';
-import { LocalEncryptionStateProvider, LocalStateProvider, TestStateProvider } from '@quadnix/octo';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { LocalEncryptionStateProvider, LocalStateProvider, TestStateProvider, } from '@quadnix/octo';
 import { Ajv2020 as Ajv } from 'ajv/dist/2020.js';
 import { load } from 'js-yaml';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Reads `octo.yml` and turns each section into the values {@link Octo} is booted with.
+ */
 export class YamlDefinitionUtility {
+    /**
+     * @param definitionFilePath Path to the definition file.
+     * @throws If the file is unreadable, or fails schema validation.
+     */
     constructor(definitionFilePath) {
         definitionFilePath = resolve(process.cwd(), definitionFilePath);
+        this.definitionDir = dirname(definitionFilePath);
         if (!existsSync(definitionFilePath)) {
             throw new Error('Cannot find definition file: ' + definitionFilePath);
         }
@@ -20,32 +29,20 @@ export class YamlDefinitionUtility {
         }
         this.validateDefinition();
     }
+    /**
+     * Substitutes `${env.KEY}` references in a value with what the definition's `env` block declares.
+     *
+     * Arrays and objects are walked, because a module input is as nested as its schema: a reference
+     * can sit inside a list of images, or a key of an object, as readily as at the top level.
+     *
+     * @throws If a value holds one of its own ancestors, which no substitution over it terminates on.
+     */
     resolveEnvironmentValue(value) {
-        if (typeof value !== 'string') {
-            return value;
-        }
-        const pattern = value.match(/^\$\{env\.(.+)}$/);
-        if (!pattern || pattern.length < 2) {
-            return value;
-        }
-        const environmentKey = this.definition.env.find((e) => e.key === pattern[1]);
-        if (!environmentKey) {
-            throw new Error(`Key "${pattern[1]}" not found under "env"!`);
-        }
-        let resolvedValue = process.env[pattern[1]] || environmentKey.value;
-        const { kind } = environmentKey;
-        switch (kind) {
-            case 'boolean': {
-                return Boolean(resolvedValue);
-            }
-            case 'number': {
-                return Number(resolvedValue);
-            }
-            default: {
-                return String(resolvedValue);
-            }
-        }
+        return this.resolveNestedEnvironmentValue(value, new Set());
     }
+    /**
+     * Imports the hook callbacks the definition names, in the shape {@link Octo.registerHooks} takes.
+     */
     async resolveHooks() {
         const hooks = {
             postCommitHooks: [],
@@ -60,8 +57,8 @@ export class YamlDefinitionUtility {
         }
         for (const hookDef of this.definition.hooks) {
             const { importPath, method } = hookDef;
-            const resolvedImport = importPath.startsWith('.') || importPath.startsWith('/') ? resolve(process.cwd(), importPath) : importPath;
             try {
+                const resolvedImport = this.resolveImportPath(importPath);
                 const imported = await import(resolvedImport);
                 if (!imported[method]) {
                     throw new Error(`Unable to find export "${method}" in path "${resolvedImport}"!`);
@@ -77,11 +74,14 @@ export class YamlDefinitionUtility {
                 }
             }
             catch (error) {
-                throw new Error(`Failed to import path "${resolvedImport}": ${error?.message || String(error)}`);
+                throw new Error(`Failed to import path "${importPath}": ${error?.message || String(error)}`);
             }
         }
         return hooks;
     }
+    /**
+     * Imports every module class the definition's `imports` block names.
+     */
     async resolveImports() {
         const imports = [];
         if (!this.definition.imports?.length) {
@@ -89,8 +89,8 @@ export class YamlDefinitionUtility {
         }
         for (const importDef of this.definition.imports) {
             const { className, importPath } = importDef;
-            const resolvedImport = importPath.startsWith('.') || importPath.startsWith('/') ? resolve(process.cwd(), importPath) : importPath;
             try {
+                const resolvedImport = this.resolveImportPath(importPath);
                 const imported = await import(resolvedImport);
                 if (!imported[className]) {
                     throw new Error(`Unable to find export "${className}" in path "${resolvedImport}"!`);
@@ -100,32 +100,51 @@ export class YamlDefinitionUtility {
                 }
             }
             catch (error) {
-                throw new Error(`Failed to import path "${resolvedImport}": ${error?.message || String(error)}`);
+                throw new Error(`Failed to import path "${importPath}": ${error?.message || String(error)}`);
             }
         }
         return imports;
     }
-    async resolveListeners() {
+    /**
+     * @param logDestination Where the logging listener writes. `run-action` passes `stderr`, because
+     * terraform's `data "external"` protocol requires that command's stdout to carry only the response
+     * JSON.
+     */
+    async resolveListeners({ logDestination = 'stdout' } = {}) {
         const listeners = [];
         if (!this.definition.settings?.listeners?.length) {
             return listeners;
         }
         for (const listenerDef of this.definition.settings.listeners) {
             if (listenerDef.type === 'HtmlReportEventListener') {
-                if (process.env.OCTO_DISABLE_HTML_REPORT_EVENT_LISTENER?.toLowerCase() !== 'true') {
-                    const imported = await import('@quadnix/octo-event-listeners/html-report');
-                    listeners.push({ type: imported.HtmlReportEventListener });
-                }
+                const imported = await import('@quadnix/octo-event-listeners/html-report');
+                listeners.push({
+                    args: [{ reportDir: listenerDef.reportDir }],
+                    type: imported.HtmlReportEventListener,
+                });
             }
             else if (listenerDef.type === 'LoggingEventListener') {
-                if (process.env.OCTO_DISABLE_LOGGING_EVENT_LISTENER?.toLowerCase() !== 'true') {
-                    const imported = await import('@quadnix/octo-event-listeners/logging');
-                    listeners.push({ type: imported.LoggingEventListener });
-                }
+                const imported = await import('@quadnix/octo-event-listeners/logging');
+                // Default to whether the destination is a terminal, so a redirected log carries no escape
+                // codes. An explicit `colorize:` in the definition still wins.
+                const destinationStream = logDestination === 'stderr' ? process.stderr : process.stdout;
+                listeners.push({
+                    args: [
+                        {
+                            colorize: listenerDef.colorize ?? Boolean(destinationStream.isTTY),
+                            destination: logDestination,
+                            level: listenerDef.level ?? 'info',
+                        },
+                    ],
+                    type: imported.LoggingEventListener,
+                });
             }
         }
         return listeners;
     }
+    /**
+     * Pairs each `modules` entry with its imported class, and resolves its inputs.
+     */
     resolveModules(imports) {
         const modules = [];
         if (!this.definition.modules?.length) {
@@ -145,16 +164,22 @@ export class YamlDefinitionUtility {
         }
         return modules;
     }
+    /**
+     * Builds the {@link IStateProvider} the definition asks for.
+     */
     resolveStateProvider() {
         const stateProvider = this.definition.settings.stateProvider;
+        // Anchored to the definition file for the same reason imports are: `run-action` runs with
+        // terragrunt's cache directory as its cwd, and a state path resolved from there would point at
+        // an empty directory - the action would read no prior state and write its result nowhere useful.
         if (stateProvider.type === 'LocalEncryptionStateProvider') {
             return {
-                type: new LocalEncryptionStateProvider(stateProvider.statePath, stateProvider.encryptionKey),
+                type: new LocalEncryptionStateProvider(resolve(this.definitionDir, stateProvider.statePath), stateProvider.encryptionKey),
             };
         }
         else if (stateProvider.type === 'LocalStateProvider') {
             return {
-                type: new LocalStateProvider(stateProvider.statePath),
+                type: new LocalStateProvider(resolve(this.definitionDir, stateProvider.statePath)),
             };
         }
         else if (stateProvider.type === 'TestStateProvider') {
@@ -166,40 +191,146 @@ export class YamlDefinitionUtility {
             throw new Error(`Invalid state provider!`);
         }
     }
-    resolveTransactionOptions() {
-        const tx = this.definition.settings.transactionOptions || {};
-        const options = {
-            appLockId: undefined,
-            enableResourceCapture: false,
-            enableResourceValidation: false,
-            yieldModelDiffs: tx.yieldModelDiffs || false,
-            yieldModelTransaction: tx.yieldModelTransaction || false,
-            yieldResourceDiffs: tx.yieldResourceDiffs || false,
-            yieldResourceTransaction: tx.yieldResourceTransaction || false,
+    /**
+     * The tag registrations the definition declares, in the shape {@link Octo.registerTags} takes.
+     *
+     * A `scope` naming a `moduleId` reaches that module's resources; an absent or empty one reaches
+     * every resource of the run.
+     */
+    resolveTags() {
+        const tags = [];
+        if (!this.definition.tags?.length) {
+            return tags;
+        }
+        for (const tagDefinition of this.definition.tags) {
+            const resolvedTags = {};
+            for (const [key, value] of Object.entries(tagDefinition.tags)) {
+                // A tag value is always a string, so an `${env.KEY}` declared as a number or a boolean is
+                // rendered rather than handed to the resource as the kind it was declared with.
+                resolvedTags[key] = String(this.resolveEnvironmentValue(value));
+            }
+            tags.push({ scope: tagDefinition.scope || {}, tags: resolvedTags });
+        }
+        return tags;
+    }
+    /**
+     * The terraform version, required providers, and provider blocks the definition declares.
+     */
+    resolveTerraformOptions() {
+        const terraform = this.definition.terraform;
+        const providers = terraform.providers.map((p) => {
+            const spec = {};
+            for (const [key, value] of Object.entries(p.spec || {})) {
+                spec[key] = this.resolveEnvironmentValue(value);
+            }
+            return {
+                accountId: this.resolveEnvironmentValue(p.accountId),
+                accountName: p.accountName ? this.resolveEnvironmentValue(p.accountName) : undefined,
+                providerType: p.providerType,
+                regionId: this.resolveEnvironmentValue(p.regionId),
+                // Passed through as-is: undefined lets octo apply its per-provider-type default.
+                setRegionAttribute: p.setRegionAttribute,
+                spec,
+            };
+        });
+        return {
+            providers,
+            requiredProviders: terraform.requiredProviders,
+            requiredVersion: this.resolveEnvironmentValue(terraform.requiredVersion),
         };
-        if (process.env.OCTO_APP_LOCK_ID) {
-            options.appLockId = process.env.OCTO_APP_LOCK_ID;
+    }
+    /**
+     * Substitutes one `${env.KEY}` reference with what the definition's `env` block declares for that
+     * key, read in the kind the block gives it. Anything holding no reference is returned as it came.
+     */
+    resolveEnvironmentReference(value) {
+        if (typeof value !== 'string') {
+            return value;
         }
-        if (process.env.OCTO_ENABLE_RESOURCE_CAPTURE) {
-            options.enableResourceCapture = process.env.OCTO_ENABLE_RESOURCE_CAPTURE.toLowerCase() === 'true';
+        const pattern = value.match(/^\$\{env\.(.+)}$/);
+        if (!pattern || pattern.length < 2) {
+            return value;
         }
-        if (process.env.OCTO_ENABLE_RESOURCE_VALIDATION) {
-            options.enableResourceValidation = process.env.OCTO_ENABLE_RESOURCE_VALIDATION.toLowerCase() === 'true';
+        // `env` is optional in the schema, so a definition can reference `${env.X}` without declaring
+        // one. Treat that as an empty block and let the "not found" error below report it.
+        const environmentKey = (this.definition.env ?? []).find((e) => e.key === pattern[1]);
+        if (!environmentKey) {
+            throw new Error(`Key "${pattern[1]}" not found under "env"!`);
         }
-        if (process.env.OCTO_YIELD_MODEL_DIFFS) {
-            options.yieldModelDiffs = process.env.OCTO_YIELD_MODEL_DIFFS.toLowerCase() === 'true';
+        let resolvedValue = process.env[pattern[1]] || environmentKey.value;
+        const { kind } = environmentKey;
+        switch (kind) {
+            case 'boolean': {
+                // A shell always supplies a string, and `Boolean("false")` is `true`. Parse the string form
+                // rather than coercing it, and reject anything that is not plainly a boolean.
+                if (typeof resolvedValue === 'boolean') {
+                    return resolvedValue;
+                }
+                const normalizedValue = String(resolvedValue).trim().toLowerCase();
+                if (normalizedValue === 'true') {
+                    return true;
+                }
+                else if (normalizedValue === 'false') {
+                    return false;
+                }
+                else {
+                    throw new Error(`Value "${resolvedValue}" for key "${pattern[1]}" is not a boolean!`);
+                }
+            }
+            case 'number': {
+                return Number(resolvedValue);
+            }
+            default: {
+                return String(resolvedValue);
+            }
         }
-        if (process.env.OCTO_YIELD_MODEL_TRANSACTION) {
-            options.yieldModelTransaction = process.env.OCTO_YIELD_MODEL_TRANSACTION.toLowerCase() === 'true';
+    }
+    /**
+     * Resolves a definition-file import specifier to something `import()` can load.
+     *
+     * A relative path resolves against the **definition file's own directory**. It cannot resolve
+     * against the current working directory: terraform invokes `octo run-action` from inside a
+     * terragrunt cache directory, so a definition saying `./dist/index.js` - which is what every
+     * generated app says - would be looked for under the cache and never found.
+     *
+     * A bare specifier resolves against the **user's project root**, not octo-build's own install
+     * directory - node would otherwise resolve it from wherever octo-build happens to live. A flat
+     * `node_modules` hides that; a linked store does not, and there the user's own dependencies are
+     * invisible.
+     */
+    resolveImportPath(importPath) {
+        if (importPath.startsWith('.') || importPath.startsWith('/')) {
+            return resolve(this.definitionDir, importPath);
         }
-        if (process.env.OCTO_YIELD_RESOURCE_DIFFS) {
-            options.yieldResourceDiffs = process.env.OCTO_YIELD_RESOURCE_DIFFS.toLowerCase() === 'true';
+        const requireFromProject = createRequire(join(this.definitionDir, 'package.json'));
+        return pathToFileURL(requireFromProject.resolve(importPath)).href;
+    }
+    /**
+     * Walks a value, substituting every `${env.KEY}` reference it holds at any depth.
+     *
+     * `ancestors` is the chain currently being walked rather than everything already seen. A YAML
+     * anchor used in two places points one node at two parents, which resolves twice and is no cycle;
+     * a node reappearing beneath itself is one, and walking it never ends.
+     *
+     * @throws If a value holds one of its own ancestors.
+     */
+    resolveNestedEnvironmentValue(value, ancestors) {
+        if (value === null || typeof value !== 'object') {
+            return this.resolveEnvironmentReference(value);
         }
-        if (process.env.OCTO_YIELD_RESOURCE_TRANSACTION) {
-            options.yieldResourceTransaction = process.env.OCTO_YIELD_RESOURCE_TRANSACTION.toLowerCase() === 'true';
+        if (ancestors.has(value)) {
+            throw new Error('Definition holds a value that contains itself!');
         }
-        return options;
+        ancestors.add(value);
+        const resolvedValue = Array.isArray(value)
+            ? value.map((v) => this.resolveNestedEnvironmentValue(v, ancestors))
+            : Object.fromEntries(Object.entries(value).map(([key, v]) => [key, this.resolveNestedEnvironmentValue(v, ancestors)]));
+        ancestors.delete(value);
+        return resolvedValue;
     }
+    /**
+     * Checks the definition against `octo-v1.schema.json`.
+     */
     validateDefinition() {
         if (!this.definition?.version || typeof this.definition?.version !== 'number') {
             throw new Error(`Definition version "${this.definition?.version}" must be a number!`);