puls-dev 0.1.0

package/dist/providers/aws/route53.js

@@ -0,0 +1,218 @@
+import { ListHostedZonesByNameCommand, CreateHostedZoneCommand, ChangeResourceRecordSetsCommand, } from '@aws-sdk/client-route-53';
+import { RegisterDomainCommand, GetOperationDetailCommand, CheckDomainAvailabilityCommand, } from '@aws-sdk/client-route-53-domains';
+import { BaseBuilder } from '../../core/resource.js';
+import { Output } from '../../core/output.js';
+import { ACMCertificateBuilder } from './acm.js';
+import { getR53Client, getR53DomainsClient } from './api.js';
+export class Route53Builder extends BaseBuilder {
+    out = {
+        zone: new Output(),
+    };
+    zoneName;
+    zoneId;
+    records = [];
+    _isRegistering = false;
+    _registrantContact;
+    _wantsWildcardSSL = false;
+    constructor(zoneName = '') {
+        super(zoneName || 'route53-pending');
+        this.zoneName = zoneName;
+        this.discoveryPromise = this.discoverZone(zoneName);
+    }
+    async discoverZone(name) {
+        if (!name)
+            return null;
+        try {
+            const r53 = getR53Client();
+            const result = await r53.send(new ListHostedZonesByNameCommand({ DNSName: name, MaxItems: 5 }));
+            const match = (result.HostedZones ?? []).find(z => z.Name === `${name}.`);
+            if (match) {
+                this.zoneId = match.Id.replace('/hostedzone/', '');
+                return match;
+            }
+            return null;
+        }
+        catch (e) {
+            if (e.name === 'CredentialsProviderError')
+                return null;
+            throw e;
+        }
+    }
+    randomDomain() {
+        const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+        const id = Array.from({ length: 12 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+        this.zoneName = `${id}.com`;
+        this.name = this.zoneName;
+        this.discoveryPromise = this.discoverZone(this.zoneName);
+        return this;
+    }
+    cert() {
+        return this.sidecars.find(s => s instanceof ACMCertificateBuilder);
+    }
+    withWildcardSSL() {
+        this._wantsWildcardSSL = true;
+        return this;
+    }
+    register(contact) {
+        this._isRegistering = true;
+        this._registrantContact = contact;
+        return this;
+    }
+    record(name, type, value) {
+        this.records.push({ name, type, value });
+        return this;
+    }
+    pointer(name, target) {
+        this.records.push({ name, type: 'A', value: target, isAlias: true });
+        return this;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const r53 = getR53Client();
+        console.log(`\n🗺️  Finalizing Route53 Zone "${this.zoneName}"...`);
+        // Register domain first so NS records are publicly resolvable before cert validation
+        if (this._isRegistering) {
+            await this.registerDomain(dryRun);
+        }
+        if (!existing) {
+            if (dryRun) {
+                console.log(`   📝 [PLAN] Create hosted zone ${this.zoneName}`);
+                this.out.zone.resolve({ name: this.zoneName, id: 'PENDING' });
+            }
+            else {
+                // Route53 Domains auto-creates the hosted zone on registration — check again before creating
+                const recheck = await this.discoverZone(this.zoneName);
+                if (!recheck) {
+                    const result = await r53.send(new CreateHostedZoneCommand({
+                        Name: this.zoneName,
+                        CallerReference: `puls-${Date.now()}`,
+                    }));
+                    this.zoneId = result.HostedZone.Id.replace('/hostedzone/', '');
+                    console.log(`🚀 Created hosted zone ${this.zoneName} (id=${this.zoneId})`);
+                }
+                else {
+                    console.log(`   ✅ Hosted zone ${this.zoneName} created by domain registration (id=${this.zoneId})`);
+                }
+            }
+        }
+        else {
+            console.log(`   ✅ Hosted zone ${this.zoneName} exists (id=${this.zoneId})`);
+        }
+        if (this.zoneId)
+            this.out.zone.resolve({ name: this.zoneName, id: this.zoneId });
+        if (this._wantsWildcardSSL && !this.cert()) {
+            this.sidecars.push(new ACMCertificateBuilder(this.zoneName, true));
+        }
+        const cert = this.cert();
+        if (cert) {
+            cert.forZone(this); // zoneId is set by now — cert writes its own validation CNAMEs
+            await cert.deploy();
+        }
+        // Regular records
+        if (this.records.length > 0 && !dryRun && this.zoneId) {
+            const resolved = this.records.map(r => ({
+                type: r.type,
+                name: r.name,
+                value: r.value instanceof BaseBuilder ? `[alias: ${r.value.name}]` : r.value,
+            }));
+            await this.upsertRecords(r53, resolved.map(r => ({ ...r, ttl: 300 })));
+        }
+        for (const rec of this.records) {
+            const val = rec.value instanceof BaseBuilder ? `[Alias to ${rec.value.name}]` : rec.value;
+            console.log(`   ✅ [${dryRun ? 'PLAN' : 'OK'}] ${rec.type}: ${rec.name}.${this.zoneName} → ${val}`);
+        }
+        return { zone: this.zoneName, id: this.zoneId };
+    }
+    async registerDomain(dryRun) {
+        const domains = getR53DomainsClient();
+        const c = this._registrantContact;
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Register domain ${this.zoneName} via Route53 Domains`);
+            if (c)
+                console.log(`      └─ Registrant: ${c.FIRSTNAME} ${c.LASTNAME} <${c.EMAIL}>`);
+            return;
+        }
+        // Check availability before attempting registration
+        const avail = await domains.send(new CheckDomainAvailabilityCommand({ DomainName: this.zoneName }));
+        if (avail.Availability !== 'AVAILABLE') {
+            console.log(`   ℹ️  Domain ${this.zoneName} is not available for registration (${avail.Availability}) — skipping`);
+            return;
+        }
+        const contact = c ? this.mapContact(c) : undefined;
+        if (!contact)
+            throw new Error(`register() called without contact details — provide a RegistrantContact`);
+        console.log(`   📋 Registering domain ${this.zoneName}... (est. ~5 min)`);
+        const result = await domains.send(new RegisterDomainCommand({
+            DomainName: this.zoneName,
+            DurationInYears: 1,
+            AutoRenew: true,
+            AdminContact: contact,
+            RegistrantContact: contact,
+            TechContact: contact,
+            PrivacyProtectAdminContact: true,
+            PrivacyProtectRegistrantContact: true,
+            PrivacyProtectTechContact: true,
+        }));
+        console.log(`🚀 Domain registration submitted (operationId=${result.OperationId})`);
+        await this.waitFor(`domain "${this.zoneName}" to become active`, async () => {
+            const op = await domains.send(new GetOperationDetailCommand({ OperationId: result.OperationId }));
+            if (op.Status === 'ERROR' || op.Status === 'FAILED') {
+                throw new Error(`Domain registration failed (${op.Status}): ${op.Message}`);
+            }
+            return op.Status === 'SUCCESSFUL';
+        }, { intervalMs: 15_000, timeoutMs: 900_000 });
+        console.log(`   ✅ Domain ${this.zoneName} registered`);
+    }
+    mapContact(c) {
+        return {
+            FirstName: c.FIRSTNAME,
+            LastName: c.LASTNAME,
+            Email: c.EMAIL,
+            PhoneNumber: this.normalizePhone(c.MOBILE),
+            ContactType: c.CONTACT_TYPE,
+            OrganizationName: c.ORGANIZATION,
+            AddressLine1: c.ADDRESSLINE,
+            City: c.CITY,
+            ZipCode: c.ZIPCODE,
+            CountryCode: c.COUNTRY,
+        };
+    }
+    // Route53 Domains requires +CC.subscriber format (e.g. +46.708339809)
+    normalizePhone(phone) {
+        if (phone.includes('.'))
+            return phone;
+        const digits = phone.replace(/^\+/, '');
+        // +1 (US/CA) and +7 (RU/KZ) are single-digit country codes
+        if (digits.startsWith('1') || digits.startsWith('7')) {
+            return `+${digits[0]}.${digits.slice(1)}`;
+        }
+        // Default: treat first 2 digits as country code
+        return `+${digits.slice(0, 2)}.${digits.slice(2)}`;
+    }
+    async upsertCnames(records) {
+        if (!this.zoneId)
+            throw new Error(`Zone ${this.zoneName} has no ID — was it deployed?`);
+        const r53 = getR53Client();
+        await this.upsertRecords(r53, records.map(r => ({ type: 'CNAME', name: `${r.name}.${this.zoneName}`, value: r.value, ttl: 300 })));
+        for (const r of records) {
+            console.log(`   ✅ CNAME ${r.name}.${this.zoneName} → ${r.value}`);
+        }
+    }
+    async upsertRecords(r53, records) {
+        await r53.send(new ChangeResourceRecordSetsCommand({
+            HostedZoneId: this.zoneId,
+            ChangeBatch: {
+                Changes: records.map(r => ({
+                    Action: 'UPSERT',
+                    ResourceRecordSet: {
+                        Name: r.name,
+                        Type: r.type,
+                        TTL: r.ttl,
+                        ResourceRecords: [{ Value: r.value }],
+                    },
+                })),
+            },
+        }));
+    }
+}

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

@@ -0,0 +1,20 @@
+import { BaseBuilder } from '../../core/resource.js';
+import { CloudFrontBuilder } from './cloudfront.js';
+export declare class S3BucketBuilder extends BaseBuilder {
+    bucketName: string;
+    private _versioning;
+    private _allowedDistributions;
+    private _region?;
+    private _uploadPath?;
+    constructor(bucketName: string);
+    region(r: string): this;
+    private discoverBucket;
+    versioning(enabled?: boolean): this;
+    allowFrom(...distributions: CloudFrontBuilder[]): this;
+    upload(filePath: string): this;
+    deploy(): Promise<{
+        name: string;
+    }>;
+    private uploadFile;
+    private updateBucketPolicy;
+}

package/dist/providers/aws/s3.js

@@ -0,0 +1,165 @@
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { HeadBucketCommand, CreateBucketCommand, GetBucketPolicyCommand, PutBucketPolicyCommand, PutObjectCommand, } from '@aws-sdk/client-s3';
+import { BaseBuilder } from '../../core/resource.js';
+import { getS3Client } from './api.js';
+import { Config } from '../../core/config.js';
+export class S3BucketBuilder extends BaseBuilder {
+    bucketName;
+    _versioning = false;
+    _allowedDistributions = [];
+    _region;
+    _uploadPath;
+    constructor(bucketName) {
+        super(bucketName);
+        this.bucketName = bucketName;
+        this.discoveryPromise = this.discoverBucket(bucketName);
+    }
+    region(r) {
+        this._region = r;
+        this.discoveryPromise = this.discoverBucket(this.bucketName);
+        return this;
+    }
+    async discoverBucket(name) {
+        try {
+            await getS3Client(this._region).send(new HeadBucketCommand({ Bucket: name }));
+            return true;
+        }
+        catch (e) {
+            const status = e.$metadata?.httpStatusCode;
+            if (status === 404 || e.name === 'NotFound')
+                return false;
+            if (status === 301 || status === 403)
+                return true; // exists in different region or access denied
+            if (e.name === 'CredentialsProviderError')
+                return false;
+            throw e;
+        }
+    }
+    versioning(enabled = true) {
+        this._versioning = enabled;
+        return this;
+    }
+    allowFrom(...distributions) {
+        this._allowedDistributions.push(...distributions);
+        return this;
+    }
+    upload(filePath) {
+        this._uploadPath = filePath;
+        return this;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const exists = await this.discoveryPromise;
+        const region = this._region ?? Config.get().providers.aws?.region ?? 'us-east-1';
+        const s3 = getS3Client(region);
+        console.log(`\n🪣  Finalizing S3 Bucket "${this.bucketName}"...`);
+        if (!exists) {
+            if (dryRun) {
+                console.log(`   📝 [PLAN] Create bucket ${this.bucketName} (${region})`);
+            }
+            else {
+                const createCmd = { Bucket: this.bucketName };
+                if (region !== 'us-east-1') {
+                    createCmd.CreateBucketConfiguration = { LocationConstraint: region };
+                }
+                await s3.send(new CreateBucketCommand(createCmd));
+                console.log(`🚀 Created bucket ${this.bucketName}`);
+            }
+        }
+        else {
+            console.log(`   ✅ Bucket ${this.bucketName} already exists.`);
+        }
+        if (this._allowedDistributions.length > 0) {
+            const unresolved = this._allowedDistributions.filter(d => !d.resolvedArn);
+            if (unresolved.length > 0) {
+                throw new Error(`[S3:${this.bucketName}] allowFrom() has unresolved distributions: ` +
+                    unresolved.map(d => `"${d.name}"`).join(', ') +
+                    '. Declare the bucket after all CloudFront distributions in your Stack.');
+            }
+            const newArns = this._allowedDistributions.map(d => d.resolvedArn);
+            if (dryRun) {
+                console.log(`   📝 [PLAN] Append ${newArns.length} CloudFront OAC ARN(s) to bucket policy`);
+                for (const arn of newArns)
+                    console.log(`      └─ ${arn}`);
+            }
+            else {
+                await this.updateBucketPolicy(s3, newArns);
+            }
+        }
+        if (this._uploadPath) {
+            if (dryRun) {
+                console.log(`   📝 [PLAN] Upload ${basename(this._uploadPath)} → s3://${this.bucketName}/`);
+            }
+            else {
+                await this.uploadFile(s3, this._uploadPath);
+            }
+        }
+        await this.deploySidecars();
+        return { name: this.bucketName };
+    }
+    async uploadFile(s3, filePath) {
+        const key = basename(filePath);
+        const body = readFileSync(filePath);
+        const contentTypeMap = {
+            '.json': 'application/json',
+            '.js': 'application/javascript',
+            '.html': 'text/html',
+            '.css': 'text/css',
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.svg': 'image/svg+xml',
+        };
+        const contentType = contentTypeMap[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+        await s3.send(new PutObjectCommand({
+            Bucket: this.bucketName,
+            Key: key,
+            Body: body,
+            ContentType: contentType,
+        }));
+        console.log(`   ✅ Uploaded ${key} → s3://${this.bucketName}/${key}`);
+    }
+    async updateBucketPolicy(s3, newArns) {
+        let policy = { Version: '2012-10-17', Statement: [] };
+        try {
+            const existing = await s3.send(new GetBucketPolicyCommand({ Bucket: this.bucketName }));
+            if (existing.Policy)
+                policy = JSON.parse(existing.Policy);
+        }
+        catch (e) {
+            if (e.name !== 'NoSuchBucketPolicy')
+                throw e;
+        }
+        // Find any existing CloudFront-principal statement regardless of Sid
+        let stmt = policy.Statement.find((s) => s.Principal?.Service === 'cloudfront.amazonaws.com' && s.Effect === 'Allow');
+        if (!stmt) {
+            stmt = {
+                Sid: 'AllowCloudFrontServicePrincipal',
+                Effect: 'Allow',
+                Principal: { Service: 'cloudfront.amazonaws.com' },
+                Action: 's3:GetObject',
+                Resource: `arn:aws:s3:::${this.bucketName}/*`,
+                Condition: { StringEquals: { 'AWS:SourceArn': [] } },
+            };
+            policy.Statement.push(stmt);
+        }
+        // Condition key may be 'aws:SourceArn' or 'AWS:SourceArn' depending on how it was created
+        const cond = stmt.Condition?.StringEquals ?? {};
+        const sourceArnKey = Object.keys(cond).find(k => k.toLowerCase() === 'aws:sourcearn') ?? 'AWS:SourceArn';
+        if (!stmt.Condition)
+            stmt.Condition = { StringEquals: {} };
+        if (!stmt.Condition.StringEquals)
+            stmt.Condition.StringEquals = {};
+        const existing = stmt.Condition.StringEquals[sourceArnKey];
+        const existingArns = Array.isArray(existing) ? existing : existing ? [existing] : [];
+        const merged = [...new Set([...existingArns, ...newArns])];
+        stmt.Condition.StringEquals[sourceArnKey] = merged;
+        await s3.send(new PutBucketPolicyCommand({
+            Bucket: this.bucketName,
+            Policy: JSON.stringify(policy),
+        }));
+        console.log(`   ✅ Updated bucket policy — ${merged.length} distribution ARN(s) allowed`);
+        for (const arn of newArns)
+            console.log(`      └─ ${arn}`);
+    }
+}

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

@@ -0,0 +1,25 @@
+import { BaseBuilder } from "../../core/resource.js";
+export declare class SecretsBuilder extends BaseBuilder {
+    private _value?;
+    private _description?;
+    private _forceDelete;
+    private _pendingDeletion;
+    resolvedValue: string | null;
+    resolvedArn: string | null;
+    constructor(secretId: string);
+    private fetchSecret;
+    awaitValue(): Promise<string | null>;
+    plainText(v: string): this;
+    keyValue(obj: object): this;
+    description(d: string): this;
+    forceDelete(): this;
+    deploy(): Promise<{
+        name: string;
+        arn: string | null;
+        value: string | null;
+    }>;
+    destroy(): Promise<{
+        destroyed: string;
+    }>;
+}
+export declare function resolveEnvVars(env: Record<string, string | SecretsBuilder>): Promise<Record<string, string>>;

package/dist/providers/aws/secrets.js

@@ -0,0 +1,151 @@
+import { GetSecretValueCommand, CreateSecretCommand, PutSecretValueCommand, DeleteSecretCommand, } from "@aws-sdk/client-secrets-manager";
+import { BaseBuilder } from "../../core/resource.js";
+import { getSecretsClient } from "./api.js";
+export class SecretsBuilder extends BaseBuilder {
+    _value;
+    _description;
+    _forceDelete = false;
+    _pendingDeletion = false;
+    resolvedValue = null;
+    resolvedArn = null;
+    constructor(secretId) {
+        super(secretId);
+        this.discoveryPromise = this.fetchSecret(secretId);
+    }
+    async fetchSecret(secretId) {
+        try {
+            const result = await getSecretsClient().send(new GetSecretValueCommand({ SecretId: secretId }));
+            this.resolvedValue = result.SecretString ?? null;
+            this.resolvedArn = result.ARN ?? null;
+            return result;
+        }
+        catch (e) {
+            if (e.name === "ResourceNotFoundException")
+                return null;
+            if (e.name === "CredentialsProviderError")
+                return null;
+            if (e.name === "InvalidRequestException") {
+                this._pendingDeletion = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    // Awaits eager discovery — used by resolveEnvVars so callers don't need discoveryPromise directly
+    async awaitValue() {
+        await this.discoveryPromise;
+        return this.resolvedValue;
+    }
+    plainText(v) {
+        this._value = v;
+        return this;
+    }
+    keyValue(obj) {
+        this._value = JSON.stringify(obj);
+        return this;
+    }
+    description(d) {
+        this._description = d;
+        return this;
+    }
+    forceDelete() {
+        this._forceDelete = true;
+        return this;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const client = getSecretsClient();
+        console.log(`\n🔐 Finalizing Secret "${this.name}"...`);
+        if (dryRun) {
+            if (existing) {
+                console.log(`   ✅ Secret "${this.name}" exists`);
+                if (this.resolvedValue !== null)
+                    console.log(`   💬 Value: ${this.resolvedValue}`);
+                if (this._value)
+                    console.log(`   📝 [PLAN] Update secret value`);
+            }
+            else {
+                console.log(`   📝 [PLAN] Create secret "${this.name}"`);
+                if (this._description)
+                    console.log(`      └─ Description: ${this._description}`);
+            }
+            return { name: this.name, arn: this.resolvedArn, value: this.resolvedValue };
+        }
+        if (!existing) {
+            if (!this._value) {
+                console.log(`   ⚠️  Secret "${this.name}" does not exist — add .plainText() or .keyValue() to create it`);
+                return { name: this.name, arn: null, value: null };
+            }
+            const result = await client.send(new CreateSecretCommand({
+                Name: this.name,
+                SecretString: this._value,
+                Description: this._description,
+            }));
+            this.resolvedArn = result.ARN ?? null;
+            this.resolvedValue = this._value;
+            console.log(`🚀 Created secret "${this.name}"`);
+        }
+        else {
+            console.log(`   ✅ Secret "${this.name}" exists`);
+            if (this.resolvedValue !== null)
+                console.log(`   💬 Value: ${this.resolvedValue}`);
+            if (this._value && this._value !== this.resolvedValue) {
+                await client.send(new PutSecretValueCommand({
+                    SecretId: this.name,
+                    SecretString: this._value,
+                }));
+                this.resolvedValue = this._value;
+                console.log(`   ✅ Updated secret value`);
+            }
+        }
+        await this.deploySidecars();
+        return { name: this.name, arn: this.resolvedArn, value: this.resolvedValue };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        console.log(`\n🗑️  Destroying Secret "${this.name}"...`);
+        if (!existing) {
+            if (this._pendingDeletion)
+                console.log(`   ⏳ Secret "${this.name}" is already scheduled for deletion`);
+            else
+                console.log(`   ✅ Secret "${this.name}" does not exist — nothing to do`);
+            return { destroyed: this.name };
+        }
+        if (dryRun) {
+            const mode = this._forceDelete
+                ? "immediate"
+                : "scheduled (30-day recovery window)";
+            console.log(`   📝 [PLAN] Delete secret "${this.name}" — ${mode}`);
+            return { destroyed: this.name };
+        }
+        await getSecretsClient().send(new DeleteSecretCommand({
+            SecretId: this.name,
+            ForceDeleteWithoutRecovery: this._forceDelete,
+            ...(this._forceDelete ? {} : { RecoveryWindowInDays: 30 }),
+        }));
+        const mode = this._forceDelete
+            ? "immediately"
+            : "scheduled for deletion (30-day recovery window)";
+        console.log(`   ✅ Secret "${this.name}" ${mode}`);
+        return { destroyed: this.name };
+    }
+}
+// Resolve a mix of plain strings and SecretsBuilders into plain strings.
+// Called at deploy time in Lambda and Fargate, after all discoveryPromises have settled.
+export async function resolveEnvVars(env) {
+    const resolved = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (v instanceof SecretsBuilder) {
+            await v.awaitValue();
+            if (v.resolvedValue === null)
+                throw new Error(`Secret "${v.name}" has no value — create it first or call .plainText()/.keyValue() in the stack`);
+            resolved[k] = v.resolvedValue;
+        }
+        else {
+            resolved[k] = v;
+        }
+    }
+    return resolved;
+}

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

@@ -0,0 +1,33 @@
+import { BaseBuilder } from '../../core/resource.js';
+export declare class SQSBuilder extends BaseBuilder {
+    private _fifo;
+    private _deduplication;
+    private _visibilityTimeout;
+    private _retentionDays;
+    private _delaySeconds;
+    private _dlqName?;
+    private _dlqMaxReceives;
+    resolvedUrl: string | null;
+    resolvedArn: string | null;
+    resolvedDlqUrl: string | null;
+    resolvedDlqArn: string | null;
+    constructor(name: string);
+    fifo(enabled?: boolean): this;
+    deduplication(enabled?: boolean): this;
+    timeout(seconds: number): this;
+    retention(days: number): this;
+    delay(seconds: number): this;
+    dlq(name: string, maxReceives?: number): this;
+    private queueName;
+    private discoverQueue;
+    private ensureQueue;
+    private buildAttributes;
+    deploy(): Promise<{
+        name: string;
+        url: string | null;
+        arn: string | null;
+    }>;
+    destroy(): Promise<{
+        destroyed: string;
+    }>;
+}