@quadnix/octo 0.0.30 → 0.2.0

package/README.md

@@ -1,13 +1,122 @@
 # Octo
-http://octo.quadnix.com/
 
-The open-source infrastructure management and CICD tool.
+Infrastructure as code written as intent: you describe an app and what it needs, modules turn that
+into Terraform, and your own Terragrunt applies it. Users start at
+[octo.quadnix.com](https://octo.quadnix.com/).
 
-> Disclaimer,
-> This library is still under development and is currently in version `0.x.x`.
-> We plan to release version `1.x.x` when it is deemed ready for production use.
+> Octo is in `0.x`. Version `1.x` will mark it ready for production.
 
-# Local Setup
-> npm install
+**This README is a set of procedures for working on the repository.** `docs/ARCHITECTURE.md`
+explains what exists, and `docs/CODING-STANDARDS.md` how to add to it.
 
-> npm run prepare
+Requires Node 20 or newer, Terraform or OpenTofu 1.6 or newer, and Terragrunt 0.78 or newer. The
+integration suites also need Docker, and the e2e suites AWS credentials.
+
+---
+
+## A — Set up this machine
+
+Once.
+
+```sh
+corepack enable
+pnpm install
+pnpm run prepare
+```
+
+`prepare` installs the pre-commit hook, which runs the format check, lint, the build with its type
+check, the circular-dependency check, the secrets spec and the docs code-block check.
+
+## B — Build, lint and test
+
+```sh
+pnpm run build
+pnpm run lint
+pnpm test
+```
+
+`octo-aws-cdk`, `octo-event-listeners`, `octo-build` and `octo-templates` import `octo` from its
+`dist`, and `octo-templates` imports `octo-aws-cdk` the same way. **Rebuild what you changed before
+testing what depends on it**, or the suite runs against the old code and still passes.
+
+`pnpm run build` also type-checks every package, tests included, through each package's
+`check:types`.
+
+`pnpm run format` writes what `pnpm run format:check` checks. Lint does not check formatting.
+
+`pnpm run lint:fix` sorts imports, members and keys. A flag passed through `pnpm run` is written
+without `--`: pnpm forwards the separator, and the script then drops the flag.
+
+## C — Run integration tests
+
+Integration specs run real Terraform; `octo-templates`' start LocalStack in Docker.
+
+```sh
+pnpm run test:integration
+```
+
+## D — Run an e2e suite
+
+**Every e2e suite reaches a live AWS account.** `octo-aws-cdk`'s plan and apply nothing;
+`octo-templates`' create real resources and tear them down.
+
+1. Copy the `.env.defaults` beside the suite to `.env` and fill in real values. `.env` is ignored.
+2. Build the packages the suite imports:
+
+   ```sh
+   npx nx run-many -t build --projects=octo,octo-event-listeners,octo-aws-cdk
+   ```
+
+3. Run one spec, by path, from its package:
+
+   ```sh
+   cd packages/octo-templates
+   NODE_OPTIONS=--experimental-vm-modules npx jest --runTestsByPath src/<template>/main.e2e-spec.ts
+   ```
+
+Never `pnpm run test:e2e` — it runs every suite live at once. Never combine `-u` with `-t`: jest then
+deletes the snapshots of every test it skipped. A template's own `README.md`, where it has one,
+holds what is particular to it.
+
+## E — Work in a worktree
+
+For a large change or a hands-free agent run:
+
+```sh
+git worktree add ../ai-worktrees/octo-worktree-<branch> -b ai/<branch>
+WORKTREE=../ai-worktrees/octo-worktree-<branch>
+find . -maxdepth 4 -name node_modules -type d ! -path "*/node_modules/*/node_modules" | \
+  while read src; do
+    mkdir -p "$WORKTREE/$(dirname $src)"
+    ln -s "$(pwd)/$src" "$WORKTREE/$src"
+  done
+```
+
+The symlinks let Nx and Jest resolve packages. Run lint and tests from inside the worktree.
+
+## F — Release
+
+1. Merge to `main` with PR titles per `.github/jobs/validate-pr-title.job.sh`. The commit type sets
+   the bump: `chore` releases nothing.
+2. Run the **Manual Release** workflow on `main`. It versions every changed package, tags, writes
+   the changelog, and publishes to npm.
+
+## Environment variables
+
+Everything outside the code that governs how this repository behaves. A suite's `.env` is read
+through `env-smart`, falling back to the `.env.defaults` beside it.
+
+| Variable                                                                                            | Set by                                        | What it does                                                                                                                                                                                                        |
+|-----------------------------------------------------------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `AWS_ACCOUNT_ID`                                                                                    | a suite's `.env`                              | The account every e2e suite plans or applies into.                                                                                                                                                                  |
+| `AWS_REGION_ID`                                                                                     | `packages/octo-aws-cdk/test/.env`             | The region the module e2es plan into. Template suites hardcode `us-east-1`.                                                                                                                                         |
+| `OCTO_DEFINITION_FILE_PATH`                                                                         | the user, or a `create-app` project's scripts | The `octo.yaml` every lifecycle command boots from. `OctoCliUtility` sets it for the CLI-driven template suites. A relative path is resolved once against the working directory, so `run-action` callbacks find it. |
+| `OCTO_JOURNAL_COMMAND_ID`                                                                           | `JournalEventListener`                        | The running command's id, set for every process it starts, so a `run-action` that Terraform starts mid-apply names that apply as `parentCommandId` in its journal.                                                  |
+| `TF_VAR_OCTO_PROJECT_ROOT`                                                                          | `TerraformUtility`, unless already set        | The working directory, so `terraform.localPath()` paths resolve inside Terragrunt's cache copy of a folder.                                                                                                         |
+| `TG_LOG_CUSTOM_FORMAT`                                                                              | `TerraformUtility`, always                    | Terragrunt's log line layout, its default without the time, since the journal records when each line arrived.                                                                                                       |
+| `TG_LOG_FORMAT`                                                                                     | `TerraformUtility`, always unset              | Unset for every Terragrunt process, so it cannot override `TG_LOG_CUSTOM_FORMAT`.                                                                                                                                   |
+| `TG_PROVIDER_CACHE`                                                                                 | `TerraformUtility`, unless already set        | `1`, so Terragrunt shares one provider cache across folders.                                                                                                                                                        |
+| `TG_TF_PATH`                                                                                        | `TerraformUtility`, from `--terraformBinary`  | Which Terraform or OpenTofu binary Terragrunt runs.                                                                                                                                                                 |
+| `NODE_OPTIONS`                                                                                      | every package's test scripts                  | `--experimental-vm-modules`, which Jest needs to run ESM. Set it yourself when running `jest` directly.                                                                                                             |
+| `OCTO_STAGE`, `OCTO_PHASE`, `OCTO_NAT`, `OCTO_TARGET`, `OCTO_WORK`, `OCTO_CASE`, `OCTO_PROBE_STATE` | you, by hand                                  | Drive the `aws-ecs-server` debugging harnesses; that template's `README.md` describes each.                                                                                                                         |
+| `GH_TOKEN`                                                                                          | a repository secret                           | Checkout and push in **Manual Release**, and the tags and GitHub releases `nx release` creates.                                                                                                                     |

package/dist/app.type.d.ts

@@ -1,8 +1,20 @@
 import type { IDependency } from './functions/dependency/dependency.js';
 import type { ANode } from './functions/node/node.abstract.js';
+import type { AccountSchema } from './models/account/account.schema.js';
+import type { AppSchema } from './models/app/app.schema.js';
+import type { DeploymentSchema } from './models/deployment/deployment.schema.js';
+import type { EnvironmentSchema } from './models/environment/environment.schema.js';
+import type { ExecutionSchema } from './models/execution/execution.schema.js';
+import type { FilesystemSchema } from './models/filesystem/filesystem.schema.js';
+import type { ImageSchema } from './models/image/image.schema.js';
 import type { IModelAction } from './models/model-action.interface.js';
 import type { AModel } from './models/model.abstract.js';
-import type { IModel, IModelReference } from './models/model.interface.js';
+import type { IModel } from './models/model.interface.js';
+import type { PipelineSchema } from './models/pipeline/pipeline.schema.js';
+import type { RegionSchema } from './models/region/region.schema.js';
+import type { ServerSchema } from './models/server/server.schema.js';
+import type { ServiceSchema } from './models/service/service.schema.js';
+import type { SubnetSchema } from './models/subnet/subnet.schema.js';
 import type { AModule } from './modules/module.abstract.js';
 import type { AAnchor } from './overlays/anchor.abstract.js';
 import type { BaseAnchorSchema } from './overlays/anchor.schema.js';
@@ -13,38 +25,89 @@ import type { AResource } from './resources/resource.abstract.js';
 import type { BaseResourceSchema } from './resources/resource.schema.js';
 import type { ValidationUtility } from './utilities/validation/validation.utility.js';
 /**
+ * An anchor found by schema, paired with the translation needed to read it as that schema.
+ *
+ * {@link AModel.getAnchorsMatchingSchema} returns these rather than raw anchors: the anchor you
+ * matched may have been declared against a different version of the schema, and this is what keeps
+ * that difference out of your module. Read it with `getSchemaInstance()`.
+ *
  * @group Types
  */
 export declare class MatchingAnchor<S extends BaseAnchorSchema> {
     private readonly actual;
     private readonly schemaTranslator?;
+    /**
+     * @param actual The anchor that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual: AAnchor<S, any>, schemaTranslator?: ((synth: any) => S) | undefined);
-    hasSchemaTranslator(): boolean;
+    /**
+     * The anchor itself, with its properties hidden - read those through
+     * {@link MatchingAnchor.getSchemaInstance}.
+     */
     getActual(): AAnchor<Omit<S, 'properties'> & {
         properties: Record<never, never>;
     }, any>;
+    /**
+     * The anchor read as the schema you matched on.
+     */
     getSchemaInstance(): S;
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator(): boolean;
 }
 /**
+ * A model found by schema. See {@link MatchingAnchor}.
+ *
  * @group Types
  */
 export declare class MatchingModel<S extends object> {
     private readonly actual;
     private readonly schemaTranslator?;
+    /**
+     * @param actual The model that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual: AModel<S, any>, schemaTranslator?: ((synth: any) => S) | undefined);
-    hasSchemaTranslator(): boolean;
+    /**
+     * The model itself, with its schema hidden - read it through
+     * {@link MatchingModel.getSchemaInstance}.
+     */
     getActual(): AModel<Record<never, never>, any>;
+    /**
+     * The model read as the schema you matched on.
+     */
     getSchemaInstance(): S;
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator(): boolean;
 }
 /**
+ * A resource found by schema. See {@link MatchingAnchor}.
+ *
+ * Pass one wherever a resource parent is expected, and the translation is carried into the graph, so
+ * the child keeps reading its parent through the schema it was written against.
+ *
  * @group Types
  */
 export declare class MatchingResource<S extends BaseResourceSchema> {
     private readonly actual;
     readonly schemaTranslator?: ((synth: BaseResourceSchema) => S) | undefined;
+    /**
+     * @param actual The resource that was matched.
+     * @param schemaTranslator Reads `actual` as the matched schema, when the two differ.
+     */
     constructor(actual: AResource<S, any>, schemaTranslator?: ((synth: BaseResourceSchema) => S) | undefined);
+    /**
+     * @internal
+     */
     addChild(...args: Parameters<AResource<BaseResourceSchema, any>['addChild']>): ReturnType<AResource<BaseResourceSchema, any>['addChild']>;
-    hasSchemaTranslator(): boolean;
+    /**
+     * The resource itself, with its schema hidden - read it through
+     * {@link MatchingResource.getSchemaInstance}.
+     */
     getActual(): AResource<Omit<S, 'properties' | 'response' | 'tags'> & {
         properties: Record<never, never>;
     } & {
@@ -52,10 +115,21 @@ export declare class MatchingResource<S extends BaseResourceSchema> {
     } & {
         tags: Record<never, never>;
     }, any>;
+    /**
+     * The resource read as the schema you matched on.
+     */
     getSchemaInstance(): S;
+    /**
+     * The resource read as the schema you matched on, with its `response` typed as fully populated.
+     * Only call it from a resource action, where the parent is guaranteed to already exist.
+     */
     getSchemaInstanceInResourceAction(): Omit<S, 'response'> & {
         response: Required<S['response']>;
     };
+    /**
+     * Whether the match went through a schema translation.
+     */
+    hasSchemaTranslator(): boolean;
 }
 /**
  * @internal
@@ -92,10 +166,19 @@ export type ValidationTypeOptions = {
     [ValidationType.REGEX]: Parameters<typeof ValidationUtility.validateRegex>[1];
 };
 /**
+ * Whether a node was registered under the given name, e.g. `region`.
+ *
+ * Use it to identify a base model without importing the subclass that implements it.
+ *
  * @group Types
  */
 export declare function hasNodeName(node: UnknownNode, nodeName: string): boolean;
 /**
+ * Marks a placeholder value that a later step fills in - typically a resource property whose real
+ * value is only known once the infrastructure exists.
+ *
+ * It is a type assertion and nothing more; it emits the string you give it.
+ *
  * @group Types
  */
 export declare function stub<T>(value: string): T;
@@ -104,6 +187,8 @@ export declare function stub<T>(value: string): T;
  */
 export type ActionInputs = EnhancedModuleSchema<UnknownModule>;
 /**
+ * The resources an action declared, keyed by an ID of your choosing.
+ *
  * @group Types
  */
 export type ActionOutputs = {
@@ -119,6 +204,8 @@ export type ClassOptionalProperties<T> = {
     [K in keyof T]: undefined extends T[K] ? K : never;
 }[keyof T];
 /**
+ * The `value` of a {@link Diff} on a `properties` field: which property changed, and to what.
+ *
  * @group Types
  */
 export type DiffValueTypePropertyUpdate = {
@@ -126,6 +213,8 @@ export type DiffValueTypePropertyUpdate = {
     value: unknown;
 };
 /**
+ * The `value` of a {@link Diff} on a `tags` field, split by what happened to each tag.
+ *
  * @group Types
  */
 export type DiffValueTypeTagUpdate = {
@@ -147,63 +236,222 @@ export type ObjectKeyValue<T> = {
     };
 }[keyof T];
 /**
+ * The class of `T`, i.e. what you pass when an API wants a type rather than an instance.
+ *
  * @group Types
  */
 export type Constructable<T> = new (...args: any[]) => T;
 /**
+ * A class of `T`, abstract or not, i.e. what you pass to name a family of classes.
+ *
+ * @group Types
+ */
+export type AbstractConstructable<T> = abstract new (...args: any[]) => T;
+/**
+ * An anchor as written to state.
+ *
+ * @group Types
+ */
+export type AnchorSerializedOutput = {
+    anchorId: string;
+    parent: {
+        context: string;
+        type: `${NodeType}`;
+    };
+    properties: {
+        [key: string]: unknown;
+    };
+};
+/**
+ * The schema of each base model, by the name it registers with `@Model`.
+ */
+type BaseModelSchemas = {
+    account: AccountSchema;
+    app: AppSchema;
+    deployment: DeploymentSchema;
+    environment: EnvironmentSchema;
+    execution: ExecutionSchema;
+    filesystem: FilesystemSchema;
+    image: ImageSchema;
+    pipeline: PipelineSchema;
+    region: RegionSchema;
+    server: ServerSchema;
+    service: ServiceSchema;
+    subnet: SubnetSchema;
+};
+/**
+ * @internal
+ */
+export type ModelName = keyof BaseModelSchemas;
+/**
+ * The model graph as written to `models.json`.
+ * * `nodeName` names the base model an entry extends, and types its `model` as that base model's
+ * schema. A model's own fields beyond it are not typed.
+ * * `modules` record inputs before references resolve.
+ *
  * @group Types
  */
 export type ModelSerializedOutput = {
-    anchors: (AnchorSchema<UnknownAnchor> & {
+    anchors: (AnchorSerializedOutput & {
         className: string;
-        location: IModelReference & {
-            type: NodeType;
+        location: {
+            context: string;
+            type: `${NodeType}`;
         };
     })[];
     dependencies: IDependency[];
     models: {
-        [p: string]: {
+        [context: string]: {
+            [N in ModelName]: {
+                className: string;
+                model: BaseModelSchemas[N];
+                moduleId: string;
+                nodeName: N;
+            };
+        }[ModelName];
+    };
+    modules: {
+        [moduleId: string]: {
             className: string;
-            model: IUnknownModel;
+            inputs: {
+                [key: string]: unknown;
+            };
         };
     };
     overlays: {
         className: string;
-        overlay: OverlaySchema<UnknownOverlay>;
+        context: string;
+        moduleId: string;
+        overlay: {
+            anchors: AnchorSerializedOutput[];
+            overlayId: string;
+            properties: {
+                [key: string]: unknown;
+            };
+        };
+    }[];
+};
+/**
+ * A resource as written to state.
+ * * `parentSchemaTranslator` is the source of the function a child reads that parent through.
+ *
+ * @group Types
+ */
+export type ResourceSerializedSchema = {
+    localResourceId: string;
+    parents: {
+        context: string;
+        parentSchemaTranslator?: string;
     }[];
+    properties: {
+        [key: string]: unknown;
+    };
+    resourceId: string;
+    response: {
+        [key: string]: string;
+    };
+    scope: string[];
+    tags: {
+        [key: string]: string;
+    };
 };
 /**
+ * The resource graph as written to `resources-actual.json` and `resources-old.json`.
+ * * `createdBy` is the context of the model or overlay whose action created the resource.
+ * * `models` record the context of every model and overlay whose action produced the resource.
+ *
  * @group Types
  */
 export type ResourceSerializedOutput = {
     dependencies: IDependency[];
     resources: {
-        [p: string]: {
+        [context: string]: {
             className: string;
-            resource: BaseResourceSchema;
+            createdBy?: string;
+            kind: 'external' | 'terraform';
+            models: string[];
+            moduleId: string;
+            resource: ResourceSerializedSchema;
         };
     };
 };
+/**
+ * A record of one generated terraform module folder, kept in state so that a later run can tell
+ * which folders it owns.
+ *
+ * @group Types
+ */
+export type TerraformFolderOutput = {
+    hasExternalResources: boolean;
+    moduleId: string;
+    /**
+     * The resources whose terraform state moves into this folder from another before terraform runs,
+     * each with the addresses and output names it moves from and to.
+     */
+    moves?: {
+        addresses: {
+            from: string;
+            to: string;
+        }[];
+        fromModuleId: string;
+        outputs: {
+            from: string;
+            to: string;
+        }[];
+        resourceId: string;
+    }[];
+    providers: {
+        accountId: string;
+        blockHcl: string;
+        providerType: string;
+        regionId: string;
+        requiredProvider: {
+            minVersion?: string;
+            source: string;
+        };
+    }[];
+};
+/**
+ * A record of where one octo resource ended up in terraform, kept in state so that a plan entry can
+ * be traced back to the resource that produced it.
+ *
+ * @group Types
+ */
+export type TerraformResourceOutput = {
+    /**
+     * Set when destroying the resource loses data, as its class declares.
+     */
+    destroyLosesData?: true;
+    moduleId: string;
+    resourceContext: string;
+    resourceId: string;
+    terraformAddresses: string[];
+};
 /**
  * @internal
  */
 export type TransactionOptions = {
-    enableResourceCapture?: boolean;
     enableResourceValidation?: boolean;
+    filterResourceDiffsByResourceId?: string;
+    generateTerraform?: boolean;
+    skipActualResourceUpdate?: boolean;
     yieldModelDiffs?: boolean;
     yieldModelTransaction?: boolean;
     yieldResourceDiffs?: boolean;
     yieldResourceTransaction?: boolean;
 };
 /**
- * @internal
- */
-export type ModifyInterface<T, R> = Omit<T, keyof R> & R;
-/**
+ * The schema of an anchor class.
+ *
  * @group Types
  */
 export type AnchorSchema<T> = T extends AAnchor<infer S, any> ? S : never;
 /**
+ * Everything an action knows about the module it belongs to: the inputs it was loaded with, whatever
+ * {@link AModule.registerMetadata} derived, and the nodes the module produced.
+ *
+ * This is the second argument of {@link IModelAction.handle}.
+ *
  * @group Types
  */
 export type EnhancedModuleSchema<T extends UnknownModule> = {
@@ -218,16 +466,21 @@ export type EnhancedModuleSchema<T extends UnknownModule> = {
 /**
  * @internal
  */
-export type ModelSchema<T> = T extends AModel<infer S, any> ? S : never;
+export type GeneratorYieldType<T extends (...args: any) => AsyncGenerator<any>> = ReturnType<T> extends AsyncGenerator<infer Y> ? Y : never;
 /**
  * @internal
  */
-export type ModuleOutput<M> = M extends AModule<any, infer T> ? T : never;
+export type ModelSchema<T> = T extends AModel<infer S, any> ? S : never;
 /**
+ * The schema of a module class.
+ *
  * @group Types
  */
 export type ModuleSchema<T> = T extends AModule<infer S, any> ? S : never;
 /**
+ * A module's schema as the caller supplies it - properties with a default become optional.
+ * This is the shape {@link Octo.loadModule} accepts.
+ *
  * @group Types
  */
 export type ModuleSchemaInputs<T> = {
@@ -240,10 +493,14 @@ export type ModuleSchemaInputs<T> = {
  */
 export type NodeSchema<T> = T extends ANode<infer S, any> ? S : never;
 /**
+ * The schema of an overlay class.
+ *
  * @group Types
  */
 export type OverlaySchema<T> = T extends AOverlay<infer S, any> ? S : never;
 /**
+ * The schema of a resource class.
+ *
  * @group Types
  */
 export type ResourceSchema<T> = T extends AResource<infer S, any> ? S : never;
@@ -283,3 +540,4 @@ export type UnknownOverlay = AOverlay<BaseOverlaySchema, any>;
  * @internal
  */
 export type UnknownResource = AResource<any, any>;
+export {};