puls-dev 0.3.6 → 0.3.7

package/README.md

@@ -1,12 +1,12 @@
 # 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/) | [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 under active development. APIs and features are evolving — we welcome 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 })
@@ -20,7 +20,7 @@ class GameInfra extends Stack {
 }
 ```
 
-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.
 
 ---
 
@@ -34,7 +34,7 @@ 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 or updated in place.
+Running the same stack twice is always safe- existing resources are detected and skipped or updated in place.
 
 ---
 
@@ -44,7 +44,7 @@ Running the same stack twice is always safe — existing resources are detected
 npm install puls-dev
 ```
 
-**One-time shell setup** — so you never have to type `npx puls` again:
+**One-time shell setup**- so you never have to type `npx puls` again:
 
 ```bash
 npx puls install-shell
@@ -57,7 +57,7 @@ This adds a `puls` launcher to `~/.puls/bin` and wires it into your shell config
 ## CLI
 
 ```bash
-puls plan    infra/stack.ts          # dry-run — prints what would change, no API writes
+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
@@ -67,7 +67,7 @@ puls install-shell                   # one-time shell setup
 puls uninstall-shell                 # remove shell integration
 ```
 
-Always run `plan` before `deploy` — it activates dry-run mode automatically.
+Always run `plan` before `deploy`- it activates dry-run mode automatically.
 
 ---
 
@@ -155,7 +155,7 @@ class StagingInfra extends Stack {
 
 ### Drift detection
 
-`Stack.diff()` compares every declared resource against its live cloud state — no API writes, structured output:
+`Stack.diff()` compares every declared resource against its live cloud state- no API writes, structured output:
 
 ```bash
 puls diff infra/production.ts
@@ -211,7 +211,7 @@ class Infra extends Stack {
 }
 ```
 
-Outputs resolve lazily — downstream resources unblock the moment their dependency finishes deploying.
+Outputs resolve lazily- downstream resources unblock the moment their dependency finishes deploying.
 
 ### Dry run / plan
 
@@ -220,7 +220,7 @@ Outputs resolve lazily — downstream resources unblock the moment their depende
 class MyStack extends Stack { ... }
 ```
 
-Or via the CLI: `puls plan infra/stack.ts` — no config change required.
+Or via the CLI: `puls plan infra/stack.ts`- no config change required.
 
 ### Protected resources
 
@@ -240,7 +240,7 @@ db = Proxmox.VM("ix-db01")...;  // Puls will refuse to modify or destroy this
 | `@Destroy` | Tear down all resources in the stack |
 | `@DryRun` | Shorthand for `@Deploy({ dryRun: true })` |
 | `@Protected` | Block changes/destruction of that resource |
-| `@Check` | Inventory query — lists all live resources across providers |
+| `@Check` | Inventory query- lists all live resources across providers |
 
 ---
 

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 {};

package/dist/providers/aws/acm.test.js

@@ -0,0 +1,167 @@
+import { test, describe, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert';
+import { ACMClient } from '@aws-sdk/client-acm';
+import { Route53Client } from '@aws-sdk/client-route-53';
+import { ACMCertificateBuilder } from './acm.js';
+import { Config } from '../../core/config.js';
+describe('ACMCertificateBuilder Unit Tests', () => {
+    let originalAcmSend;
+    let originalR53Send;
+    let acmCalls = [];
+    let r53Calls = [];
+    let mockAcmResponses = {};
+    let mockR53Responses = {};
+    function stubSend(calls, responses) {
+        return async function (command) {
+            const commandName = command.constructor.name;
+            calls.push({ commandName, input: command.input });
+            const handler = responses[commandName];
+            if (handler) {
+                if (typeof handler === 'function')
+                    return handler(command.input);
+                if (handler instanceof Error)
+                    throw handler;
+                return handler;
+            }
+            return {};
+        };
+    }
+    beforeEach(() => {
+        Config.set({ dryRun: false, providers: { aws: { region: 'us-east-1' } } });
+        acmCalls = [];
+        r53Calls = [];
+        mockAcmResponses = {};
+        mockR53Responses = {};
+        originalAcmSend = ACMClient.prototype.send;
+        originalR53Send = Route53Client.prototype.send;
+        ACMClient.prototype.send = stubSend(acmCalls, mockAcmResponses);
+        Route53Client.prototype.send = stubSend(r53Calls, mockR53Responses);
+    });
+    afterEach(() => {
+        ACMClient.prototype.send = originalAcmSend;
+        Route53Client.prototype.send = originalR53Send;
+        mock.restoreAll();
+    });
+    test('returns null when no matching certificate is found', async () => {
+        mockAcmResponses['ListCertificatesCommand'] = { CertificateSummaryList: [] };
+        const builder = new ACMCertificateBuilder('example.com');
+        const result = await builder.discoveryPromise;
+        assert.strictEqual(result, null);
+        assert.strictEqual(acmCalls[0].commandName, 'ListCertificatesCommand');
+    });
+    test('discovers existing wildcard certificate by domain name', async () => {
+        mockAcmResponses['ListCertificatesCommand'] = {
+            CertificateSummaryList: [
+                {
+                    DomainName: '*.example.com',
+                    CertificateArn: 'arn:aws:acm:us-east-1:123:certificate/abc',
+                },
+            ],
+        };
+        const builder = new ACMCertificateBuilder('example.com', true);
+        const result = await builder.discoveryPromise;
+        assert.ok(result);
+        assert.strictEqual(builder.resolvedArn, 'arn:aws:acm:us-east-1:123:certificate/abc');
+    });
+    test('returns existing cert without requesting a new one', async () => {
+        mockAcmResponses['ListCertificatesCommand'] = {
+            CertificateSummaryList: [
+                {
+                    DomainName: '*.example.com',
+                    CertificateArn: 'arn:aws:acm:us-east-1:123:certificate/abc',
+                    Status: 'ISSUED',
+                },
+            ],
+        };
+        const builder = new ACMCertificateBuilder('example.com');
+        const result = await builder.deploy();
+        assert.strictEqual(result.arn, 'arn:aws:acm:us-east-1:123:certificate/abc');
+        assert.ok(!acmCalls.some((c) => c.commandName === 'RequestCertificateCommand'));
+    });
+    test('performs dry-run without requesting a certificate', async () => {
+        Config.set({ dryRun: true, providers: { aws: { region: 'us-east-1' } } });
+        mockAcmResponses['ListCertificatesCommand'] = { CertificateSummaryList: [] };
+        const builder = new ACMCertificateBuilder('example.com');
+        const result = await builder.deploy();
+        assert.ok(result.arn.includes('DRYRUN'));
+        assert.ok(!acmCalls.some((c) => c.commandName === 'RequestCertificateCommand'));
+    });
+    test('requests wildcard cert and writes DNS validation records to Route53', async () => {
+        mockAcmResponses['ListCertificatesCommand'] = { CertificateSummaryList: [] };
+        mockAcmResponses['RequestCertificateCommand'] = {
+            CertificateArn: 'arn:aws:acm:us-east-1:123:certificate/new-cert',
+        };
+        let describeCallCount = 0;
+        mockAcmResponses['DescribeCertificateCommand'] = () => {
+            describeCallCount++;
+            if (describeCallCount === 1) {
+                // First call: validation records ready
+                return {
+                    Certificate: {
+                        Status: 'PENDING_VALIDATION',
+                        DomainValidationOptions: [
+                            {
+                                ResourceRecord: {
+                                    Name: '_abc.example.com',
+                                    Value: '_xyz.acm-validations.aws.',
+                                },
+                            },
+                        ],
+                    },
+                };
+            }
+            // Second call: ISSUED
+            return { Certificate: { Status: 'ISSUED' } };
+        };
+        mockR53Responses['ChangeResourceRecordSetsCommand'] = {};
+        // Fast-forward poll timers
+        mock.method(global, 'setTimeout', (fn) => fn());
+        const builder = new ACMCertificateBuilder('example.com', true);
+        builder.forZone({ zoneId: 'Z123456', zoneName: 'example.com' });
+        const result = await builder.deploy();
+        assert.strictEqual(result.arn, 'arn:aws:acm:us-east-1:123:certificate/new-cert');
+        const requestCall = acmCalls.find((c) => c.commandName === 'RequestCertificateCommand');
+        assert.ok(requestCall);
+        assert.strictEqual(requestCall.input.DomainName, '*.example.com');
+        assert.strictEqual(requestCall.input.ValidationMethod, 'DNS');
+        const r53Call = r53Calls.find((c) => c.commandName === 'ChangeResourceRecordSetsCommand');
+        assert.ok(r53Call);
+        assert.strictEqual(r53Call.input.HostedZoneId, 'Z123456');
+        const changes = r53Call.input.ChangeBatch.Changes;
+        assert.strictEqual(changes.length, 1);
+        assert.strictEqual(changes[0].Action, 'UPSERT');
+        assert.ok(changes[0].ResourceRecordSet.Name.includes('_abc'));
+    });
+    test('deduplicates validation CNAME records before writing to Route53', async () => {
+        mockAcmResponses['ListCertificatesCommand'] = { CertificateSummaryList: [] };
+        mockAcmResponses['RequestCertificateCommand'] = {
+            CertificateArn: 'arn:aws:acm:us-east-1:123:certificate/new-cert',
+        };
+        let describeCount = 0;
+        mockAcmResponses['DescribeCertificateCommand'] = () => {
+            describeCount++;
+            if (describeCount === 1) {
+                return {
+                    Certificate: {
+                        Status: 'PENDING_VALIDATION',
+                        // wildcard + apex SANs produce the same CNAME - duplicated
+                        DomainValidationOptions: [
+                            { ResourceRecord: { Name: '_dup.example.com', Value: '_val.aws.' } },
+                            { ResourceRecord: { Name: '_dup.example.com', Value: '_val.aws.' } },
+                        ],
+                    },
+                };
+            }
+            return { Certificate: { Status: 'ISSUED' } };
+        };
+        mockR53Responses['ChangeResourceRecordSetsCommand'] = {};
+        mock.method(global, 'setTimeout', (fn) => fn());
+        const builder = new ACMCertificateBuilder('example.com', true);
+        builder.forZone({ zoneId: 'Z123456', zoneName: 'example.com' });
+        await builder.deploy();
+        const r53Call = r53Calls.find((c) => c.commandName === 'ChangeResourceRecordSetsCommand');
+        assert.ok(r53Call);
+        // Should be deduplicated to 1 record
+        assert.strictEqual(r53Call.input.ChangeBatch.Changes.length, 1);
+    });
+});

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

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