@skippercorp/skipper 1.0.1

package/src/command/aws/cloudformation.ts

@@ -0,0 +1,243 @@
+import {
+  CloudFormationClient,
+  CreateStackCommand,
+  DescribeStackEventsCommand,
+  DescribeStacksCommand,
+  type Output,
+  type StackEvent,
+  UpdateStackCommand,
+} from "@aws-sdk/client-cloudformation";
+
+const SUCCESS_STATES = new Set(["CREATE_COMPLETE", "UPDATE_COMPLETE"]);
+const FAILURE_STATES = new Set([
+  "CREATE_FAILED",
+  "ROLLBACK_COMPLETE",
+  "ROLLBACK_FAILED",
+  "DELETE_FAILED",
+  "UPDATE_ROLLBACK_FAILED",
+  "UPDATE_ROLLBACK_COMPLETE",
+  "UPDATE_FAILED",
+]);
+
+export type DeployStackInput = {
+  client: CloudFormationClient;
+  stackName: string;
+  templateBody: string;
+  parameters: Record<string, string>;
+  timeoutMinutes: number;
+  tags?: Record<string, string>;
+};
+
+export type DeployStackResult = {
+  action: "create" | "update" | "noop";
+  status: string;
+  outputs: Output[];
+};
+
+/**
+ * Classify CloudFormation stack status.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+export function classifyStackStatus(status: string):
+  | "success"
+  | "failure"
+  | "in-progress" {
+  if (SUCCESS_STATES.has(status)) return "success";
+  if (FAILURE_STATES.has(status)) return "failure";
+  return "in-progress";
+}
+
+/**
+ * Create or update stack and wait for terminal status.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+export async function deployStack(
+  input: DeployStackInput,
+): Promise<DeployStackResult> {
+  const exists = await stackExists(input.client, input.stackName);
+
+  if (!exists) {
+    await input.client.send(
+      new CreateStackCommand({
+        StackName: input.stackName,
+        TemplateBody: input.templateBody,
+        Parameters: toCfnParameters(input.parameters),
+        Tags: toCfnTags(input.tags),
+        Capabilities: ["CAPABILITY_NAMED_IAM"],
+      }),
+    );
+
+    const status = await waitForTerminalStatus(
+      input.client,
+      input.stackName,
+      input.timeoutMinutes,
+    );
+    const outputs = await getOutputs(input.client, input.stackName);
+    return { action: "create", status, outputs };
+  }
+
+  const current = await getStackStatus(input.client, input.stackName);
+  if (current.endsWith("_IN_PROGRESS")) {
+    throw new Error(`Stack ${input.stackName} currently ${current}`);
+  }
+
+  try {
+    await input.client.send(
+      new UpdateStackCommand({
+        StackName: input.stackName,
+        TemplateBody: input.templateBody,
+        Parameters: toCfnParameters(input.parameters),
+        Tags: toCfnTags(input.tags),
+        Capabilities: ["CAPABILITY_NAMED_IAM"],
+      }),
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("No updates are to be performed")) {
+      const outputs = await getOutputs(input.client, input.stackName);
+      return { action: "noop", status: current, outputs };
+    }
+    throw error;
+  }
+
+  const status = await waitForTerminalStatus(
+    input.client,
+    input.stackName,
+    input.timeoutMinutes,
+  );
+  const outputs = await getOutputs(input.client, input.stackName);
+  return { action: "update", status, outputs };
+}
+
+/**
+ * Build short failure summary from stack events.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+export async function getFailureSummary(
+  client: CloudFormationClient,
+  stackName: string,
+): Promise<string[]> {
+  const res = await client.send(
+    new DescribeStackEventsCommand({ StackName: stackName }),
+  );
+
+  const events = (res.StackEvents ?? [])
+    .filter((event: StackEvent) => {
+      const status = event.ResourceStatus ?? "";
+      return status.includes("FAILED") || status.includes("ROLLBACK");
+    })
+    .slice(0, 10)
+    .map((event: StackEvent) => {
+      const id = event.LogicalResourceId ?? "unknown";
+      const status = event.ResourceStatus ?? "unknown";
+      const reason = event.ResourceStatusReason ?? "no reason";
+      return `${id}: ${status} - ${reason}`;
+    });
+
+  return events;
+}
+
+/**
+ * Check if stack already exists.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+async function stackExists(
+  client: CloudFormationClient,
+  stackName: string,
+): Promise<boolean> {
+  try {
+    await client.send(new DescribeStacksCommand({ StackName: stackName }));
+    return true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("does not exist")) return false;
+    throw error;
+  }
+}
+
+/**
+ * Read stack status value.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+async function getStackStatus(
+  client: CloudFormationClient,
+  stackName: string,
+): Promise<string> {
+  const res = await client.send(new DescribeStacksCommand({ StackName: stackName }));
+  const stack = res.Stacks?.[0];
+  if (!stack?.StackStatus) throw new Error(`Cannot read stack status: ${stackName}`);
+  return stack.StackStatus;
+}
+
+/**
+ * Poll until stack reaches terminal status.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+async function waitForTerminalStatus(
+  client: CloudFormationClient,
+  stackName: string,
+  timeoutMinutes: number,
+): Promise<string> {
+  const deadline = Date.now() + timeoutMinutes * 60_000;
+  while (Date.now() < deadline) {
+    const status = await getStackStatus(client, stackName);
+    const kind = classifyStackStatus(status);
+    if (kind === "success") return status;
+    if (kind === "failure") {
+      throw new Error(`Stack failed: ${status}`);
+    }
+    await Bun.sleep(5000);
+  }
+  throw new Error(`Timed out waiting for stack ${stackName}`);
+}
+
+/**
+ * Read stack outputs list.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+async function getOutputs(
+  client: CloudFormationClient,
+  stackName: string,
+): Promise<Output[]> {
+  const res = await client.send(new DescribeStacksCommand({ StackName: stackName }));
+  const stack = res.Stacks?.[0];
+  return stack?.Outputs ?? [];
+}
+
+/**
+ * Convert parameters map to CloudFormation list.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+function toCfnParameters(parameters: Record<string, string>) {
+  return Object.entries(parameters).map(([ParameterKey, ParameterValue]) => ({
+    ParameterKey,
+    ParameterValue,
+  }));
+}
+
+/**
+ * Convert tags map to CloudFormation list.
+ *
+ * @since 1.0.0
+ * @category AWS.CloudFormation
+ */
+function toCfnTags(tags?: Record<string, string>) {
+  if (!tags) return undefined;
+  return Object.entries(tags).map(([Key, Value]) => ({ Key, Value }));
+}

package/src/command/aws/defaults.ts

@@ -0,0 +1,103 @@
+import { basename } from "node:path";
+
+const DEFAULT_ENV = "sandbox";
+const DEFAULT_REGION = "us-east-1";
+
+export type DeployDefaults = {
+  service: string;
+  env: string;
+  region: string;
+};
+
+/**
+ * Resolve default deploy inputs from cwd + env.
+ *
+ * @since 1.0.0
+ * @category AWS.Defaults
+ */
+export function resolveDeployDefaults(
+  cwd = process.cwd(),
+  env: Record<string, string | undefined> = process.env,
+): DeployDefaults {
+  const service =
+    toSimpleName(env.SKIPPER_AWS_SERVICE ?? "") ||
+    toSimpleName(basename(cwd)) ||
+    "skipper";
+  const deployEnv =
+    toSimpleName(env.SKIPPER_AWS_ENV ?? "") ||
+    toSimpleName(env.AWS_PROFILE ?? "") ||
+    DEFAULT_ENV;
+  const region = env.AWS_REGION ?? env.AWS_DEFAULT_REGION ?? DEFAULT_REGION;
+  return { service, env: deployEnv, region };
+}
+
+/**
+ * Validate simple slug-like value.
+ *
+ * @since 1.0.0
+ * @category AWS.Defaults
+ */
+export function isSimpleName(value: string): boolean {
+  return /^[a-zA-Z0-9-]+$/.test(value);
+}
+
+/**
+ * Parse webhook events CSV.
+ *
+ * @since 1.0.0
+ * @category AWS.Defaults
+ */
+export function parseGithubEvents(value?: string): string[] {
+  if (!value || value.trim().length === 0) return ["*"];
+  const events = value
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  if (events.length === 0) return ["*"];
+  for (const event of events) {
+    if (!/^[a-z0-9_*.-]+$/i.test(event)) {
+      throw new Error(`invalid github event: ${event}`);
+    }
+  }
+  return events;
+}
+
+/**
+ * Parse stack tags CSV.
+ *
+ * @since 1.0.0
+ * @category AWS.Defaults
+ */
+export function parseTags(value?: string): Record<string, string> | undefined {
+  if (!value) return undefined;
+  const entries = value
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  if (entries.length === 0) return undefined;
+  const tags: Record<string, string> = {};
+  for (const entry of entries) {
+    const [key, ...rest] = entry.split("=");
+    const cleanKey = key?.trim();
+    const cleanValue = rest.join("=").trim();
+    if (!cleanKey || cleanValue.length === 0) {
+      throw new Error(`invalid tag: ${entry}`);
+    }
+    tags[cleanKey] = cleanValue;
+  }
+  return tags;
+}
+
+/**
+ * Normalize value into simple name.
+ *
+ * @since 1.0.0
+ * @category AWS.Defaults
+ */
+function toSimpleName(value: string): string {
+  return value
+    .trim()
+    .replace(/[^a-zA-Z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/--+/g, "-");
+}

package/src/command/aws/deploy-template.ts

@@ -0,0 +1,308 @@
+import { createHash } from "node:crypto";
+import {
+  listWorkerChunkParameterKeys,
+  WORKERS_CHUNK_COUNT_PARAM,
+  WORKERS_ENCODING_PARAM,
+  WORKERS_SCHEMA_VERSION_PARAM,
+  WORKERS_SHA256_PARAM,
+} from "../../worker/aws-params.js";
+import type { WorkerGithubEventSubscription } from "../../worker/github-events.js";
+
+type JsonMap = Record<string, unknown>;
+
+export type BuildDeployTemplateInput = {
+  workerSubscriptions: WorkerGithubEventSubscription[];
+};
+
+/**
+ * Build repo-scoped deploy template JSON string.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+export function buildDeployTemplate(input: BuildDeployTemplateInput): string {
+  const workerSubscriptions = [...input.workerSubscriptions].sort((left, right) =>
+    left.workerId.localeCompare(right.workerId),
+  );
+  const template = {
+    AWSTemplateFormatVersion: "2010-09-09",
+    Description: "Skipper repository-scoped EventBridge subscription",
+    Parameters: buildParameters(),
+    Resources: buildResources(workerSubscriptions),
+    Outputs: buildOutputs(workerSubscriptions),
+  };
+  return JSON.stringify(template, null, 2);
+}
+
+/**
+ * Build deploy template parameters.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function buildParameters(): JsonMap {
+  const parameters: JsonMap = {
+    ServiceName: { Type: "String" },
+    Environment: { Type: "String" },
+    RepositoryFullName: { Type: "String" },
+    RepositoryPrefix: { Type: "String" },
+    EventBusName: { Type: "String" },
+    EventSource: { Type: "String" },
+    EventDetailType: { Type: "String" },
+    EcsClusterArn: { Type: "String" },
+    EcsTaskDefinitionArn: { Type: "String" },
+    EcsSecurityGroupId: { Type: "String" },
+    EcsSubnetIdsCsv: { Type: "String" },
+    EcsTaskExecutionRoleArn: { Type: "String" },
+    EcsTaskRoleArn: { Type: "String" },
+    WebhookSecretParameterName: { Type: "String" },
+    GitHubToken: { Type: "String", Default: "", NoEcho: true },
+    LambdaCodeS3Bucket: { Type: "String" },
+    LambdaCodeS3Key: { Type: "String" },
+    [WORKERS_ENCODING_PARAM]: { Type: "String", Default: "" },
+    [WORKERS_SHA256_PARAM]: { Type: "String", Default: "" },
+    [WORKERS_SCHEMA_VERSION_PARAM]: { Type: "String", Default: "1" },
+    [WORKERS_CHUNK_COUNT_PARAM]: { Type: "Number", Default: 0 },
+  };
+  for (const key of listWorkerChunkParameterKeys()) {
+    parameters[key] = { Type: "String", Default: "" };
+  }
+  return parameters;
+}
+
+/**
+ * Build deploy template resources.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function buildResources(workerSubscriptions: WorkerGithubEventSubscription[]): JsonMap {
+  const resources: JsonMap = {
+    ...buildSharedResources(),
+  };
+  for (const subscription of workerSubscriptions) {
+    Object.assign(resources, buildWorkerResources(subscription));
+  }
+  return resources;
+}
+
+/**
+ * Build resources shared by all worker Lambda subscriptions.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function buildSharedResources(): JsonMap {
+  return {
+    RepositoryWorkerLambdaRole: {
+      Type: "AWS::IAM::Role",
+      Properties: {
+        AssumeRolePolicyDocument: {
+          Version: "2012-10-17",
+          Statement: [
+            {
+              Effect: "Allow",
+              Principal: { Service: "lambda.amazonaws.com" },
+              Action: "sts:AssumeRole",
+            },
+          ],
+        },
+        Policies: [
+          {
+            PolicyName: "repository-worker-lambda",
+            PolicyDocument: {
+              Version: "2012-10-17",
+              Statement: [
+                {
+                  Effect: "Allow",
+                  Action: ["logs:CreateLogStream", "logs:PutLogEvents"],
+                  Resource: {
+                    "Fn::Sub":
+                      "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/*:*",
+                  },
+                },
+                {
+                  Effect: "Allow",
+                  Action: ["ecs:RunTask"],
+                  Resource: { Ref: "EcsTaskDefinitionArn" },
+                },
+                {
+                  Effect: "Allow",
+                  Action: ["iam:PassRole"],
+                  Resource: [{ Ref: "EcsTaskExecutionRoleArn" }, { Ref: "EcsTaskRoleArn" }],
+                  Condition: {
+                    StringEquals: {
+                      "iam:PassedToService": "ecs-tasks.amazonaws.com",
+                    },
+                  },
+                },
+                {
+                  Effect: "Allow",
+                  Action: ["cloudformation:DescribeStacks"],
+                  Resource: {
+                    "Fn::Sub":
+                      "arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${AWS::StackName}/*",
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  };
+}
+
+/**
+ * Build resources for one worker-specific Lambda subscription.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function buildWorkerResources(subscription: WorkerGithubEventSubscription): JsonMap {
+  const eventNames = subscription.events
+    .map((event) => event.trim())
+    .filter((event) => event.length > 0);
+  if (eventNames.length === 0) {
+    return {};
+  }
+  const logicalPrefix = buildWorkerLogicalId(subscription.workerId);
+  const logGroupLogicalId = `${logicalPrefix}LambdaLogGroup`;
+  const lambdaLogicalId = `${logicalPrefix}LambdaFunction`;
+  const eventRuleLogicalId = `${logicalPrefix}EventRule`;
+  const permissionLogicalId = `${logicalPrefix}LambdaInvokePermission`;
+  const targetId = `worker-${sha1Suffix(subscription.workerId).slice(0, 12)}`;
+  return {
+    [logGroupLogicalId]: {
+      Type: "AWS::Logs::LogGroup",
+      Properties: {
+        LogGroupName: {
+          "Fn::Sub": `/aws/lambda/\${${lambdaLogicalId}}`,
+        },
+        RetentionInDays: 14,
+      },
+    },
+    [lambdaLogicalId]: {
+      Type: "AWS::Lambda::Function",
+      Properties: {
+        Runtime: "nodejs20.x",
+        Handler: "index.handler",
+        Role: { "Fn::GetAtt": ["RepositoryWorkerLambdaRole", "Arn"] },
+        Timeout: 30,
+        MemorySize: 512,
+        Code: {
+          S3Bucket: { Ref: "LambdaCodeS3Bucket" },
+          S3Key: { Ref: "LambdaCodeS3Key" },
+        },
+        Environment: {
+          Variables: {
+            ECS_CLUSTER_ARN: { Ref: "EcsClusterArn" },
+            ECS_TASK_DEFINITION_ARN: { Ref: "EcsTaskDefinitionArn" },
+            ECS_SECURITY_GROUP_ID: { Ref: "EcsSecurityGroupId" },
+            ECS_SUBNET_IDS: { Ref: "EcsSubnetIdsCsv" },
+            WORKERS_STACK_NAME: { Ref: "AWS::StackName" },
+            WORKERS_ENCODING: { Ref: WORKERS_ENCODING_PARAM },
+            WORKERS_SHA256: { Ref: WORKERS_SHA256_PARAM },
+            WORKERS_SCHEMA_VERSION: { Ref: WORKERS_SCHEMA_VERSION_PARAM },
+            WORKERS_CHUNK_COUNT: {
+              "Fn::Join": ["", [{ Ref: WORKERS_CHUNK_COUNT_PARAM }]],
+            },
+            WEBHOOK_SECRET: {
+              "Fn::Sub":
+                "{{resolve:ssm:${WebhookSecretParameterName}}}",
+            },
+            GITHUB_TOKEN: { Ref: "GitHubToken" },
+            SKIPPER_WORKER_ID: subscription.workerId,
+          },
+        },
+      },
+    },
+    [eventRuleLogicalId]: {
+      Type: "AWS::Events::Rule",
+      Properties: {
+        Description: `Skipper worker ${subscription.workerId} repository subscription`,
+        EventBusName: { Ref: "EventBusName" },
+        State: "ENABLED",
+        EventPattern: {
+          source: [{ Ref: "EventSource" }],
+          "detail-type": [{ Ref: "EventDetailType" }],
+          detail: {
+            repository: {
+              full_name: [{ Ref: "RepositoryFullName" }],
+            },
+            headers: {
+              "x-github-event": eventNames,
+            },
+          },
+        },
+        Targets: [
+          {
+            Arn: { "Fn::GetAtt": [lambdaLogicalId, "Arn"] },
+            Id: targetId,
+          },
+        ],
+      },
+    },
+    [permissionLogicalId]: {
+      Type: "AWS::Lambda::Permission",
+      Properties: {
+        FunctionName: { Ref: lambdaLogicalId },
+        Action: "lambda:InvokeFunction",
+        Principal: "events.amazonaws.com",
+        SourceArn: { "Fn::GetAtt": [eventRuleLogicalId, "Arn"] },
+      },
+    },
+  };
+}
+
+/**
+ * Build deploy template outputs.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function buildOutputs(workerSubscriptions: WorkerGithubEventSubscription[]): JsonMap {
+  return {
+    RepositoryFullName: { Value: { Ref: "RepositoryFullName" } },
+    WorkerSubscriptionCount: {
+      Value: String(workerSubscriptions.length),
+    },
+  };
+}
+
+/**
+ * Build stable CloudFormation logical id prefix from worker id.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function buildWorkerLogicalId(workerId: string): string {
+  const base = toPascalCase(workerId).slice(0, 40);
+  return `Worker${base}${sha1Suffix(workerId).slice(0, 8)}`;
+}
+
+/**
+ * Convert kebab/slug string to PascalCase alnum value.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function toPascalCase(value: string): string {
+  const parts = value.split(/[^a-zA-Z0-9]+/).filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return "Worker";
+  }
+  return parts
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1).toLowerCase()}`)
+    .join("");
+}
+
+/**
+ * Build stable sha1 hex suffix.
+ *
+ * @since 1.0.0
+ * @category AWS.DeployTemplate
+ */
+function sha1Suffix(value: string): string {
+  return createHash("sha1").update(value).digest("hex");
+}