declastruct 1.7.3 → 1.9.0

package/dist/contract/cli/apply.js

@@ -36,6 +36,7 @@ const path_1 = require("path");
 const rhachet_artifact_git_1 = require("rhachet-artifact-git");
 const DeclastructPlan_1 = require("../../domain.objects/DeclastructPlan");
 const applyChanges_1 = require("../../domain.operations/apply/applyChanges");
+const initializeProviders_1 = require("../../infra/initializeProviders");
 const log = console;
 /**
  * .what = executes the apply command to apply infrastructure changes
@@ -50,12 +51,16 @@ const executeApplyCommand = async (input) => {
     if (isYoloMode) {
         // yolo mode requires --wish
         if (!input.wishFilePath)
-            throw new helpful_errors_1.BadRequestError('--wish required when --plan yolo');
+            throw new helpful_errors_1.BadRequestError('--wish required when --plan yolo', {
+                hint: 'add --wish <file> to specify the wish file',
+            });
     }
     else {
         // standard mode requires --plan (not "yolo")
         if (!input.planFilePath)
-            throw new helpful_errors_1.BadRequestError('--plan required');
+            throw new helpful_errors_1.BadRequestError('--plan required', {
+                hint: 'add --plan <file> to specify the plan file',
+            });
     }
     // resolve plan path (null for yolo mode)
     const resolvedPlanPath = isYoloMode
@@ -66,7 +71,10 @@ const executeApplyCommand = async (input) => {
         if (!resolvedPlanPath)
             return null;
         if (!(0, fs_1.existsSync)(resolvedPlanPath))
-            throw new helpful_errors_1.BadRequestError(`Plan file not found: ${resolvedPlanPath}`);
+            throw new helpful_errors_1.BadRequestError('plan file not found', {
+                path: resolvedPlanPath,
+                hint: 'check that the --plan path points to an extant file',
+            });
         const planJson = await (0, promises_1.readFile)(resolvedPlanPath, 'utf-8');
         return new DeclastructPlan_1.DeclastructPlan(JSON.parse(planJson));
     })();
@@ -76,7 +84,10 @@ const executeApplyCommand = async (input) => {
         : plan.wish.uri;
     // validate wish file exists
     if (!(0, fs_1.existsSync)(resolvedWishPath))
-        throw new helpful_errors_1.BadRequestError(`Wish file not found: ${resolvedWishPath}`);
+        throw new helpful_errors_1.BadRequestError('wish file not found', {
+            path: resolvedWishPath,
+            hint: 'check that the wish file path is correct',
+        });
     // get git root for relative path display
     const gitRoot = await (0, rhachet_artifact_git_1.getGitRepoRoot)({ from: process.cwd() });
     const relativePlanPath = resolvedPlanPath
@@ -86,27 +97,49 @@ const executeApplyCommand = async (input) => {
     // log header
     log.info('');
     log.info('🌊 declastruct apply');
-    if (relativePlanPath)
-        log.info(`   plan: ${relativePlanPath}`);
-    log.info(`   wish: ${relativeWishPath}`);
+    if (relativePlanPath) {
+        log.info(`   ├─ plan: ${relativePlanPath}`);
+        log.info(`   └─ wish: ${relativeWishPath}`);
+    }
+    else {
+        log.info(`   ├─ plan: (yolo)`);
+        log.info(`   └─ wish: ${relativeWishPath}`);
+    }
     log.info('');
+    // create cli context with passthrough args from plan
+    const cliContext = {
+        passthrough: { argv: plan?.wish.argv ?? [] },
+    };
+    // inject argv from plan so wish file sees same args as plan time
+    // this ensures staleness check compares same resources
+    process.argv = [
+        process.argv[0],
+        process.argv[1],
+        ...cliContext.passthrough.argv,
+    ];
     // import wish file
     const wish = await Promise.resolve(`${resolvedWishPath}`).then(s => __importStar(require(s)));
     // validate exports
     if (typeof wish.getResources !== 'function')
-        throw new helpful_errors_1.BadRequestError('Wish file must export getResources() function');
+        throw new helpful_errors_1.BadRequestError('wish file must export getResources() function', {
+            path: resolvedWishPath,
+            hint: 'add `export const getResources = () => [...]` to the wish file',
+        });
     if (typeof wish.getProviders !== 'function')
-        throw new helpful_errors_1.BadRequestError('Wish file must export getProviders() function');
+        throw new helpful_errors_1.BadRequestError('wish file must export getProviders() function', {
+            path: resolvedWishPath,
+            hint: 'add `export const getProviders = () => [...]` to the wish file',
+        });
     // get resources and providers
     const resources = await wish.getResources();
     const providers = await wish.getProviders();
     // initialize providers
-    // log.info('✨ start providers...');
-    await Promise.all(providers.map((p) => p.hooks.beforeAll()));
-    // create context
+    await (0, initializeProviders_1.initializeProviders)({ providers });
+    // create context with passthrough args
     const context = {
         bottleneck: new bottleneck_1.default({ maxConcurrent: 1 }),
         log,
+        passthrough: cliContext.passthrough,
     };
     // apply changes (plan=null triggers yolo mode, skipping validation)
     const result = await (0, applyChanges_1.applyChanges)({
@@ -120,7 +153,8 @@ const executeApplyCommand = async (input) => {
     await Promise.all(providers.map((p) => p.hooks.afterAll()));
     // log summary
     log.info('');
-    log.info(`🌊 applied ${result.appliedChanges.length} changes`);
+    log.info('🌊 declastruct apply');
+    log.info(`   └─ applied: ${result.appliedChanges.length}`);
     log.info('');
 };
 exports.executeApplyCommand = executeApplyCommand;

package/dist/contract/cli/apply.js.map

@@ -1 +1 @@
-{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../src/contract/cli/apply.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../src/contract/cli/apply.ts"],"names":[],"mappings":"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"}

package/dist/contract/cli/invoke.js

@@ -5,10 +5,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.invoke = void 0;
 const commander_1 = require("commander");
+const helpful_errors_1 = require("helpful-errors");
 const package_json_1 = __importDefault(require("../../../package.json"));
 const apply_1 = require("./apply");
 const plan_1 = require("./plan");
 const log = console;
+/**
+ * .what = determines exit code based on error type
+ * .why = semantic exit codes let callers know if they can retry or must fix
+ */
+const getExitCodeForError = (error) => {
+    if (error instanceof helpful_errors_1.BadRequestError)
+        return 2;
+    return 1;
+};
 /**
  * .what = invokes CLI commands based on user input
  * .why = provides global entry point for declastruct CLI
@@ -25,16 +35,41 @@ const invoke = async ({ args }) => {
         .description('Generate a change plan from a wish file')
         .requiredOption('--wish <file>', 'Path to wish file')
         .requiredOption('--into <file>', 'Path to output plan file')
-        .action(async (options) => {
+        .option('--snap <file>', 'Path to output snapshot file')
+        .usage('--wish <file> --into <file> [-- <wish-args>]')
+        .allowExcessArguments(true)
+        .configureOutput({
+        writeErr: (str) => {
+            // intercept unknown option errors and add hint
+            if (str.includes('unknown option')) {
+                const match = str.match(/unknown option '([^']+)'/);
+                const flag = match?.[1] ?? '';
+                log.error(str.trim());
+                log.error(`hint: to pass args to your wish file, use: -- ${flag}`);
+            }
+            else {
+                log.error(str.trim());
+            }
+        },
+    })
+        .action(async (options, command) => {
         try {
+            // capture args after -- separator
+            const passthroughArgs = command.args;
             await (0, plan_1.executePlanCommand)({
                 wishFilePath: options.wish,
                 planFilePath: options.into,
+                snapFilePath: options.snap ?? null,
+                passthroughArgs,
             });
         }
         catch (error) {
-            log.error('✖ Error during plan:', error);
-            process.exit(1);
+            // allowlist: BadRequestError (user must fix) and Error (malfunction)
+            // rethrow anything else (non-Error thrown = unexpected)
+            if (!(error instanceof Error))
+                throw error;
+            log.error('✖ plan failed:', error);
+            process.exit(getExitCodeForError(error));
         }
     });
     program
@@ -42,6 +77,7 @@ const invoke = async ({ args }) => {
         .description('Apply changes from a plan file')
         .option('--plan <file>', 'Path to plan file, or "yolo" for immediate apply')
         .option('--wish <file>', 'Path to wish file (required when --plan yolo)')
+        .allowExcessArguments(true) // ignore passthrough args - apply uses plan's captured state
         .action(async (options) => {
         try {
             await (0, apply_1.executeApplyCommand)({
@@ -50,8 +86,12 @@ const invoke = async ({ args }) => {
             });
         }
         catch (error) {
-            log.error('✖ Error during apply:', error);
-            process.exit(1);
+            // allowlist: BadRequestError (user must fix) and Error (malfunction)
+            // rethrow non-Error values (unexpected)
+            if (!(error instanceof Error))
+                throw error;
+            log.error('✖ apply failed:', error);
+            process.exit(getExitCodeForError(error));
         }
     });
     await program.parseAsync(args, { from: 'user' });

package/dist/contract/cli/invoke.js.map

@@ -1 +1 @@
-{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../../src/contract/cli/invoke.ts"],"names":[],"mappings":";;;;;;AAAA,yCAAoC;AAEpC,yEAAwC;AACxC,mCAA8C;AAC9C,iCAA4C;AAE5C,MAAM,GAAG,GAAG,OAAO,CAAC;AAEpB;;;;GAIG;AACI,MAAM,MAAM,GAAG,KAAK,EAAE,EAAE,IAAI,EAAsB,EAAiB,EAAE;IAC1E,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,aAAa,CAAC;SACnB,WAAW,CAAC,wCAAwC,CAAC;SACrD,OAAO,CAAC,sBAAG,CAAC,OAAO,CAAC,CAAC;IAExB,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,yCAAyC,CAAC;SACtD,cAAc,CAAC,eAAe,EAAE,mBAAmB,CAAC;SACpD,cAAc,CAAC,eAAe,EAAE,0BAA0B,CAAC;SAC3D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,MAAM,IAAA,yBAAkB,EAAC;gBACvB,YAAY,EAAE,OAAO,CAAC,IAAI;gBAC1B,YAAY,EAAE,OAAO,CAAC,IAAI;aAC3B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gCAAgC,CAAC;SAC7C,MAAM,CAAC,eAAe,EAAE,kDAAkD,CAAC;SAC3E,MAAM,CAAC,eAAe,EAAE,+CAA+C,CAAC;SACxE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,MAAM,IAAA,2BAAmB,EAAC;gBACxB,YAAY,EAAE,OAAO,CAAC,IAAI;gBAC1B,YAAY,EAAE,OAAO,CAAC,IAAI;aAC3B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;YAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC;AA3CW,QAAA,MAAM,UA2CjB"}
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../../src/contract/cli/invoke.ts"],"names":[],"mappings":"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"}

package/dist/contract/cli/plan.d.ts

@@ -4,7 +4,9 @@
  * .why = provides CLI interface for planning infrastructure changes
  * .note = requires wish file with getResources() and getProviders() exports
  */
-export declare const executePlanCommand: ({ wishFilePath, planFilePath, }: {
+export declare const executePlanCommand: ({ wishFilePath, planFilePath, snapFilePath, passthroughArgs, }: {
     wishFilePath: string;
     planFilePath: string;
+    snapFilePath: string | null;
+    passthroughArgs?: string[];
 }) => Promise<void>;

package/dist/contract/cli/plan.js

@@ -35,51 +35,81 @@ const helpful_errors_1 = require("helpful-errors");
 const path_1 = require("path");
 const rhachet_artifact_git_1 = require("rhachet-artifact-git");
 const planChanges_1 = require("../../domain.operations/plan/planChanges");
+const initializeProviders_1 = require("../../infra/initializeProviders");
 const log = console;
 /**
  * .what = executes the plan command to generate an infrastructure change plan
  * .why = provides CLI interface for planning infrastructure changes
  * .note = requires wish file with getResources() and getProviders() exports
  */
-const executePlanCommand = async ({ wishFilePath, planFilePath, }) => {
+const executePlanCommand = async ({ wishFilePath, planFilePath, snapFilePath, passthroughArgs = [], }) => {
     // resolve paths
     const resolvedWishPath = (0, path_1.resolve)(process.cwd(), wishFilePath);
     const resolvedPlanPath = (0, path_1.resolve)(process.cwd(), planFilePath);
+    const resolvedSnapPath = snapFilePath
+        ? (0, path_1.resolve)(process.cwd(), snapFilePath)
+        : null;
     // get git root for relative path display
     const gitRoot = await (0, rhachet_artifact_git_1.getGitRepoRoot)({ from: process.cwd() });
     const relativeWishPath = (0, path_1.relative)(gitRoot, resolvedWishPath);
     const relativePlanPath = (0, path_1.relative)(gitRoot, resolvedPlanPath);
+    const relativeSnapPath = resolvedSnapPath
+        ? (0, path_1.relative)(gitRoot, resolvedSnapPath)
+        : null;
     // validate wish file exists
     if (!(0, fs_1.existsSync)(resolvedWishPath)) {
-        throw new helpful_errors_1.BadRequestError(`Wish file not found: ${resolvedWishPath}`);
+        throw new helpful_errors_1.BadRequestError('wish file not found', {
+            path: resolvedWishPath,
+            hint: 'check that the --wish path points to an extant file',
+        });
     }
     log.info('');
     log.info('🌊 declastruct plan');
-    log.info(`   wish: ${relativeWishPath}`);
-    log.info(`   plan: ${relativePlanPath}`);
+    log.info(`   ├─ wish: ${relativeWishPath}`);
+    log.info(`   ├─ plan: ${relativePlanPath}`);
+    if (relativeSnapPath)
+        log.info(`   └─ snap: ${relativeSnapPath}`);
+    else
+        log.info(`   └─ snap: (none)`);
     log.info('');
-    // import wish file
+    // create cli context with passthrough args
+    const cliContext = {
+        passthrough: { argv: passthroughArgs },
+    };
+    // inject passthrough args into process.argv before import
+    process.argv = [
+        process.argv[0],
+        process.argv[1],
+        ...cliContext.passthrough.argv,
+    ];
+    // import wish file (now sees passthrough.argv in process.argv)
     const wish = await Promise.resolve(`${resolvedWishPath}`).then(s => __importStar(require(s)));
     // validate exports
     if (typeof wish.getResources !== 'function') {
-        throw new helpful_errors_1.BadRequestError('Wish file must export getResources() function');
+        throw new helpful_errors_1.BadRequestError('wish file must export getResources() function', {
+            path: resolvedWishPath,
+            hint: 'add `export const getResources = () => [...]` to the wish file',
+        });
     }
     if (typeof wish.getProviders !== 'function') {
-        throw new helpful_errors_1.BadRequestError('Wish file must export getProviders() function');
+        throw new helpful_errors_1.BadRequestError('wish file must export getProviders() function', {
+            path: resolvedWishPath,
+            hint: 'add `export const getProviders = () => [...]` to the wish file',
+        });
     }
     // get resources and providers
     const resources = await wish.getResources();
     const providers = await wish.getProviders();
     // initialize providers
-    // log.info('✨ start providers...');
-    await Promise.all(providers.map((p) => p.hooks.beforeAll()));
-    // create context
+    await (0, initializeProviders_1.initializeProviders)({ providers });
+    // create context with passthrough args
     const context = {
         bottleneck: new bottleneck_1.default({ maxConcurrent: 1 }),
         log,
+        passthrough: cliContext.passthrough,
     };
-    // plan changes (logs emitted in real-time by planChanges)
-    const plan = await (0, planChanges_1.planChanges)({
+    // plan changes (outputs emitted in real-time by planChanges)
+    const { plan, snapshot } = await (0, planChanges_1.planChanges)({
         resources,
         providers,
         wishFilePath: resolvedWishPath,
@@ -89,14 +119,23 @@ const executePlanCommand = async ({ wishFilePath, planFilePath, }) => {
     await (0, promises_1.mkdir)(planDir, { recursive: true });
     // write plan to file
     await (0, promises_1.writeFile)(resolvedPlanPath, JSON.stringify(plan, null, 2), 'utf-8');
+    // write snapshot to file if requested
+    if (resolvedSnapPath) {
+        const snapDir = (0, path_1.dirname)(resolvedSnapPath);
+        await (0, promises_1.mkdir)(snapDir, { recursive: true });
+        await (0, promises_1.writeFile)(resolvedSnapPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+    }
     // cleanup providers
-    // log.info('');
-    // log.info('✨ stop providers...');
-    await Promise.all(providers.map((p) => p.hooks.afterAll()));
+    await (0, initializeProviders_1.finalizeProviders)({ providers });
     // log summary
     log.info('');
-    log.info(`🌊 planned for ${plan.changes.length} resources`);
-    log.info(`   into ${relativePlanPath}`);
+    log.info('🌊 declastruct plan');
+    log.info(`   ├─ resources: ${plan.changes.length}`);
+    log.info(`   ├─ plan: ${relativePlanPath}`);
+    if (relativeSnapPath)
+        log.info(`   └─ snap: ${relativeSnapPath}`);
+    else
+        log.info(`   └─ snap: (none)`);
     log.info('');
 };
 exports.executePlanCommand = executePlanCommand;

package/dist/contract/cli/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/contract/cli/plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/contract/cli/plan.ts"],"names":[],"mappings":"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"}

package/dist/domain.objects/ContextDeclastructCli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * .what = context for CLI operations with passthrough args
+ * .why = enables wish files to receive args passed via -- separator
+ */
+export type ContextDeclastructCli = {
+    /**
+     * args passed through from CLI via -- separator
+     */
+    passthrough: {
+        /**
+         * argv to inject into process.argv before wish file import
+         */
+        argv: string[];
+    };
+};

package/dist/domain.objects/ContextDeclastructCli.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ContextDeclastructCli.js.map

package/dist/domain.objects/ContextDeclastructCli.js.map

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

package/dist/domain.objects/DeclastructPlan.d.ts

@@ -19,9 +19,15 @@ export interface DeclastructPlan {
      */
     wish: {
         /**
-         * file path URI to the wish file containing resources and providers
+         * file path URI to the wish file
          */
         uri: string;
+        /**
+         * args passed via -- separator at plan time
+         *
+         * .why = apply must replay these to get same resources for staleness check
+         */
+        argv: string[];
     };
     /**
      * all proposed changes

package/dist/domain.objects/DeclastructPlan.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeclastructPlan.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructPlan.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAoC9C,MAAa,eACX,SAAQ,6BAA6B;;AADvC,0CAOC;AAHe,uBAAO,GAAG,CAAC,MAAM,CAAU,CAAC;AAC5B,sBAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,yBAAS,GAAG,EAAW,CAAC"}
+{"version":3,"file":"DeclastructPlan.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructPlan.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AA2C9C,MAAa,eACX,SAAQ,6BAA6B;;AADvC,0CAOC;AAHe,uBAAO,GAAG,CAAC,MAAM,CAAU,CAAC;AAC5B,sBAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,yBAAS,GAAG,EAAW,CAAC"}

package/dist/domain.objects/DeclastructSnapshot.d.ts

@@ -0,0 +1,54 @@
+import { DomainLiteral } from 'domain-objects';
+import type { IsoTimestamp } from './IsoTimestamp';
+/**
+ * .what = a single entry in a snapshot, captures state for one resource
+ * .why = enables debug and audit of what declastruct observed for each resource
+ */
+export interface DeclastructSnapshotEntry {
+    /**
+     * which resource this entry is for
+     */
+    forResource: {
+        /**
+         * class name of the resource
+         */
+        class: string;
+        /**
+         * scannable identifier of this specific resource
+         */
+        slug: string;
+    };
+    /**
+     * serialized state of the resource
+     *
+     * .note = null if the resource does not exist remotely (for remote[])
+     * .note = contains _dobj stamp from serialize()
+     */
+    state: Record<string, any> | null;
+}
+export declare class DeclastructSnapshotEntry extends DomainLiteral<DeclastructSnapshotEntry> implements DeclastructSnapshotEntry {
+}
+/**
+ * .what = snapshot of remote and wished state at plan time
+ * .why = enables debug and audit of what declastruct observed before diff
+ */
+export interface DeclastructSnapshot {
+    /**
+     * timestamp when the snapshot was taken
+     */
+    observedAt: IsoTimestamp;
+    /**
+     * remote state for each resource (before omitReadonly)
+     */
+    remote: DeclastructSnapshotEntry[];
+    /**
+     * wished state for each resource (what user declared)
+     */
+    wished: DeclastructSnapshotEntry[];
+}
+export declare class DeclastructSnapshot extends DomainLiteral<DeclastructSnapshot> implements DeclastructSnapshot {
+    static nested: {
+        remote: typeof DeclastructSnapshotEntry;
+        wished: typeof DeclastructSnapshotEntry;
+    };
+}

package/dist/domain.objects/DeclastructSnapshot.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeclastructSnapshot = exports.DeclastructSnapshotEntry = void 0;
+const domain_objects_1 = require("domain-objects");
+class DeclastructSnapshotEntry extends domain_objects_1.DomainLiteral {
+}
+exports.DeclastructSnapshotEntry = DeclastructSnapshotEntry;
+class DeclastructSnapshot extends domain_objects_1.DomainLiteral {
+}
+exports.DeclastructSnapshot = DeclastructSnapshot;
+DeclastructSnapshot.nested = {
+    remote: DeclastructSnapshotEntry,
+    wished: DeclastructSnapshotEntry,
+};
+//# sourceMappingURL=DeclastructSnapshot.js.map

package/dist/domain.objects/DeclastructSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructSnapshot.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructSnapshot.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAiC/C,MAAa,wBACX,SAAQ,8BAAuC;CACT;AAFxC,4DAEwC;AAuBxC,MAAa,mBACX,SAAQ,8BAAkC;;AAD5C,kDAQC;AAJe,0BAAM,GAAG;IACrB,MAAM,EAAE,wBAAwB;IAChC,MAAM,EAAE,wBAAwB;CACjC,CAAC"}

package/dist/domain.operations/apply/applyChanges.d.ts

@@ -1,6 +1,7 @@
 import { type DomainEntity } from 'domain-objects';
 import type { ContextLogTrail } from 'simple-log-methods';
 import type { ContextDeclastruct } from '../../domain.objects/ContextDeclastruct';
+import type { ContextDeclastructCli } from '../../domain.objects/ContextDeclastructCli';
 import { type DeclastructChange } from '../../domain.objects/DeclastructChange';
 import type { DeclastructPlan } from '../../domain.objects/DeclastructPlan';
 import type { DeclastructProvider } from '../../domain.objects/DeclastructProvider';
@@ -15,6 +16,6 @@ export declare const applyChanges: (input: {
     plan: DeclastructPlan | null;
     resources: DomainEntity<any>[];
     providers: DeclastructProvider<any, any>[];
-}, context: ContextLogTrail & ContextDeclastruct) => Promise<{
+}, context: ContextLogTrail & ContextDeclastruct & ContextDeclastructCli) => Promise<{
     appliedChanges: DeclastructChange[];
 }>;

package/dist/domain.operations/apply/applyChanges.js

@@ -9,6 +9,25 @@ const validate_1 = require("../../domain.operations/plan/validate");
 const colorizeAction_1 = require("../../infra/colorizeAction");
 const withSpinner_1 = require("../../infra/withSpinner");
 const applyChange_1 = require("./applyChange");
+/**
+ * .what = checks if plan has any non-KEEP changes
+ * .why = determines whether apply phase should proceed
+ */
+const hasChangesToApply = (input) => {
+    return input.changes.some((change) => change.action !== DeclastructChange_1.DeclastructChangeAction.KEEP);
+};
+/**
+ * .what = finds resource that matches forResource identifier
+ * .why = locates the declared resource for a planned change
+ */
+const getOneResourceForChange = (input) => {
+    const resourceFound = input.resources.find((candidate) => candidate.constructor.name === input.forResource.class &&
+        (0, domain_objects_1.getUniqueIdentifierSlug)(candidate) === input.forResource.slug);
+    if (!resourceFound) {
+        helpful_errors_1.UnexpectedCodePathError.throw('could not find resource specified in plan. was it removed?', { forResource: input.forResource });
+    }
+    return resourceFound;
+};
 /**
  * .what = applies changes to achieve desired state
  * .why = executes infrastructure changes in a controlled, observable manner
@@ -18,18 +37,17 @@ const applyChange_1 = require("./applyChange");
  */
 const applyChanges = async (input, context) => {
     // replan to get current state
-    const currentPlan = await (0, planChanges_1.planChanges)({
+    const { plan: currentPlan } = await (0, planChanges_1.planChanges)({
         resources: input.resources,
         providers: input.providers,
         wishFilePath: input.plan?.wish.uri ?? 'ignorable',
     }, context);
     // use current plan for apply (works for both modes)
     const planToApply = currentPlan;
-    // check if there are any actionable changes (non-KEEP)
-    const hasActionableChanges = planToApply.changes.some((change) => change.action !== DeclastructChange_1.DeclastructChangeAction.KEEP);
     // skip apply phase if everything is in sync
-    if (!hasActionableChanges)
+    if (!hasChangesToApply({ changes: planToApply.changes })) {
         return { appliedChanges: [] };
+    }
     // validate plan matches current state (skip if no plan provided, i.e. yolo mode)
     if (input.plan) {
         (0, validate_1.assertPlanStillValid)({
@@ -56,9 +74,10 @@ const applyChanges = async (input, context) => {
             continue;
         }
         // find the desired resource
-        const resourceFound = input.resources.find((candidate) => candidate.constructor.name === change.forResource.class &&
-            (0, domain_objects_1.getUniqueIdentifierSlug)(candidate) === change.forResource.slug) ??
-            helpful_errors_1.UnexpectedCodePathError.throw('could not find resource specified in plan. was it removed?', { change });
+        const resourceFound = getOneResourceForChange({
+            resources: input.resources,
+            forResource: change.forResource,
+        });
         // log the action line (stays fixed)
         const actionLabel = (0, colorizeAction_1.colorizeAction)(change.action);
         context.log.info(`○ ${actionLabel} ${change.forResource.slug}`);

package/dist/domain.operations/apply/applyChanges.js.map

@@ -1 +1 @@
-{"version":3,"file":"applyChanges.js","sourceRoot":"","sources":["../../../src/domain.operations/apply/applyChanges.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"applyChanges.js","sourceRoot":"","sources":["../../../src/domain.operations/apply/applyChanges.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/plan/planChanges.d.ts

@@ -1,8 +1,10 @@
 import { type DomainEntity } from 'domain-objects';
 import type { ContextLogTrail } from 'simple-log-methods';
 import type { ContextDeclastruct } from '../../domain.objects/ContextDeclastruct';
+import type { ContextDeclastructCli } from '../../domain.objects/ContextDeclastructCli';
 import { DeclastructPlan } from '../../domain.objects/DeclastructPlan';
 import type { DeclastructProvider } from '../../domain.objects/DeclastructProvider';
+import { DeclastructSnapshot } from '../../domain.objects/DeclastructSnapshot';
 /**
  * .what = generates a plan of changes required to achieve desired state
  * .why = enables users to review infrastructure changes before applying them
@@ -12,4 +14,7 @@ export declare const planChanges: (input: {
     resources: DomainEntity<any>[];
     providers: DeclastructProvider<any, any>[];
     wishFilePath: string;
-}, context: ContextLogTrail & ContextDeclastruct) => Promise<DeclastructPlan>;
+}, context: ContextLogTrail & ContextDeclastruct & ContextDeclastructCli) => Promise<{
+    plan: DeclastructPlan;
+    snapshot: DeclastructSnapshot;
+}>;

package/dist/domain.operations/plan/planChanges.js

@@ -2,15 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.planChanges = void 0;
 const domain_objects_1 = require("domain-objects");
+const helpful_errors_1 = require("helpful-errors");
 const DeclastructChange_1 = require("../../domain.objects/DeclastructChange");
 const DeclastructPlan_1 = require("../../domain.objects/DeclastructPlan");
+const DeclastructSnapshot_1 = require("../../domain.objects/DeclastructSnapshot");
 const del_1 = require("../../domain.operations/del/del");
+const asIndentedLines_1 = require("../../infra/asIndentedLines");
 const asIsoTimestamp_1 = require("../../infra/asIsoTimestamp");
 const colorizeAction_1 = require("../../infra/colorizeAction");
 const withSpinner_1 = require("../../infra/withSpinner");
 const computeChange_1 = require("./computeChange");
 const getDaoByResource_1 = require("./getDaoByResource");
 const hashChanges_1 = require("./hashChanges");
+/**
+ * .what = checks if all changes are KEEP (no actions required)
+ * .why = determines whether to show "all in sync" message
+ */
+const isAllInSync = (input) => {
+    return input.changes.every((change) => change.action === DeclastructChange_1.DeclastructChangeAction.KEEP);
+};
 /**
  * .what = generates a plan of changes required to achieve desired state
  * .why = enables users to review infrastructure changes before applying them
@@ -24,8 +34,12 @@ const planChanges = async (input, context) => {
     const bottleneck = 'onPlan' in context.bottleneck
         ? context.bottleneck.onPlan
         : context.bottleneck;
-    // compute change for each resource with real-time logging
+    // capture observation timestamp (before any API calls)
+    const observedAt = (0, asIsoTimestamp_1.asIsoTimestamp)(new Date());
+    // compute change for each resource with real-time output
     const changes = [];
+    const snapshotRemote = [];
+    const snapshotWished = [];
     for (const resource of input.resources) {
         const change = await bottleneck.schedule(async () => {
             // find DAO and provider context for this resource
@@ -45,6 +59,25 @@ const planChanges = async (input, context) => {
             context.log.info(`   ├─ ✔ done in ${durationSec}s`);
             // determine desired state - null if marked for deletion
             const desiredState = (0, del_1.isMarkedForDeletion)(resource) ? null : resource;
+            // collect snapshot entry BEFORE omitReadonly (for debug and audit)
+            const forResource = {
+                class: resource.constructor.name,
+                slug: helpful_errors_1.UnexpectedCodePathError.wrap(() => (0, domain_objects_1.getUniqueIdentifierSlug)(resource), {
+                    message: 'failed to getUniqueIdentifierSlug for snapshot',
+                    metadata: {
+                        resource,
+                        ctor: resource.constructor.name,
+                    },
+                })(),
+            };
+            snapshotRemote.push(new DeclastructSnapshot_1.DeclastructSnapshotEntry({
+                forResource,
+                state: remoteState ? JSON.parse((0, domain_objects_1.serialize)(remoteState)) : null,
+            }));
+            snapshotWished.push(new DeclastructSnapshot_1.DeclastructSnapshotEntry({
+                forResource,
+                state: JSON.parse((0, domain_objects_1.serialize)(resource)), // always the declared resource, not desiredState
+            }));
             // compute change
             const computed = (0, computeChange_1.computeChange)({
                 desired: desiredState,
@@ -60,10 +93,10 @@ const planChanges = async (input, context) => {
             context.log.info(`   └─ decision ${(0, colorizeAction_1.colorizeAction)(computed.action)}`);
             // and the diff too, indented to align with tree
             if (computed.state.difference) {
-                const indentedDiff = computed.state.difference
-                    .split('\n')
-                    .map((line) => `      ${line}`)
-                    .join('\n');
+                const indentedDiff = (0, asIndentedLines_1.asIndentedLines)({
+                    text: computed.state.difference,
+                    indent: '      ',
+                });
                 context.log.info(indentedDiff);
             }
             context.log.info('');
@@ -73,20 +106,27 @@ const planChanges = async (input, context) => {
             changes.push(change);
     }
     // log success message if everything is in sync
-    const allInSync = changes.every((change) => change.action === DeclastructChange_1.DeclastructChangeAction.KEEP);
-    if (allInSync) {
+    if (isAllInSync({ changes })) {
         context.log.info('');
         context.log.info('🎉 everything is in sync!');
     }
-    // return plan
-    return new DeclastructPlan_1.DeclastructPlan({
+    // build plan
+    const plan = new DeclastructPlan_1.DeclastructPlan({
         hash: (0, hashChanges_1.hashChanges)(changes),
         createdAt: (0, asIsoTimestamp_1.asIsoTimestamp)(new Date()),
         wish: {
             uri: input.wishFilePath,
+            argv: context.passthrough.argv,
         },
         changes,
     });
+    // build snapshot
+    const snapshot = new DeclastructSnapshot_1.DeclastructSnapshot({
+        observedAt,
+        remote: snapshotRemote,
+        wished: snapshotWished,
+    });
+    return { plan, snapshot };
 };
 exports.planChanges = planChanges;
 //# sourceMappingURL=planChanges.js.map

package/dist/domain.operations/plan/planChanges.js.map

@@ -1 +1 @@
-{"version":3,"file":"planChanges.js","sourceRoot":"","sources":["../../../src/domain.operations/plan/planChanges.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"planChanges.js","sourceRoot":"","sources":["../../../src/domain.operations/plan/planChanges.ts"],"names":[],"mappings":"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"}

package/dist/infra/asIndentedLines.d.ts

@@ -0,0 +1,8 @@
+/**
+ * .what = indents each line of text with specified prefix
+ * .why = formats multi-line text to align with tree structure in logs
+ */
+export declare const asIndentedLines: (input: {
+    text: string;
+    indent: string;
+}) => string;

package/dist/infra/asIndentedLines.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asIndentedLines = void 0;
+/**
+ * .what = indents each line of text with specified prefix
+ * .why = formats multi-line text to align with tree structure in logs
+ */
+const asIndentedLines = (input) => {
+    return input.text
+        .split('\n')
+        .map((line) => `${input.indent}${line}`)
+        .join('\n');
+};
+exports.asIndentedLines = asIndentedLines;
+//# sourceMappingURL=asIndentedLines.js.map

package/dist/infra/asIndentedLines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asIndentedLines.js","sourceRoot":"","sources":["../../src/infra/asIndentedLines.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACI,MAAM,eAAe,GAAG,CAAC,KAG/B,EAAU,EAAE;IACX,OAAO,KAAK,CAAC,IAAI;SACd,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;SACvC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC,CAAC;AARW,QAAA,eAAe,mBAQ1B"}

package/dist/infra/initializeProviders.d.ts

@@ -0,0 +1,15 @@
+import type { DeclastructProvider } from '../domain.objects/DeclastructProvider';
+/**
+ * .what = initializes all providers via their beforeAll hooks
+ * .why = providers may need to establish connections or state before use
+ */
+export declare const initializeProviders: (input: {
+    providers: DeclastructProvider<any, any>[];
+}) => Promise<void>;
+/**
+ * .what = finalizes all providers via their afterAll hooks
+ * .why = providers may need to close connections or cleanup state after use
+ */
+export declare const finalizeProviders: (input: {
+    providers: DeclastructProvider<any, any>[];
+}) => Promise<void>;

package/dist/infra/initializeProviders.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.finalizeProviders = exports.initializeProviders = void 0;
+/**
+ * .what = initializes all providers via their beforeAll hooks
+ * .why = providers may need to establish connections or state before use
+ */
+const initializeProviders = async (input) => {
+    await Promise.all(input.providers.map((p) => p.hooks.beforeAll()));
+};
+exports.initializeProviders = initializeProviders;
+/**
+ * .what = finalizes all providers via their afterAll hooks
+ * .why = providers may need to close connections or cleanup state after use
+ */
+const finalizeProviders = async (input) => {
+    await Promise.all(input.providers.map((p) => p.hooks.afterAll()));
+};
+exports.finalizeProviders = finalizeProviders;
+//# sourceMappingURL=initializeProviders.js.map

package/dist/infra/initializeProviders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initializeProviders.js","sourceRoot":"","sources":["../../src/infra/initializeProviders.ts"],"names":[],"mappings":";;;AAEA;;;GAGG;AACI,MAAM,mBAAmB,GAAG,KAAK,EAAE,KAEzC,EAAiB,EAAE;IAClB,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AAJW,QAAA,mBAAmB,uBAI9B;AAEF;;;GAGG;AACI,MAAM,iBAAiB,GAAG,KAAK,EAAE,KAEvC,EAAiB,EAAE;IAClB,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AACpE,CAAC,CAAC;AAJW,QAAA,iBAAiB,qBAI5B"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "declastruct",
   "author": "ehmpathy",
   "description": "Add declarative control to any resource constructs. Declare, plan, and apply within an observable pit-of-success.",
-  "version": "1.7.3",
+  "version": "1.9.0",
   "repository": "ehmpathy/declastruct",
   "homepage": "https://github.com/ehmpathy/declastruct",
   "keywords": [
@@ -53,7 +53,8 @@
     "preversion": "npm run prepush",
     "postversion": "git push origin HEAD --tags --no-verify",
     "prepare:husky": "npx husky install && chmod ug+x .husky/*",
-    "prepare": "[ -e .git ] && npm run prepare:husky || exit 0"
+    "prepare": "[ -e .git ] && npm run prepare:husky || exit 0 && npm run prepare:rhachet",
+    "prepare:rhachet": "npm run build && rhachet init --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect reflector dreamer dispatcher"
   },
   "dependencies": {
     "bottleneck": "2.19.5",
@@ -84,14 +85,18 @@
     "cz-conventional-changelog": "3.3.0",
     "declapract": "^0.13.1",
     "declapract-typescript-ehmpathy": "0.45.3",
-    "declastruct": "1.7.0",
+    "declastruct": "link:.",
     "declastruct-github": "1.0.7",
     "depcheck": "1.4.3",
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.12.3",
-    "rhachet-roles-ehmpathy": "1.12.0",
+    "rhachet": "1.39.13",
+    "rhachet-brains-anthropic": "0.4.0",
+    "rhachet-brains-xai": "0.3.3",
+    "rhachet-roles-bhrain": "0.24.1",
+    "rhachet-roles-bhuild": "0.17.2",
+    "rhachet-roles-ehmpathy": "1.34.28",
     "test-fns": "1.7.2",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",

package/readme.md

@@ -120,6 +120,48 @@ planned changes:
     + metadata: { source: "app-web" }
 ```
 
+#### pass args to your wish file
+
+pass args to your wish file via `--` separator:
+
+```sh
+npx declastruct plan \
+  --wish provision/resources.ts \
+  --into provision/.temp/plan.json \
+  -- --env prod --region us-west-2
+```
+
+args after `--` are injected into `process.argv` before the wish file loads. parse them with node's `parseArgs`:
+
+```ts
+import { parseArgs } from 'util';
+
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    env: { type: 'string', default: 'test' },
+    region: { type: 'string', default: 'us-east-1' },
+  },
+});
+
+export const getResources = async () => {
+  // use values.env, values.region to configure resources
+  return [
+    DeclaredAwsS3Bucket.as({
+      name: `app-${values.env}-assets`,
+      region: values.region,
+    }),
+  ];
+};
+```
+
+**typo safety:** unknown flags without `--` trigger an error with guidance:
+
+```
+error: unknown option '--env'
+hint: to pass args to your wish file, use: -- --env
+```
+
 ### 3. **apply** the plan 🪄
 
 apply the plan to make your wish come true