@quadnix/octo-build 0.0.16 → 0.1.0

package/dist/commands/unlock/unlock.command.js

@@ -0,0 +1,51 @@
+import { Container, StateManagementService } from '@quadnix/octo';
+import chalk from 'chalk';
+import { bootStateProvider, reportError } from '../../utilities/octo/octo.utility.js';
+/**
+ * Releases the app lock.
+ *
+ * A run that finishes releases its own lock - `commit` always does, however it ends - so this is
+ * either for a run that never reached its commit, or for `--force` after one died holding the lock.
+ */
+export const unlockCommand = {
+    builder: (yargs) => {
+        return yargs
+            .option('lockId', {
+            demandOption: false,
+            description: 'The lock ID to release, as printed by `octo lock`.',
+            type: 'string',
+        })
+            .option('force', {
+            default: false,
+            demandOption: false,
+            description: 'Release whatever lock is held, without knowing its ID. For a run that died holding one.',
+            type: 'boolean',
+        });
+    },
+    command: 'unlock',
+    describe: 'Release the app state lock.',
+    handler: async (argv) => {
+        const { force, lockId } = argv;
+        try {
+            if (!force && !lockId) {
+                throw new Error('Either --lockId or --force is required to unlock!');
+            }
+            await bootStateProvider();
+            const stateManagementService = await Container.getInstance().get(StateManagementService);
+            // Force reads the held lock and releases that, which is the only way through when the ID was
+            // lost with the run that took it.
+            const existingLockId = await stateManagementService.getAppLock();
+            if (!existingLockId) {
+                console.error(chalk.green('App is already unlocked.'));
+                return;
+            }
+            await stateManagementService.unlockApp(force ? existingLockId : lockId);
+            console.error(chalk.green(`App was unlocked, releasing lock ID "${existingLockId}".`));
+        }
+        catch (error) {
+            reportError(error);
+            process.exit(1);
+        }
+    },
+};
+//# sourceMappingURL=unlock.command.js.map

package/dist/commands/unlock/unlock.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlock.command.js","sourceRoot":"","sources":["../../../src/commands/unlock/unlock.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAOtF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,CAAC,KAAW,EAAQ,EAAE;QAC7B,OAAO,KAAK;aACT,MAAM,CAAC,QAAQ,EAAE;YAChB,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,oDAAoD;YACjE,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,OAAO,EAAE;YACf,OAAO,EAAE,KAAK;YACd,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,yFAAyF;YACtG,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;IACP,CAAC;IACD,OAAO,EAAE,QAAQ;IACjB,QAAQ,EAAE,6BAA6B;IACvC,OAAO,EAAE,KAAK,EAAE,IAAgD,EAAiB,EAAE;QACjF,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAE/B,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;YACvE,CAAC;YAED,MAAM,iBAAiB,EAAE,CAAC;YAC1B,MAAM,sBAAsB,GAAG,MAAM,SAAS,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;YAEzF,6FAA6F;YAC7F,kCAAkC;YAClC,MAAM,cAAc,GAAG,MAAM,sBAAsB,CAAC,UAAU,EAAE,CAAC;YACjE,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;gBACvD,OAAO;YACT,CAAC;YAED,MAAM,sBAAsB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAO,CAAC,CAAC;YACzE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,wCAAwC,cAAc,IAAI,CAAC,CAAC,CAAC;QACzF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,WAAW,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/commands/validate/index.d.ts

@@ -0,0 +1 @@
+export { validateCommand } from './validate.command.js';

package/dist/commands/validate/index.js

@@ -0,0 +1,2 @@
+export { validateCommand } from './validate.command.js';
+//# sourceMappingURL=index.js.map

package/dist/commands/validate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/validate/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/commands/validate/validate.command.d.ts

@@ -0,0 +1,17 @@
+import type { ArgumentsCamelCase, Argv } from 'yargs';
+type ValidateCommandArguments = {
+    terraformBinary?: string;
+    terragruntBinary?: string;
+    terragruntDir: string;
+    timeoutInMs?: number;
+};
+/**
+ * Step 2 of the octo lifecycle. See {@link Octo.validate}.
+ */
+export declare const validateCommand: {
+    builder: (yargs: Argv) => Argv;
+    command: string;
+    describe: string;
+    handler: (argv: ArgumentsCamelCase<ValidateCommandArguments>) => Promise<void>;
+};
+export {};

package/dist/commands/validate/validate.command.js

@@ -0,0 +1,68 @@
+import { resolve } from 'path';
+import { Container, TerraformUtility } from '@quadnix/octo';
+import chalk from 'chalk';
+import { bootOcto, prepareCallbackEnvironment, reportError } from '../../utilities/octo/octo.utility.js';
+/**
+ * Step 2 of the octo lifecycle. See {@link Octo.validate}.
+ */
+export const validateCommand = {
+    builder: (yargs) => {
+        return yargs
+            .option('terragruntDir', {
+            demandOption: true,
+            description: 'The generated Terragrunt directory to plan and validate.',
+            type: 'string',
+        })
+            .option('terraformBinary', {
+            demandOption: false,
+            description: 'Override the terraform/tofu binary terragrunt should invoke (sets TG_TF_PATH).',
+            type: 'string',
+        })
+            .option('terragruntBinary', {
+            demandOption: false,
+            description: 'Override the terragrunt binary/path to invoke.',
+            type: 'string',
+        })
+            .option('timeoutInMs', {
+            demandOption: false,
+            description: 'Override the per-command timeout, in milliseconds.',
+            type: 'number',
+        });
+    },
+    command: 'validate',
+    describe: "Step 2: validate the generated Terraform plans against Octo's resource diff.",
+    handler: async (argv) => {
+        const { terraformBinary, terragruntBinary, terragruntDir, timeoutInMs } = argv;
+        const resolvedDir = resolve(process.cwd(), terragruntDir);
+        try {
+            // A plan reads every `data "external"`, and each one shells back out to `octo get-response`.
+            prepareCallbackEnvironment();
+            const { app, octo } = await bootOcto();
+            const terraformUtility = await Container.getInstance().get(TerraformUtility, {
+                args: [{ terraformBinary, terragruntBinary, timeoutInMs }, true],
+            });
+            // A folder whose plan cannot be read is carried as an error rather than aborting the run. Octo
+            // reports the failure for a folder holding a module it tracks, and ignores one it does not know.
+            const planResult = await terraformUtility.plan(resolvedDir, { json: true });
+            // The report itself is rendered by whichever listeners the definition registers — none of
+            // them, and this command prints only its verdict. What survives here is the exit code, which
+            // is the CLI's own job and not a listener's.
+            const report = await octo.validate(app, planResult);
+            // Only being unable to read a folder is unsuccessful. Drift and unexplained changes are
+            // findings to act on, not exit codes.
+            //
+            // The verdict itself is not printed here - the listeners render the report, drift included,
+            // on stdout, and a `console.log` alongside pino lands out of order. What is left is the exit
+            // code, which is the CLI's own job, and the failure line on stderr.
+            if (report.failures.length > 0) {
+                console.error(chalk.red('\nValidation could not complete!'));
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            reportError(error);
+            process.exit(1);
+        }
+    },
+};
+//# sourceMappingURL=validate.command.js.map

package/dist/commands/validate/validate.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.command.js","sourceRoot":"","sources":["../../../src/commands/validate/validate.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,QAAQ,EAAE,0BAA0B,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AASzG;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,CAAC,KAAW,EAAQ,EAAE;QAC7B,OAAO,KAAK;aACT,MAAM,CAAC,eAAe,EAAE;YACvB,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,0DAA0D;YACvE,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,iBAAiB,EAAE;YACzB,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,gFAAgF;YAC7F,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,kBAAkB,EAAE;YAC1B,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,gDAAgD;YAC7D,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,aAAa,EAAE;YACrB,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,oDAAoD;YACjE,IAAI,EAAE,QAAQ;SACf,CAAC,CAAC;IACP,CAAC;IACD,OAAO,EAAE,UAAU;IACnB,QAAQ,EAAE,8EAA8E;IACxF,OAAO,EAAE,KAAK,EAAE,IAAkD,EAAiB,EAAE;QACnF,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;QAC/E,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,CAAC;QAE1D,IAAI,CAAC;YACH,6FAA6F;YAC7F,0BAA0B,EAAE,CAAC;YAE7B,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,MAAM,QAAQ,EAAE,CAAC;YACvC,MAAM,gBAAgB,GAAG,MAAM,SAAS,CAAC,WAAW,EAAE,CAAC,GAAG,CAAwB,gBAAgB,EAAE;gBAClG,IAAI,EAAE,CAAC,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC;aACjE,CAAC,CAAC;YAEH,+FAA+F;YAC/F,iGAAiG;YACjG,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAE5E,0FAA0F;YAC1F,6FAA6F;YAC7F,6CAA6C;YAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YAEpD,wFAAwF;YACxF,sCAAsC;YACtC,EAAE;YACF,4FAA4F;YAC5F,6FAA6F;YAC7F,oEAAoE;YACpE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC/B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,WAAW,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/index.js

@@ -2,16 +2,22 @@
 import * as process from 'process';
 import chalk from 'chalk';
 import yargs from 'yargs/yargs';
+import { applyCommand } from './commands/apply/index.js';
 import { buildCommand } from './commands/build/index.js';
+import { commitCommand } from './commands/commit/index.js';
 import { createAnchorCommand } from './commands/create-anchor/index.js';
 import { createAppCommand } from './commands/create-app/index.js';
-import { createCdkCommand } from './commands/create-cdk/index.js';
+import { createExternalResourceCommand } from './commands/create-external-resource/index.js';
 import { createModelCommand } from './commands/create-model/index.js';
 import { createModuleCommand } from './commands/create-module/index.js';
 import { createOverlayCommand } from './commands/create-overlay/index.js';
-import { createResourceCommand } from './commands/create-resource/index.js';
-import { runCommand } from './commands/run/index.js';
-import { stateCommand } from './commands/state/index.js';
+import { createTerraformResourceCommand } from './commands/create-terraform-resource/index.js';
+import { generateCommand } from './commands/generate/index.js';
+import { getResponseCommand } from './commands/get-response/index.js';
+import { lockCommand } from './commands/lock/index.js';
+import { runActionCommand } from './commands/run-action/index.js';
+import { unlockCommand } from './commands/unlock/index.js';
+import { validateCommand } from './commands/validate/index.js';
 const PROGRAM_NAME = 'octo';
 const parser = yargs(process.argv.slice(2))
     .scriptName(PROGRAM_NAME)
@@ -23,13 +29,19 @@ const parser = yargs(process.argv.slice(2))
     .alias('v', 'version');
 parser.command(createAnchorCommand);
 parser.command(createAppCommand);
-parser.command(createCdkCommand);
+parser.command(createExternalResourceCommand);
 parser.command(createModelCommand);
 parser.command(createModuleCommand);
 parser.command(createOverlayCommand);
-parser.command(createResourceCommand);
+parser.command(createTerraformResourceCommand);
+parser.command(applyCommand);
 parser.command(buildCommand);
-parser.command(runCommand);
-parser.command(stateCommand);
+parser.command(commitCommand);
+parser.command(generateCommand);
+parser.command(getResponseCommand);
+parser.command(lockCommand);
+parser.command(runActionCommand);
+parser.command(unlockCommand);
+parser.command(validateCommand);
 await parser.argv;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,MAAM,aAAa,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACxC,UAAU,CAAC,YAAY,CAAC;KACxB,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;KACnD,aAAa,CAAC,CAAC,EAAE,2BAA2B,CAAC;KAC7C,IAAI,EAAE;KACN,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC;KAClB,OAAO,EAAE;KACT,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AAEzB,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACpC,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AACjC,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AACjC,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AACnC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACpC,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACrC,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;AACtC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAC7B,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAC3B,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAE7B,MAAM,MAAM,CAAC,IAAI,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,MAAM,aAAa,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,+CAA+C,CAAC;AAC/F,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACxC,UAAU,CAAC,YAAY,CAAC;KACxB,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;KACnD,aAAa,CAAC,CAAC,EAAE,2BAA2B,CAAC;KAC7C,IAAI,EAAE;KACN,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC;KAClB,OAAO,EAAE;KACT,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AAEzB,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACpC,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AACjC,MAAM,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC;AAC9C,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AACnC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACpC,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACrC,MAAM,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;AAC/C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAC7B,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAC7B,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAC9B,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;AAChC,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AACnC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAC5B,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AACjC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAC9B,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;AAEhC,MAAM,MAAM,CAAC,IAAI,CAAC"}

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;
 }