puls-dev 0.2.7 → 0.2.9

package/dist/providers/aws/api.js

@@ -15,26 +15,106 @@ import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
 import { CloudWatchClient } from "@aws-sdk/client-cloudwatch";
 import { SNSClient } from "@aws-sdk/client-sns";
 import { Config } from "../../core/config.js";
+import { withRetry } from "../../core/retry.js";
+import { resourceContextStorage } from "../../core/context.js";
 function getRegion() {
     const region = Config.get().providers.aws?.region;
-    if (!region)
+    if (!region) {
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return "us-east-1";
+        }
         throw new Error('AWS region not configured. Call AWS.init({ region: "..." })');
+    }
     return region;
 }
-export const getS3Client = (region) => new S3Client({ region: region ?? getRegion() });
+function createAwsOfflineMock(command) {
+    const name = command.constructor.name;
+    if (name.includes("RunInstances")) {
+        return {
+            Instances: [
+                {
+                    InstanceId: "i-mock1234567890abcdef0",
+                    State: { Name: "running" },
+                    PublicIpAddress: "54.210.12.34",
+                    PrivateIpAddress: "10.0.1.10",
+                }
+            ]
+        };
+    }
+    if (name.includes("CreateVpc")) {
+        return { Vpc: { VpcId: "vpc-mock123456" } };
+    }
+    if (name.includes("CreateSubnet")) {
+        return { Subnet: { SubnetId: "subnet-mock123456" } };
+    }
+    if (name.includes("CreateSecurityGroup")) {
+        return { GroupId: "sg-mock123456" };
+    }
+    if (name.includes("CreateBucket")) {
+        return { Location: "/mock-bucket" };
+    }
+    if (name.includes("CreateKeyPair")) {
+        return { KeyMaterial: "mock-private-key", KeyName: "mock-key" };
+    }
+    const mockProxy = new Proxy({}, {
+        get(target, prop) {
+            if (prop === "then")
+                return undefined;
+            if (prop === "CertificateArn")
+                return "arn:aws:acm:us-east-1:123456789012:certificate/mock-cert-uuid";
+            if (prop === "HostedZoneId")
+                return "Z2FDTNDATAQYW2";
+            if (prop === "Id" || prop === "id")
+                return "mock-id-12345";
+            if (prop === "Arn" || prop === "arn")
+                return `arn:aws:mock:::resource/mock-id`;
+            if (prop === "Status" || prop === "status")
+                return "Active";
+            if (prop === "DNSName")
+                return "mock.cloudfront.net";
+            if (prop.endsWith("s"))
+                return [];
+            return `mock-${prop.toLowerCase()}`;
+        }
+    });
+    return mockProxy;
+}
+function wrapClient(client) {
+    const originalSend = client.send;
+    client.send = function (command, options) {
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(createAwsOfflineMock(command));
+        }
+        const opts = abortSignal ? { abortSignal, ...options } : options;
+        return withRetry(() => originalSend.call(client, command, opts), {
+            retryable: (err) => {
+                const code = err.name || err.code;
+                const status = err.$metadata?.httpStatusCode;
+                return (code === "ThrottlingException" ||
+                    code === "ProvisionedThroughputExceededException" ||
+                    code === "RequestLimitExceeded" ||
+                    (status && status >= 500));
+            }
+        });
+    };
+    return client;
+}
+export const getS3Client = (region) => wrapClient(new S3Client({ region: region ?? getRegion() }));
 // CloudFront, Route53, ACM, Route53 Domains, and IAM are all global - must use us-east-1
-export const getCFClient = () => new CloudFrontClient({ region: "us-east-1" });
-export const getR53Client = () => new Route53Client({ region: "us-east-1" });
-export const getR53DomainsClient = () => new Route53DomainsClient({ region: "us-east-1" });
-export const getACMClient = () => new ACMClient({ region: "us-east-1" });
-export const getIAMClient = () => new IAMClient({ region: "us-east-1" });
-export const getLambdaClient = (region) => new LambdaClient({ region: region ?? getRegion() });
-export const getAPIGWClient = (region) => new ApiGatewayV2Client({ region: region ?? getRegion() });
-export const getECSClient = (region) => new ECSClient({ region: region ?? getRegion() });
-export const getEC2Client = (region) => new EC2Client({ region: region ?? getRegion() });
-export const getCWLogsClient = (region) => new CloudWatchLogsClient({ region: region ?? getRegion() });
-export const getRDSClient = (region) => new RDSClient({ region: region ?? getRegion() });
-export const getSQSClient = (region) => new SQSClient({ region: region ?? getRegion() });
-export const getSecretsClient = (region) => new SecretsManagerClient({ region: region ?? getRegion() });
-export const getCWClient = (region) => new CloudWatchClient({ region: region ?? getRegion() });
-export const getSNSClient = (region) => new SNSClient({ region: region ?? getRegion() });
+export const getCFClient = () => wrapClient(new CloudFrontClient({ region: "us-east-1" }));
+export const getR53Client = () => wrapClient(new Route53Client({ region: "us-east-1" }));
+export const getR53DomainsClient = () => wrapClient(new Route53DomainsClient({ region: "us-east-1" }));
+export const getACMClient = () => wrapClient(new ACMClient({ region: "us-east-1" }));
+export const getIAMClient = () => wrapClient(new IAMClient({ region: "us-east-1" }));
+export const getLambdaClient = (region) => wrapClient(new LambdaClient({ region: region ?? getRegion() }));
+export const getAPIGWClient = (region) => wrapClient(new ApiGatewayV2Client({ region: region ?? getRegion() }));
+export const getECSClient = (region) => wrapClient(new ECSClient({ region: region ?? getRegion() }));
+export const getEC2Client = (region) => wrapClient(new EC2Client({ region: region ?? getRegion() }));
+export const getCWLogsClient = (region) => wrapClient(new CloudWatchLogsClient({ region: region ?? getRegion() }));
+export const getRDSClient = (region) => wrapClient(new RDSClient({ region: region ?? getRegion() }));
+export const getSQSClient = (region) => wrapClient(new SQSClient({ region: region ?? getRegion() }));
+export const getSecretsClient = (region) => wrapClient(new SecretsManagerClient({ region: region ?? getRegion() }));
+export const getCWClient = (region) => wrapClient(new CloudWatchClient({ region: region ?? getRegion() }));
+export const getSNSClient = (region) => wrapClient(new SNSClient({ region: region ?? getRegion() }));

package/dist/providers/aws/ec2.d.ts

@@ -0,0 +1,51 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+import { EC2TemplateBuilder } from "./template.js";
+export declare class EC2VMBuilder extends BaseBuilder {
+    readonly out: {
+        ip: Output<string>;
+        id: Output<string>;
+    };
+    private _instanceType;
+    private _ami;
+    private _templateSource?;
+    private _keyName?;
+    private _subnetId?;
+    private _securityGroupIds?;
+    private _userData?;
+    private _sshPrivateKeyPath?;
+    private _provision;
+    private _forceConfigCheck;
+    private resolvedInstanceId?;
+    private resolvedIp?;
+    constructor(name: string);
+    instanceType(type: string): this;
+    ami(amiId: string): this;
+    fromTemplate(template: EC2TemplateBuilder): this;
+    keyName(name: string): this;
+    subnetId(id: string): this;
+    securityGroupIds(ids: string[]): this;
+    userData(data: string): this;
+    sshPrivateKey(path: string): this;
+    provision(...playbookPaths: (string | string[])[]): this;
+    forceConfigCheck(): this;
+    protected checkPort(ip: string, port: number): Promise<boolean>;
+    protected runProvisioner(ip: string, script: string): Promise<void>;
+    private discoverVM;
+    deploy(): Promise<{
+        name: string;
+        id: string;
+        ip?: undefined;
+    } | {
+        name: string;
+        id: string | undefined;
+        ip: string | undefined;
+    } | null>;
+    destroy(): Promise<{
+        destroyed: boolean;
+    } | {
+        destroyed: string;
+    }>;
+}
+export declare function parseAwsTagsForProvision(tags?: any[]): Record<string, string>;
+export declare function mergeAwsTagsForProvision(metadata: Record<string, string>): string;

package/dist/providers/aws/ec2.js

@@ -0,0 +1,331 @@
+import { DescribeInstancesCommand, RunInstancesCommand, TerminateInstancesCommand, StopInstancesCommand, StartInstancesCommand, ModifyInstanceAttributeCommand, CreateTagsCommand, } from "@aws-sdk/client-ec2";
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+import { getEC2Client } from "./api.js";
+import { checkPort, runProvisioner } from "../../core/provisioner.js";
+import { getFileHash } from "../proxmox/hash.js";
+import { resourceContextStorage } from "../../core/context.js";
+export class EC2VMBuilder extends BaseBuilder {
+    out = {
+        ip: new Output(),
+        id: new Output(),
+    };
+    _instanceType = "t3.micro";
+    _ami = "ami-0c55b159cbfafe1f0"; // Default standard Ubuntu 22.04 LTS in us-east-1
+    _templateSource;
+    _keyName;
+    _subnetId;
+    _securityGroupIds;
+    _userData;
+    _sshPrivateKeyPath;
+    _provision = [];
+    _forceConfigCheck = false;
+    resolvedInstanceId;
+    resolvedIp;
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverVM();
+    }
+    instanceType(type) {
+        this._instanceType = type;
+        return this;
+    }
+    ami(amiId) {
+        this._ami = amiId;
+        return this;
+    }
+    fromTemplate(template) {
+        this._templateSource = template;
+        this.dependsOn(template);
+        return this;
+    }
+    keyName(name) {
+        this._keyName = name;
+        return this;
+    }
+    subnetId(id) {
+        this._subnetId = id;
+        return this;
+    }
+    securityGroupIds(ids) {
+        this._securityGroupIds = ids;
+        return this;
+    }
+    userData(data) {
+        this._userData = data;
+        return this;
+    }
+    sshPrivateKey(path) {
+        this._sshPrivateKeyPath = path;
+        return this;
+    }
+    provision(...playbookPaths) {
+        this._provision.push(...playbookPaths.flat());
+        return this;
+    }
+    forceConfigCheck() {
+        this._forceConfigCheck = true;
+        return this;
+    }
+    async checkPort(ip, port) {
+        return checkPort(ip, port);
+    }
+    async runProvisioner(ip, script) {
+        if (!this._sshPrivateKeyPath) {
+            throw new Error(`[EC2VMBuilder:${this.name}] sshPrivateKey(path) is required to run playbook provisioning.`);
+        }
+        // Default user is 'ubuntu' for standard Ubuntu images on AWS EC2
+        return runProvisioner(ip, "ubuntu", this._sshPrivateKeyPath, script);
+    }
+    async discoverVM() {
+        try {
+            const client = getEC2Client();
+            const result = await client.send(new DescribeInstancesCommand({
+                Filters: [
+                    { Name: "tag:Name", Values: [this.name] },
+                    {
+                        Name: "instance-state-name",
+                        Values: ["pending", "running", "stopping", "stopped"],
+                    },
+                ],
+            }));
+            const reservation = result.Reservations?.[0];
+            const instance = reservation?.Instances?.[0];
+            if (instance) {
+                this.resolvedInstanceId = instance.InstanceId;
+                this.resolvedIp = instance.PublicIpAddress ?? instance.PrivateIpAddress ?? undefined;
+                if (instance.InstanceId)
+                    this.out.id.resolve(instance.InstanceId);
+                if (this.resolvedIp)
+                    this.out.ip.resolve(this.resolvedIp);
+            }
+            return instance ?? null;
+        }
+        catch (e) {
+            if (e.name === "CredentialsProviderError" ||
+                e.message?.includes("credentials not configured")) {
+                return null;
+            }
+            throw e;
+        }
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const client = getEC2Client();
+        const hasChanges = existing ? existing.InstanceType !== this._instanceType : true;
+        if (await this.checkProtection(hasChanges))
+            return null;
+        // Parse applied playbooks metadata from EC2 Tags
+        const appliedHashes = parseAwsTagsForProvision(existing?.Tags);
+        const declaredPlaybooksWithHashes = this._provision.map((p) => {
+            const baseName = p.split("/").pop() ?? p;
+            const slug = baseName.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+            return { path: p, slug, hash: getFileHash(p) };
+        });
+        const playbooksToRun = this._forceConfigCheck
+            ? declaredPlaybooksWithHashes
+            : declaredPlaybooksWithHashes.filter((p) => {
+                const appliedHash = appliedHashes[p.slug];
+                return !appliedHash || appliedHash !== p.hash;
+            });
+        const playbookRunRequired = playbooksToRun.length > 0;
+        if (dryRun) {
+            console.log(`\n🔍 [DRY RUN] AWS EC2 VM "${this.name}"...`);
+            if (!existing) {
+                const sourceLabel = this._templateSource ? `Template: ${this._templateSource.name}` : `AMI ${this._ami}`;
+                console.log(`   📝 Plan: Create AWS EC2 Instance`);
+                const details = [
+                    `Name:          ${this.name}`,
+                    `Instance Type: ${this._instanceType}`,
+                    `Source:        ${sourceLabel}`,
+                ];
+                if (this._provision.length > 0) {
+                    details.push(`Provision:     ${this._provision.join(", ")}`);
+                }
+                for (let i = 0; i < details.length; i++) {
+                    const prefix = i === details.length - 1 ? "      └─ " : "      ├─ ";
+                    console.log(`${prefix}${details[i]}`);
+                }
+                this.out.id.resolve("PENDING");
+                this.out.ip.resolve("0.0.0.0");
+            }
+            else if (hasChanges || playbookRunRequired) {
+                if (hasChanges) {
+                    console.log(`   📝 Plan: Stop, Resize, and Start EC2 VM ${this.name} (${existing.InstanceType} → ${this._instanceType})`);
+                }
+                if (playbookRunRequired) {
+                    console.log(`   📝 [PLAN] Run ${playbooksToRun.length} playbook changes on existing EC2 VM:`);
+                    for (const p of playbooksToRun) {
+                        console.log(`      └─ Playbook: ${p.path} (hash: ${p.hash})`);
+                    }
+                }
+            }
+            else {
+                console.log(`   ✅ AWS EC2 VM "${this.name}" is up to date.`);
+            }
+            return { name: this.name, id: this.resolvedInstanceId ?? "PENDING" };
+        }
+        console.log(`\n⏳ Finalizing AWS EC2 VM "${this.name}"...`);
+        if (!existing) {
+            const initialHashes = {};
+            for (const p of declaredPlaybooksWithHashes) {
+                initialHashes[p.slug] = p.hash;
+            }
+            const initialMetadataVal = mergeAwsTagsForProvision(initialHashes);
+            let activeAmi = this._ami;
+            if (this._templateSource) {
+                activeAmi = await this._templateSource.out.amiId.get();
+            }
+            console.log(`🚀 Creating AWS EC2 VM Instance "${this.name}"...`);
+            const result = await client.send(new RunInstancesCommand({
+                ImageId: activeAmi,
+                InstanceType: this._instanceType,
+                MinCount: 1,
+                MaxCount: 1,
+                KeyName: this._keyName,
+                SubnetId: this._subnetId,
+                SecurityGroupIds: this._securityGroupIds,
+                UserData: this._userData ? Buffer.from(this._userData).toString("base64") : undefined,
+                TagSpecifications: [
+                    {
+                        ResourceType: "instance",
+                        Tags: [
+                            { Key: "Name", Value: this.name },
+                            ...(initialMetadataVal ? [{ Key: "puls-provision", Value: initialMetadataVal }] : []),
+                        ],
+                    },
+                ],
+            }));
+            const instanceId = result.Instances?.[0]?.InstanceId;
+            if (!instanceId)
+                throw new Error("Failed to retrieve instance ID from RunInstancesCommand");
+            this.resolvedInstanceId = instanceId;
+            this.out.id.resolve(instanceId);
+            // Poll until instance is running and has an IP address
+            await this.waitFor(`AWS EC2 VM "${this.name}" to start running`, async () => {
+                const current = await this.discoverVM();
+                return current && current.State?.Name === "running" && !!this.resolvedIp;
+            }, { intervalMs: 10_000, timeoutMs: 300_000 });
+            console.log(`🚀 AWS EC2 VM "${this.name}" is now running.`);
+            if (this._provision.length > 0) {
+                const activeIp = this.resolvedIp ?? "0.0.0.0";
+                if (activeIp === "0.0.0.0") {
+                    throw new Error(`Failed to resolve IP for new AWS EC2 VM "${this.name}" to run playbooks`);
+                }
+                await this.waitFor(`SSH on ${activeIp} to be ready`, () => this.checkPort(activeIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
+                for (const playbook of this._provision) {
+                    await this.runProvisioner(activeIp, playbook);
+                }
+            }
+        }
+        else {
+            const instanceId = existing.InstanceId;
+            this.resolvedInstanceId = instanceId;
+            if (hasChanges) {
+                console.log(`✨ Resizing AWS EC2 VM ${this.name} (${existing.InstanceType} → ${this._instanceType})...`);
+                console.log(`   🔄 Stopping EC2 VM to perform resize...`);
+                await client.send(new StopInstancesCommand({ InstanceIds: [instanceId] }));
+                await this.waitFor(`VM "${this.name}" to stop`, async () => {
+                    const current = await this.discoverVM();
+                    return current && current.State?.Name === "stopped";
+                }, { intervalMs: 10_000, timeoutMs: 300_000 });
+                // Perform resize
+                await client.send(new ModifyInstanceAttributeCommand({
+                    InstanceId: instanceId,
+                    InstanceType: { Value: this._instanceType },
+                }));
+                // Restart VM
+                console.log(`   🔄 Restarting EC2 VM...`);
+                await client.send(new StartInstancesCommand({ InstanceIds: [instanceId] }));
+                await this.waitFor(`VM "${this.name}" to restart`, async () => {
+                    const current = await this.discoverVM();
+                    return current && current.State?.Name === "running" && !!this.resolvedIp;
+                }, { intervalMs: 10_000, timeoutMs: 300_000 });
+                console.log(`   ✅ AWS EC2 VM resized and restarted successfully.`);
+            }
+            if (playbookRunRequired) {
+                console.log(`   🔄 Running ${playbooksToRun.length} playbook changes on AWS EC2 VM...`);
+                const activeIp = this.resolvedIp ?? "0.0.0.0";
+                if (activeIp === "0.0.0.0") {
+                    throw new Error(`Failed to resolve IP for AWS EC2 VM "${this.name}" to run playbooks`);
+                }
+                await this.waitFor(`SSH on ${activeIp} to be ready`, () => this.checkPort(activeIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
+                for (const p of playbooksToRun) {
+                    await this.runProvisioner(activeIp, p.path);
+                    appliedHashes[p.slug] = p.hash;
+                }
+                // Update EC2 Tags with new hashes
+                const newValue = mergeAwsTagsForProvision(appliedHashes);
+                await client.send(new CreateTagsCommand({
+                    Resources: [instanceId],
+                    Tags: [{ Key: "puls-provision", Value: newValue }],
+                }));
+                console.log(`   ✅ Playbooks applied successfully and EC2 Tags updated.`);
+            }
+            if (!hasChanges && !playbookRunRequired) {
+                console.log(`   ✅ AWS EC2 VM "${this.name}" is up to date.`);
+            }
+        }
+        const context = resourceContextStorage.getStore();
+        if (context && context.hosts) {
+            const activeIp = this.resolvedIp ?? "0.0.0.0";
+            if (!context.hosts.some(h => h.name === this.name)) {
+                context.hosts.push({
+                    name: this.name,
+                    ip: activeIp,
+                    user: "ubuntu",
+                    sshKey: this._sshPrivateKeyPath,
+                    provider: "aws"
+                });
+            }
+        }
+        await this.deploySidecars();
+        return {
+            name: this.name,
+            id: this.resolvedInstanceId,
+            ip: this.resolvedIp,
+        };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const client = getEC2Client();
+        console.log(`\n🗑️  Destroying AWS EC2 VM "${this.name}"...`);
+        if (!existing) {
+            console.log(`   ─  AWS EC2 VM "${this.name}" not found`);
+            return { destroyed: false };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Delete AWS EC2 VM "${this.name}" (id=${existing.InstanceId})`);
+            return { destroyed: this.name };
+        }
+        console.log(`   🔄 Terminating AWS EC2 VM "${this.name}" (id=${existing.InstanceId})...`);
+        await client.send(new TerminateInstancesCommand({ InstanceIds: [existing.InstanceId] }));
+        console.log(`   🗑️  Removed AWS EC2 VM "${this.name}"`);
+        await this.destroySidecars();
+        return { destroyed: this.name };
+    }
+}
+export function parseAwsTagsForProvision(tags) {
+    const tag = (tags ?? []).find((t) => t.Key === "puls-provision");
+    if (!tag?.Value)
+        return {};
+    const record = {};
+    const entries = tag.Value.split(",");
+    for (const entry of entries) {
+        const parts = entry.trim().split("=");
+        if (parts.length === 2) {
+            const [name, hash] = parts;
+            if (name && hash) {
+                record[name.trim()] = hash.trim();
+            }
+        }
+    }
+    return record;
+}
+export function mergeAwsTagsForProvision(metadata) {
+    return Object.entries(metadata)
+        .map(([name, hash]) => `${name}=${hash}`)
+        .join(",");
+}

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

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