puls-dev 0.3.3 → 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.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/puls.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+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);
+function findTsx() {
+    let dir = process.cwd();
+    while (true) {
+        const candidate = path.join(dir, "node_modules", ".bin", "tsx");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function getVersion() {
+    try {
+        const pkg = require(path.join(__dirname, "../../package.json"));
+        return pkg.version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+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 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)
+  --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 {
+    parsed = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            parallel: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            "fail-on-drift": { type: "boolean" },
+            version: { type: "boolean", short: "v" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+}
+catch (err) {
+    console.error(`Error: ${err.message}`);
+    console.error('Run "puls --help" for usage.');
+    process.exit(1);
+}
+const { values, positionals } = parsed;
+if (values.version) {
+    console.log(`puls v${getVersion()}`);
+    process.exit(0);
+}
+if (values.help || positionals.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+}
+const [command, userFile] = positionals;
+const COMMANDS = ["plan", "deploy", "destroy", "diff", "install-shell", "uninstall-shell"];
+if (!COMMANDS.includes(command)) {
+    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);
+}
+const resolvedFile = path.resolve(process.cwd(), userFile);
+if (!existsSync(resolvedFile)) {
+    console.error(`Error: File not found: ${resolvedFile}`);
+    process.exit(1);
+}
+const childEnv = { ...process.env };
+if (command === "plan" || values["dry-run"]) {
+    childEnv.PULS_DRY_RUN = "true";
+}
+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",
+    env: childEnv,
+});
+child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+        console.error("Error: Could not find tsx. Install it in your project:\n\n" +
+            "  npm install --save-dev tsx\n\n" +
+            "or globally:\n\n" +
+            "  npm install -g tsx");
+    }
+    else {
+        console.error(`Error spawning tsx: ${err.message}`);
+    }
+    process.exit(1);
+});
+child.on("close", (code) => {
+    process.exit(code ?? 1);
+});

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/config.d.ts

@@ -9,6 +9,7 @@ export interface GlobalConfig {
             defaultRegion?: string;
             spacesAccessKey?: string;
             spacesSecretKey?: string;
+            sshUser?: string;
         };
         aws?: {
             region: string;
@@ -23,6 +24,7 @@ export interface GlobalConfig {
             dnsDomain?: string;
             dnsServers?: string[];
             verifySsl?: boolean;
+            sshUser?: string;
         };
         firebase?: {
             projectId: string;
@@ -32,6 +34,7 @@ export interface GlobalConfig {
             projectId?: string;
             serviceAccountPath?: string;
             region?: string;
+            sshUser?: string;
         };
     };
 }

package/dist/core/context.d.ts

@@ -10,5 +10,6 @@ export interface ResourceContext {
     abortSignal?: AbortSignal;
     hosts?: HostEntry[];
     stackName?: string;
+    secrets: Set<string>;
 }
 export declare const resourceContextStorage: AsyncLocalStorage<ResourceContext>;

package/dist/core/decorators.d.ts

@@ -17,6 +17,7 @@ type ProviderOpts = {
         dnsDomain?: string;
         dnsServers?: string[];
         verifySsl?: boolean;
+        sshUser?: string;
     };
 };
 export declare function Protected(target: any, propertyKey: string): void;

package/dist/core/decorators.js

@@ -23,6 +23,11 @@ function applyConfig(opts) {
             },
         });
     }
+    // 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")
+        Config.set({ parallel: true });
 }
 export function Protected(target, propertyKey) {
     Reflect.defineMetadata("protected", true, target, propertyKey);
@@ -73,15 +78,30 @@ export function Destroy(optsOrTarget, propertyKey) {
 export function Deploy(opts = {}) {
     return function (constructor) {
         const regions = opts.regions ?? [];
+        const mode = process.env.PULS_MODE;
         if (regions.length > 0) {
             Promise.resolve().then(async () => {
                 for (const r of regions) {
-                    console.log(`\n🌍 [MULTI-REGION] Deploying stack to region: ${r}`);
+                    const label = mode === "destroy" ? "Tearing down" : "Deploying";
+                    console.log(`\n🌍 [MULTI-REGION] ${label} stack in region: ${r}`);
                     applyConfig({ ...opts, region: r });
                     const instance = new constructor();
                     Stack._register(constructor, instance, r);
-                    if (typeof instance.deploy === "function") {
-                        await instance.deploy();
+                    if (mode === "destroy") {
+                        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();
                     }
                 }
             });
@@ -91,8 +111,22 @@ export function Deploy(opts = {}) {
             const instance = new constructor();
             Stack._register(constructor, instance);
             Promise.resolve().then(async () => {
-                if (typeof instance.deploy === "function")
-                    await instance.deploy();
+                if (mode === "destroy") {
+                    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/output.js

@@ -20,7 +20,14 @@ export class Output {
     // Transform this output into a new Output<U> without awaiting it yourself.
     apply(fn) {
         const out = new Output();
-        this._promise.then(v => out.resolve(fn(v)), err => out.reject(err));
+        this._promise.then(v => {
+            try {
+                out.resolve(fn(v));
+            }
+            catch (e) {
+                out.reject(e);
+            }
+        }, err => out.reject(err));
         return out;
     }
 }

package/dist/core/production.test.js

@@ -165,6 +165,7 @@ describe("Production Features Unit Tests", () => {
     test("Ansible Provisioner Stack-Wide Dynamic Inventory Generation", async () => {
         const context = {
             stackName: "my-test-stack",
+            secrets: new Set(),
             hosts: [
                 { name: "web1", ip: "1.2.3.4", user: "root", sshKey: "/path/to/key", provider: "do" },
                 { name: "db1", ip: "5.6.7.8", user: "ubuntu", sshKey: "/path/to/other-key", provider: "aws" }

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/secret.d.ts

@@ -1,5 +1,6 @@
 import { Output } from "./output.js";
 export declare const resolvedSecrets: Set<string>;
+export declare function clearResolvedSecrets(): void;
 /**
  * Secret represents a lazy, secure credential that is fetched asynchronously
  * at deployment time instead of during the eager construction phase.