puls-dev 0.3.4 → 0.3.5

package/dist/bin/install-shell.d.ts

@@ -0,0 +1,2 @@
+export declare function installShell(): void;
+export declare function uninstallShell(): void;

package/dist/bin/install-shell.js

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const MARKER = "# added by puls-dev";
+const LAUNCHER_CONTENT = `#!/bin/sh
+exec npx --yes puls-dev "$@"
+`;
+function detectShellConfig() {
+    const shellBin = process.env.SHELL ?? "";
+    if (shellBin.endsWith("zsh")) {
+        return { shell: "zsh", configFile: path.join(os.homedir(), ".zshrc") };
+    }
+    if (shellBin.endsWith("bash")) {
+        // macOS uses ~/.bash_profile for login shells; Linux uses ~/.bashrc
+        const isMac = process.platform === "darwin";
+        const configFile = isMac
+            ? path.join(os.homedir(), ".bash_profile")
+            : path.join(os.homedir(), ".bashrc");
+        return { shell: "bash", configFile };
+    }
+    if (shellBin.endsWith("fish")) {
+        return {
+            shell: "fish",
+            configFile: path.join(os.homedir(), ".config", "fish", "config.fish"),
+        };
+    }
+    return null;
+}
+function buildPathLine(shell) {
+    if (shell === "fish") {
+        return `fish_add_path "$HOME/.puls/bin"`;
+    }
+    return `export PATH="$HOME/.puls/bin:$PATH"`;
+}
+export function installShell() {
+    const home = os.homedir();
+    const launcherDir = path.join(home, ".puls", "bin");
+    const launcherPath = path.join(launcherDir, "puls");
+    // 1. Create launcher
+    const launcherExists = fs.existsSync(launcherPath);
+    if (!launcherExists) {
+        fs.mkdirSync(launcherDir, { recursive: true });
+        fs.writeFileSync(launcherPath, LAUNCHER_CONTENT, { encoding: "utf8" });
+        fs.chmodSync(launcherPath, 0o755);
+        console.log(`✅ Created launcher at ${launcherPath}`);
+    }
+    else {
+        console.log(`   Launcher already exists at ${launcherPath}`);
+    }
+    // 2. Detect shell config
+    const detected = detectShellConfig();
+    if (!detected) {
+        console.log(`\n⚠️  Could not detect your shell from $SHELL="${process.env.SHELL ?? ""}".`);
+        console.log(`   Add this line manually to your shell config:\n`);
+        console.log(`     export PATH="$HOME/.puls/bin:$PATH"\n`);
+        return;
+    }
+    const { shell, configFile } = detected;
+    const pathLine = buildPathLine(shell);
+    // 3. Ensure config file exists
+    if (!fs.existsSync(configFile)) {
+        fs.mkdirSync(path.dirname(configFile), { recursive: true });
+        fs.writeFileSync(configFile, "", "utf8");
+    }
+    // 4. Check if already present (idempotent)
+    const existing = fs.readFileSync(configFile, "utf8");
+    if (existing.includes(MARKER)) {
+        console.log(`   Shell config already updated (${configFile})`);
+        console.log(`\n✅ puls is already set up. Open a new terminal or run:\n`);
+        console.log(`   source ${configFile}\n`);
+        return;
+    }
+    // 5. Append PATH entry with marker
+    const addition = `\n${MARKER}\n${pathLine}\n`;
+    fs.appendFileSync(configFile, addition, "utf8");
+    console.log(`✅ Added puls to PATH in ${configFile}`);
+    console.log(`\n🎉 All done! Activate now by running:\n`);
+    console.log(`   source ${configFile}`);
+    console.log(`\nThen use puls directly:\n`);
+    console.log(`   puls plan   infra/stack.ts`);
+    console.log(`   puls deploy infra/stack.ts`);
+    console.log(`   puls diff   infra/stack.ts\n`);
+}
+export function uninstallShell() {
+    const home = os.homedir();
+    const launcherPath = path.join(home, ".puls", "bin", "puls");
+    const launcherDir = path.join(home, ".puls", "bin");
+    // 1. Remove launcher
+    if (fs.existsSync(launcherPath)) {
+        fs.rmSync(launcherPath);
+        console.log(`✅ Removed launcher at ${launcherPath}`);
+        // Clean up empty dirs
+        try {
+            fs.rmdirSync(launcherDir);
+            fs.rmdirSync(path.join(home, ".puls"));
+        }
+        catch {
+            // Non-empty dirs left behind (user may have other files) — that's fine
+        }
+    }
+    else {
+        console.log(`   Launcher not found at ${launcherPath} — nothing to remove.`);
+    }
+    // 2. Remove PATH line from shell config
+    const detected = detectShellConfig();
+    if (!detected) {
+        console.log(`\n⚠️  Could not detect shell config. Remove the puls PATH line manually.`);
+        return;
+    }
+    const { configFile } = detected;
+    if (!fs.existsSync(configFile)) {
+        console.log(`   Shell config not found at ${configFile} — nothing to clean up.`);
+        return;
+    }
+    const content = fs.readFileSync(configFile, "utf8");
+    if (!content.includes(MARKER)) {
+        console.log(`   Shell config at ${configFile} has no puls entry — nothing to remove.`);
+        return;
+    }
+    // Remove the marker line and the PATH line that follows it
+    const cleaned = content
+        .split("\n")
+        .reduce((acc, line) => {
+        if (line.trim() === MARKER)
+            return { out: acc.out, skip: true };
+        if (acc.skip)
+            return { out: acc.out, skip: false }; // skip the PATH line
+        return { out: [...acc.out, line], skip: false };
+    }, { out: [], skip: false })
+        .out
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n"); // collapse triple+ blank lines
+    fs.writeFileSync(configFile, cleaned, "utf8");
+    console.log(`✅ Removed puls PATH entry from ${configFile}`);
+    console.log(`\n   Restart your terminal for changes to take effect.\n`);
+}

package/dist/bin/puls.js

@@ -5,6 +5,7 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
+import { installShell, uninstallShell } from "./install-shell.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
@@ -32,20 +33,26 @@ function getVersion() {
 }
 const HELP = `
 Usage:
-  puls plan    <file>   Dry-run the stack — prints what would change, no API writes
-  puls deploy  <file>   Deploy the stack
-  puls destroy <file>   Destroy the stack
+  puls plan             <file>   Dry-run the stack - prints what would change, no API writes
+  puls deploy           <file>   Deploy the stack
+  puls destroy          <file>   Destroy the stack
+  puls diff             <file>   Compare declared intent against live cloud state
+  puls install-shell             Add puls to your shell so you never need npx again
+  puls uninstall-shell           Remove the puls shell integration
 
 Options:
-  --parallel   Enable parallel resource execution
-  --dry-run    Force dry-run mode (alias: same as plan)
-  --version    Print version and exit
-  --help       Print this help and exit
+  --parallel       Enable parallel resource execution
+  --dry-run        Force dry-run mode (alias: same as plan)
+  --fail-on-drift  Exit with code 1 if drift is detected (diff command only)
+  --version        Print version and exit
+  --help           Print this help and exit
 
 Examples:
+  npx puls install-shell         # one-time setup — then just use "puls" directly
   puls plan    infra/staging.ts
   puls deploy  infra/staging.ts --parallel
   puls destroy infra/staging.ts
+  puls diff    infra/staging.ts --fail-on-drift
 `.trim();
 let parsed;
 try {
@@ -54,6 +61,7 @@ try {
         options: {
             parallel: { type: "boolean" },
             "dry-run": { type: "boolean" },
+            "fail-on-drift": { type: "boolean" },
             version: { type: "boolean", short: "v" },
             help: { type: "boolean", short: "h" },
         },
@@ -76,12 +84,20 @@ if (values.help || positionals.length === 0) {
     process.exit(0);
 }
 const [command, userFile] = positionals;
-const COMMANDS = ["plan", "deploy", "destroy"];
+const COMMANDS = ["plan", "deploy", "destroy", "diff", "install-shell", "uninstall-shell"];
 if (!COMMANDS.includes(command)) {
-    console.error(`Error: Unknown command "${command}". Expected: plan, deploy, or destroy.`);
-    console.error('Run "puls --help" for usage.');
+    console.error(`Error: Unknown command "${command}". Run "puls --help" for usage.`);
     process.exit(1);
 }
+// Shell management commands run directly — no stack file needed
+if (command === "install-shell") {
+    installShell();
+    process.exit(0);
+}
+if (command === "uninstall-shell") {
+    uninstallShell();
+    process.exit(0);
+}
 if (!userFile) {
     console.error(`Error: Missing file argument.\nUsage: puls ${command} <file>`);
     process.exit(1);
@@ -98,9 +114,15 @@ if (command === "plan" || values["dry-run"]) {
 if (command === "destroy") {
     childEnv.PULS_MODE = "destroy";
 }
+if (command === "diff") {
+    childEnv.PULS_MODE = "diff";
+}
 if (values.parallel) {
     childEnv.PULS_PARALLEL = "true";
 }
+if (values["fail-on-drift"]) {
+    childEnv.PULS_FAIL_ON_DRIFT = "true";
+}
 const tsxBin = findTsx() ?? "tsx";
 const child = spawn(tsxBin, [resolvedFile], {
     stdio: "inherit",

package/dist/core/checker.js

@@ -48,6 +48,13 @@ function renderProxmox(inv) {
             render: (v) => `${Math.round(v.maxdisk / 1024 ** 3)}GB`,
         },
     ]);
+    if (inv.templates.length > 0) {
+        printSection(`Proxmox Templates  ·  ${inv.templates.length}`, inv.templates, [
+            { header: "Name", width: 32, render: (t) => t.name },
+            { header: "VMID", width: 6, render: (t) => String(t.vmid) },
+            { header: "Node", width: 12, render: (t) => t.node },
+        ]);
+    }
 }
 function renderDo(inv) {
     const costStr = inv.totalMonthlyCost > 0 ? `  ·  $${inv.totalMonthlyCost}/mo` : "";
@@ -83,8 +90,40 @@ function renderDo(inv) {
             { header: "TTL", width: 6, render: (d) => String(d.ttl) },
         ]);
     }
+    if (inv.databases.length > 0) {
+        printSection(`DigitalOcean Databases  ·  ${inv.databases.length}`, inv.databases, [
+            { header: "Name", width: 24, render: (d) => d.name },
+            { header: "Engine", width: 14, render: (d) => d.engine },
+            { header: "Region", width: 8, render: (d) => d.region },
+            { header: "Status", width: 10, render: (d) => d.status },
+            { header: "Nodes", width: 5, render: (d) => String(d.nodeCount) },
+        ]);
+    }
+    if (inv.apps.length > 0) {
+        printSection(`DigitalOcean Apps  ·  ${inv.apps.length}`, inv.apps, [
+            { header: "Name", width: 24, render: (a) => a.name },
+            { header: "Status", width: 12, render: (a) => a.status },
+            { header: "URL", width: 40, render: (a) => a.liveUrl || "-" },
+        ]);
+    }
+    if (inv.vpcs.length > 0) {
+        printSection(`DigitalOcean VPCs  ·  ${inv.vpcs.length}`, inv.vpcs, [
+            { header: "Name", width: 24, render: (v) => v.name },
+            { header: "Region", width: 8, render: (v) => v.region },
+            { header: "IP Range", width: 20, render: (v) => v.ipRange },
+        ]);
+    }
 }
 function renderAws(inv) {
+    if (inv.ec2Instances.length > 0) {
+        printSection(`AWS EC2  ·  ${inv.ec2Instances.length} instances  ·  ${inv.region}`, inv.ec2Instances, [
+            { header: "Name", width: 24, render: (i) => i.name },
+            { header: "ID", width: 20, render: (i) => i.id },
+            { header: "Type", width: 14, render: (i) => i.type },
+            { header: "State", width: 10, render: (i) => i.state },
+            { header: "IP", width: 15, render: (i) => i.publicIp ?? "-" },
+        ]);
+    }
     if (inv.distributions.length > 0) {
         printSection(`AWS CloudFront  ·  ${inv.distributions.length}  ·  ${inv.region}`, inv.distributions, [
             { header: "ID", width: 14, render: (d) => d.id },
@@ -154,6 +193,16 @@ function renderGcp(inv) {
             { header: "DNS Name", width: 32, render: (z) => z.dnsName },
         ]);
     }
+    if (inv.pubSubTopics.length > 0) {
+        printSection(`GCP Pub/Sub Topics  ·  ${inv.pubSubTopics.length}`, inv.pubSubTopics, [
+            { header: "Topic", width: 52, render: (t) => t.name },
+        ]);
+    }
+    if (inv.secrets.length > 0) {
+        printSection(`GCP Secret Manager  ·  ${inv.secrets.length}`, inv.secrets, [
+            { header: "Secret", width: 52, render: (s) => s.name },
+        ]);
+    }
 }
 function renderFirebase(inv) {
     if (inv.hostingSites.length > 0) {
@@ -169,6 +218,31 @@ function renderFirebase(inv) {
             { header: "Runtime", width: 10, render: (f) => f.runtime },
         ]);
     }
+    if (inv.firestoreDbs.length > 0) {
+        printSection(`Firebase Firestore  ·  ${inv.firestoreDbs.length}`, inv.firestoreDbs, [
+            { header: "Database", width: 24, render: (d) => d.name },
+            { header: "Type", width: 20, render: (d) => d.type },
+            { header: "State", width: 10, render: (d) => d.state },
+        ]);
+    }
+    if (inv.storageBuckets.length > 0) {
+        printSection(`Firebase Storage  ·  ${inv.storageBuckets.length}`, inv.storageBuckets, [
+            { header: "Bucket", width: 40, render: (b) => b.name },
+            { header: "Location", width: 12, render: (b) => b.location },
+        ]);
+    }
+    if (inv.authProviders.length > 0) {
+        printSection(`Firebase Auth  ·  ${inv.authProviders.length} provider${inv.authProviders.length !== 1 ? "s" : ""}`, inv.authProviders, [
+            { header: "Provider", width: 32, render: (p) => p.providerId },
+        ]);
+    }
+    if (inv.remoteConfig) {
+        const rc = inv.remoteConfig;
+        printSection(`Firebase RemoteConfig  ·  v${rc.version}`, [rc], [
+            { header: "Parameters", width: 10, render: (r) => String(r.parameterCount) },
+            { header: "Version", width: 12, render: (r) => r.version },
+        ]);
+    }
 }
 // ─── Checker ──────────────────────────────────────────────────────────────────
 export class Checker {

package/dist/core/decorators.js

@@ -23,7 +23,7 @@ function applyConfig(opts) {
             },
         });
     }
-    // CLI env-var overrides — applied last so `puls plan/destroy/--parallel` wins over decorator options
+    // CLI env-var overrides - applied last so `puls plan/destroy/--parallel` wins over decorator options
     if (process.env.PULS_DRY_RUN === "true")
         Config.set({ dryRun: true });
     if (process.env.PULS_PARALLEL === "true")
@@ -91,6 +91,14 @@ export function Deploy(opts = {}) {
                         if (typeof instance.destroy === "function")
                             await instance.destroy();
                     }
+                    else if (mode === "diff") {
+                        if (typeof instance.diff === "function") {
+                            const result = await instance.diff();
+                            if (process.env.PULS_FAIL_ON_DRIFT === "true" && result?.hasDrift) {
+                                process.exitCode = 1;
+                            }
+                        }
+                    }
                     else {
                         if (typeof instance.deploy === "function")
                             await instance.deploy();
@@ -107,6 +115,14 @@ export function Deploy(opts = {}) {
                     if (typeof instance.destroy === "function")
                         await instance.destroy();
                 }
+                else if (mode === "diff") {
+                    if (typeof instance.diff === "function") {
+                        const result = await instance.diff();
+                        if (process.env.PULS_FAIL_ON_DRIFT === "true" && result?.hasDrift) {
+                            process.exitCode = 1;
+                        }
+                    }
+                }
                 else {
                     if (typeof instance.deploy === "function")
                         await instance.deploy();

package/dist/core/resource.d.ts

@@ -1,12 +1,16 @@
+import type { FieldDiff } from "../types/diff.js";
 export declare abstract class BaseBuilder {
     name: string;
     protected isProtected: boolean;
     protected localDryRun: boolean | null;
     protected discoveryPromise: Promise<any>;
     protected sidecars: BaseBuilder[];
+    protected _adoptedId: string | null;
     /** @internal */
     _deployPromise: Promise<any>;
     /** @internal */
+    _resolveDiscovery(): Promise<any>;
+    /** @internal */
     _destroyPromise?: Promise<any>;
     /** @internal */
     _dependencies: BaseBuilder[];
@@ -17,6 +21,37 @@ export declare abstract class BaseBuilder {
     constructor(name: string);
     dependsOn(resource: BaseBuilder): this;
     protect(): this;
+    /**
+     * Adopt an existing cloud resource by its provider ID, bringing it under
+     * Puls management without recreating it. If name-based discovery finds the
+     * resource, that result wins; adoptId only kicks in when discovery returns
+     * null (i.e. the resource was created outside this stack or with a different
+     * naming convention).
+     *
+     * Outputs that depend on live API response fields (e.g. `out.host`) won't be
+     * resolved automatically — chain `.adoptOutput(key, value)` for each one you
+     * need for cross-stack wiring.
+     */
+    adoptId(id: string): this;
+    /**
+     * Pre-resolve a named output on this builder. Use alongside `adoptId` to
+     * supply known connection details (host, port, uri, etc.) so downstream
+     * resources can reference them before this builder deploys.
+     *
+     * @example
+     *   db = DO.Database("prod-db")
+     *     .adoptId("abc123")
+     *     .adoptOutput("host", "db.internal.example.com")
+     *     .adoptOutput("uri", "postgres://...");
+     */
+    /**
+     * Returns field-level differences between declared intent and live cloud state.
+     * Called by `Stack.diff()` for each resource that exists. Override in provider
+     * builders to surface meaningful drift fields. The default returns an empty array
+     * (no field-level diff available).
+     */
+    getDiff(_existing: any): FieldDiff[];
+    adoptOutput(key: string, value: any): this;
     dryRun(enabled?: boolean): this;
     beforeDeploy(callback: () => Promise<void> | void): this;
     afterDeploy(callback: (result: any) => Promise<void> | void): this;

package/dist/core/resource.js

@@ -5,9 +5,14 @@ export class BaseBuilder {
     localDryRun = null;
     discoveryPromise;
     sidecars = [];
+    _adoptedId = null;
     /** @internal */
     _deployPromise;
     /** @internal */
+    async _resolveDiscovery() {
+        return this.discoveryPromise;
+    }
+    /** @internal */
     _destroyPromise;
     /** @internal */
     _dependencies = [];
@@ -26,6 +31,56 @@ export class BaseBuilder {
         this.isProtected = true;
         return this;
     }
+    /**
+     * Adopt an existing cloud resource by its provider ID, bringing it under
+     * Puls management without recreating it. If name-based discovery finds the
+     * resource, that result wins; adoptId only kicks in when discovery returns
+     * null (i.e. the resource was created outside this stack or with a different
+     * naming convention).
+     *
+     * Outputs that depend on live API response fields (e.g. `out.host`) won't be
+     * resolved automatically — chain `.adoptOutput(key, value)` for each one you
+     * need for cross-stack wiring.
+     */
+    adoptId(id) {
+        this._adoptedId = id;
+        const original = this.discoveryPromise;
+        this.discoveryPromise = original.then((found) => {
+            if (!found) {
+                this.out?.id?.resolve?.(id);
+                return { id, status: "adopted", _adopted: true };
+            }
+            return found;
+        });
+        return this;
+    }
+    /**
+     * Pre-resolve a named output on this builder. Use alongside `adoptId` to
+     * supply known connection details (host, port, uri, etc.) so downstream
+     * resources can reference them before this builder deploys.
+     *
+     * @example
+     *   db = DO.Database("prod-db")
+     *     .adoptId("abc123")
+     *     .adoptOutput("host", "db.internal.example.com")
+     *     .adoptOutput("uri", "postgres://...");
+     */
+    /**
+     * Returns field-level differences between declared intent and live cloud state.
+     * Called by `Stack.diff()` for each resource that exists. Override in provider
+     * builders to surface meaningful drift fields. The default returns an empty array
+     * (no field-level diff available).
+     */
+    getDiff(_existing) {
+        return [];
+    }
+    adoptOutput(key, value) {
+        const out = this.out;
+        if (typeof out?.[key]?.resolve === "function") {
+            out[key].resolve(value);
+        }
+        return this;
+    }
     dryRun(enabled = true) {
         this.localDryRun = enabled;
         return this;
@@ -123,7 +178,8 @@ export class BaseBuilder {
     }
     async destroy() {
         const dryRun = this.isDryRunActive();
-        console.log(`\n🗑️  Destroying "${this.name}"...`);
+        const adoptedSuffix = this._adoptedId ? ` [adopted id=${this._adoptedId}]` : "";
+        console.log(`\n🗑️  Destroying "${this.name}"${adoptedSuffix}...`);
         console.log(`   ✅ [${dryRun ? "PLAN" : "OK"}] Resource "${this.name}" marked for destruction.`);
         await this.destroySidecars();
         return { destroyed: this.name };

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

@@ -107,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) {
@@ -135,6 +174,54 @@ 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 = [];
@@ -193,7 +280,7 @@ export class Stack {
                         resource._deployPromise = (async () => {
                             try {
                                 // Yield so the map() loop finishes assigning all _deployPromise values before
-                                // any task checks its dependencies — a dependency that appears later in the list
+                                // 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) {

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from "./core/resource.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/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;