puls-dev 0.3.2 → 0.3.4

package/dist/bin/puls.d.ts

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

package/dist/bin/puls.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+function findTsx() {
+    let dir = process.cwd();
+    while (true) {
+        const candidate = path.join(dir, "node_modules", ".bin", "tsx");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function getVersion() {
+    try {
+        const pkg = require(path.join(__dirname, "../../package.json"));
+        return pkg.version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+const HELP = `
+Usage:
+  puls plan    <file>   Dry-run the stack — prints what would change, no API writes
+  puls deploy  <file>   Deploy the stack
+  puls destroy <file>   Destroy the stack
+
+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
+
+Examples:
+  puls plan    infra/staging.ts
+  puls deploy  infra/staging.ts --parallel
+  puls destroy infra/staging.ts
+`.trim();
+let parsed;
+try {
+    parsed = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            parallel: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            version: { type: "boolean", short: "v" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+}
+catch (err) {
+    console.error(`Error: ${err.message}`);
+    console.error('Run "puls --help" for usage.');
+    process.exit(1);
+}
+const { values, positionals } = parsed;
+if (values.version) {
+    console.log(`puls v${getVersion()}`);
+    process.exit(0);
+}
+if (values.help || positionals.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+}
+const [command, userFile] = positionals;
+const COMMANDS = ["plan", "deploy", "destroy"];
+if (!COMMANDS.includes(command)) {
+    console.error(`Error: Unknown command "${command}". Expected: plan, deploy, or destroy.`);
+    console.error('Run "puls --help" for usage.');
+    process.exit(1);
+}
+if (!userFile) {
+    console.error(`Error: Missing file argument.\nUsage: puls ${command} <file>`);
+    process.exit(1);
+}
+const resolvedFile = path.resolve(process.cwd(), userFile);
+if (!existsSync(resolvedFile)) {
+    console.error(`Error: File not found: ${resolvedFile}`);
+    process.exit(1);
+}
+const childEnv = { ...process.env };
+if (command === "plan" || values["dry-run"]) {
+    childEnv.PULS_DRY_RUN = "true";
+}
+if (command === "destroy") {
+    childEnv.PULS_MODE = "destroy";
+}
+if (values.parallel) {
+    childEnv.PULS_PARALLEL = "true";
+}
+const tsxBin = findTsx() ?? "tsx";
+const child = spawn(tsxBin, [resolvedFile], {
+    stdio: "inherit",
+    env: childEnv,
+});
+child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+        console.error("Error: Could not find tsx. Install it in your project:\n\n" +
+            "  npm install --save-dev tsx\n\n" +
+            "or globally:\n\n" +
+            "  npm install -g tsx");
+    }
+    else {
+        console.error(`Error spawning tsx: ${err.message}`);
+    }
+    process.exit(1);
+});
+child.on("close", (code) => {
+    process.exit(code ?? 1);
+});

package/dist/core/config.d.ts

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

package/dist/core/context.d.ts

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

package/dist/core/decorators.d.ts

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

package/dist/core/decorators.js

@@ -23,6 +23,11 @@ function applyConfig(opts) {
             },
         });
     }
+    // CLI env-var overrides — applied last so `puls plan/destroy/--parallel` wins over decorator options
+    if (process.env.PULS_DRY_RUN === "true")
+        Config.set({ dryRun: true });
+    if (process.env.PULS_PARALLEL === "true")
+        Config.set({ parallel: true });
 }
 export function Protected(target, propertyKey) {
     Reflect.defineMetadata("protected", true, target, propertyKey);
@@ -73,15 +78,22 @@ export function Destroy(optsOrTarget, propertyKey) {
 export function Deploy(opts = {}) {
     return function (constructor) {
         const regions = opts.regions ?? [];
+        const mode = process.env.PULS_MODE;
         if (regions.length > 0) {
             Promise.resolve().then(async () => {
                 for (const r of regions) {
-                    console.log(`\n🌍 [MULTI-REGION] Deploying stack to region: ${r}`);
+                    const label = mode === "destroy" ? "Tearing down" : "Deploying";
+                    console.log(`\n🌍 [MULTI-REGION] ${label} stack in region: ${r}`);
                     applyConfig({ ...opts, region: r });
                     const instance = new constructor();
                     Stack._register(constructor, instance, r);
-                    if (typeof instance.deploy === "function") {
-                        await instance.deploy();
+                    if (mode === "destroy") {
+                        if (typeof instance.destroy === "function")
+                            await instance.destroy();
+                    }
+                    else {
+                        if (typeof instance.deploy === "function")
+                            await instance.deploy();
                     }
                 }
             });
@@ -91,8 +103,14 @@ export function Deploy(opts = {}) {
             const instance = new constructor();
             Stack._register(constructor, instance);
             Promise.resolve().then(async () => {
-                if (typeof instance.deploy === "function")
-                    await instance.deploy();
+                if (mode === "destroy") {
+                    if (typeof instance.destroy === "function")
+                        await instance.destroy();
+                }
+                else {
+                    if (typeof instance.deploy === "function")
+                        await instance.deploy();
+                }
             });
         }
     };

package/dist/core/output.js

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

package/dist/core/production.test.js

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

package/dist/core/secret.d.ts

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

package/dist/core/secret.js

@@ -1,6 +1,10 @@
 import { Output } from "./output.js";
 import { Config } from "./config.js";
+import { resourceContextStorage } from "./context.js";
 export const resolvedSecrets = new Set();
+export function clearResolvedSecrets() {
+    resolvedSecrets.clear();
+}
 /**
  * Secret represents a lazy, secure credential that is fetched asynchronously
  * at deployment time instead of during the eager construction phase.
@@ -25,6 +29,7 @@ export class Secret extends Output {
             this.resolve(val);
             if (val && val.length >= 3) {
                 resolvedSecrets.add(val);
+                resourceContextStorage.getStore()?.secrets.add(val);
             }
         }
         catch (err) {

package/dist/core/stack.js

@@ -3,6 +3,42 @@ import { BaseBuilder } from "./resource.js";
 import { Config } from "./config.js";
 import { resourceContextStorage } from "./context.js";
 import { resolvedSecrets } from "./secret.js";
+async function withRedactedConsole(secrets, fn) {
+    const originalLog = console.log;
+    const redact = (message) => {
+        if (typeof message !== "string")
+            return message;
+        let result = message;
+        for (const secret of secrets) {
+            if (secret && secret.length >= 3) {
+                const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+                result = result.replace(new RegExp(escaped, "g"), "********");
+            }
+        }
+        return result;
+    };
+    console.log = (...args) => {
+        const redactedArgs = args.map((arg) => {
+            if (typeof arg === "string")
+                return redact(arg);
+            try {
+                const str = String(arg);
+                const hasSecret = [...secrets].some((s) => s && s.length >= 3 && str.includes(s));
+                if (hasSecret)
+                    return redact(str);
+            }
+            catch { }
+            return arg;
+        });
+        originalLog(...redactedArgs);
+    };
+    try {
+        return await fn();
+    }
+    finally {
+        console.log = originalLog;
+    }
+}
 const _registry = new Map();
 function formatEntry(val, parentKey) {
     const isSensitiveKey = (k) => /password|secret|token|key/i.test(k);
@@ -102,50 +138,16 @@ export class Stack {
     async deploy() {
         const controller = new AbortController();
         const hosts = [];
+        // Snapshot current secrets; new secrets resolved during this run are added via context
+        const secrets = new Set(resolvedSecrets);
         const context = {
             abortSignal: controller.signal,
             hosts,
-            stackName: this.constructor.name
+            stackName: this.constructor.name,
+            secrets,
         };
         return resourceContextStorage.run(context, async () => {
-            const originalLog = console.log;
-            console.log = (...args) => {
-                const redact = (message) => {
-                    if (typeof message !== "string")
-                        return message;
-                    let result = message;
-                    for (const secret of resolvedSecrets) {
-                        if (secret && secret.length >= 3) {
-                            const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
-                            const regex = new RegExp(escaped, 'g');
-                            result = result.replace(regex, '********');
-                        }
-                    }
-                    return result;
-                };
-                const redactedArgs = args.map(arg => {
-                    if (typeof arg === "string") {
-                        return redact(arg);
-                    }
-                    try {
-                        const str = String(arg);
-                        let hasSecret = false;
-                        for (const secret of resolvedSecrets) {
-                            if (secret && secret.length >= 3 && str.includes(secret)) {
-                                hasSecret = true;
-                                break;
-                            }
-                        }
-                        if (hasSecret) {
-                            return redact(str);
-                        }
-                    }
-                    catch { }
-                    return arg;
-                });
-                originalLog(...redactedArgs);
-            };
-            try {
+            return withRedactedConsole(secrets, async () => {
                 console.log(`\n🏗️  Deploying Stack: ${this.constructor.name}`);
                 // Stack-level beforeDeploy hook
                 if (typeof this.beforeDeploy === "function") {
@@ -187,11 +189,13 @@ export class Stack {
                 }
                 // 2. Schedule execution
                 if (isParallel) {
-                    const startPromise = Promise.resolve();
                     const promises = resources.map(({ prop, resource }) => {
                         resource._deployPromise = (async () => {
                             try {
-                                await startPromise;
+                                // Yield so the map() loop finishes assigning all _deployPromise values before
+                                // any task checks its dependencies — a dependency that appears later in the list
+                                // would otherwise have an undefined _deployPromise and be silently skipped.
+                                await Promise.resolve();
                                 if (controller.signal.aborted) {
                                     throw new Error("Deployment aborted due to previous failure");
                                 }
@@ -287,59 +291,21 @@ export class Stack {
                     await this.afterDeploy(outputs);
                 }
                 return outputs;
-            }
-            finally {
-                console.log = originalLog;
-            }
+            });
         });
     }
     async destroy() {
         const controller = new AbortController();
         const hosts = [];
+        const secrets = new Set(resolvedSecrets);
         const context = {
             abortSignal: controller.signal,
             hosts,
-            stackName: this.constructor.name
+            stackName: this.constructor.name,
+            secrets,
         };
         return resourceContextStorage.run(context, async () => {
-            const originalLog = console.log;
-            console.log = (...args) => {
-                const redact = (message) => {
-                    if (typeof message !== "string")
-                        return message;
-                    let result = message;
-                    for (const secret of resolvedSecrets) {
-                        if (secret && secret.length >= 3) {
-                            const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
-                            const regex = new RegExp(escaped, 'g');
-                            result = result.replace(regex, '********');
-                        }
-                    }
-                    return result;
-                };
-                const redactedArgs = args.map(arg => {
-                    if (typeof arg === "string") {
-                        return redact(arg);
-                    }
-                    try {
-                        const str = String(arg);
-                        let hasSecret = false;
-                        for (const secret of resolvedSecrets) {
-                            if (secret && secret.length >= 3 && str.includes(secret)) {
-                                hasSecret = true;
-                                break;
-                            }
-                        }
-                        if (hasSecret) {
-                            return redact(str);
-                        }
-                    }
-                    catch { }
-                    return arg;
-                });
-                originalLog(...redactedArgs);
-            };
-            try {
+            return withRedactedConsole(secrets, async () => {
                 console.log(`\n💥 Tearing down Stack: ${this.constructor.name}`);
                 // Stack-level beforeDestroy hook
                 if (typeof this.beforeDestroy === "function") {
@@ -374,12 +340,13 @@ export class Stack {
                 }
                 // 2. Schedule execution
                 if (isParallel) {
-                    const startPromise = Promise.resolve();
                     // In parallel destroy, await all dependents (reverse dependencies) first
                     const promises = resources.map(({ prop, resource }) => {
                         resource._destroyPromise = (async () => {
                             try {
-                                await startPromise;
+                                // Yield so the map() loop finishes assigning all _destroyPromise values before
+                                // any task checks its dependents (same reason as parallel deploy).
+                                await Promise.resolve();
                                 if (controller.signal.aborted) {
                                     throw new Error("Teardown aborted due to previous failure");
                                 }
@@ -458,10 +425,7 @@ export class Stack {
                     await this.afterDestroy(outputs);
                 }
                 return outputs;
-            }
-            finally {
-                console.log = originalLog;
-            }
+            });
         });
     }
 }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
-export { Secret } from "./core/secret.js";
+export { Secret, clearResolvedSecrets } from "./core/secret.js";
 export { Output } from "./core/output.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
 export { SLACK, DISCORD } from "./core/hooks.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
-export { Secret } from "./core/secret.js";
+export { Secret, clearResolvedSecrets } from "./core/secret.js";
 export { Output } from "./core/output.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
 export { SLACK, DISCORD } from "./core/hooks.js";

package/dist/providers/do/droplet.d.ts

@@ -12,6 +12,7 @@ export declare class DropletBuilder extends BaseBuilder {
     private dropletId?;
     private resolvedIp?;
     private sshKeyPath?;
+    private _sshUser?;
     private _provision;
     private _forceConfigCheck;
     constructor(name: string);
@@ -21,7 +22,11 @@ export declare class DropletBuilder extends BaseBuilder {
     image(image: (typeof OS)[keyof typeof OS] | string): this;
     region(region: (typeof REGION)[keyof typeof REGION] | string): this;
     size(size: (typeof SIZE)[keyof typeof SIZE] | string): this;
+    sshKey(keyPath: string): this;
+    /** @deprecated Use `.sshKey()` instead */
     sslKey(keyPath: string): this;
+    sshUser(user: string): this;
+    private resolveUser;
     vpc(uuid: string | Output<string>): this;
     provision(...playbookPaths: (string | string[])[]): this;
     forceConfigCheck(): this;

package/dist/providers/do/droplet.js

@@ -24,6 +24,7 @@ export class DropletBuilder extends BaseBuilder {
     dropletId;
     resolvedIp;
     sshKeyPath;
+    _sshUser;
     _provision = [];
     _forceConfigCheck = false;
     constructor(name) {
@@ -70,10 +71,24 @@ export class DropletBuilder extends BaseBuilder {
         this.config.size = size;
         return this;
     }
-    sslKey(keyPath) {
+    sshKey(keyPath) {
         this.sshKeyPath = keyPath.replace('~', homedir());
         return this;
     }
+    /** @deprecated Use `.sshKey()` instead */
+    sslKey(keyPath) {
+        return this.sshKey(keyPath);
+    }
+    sshUser(user) {
+        this._sshUser = user;
+        return this;
+    }
+    resolveUser() {
+        return (this._sshUser ??
+            process.env.DO_SSH_USER ??
+            Config.get().providers.do?.sshUser ??
+            "root");
+    }
     vpc(uuid) {
         this.config.vpc_uuid = uuid;
         return this;
@@ -91,7 +106,7 @@ export class DropletBuilder extends BaseBuilder {
     }
     async runProvisioner(ip, script) {
         const keyPath = this.sshKeyPath ? this.sshKeyPath : undefined;
-        return runProvisioner(ip, "root", keyPath, script);
+        return runProvisioner(ip, this.resolveUser(), keyPath, script);
     }
     async resolveOrRegisterSshKey(api) {
         const pubPath = this.sshKeyPath.replace(/\.pub$/, '') + '.pub';
@@ -258,7 +273,7 @@ export class DropletBuilder extends BaseBuilder {
                 context.hosts.push({
                     name: this.name,
                     ip: activeIp,
-                    user: "root",
+                    user: this.resolveUser(),
                     sshKey: this.sshKeyPath,
                     provider: "do"
                 });

package/dist/providers/do/droplet.test.js

@@ -106,7 +106,7 @@ describe('DropletBuilder Unit Tests', () => {
         builder
             .region('nyc3')
             .size('s-1vcpu-1gb')
-            .sslKey('~/.ssh/id_rsa.pub');
+            .sshKey('~/.ssh/id_rsa.pub');
         const result = await builder.deploy();
         assert.ok(result);
         assert.strictEqual(result.region, 'nyc3');

package/dist/providers/gcp/template.d.ts

@@ -9,6 +9,7 @@ export declare class GCPTemplateBuilder extends BaseBuilder {
     private _zone;
     private _network;
     private _sshKeys;
+    private _sshUser?;
     private _provision;
     constructor(name: string);
     baseImage(img: string): this;
@@ -16,6 +17,8 @@ export declare class GCPTemplateBuilder extends BaseBuilder {
     zone(z: string): this;
     network(netPath: string): this;
     sshKey(keys: string | string[]): this;
+    sshUser(user: string): this;
+    private resolveUser;
     provision(...playbookPaths: (string | string[])[]): this;
     private discoverImage;
     protected checkPort(ip: string, port: number): Promise<boolean>;

package/dist/providers/gcp/template.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { homedir } from "node:os";
 import { BaseBuilder } from "../../core/resource.js";
+import { Config } from "../../core/config.js";
 import { Output } from "../../core/output.js";
 import { gcpFetch, getProjectId } from "./api.js";
 import { checkPort, runProvisioner } from "../../core/provisioner.js";
@@ -15,6 +16,7 @@ export class GCPTemplateBuilder extends BaseBuilder {
     _zone = "us-central1-a";
     _network = "global/networks/default";
     _sshKeys = [];
+    _sshUser;
     _provision = [];
     constructor(name) {
         super(name);
@@ -41,6 +43,16 @@ export class GCPTemplateBuilder extends BaseBuilder {
         this._sshKeys = keys;
         return this;
     }
+    sshUser(user) {
+        this._sshUser = user;
+        return this;
+    }
+    resolveUser() {
+        return (this._sshUser ??
+            process.env.GCP_SSH_USER ??
+            Config.get().providers.gcp?.sshUser ??
+            "root");
+    }
     provision(...playbookPaths) {
         this._provision.push(...playbookPaths.flat());
         return this;
@@ -66,7 +78,7 @@ export class GCPTemplateBuilder extends BaseBuilder {
     async runProvisioner(ip, script) {
         const keysArray = Array.isArray(this._sshKeys) ? this._sshKeys : [this._sshKeys];
         const keyPath = keysArray.find(k => !k.startsWith('ssh-') && !k.startsWith('ecdsa-') && !k.startsWith('sk-'));
-        return runProvisioner(ip, "root", keyPath, script);
+        return runProvisioner(ip, this.resolveUser(), keyPath, script);
     }
     async deploy() {
         const dryRun = this.isDryRunActive();

package/dist/providers/gcp/vm.d.ts

@@ -12,6 +12,7 @@ export declare class GCPVMBuilder extends BaseBuilder {
     private _zone;
     private _network;
     private _sshKeys;
+    private _sshUser?;
     private _provision;
     private _forceConfigCheck;
     private resolvedInstanceId?;
@@ -23,6 +24,8 @@ export declare class GCPVMBuilder extends BaseBuilder {
     zone(z: string): this;
     network(netPath: string): this;
     sshKey(keys: string | string[]): this;
+    sshUser(user: string): this;
+    private resolveUser;
     provision(...playbookPaths: (string | string[])[]): this;
     forceConfigCheck(): this;
     protected checkPort(ip: string, port: number): Promise<boolean>;