puls-dev 0.2.6 → 0.2.8

package/dist/core/parser.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Strips comments from a YAML/JSON line while preserving comment hashes inside quotes.
+ */
+function stripComments(line) {
+    const hashIdx = line.indexOf("#");
+    if (hashIdx < 0)
+        return line;
+    let inQuotes = false;
+    let quoteChar = "";
+    for (let i = 0; i < hashIdx; i++) {
+        const char = line[i];
+        if (char === '"' || char === "'") {
+            if (!inQuotes) {
+                inQuotes = true;
+                quoteChar = char;
+            }
+            else if (char === quoteChar) {
+                inQuotes = false;
+            }
+        }
+    }
+    if (inQuotes) {
+        return line;
+    }
+    return line.slice(0, hashIdx);
+}
+/**
+ * Robust, zero-dependency, indentation-aware YAML parser.
+ * Parses sequences of key-value maps and nested string arrays.
+ */
+export function parseYaml(content) {
+    const list = [];
+    const lines = content.split(/\r?\n/);
+    let currentItem = null;
+    let activeKey = null;
+    let rootIndent = 0;
+    for (let line of lines) {
+        line = stripComments(line);
+        if (!line.trim())
+            continue;
+        const leadingSpaces = line.length - line.trimStart().length;
+        const trimmed = line.trim();
+        // Check if it's a bullet item list entry
+        if (trimmed.startsWith("-")) {
+            const rest = trimmed.slice(1).trim();
+            // If it is indented more than the root item and does not match a key-value pattern,
+            // treat it as an array item under the active key.
+            const isRestKeyValue = /^[a-zA-Z0-9_-]+\s*:/.test(rest);
+            if (leadingSpaces > rootIndent && !isRestKeyValue) {
+                if (currentItem && activeKey) {
+                    if (!Array.isArray(currentItem[activeKey])) {
+                        currentItem[activeKey] = [];
+                    }
+                    let val = rest;
+                    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+                        val = val.slice(1, -1);
+                    }
+                    currentItem[activeKey].push(val);
+                }
+                continue;
+            }
+            // Otherwise, it represents a new item at the root list level
+            if (currentItem) {
+                list.push(currentItem);
+            }
+            currentItem = {};
+            rootIndent = leadingSpaces;
+            activeKey = null;
+            if (rest) {
+                const colonIdx = rest.indexOf(":");
+                if (colonIdx > 0 && isRestKeyValue) {
+                    const key = rest.slice(0, colonIdx).trim();
+                    let value = rest.slice(colonIdx + 1).trim();
+                    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    // Convert to number if numeric
+                    if (/^\d+$/.test(value)) {
+                        currentItem[key] = parseInt(value, 10);
+                    }
+                    else {
+                        currentItem[key] = value;
+                    }
+                    activeKey = key;
+                }
+            }
+        }
+        else {
+            // Key-value pair or list start
+            const isKeyValue = /^[a-zA-Z0-9_-]+\s*:/.test(trimmed);
+            if (isKeyValue && currentItem) {
+                const colonIdx = trimmed.indexOf(":");
+                const key = trimmed.slice(0, colonIdx).trim();
+                let value = trimmed.slice(colonIdx + 1).trim();
+                if (value === "") {
+                    // Starts a nested list/array
+                    currentItem[key] = [];
+                    activeKey = key;
+                }
+                else {
+                    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    if (/^\d+$/.test(value)) {
+                        currentItem[key] = parseInt(value, 10);
+                    }
+                    else {
+                        currentItem[key] = value;
+                    }
+                    activeKey = key;
+                }
+            }
+        }
+    }
+    if (currentItem) {
+        list.push(currentItem);
+    }
+    return list;
+}
+/**
+ * Resolves a file path relative to the current working directory,
+ * reads its content, and parses it according to its extension (.json vs .yaml/.yml).
+ */
+export function loadRecordsFromFile(filePath) {
+    const absolutePath = path.resolve(process.cwd(), filePath);
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".json") {
+        const parsed = JSON.parse(fileContent);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    else if (ext === ".yaml" || ext === ".yml") {
+        return parseYaml(fileContent);
+    }
+    else {
+        throw new Error(`Unsupported configuration file format: ${filePath}. Only JSON and YAML/YML files are supported.`);
+    }
+}

package/dist/core/parser.test.d.ts

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

package/dist/core/parser.test.js

@@ -0,0 +1,117 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import { parseYaml, loadRecordsFromFile } from "./parser.js";
+describe("YAML & JSON Config Parser", () => {
+    test("parses standard simple key-value YAML blocks correctly", () => {
+        const yaml = `
+- name: www
+  type: CNAME
+  value: lb.google.com
+- name: mail
+  type: A
+  value: 1.2.3.4
+  ttl: 600
+`;
+        const result = parseYaml(yaml);
+        assert.strictEqual(result.length, 2);
+        assert.deepStrictEqual(result[0], {
+            name: "www",
+            type: "CNAME",
+            value: "lb.google.com",
+        });
+        assert.deepStrictEqual(result[1], {
+            name: "mail",
+            type: "A",
+            value: "1.2.3.4",
+            ttl: 600,
+        });
+    });
+    test("ignores comments and blank lines in YAML", () => {
+        const yaml = `
+# This is a comment at the top
+- name: "@"
+  type: TXT  # inline comment
+  value: "v=spf1 include:_spf.google.com ~all"
+
+# Another comment with spaces
+- name: api
+  type: CNAME
+  value: api.service.com
+`;
+        const result = parseYaml(yaml);
+        assert.strictEqual(result.length, 2);
+        assert.strictEqual(result[0].name, "@");
+        assert.strictEqual(result[0].type, "TXT");
+        assert.strictEqual(result[0].value, "v=spf1 include:_spf.google.com ~all");
+        assert.strictEqual(result[1].name, "api");
+    });
+    test("parses nested array list values based on indentation", () => {
+        const yaml = `
+- type: ingress
+  protocol: tcp
+  port: 80
+  sources:
+    - 0.0.0.0/0
+    - ::/0
+- type: egress
+  protocol: tcp
+  port: all
+  destinations:
+    - 10.0.0.0/8
+`;
+        const result = parseYaml(yaml);
+        assert.strictEqual(result.length, 2);
+        assert.deepStrictEqual(result[0], {
+            type: "ingress",
+            protocol: "tcp",
+            port: 80,
+            sources: ["0.0.0.0/0", "::/0"],
+        });
+        assert.deepStrictEqual(result[1], {
+            type: "egress",
+            protocol: "tcp",
+            port: "all",
+            destinations: ["10.0.0.0/8"],
+        });
+    });
+    test("loads from JSON and YAML files successfully", () => {
+        const tempJsonPath = path.resolve(process.cwd(), "temp-test-records.json");
+        const tempYamlPath = path.resolve(process.cwd(), "temp-test-records.yaml");
+        const jsonContent = JSON.stringify([
+            { name: "api", type: "CNAME", value: "lb.com" }
+        ]);
+        const yamlContent = `
+- name: web
+  type: A
+  value: 5.6.7.8
+`;
+        // Write temp files
+        fs.writeFileSync(tempJsonPath, jsonContent, "utf-8");
+        fs.writeFileSync(tempYamlPath, yamlContent, "utf-8");
+        try {
+            const parsedJson = loadRecordsFromFile("temp-test-records.json");
+            assert.strictEqual(parsedJson.length, 1);
+            assert.deepStrictEqual(parsedJson[0], {
+                name: "api",
+                type: "CNAME",
+                value: "lb.com",
+            });
+            const parsedYaml = loadRecordsFromFile("temp-test-records.yaml");
+            assert.strictEqual(parsedYaml.length, 1);
+            assert.deepStrictEqual(parsedYaml[0], {
+                name: "web",
+                type: "A",
+                value: "5.6.7.8",
+            });
+        }
+        finally {
+            // Clean up temp files
+            if (fs.existsSync(tempJsonPath))
+                fs.unlinkSync(tempJsonPath);
+            if (fs.existsSync(tempYamlPath))
+                fs.unlinkSync(tempYamlPath);
+        }
+    });
+});

package/dist/core/provisioner.d.ts

@@ -0,0 +1,4 @@
+export declare function checkPort(ip: string, port: number): Promise<boolean>;
+export declare function runAnsible(ip: string, user: string, sshKeys: string | string[] | undefined, playbook: string): Promise<void>;
+export declare function runPuppet(ip: string, user: string, sshKeys: string | string[] | undefined, manifest: string): Promise<void>;
+export declare function runProvisioner(ip: string, user: string, sshKeys: string | string[] | undefined, scriptPath: string): Promise<void>;

package/dist/core/provisioner.js

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { homedir } from "node:os";
+export function checkPort(ip, port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(2000);
+        socket.on("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on("error", () => {
+            resolve(false);
+        });
+        socket.on("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, ip);
+    });
+}
+function resolveSshKeyPath(sshKeys) {
+    const keyInput = Array.isArray(sshKeys) ? null : sshKeys;
+    return (keyInput &&
+        !keyInput.startsWith("ssh-") &&
+        !keyInput.startsWith("ecdsa-") &&
+        !keyInput.startsWith("sk-")
+        ? keyInput.replace(/\.pub$/, "")
+        : `${homedir()}/.ssh/id_ed25519`).replace(/^~/, homedir());
+}
+export function runAnsible(ip, user, sshKeys, playbook) {
+    console.log(`   🔧 Running Ansible: ${playbook} → ${ip}`);
+    const keyPath = resolveSshKeyPath(sshKeys);
+    return new Promise((resolve, reject) => {
+        const proc = spawn("ansible-playbook", [
+            playbook,
+            "-i",
+            `${ip},`,
+            "-u",
+            user,
+            "--private-key",
+            keyPath,
+            "--ssh-extra-args",
+            "-o StrictHostKeyChecking=no -o ConnectTimeout=30",
+        ], { stdio: "inherit" });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                console.log(`   ✅ Provisioning complete`);
+                resolve();
+            }
+            else
+                reject(new Error(`ansible-playbook exited with code ${code}`));
+        });
+        proc.on("error", (err) => reject(new Error(`Failed to run ansible-playbook: ${err.message}`)));
+    });
+}
+export function runPuppet(ip, user, sshKeys, manifest) {
+    console.log(`   🔧 Applying Puppet manifest: ${manifest} → ${ip}`);
+    const keyPath = resolveSshKeyPath(sshKeys);
+    // Copy manifest then apply it
+    return new Promise((resolve, reject) => {
+        const scp = spawn("scp", [
+            "-i",
+            keyPath,
+            "-o",
+            "StrictHostKeyChecking=no",
+            manifest,
+            `${user}@${ip}:/tmp/manifest.pp`,
+        ], { stdio: "inherit" });
+        scp.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`scp exited with code ${code}`));
+                return;
+            }
+            const puppet = spawn("ssh", [
+                "-i",
+                keyPath,
+                "-o",
+                "StrictHostKeyChecking=no",
+                `${user}@${ip}`,
+                "puppet apply /tmp/manifest.pp",
+            ], { stdio: "inherit" });
+            puppet.on("close", (c) => {
+                if (c === 0) {
+                    console.log(`   ✅ Provisioning complete`);
+                    resolve();
+                }
+                else
+                    reject(new Error(`puppet apply exited with code ${c}`));
+            });
+            puppet.on("error", (err) => reject(new Error(`Failed to run puppet: ${err.message}`)));
+        });
+        scp.on("error", (err) => reject(new Error(`Failed to run scp: ${err.message}`)));
+    });
+}
+export function runProvisioner(ip, user, sshKeys, scriptPath) {
+    const ext = scriptPath.split(".").pop()?.toLowerCase();
+    if (ext === "sh") {
+        throw new Error(`Shell script provisioning (.sh) is no longer supported. ` +
+            `Please migrate "${scriptPath}" to an Ansible playbook (.yaml/.yml).`);
+    }
+    if (ext === "pp")
+        return runPuppet(ip, user, sshKeys, scriptPath);
+    return runAnsible(ip, user, sshKeys, scriptPath); // .yml / .yaml
+}

package/dist/core/resource.d.ts

@@ -4,9 +4,25 @@ export declare abstract class BaseBuilder {
     protected localDryRun: boolean | null;
     protected discoveryPromise: Promise<any>;
     protected sidecars: BaseBuilder[];
+    private _beforeDeployHooks;
+    private _afterDeployHooks;
+    private _beforeDestroyHooks;
+    private _afterDestroyHooks;
     constructor(name: string);
     protect(): this;
     dryRun(enabled?: boolean): this;
+    beforeDeploy(callback: () => Promise<void> | void): this;
+    afterDeploy(callback: (result: any) => Promise<void> | void): this;
+    beforeDestroy(callback: () => Promise<void> | void): this;
+    afterDestroy(callback: (result: any) => Promise<void> | void): this;
+    /** @internal */
+    _runBeforeDeploy(): Promise<void>;
+    /** @internal */
+    _runAfterDeploy(result: any): Promise<void>;
+    /** @internal */
+    _runBeforeDestroy(): Promise<void>;
+    /** @internal */
+    _runAfterDestroy(result: any): Promise<void>;
     protected isDryRunActive(): boolean;
     protected checkProtection(hasChanges: boolean): Promise<boolean>;
     protected waitFor(label: string, condition: () => Promise<boolean>, opts?: {

package/dist/core/resource.js

@@ -5,6 +5,10 @@ export class BaseBuilder {
     localDryRun = null;
     discoveryPromise;
     sidecars = [];
+    _beforeDeployHooks = [];
+    _afterDeployHooks = [];
+    _beforeDestroyHooks = [];
+    _afterDestroyHooks = [];
     constructor(name) {
         this.name = name;
     }
@@ -16,6 +20,46 @@ export class BaseBuilder {
         this.localDryRun = enabled;
         return this;
     }
+    beforeDeploy(callback) {
+        this._beforeDeployHooks.push(callback);
+        return this;
+    }
+    afterDeploy(callback) {
+        this._afterDeployHooks.push(callback);
+        return this;
+    }
+    beforeDestroy(callback) {
+        this._beforeDestroyHooks.push(callback);
+        return this;
+    }
+    afterDestroy(callback) {
+        this._afterDestroyHooks.push(callback);
+        return this;
+    }
+    /** @internal */
+    async _runBeforeDeploy() {
+        for (const cb of this._beforeDeployHooks) {
+            await cb();
+        }
+    }
+    /** @internal */
+    async _runAfterDeploy(result) {
+        for (const cb of this._afterDeployHooks) {
+            await cb(result);
+        }
+    }
+    /** @internal */
+    async _runBeforeDestroy() {
+        for (const cb of this._beforeDestroyHooks) {
+            await cb();
+        }
+    }
+    /** @internal */
+    async _runAfterDestroy(result) {
+        for (const cb of this._afterDestroyHooks) {
+            await cb(result);
+        }
+    }
     isDryRunActive() {
         return this.localDryRun !== null
             ? this.localDryRun

package/dist/core/secret.d.ts

@@ -0,0 +1,40 @@
+import { Output } from "./output.js";
+/**
+ * Secret represents a lazy, secure credential that is fetched asynchronously
+ * at deployment time instead of during the eager construction phase.
+ */
+export declare class Secret extends Output<string> {
+    readonly secretName: string;
+    constructor(secretName: string, fetcher: () => Promise<string>);
+    private startFetching;
+    /**
+     * Helper method to seamlessly unpack either a static string, a standard Output, or a Secret.
+     * Call this within resource builder deploy() methods.
+     */
+    static resolve(val: string | Output<string> | Secret | any): Promise<string>;
+    /**
+     * Fetches a secret from a local environment variable.
+     */
+    static env(envName: string, fallback?: string): Secret;
+    /**
+     * Fetches a secret from AWS Secrets Manager.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static aws(secretId: string, options?: {
+        region?: string;
+    }): Secret;
+    /**
+     * Fetches a parameter from AWS SSM Parameter Store.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static ssm(parameterName: string, options?: {
+        region?: string;
+    }): Secret;
+    /**
+     * Fetches a secret from GCP Secret Manager.
+     * Uses dynamic imports so GCP config/fetch tools are only loaded if this helper is actually called.
+     */
+    static gcp(secretId: string, options?: {
+        projectId?: string;
+    }): Secret;
+}

package/dist/core/secret.js

@@ -0,0 +1,95 @@
+import { Output } from "./output.js";
+import { Config } from "./config.js";
+/**
+ * Secret represents a lazy, secure credential that is fetched asynchronously
+ * at deployment time instead of during the eager construction phase.
+ */
+export class Secret extends Output {
+    secretName;
+    constructor(secretName, fetcher) {
+        super();
+        this.secretName = secretName;
+        this.startFetching(fetcher);
+    }
+    async startFetching(fetcher) {
+        try {
+            if (Config.isGlobalDryRun()) {
+                // Resolve immediately to a secure placeholder during dry-run testing
+                this.resolve(`[SECRET:${this.secretName}]`);
+                return;
+            }
+            const val = await fetcher();
+            this.resolve(val);
+        }
+        catch (err) {
+            this.reject(err);
+        }
+    }
+    /**
+     * Helper method to seamlessly unpack either a static string, a standard Output, or a Secret.
+     * Call this within resource builder deploy() methods.
+     */
+    static async resolve(val) {
+        if (val instanceof Output) {
+            return await val.get();
+        }
+        return val;
+    }
+    /**
+     * Fetches a secret from a local environment variable.
+     */
+    static env(envName, fallback) {
+        return new Secret(envName, async () => {
+            const val = process.env[envName] ?? fallback;
+            if (val === undefined) {
+                throw new Error(`Environment secret "${envName}" is not set and has no fallback.`);
+            }
+            return val;
+        });
+    }
+    /**
+     * Fetches a secret from AWS Secrets Manager.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static aws(secretId, options) {
+        return new Secret(secretId, async () => {
+            const { SecretsManagerClient, GetSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
+            const client = new SecretsManagerClient({ region: options?.region ?? process.env.AWS_REGION ?? "us-east-1" });
+            const result = await client.send(new GetSecretValueCommand({ SecretId: secretId }));
+            if (!result.SecretString) {
+                throw new Error(`AWS Secret "${secretId}" is empty or not a string.`);
+            }
+            return result.SecretString;
+        });
+    }
+    /**
+     * Fetches a parameter from AWS SSM Parameter Store.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static ssm(parameterName, options) {
+        return new Secret(parameterName, async () => {
+            const { SSMClient, GetParameterCommand } = await import("@aws-sdk/client-ssm");
+            const client = new SSMClient({ region: options?.region ?? process.env.AWS_REGION ?? "us-east-1" });
+            const result = await client.send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+            if (!result.Parameter?.Value) {
+                throw new Error(`AWS SSM Parameter "${parameterName}" is empty.`);
+            }
+            return result.Parameter.Value;
+        });
+    }
+    /**
+     * Fetches a secret from GCP Secret Manager.
+     * Uses dynamic imports so GCP config/fetch tools are only loaded if this helper is actually called.
+     */
+    static gcp(secretId, options) {
+        return new Secret(secretId, async () => {
+            const { gcpFetch, getProjectId } = await import("../providers/gcp/api.js");
+            const project = options?.projectId ?? getProjectId();
+            const payload = await gcpFetch("https://secretmanager.googleapis.com", `/v1/projects/${project}/secrets/${secretId}/versions/latest:access`);
+            if (!payload?.payload?.data) {
+                throw new Error(`GCP Secret "${secretId}" payload is empty.`);
+            }
+            return Buffer.from(payload.payload.data, "base64").toString("utf8");
+        });
+    }
+}

package/dist/core/secret.test.d.ts

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