puls-dev 0.2.0 → 0.2.2

package/dist/providers/gcp/cloudsql.test.js

@@ -0,0 +1,295 @@
+import { test, describe, beforeEach, afterEach, mock } from "node:test";
+import assert from "node:assert";
+import { GoogleAuth } from "google-auth-library";
+import { GCPCloudSQLBuilder } from "./cloudsql.js";
+import { Config } from "../../core/config.js";
+describe("GCPCloudSQLBuilder Unit Tests", () => {
+    let originalFetch;
+    let fetchCalls = [];
+    let mockResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                gcp: {
+                    projectId: "my-gcp-project",
+                    serviceAccountPath: "/fake/sa.json",
+                    region: "us-central1",
+                },
+            },
+        });
+        originalFetch = globalThis.fetch;
+        fetchCalls = [];
+        mockResponses = {};
+        globalThis.fetch = async (input, init) => {
+            const url = String(input);
+            const method = init?.method ?? "GET";
+            let body;
+            if (init?.body) {
+                if (typeof init.body === "string") {
+                    try {
+                        body = JSON.parse(init.body);
+                    }
+                    catch {
+                        body = init.body;
+                    }
+                }
+                else {
+                    body = "[Binary/Buffer Body]";
+                }
+            }
+            const headers = init?.headers;
+            fetchCalls.push({ url, method, body, headers });
+            const matchKey = Object.keys(mockResponses)
+                .filter((key) => {
+                const [mMethod, mPath] = key.split(" ");
+                return method === mMethod && url.includes(mPath);
+            })
+                .sort((a, b) => b.split(" ")[1].length - a.split(" ")[1].length)[0];
+            if (matchKey) {
+                const resp = mockResponses[matchKey];
+                return {
+                    ok: resp.status >= 200 && resp.status < 300,
+                    status: resp.status,
+                    json: async () => resp.body,
+                    text: async () => JSON.stringify(resp.body),
+                };
+            }
+            return {
+                ok: false,
+                status: 404,
+                json: async () => ({ message: `Endpoint not mocked: ${method} ${url}` }),
+                text: async () => `Endpoint not mocked: ${method} ${url}`,
+            };
+        };
+        mock.method(GoogleAuth.prototype, "getClient", async () => {
+            return {
+                getAccessToken: async () => ({ token: "fake-gcp-token" }),
+            };
+        });
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        mock.restoreAll();
+    });
+    test("fluent builder api sets properties correctly", () => {
+        const builder = new GCPCloudSQLBuilder("my-db")
+            .engine({ engine: "postgres", version: "15" })
+            .size("db-custom-2-7680")
+            .storage(50)
+            .credentials("db_user", "db_pass")
+            .database("my_app_db")
+            .publicAccess(true)
+            .region("us-east4");
+        assert.strictEqual(builder._engine, "postgres");
+        assert.strictEqual(builder._engineVersion, "15");
+        assert.strictEqual(builder._tier, "db-custom-2-7680");
+        assert.strictEqual(builder._storage, 50);
+        assert.strictEqual(builder._username, "db_user");
+        assert.strictEqual(builder._password, "db_pass");
+        assert.strictEqual(builder._dbName, "my_app_db");
+        assert.strictEqual(builder._publicAccess, true);
+        assert.strictEqual(builder._region, "us-east4");
+    });
+    test("runs in dry-run mode safely and logs plans", async () => {
+        Config.set({
+            dryRun: true,
+            providers: {
+                gcp: {
+                    projectId: "my-gcp-project",
+                    serviceAccountPath: "/fake/sa.json",
+                    region: "us-central1",
+                },
+            },
+        });
+        const builder = new GCPCloudSQLBuilder("dry-run-db")
+            .credentials("root", "secretpwd")
+            .engine({ engine: "mysql", version: "8.0" })
+            .size("db-f1-micro")
+            .storage(15);
+        const result = await builder.deploy();
+        assert.strictEqual(result.name, "dry-run-db");
+        assert.strictEqual(result.endpoint, "127.0.0.1");
+        assert.strictEqual(result.port, 3306);
+        assert.strictEqual(result.connectionName, "my-gcp-project:us-central1:dry-run-db");
+        // No write calls should be sent in dry-run mode
+        const writeCalls = fetchCalls.filter((c) => c.method !== "GET");
+        assert.strictEqual(writeCalls.length, 0);
+    });
+    test("creates a new instance, database, and custom user when missing", async () => {
+        // 1. Stateful mock for GET /instances/new-db: returns 404 on discovery, 200 after creation
+        mockResponses["GET /instances/new-db"] = {
+            get status() {
+                const getCalls = fetchCalls.filter((c) => c.method === "GET" && c.url.includes("/instances/new-db"));
+                return getCalls.length <= 1 ? 404 : 200;
+            },
+            get body() {
+                const getCalls = fetchCalls.filter((c) => c.method === "GET" && c.url.includes("/instances/new-db"));
+                if (getCalls.length <= 1)
+                    return { message: "Not found" };
+                return {
+                    name: "new-db",
+                    connectionName: "my-gcp-project:us-central1:new-db",
+                    ipAddresses: [{ type: "PRIMARY", ipAddress: "35.200.10.20" }],
+                    settings: {
+                        tier: "db-f1-micro",
+                        dataDiskSizeGb: "20",
+                    },
+                };
+            },
+        };
+        // 2. Mock POST (create instance)
+        mockResponses["POST /instances"] = {
+            status: 200,
+            body: { name: "op-create-123", status: "PENDING" },
+        };
+        // 3. Mock GET (poll operation status until DONE)
+        mockResponses["GET /operations/op-create-123"] = {
+            status: 200,
+            body: { status: "DONE" },
+        };
+        // 5. Mock POST (create database)
+        mockResponses["POST /instances/new-db/databases"] = {
+            status: 201,
+            body: {},
+        };
+        // 6. Mock POST (create custom user)
+        mockResponses["POST /instances/new-db/users"] = {
+            status: 201,
+            body: {},
+        };
+        const builder = new GCPCloudSQLBuilder("new-db")
+            .engine({ engine: "postgres", version: "16" })
+            .size("db-f1-micro")
+            .storage(20)
+            .credentials("custom_admin", "securepwd")
+            .database("custom_db")
+            .publicAccess(false);
+        const result = await builder.deploy();
+        assert.strictEqual(result.name, "new-db");
+        assert.strictEqual(result.endpoint, "35.200.10.20");
+        assert.strictEqual(result.port, 5432);
+        assert.strictEqual(result.connectionName, "my-gcp-project:us-central1:new-db");
+        // Verify correct calls were made
+        const postInstances = fetchCalls.find((c) => c.method === "POST" && c.url.endsWith("/instances"));
+        assert.ok(postInstances);
+        assert.strictEqual(postInstances.body.name, "new-db");
+        assert.strictEqual(postInstances.body.databaseVersion, "POSTGRES_16");
+        assert.strictEqual(postInstances.body.rootPassword, "securepwd");
+        assert.strictEqual(postInstances.body.settings.dataDiskSizeGb, "20");
+        const postDB = fetchCalls.find((c) => c.method === "POST" && c.url.includes("/databases"));
+        assert.ok(postDB);
+        assert.strictEqual(postDB.body.name, "custom_db");
+        const postUser = fetchCalls.find((c) => c.method === "POST" && c.url.includes("/users"));
+        assert.ok(postUser);
+        assert.strictEqual(postUser.body.name, "custom_admin");
+        assert.strictEqual(postUser.body.password, "securepwd");
+    });
+    test("patches instance when configuration storage or tier differs", async () => {
+        // 1. Mock GET (discovery) returns existing instance with 10GB and different tier
+        mockResponses["GET /instances/patch-db"] = {
+            status: 200,
+            body: {
+                name: "patch-db",
+                connectionName: "my-gcp-project:us-central1:patch-db",
+                ipAddresses: [{ type: "PRIMARY", ipAddress: "35.200.10.20" }],
+                settings: {
+                    tier: "db-f1-micro",
+                    dataDiskSizeGb: "10",
+                },
+            },
+        };
+        // 2. Mock PATCH (update settings)
+        mockResponses["PATCH /instances/patch-db"] = {
+            status: 200,
+            body: { name: "op-patch-123", status: "PENDING" },
+        };
+        // 3. Mock GET (poll operation status until DONE)
+        mockResponses["GET /operations/op-patch-123"] = {
+            status: 200,
+            body: { status: "DONE" },
+        };
+        const builder = new GCPCloudSQLBuilder("patch-db")
+            .engine({ engine: "postgres", version: "16" })
+            .size("db-custom-2-7680") // changed tier!
+            .storage(30) // increased storage!
+            .credentials("postgres", "securepwd");
+        const result = await builder.deploy();
+        assert.strictEqual(result.name, "patch-db");
+        // Verify PATCH was called
+        const patchCalls = fetchCalls.filter((c) => c.method === "PATCH");
+        assert.strictEqual(patchCalls.length, 1);
+        assert.strictEqual(patchCalls[0].body.settings.tier, "db-custom-2-7680");
+        assert.strictEqual(patchCalls[0].body.settings.dataDiskSizeGb, "30");
+    });
+    test("skips patch if instance configuration is identical", async () => {
+        // 1. Mock GET (discovery) returns identical settings
+        mockResponses["GET /instances/ident-db"] = {
+            status: 200,
+            body: {
+                name: "ident-db",
+                connectionName: "my-gcp-project:us-central1:ident-db",
+                ipAddresses: [{ type: "PRIMARY", ipAddress: "35.200.10.20" }],
+                settings: {
+                    tier: "db-f1-micro",
+                    dataDiskSizeGb: "10",
+                    ipConfiguration: {
+                        authorizedNetworks: [],
+                    },
+                },
+            },
+        };
+        const builder = new GCPCloudSQLBuilder("ident-db")
+            .engine({ engine: "postgres", version: "16" })
+            .size("db-f1-micro")
+            .storage(10)
+            .credentials("postgres", "securepwd")
+            .publicAccess(false);
+        const result = await builder.deploy();
+        assert.strictEqual(result.name, "ident-db");
+        // Assert NO write calls for instances (POST or PATCH) occurred
+        const writeCalls = fetchCalls.filter((c) => c.method === "PATCH" ||
+            (c.method === "POST" && c.url.endsWith("/instances")));
+        assert.strictEqual(writeCalls.length, 0);
+    });
+    test("destroys an existing instance successfully", async () => {
+        // 1. Mock GET (discovery on destroy) returns existing instance
+        mockResponses["GET /instances/to-delete-db"] = {
+            status: 200,
+            body: {
+                name: "to-delete-db",
+                connectionName: "my-gcp-project:us-central1:to-delete-db",
+            },
+        };
+        // 2. Mock DELETE
+        mockResponses["DELETE /instances/to-delete-db"] = {
+            status: 200,
+            body: { name: "op-delete-123", status: "PENDING" },
+        };
+        // 3. Mock GET (poll operation status until DONE)
+        mockResponses["GET /operations/op-delete-123"] = {
+            status: 200,
+            body: { status: "DONE" },
+        };
+        const builder = new GCPCloudSQLBuilder("to-delete-db");
+        const result = await builder.destroy();
+        assert.deepStrictEqual(result, { destroyed: "to-delete-db" });
+        // Verify DELETE was called
+        const deleteCalls = fetchCalls.filter((c) => c.method === "DELETE");
+        assert.strictEqual(deleteCalls.length, 1);
+        assert.strictEqual(deleteCalls[0].url.includes("/instances/to-delete-db"), true);
+    });
+    test("destroy does nothing when instance does not exist", async () => {
+        // Mock GET returned 404
+        mockResponses["GET /instances/not-exist-db"] = {
+            status: 404,
+            body: { message: "Not found" },
+        };
+        const builder = new GCPCloudSQLBuilder("not-exist-db");
+        const result = await builder.destroy();
+        assert.deepStrictEqual(result, { destroyed: "not-exist-db" });
+        // Verify no DELETE was called
+        const deleteCalls = fetchCalls.filter((c) => c.method === "DELETE");
+        assert.strictEqual(deleteCalls.length, 0);
+    });
+});

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

@@ -0,0 +1,38 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+export declare class GCPServiceAccountBuilder extends BaseBuilder {
+    readonly out: {
+        email: Output<string>;
+        name: Output<string>;
+    };
+    private _displayName?;
+    private _description?;
+    constructor(accountId: string);
+    get email(): string;
+    displayName(name: string): this;
+    description(desc: string): this;
+    private discoverServiceAccount;
+    deploy(): Promise<{
+        email: string;
+        name: string;
+    }>;
+    destroy(): Promise<{
+        destroyed: string;
+    }>;
+}
+export declare class GCPIAMBindingBuilder extends BaseBuilder {
+    private _role;
+    private _members;
+    constructor(name: string);
+    role(name: string): this;
+    member(m: string | GCPServiceAccountBuilder | Output<string>): this;
+    members(...m: (string | GCPServiceAccountBuilder | Output<string>)[]): this;
+    private resolveMembers;
+    deploy(): Promise<{
+        role: string;
+        bound: string[];
+    }>;
+    destroy(): Promise<{
+        destroyed: string;
+    }>;
+}

package/dist/providers/gcp/iam.js

@@ -0,0 +1,309 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+import { gcpFetch, getProjectId } from "./api.js";
+const IAM_BASE = "https://iam.googleapis.com";
+const CRM_BASE = "https://cloudresourcemanager.googleapis.com";
+export class GCPServiceAccountBuilder extends BaseBuilder {
+    out = {
+        email: new Output(),
+        name: new Output(),
+    };
+    _displayName;
+    _description;
+    constructor(accountId) {
+        super(accountId);
+        this.discoveryPromise = this.discoverServiceAccount();
+    }
+    get email() {
+        const project = getProjectId();
+        return `${this.name}@${project}.iam.gserviceaccount.com`;
+    }
+    displayName(name) {
+        this._displayName = name;
+        return this;
+    }
+    description(desc) {
+        this._description = desc;
+        return this;
+    }
+    async discoverServiceAccount() {
+        try {
+            const project = getProjectId();
+            const sa = await gcpFetch(IAM_BASE, `/v1/projects/${project}/serviceAccounts/${this.email}`);
+            if (sa) {
+                this.out.email.resolve(this.email);
+                this.out.name.resolve(sa.name ?? `projects/${project}/serviceAccounts/${this.email}`);
+            }
+            return sa;
+        }
+        catch (e) {
+            if (e.message?.includes("404") ||
+                e.message?.includes("403") ||
+                e.message?.includes("credentials not configured")) {
+                return null;
+            }
+            throw e;
+        }
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const project = getProjectId();
+        const existing = await this.discoveryPromise;
+        console.log(`\n👤 Finalizing GCP Service Account "${this.name}"...`);
+        if (dryRun) {
+            if (existing) {
+                console.log(`   ✅ Service account "${this.name}" exists (email: ${this.email})`);
+                if (this._displayName || this._description) {
+                    console.log(`   📝 [PLAN] Update service account metadata`);
+                }
+            }
+            else {
+                console.log(`   📝 [PLAN] Create service account "${this.name}"`);
+            }
+            this.out.email.resolve(this.email);
+            this.out.name.resolve(`projects/${project}/serviceAccounts/${this.email}`);
+            return { email: this.email, name: `projects/${project}/serviceAccounts/${this.email}` };
+        }
+        if (!existing) {
+            console.log(`🚀 Creating GCP Service Account "${this.name}"...`);
+            const sa = await gcpFetch(IAM_BASE, `/v1/projects/${project}/serviceAccounts`, {
+                method: "POST",
+                body: JSON.stringify({
+                    accountId: this.name,
+                    serviceAccount: {
+                        displayName: this._displayName,
+                        description: this._description,
+                    },
+                }),
+            });
+            this.out.email.resolve(this.email);
+            this.out.name.resolve(sa.name ?? `projects/${project}/serviceAccounts/${this.email}`);
+            console.log(`   ✅ Service account created: ${this.email}`);
+        }
+        else {
+            console.log(`   ✅ Service account "${this.name}" exists`);
+            const needsUpdate = (this._displayName && existing.displayName !== this._displayName) ||
+                (this._description && existing.description !== this._description);
+            if (needsUpdate) {
+                console.log(`🔄 Updating GCP Service Account "${this.name}" metadata...`);
+                await gcpFetch(IAM_BASE, `/v1/projects/${project}/serviceAccounts/${this.email}`, {
+                    method: "PATCH",
+                    body: JSON.stringify({
+                        displayName: this._displayName,
+                        description: this._description,
+                    }),
+                });
+                console.log(`   ✅ Metadata updated.`);
+            }
+        }
+        await this.deploySidecars();
+        return {
+            email: this.email,
+            name: `projects/${project}/serviceAccounts/${this.email}`,
+        };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const project = getProjectId();
+        console.log(`\n🗑️  Destroying GCP Service Account "${this.name}"...`);
+        const existing = await this.discoverServiceAccount();
+        if (!existing) {
+            console.log(`   ✅ Service account "${this.name}" does not exist - nothing to do.`);
+            return { destroyed: this.name };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Delete service account "${this.name}" (${this.email})`);
+            return { destroyed: this.name };
+        }
+        await gcpFetch(IAM_BASE, `/v1/projects/${project}/serviceAccounts/${this.email}`, {
+            method: "DELETE",
+        });
+        console.log(`   ✅ Service account "${this.name}" deleted.`);
+        await this.destroySidecars();
+        return { destroyed: this.name };
+    }
+}
+export class GCPIAMBindingBuilder extends BaseBuilder {
+    _role;
+    _members = [];
+    constructor(name) {
+        super(name);
+        // Bindings are project-wide and dynamic, so discovery of project policy happens during deploy
+        this.discoveryPromise = Promise.resolve(null);
+    }
+    role(name) {
+        this._role = name;
+        return this;
+    }
+    member(m) {
+        this._members.push(m);
+        return this;
+    }
+    members(...m) {
+        this._members.push(...m);
+        return this;
+    }
+    async resolveMembers() {
+        const resolved = [];
+        for (const m of this._members) {
+            if (m instanceof GCPServiceAccountBuilder) {
+                resolved.push(`serviceAccount:${m.email}`);
+            }
+            else if (m instanceof Output) {
+                const val = await m.get();
+                resolved.push(val.includes(":") ? val : `serviceAccount:${val}`);
+            }
+            else {
+                const val = String(m);
+                if (val.includes(":")) {
+                    resolved.push(val);
+                }
+                else if (val.includes("@")) {
+                    if (val.endsWith(".gserviceaccount.com")) {
+                        resolved.push(`serviceAccount:${val}`);
+                    }
+                    else {
+                        resolved.push(`user:${val}`);
+                    }
+                }
+                else {
+                    const project = getProjectId();
+                    resolved.push(`serviceAccount:${val}@${project}.iam.gserviceaccount.com`);
+                }
+            }
+        }
+        return resolved;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const project = getProjectId();
+        console.log(`\n🔐 Finalizing GCP IAM Binding for Role "${this._role}"...`);
+        if (!this._role) {
+            throw new Error(`[GCP.IAMBinding:${this.name}] .role("...") is required`);
+        }
+        if (this._members.length === 0) {
+            throw new Error(`[GCP.IAMBinding:${this.name}] At least one member is required via .member()/.members()`);
+        }
+        const resolvedMembers = await this.resolveMembers();
+        // 1. Fetch current policy
+        let policy;
+        try {
+            policy = await gcpFetch(CRM_BASE, `/v1/projects/${project}:getIamPolicy`, {
+                method: "POST",
+                body: JSON.stringify({}),
+            });
+        }
+        catch (e) {
+            if (dryRun || e.message?.includes("credentials not configured")) {
+                policy = { bindings: [], etag: "DRYRUN_ETAG" };
+            }
+            else {
+                throw e;
+            }
+        }
+        const bindings = policy.bindings ?? [];
+        let binding = bindings.find((b) => b.role === this._role);
+        // 2. Compute members to add
+        const toAdd = [];
+        if (!binding) {
+            toAdd.push(...resolvedMembers);
+        }
+        else {
+            const existingMembers = binding.members ?? [];
+            for (const m of resolvedMembers) {
+                if (!existingMembers.includes(m)) {
+                    toAdd.push(m);
+                }
+            }
+        }
+        if (toAdd.length === 0) {
+            console.log(`   ✅ IAM binding for role "${this._role}" is up to date (members already bound)`);
+            return { role: this._role, bound: resolvedMembers };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Bind members [${toAdd.join(", ")}] to role "${this._role}"`);
+            return { role: this._role, bound: resolvedMembers };
+        }
+        // 3. Mutate policy safely
+        if (!binding) {
+            binding = { role: this._role, members: resolvedMembers };
+            bindings.push(binding);
+        }
+        else {
+            binding.members = [...(binding.members ?? []), ...toAdd];
+        }
+        policy.bindings = bindings;
+        // 4. Set updated policy with optimistic locking etag
+        await gcpFetch(CRM_BASE, `/v1/projects/${project}:setIamPolicy`, {
+            method: "POST",
+            body: JSON.stringify({
+                policy,
+            }),
+        });
+        console.log(`🚀 Successfully bound members [${toAdd.join(", ")}] to role "${this._role}"`);
+        await this.deploySidecars();
+        return {
+            role: this._role,
+            bound: resolvedMembers,
+        };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const project = getProjectId();
+        console.log(`\n🗑️  Removing GCP IAM Bindings for Role "${this._role}"...`);
+        if (!this._role) {
+            return { destroyed: this.name };
+        }
+        const resolvedMembers = await this.resolveMembers();
+        // 1. Fetch current policy
+        let policy;
+        try {
+            policy = await gcpFetch(CRM_BASE, `/v1/projects/${project}:getIamPolicy`, {
+                method: "POST",
+                body: JSON.stringify({}),
+            });
+        }
+        catch (e) {
+            if (dryRun || e.message?.includes("credentials not configured")) {
+                return { destroyed: this.name };
+            }
+            throw e;
+        }
+        const bindings = policy.bindings ?? [];
+        const binding = bindings.find((b) => b.role === this._role);
+        if (!binding) {
+            console.log(`   ✅ No bindings found for role "${this._role}" - nothing to do.`);
+            return { destroyed: this.name };
+        }
+        const existingMembers = binding.members ?? [];
+        const remaining = existingMembers.filter((m) => !resolvedMembers.includes(m));
+        const removed = existingMembers.filter((m) => resolvedMembers.includes(m));
+        if (removed.length === 0) {
+            console.log(`   ✅ Bound members already removed - nothing to do.`);
+            return { destroyed: this.name };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Remove members [${removed.join(", ")}] from role "${this._role}"`);
+            return { destroyed: this.name };
+        }
+        // 2. Safe removal
+        if (remaining.length === 0) {
+            // If no members left in this role, remove the role binding block completely
+            policy.bindings = bindings.filter((b) => b.role !== this._role);
+        }
+        else {
+            binding.members = remaining;
+            policy.bindings = bindings;
+        }
+        // 3. Set updated policy with etag
+        await gcpFetch(CRM_BASE, `/v1/projects/${project}:setIamPolicy`, {
+            method: "POST",
+            body: JSON.stringify({
+                policy,
+            }),
+        });
+        console.log(`   ✅ Removed members [${removed.join(", ")}] from role "${this._role}".`);
+        await this.destroySidecars();
+        return { destroyed: this.name };
+    }
+}

package/dist/providers/gcp/iam.test.d.ts

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