puls-dev 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License (ISC)
+
+Copyright (c) 2026, Pulsdev.io
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# Puls-dev
+
+Intent-driven infrastructure-as-code. Describe what you want — Puls figures out create, update, or skip.
+
+```typescript
+@Deploy({ proxmox: CONFIG.STAGING })
+class GameInfra extends Stack {
+  server = Proxmox.VM("example-vm")
+    .image(OS.UBUNTU_24_04)
+    .cores(4).memory(8192)
+    .ip("1.1.1.1").vlan(2010)
+    .sshKey(KEYS)
+    .provision("config/default.yaml");
+}
+```
+
+No state files. No plan step. Runs against real APIs — idempotent by default.
+
+---
+
+## How it works
+
+Puls uses **eager discovery**: the moment you declare a resource, it checks the real API in the background. By the time `deploy()` runs, it already knows the current state.
+
+```
+Declare resource  →  Discovery fires immediately (async)
+                  →  You chain config (.cores(), .ip(), ...)
+                  →  deploy() awaits discovery, diffs, acts
+```
+
+Running the same stack twice is always safe — existing resources are detected and skipped.
+
+---
+
+## Providers
+
+| Provider | Resources |
+|----------|-----------|
+| [DigitalOcean](docs/providers/digitalocean.md) | Droplet, Domain, Firewall, Certificate, LoadBalancer |
+| [AWS](docs/providers/aws.md) | Route53, ACM (wildcard SSL), CloudFront, S3 |
+| [Proxmox](docs/providers/proxmox.md) | VM (clone, cloud-init, provision, replace) |
+
+---
+
+## Quick examples
+
+### DigitalOcean
+
+```typescript
+import { DO, DO_TYPES, Stack, Deploy } from "puls";
+const { SIZE, REGION } = DO_TYPES;
+
+@Deploy({ token: process.env.DO_TOKEN! })
+class Production extends Stack {
+  web = DO.Droplet("prod-web").size(SIZE.MEDIUM).region(REGION.FRA).allowPublicWeb();
+  dns = DO.Domain("example.com").pointer("@", this.web).withSSL();
+}
+```
+
+### AWS
+
+```typescript
+import { AWS, AWS_TYPES, Stack, Deploy } from "puls";
+const { DISTRO, BUCKET, DOMAIN_REGISTER, REGION } = AWS_TYPES;
+
+@Deploy({ region: REGION.US_EAST_1 })
+class CDNStack extends Stack {
+  domain = AWS.Route53().randomDomain().register(DOMAIN_REGISTER).withWildcardSSL();
+
+  cdn = AWS.CloudFront(`CDN-${this.domain.zoneName.slice(0, 8)}`)
+    .copyFrom(DISTRO.TURKEY_CDN)
+    .forDomain(this.domain, ["ec", "nc"]);
+
+  bucket = AWS.S3(BUCKET.NLC_GAMES_UREG)
+    .allowFrom(this.cdn)
+    .region(REGION.EU_WEST_1);
+}
+```
+
+### Proxmox
+
+```typescript
+import { Proxmox, PROXMOX_TYPES, Stack, Deploy, Protected } from "puls";
+const { CONFIG, OS, KEYS } = PROXMOX_TYPES;
+
+@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);
+
+  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");
+}
+```
+
+---
+
+## Decorators
+
+| Decorator | Effect |
+|-----------|--------|
+| `@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.
+
+---
+
+## Running
+
+```bash
+npm install
+npx tsx your-stack.ts
+```
+
+Requires Node 20+.
+
+**.env**
+```
+# DigitalOcean
+DO_TOKEN=
+
+# AWS (standard SDK env vars)
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=us-east-1
+
+# Proxmox
+PROXMOX_URL=https://pve.example.com:8006
+PROXMOX_USER=root@pam
+PROXMOX_TOKEN_NAME=puls
+PROXMOX_TOKEN_SECRET=some-super-secret
+PROXMOX_NODES=pve1,pve2
+PROXMOX_DNS_DOMAIN=nolimit.int
+PROXMOX_DNS_SERVERS=1.1.1.1,2.2.2.2
+```

package/dist/core/checker.d.ts

@@ -0,0 +1,5 @@
+import "reflect-metadata";
+import type { InventoryResult } from '../types/inventory.ts';
+export declare abstract class Checker {
+    check(): Promise<InventoryResult>;
+}

package/dist/core/checker.js

@@ -0,0 +1,148 @@
+import "reflect-metadata";
+import { Config } from './config.js';
+import { listProxmoxVMs } from '../providers/proxmox/list.js';
+import { listDoResources } from '../providers/do/list.js';
+import { listAwsResources } from '../providers/aws/list.js';
+function clip(text, width) {
+    return text.length > width ? text.slice(0, width - 1) + '…' : text.padEnd(width);
+}
+function printSection(title, rows, cols) {
+    const colsWidth = cols.reduce((s, c) => s + c.width, 0) + (cols.length - 1) * 2;
+    const innerWidth = Math.max(colsWidth + 4, title.length + 4);
+    const bar = (l, r) => `  ${l}${'─'.repeat(innerWidth)}${r}`;
+    const row = (content) => `  │  ${content.padEnd(innerWidth - 4)}  │`;
+    console.log('');
+    console.log(bar('┌', '┐'));
+    console.log(row(title));
+    console.log(bar('├', '┤'));
+    if (rows.length === 0) {
+        console.log(row('(none)'));
+    }
+    else {
+        const headerLine = cols.map((c) => clip(c.header.toUpperCase(), c.width)).join('  ');
+        console.log(row(headerLine));
+        console.log(bar('├', '┤'));
+        for (const r of rows) {
+            console.log(row(cols.map((c) => clip(c.render(r), c.width)).join('  ')));
+        }
+    }
+    console.log(bar('└', '┘'));
+}
+// ─── Per-provider renderers ───────────────────────────────────────────────────
+function renderProxmox(inv) {
+    const running = inv.vms.filter((v) => v.status === 'running').length;
+    printSection(`Proxmox  ·  ${inv.vms.length} VM${inv.vms.length !== 1 ? 's' : ''}  (${running} running)`, inv.vms, [
+        { header: 'Name', width: 26, render: (v) => v.name },
+        { header: 'VMID', width: 6, render: (v) => String(v.vmid) },
+        { header: 'Node', width: 12, render: (v) => v.node },
+        { header: 'Status', width: 8, render: (v) => v.status },
+        { header: 'Mem', width: 6, render: (v) => `${Math.round(v.maxmem / 1024 ** 3)}GB` },
+        { header: 'Disk', width: 6, render: (v) => `${Math.round(v.maxdisk / 1024 ** 3)}GB` },
+    ]);
+}
+function renderDo(inv) {
+    const costStr = inv.totalMonthlyCost > 0 ? `  ·  $${inv.totalMonthlyCost}/mo` : '';
+    printSection(`DigitalOcean Droplets  ·  ${inv.droplets.length}${costStr}`, inv.droplets, [
+        { header: 'Name', width: 24, render: (d) => d.name },
+        { header: 'Region', width: 6, render: (d) => d.region },
+        { header: 'Size', width: 18, render: (d) => d.size },
+        { header: 'Status', width: 8, render: (d) => d.status },
+        { header: 'IP', width: 15, render: (d) => d.ip ?? '—' },
+        { header: '$/mo', width: 5, render: (d) => d.monthlyCost > 0 ? `$${d.monthlyCost}` : '?' },
+    ]);
+    if (inv.firewalls.length > 0) {
+        printSection(`DigitalOcean Firewalls  ·  ${inv.firewalls.length}`, inv.firewalls, [
+            { header: 'Name', width: 32, render: (f) => f.name },
+            { header: 'Droplets', width: 8, render: (f) => String(f.dropletCount) },
+        ]);
+    }
+    if (inv.loadBalancers.length > 0) {
+        printSection(`DigitalOcean Load Balancers  ·  ${inv.loadBalancers.length}`, inv.loadBalancers, [
+            { header: 'Name', width: 24, render: (lb) => lb.name },
+            { header: 'Region', width: 6, render: (lb) => lb.region },
+            { header: 'IP', width: 15, render: (lb) => lb.ip },
+            { header: 'Status', width: 8, render: (lb) => lb.status },
+        ]);
+    }
+    if (inv.domains.length > 0) {
+        printSection(`DigitalOcean Domains  ·  ${inv.domains.length}`, inv.domains, [
+            { header: 'Domain', width: 42, render: (d) => d.name },
+            { header: 'TTL', width: 6, render: (d) => String(d.ttl) },
+        ]);
+    }
+}
+function renderAws(inv) {
+    if (inv.distributions.length > 0) {
+        printSection(`AWS CloudFront  ·  ${inv.distributions.length}  ·  ${inv.region}`, inv.distributions, [
+            { header: 'ID', width: 14, render: (d) => d.id },
+            { header: 'Domain', width: 34, render: (d) => d.aliases[0] ?? d.domain },
+            { header: 'Status', width: 10, render: (d) => d.status },
+        ]);
+    }
+    if (inv.buckets.length > 0) {
+        printSection(`AWS S3  ·  ${inv.buckets.length} buckets`, inv.buckets, [
+            { header: 'Bucket', width: 52, render: (b) => b.name },
+        ]);
+    }
+    if (inv.lambdas.length > 0) {
+        printSection(`AWS Lambda  ·  ${inv.lambdas.length} functions`, inv.lambdas, [
+            { header: 'Function', width: 32, render: (f) => f.name },
+            { header: 'Runtime', width: 12, render: (f) => f.runtime },
+            { header: 'Memory', width: 8, render: (f) => `${f.memorySizeMb}MB` },
+        ]);
+    }
+    if (inv.rdsInstances.length > 0) {
+        printSection(`AWS RDS  ·  ${inv.rdsInstances.length} instances`, inv.rdsInstances, [
+            { header: 'Identifier', width: 26, render: (i) => i.identifier },
+            { header: 'Engine', width: 18, render: (i) => i.engine },
+            { header: 'Class', width: 14, render: (i) => i.instanceClass },
+            { header: 'Status', width: 10, render: (i) => i.status },
+        ]);
+    }
+    if (inv.hostedZones.length > 0) {
+        printSection(`AWS Route53  ·  ${inv.hostedZones.length} zones`, inv.hostedZones, [
+            { header: 'Zone', width: 38, render: (z) => z.name },
+            { header: 'Records', width: 7, render: (z) => String(z.recordCount) },
+        ]);
+    }
+}
+// ─── Checker ──────────────────────────────────────────────────────────────────
+export class Checker {
+    async check() {
+        const cfg = Config.get();
+        const errors = [];
+        const result = { errors };
+        const tasks = [];
+        console.log(`\n🔍 Checking infrastructure...`);
+        if (cfg.providers.proxmox?.url && cfg.providers.proxmox?.tokenSecret) {
+            tasks.push(listProxmoxVMs()
+                .then((inv) => { result.proxmox = inv; })
+                .catch((err) => { errors.push({ provider: 'proxmox', message: err.message }); }));
+        }
+        if (cfg.providers.do?.token) {
+            tasks.push(listDoResources()
+                .then((inv) => { result.do = inv; })
+                .catch((err) => { errors.push({ provider: 'do', message: err.message }); }));
+        }
+        if (cfg.providers.aws?.region) {
+            tasks.push(listAwsResources()
+                .then((inv) => { result.aws = inv; })
+                .catch((err) => { errors.push({ provider: 'aws', message: err.message }); }));
+        }
+        await Promise.all(tasks);
+        if (result.proxmox)
+            renderProxmox(result.proxmox);
+        if (result.do)
+            renderDo(result.do);
+        if (result.aws)
+            renderAws(result.aws);
+        for (const e of errors) {
+            console.warn(`\n  [!] ${e.provider}: ${e.message}`);
+        }
+        const totalCost = result.do?.totalMonthlyCost ?? 0;
+        if (totalCost > 0) {
+            console.log(`\n  Total estimated monthly cost (DigitalOcean): $${totalCost}`);
+        }
+        return result;
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1,35 @@
+export interface GlobalConfig {
+    dryRun?: boolean;
+    providers: {
+        do?: {
+            token: string;
+            defaultRegion?: string;
+        };
+        aws?: {
+            region: string;
+        };
+        proxmox?: {
+            url: string;
+            user: string;
+            tokenName: string;
+            tokenSecret: string;
+            nodes?: string[];
+            storage?: string;
+            dnsDomain?: string;
+            dnsServers?: string[];
+            verifySsl?: boolean;
+        };
+        firebase?: {
+            projectId: string;
+            serviceAccountPath: string;
+        };
+    };
+}
+declare class ConfigManager {
+    private config;
+    set(newConfig: Partial<GlobalConfig>): void;
+    get(): GlobalConfig;
+    isGlobalDryRun(): boolean;
+}
+export declare const Config: ConfigManager;
+export {};

package/dist/core/config.js

@@ -0,0 +1,15 @@
+class ConfigManager {
+    config = {
+        providers: {},
+    };
+    set(newConfig) {
+        this.config = { ...this.config, ...newConfig };
+    }
+    get() {
+        return this.config;
+    }
+    isGlobalDryRun() {
+        return this.config.dryRun ?? false;
+    }
+}
+export const Config = new ConfigManager();

package/dist/core/decorators.d.ts

@@ -0,0 +1,26 @@
+import "reflect-metadata";
+type ProviderOpts = {
+    token?: string;
+    region?: string;
+    dryRun?: boolean;
+    firebase?: string;
+    proxmox?: {
+        url: string;
+        user: string;
+        tokenName: string;
+        tokenSecret: string;
+        nodes?: string[];
+        storage?: string;
+        dnsDomain?: string;
+        dnsServers?: string[];
+        verifySsl?: boolean;
+    };
+};
+export declare function Protected(target: any, propertyKey: string): void;
+export declare function Destroy(target: any, propertyKey: string): void;
+export declare function Destroy(target: Function): void;
+export declare function Destroy(opts: ProviderOpts): (constructor: any) => void;
+export declare function Deploy(opts?: ProviderOpts): (constructor: any) => void;
+export declare function Check(opts?: ProviderOpts): (constructor: any) => void;
+export declare function DryRun(opts?: ProviderOpts | any): ((constructor: any) => void) | undefined;
+export {};

package/dist/core/decorators.js

@@ -0,0 +1,86 @@
+import "reflect-metadata";
+import { readFileSync } from "node:fs";
+import { Config } from "./config.js";
+import { Stack } from "./stack.js";
+function applyConfig(opts) {
+    if (opts.dryRun !== undefined)
+        Config.set({ dryRun: opts.dryRun });
+    if (opts.token)
+        Config.set({
+            providers: { ...Config.get().providers, do: { token: opts.token } },
+        });
+    if (opts.region)
+        Config.set({
+            providers: { ...Config.get().providers, aws: { region: opts.region } },
+        });
+    if (opts.proxmox)
+        Config.set({
+            providers: { ...Config.get().providers, proxmox: opts.proxmox },
+        });
+    if (opts.firebase) {
+        const sa = JSON.parse(readFileSync(opts.firebase, "utf8"));
+        Config.set({
+            providers: { ...Config.get().providers, firebase: { projectId: sa.project_id, serviceAccountPath: opts.firebase } },
+        });
+    }
+}
+export function Protected(target, propertyKey) {
+    Reflect.defineMetadata("protected", true, target, propertyKey);
+}
+export function Destroy(optsOrTarget, propertyKey) {
+    if (propertyKey !== undefined) {
+        Reflect.defineMetadata("destroy", true, optsOrTarget, propertyKey);
+        return;
+    }
+    if (typeof optsOrTarget === "function") {
+        const instance = new optsOrTarget();
+        Stack._register(optsOrTarget, instance);
+        Promise.resolve().then(async () => {
+            if (typeof instance.destroy === "function")
+                await instance.destroy();
+        });
+        return;
+    }
+    return function (constructor) {
+        applyConfig(optsOrTarget);
+        const instance = new constructor();
+        Stack._register(constructor, instance);
+        Promise.resolve().then(async () => {
+            if (typeof instance.destroy === "function")
+                await instance.destroy();
+        });
+    };
+}
+// THE "MAGIC": Auto-executing Stack Decorator
+export function Deploy(opts = {}) {
+    return function (constructor) {
+        applyConfig(opts);
+        // Instantiate synchronously so resource discovery kicks off immediately and
+        // other stacks can call Stack.from(ThisClass) to reference its Output fields.
+        const instance = new constructor();
+        Stack._register(constructor, instance);
+        Promise.resolve().then(async () => {
+            if (typeof instance.deploy === "function")
+                await instance.deploy();
+        });
+    };
+}
+export function Check(opts = {}) {
+    return function (constructor) {
+        applyConfig(opts);
+        const instance = new constructor();
+        Promise.resolve().then(async () => {
+            if (typeof instance.check === "function")
+                await instance.check();
+        });
+    };
+}
+// Shortcut for Dry Run — accepts the same options as @Deploy
+export function DryRun(opts = {}) {
+    if (typeof opts === "function") {
+        Deploy({ dryRun: true })(opts);
+    }
+    else {
+        return Deploy({ ...opts, dryRun: true });
+    }
+}

package/dist/core/output.d.ts

@@ -0,0 +1,8 @@
+export declare class Output<T> {
+    private _promise;
+    private _resolve;
+    constructor();
+    resolve(value: T): void;
+    get(): Promise<T>;
+    apply<U>(fn: (val: T) => U): Output<U>;
+}

package/dist/core/output.js

@@ -0,0 +1,19 @@
+export class Output {
+    _promise;
+    _resolve;
+    constructor() {
+        this._promise = new Promise(resolve => (this._resolve = resolve));
+    }
+    resolve(value) {
+        this._resolve(value);
+    }
+    get() {
+        return this._promise;
+    }
+    // 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)));
+        return out;
+    }
+}

package/dist/core/resource.d.ts

@@ -0,0 +1,20 @@
+export declare abstract class BaseBuilder {
+    name: string;
+    protected isProtected: boolean;
+    protected localDryRun: boolean | null;
+    protected discoveryPromise: Promise<any>;
+    protected sidecars: BaseBuilder[];
+    constructor(name: string);
+    protect(): this;
+    dryRun(enabled?: boolean): this;
+    protected isDryRunActive(): boolean;
+    protected checkProtection(hasChanges: boolean): Promise<boolean>;
+    protected waitFor(label: string, condition: () => Promise<boolean>, opts?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<void>;
+    protected deploySidecars(): Promise<void>;
+    protected destroySidecars(): Promise<void>;
+    destroy(): Promise<any>;
+    abstract deploy(): Promise<any>;
+}

package/dist/core/resource.js

@@ -0,0 +1,77 @@
+import { Config } from "./config.js";
+export class BaseBuilder {
+    name;
+    isProtected = false;
+    localDryRun = null;
+    discoveryPromise;
+    sidecars = [];
+    constructor(name) {
+        this.name = name;
+    }
+    protect() {
+        this.isProtected = true;
+        return this;
+    }
+    dryRun(enabled = true) {
+        this.localDryRun = enabled;
+        return this;
+    }
+    isDryRunActive() {
+        return this.localDryRun !== null
+            ? this.localDryRun
+            : Config.isGlobalDryRun();
+    }
+    async checkProtection(hasChanges) {
+        if (this.isProtected && hasChanges) {
+            console.error(`\n🛑 [CRITICAL] Resource "${this.name}" is PROTECTED.`);
+            console.error(`   Refusing to apply changes to a protected resource.`);
+            console.error(`   Please remove .protect() if you intentionally want to modify this.`);
+            return true;
+        }
+        return false;
+    }
+    // Waits for a long-running cloud operation to complete.
+    // In dry-run mode: skips entirely — no waiting.
+    // In real mode: polls via the provided condition fn until it returns true.
+    // The mock fallback simulates a realistic delay with progress output.
+    async waitFor(label, condition, opts = {}) {
+        if (this.isDryRunActive()) {
+            console.log(`   ⏭️  [PLAN] Would wait for: ${label}`);
+            return;
+        }
+        const intervalMs = opts.intervalMs ?? 5000;
+        const timeoutMs = opts.timeoutMs ?? 600_000; // 10 min default
+        const started = Date.now();
+        process.stdout.write(`   ⏳ Waiting for ${label}`);
+        while (true) {
+            const done = await condition();
+            if (done) {
+                console.log(` ✅`);
+                return;
+            }
+            if (Date.now() - started > timeoutMs) {
+                console.log(` ❌`);
+                throw new Error(`Timed out waiting for: ${label}`);
+            }
+            process.stdout.write(`.`);
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    async deploySidecars() {
+        for (const sidecar of this.sidecars) {
+            await sidecar.deploy();
+        }
+    }
+    async destroySidecars() {
+        for (const sidecar of [...this.sidecars].reverse()) {
+            await sidecar.destroy();
+        }
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        console.log(`\n🗑️  Destroying "${this.name}"...`);
+        console.log(`   ✅ [${dryRun ? 'PLAN' : 'OK'}] Resource "${this.name}" marked for destruction.`);
+        await this.destroySidecars();
+        return { destroyed: this.name };
+    }
+}

package/dist/core/stack.d.ts

@@ -0,0 +1,20 @@
+import "reflect-metadata";
+export declare abstract class Stack {
+    /** @internal — called by @Deploy to register the instance for cross-stack references. */
+    static _register(cls: Function, instance: Stack): void;
+    /**
+     * Returns the already-constructed instance of another Stack so you can reference
+     * its resource Output fields before deployment completes.
+     *
+     * The target stack must be decorated with @Deploy and imported before this call.
+     *
+     * @example
+     * class DNSStack extends Stack {
+     *   private infra = Stack.from(InfraStack);
+     *   dns = DO.Domain("example.com").pointer("app", this.infra.app.ip);
+     * }
+     */
+    static from<T extends Stack>(cls: new (...args: any[]) => T): T;
+    deploy(): Promise<Record<string, any>>;
+    destroy(): Promise<Record<string, any>>;
+}