puls-dev 0.3.5 → 0.3.7

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.js

@@ -95,11 +95,11 @@ export function uninstallShell() {
             fs.rmdirSync(path.join(home, ".puls"));
         }
         catch {
-            // Non-empty dirs left behind (user may have other files) — that's fine
+            // Non-empty dirs left behind (user may have other files)- that's fine
         }
     }
     else {
-        console.log(`   Launcher not found at ${launcherPath} — nothing to remove.`);
+        console.log(`   Launcher not found at ${launcherPath}- nothing to remove.`);
     }
     // 2. Remove PATH line from shell config
     const detected = detectShellConfig();
@@ -109,12 +109,12 @@ export function uninstallShell() {
     }
     const { configFile } = detected;
     if (!fs.existsSync(configFile)) {
-        console.log(`   Shell config not found at ${configFile} — nothing to clean up.`);
+        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.`);
+        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
@@ -127,8 +127,7 @@ export function uninstallShell() {
             return { out: acc.out, skip: false }; // skip the PATH line
         return { out: [...acc.out, line], skip: false };
     }, { out: [], skip: false })
-        .out
-        .join("\n")
+        .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}`);

package/dist/bin/puls.js

@@ -48,7 +48,7 @@ Options:
   --help           Print this help and exit
 
 Examples:
-  npx puls install-shell         # one-time setup — then just use "puls" directly
+  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
@@ -84,12 +84,19 @@ if (values.help || positionals.length === 0) {
     process.exit(0);
 }
 const [command, userFile] = positionals;
-const COMMANDS = ["plan", "deploy", "destroy", "diff", "install-shell", "uninstall-shell"];
+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
+// Shell management commands run directly- no stack file needed
 if (command === "install-shell") {
     installShell();
     process.exit(0);

package/dist/core/config.d.ts

@@ -36,6 +36,10 @@ export interface GlobalConfig {
             region?: string;
             sshUser?: string;
         };
+        cloudflare?: {
+            token: string;
+            accountId?: string;
+        };
     };
 }
 declare class ConfigManager {

package/dist/core/decorators.d.ts

@@ -19,6 +19,10 @@ type ProviderOpts = {
         verifySsl?: boolean;
         sshUser?: string;
     };
+    cloudflare?: {
+        token: string;
+        accountId?: string;
+    };
 };
 export declare function Protected(target: any, propertyKey: string): void;
 export declare function ForceConfigCheck(target: any, propertyKey: string): void;

package/dist/core/decorators.js

@@ -15,6 +15,8 @@ function applyConfig(opts) {
         Config.set({ providers: { aws: { region: opts.region } } });
     if (opts.proxmox)
         Config.set({ providers: { proxmox: opts.proxmox } });
+    if (opts.cloudflare)
+        Config.set({ providers: { cloudflare: opts.cloudflare } });
     if (opts.firebase) {
         const sa = JSON.parse(readFileSync(opts.firebase, "utf8"));
         Config.set({

package/dist/core/parallel.test.js

@@ -201,15 +201,16 @@ describe("Parallel Resource Deployment Unit Tests", () => {
         assert.strictEqual(logs.includes("start:r2"), false);
     });
     test("decorator option propagation sets configuration values", async () => {
-        // Clear parallel flag
         Config.set({ parallel: false });
-        // We define a decorated simple stack
         let SimpleDecoStack = class SimpleDecoStack extends Stack {
         };
         SimpleDecoStack = __decorate([
             Deploy({ parallel: true })
         ], SimpleDecoStack);
-        // Verify decorator correctly updated global configuration to true
         assert.strictEqual(Config.isParallelActive(), true);
+        // @Deploy fires an async stack.deploy() that escapes this test's scope.
+        // Waiting here lets it complete before the test runner serializes results,
+        // preventing IPC stream corruption on the way back to the parent process.
+        await new Promise(resolve => setTimeout(resolve, 50));
     });
 });

package/dist/core/resource.d.ts

@@ -29,7 +29,7 @@ export declare abstract class BaseBuilder {
      * 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
+     * resolved automatically- chain `.adoptOutput(key, value)` for each one you
      * need for cross-stack wiring.
      */
     adoptId(id: string): this;
@@ -51,6 +51,7 @@ export declare abstract class BaseBuilder {
      * (no field-level diff available).
      */
     getDiff(_existing: any): FieldDiff[];
+    forceConfigCheck?(): void;
     adoptOutput(key: string, value: any): this;
     dryRun(enabled?: boolean): this;
     beforeDeploy(callback: () => Promise<void> | void): this;

package/dist/core/resource.js

@@ -39,7 +39,7 @@ export class BaseBuilder {
      * 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
+     * resolved automatically- chain `.adoptOutput(key, value)` for each one you
      * need for cross-stack wiring.
      */
     adoptId(id) {
@@ -178,7 +178,9 @@ export class BaseBuilder {
     }
     async destroy() {
         const dryRun = this.isDryRunActive();
-        const adoptedSuffix = this._adoptedId ? ` [adopted id=${this._adoptedId}]` : "";
+        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();

package/dist/core/stack.d.ts

@@ -17,6 +17,10 @@ export declare abstract class Stack {
      * }
      */
     static from<T extends Stack>(cls: new (...args: any[]) => T, region?: string): T;
+    beforeDeploy?(): Promise<void> | void;
+    afterDeploy?(outputs: Record<string, any>): Promise<void> | void;
+    beforeDestroy?(): Promise<void> | void;
+    afterDestroy?(outputs: Record<string, any>): Promise<void> | void;
     /**
      * Compares every declared resource against its live cloud state without
      * making any API writes. Returns a structured `StackDiff` and prints a

package/dist/core/stack.js

@@ -237,7 +237,7 @@ export class Stack {
             return withRedactedConsole(secrets, async () => {
                 console.log(`\n🏗️  Deploying Stack: ${this.constructor.name}`);
                 // Stack-level beforeDeploy hook
-                if (typeof this.beforeDeploy === "function") {
+                if (this.beforeDeploy) {
                     console.log(`   ⚡ Running Stack-level beforeDeploy hook...`);
                     await this.beforeDeploy();
                 }
@@ -255,8 +255,8 @@ export class Stack {
                         if (isProtected)
                             val.protect();
                         const forceConfigCheck = Reflect.getMetadata("forceConfigCheck", this, prop);
-                        if (forceConfigCheck && typeof val.forceConfigCheck === "function") {
-                            val.forceConfigCheck();
+                        if (forceConfigCheck) {
+                            val.forceConfigCheck?.();
                         }
                     }
                     else if (Array.isArray(val)) {
@@ -267,8 +267,8 @@ export class Stack {
                                 resources.push({ prop, resource: item });
                                 if (isProtected)
                                     item.protect();
-                                if (forceConfigCheck && typeof item.forceConfigCheck === "function") {
-                                    item.forceConfigCheck();
+                                if (forceConfigCheck) {
+                                    item.forceConfigCheck?.();
                                 }
                             }
                         }
@@ -373,7 +373,7 @@ export class Stack {
                 }
                 printOutputs(this.constructor.name, outputs);
                 // Stack-level afterDeploy hook
-                if (typeof this.afterDeploy === "function") {
+                if (this.afterDeploy) {
                     console.log(`   ⚡ Running Stack-level afterDeploy hook...`);
                     await this.afterDeploy(outputs);
                 }
@@ -395,7 +395,7 @@ export class Stack {
             return withRedactedConsole(secrets, async () => {
                 console.log(`\n💥 Tearing down Stack: ${this.constructor.name}`);
                 // Stack-level beforeDestroy hook
-                if (typeof this.beforeDestroy === "function") {
+                if (this.beforeDestroy) {
                     console.log(`   ⚡ Running Stack-level beforeDestroy hook...`);
                     await this.beforeDestroy();
                 }
@@ -507,7 +507,7 @@ export class Stack {
                 }
                 printOutputs(this.constructor.name, outputs);
                 // Stack-level afterDestroy hook
-                if (typeof this.afterDestroy === "function") {
+                if (this.afterDestroy) {
                     console.log(`   ⚡ Running Stack-level afterDestroy hook...`);
                     await this.afterDestroy(outputs);
                 }

package/dist/providers/aws/acm.test.d.ts

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