puls-dev 0.3.4 → 0.3.6

package/README.md

@@ -1,27 +1,26 @@
 # Pulsdev.io
 
-**Intent-driven infrastructure-as-code. Describe what you want - Puls figures out create, update, or skip.**
+**Intent-driven infrastructure-as-code. Describe what you want — Puls figures out create, update, or skip.**
 
-[Live Documentation](https://pulsdev.io/) | Matrix|Gitter: **pulsdev.io** ([Join](https://matrix.to/#/#pulsdevio:gitter.im))
+[Live Documentation](https://pulsdev.io/) | [GitHub Actions](docs/github-actions.md) | Matrix|Gitter: **pulsdev.io** ([Join](https://matrix.to/#/#pulsdevio:gitter.im))
 
 > [!IMPORTANT]
 > **Active Pre-1.0 Development**
-> `pulsdev.io` is currently undergoing **active development**. While the framework features exhaustive 100% test coverage and strict production safety locks (such as dry-run planning and protected resource decorators), APIs and features are actively evolving.
-> We are aggressively rolling out new resources and provider integrations. We welcome your feedback, bug reports, and contributions!
+> `pulsdev.io` is under active development. APIs and features are evolving — we welcome feedback, bug reports, and contributions!
 
 ```typescript
 @Deploy({ proxmox: CONFIG.STAGING })
 class GameInfra extends Stack {
-  server = Proxmox.VM("example-vm")
+  server = Proxmox.VM("ix-app01")
     .image(OS.UBUNTU_24_04)
     .cores(4).memory(8192)
-    .ip("1.1.1.1").vlan(2010)
+    .ip("10.8.10.51").vlan(2010)
     .sshKey(KEYS)
     .provision("config/default.yaml");
 }
 ```
 
-No state files. No plan step. Runs against real APIs - idempotent by default.
+No state files. No plan step. Runs against real APIs — idempotent by default.
 
 ---
 
@@ -35,20 +34,52 @@ Declare resource  →  Discovery fires immediately (async)
                   →  deploy() awaits discovery, diffs, acts
 ```
 
-Running the same stack twice is always safe - existing resources are detected and skipped.
+Running the same stack twice is always safe — existing resources are detected and skipped or updated in place.
 
 ---
 
-## Providers
+## Install
+
+```bash
+npm install puls-dev
+```
+
+**One-time shell setup** — so you never have to type `npx puls` again:
+
+```bash
+npx puls install-shell
+```
+
+This adds a `puls` launcher to `~/.puls/bin` and wires it into your shell config (`~/.zshrc`, `~/.bashrc`, or Fish). Open a new terminal and `puls` works everywhere.
 
-| Provider | Resources | Status |
-|----------|-----------|--------|
-| [Google Cloud Platform (GCP)](docs/providers/gcp.md) | Cloud Run, Cloud SQL, Secret Manager, Pub/Sub, Cloud DNS, IAM (Service Accounts & Bindings) | **Completed** |
-| [AWS](docs/providers/aws.md) | Route53, ACM (wildcard SSL), CloudFront, S3 | **Completed** |
-| [Firebase](docs/providers/firebase.md) | Hosting, Functions, Firestore (Indexes & Rules), Storage (Rules/CORS), Auth, Remote Config, App Check | **Completed** |
-| [DigitalOcean](docs/providers/digitalocean.md) | Droplet, Domain, Firewall, Certificate, LoadBalancer | **Completed** |
-| [Proxmox](docs/providers/proxmox.md) | VM (clone, cloud-init, provision, cluster-aware node selection, replace) | **Completed** |
+---
+
+## CLI
+
+```bash
+puls plan    infra/stack.ts          # dry-run — prints what would change, no API writes
+puls deploy  infra/stack.ts          # apply the stack
+puls destroy infra/stack.ts          # tear down the stack
+puls diff    infra/stack.ts          # compare declared intent vs live cloud state
+puls diff    infra/stack.ts --fail-on-drift   # exit 1 if anything has drifted
+
+puls install-shell                   # one-time shell setup
+puls uninstall-shell                 # remove shell integration
+```
+
+Always run `plan` before `deploy` — it activates dry-run mode automatically.
+
+---
+
+## Providers
 
+| Provider | Resources |
+|----------|-----------|
+| **AWS** | EC2, RDS, Lambda, ECS/Fargate, API Gateway, S3, CloudFront, Route53, ACM, SQS, SNS, IAM, CloudWatch, SecretsManager |
+| **DigitalOcean** | Droplet, Domain (full DNS), Firewall, Certificate, LoadBalancer, Database, App Platform, VPC, Spaces |
+| **GCP** | Compute VM, Cloud Run, Cloud SQL, Secret Manager, Pub/Sub, Cloud DNS, IAM |
+| **Firebase** | Hosting, Functions, Firestore, Storage, Auth, RemoteConfig, App Check |
+| **Proxmox** | VM (clone, cloud-init, provision, cluster-aware scheduling), Templates (golden images) |
 
 ---
 
@@ -57,11 +88,13 @@ Running the same stack twice is always safe - existing resources are detected an
 ### DigitalOcean
 
 ```typescript
+import "dotenv/config";
 import { Stack, Deploy } from "puls-dev";
 import { DO, SIZE, REGION } from "puls-dev/do";
 
 @Deploy({ token: process.env.DO_TOKEN! })
 class Production extends Stack {
+  db  = DO.Database("prod-db").engine("pg").size("db-s-2vcpu-2gb").nodes(2);
   web = DO.Droplet("prod-web").size(SIZE.MEDIUM).region(REGION.FRA).allowPublicWeb();
   dns = DO.Domain("example.com").pointer("@", this.web).withSSL();
 }
@@ -70,47 +103,132 @@ class Production extends Stack {
 ### AWS
 
 ```typescript
+import "dotenv/config";
 import { Stack, Deploy } from "puls-dev";
-import { AWS, DISTRO, BUCKET, DOMAIN_REGISTER, REGION } from "puls-dev/aws";
+import { AWS, REGION, RUNTIME, DB } from "puls-dev/aws";
 
-@Deploy({ region: REGION.US_EAST_1 })
-class CDNStack extends Stack {
-  domain = AWS.Route53().randomDomain().register(DOMAIN_REGISTER).withWildcardSSL();
+@Deploy({ region: REGION.EU_CENTRAL_1 })
+class AppStack extends Stack {
+  db  = AWS.RDS("app-db").engine(DB.POSTGRES_16).size("db.t3.micro");
+  api = AWS.Lambda("app-api").code("./functions/api").runtime(RUNTIME.NODEJS_20);
+  cdn = AWS.S3("app-assets").staticSite().allowFrom(this.api);
+}
+```
+
+### GCP
 
-  cdn = AWS.CloudFront(`CDN-${this.domain.zoneName.slice(0, 8)}`)
-    .copyFrom(DISTRO.CDN)
-    .forDomain(this.domain, ["ec", "nc"]);
+```typescript
+import "dotenv/config";
+import { Stack, Deploy } from "puls-dev";
+import { GCP } from "puls-dev/gcp";
 
-  bucket = AWS.S3(BUCKET.NLC_GAMES_UREG)
-    .allowFrom(this.cdn)
-    .region(REGION.EU_WEST_1);
+@Deploy({})
+class CloudStack extends Stack {
+  secret = GCP.Secret("db-password").value(process.env.DB_PASS!);
+  api    = GCP.CloudRun("app-api").image("gcr.io/my-project/api:latest").port(8080).public();
+  db     = GCP.CloudSQL("app-db").engine("postgres").version("16").tier("db-f1-micro");
 }
 ```
 
 ### Proxmox
 
 ```typescript
+import "dotenv/config";
 import { Stack, Deploy, Protected } from "puls-dev";
 import { Proxmox, CONFIG, OS, KEYS } from "puls-dev/proxmox";
 
 @Deploy({ proxmox: CONFIG.STAGING })
 class StagingInfra extends Stack {
   @Protected
-  db = Proxmox.VM("ix-sto1-db01")
-    .image(OS.UBUNTU_24_04)
-    .cores(2).memory(4096)
-    .ip("1.1.1.1").vlan(2010)
-    .sshKey(KEYS);
+  db = Proxmox.VM("ix-db01").image(OS.UBUNTU_24_04).cores(2).memory(4096)
+        .ip("10.8.10.50").vlan(2010).sshKey(KEYS);
 
-  app = Proxmox.VM("ix-sto1-app01")
-    .image(OS.UBUNTU_24_04)
-    .cores(4).memory(8192)
-    .ip("1.1.1.1").vlan(2010)
-    .sshKey(KEYS)
-    .provision("config/default.yaml");
+  app = Proxmox.VM("ix-app01").image(OS.UBUNTU_24_04).cores(4).memory(8192)
+         .ip("10.8.10.51").vlan(2010).sshKey(KEYS)
+         .provision("config/default.yaml");
+}
+```
+
+---
+
+## Key features
+
+### Drift detection
+
+`Stack.diff()` compares every declared resource against its live cloud state — no API writes, structured output:
+
+```bash
+puls diff infra/production.ts
+```
+
+```
+🔍 Diff: Production
+
+   db   prod-db   ⚠️  drift
+        └─ size      db-s-1vcpu-1gb  →  db-s-2vcpu-2gb
+        └─ nodes     1  →  2
+   web  prod-web  ✅ in-sync
+   dns  example.com  ✅ in-sync
+
+   ⚠️  1 drifted out of 3 resources.
+```
+
+### Resource adoption
+
+Bring existing cloud infrastructure under Puls management without recreating it:
+
+```typescript
+db = DO.Database("prod-db")
+  .adoptId("existing-cluster-uuid")
+  .adoptOutput("host", "db.internal.example.com")
+  .adoptOutput("uri", "postgres://...");
+```
+
+### GitHub Actions integration
+
+Post plan output as a PR comment automatically. Add to your repo:
+
+```yaml
+# .github/workflows/puls-plan.yml
+- uses: puls-dev/puls-dev@v1
+  with:
+    command: plan
+    stack-file: infra/production.ts
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    DO_TOKEN: ${{ secrets.DO_TOKEN }}
+```
+
+Every PR that touches infra files gets a comment showing exactly what would change. See [docs/github-actions.md](docs/github-actions.md) for deploy and drift-check workflows.
+
+### Stack outputs & cross-stack wiring
+
+```typescript
+@Deploy({ proxmox: CONFIG.STAGING, token: process.env.DO_TOKEN })
+class Infra extends Stack {
+  vm  = Proxmox.VM("ix-app01").cores(4).memory(8192).ip("10.8.10.51").vlan(2010);
+  dns = DO.Domain("example.com").pointer("app", this.vm.out.ip); // Output<string>
 }
 ```
 
+Outputs resolve lazily — downstream resources unblock the moment their dependency finishes deploying.
+
+### Dry run / plan
+
+```typescript
+@Deploy({ dryRun: true, proxmox: CONFIG.STAGING })
+class MyStack extends Stack { ... }
+```
+
+Or via the CLI: `puls plan infra/stack.ts` — no config change required.
+
+### Protected resources
+
+```typescript
+@Protected
+db = Proxmox.VM("ix-db01")...;  // Puls will refuse to modify or destroy this
+```
+
 ---
 
 ## Decorators
@@ -120,29 +238,19 @@ class StagingInfra extends Stack {
 | `@Deploy({ ... })` | Deploy all resources in the stack |
 | `@Deploy({ dryRun: true })` | Print plan without making changes |
 | `@Destroy` | Tear down all resources in the stack |
-| `@Destroy({ proxmox: CONFIG.STAGING })` | Tear down with provider credentials |
 | `@DryRun` | Shorthand for `@Deploy({ dryRun: true })` |
-| `@Protected` (property) | Block changes/destruction of that resource |
-
-See [docs/decorators.md](docs/decorators.md) for full reference.
+| `@Protected` | Block changes/destruction of that resource |
+| `@Check` | Inventory query — lists all live resources across providers |
 
 ---
 
-## Running
+## .env
 
 ```bash
-npm install puls-dev
-npx tsx your-stack.ts
-```
-
-Requires Node 20+.
-
-**.env**
-```
 # DigitalOcean
 DO_TOKEN=
 
-# AWS (standard SDK env vars)
+# AWS
 AWS_ACCESS_KEY_ID=
 AWS_SECRET_ACCESS_KEY=
 AWS_REGION=us-east-1
@@ -151,8 +259,11 @@ AWS_REGION=us-east-1
 PROXMOX_URL=https://pve.example.com:8006
 PROXMOX_USER=root@pam
 PROXMOX_TOKEN_NAME=puls
-PROXMOX_TOKEN_SECRET=some-super-secret
+PROXMOX_TOKEN_SECRET=
 PROXMOX_NODES=pve1,pve2
-PROXMOX_DNS_DOMAIN=nolimit.int
-PROXMOX_DNS_SERVERS=1.1.1.1,2.2.2.2
+
+# GCP / Firebase
+GCP_SA=./service-account.json
 ```
+
+Requires Node 20+.

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();