@quadnix/octo-build 0.0.17 → 0.2.0

package/dist/commands/create-app/generator-octo-app-template/generators/app/templates/index.ts.ejs

@@ -0,0 +1,19 @@
+/**
+ * Custom Octo constructs for this app.
+ *
+ * The `create-*` commands maintain this file. Modules are exported because the definition file
+ * names them; everything else is imported for the registration side effect its decorator performs,
+ * which is what makes a construct known to Octo at boot.
+ *
+ * To use a module, `npm run build` and reference the built file from `octo.yaml`:
+ *
+ * ```yaml
+ * imports:
+ *   - className: MyModule
+ *     importPath: "./dist/index.js"
+ * ```
+ *
+ * An app that only composes the modules shipped by `@quadnix/octo-aws-cdk` needs nothing here.
+ */
+
+export {};

package/dist/commands/create-app/generator-octo-app-template/generators/app/templates/package.json.ejs

@@ -18,6 +18,7 @@
     "moduleNameMapper": {
       "(.+)\\.js": "$1"
     },
+    "passWithNoTests": true,
     "preset": "ts-jest/presets/default-esm",
     "rootDir": ".",
     "testEnvironment": "node",
@@ -32,9 +33,10 @@
     }
   },
   "keywords": [
-    "cdk",
     "infrastructure",
     "octo",
+    "terraform",
+    "terragrunt",
     "typescript"
   ],
   "name": "<%= name %>",
@@ -43,6 +45,12 @@
     "build": "rimraf dist && tsc -p tsconfig.build.json",
     "format": "prettier --write \"src/**/*.ts\"",
     "lint": "eslint .",
+    "octo:apply": "OCTO_DEFINITION_FILE_PATH=octo.yaml octo apply --terragruntDir .octo-tf",
+    "octo:commit": "OCTO_DEFINITION_FILE_PATH=octo.yaml octo commit --terragruntDir .octo-tf",
+    "octo:generate": "OCTO_DEFINITION_FILE_PATH=octo.yaml octo generate -o .octo-tf",
+    "octo:lock": "OCTO_DEFINITION_FILE_PATH=octo.yaml octo lock",
+    "octo:unlock": "OCTO_DEFINITION_FILE_PATH=octo.yaml octo unlock",
+    "octo:validate": "OCTO_DEFINITION_FILE_PATH=octo.yaml octo validate --terragruntDir .octo-tf",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --testRegex=\"\\.spec.ts$\"",
     "test:e2e": "NODE_OPTIONS=--experimental-vm-modules jest --testRegex=\"\\.e2e-spec.ts$\""
   },

package/dist/commands/create-app/generator-octo-app-template/generators/app/templates/src/aws-dynamodb-service/octo.yaml.ejs

@@ -0,0 +1,111 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/quadnix/octo/refs/heads/main/packages/octo-build/src/resources/octo-v1.schema.json
+
+version: 1
+
+env:
+  - key: AWS_ACCOUNT_ID
+    kind: string
+    value: "123456789123"
+
+terraform:
+  requiredVersion: "1.6.0"
+  requiredProviders:
+    aws:
+      source: hashicorp/aws
+  providers:
+    - providerType: aws
+      accountId: "${env.AWS_ACCOUNT_ID}"
+      # Optional. Puts a name in the generated provider alias in place of the account number.
+      # accountName: prod
+      regionId: us-east-1
+      spec:
+        profile: default
+
+settings:
+  listeners:
+    - type: JournalEventListener
+    - type: LoggingEventListener
+
+  stateProvider:
+    type: LocalStateProvider
+    statePath: .octo
+
+imports:
+  - className: SimpleAppModule
+    importPath: "@quadnix/octo-aws-cdk/modules/app/simple-app"
+  - className: AwsIniAccountModule
+    importPath: "@quadnix/octo-aws-cdk/modules/account/aws-ini-account"
+  - className: AwsSingleAzRegionModule
+    importPath: "@quadnix/octo-aws-cdk/modules/region/aws-single-az-region"
+  - className: AwsDynamoDBServiceModule
+    importPath: "@quadnix/octo-aws-cdk/modules/service/aws-dynamodb-service"
+
+modules:
+  - moduleId: app-module
+    moduleClass: SimpleAppModule
+    moduleInputs:
+      name: aws-dynamodb-service
+
+  - moduleId: account-module
+    moduleClass: AwsIniAccountModule
+    moduleInputs:
+      accountId: "${env.AWS_ACCOUNT_ID}"
+      app: "${{app-module.model.app}}"
+      iniProfile: default
+
+  - moduleId: region-module
+    moduleClass: AwsSingleAzRegionModule
+    moduleInputs:
+      account: "${{account-module.model.account}}"
+      name: app-region-east
+      regionId: aws-us-east-1a
+      vpcCidrBlock: 10.0.0.0/16
+
+  - moduleId: dynamodb-service-module
+    moduleClass: AwsDynamoDBServiceModule
+    moduleInputs:
+      # Every attribute a key schema or an index refers to must be declared here. DynamoDB is
+      # schemaless otherwise - attributes that are neither keys nor indexed are not declared.
+      AttributeDefinitions:
+        - AttributeName: AccountId
+          AttributeType: S
+        - AttributeName: AccountType
+          AttributeType: S
+        - AttributeName: CreatedAt
+          AttributeType: N
+        - AttributeName: UserId
+          AttributeType: S
+      billingMode:
+        type: PROVISIONED
+        settings:
+          ProvisionedThroughput:
+            ReadCapacityUnits: 5
+            WriteCapacityUnits: 5
+      # A global secondary index can be added or removed on a live table.
+      GlobalSecondaryIndexes:
+        - IndexName: AccountUserIndex
+          KeySchema:
+            - AttributeName: UserId
+              KeyType: HASH
+          Projection:
+            ProjectionType: ALL
+      KeySchema:
+        - AttributeName: AccountId
+          KeyType: HASH
+        - AttributeName: AccountType
+          KeyType: RANGE
+      # A local secondary index is fixed at table creation; changing one recreates the table.
+      LocalSecondaryIndexes:
+        - IndexName: AccountCreatedAtIndex
+          KeySchema:
+            - AttributeName: AccountId
+              KeyType: HASH
+            - AttributeName: CreatedAt
+              KeyType: RANGE
+          Projection:
+            ProjectionType: ALL
+      region: "${{region-module.model.region}}"
+      StreamSpecification:
+        StreamViewType: NEW_AND_OLD_IMAGES
+      TableName: accounts
+      timeToLiveAttribute: ExpiresAt

package/dist/commands/create-app/generator-octo-app-template/generators/app/templates/src/aws-ecs-server/octo.yaml.ejs

@@ -7,9 +7,23 @@ env:
     kind: string
     value: "123456789123"
 
+terraform:
+  requiredVersion: "1.6.0"
+  requiredProviders:
+    aws:
+      source: hashicorp/aws
+  providers:
+    - providerType: aws
+      accountId: "${env.AWS_ACCOUNT_ID}"
+      # Optional. Puts a name in the generated provider alias in place of the account number.
+      # accountName: prod
+      regionId: us-east-1
+      spec:
+        profile: default
+
 settings:
   listeners:
-    - type: HtmlReportEventListener
+    - type: JournalEventListener
     - type: LoggingEventListener
 
   stateProvider:
@@ -21,16 +35,16 @@ imports:
     importPath: "@quadnix/octo-aws-cdk/modules/app/simple-app"
   - className: AwsIniAccountModule
     importPath: "@quadnix/octo-aws-cdk/modules/account/aws-ini-account"
-  - className: AwsEcsDeploymentModule
-    importPath: "@quadnix/octo-aws-cdk/modules/deployment/aws-ecs-deployment"
+  - className: AwsDeploymentModule
+    importPath: "@quadnix/octo-aws-cdk/modules/deployment/aws-deployment"
   - className: AwsEcsEnvironmentModule
     importPath: "@quadnix/octo-aws-cdk/modules/environment/aws-ecs-environment"
   - className: AwsEcsExecutionModule
     importPath: "@quadnix/octo-aws-cdk/modules/execution/aws-ecs-execution"
   - className: AwsMultiAzRegionModule
     importPath: "@quadnix/octo-aws-cdk/modules/region/aws-multi-az-region"
-  - className: AwsEcsServerModule
-    importPath: "@quadnix/octo-aws-cdk/modules/server/aws-ecs-server"
+  - className: AwsServerModule
+    importPath: "@quadnix/octo-aws-cdk/modules/server/aws-server"
   - className: AwsEcsAlbServiceModule
     importPath: "@quadnix/octo-aws-cdk/modules/service/aws-ecs-alb-service"
   - className: AwsSimpleSubnetModule
@@ -59,24 +73,22 @@ modules:
       vpcCidrBlock: 10.0.0.0/16
 
   - moduleId: backend-server-module
-    moduleClass: AwsEcsServerModule
+    moduleClass: AwsServerModule
     moduleInputs:
       account: "${{account-module.model.account}}"
       serverKey: backend
 
   - moduleId: backend-deployment-v1-module
-    moduleClass: AwsEcsDeploymentModule
+    moduleClass: AwsDeploymentModule
     moduleInputs:
-      deploymentContainerProperties:
-        cpu: 256
-        image:
-          command: node webserver
-          ports:
-            - containerPort: 80
-              protocol: tcp
-          uri: docker.io/ealen/echo-server:0.9.2
-        memory: 512
+      command: [node, webserver]
+      cpu: 256
       deploymentTag: v1
+      imageUri: docker.io/ealen/echo-server:0.9.2
+      memory: 512
+      ports:
+        - containerPort: 80
+          protocol: tcp
       server: "${{backend-server-module.model.server}}"
 
   - moduleId: qa-environment-module

package/dist/commands/create-app/generator-octo-app-template/generators/app/templates/src/aws-s3-website/octo.yaml.ejs

@@ -10,9 +10,23 @@ env:
     kind: string
     value: my-website-unique-bucket
 
+terraform:
+  requiredVersion: "1.6.0"
+  requiredProviders:
+    aws:
+      source: hashicorp/aws
+  providers:
+    - providerType: aws
+      accountId: "${env.AWS_ACCOUNT_ID}"
+      # Optional. Puts a name in the generated provider alias in place of the account number.
+      # accountName: prod
+      regionId: us-east-1
+      spec:
+        profile: default
+
 settings:
   listeners:
-    - type: HtmlReportEventListener
+    - type: JournalEventListener
     - type: LoggingEventListener
 
   stateProvider:
@@ -24,6 +38,8 @@ imports:
     importPath: "@quadnix/octo-aws-cdk/modules/app/simple-app"
   - className: AwsIniAccountModule
     importPath: "@quadnix/octo-aws-cdk/modules/account/aws-ini-account"
+  - className: AwsServerlessRegionModule
+    importPath: "@quadnix/octo-aws-cdk/modules/region/aws-serverless-region"
   - className: AwsS3StaticWebsiteServiceModule
     importPath: "@quadnix/octo-aws-cdk/modules/service/aws-s3-static-website-service"
 
@@ -39,10 +55,16 @@ modules:
       accountId: "${env.AWS_ACCOUNT_ID}"
       app: "${{app-module.model.app}}"
 
+  - moduleId: region-module
+    moduleClass: AwsServerlessRegionModule
+    moduleInputs:
+      account: "${{account-module.model.account}}"
+      name: aws-s3-website
+      regionId: aws-us-east-1
+
   - moduleId: s3-website-service-module
     moduleClass: AwsS3StaticWebsiteServiceModule
     moduleInputs:
-      account: "${{account-module.model.account}}"
-      awsRegionId: us-east-1
       bucketName: "${env.AWS_S3_WEBSITE_BUCKET_NAME}"
       directoryPath: website
+      region: "${{region-module.model.region}}"

package/dist/commands/create-app/generator-octo-app-template/generators/app/templates/tsconfig.json.ejs

@@ -20,9 +20,6 @@
     "strictBindCallApply": true,
     "strictNullChecks": true,
     "target": "ES2022",
-    "typeRoots": [
-      "node_modules/@types"
-    ],
     "useDefineForClassFields": false,
     "verbatimModuleSyntax": true
   },

package/dist/commands/{create-resource/create-resource.command.d.ts → create-external-resource/create-external-resource.command.d.ts}

@@ -1,5 +1,5 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
-export declare const createResourceCommand: {
+export declare const createExternalResourceCommand: {
     builder: (yargs: Argv) => Argv;
     command: string;
     describe: string;

package/dist/commands/create-external-resource/create-external-resource.command.js

@@ -0,0 +1,64 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { createEnv } from 'yeoman-environment';
+import { StringUtility } from '../../utilities/string/string.utility.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const createExternalResourceCommand = {
+    builder: (yargs) => {
+        return yargs
+            .option('name', {
+            alias: 'n',
+            demandOption: true,
+            description: 'Name of the resource to create. Should be in kebab-case (e.g., my-awesome-resource).',
+            type: 'string',
+        })
+            .option('package', {
+            demandOption: true,
+            description: 'Package name for the resource.',
+            type: 'string',
+        })
+            .option('path', {
+            alias: 'p',
+            default: '.',
+            description: 'Root directory path of the project.',
+            type: 'string',
+        });
+    },
+    command: 'create-external-resource',
+    // Named for the lifecycle, not as the general case: a resource terraform manages is the common
+    // one, and that is `create-terraform-resource`. This generator emits the other kind - a resource
+    // whose add/delete run as SDK calls, which terraform drives by shelling back into `run-action`.
+    describe: 'Create a new Octo resource whose lifecycle runs outside Terraform.',
+    handler: async (argv) => {
+        const { name, package: packageName, path } = argv;
+        // Validate resource name format (should be kebab-case)
+        if (!StringUtility.isKebabCase(name)) {
+            console.error(chalk.red('Resource name must be in kebab-case format (e.g., my-vpc)'));
+            process.exit(1);
+        }
+        // Rejected here rather than at registration: the decorator runs this same check, but only once
+        // the generated resource is loaded, long after the files are on disk.
+        if (!StringUtility.isValidPackageName(packageName)) {
+            console.error(chalk.red(`Invalid package name "${packageName}"! Expected e.g. @octo or my-package.`));
+            process.exit(1);
+        }
+        console.log(chalk.blue(`Creating external resource "${name}" with package "${packageName}"...`));
+        const env = createEnv();
+        env.register(resolve(__dirname, 'generator-octo-external-resource-template/generators/app/index.js'), {
+            namespace: 'generator-octo-external-resource-template:app',
+        });
+        try {
+            await env.run(['generator-octo-external-resource-template:app', name, packageName, path], {
+                skipCache: true,
+                skipInstall: true,
+            });
+            console.log(chalk.green(`Successfully created external resource!`));
+        }
+        catch (error) {
+            console.error(chalk.red(`Failed to create external resource! ${error.message}`));
+            process.exit(1);
+        }
+    },
+};
+//# sourceMappingURL=create-external-resource.command.js.map

package/dist/commands/create-external-resource/create-external-resource.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-external-resource.command.js","sourceRoot":"","sources":["../../../src/commands/create-external-resource/create-external-resource.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAEzE,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,OAAO,EAAE,CAAC,KAAW,EAAQ,EAAE;QAC7B,OAAO,KAAK;aACT,MAAM,CAAC,MAAM,EAAE;YACd,KAAK,EAAE,GAAG;YACV,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,sFAAsF;YACnG,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,SAAS,EAAE;YACjB,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,gCAAgC;YAC7C,IAAI,EAAE,QAAQ;SACf,CAAC;aACD,MAAM,CAAC,MAAM,EAAE;YACd,KAAK,EAAE,GAAG;YACV,OAAO,EAAE,GAAG;YACZ,WAAW,EAAE,qCAAqC;YAClD,IAAI,EAAE,QAAQ;SACf,CAAC,CAAC;IACP,CAAC;IACD,OAAO,EAAE,0BAA0B;IACnC,+FAA+F;IAC/F,iGAAiG;IACjG,gGAAgG;IAChG,QAAQ,EAAE,oEAAoE;IAC9E,OAAO,EAAE,KAAK,EAAE,IAAyE,EAAiB,EAAE;QAC1G,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;QAElD,uDAAuD;QACvD,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC,CAAC;YACtF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,+FAA+F;QAC/F,sEAAsE;QACtE,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAyB,WAAW,uCAAuC,CAAC,CAAC,CAAC;YACtG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,+BAA+B,IAAI,mBAAmB,WAAW,MAAM,CAAC,CAAC,CAAC;QAEjG,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;QACxB,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,mEAAmE,CAAC,EAAE;YACpG,SAAS,EAAE,+CAA+C;SAC3D,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,+CAA+C,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;gBACxF,SAAS,EAAE,IAAI;gBACf,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;YAEH,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,uCAAuC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/commands/{create-resource/generator-octo-resource-template → create-external-resource/generator-octo-external-resource-template}/generators/app/index.d.ts

@@ -1,10 +1,25 @@
 import Generator, { type BaseOptions } from 'yeoman-generator';
+/**
+ * @internal
+ */
 export default class extends Generator {
-    private readonly cdkRootDir;
     private readonly packageName;
+    private readonly projectRootDir;
     private readonly resourceName;
+    /**
+     * @internal
+     */
     constructor(args: string[], opts: BaseOptions);
+    /**
+     * @internal
+     */
+    end(): void;
+    /**
+     * @internal
+     */
     initializing(): Promise<void>;
+    /**
+     * @internal
+     */
     writing(): Promise<void>;
-    end(): void;
 }

package/dist/commands/{create-resource/generator-octo-resource-template → create-external-resource/generator-octo-external-resource-template}/generators/app/index.js

@@ -1,16 +1,37 @@
 import { readdir, stat } from 'fs/promises';
 import { join, resolve } from 'path';
 import Generator, {} from 'yeoman-generator';
+import { ProjectIndexUtility } from '../../../../../utilities/project-index/project-index.utility.js';
 import { StringUtility } from '../../../../../utilities/string/string.utility.js';
+/**
+ * @internal
+ */
 export default class extends Generator {
+    /**
+     * @internal
+     */
     constructor(args, opts) {
         super(args, opts);
         this.resourceName = args[0];
         this.packageName = args[1];
-        this.cdkRootDir = args[2];
+        this.projectRootDir = args[2];
     }
+    /**
+     * @internal
+     */
+    end() {
+        const targetPath = resolve(join(this.projectRootDir, 'src', 'resources', this.resourceName));
+        this.log('✅ Your external resource has been generated successfully!');
+        this.log(`📁 Resource created at: ${targetPath}`);
+        ProjectIndexUtility.addImport(this.projectRootDir, `./resources/${this.resourceName}/index.js`);
+        this.log('📦 Next steps:');
+        this.log(`   Address all "Fix me" in generated files`);
+    }
+    /**
+     * @internal
+     */
     async initializing() {
-        const targetPath = resolve(join(this.cdkRootDir, 'src', 'resources', this.resourceName));
+        const targetPath = resolve(join(this.projectRootDir, 'src', 'resources', this.resourceName));
         // Check if directory already exists and is not empty.
         let targetPathStat;
         try {
@@ -30,46 +51,26 @@ export default class extends Generator {
         // Set the destination root to the resource directory.
         this.destinationRoot(targetPath);
     }
+    /**
+     * @internal
+     */
     async writing() {
-        // Create the resource file.
-        this.fs.copyTpl(this.templatePath('resources/resource/resource.ts.ejs'), this.destinationPath(`${this.resourceName}.resource.ts`), {
+        const templateData = {
             packageName: this.packageName,
             resourceName: this.resourceName,
+            resourceNameCamel: StringUtility.toCamelCase(this.resourceName),
             resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
+        };
+        // Create the resource file.
+        this.fs.copyTpl(this.templatePath('resources/resource/resource.ts.ejs'), this.destinationPath(`${this.resourceName}.resource.ts`), templateData);
         // Create schema file.
-        this.fs.copyTpl(this.templatePath('resources/resource/index.schema.ts.ejs'), this.destinationPath('index.schema.ts'), {
-            resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
+        this.fs.copyTpl(this.templatePath('resources/resource/index.schema.ts.ejs'), this.destinationPath('index.schema.ts'), templateData);
         // Create index.ts
-        this.fs.copyTpl(this.templatePath('resources/resource/index.ts.ejs'), this.destinationPath('index.ts'), {
-            resourceName: this.resourceName,
-            resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
+        this.fs.copyTpl(this.templatePath('resources/resource/index.ts.ejs'), this.destinationPath('index.ts'), templateData);
         // Create actions directory and action files
-        this.fs.copyTpl(this.templatePath('resources/resource/actions/add.resource.action.ts.ejs'), this.destinationPath('actions', `add-${this.resourceName}.resource.action.ts`), {
-            resourceName: this.resourceName,
-            resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
-        this.fs.copyTpl(this.templatePath('resources/resource/actions/delete.resource.action.ts.ejs'), this.destinationPath('actions', `delete-${this.resourceName}.resource.action.ts`), {
-            resourceName: this.resourceName,
-            resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
-        this.fs.copyTpl(this.templatePath('resources/resource/actions/update-tags.resource.action.ts.ejs'), this.destinationPath('actions', `update-${this.resourceName}-tags.resource.action.ts`), {
-            resourceName: this.resourceName,
-            resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
-        this.fs.copyTpl(this.templatePath('resources/resource/actions/validate.resource.action.ts.ejs'), this.destinationPath('actions', `validate-${this.resourceName}.resource.action.ts`), {
-            resourceName: this.resourceName,
-            resourceNamePascal: StringUtility.toPascalCase(this.resourceName),
-        });
-    }
-    end() {
-        const targetPath = resolve(join(this.cdkRootDir, 'src', 'resources', this.resourceName));
-        this.log('✅ Your resource has been generated successfully!');
-        this.log(`📁 Resource created at: ${targetPath}`);
-        this.log('📦 Next steps:');
-        this.log(`   Address all "Fix me" in generated files`);
+        this.fs.copyTpl(this.templatePath('resources/resource/actions/add.resource.action.ts.ejs'), this.destinationPath('actions', `add-${this.resourceName}.resource.action.ts`), templateData);
+        this.fs.copyTpl(this.templatePath('resources/resource/actions/delete.resource.action.ts.ejs'), this.destinationPath('actions', `delete-${this.resourceName}.resource.action.ts`), templateData);
+        this.fs.copyTpl(this.templatePath('resources/resource/actions/update.resource.action.ts.ejs'), this.destinationPath('actions', `update-${this.resourceName}.resource.action.ts`), templateData);
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/commands/create-external-resource/generator-octo-external-resource-template/generators/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/commands/create-external-resource/generator-octo-external-resource-template/generators/app/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/{create-resource/generator-octo-resource-template → create-external-resource/generator-octo-external-resource-template}/generators/app/templates/resources/resource/actions/add.resource.action.ts.ejs

@@ -19,25 +19,16 @@ export class Add<%= resourceNamePascal %>ResourceAction extends ANodeAction impl
 
   async handle(diff: Diff<<%= resourceNamePascal %>>): Promise<<%= resourceNamePascal %>Schema['response']> {
     // Get properties.
-    const <%= resourceName %> = diff.node;
-    const properties = <%= resourceName %>.properties;
-    const response = <%= resourceName %>.response;
-    const tags = <%= resourceName %>.tags;
+    const <%= resourceNameCamel %> = diff.node;
+    const properties = <%= resourceNameCamel %>.properties;
+    const response = <%= resourceNameCamel %>.response;
+    const tags = <%= resourceNameCamel %>.tags;
 
     // Fix me: Implement the add resource logic.
-    // This is where you would create the actual resource.
+    // This is where you would create the actual resource (SDK call, script, API request, ...).
 
-    // Fix me: Return response properties.
-    return response;
-  }
-
-  async mock(diff: Diff<<%= resourceNamePascal %>>, capture: Partial<<%= resourceNamePascal %>Schema['response']>): Promise<<%= resourceNamePascal %>Schema['response']> {
-    // Get properties.
-    const <%= resourceName %> = diff.node;
-    const properties = <%= resourceName %>.properties;
-    const response = <%= resourceName %>.response;
-
-    // Fix me: Return response using captures.
+    // Fix me: Populate and return every declared response key. Each key must be declared on the
+    // schema's `response` so Octo can emit it as a Terraform output.
     return response;
   }
 }

package/dist/commands/{create-resource/generator-octo-resource-template → create-external-resource/generator-octo-external-resource-template}/generators/app/templates/resources/resource/actions/delete.resource.action.ts.ejs

@@ -1,6 +1,24 @@
 import { ANodeAction, Action, type Diff, DiffAction, Factory, type IResourceAction, hasNodeName } from '@quadnix/octo';
 import { <%= resourceNamePascal %> } from '../<%= resourceName %>.resource.js';
 
+/**
+ * Deletes the resource.
+ *
+ * Unlike add and update, this does **not** run mid-apply. Terraform cannot run it: octo deletes a
+ * resource by removing its block from the configuration, and terraform will not run a
+ * `when = destroy` provisioner for a resource that is no longer in the configuration. So `octo
+ * commit` runs this instead, from the project directory, after terraform has destroyed the
+ * `null_resource`.
+ *
+ * Two consequences worth designing around:
+ *
+ * - **The working directory is not the one add and update saw.** Those run inside a terragrunt
+ *   cache directory; this runs wherever `octo commit` was invoked. Anything positional - a relative
+ *   file path, a relative config lookup - resolves somewhere else. Build absolute paths from a
+ *   module input rather than assuming a cwd.
+ * - **Throwing here aborts the commit**, on purpose: octo state then still records the resource, so
+ *   the next run diffs it again and retries. Failing loudly is better than a silent leak.
+ */
 @Action(<%= resourceNamePascal %>)
 export class Delete<%= resourceNamePascal %>ResourceAction extends ANodeAction implements IResourceAction<<%= resourceNamePascal %>> {
   constructor() {
@@ -18,9 +36,9 @@ export class Delete<%= resourceNamePascal %>ResourceAction extends ANodeAction i
 
   async handle(diff: Diff<<%= resourceNamePascal %>>): Promise<void> {
     // Get properties.
-    const <%= resourceName %> = diff.node;
-    const properties = <%= resourceName %>.properties;
-    const response = <%= resourceName %>.response;
+    const <%= resourceNameCamel %> = diff.node;
+    const properties = <%= resourceNameCamel %>.properties;
+    const response = <%= resourceNameCamel %>.response;
 
     // Fix me: Implement the delete resource logic.
     // This is where you would delete the actual resource.

package/dist/commands/create-external-resource/generator-octo-external-resource-template/generators/app/templates/resources/resource/actions/update.resource.action.ts.ejs

@@ -0,0 +1,63 @@
+import { ANodeAction, Action, type Diff, DiffAction, Factory, type IResourceAction, hasNodeName } from '@quadnix/octo';
+import type { <%= resourceNamePascal %>Schema } from '../index.schema.js';
+import { <%= resourceNamePascal %> } from '../<%= resourceName %>.resource.js';
+
+/**
+ * Handles the two `UPDATE` diffs an external resource receives.
+ *
+ * Neither is optional: a diff that no registered action matches aborts the whole transaction with
+ * "No matching action given for diff!". Deleting this file means a generated resource works until
+ * its first change and then refuses to apply at all.
+ *
+ * - **`properties`** - the default `diffProperties()` emits this whenever a property changes. You
+ *   own the partial-update semantics. `diff.value` carries the changed properties; the resource's
+ *   `properties` already hold the new values. If the underlying API cannot change an attribute in
+ *   place, do not silently skip it - either recreate it here, or override `diffProperties()` on the
+ *   resource to return `DiffAction.REPLACE` with a reason, which routes the change through the add
+ *   and delete actions instead.
+ * - **`parent`** - emitted when a parent is replaced, with `diff.value` naming the new parent. The
+ *   parent's outputs are this resource's inputs, so they have just changed underneath it: re-read
+ *   them from `this.parents` and re-apply. Skipping this case is how an external resource ends up
+ *   pointing at a parent that no longer exists.
+ */
+@Action(<%= resourceNamePascal %>)
+export class Update<%= resourceNamePascal %>ResourceAction extends ANodeAction implements IResourceAction<<%= resourceNamePascal %>> {
+  constructor() {
+    super();
+  }
+
+  filter(diff: Diff): boolean {
+    return (
+      diff.action === DiffAction.UPDATE &&
+      diff.node instanceof <%= resourceNamePascal %> &&
+      hasNodeName(diff.node, '<%= resourceName %>') &&
+      (diff.field === 'properties' || diff.field === 'parent')
+    );
+  }
+
+  async handle(diff: Diff<<%= resourceNamePascal %>>): Promise<<%= resourceNamePascal %>Schema['response']> {
+    // Get properties.
+    const <%= resourceNameCamel %> = diff.node;
+    const properties = <%= resourceNameCamel %>.properties;
+    const response = <%= resourceNameCamel %>.response;
+
+    // Fix me: Implement the update resource logic.
+    // This is where you would apply the changed properties to the actual resource.
+
+    // Fix me: Return every declared response key, re-reading any the update changed. Returning the
+    // response unchanged is what an unimplemented update looks like, and it reports success.
+    return response;
+  }
+}
+
+@Factory<Update<%= resourceNamePascal %>ResourceAction>(Update<%= resourceNamePascal %>ResourceAction)
+export class Update<%= resourceNamePascal %>ResourceActionFactory {
+  private static instance: Update<%= resourceNamePascal %>ResourceAction;
+
+  static async create(): Promise<Update<%= resourceNamePascal %>ResourceAction> {
+    if (!this.instance) {
+      this.instance = new Update<%= resourceNamePascal %>ResourceAction();
+    }
+    return this.instance;
+  }
+}