puls-dev 0.3.3 → 0.3.5

package/dist/core/secret.js

@@ -1,6 +1,10 @@
 import { Output } from "./output.js";
 import { Config } from "./config.js";
+import { resourceContextStorage } from "./context.js";
 export const resolvedSecrets = new Set();
+export function clearResolvedSecrets() {
+    resolvedSecrets.clear();
+}
 /**
  * Secret represents a lazy, secure credential that is fetched asynchronously
  * at deployment time instead of during the eager construction phase.
@@ -25,6 +29,7 @@ export class Secret extends Output {
             this.resolve(val);
             if (val && val.length >= 3) {
                 resolvedSecrets.add(val);
+                resourceContextStorage.getStore()?.secrets.add(val);
             }
         }
         catch (err) {

package/dist/core/stack.d.ts

@@ -1,4 +1,5 @@
 import "reflect-metadata";
+import type { StackDiff } from "../types/diff.js";
 export declare abstract class Stack {
     /** @internal - called by @Deploy to register the instance for cross-stack references. */
     static _register(cls: Function, instance: Stack, region?: string): void;
@@ -16,6 +17,16 @@ export declare abstract class Stack {
      * }
      */
     static from<T extends Stack>(cls: new (...args: any[]) => T, region?: string): T;
+    /**
+     * Compares every declared resource against its live cloud state without
+     * making any API writes. Returns a structured `StackDiff` and prints a
+     * formatted report to the console.
+     *
+     * Field-level drift is surfaced for providers that implement `getDiff()`.
+     * Resources with no `getDiff()` override show only existence status
+     * (missing / in-sync / adopted).
+     */
+    diff(): Promise<StackDiff>;
     deploy(): Promise<Record<string, any>>;
     destroy(): Promise<Record<string, any>>;
 }

package/dist/core/stack.js

@@ -3,6 +3,42 @@ import { BaseBuilder } from "./resource.js";
 import { Config } from "./config.js";
 import { resourceContextStorage } from "./context.js";
 import { resolvedSecrets } from "./secret.js";
+async function withRedactedConsole(secrets, fn) {
+    const originalLog = console.log;
+    const redact = (message) => {
+        if (typeof message !== "string")
+            return message;
+        let result = message;
+        for (const secret of secrets) {
+            if (secret && secret.length >= 3) {
+                const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+                result = result.replace(new RegExp(escaped, "g"), "********");
+            }
+        }
+        return result;
+    };
+    console.log = (...args) => {
+        const redactedArgs = args.map((arg) => {
+            if (typeof arg === "string")
+                return redact(arg);
+            try {
+                const str = String(arg);
+                const hasSecret = [...secrets].some((s) => s && s.length >= 3 && str.includes(s));
+                if (hasSecret)
+                    return redact(str);
+            }
+            catch { }
+            return arg;
+        });
+        originalLog(...redactedArgs);
+    };
+    try {
+        return await fn();
+    }
+    finally {
+        console.log = originalLog;
+    }
+}
 const _registry = new Map();
 function formatEntry(val, parentKey) {
     const isSensitiveKey = (k) => /password|secret|token|key/i.test(k);
@@ -71,6 +107,45 @@ function printOutputs(stackName, outputs) {
     }
     console.log(`  └${line}┘`);
 }
+function printDiff(diff) {
+    console.log(`\n🔍 Diff: ${diff.stackName}`);
+    const propWidth = Math.max(...diff.resources.map((r) => r.prop.length), 4);
+    const nameWidth = Math.max(...diff.resources.map((r) => r.resource.length), 8);
+    for (const r of diff.resources) {
+        const prop = r.prop.padEnd(propWidth);
+        const name = r.resource.padEnd(nameWidth);
+        if (r.status === "in-sync") {
+            console.log(`   ${prop}  ${name}  ✅ in-sync`);
+        }
+        else if (r.status === "adopted") {
+            console.log(`   ${prop}  ${name}  🔗 adopted`);
+        }
+        else if (r.status === "missing") {
+            console.log(`   ${prop}  ${name}  ❌ missing  (will create)`);
+        }
+        else {
+            console.log(`   ${prop}  ${name}  ⚠️  drift`);
+            const fieldWidth = Math.max(...r.changes.map((c) => String(c.field).length), 8);
+            for (const c of r.changes) {
+                const field = String(c.field).padEnd(fieldWidth);
+                console.log(`      └─ ${field}  ${String(c.declared)}  →  ${c.live}`);
+            }
+        }
+    }
+    const driftCount = diff.resources.filter((r) => r.status === "drift").length;
+    const missingCount = diff.resources.filter((r) => r.status === "missing").length;
+    if (driftCount === 0 && missingCount === 0) {
+        console.log(`\n   ✅ All ${diff.resources.length} resources are in sync.`);
+    }
+    else {
+        const parts = [];
+        if (driftCount > 0)
+            parts.push(`${driftCount} drifted`);
+        if (missingCount > 0)
+            parts.push(`${missingCount} missing`);
+        console.log(`\n   ⚠️  ${parts.join(", ")} out of ${diff.resources.length} resources.`);
+    }
+}
 export class Stack {
     /** @internal - called by @Deploy to register the instance for cross-stack references. */
     static _register(cls, instance, region) {
@@ -99,53 +174,67 @@ export class Stack {
             throw new Error(`Stack "${cls.name}" ${region ? `for region "${region}" ` : ""}is not registered. Make sure it is decorated with @Deploy and its module is imported before referencing it.`);
         return instance;
     }
+    /**
+     * Compares every declared resource against its live cloud state without
+     * making any API writes. Returns a structured `StackDiff` and prints a
+     * formatted report to the console.
+     *
+     * Field-level drift is surfaced for providers that implement `getDiff()`.
+     * Resources with no `getDiff()` override show only existence status
+     * (missing / in-sync / adopted).
+     */
+    async diff() {
+        const props = Object.getOwnPropertyNames(this);
+        const entries = [];
+        for (const prop of props) {
+            const val = this[prop];
+            if (val instanceof BaseBuilder) {
+                entries.push({ prop, resource: val });
+            }
+            else if (Array.isArray(val)) {
+                for (const item of val) {
+                    if (item instanceof BaseBuilder) {
+                        entries.push({ prop, resource: item });
+                    }
+                }
+            }
+        }
+        const resources = [];
+        for (const { prop, resource } of entries) {
+            const existing = await resource._resolveDiscovery();
+            let status;
+            let changes = resource.getDiff(existing ?? {});
+            if (!existing) {
+                status = "missing";
+                changes = [];
+            }
+            else if (existing._adopted === true) {
+                status = "adopted";
+                changes = [];
+            }
+            else {
+                status = changes.length > 0 ? "drift" : "in-sync";
+            }
+            resources.push({ prop, resource: resource.name, status, changes });
+        }
+        const hasDrift = resources.some((r) => r.status === "drift" || r.status === "missing");
+        const result = { stackName: this.constructor.name, resources, hasDrift };
+        printDiff(result);
+        return result;
+    }
     async deploy() {
         const controller = new AbortController();
         const hosts = [];
+        // Snapshot current secrets; new secrets resolved during this run are added via context
+        const secrets = new Set(resolvedSecrets);
         const context = {
             abortSignal: controller.signal,
             hosts,
-            stackName: this.constructor.name
+            stackName: this.constructor.name,
+            secrets,
         };
         return resourceContextStorage.run(context, async () => {
-            const originalLog = console.log;
-            console.log = (...args) => {
-                const redact = (message) => {
-                    if (typeof message !== "string")
-                        return message;
-                    let result = message;
-                    for (const secret of resolvedSecrets) {
-                        if (secret && secret.length >= 3) {
-                            const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
-                            const regex = new RegExp(escaped, 'g');
-                            result = result.replace(regex, '********');
-                        }
-                    }
-                    return result;
-                };
-                const redactedArgs = args.map(arg => {
-                    if (typeof arg === "string") {
-                        return redact(arg);
-                    }
-                    try {
-                        const str = String(arg);
-                        let hasSecret = false;
-                        for (const secret of resolvedSecrets) {
-                            if (secret && secret.length >= 3 && str.includes(secret)) {
-                                hasSecret = true;
-                                break;
-                            }
-                        }
-                        if (hasSecret) {
-                            return redact(str);
-                        }
-                    }
-                    catch { }
-                    return arg;
-                });
-                originalLog(...redactedArgs);
-            };
-            try {
+            return withRedactedConsole(secrets, async () => {
                 console.log(`\n🏗️  Deploying Stack: ${this.constructor.name}`);
                 // Stack-level beforeDeploy hook
                 if (typeof this.beforeDeploy === "function") {
@@ -187,11 +276,13 @@ export class Stack {
                 }
                 // 2. Schedule execution
                 if (isParallel) {
-                    const startPromise = Promise.resolve();
                     const promises = resources.map(({ prop, resource }) => {
                         resource._deployPromise = (async () => {
                             try {
-                                await startPromise;
+                                // Yield so the map() loop finishes assigning all _deployPromise values before
+                                // any task checks its dependencies - a dependency that appears later in the list
+                                // would otherwise have an undefined _deployPromise and be silently skipped.
+                                await Promise.resolve();
                                 if (controller.signal.aborted) {
                                     throw new Error("Deployment aborted due to previous failure");
                                 }
@@ -287,59 +378,21 @@ export class Stack {
                     await this.afterDeploy(outputs);
                 }
                 return outputs;
-            }
-            finally {
-                console.log = originalLog;
-            }
+            });
         });
     }
     async destroy() {
         const controller = new AbortController();
         const hosts = [];
+        const secrets = new Set(resolvedSecrets);
         const context = {
             abortSignal: controller.signal,
             hosts,
-            stackName: this.constructor.name
+            stackName: this.constructor.name,
+            secrets,
         };
         return resourceContextStorage.run(context, async () => {
-            const originalLog = console.log;
-            console.log = (...args) => {
-                const redact = (message) => {
-                    if (typeof message !== "string")
-                        return message;
-                    let result = message;
-                    for (const secret of resolvedSecrets) {
-                        if (secret && secret.length >= 3) {
-                            const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
-                            const regex = new RegExp(escaped, 'g');
-                            result = result.replace(regex, '********');
-                        }
-                    }
-                    return result;
-                };
-                const redactedArgs = args.map(arg => {
-                    if (typeof arg === "string") {
-                        return redact(arg);
-                    }
-                    try {
-                        const str = String(arg);
-                        let hasSecret = false;
-                        for (const secret of resolvedSecrets) {
-                            if (secret && secret.length >= 3 && str.includes(secret)) {
-                                hasSecret = true;
-                                break;
-                            }
-                        }
-                        if (hasSecret) {
-                            return redact(str);
-                        }
-                    }
-                    catch { }
-                    return arg;
-                });
-                originalLog(...redactedArgs);
-            };
-            try {
+            return withRedactedConsole(secrets, async () => {
                 console.log(`\n💥 Tearing down Stack: ${this.constructor.name}`);
                 // Stack-level beforeDestroy hook
                 if (typeof this.beforeDestroy === "function") {
@@ -374,12 +427,13 @@ export class Stack {
                 }
                 // 2. Schedule execution
                 if (isParallel) {
-                    const startPromise = Promise.resolve();
                     // In parallel destroy, await all dependents (reverse dependencies) first
                     const promises = resources.map(({ prop, resource }) => {
                         resource._destroyPromise = (async () => {
                             try {
-                                await startPromise;
+                                // Yield so the map() loop finishes assigning all _destroyPromise values before
+                                // any task checks its dependents (same reason as parallel deploy).
+                                await Promise.resolve();
                                 if (controller.signal.aborted) {
                                     throw new Error("Teardown aborted due to previous failure");
                                 }
@@ -458,10 +512,7 @@ export class Stack {
                     await this.afterDestroy(outputs);
                 }
                 return outputs;
-            }
-            finally {
-                console.log = originalLog;
-            }
+            });
         });
     }
 }

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
-export { Secret } from "./core/secret.js";
+export { Secret, clearResolvedSecrets } from "./core/secret.js";
 export { Output } from "./core/output.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
+export type { FieldDiff, ResourceDiff, StackDiff, ResourceStatus } from "./types/diff.js";
 export { SLACK, DISCORD } from "./core/hooks.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
-export { Secret } from "./core/secret.js";
+export { Secret, clearResolvedSecrets } from "./core/secret.js";
 export { Output } from "./core/output.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
 export { SLACK, DISCORD } from "./core/hooks.js";

package/dist/providers/aws/api.js

@@ -60,6 +60,9 @@ function createAwsOfflineMock(command) {
         get(target, prop) {
             if (prop === "then")
                 return undefined;
+            // Pagination tokens must be undefined so discovery loops exit cleanly
+            if (prop === "NextToken" || prop === "NextMarker" || prop === "Marker" || prop === "ContinuationToken")
+                return undefined;
             if (prop === "CertificateArn")
                 return "arn:aws:acm:us-east-1:123456789012:certificate/mock-cert-uuid";
             if (prop === "HostedZoneId")

package/dist/providers/aws/ec2.d.ts

@@ -29,6 +29,11 @@ export declare class EC2VMBuilder extends BaseBuilder {
     sshPrivateKey(path: string): this;
     provision(...playbookPaths: (string | string[])[]): this;
     forceConfigCheck(): this;
+    getDiff(existing: any): {
+        field: string;
+        declared: string;
+        live: any;
+    }[];
     protected checkPort(ip: string, port: number): Promise<boolean>;
     protected runProvisioner(ip: string, script: string): Promise<void>;
     private discoverVM;

package/dist/providers/aws/ec2.js

@@ -67,6 +67,13 @@ export class EC2VMBuilder extends BaseBuilder {
         this._forceConfigCheck = true;
         return this;
     }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing.InstanceType !== this._instanceType) {
+            diffs.push({ field: "instanceType", declared: this._instanceType, live: existing.InstanceType });
+        }
+        return diffs;
+    }
     async checkPort(ip, port) {
         return checkPort(ip, port);
     }

package/dist/providers/aws/lambda.d.ts

@@ -20,6 +20,11 @@ export declare class LambdaBuilder extends BaseBuilder {
     timeout(seconds: number): this;
     role(arnOrBuilder: string | IAMRoleBuilder): this;
     env(vars: Record<string, string | SecretsBuilder>): this;
+    getDiff(existing: any): {
+        field: string;
+        declared: string;
+        live: any;
+    }[];
     private ensureRole;
     private buildZip;
     deploy(): Promise<{

package/dist/providers/aws/lambda.js

@@ -78,6 +78,30 @@ export class LambdaBuilder extends BaseBuilder {
         this._env = { ...this._env, ...vars };
         return this;
     }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing.Runtime !== this._runtime) {
+            diffs.push({ field: "runtime", declared: this._runtime, live: existing.Runtime });
+        }
+        if (existing.Handler !== this._handler) {
+            diffs.push({ field: "handler", declared: this._handler, live: existing.Handler });
+        }
+        if (existing.MemorySize !== this._memory) {
+            diffs.push({ field: "memory", declared: `${this._memory} MB`, live: `${existing.MemorySize} MB` });
+        }
+        if (existing.Timeout !== this._timeout) {
+            diffs.push({ field: "timeout", declared: `${this._timeout}s`, live: `${existing.Timeout}s` });
+        }
+        const liveEnv = existing.Environment?.Variables ?? {};
+        const declaredKeys = Object.keys(this._env);
+        const liveKeys = Object.keys(liveEnv);
+        const allKeys = new Set([...declaredKeys, ...liveKeys]);
+        const envDrift = [...allKeys].filter((k) => String(this._env[k]) !== String(liveEnv[k]));
+        if (envDrift.length > 0) {
+            diffs.push({ field: "env", declared: `${declaredKeys.length} vars`, live: `${liveKeys.length} vars (${envDrift.length} changed)` });
+        }
+        return diffs;
+    }
     async ensureRole() {
         if (this._roleBuilder) {
             return await this._roleBuilder.out.arn.get();

package/dist/providers/aws/list.js

@@ -3,16 +3,18 @@ import { ListBucketsCommand } from '@aws-sdk/client-s3';
 import { ListFunctionsCommand } from '@aws-sdk/client-lambda';
 import { DescribeDBInstancesCommand } from '@aws-sdk/client-rds';
 import { ListHostedZonesCommand } from '@aws-sdk/client-route-53';
-import { getCFClient, getS3Client, getLambdaClient, getRDSClient, getR53Client } from './api.js';
+import { DescribeInstancesCommand } from '@aws-sdk/client-ec2';
+import { getCFClient, getS3Client, getLambdaClient, getRDSClient, getR53Client, getEC2Client } from './api.js';
 import { Config } from '../../core/config.js';
 export async function listAwsResources() {
     const region = Config.get().providers.aws.region;
-    const [cfResult, s3Result, lambdaResult, rdsResult, r53Result] = await Promise.all([
+    const [cfResult, s3Result, lambdaResult, rdsResult, r53Result, ec2Result] = await Promise.all([
         getCFClient().send(new ListDistributionsCommand({})),
         getS3Client().send(new ListBucketsCommand({})),
         getLambdaClient().send(new ListFunctionsCommand({ MaxItems: 50 })),
         getRDSClient().send(new DescribeDBInstancesCommand({})),
         getR53Client().send(new ListHostedZonesCommand({})),
+        getEC2Client().send(new DescribeInstancesCommand({ MaxResults: 200 })),
     ]);
     const distributions = (cfResult.DistributionList?.Items ?? []).map((d) => ({
         id: d.Id,
@@ -40,5 +42,15 @@ export async function listAwsResources() {
         id: z.Id.replace('/hostedzone/', ''),
         recordCount: z.ResourceRecordSetCount ?? 0,
     }));
-    return { region, distributions, buckets, lambdas, rdsInstances, hostedZones };
+    const ec2Instances = (ec2Result.Reservations ?? [])
+        .flatMap((r) => r.Instances ?? [])
+        .filter((i) => i.State?.Name !== 'terminated')
+        .map((i) => ({
+        id: i.InstanceId,
+        name: i.Tags?.find((t) => t.Key === 'Name')?.Value ?? i.InstanceId,
+        type: i.InstanceType ?? 'unknown',
+        state: i.State?.Name ?? 'unknown',
+        publicIp: i.PublicIpAddress,
+    }));
+    return { region, distributions, buckets, lambdas, rdsInstances, hostedZones, ec2Instances };
 }

package/dist/providers/aws/rds.d.ts

@@ -24,6 +24,15 @@ export declare class RDSBuilder extends BaseBuilder {
     subnets(ids: string[]): this;
     securityGroups(ids: string[]): this;
     publicAccess(enabled?: boolean): this;
+    getDiff(existing: any): ({
+        field: string;
+        declared: string;
+        live: any;
+    } | {
+        field: string;
+        declared: boolean;
+        live: any;
+    })[];
     database(name: string): this;
     credentials(username: string, password: string): this;
     private discoverInstance;

package/dist/providers/aws/rds.js

@@ -54,6 +54,25 @@ export class RDSBuilder extends BaseBuilder {
         this._publicAccess = enabled;
         return this;
     }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing.Engine !== this._engine) {
+            diffs.push({ field: "engine", declared: this._engine, live: existing.Engine });
+        }
+        if (existing.EngineVersion !== this._engineVersion) {
+            diffs.push({ field: "engineVersion", declared: this._engineVersion, live: existing.EngineVersion });
+        }
+        if (existing.DBInstanceClass !== this._instanceClass) {
+            diffs.push({ field: "instanceClass", declared: this._instanceClass, live: existing.DBInstanceClass });
+        }
+        if (existing.AllocatedStorage !== this._storage) {
+            diffs.push({ field: "storage", declared: `${this._storage} GB`, live: `${existing.AllocatedStorage} GB` });
+        }
+        if (existing.PubliclyAccessible !== this._publicAccess) {
+            diffs.push({ field: "publicAccess", declared: this._publicAccess, live: existing.PubliclyAccessible });
+        }
+        return diffs;
+    }
     database(name) {
         this._dbName = name;
         return this;

package/dist/providers/do/database.d.ts

@@ -26,6 +26,15 @@ export declare class DatabaseBuilder extends BaseBuilder {
     allowIp(cidr: string): this;
     allowDroplet(dropletId: string): this;
     allowTag(tagName: string): this;
+    getDiff(existing: any): ({
+        field: string;
+        declared: string;
+        live: any;
+    } | {
+        field: string;
+        declared: number;
+        live: any;
+    })[];
     private discoverCluster;
     deploy(): Promise<{
         name: string;

package/dist/providers/do/database.js

@@ -58,6 +58,25 @@ export class DatabaseBuilder extends BaseBuilder {
         this._firewallRules.push({ type: "tag", value: tagName });
         return this;
     }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing.engine !== this._engine) {
+            diffs.push({ field: "engine", declared: this._engine, live: existing.engine });
+        }
+        if (existing.version !== this._version) {
+            diffs.push({ field: "version", declared: this._version, live: existing.version });
+        }
+        if (existing.size !== this._size) {
+            diffs.push({ field: "size", declared: this._size, live: existing.size });
+        }
+        if (existing.region !== this._region) {
+            diffs.push({ field: "region", declared: this._region, live: existing.region });
+        }
+        if (existing.num_nodes !== this._nodes) {
+            diffs.push({ field: "nodes", declared: this._nodes, live: existing.num_nodes });
+        }
+        return diffs;
+    }
     async discoverCluster(name) {
         try {
             const api = getDoApi();

package/dist/providers/do/domain.js

@@ -104,7 +104,7 @@ export class DomainBuilder extends BaseBuilder {
         if (existing) {
             try {
                 const res = await api.get(`/domains/${this.domainName}/records?per_page=200`);
-                existingRecords = res.domain_records;
+                existingRecords = res.domain_records ?? [];
             }
             catch {
                 existingRecords = [];

package/dist/providers/do/droplet.d.ts

@@ -12,6 +12,7 @@ export declare class DropletBuilder extends BaseBuilder {
     private dropletId?;
     private resolvedIp?;
     private sshKeyPath?;
+    private _sshUser?;
     private _provision;
     private _forceConfigCheck;
     constructor(name: string);
@@ -21,10 +22,19 @@ export declare class DropletBuilder extends BaseBuilder {
     image(image: (typeof OS)[keyof typeof OS] | string): this;
     region(region: (typeof REGION)[keyof typeof REGION] | string): this;
     size(size: (typeof SIZE)[keyof typeof SIZE] | string): this;
+    sshKey(keyPath: string): this;
+    /** @deprecated Use `.sshKey()` instead */
     sslKey(keyPath: string): this;
+    sshUser(user: string): this;
+    private resolveUser;
     vpc(uuid: string | Output<string>): this;
     provision(...playbookPaths: (string | string[])[]): this;
     forceConfigCheck(): this;
+    getDiff(existing: any): {
+        field: string;
+        declared: any;
+        live: any;
+    }[];
     protected checkPort(ip: string, port: number): Promise<boolean>;
     protected runProvisioner(ip: string, script: string): Promise<void>;
     private resolveOrRegisterSshKey;