@quadnix/octo 0.0.30 → 0.2.0

package/dist/index.type.d.ts

@@ -0,0 +1,5 @@
+export type { ModelSerializedOutput, ResourceSerializedOutput } from './app.type.js';
+export type { IDependency } from './functions/dependency/dependency.js';
+export type { DiffAction } from './functions/diff/diff.js';
+export type { ServiceType } from './models/service/service.schema.js';
+export type { ExternalResourceStateFile, ModelStateFile, ResourceStateFile, } from './services/state-management/state-management.service.js';

package/dist/index.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.type.js.map

package/dist/index.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.type.js","sourceRoot":"","sources":["../src/index.type.ts"],"names":[],"mappings":""}

package/dist/main.d.ts

@@ -1,47 +1,192 @@
-import type { Constructable, ModuleSchemaInputs, TransactionOptions, UnknownModule, UnknownResource } from './app.type.js';
+import type { Constructable, ModuleSchemaInputs, UnknownModule, UnknownResource } from './app.type.js';
 import { Container } from './functions/container/container.js';
 import { App } from './models/app/app.model.js';
+import { type ModelTransactionResult } from './modes/apply-transaction.js';
+import { type TerraformOutputs, commit as runCommit } from './modes/commit.mode.js';
+import { generate as runGenerate } from './modes/generate.mode.js';
+import { runAction as runRunAction } from './modes/run-action.mode.js';
+import { type TerraformPlan, validate as runValidate } from './modes/validate.mode.js';
 import { ModuleContainer } from './modules/module.container.js';
-import { BaseResourceSchema } from './resources/resource.schema.js';
 import { InputService } from './services/input/input.service.js';
 import { SchemaTranslationService } from './services/schema-translation/schema-translation.service.js';
 import type { IStateProvider } from './services/state-management/state-provider.interface.js';
-import { TransactionService } from './services/transaction/transaction.service.js';
+import { TerraformService } from './services/terraform/terraform.service.js';
 /**
+ * The entry point to Octo.
+ *
+ * You describe infrastructure by loading modules, and Octo turns that description into terraform,
+ * checks what terraform intends to do, and records what it did. That is the lifecycle, and it is
+ * always these four steps:
+ *
+ * 1. {@link Octo.generate} - write the terraform module folders for the infrastructure you described.
+ * 2. {@link Octo.validate} - correlate terraform's plans with your intent, and report the difference.
+ * 3. `terraform apply` - see {@link TerraformUtility}. Octo does not do this for you.
+ * 4. {@link Octo.commit} - record the applied result back into Octo's state.
+ *
+ * Splitting them is deliberate: nothing is applied until you have seen a report of what would change,
+ * and each step is a separate process, so a CI pipeline can gate between them.
+ *
+ * @example
+ * ```ts
+ * const octo = new Octo();
+ * await octo.initialize(new LocalStateProvider('./infrastructure'));
+ *
+ * octo.registerTerraformConfig({ providers: { aws: { source: 'hashicorp/aws' } } });
+ * octo.registerTerraformProvider('aws', '1234567890', 'us-east-1');
+ *
+ * octo.loadModule(SimpleAppModule, 'app-module', { name: 'my-app' });
+ * await octo.compose();
+ *
+ * await octo.generate(octo.getRootModel(), { outputDir: './infrastructure/terraform' });
+ * ```
+ *
  * @group Main
+ *
+ * @see Definition of [Modules](/docs/fundamentals/modules).
  */
 export declare class Octo {
-    private readonly modelStateFileName;
-    private readonly actualResourceStateFileName;
-    private readonly oldResourceStateFileName;
-    private captureService;
+    private eventService;
     private inputService;
     private modelSerializationService;
     private moduleContainer;
     private resourceSerializationService;
     private schemaTranslationService;
     private stateManagementService;
-    private transactionService;
-    beginTransaction(app: App, { appLockId, enableResourceCapture, enableResourceValidation, yieldModelDiffs, yieldModelTransaction, yieldResourceDiffs, yieldResourceTransaction, }?: TransactionOptions & {
-        appLockId?: string;
-    }): ReturnType<TransactionService['beginTransaction']>;
-    private commitTransaction;
+    private terraformService;
+    /**
+     * The last step of the lifecycle - records the result of a `terraform apply` back into Octo's state.
+     *
+     * A terraform apply reports what it created, and part of that is what each octo resource's
+     * `response` is made of - ARNs, generated IDs, endpoints. Without this step the next run has no
+     * idea any of it exists.
+     *
+     * **All-or-nothing**: if an expected output is missing, this throws before touching state, so a
+     * partial apply never leaves a half-written record behind. Pass `partial` after an apply that
+     * failed and the missing outputs become warnings instead, with every resource they belong to left
+     * out of the committed graph. Outputs for a folder Octo does not track are ignored, and returned
+     * as warnings for you to surface.
+     *
+     * **Requires the lock**, and does not release it. Taking and releasing the lock belongs to whoever
+     * drives the lifecycle - the CLI's `octo commit` releases it once this returns, and keeps it when this
+     * throws.
+     *
+     * @param app The root model, from {@link Octo.getRootModel}.
+     * @param options `lockId` is the lock from `octo lock`. `outputs` is
+     * `TerraformUtility.output(dir, { json: true })` in full. `partial` records what a failed apply
+     * did build.
+     * @param transaction The model transaction result.
+     * @throws {@link TransactionError} When the app is not locked, or `lockId` is not the lock held.
+     */
+    commit(app: App, options: {
+        lockId: string;
+        outputs: Map<string, TerraformOutputs>;
+        partial?: boolean;
+    }, transaction?: ModelTransactionResult): Promise<Pick<Awaited<ReturnType<typeof runCommit>>, 'warnings'>>;
+    /**
+     * Runs every loaded module, in the order {@link Octo.orderModules} set, building the model graph.
+     * Call it once, after loading modules and before any lifecycle step.
+     *
+     * @returns Every model and overlay the modules created, keyed by a unique ID.
+     */
     compose(): Promise<{
         [key: string]: unknown;
     }>;
+    /**
+     * The first step of the lifecycle - writes the terragrunt module folders for the infrastructure you
+     * described, one folder per module, and saves the model state.
+     *
+     * A new module gets a new folder, and a changed module is rewritten in the folder it already has.
+     * A module you *removed* is not deleted: its folder is **emptied**, keeping only the provider
+     * blocks, so the next terraform apply destroys the live infrastructure rather than orphaning it.
+     * Octo never deletes a folder.
+     *
+     * @param app The root model, from {@link Octo.getRootModel}.
+     * @param options `outputDir` is where the module folders are written.
+     * @param transaction The model transaction result.
+     */
+    generate(app: App, options: {
+        outputDir: string;
+    }, transaction?: ModelTransactionResult): ReturnType<typeof runGenerate>;
+    /**
+     * To fetch a loaded module by its module ID.
+     *
+     * @returns The module, or `undefined` if no module was loaded under that ID.
+     */
     getModule<M extends UnknownModule>(...args: Parameters<InputService['getModule']>): M | undefined;
+    /**
+     * To fetch the resources a module produced, by its module ID.
+     */
     getModuleResources(...args: Parameters<InputService['getModuleResources']>): UnknownResource[];
+    /**
+     * The root of the model graph - the one {@link App} the loaded modules produced. Every lifecycle
+     * step takes it. Call after {@link Octo.compose}.
+     *
+     * @throws If no app model, or more than one distinct app model, was registered.
+     */
+    getRootModel(): App;
+    /**
+     * Boots Octo. Call it once, before anything else.
+     *
+     * The two optional arguments are how you replace Octo's internals with your own: exclusions run
+     * first, so you can unregister a built-in {@link Factory} and then resolve yours in its place.
+     *
+     * @param stateProvider Where Octo reads and writes its state. See {@link IStateProvider}.
+     * @param initializeInContainer Factories to resolve at boot - event listeners, most commonly.
+     * @param excludeInContainer Factories to unregister at boot.
+     */
     initialize(stateProvider: IStateProvider, initializeInContainer?: {
-        type: Parameters<Container['get']>[0];
         options?: Parameters<Container['get']>[1];
+        type: Parameters<Container['get']>[0];
     }[], excludeInContainer?: {
         type: Parameters<Container['unRegisterFactory']>[0];
     }[]): Promise<void>;
+    /**
+     * To load a module, which {@link Octo.compose} will then run.
+     *
+     * The same module class can be loaded more than once under different module IDs, and the ID scopes
+     * everything that instance produces.
+     *
+     * @param module The module class, or its registered name.
+     * @param moduleId A unique ID for this instance of the module.
+     * @param inputs The inputs, matching the module's schema.
+     */
     loadModule<M extends UnknownModule>(module: Constructable<M> | string, moduleId: string, inputs: ModuleSchemaInputs<M>): void;
+    /**
+     * To set the order {@link Octo.compose} runs modules in, by listing their classes.
+     *
+     * Order matters because a module resolves what earlier modules produced - a subnet module must run
+     * after the region module whose region it attaches to.
+     */
     orderModules(...args: Parameters<ModuleContainer['order']>): ReturnType<ModuleContainer['order']>;
-    registerCapture<S extends BaseResourceSchema>(resourceContext: string, response: Partial<S['response']>): void;
+    /**
+     * To register callbacks that run at fixed points of the lifecycle. Use them to inject behavior -
+     * an audit trail, an approval gate - without modifying the framework.
+     *
+     * The hook points, each with its own signature:
+     * - `PreCommitHook` / `PostCommitHook` - around the commit.
+     * - `PreModelActionHook` / `PostModelActionHook` - around every model action.
+     * - `PreResourceActionHook` / `PostResourceActionHook` - around every resource action.
+     *
+     * @see Techniques for [Hooks](/docs/techniques/hooks).
+     */
     registerHooks(...args: Parameters<ModuleContainer['registerHooks']>): ReturnType<ModuleContainer['registerHooks']>;
+    /**
+     * To teach Octo how to read one schema as another.
+     *
+     * Modules find each other by schema, so a module that changes its schema breaks its consumers.
+     * A translation is the escape hatch: register the schema you have, the schema your module expects,
+     * and a function between them, and the lookup keeps working while you migrate.
+     *
+     * @see Techniques for [Schema](/docs/techniques/schema).
+     */
     registerSchemaTranslation(...args: Parameters<SchemaTranslationService['registerSchemaTranslation']>): ReturnType<SchemaTranslationService['registerSchemaTranslation']>;
+    /**
+     * To apply tags to resources in bulk, so that individual modules do not each have to be told about
+     * your organization's tagging policy.
+     *
+     * Each entry's `scope` decides its reach: empty tags every resource of the app, `moduleId` tags
+     * every resource of one module, and `resourceContext` tags a single resource.
+     */
     registerTags(args: {
         scope: {
             moduleId?: string;
@@ -51,7 +196,93 @@ export declare class Octo {
             [key: string]: string;
         };
     }[]): void;
+    /**
+     * To set the minimum terraform version, and the `required_providers` block rendered into every
+     * generated module folder.
+     *
+     * Call it after {@link Octo.initialize}, and before {@link Octo.generate}.
+     */
+    registerTerraformConfig(...args: Parameters<TerraformService['addTerraformConfig']>): ReturnType<TerraformService['addTerraformConfig']>;
+    /**
+     * To register a terraform provider for one deployment target - a provider type, an account, and a
+     * region.
+     *
+     * Resources bind to a provider by `{ accountId, regionId }` alone, so this is the one place a
+     * provider type is named. Register one per account/region combination you deploy into.
+     *
+     * Call it after {@link Octo.initialize}, and before {@link Octo.generate}.
+     */
+    registerTerraformProvider(...args: Parameters<TerraformService['addTerraformProvider']>): ReturnType<TerraformService['addTerraformProvider']>;
+    /**
+     * Runs one resource action for an external resource.
+     *
+     * Terraform calls back into this mid-apply, through the generated CLI command; it is not a step you
+     * run yourself.
+     *
+     * @internal
+     */
+    runAction(app: App, options: {
+        inputs?: Record<string, unknown>;
+        resourceId: string;
+    }): ReturnType<typeof runRunAction>;
+    /**
+     * The second step of the lifecycle - correlates terraform's plans with your intent, and reports
+     * what it finds. This is what you read before deciding whether to apply.
+     *
+     * The report answers two questions separately:
+     * 1. **What will change, and why.** Including terraform changes Octo did not flag directly but can
+     *    attribute to something it did - a referenced resource whose identity moved, or an address the
+     *    resource no longer renders.
+     * 2. **What changed that your intent does not explain** - drift, i.e. infrastructure modified
+     *    outside Octo. Read `confidence` first: drift is only reliable when intent itself is unchanged.
+     *
+     * The report fails only when terraform could not plan a folder Octo generated. Folders Octo does
+     * not track are excluded, and noted. So is every external resource a previous run published and no
+     * commit has recorded, which is the only step that reads those records back for a user.
+     *
+     * @param app The root model, from {@link Octo.getRootModel}.
+     * @param plans The whole result of `TerraformUtility.plan(dir, { json: true })`. Its `errors` map
+     * carries terraform's own message for each folder that failed to plan.
+     * @param transaction The model transaction result.
+     */
+    validate(app: App, plans: {
+        errors?: Map<string, string>;
+        plans: Map<string, TerraformPlan>;
+    }, transaction?: ModelTransactionResult): ReturnType<typeof runValidate>;
+    /**
+     * This function persists the model and resource state using {@link IStateProvider}.
+     * Then immediately fetches the resource state in memory for the next set of operations.
+     *
+     * @internal
+     */
+    private commitTransaction;
+    /**
+     * This function deserializes the resource state in memory.
+     * It deserializes the actual resource state into actual resources,
+     * and the last resource state into old resources.
+     *
+     * @internal
+     */
     private retrieveResourceState;
+    /**
+     * Wraps a mode to emit its boundary events, and re-throws whatever the mode threw.
+     * The finishing events use `emitAndWait`, so a listener that writes a file completes first.
+     *
+     * @internal
+     */
+    private runMode;
+    /**
+     * This function persists the in-memory model state.
+     *
+     * @internal
+     */
     private saveModelState;
+    /**
+     * This function persists the in-memory resource state.
+     * The actual resource state is persisted as actual,
+     * and the current resource state is persisted as old.
+     *
+     * @internal
+     */
     private saveResourceState;
 }