stacktape 3.5.7 → 3.6.0-beta.0

package/ai-docs/config-ref/astro-web.md

@@ -0,0 +1,115 @@
+---
+docType: config-ref
+title: Astro Web
+resourceType: astro-web
+tags:
+  - astro-web
+  - astro
+  - astro.js
+source: types/stacktape-config/astro-web.d.ts
+priority: 1
+---
+
+# Astro Web
+
+Deploy an Astro SSR app with Lambda for server rendering, S3 for static assets, and CloudFront CDN.
+
+For static-only Astro sites, use `hosting-bucket` with `hostingContentType: 'astro-static-website'` instead.
+
+Resource type: `astro-web`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Deploy an Astro SSR app with Lambda for server rendering, S3 for static assets, and CloudFront CDN.
+ *
+ * ---
+ *
+ * For static-only Astro sites, use `hosting-bucket` with `hostingContentType: 'astro-static-website'` instead.
+ */
+interface AstroWeb {
+  type: 'astro-web';
+  properties: AstroWebProps;
+  overrides?: ResourceOverrides;
+}
+
+interface AstroWebProps extends ResourceAccessProps {
+  /**
+   * #### Directory containing your `astro.config.mjs`. For monorepos, point to the Astro workspace.
+   *
+   * @default "."
+   */
+  appDirectory?: string;
+  /**
+   * #### Override the default `astro build` command.
+   */
+  buildCommand?: string;
+  /**
+   * #### Environment variables for the SSR function. Use `$ResourceParam()` or `$Secret()` for dynamic values.
+   */
+  environment?: EnvironmentVar[];
+  /**
+   * #### Attach custom domains with auto-managed DNS records and TLS certificates.
+   *
+   * ---
+   *
+   * **Prerequisite:** A Route 53 hosted zone for your domain must exist in your AWS account.
+   */
+  customDomains?: DomainConfiguration[];
+  /**
+   * #### Customize the SSR Lambda function (memory, timeout, VPC, logging).
+   */
+  serverLambda?: AstroWebServerLambdaConfig;
+  /**
+   * #### Name of a `web-app-firewall` resource to protect this app. Firewall `scope` must be `cdn`.
+   */
+  useFirewall?: string;
+  /**
+   * #### Dev server config for `stacktape dev`. Defaults to `astro dev`.
+   */
+  dev?: AstroWebDevConfig;
+  /**
+   * #### Set custom headers (e.g., `Cache-Control`) for static files matching a pattern.
+   */
+  fileOptions?: DirectoryUploadFilter[];
+  /**
+   * #### CDN cache controls for SSR routes and specific path patterns.
+   */
+  cdn?: SsrWebCdnConfig;
+}
+
+interface AstroWebServerLambdaConfig {
+  /**
+   * #### Memory in MB (128–10,240). CPU scales proportionally — 1,769 MB = 1 vCPU.
+   *
+   * @default 1024
+   */
+  memory?: number;
+  /**
+   * #### Max execution time in seconds. Max: 30.
+   *
+   * @default 30
+   */
+  timeout?: number;
+  /**
+   * #### Connect to VPC resources (databases, Redis). **Warning:** function loses direct internet access.
+   */
+  joinDefaultVpc?: boolean;
+  /**
+   * #### Logging config. Logs are sent to CloudWatch. View with `stacktape logs` or in the AWS console.
+   */
+  logging?: LambdaFunctionLogging;
+}
+
+interface AstroWebDevConfig {
+  /**
+   * #### Override the default `astro dev` command (e.g., `npm run dev`).
+   */
+  command?: string;
+  /**
+   * #### Working directory for the dev command, relative to project root.
+   */
+  workingDirectory?: string;
+}
+```

package/ai-docs/config-ref/aws-cdk-construct.md

@@ -0,0 +1,68 @@
+---
+docType: config-ref
+title: Aws Cdk Construct
+resourceType: aws-cdk-construct
+tags:
+  - aws-cdk-construct
+  - cdk
+  - construct
+source: types/stacktape-config/aws-cdk-construct.d.ts
+priority: 1
+---
+
+# Aws Cdk Construct
+
+Embed an AWS CDK construct directly in your Stacktape stack.
+
+Escape hatch for resources not natively supported by Stacktape. Write a CDK construct class
+in TypeScript/JavaScript and Stacktape will synthesize and deploy it as part of your stack.
+
+Resource type: `aws-cdk-construct`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Embed an AWS CDK construct directly in your Stacktape stack.
+ *
+ * ---
+ *
+ * Escape hatch for resources not natively supported by Stacktape. Write a CDK construct class
+ * in TypeScript/JavaScript and Stacktape will synthesize and deploy it as part of your stack.
+ */
+interface AwsCdkConstruct {
+  type: 'aws-cdk-construct';
+  properties?: AwsCdkConstructProps;
+  //   overrides?: ResourceOverrides;
+}
+
+interface AwsCdkConstructProps {
+  /**
+   * #### Path to the file containing your CDK construct class.
+   *
+   * ---
+   *
+   * Supports `.js` and `.ts` files. The file must export a class that extends `Construct` from `aws-cdk-lib`.
+   */
+  entryfilePath: string;
+  /**
+   * #### Name of the exported construct class from the entry file.
+   *
+   * ---
+   *
+   * Must match the exact export name. Use this when the file has multiple exports or uses named exports.
+   *
+   * @default "default"
+   */
+  exportName?: string;
+  /**
+   * #### Custom props passed to the construct's constructor.
+   *
+   * ---
+   *
+   * This object is forwarded as the third argument (`props`) to your construct class. Use `$ResourceParam()` and `$Secret()`
+   * directives here to pass dynamic values from other resources in your stack.
+   */
+  constructProperties?: any;
+}
+```

package/ai-docs/config-ref/bastion.md

@@ -0,0 +1,93 @@
+---
+docType: config-ref
+title: Bastion
+resourceType: bastion
+tags:
+  - bastion
+  - jump-host
+  - ssh
+source: types/stacktape-config/bastion.d.ts
+priority: 1
+---
+
+# Bastion
+
+Secure jump box for accessing private resources (databases, Redis, OpenSearch) in your VPC.
+
+Uses keyless SSH via AWS Systems Manager — no SSH keys to manage. Connect with `stacktape bastion:ssh`
+or create port-forwarding tunnels with `stacktape bastion:tunnel`. Costs ~$4/month (t3.micro).
+
+Resource type: `bastion`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Secure jump box for accessing private resources (databases, Redis, OpenSearch) in your VPC.
+ *
+ * ---
+ *
+ * Uses keyless SSH via AWS Systems Manager — no SSH keys to manage. Connect with `stacktape bastion:ssh`
+ * or create port-forwarding tunnels with `stacktape bastion:tunnel`. Costs ~$4/month (t3.micro).
+ */
+interface Bastion {
+  type: 'bastion';
+  properties?: BastionProps;
+  overrides?: ResourceOverrides;
+}
+
+interface BastionProps {
+  /**
+   * #### EC2 instance type. `t3.micro` is sufficient for SSH tunneling and basic admin tasks.
+   *
+   * @default t3.micro
+   */
+  instanceSize?: string;
+  /**
+   * #### Shell commands to run when the instance starts (as root — no `sudo` needed).
+   *
+   * ---
+   *
+   * Use to install CLI tools, database clients, or other dependencies.
+   * **Warning:** changing this list after creation replaces the instance — any data on the old instance is lost.
+   */
+  runCommandsAtLaunch?: string[];
+  /**
+   * #### Log retention settings for system, security, and audit logs. Logs are sent to CloudWatch.
+   */
+  logging?: BastionLoggingConfig;
+}
+
+interface BastionLoggingConfig {
+  /**
+   * #### System messages (`/var/log/messages`) — startup info, kernel messages, service logs.
+   *
+   * @default retentionDays: 30
+   */
+  messages?: BastionLogging;
+  /**
+   * #### Auth logs (`/var/log/secure`) — SSH login attempts, authentication events.
+   *
+   * @default retentionDays: 180
+   */
+  secure?: BastionLogging;
+  /**
+   * #### Audit logs (`/var/log/audit/audit.log`) — detailed security events from the Linux audit system.
+   *
+   * @default retentionDays: 365
+   */
+  audit?: BastionLogging;
+}
+
+interface BastionLogging extends LogForwardingBase {
+  /**
+   * #### Disable this log type. Stops sending to CloudWatch.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * #### Days to keep logs in CloudWatch before automatic deletion.
+   */
+  retentionDays?: 1 | 3 | 5 | 7 | 14 | 30 | 60 | 90 | 120 | 150 | 180 | 365 | 400 | 545 | 731 | 1827 | 3653;
+}
+```

package/ai-docs/config-ref/batch-job.md

@@ -0,0 +1,179 @@
+---
+docType: config-ref
+title: Batch Job
+resourceType: batch-job
+tags:
+  - batch-job
+  - batch
+  - job
+  - scheduled-job
+source: types/stacktape-config/batch-jobs.d.ts
+priority: 1
+---
+
+# Batch Job
+
+Run containerized tasks to completion — data processing, ML training, video encoding, etc.
+
+Pay only for the compute time used. Supports CPU and GPU workloads, retries on failure,
+and can be triggered by schedules, HTTP requests, S3 uploads, or queue messages.
+
+Resource type: `batch-job`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Run containerized tasks to completion — data processing, ML training, video encoding, etc.
+ *
+ * ---
+ *
+ * Pay only for the compute time used. Supports CPU and GPU workloads, retries on failure,
+ * and can be triggered by schedules, HTTP requests, S3 uploads, or queue messages.
+ */
+interface BatchJob {
+  type: 'batch-job';
+  properties: BatchJobProps;
+  overrides?: ResourceOverrides;
+}
+
+interface BatchJobProps extends ResourceAccessProps {
+  /**
+   * #### Docker container image and environment for the job.
+   */
+  container: BatchJobContainer;
+  /**
+   * #### CPU, memory, and GPU requirements. AWS auto-provisions a matching instance.
+   */
+  resources: BatchJobResources;
+  /**
+   * #### Max run time in seconds. The job is killed if it exceeds this, then retried if `retryConfig` is set.
+   */
+  timeout?: number;
+  /**
+   * #### Use discounted spare AWS capacity. Saves up to 90%, but jobs can be interrupted.
+   *
+   * ---
+   *
+   * **Use this when:** Your job can safely be restarted from the beginning (e.g., data imports,
+   * image processing, ML training with checkpoints). Combine with `retryConfig` to auto-retry
+   * on interruption.
+   *
+   * **Don't use when:** Your job has side effects that can't be repeated (e.g., sending emails,
+   * charging payments) or must finish within a strict deadline.
+   *
+   * If interrupted, your container gets a `SIGTERM` and 120 seconds to shut down gracefully.
+   *
+   * @default false
+   */
+  useSpotInstances?: boolean;
+  /**
+   * #### Container logging (stdout/stderr). Sent to CloudWatch, viewable with `stacktape logs`.
+   */
+  logging?: BatchJobLogging;
+  /**
+   * #### Auto-retry on failure, timeout, or Spot interruption.
+   */
+  retryConfig?: BatchJobRetryConfiguration;
+  /**
+   * #### Events that trigger this job (schedules, HTTP requests, S3 uploads, SQS messages, etc.).
+   */
+  events?: (
+    | HttpApiIntegration
+    | S3Integration
+    | ScheduleIntegration
+    | SnsIntegration
+    | SqsIntegration
+    | KinesisIntegration
+    | DynamoDbIntegration
+    | CloudwatchLogIntegration
+    | ApplicationLoadBalancerIntegration
+    | EventBusIntegration
+  )[];
+}
+
+interface BatchJobRetryConfiguration {
+  /**
+   * #### Max retry attempts before the job is marked as failed.
+   * @default 1
+   */
+  attempts?: number;
+  /**
+   * #### Seconds to wait between retries.
+   * @default 0
+   */
+  retryIntervalSeconds?: number;
+  /**
+   * #### Multiply wait time by this factor after each retry (exponential backoff).
+   *
+   * ---
+   *
+   * E.g., with `retryIntervalSeconds: 5` and `retryIntervalMultiplier: 2`, waits are 5s, 10s, 20s, etc.
+   *
+   * @default 1
+   */
+  retryIntervalMultiplier?: number;
+}
+
+interface BatchJobContainer {
+  /**
+   * #### How to build or specify the container image for this job.
+   */
+  packaging: BatchJobContainerPackaging;
+  /**
+   * #### Environment variables injected into the container at runtime.
+   *
+   * ---
+   *
+   * Use `$ResourceParam()` or `$Secret()` to inject database URLs, API keys, etc.
+   */
+  environment?: EnvironmentVar[];
+}
+
+interface BatchJobResources {
+  /**
+   * #### Number of vCPUs for the job (e.g., 1, 2, 4).
+   */
+  cpu: number;
+  /**
+   * #### Memory in MB. Use slightly less than powers of 2 for efficient instance sizing.
+   *
+   * ---
+   *
+   * AWS reserves some memory for system processes. Requesting exactly 8192 MB (8 GB) may provision
+   * a larger instance than needed. Use 7680 MB instead to fit on a standard 8 GB instance.
+   */
+  memory: number;
+  /**
+   * #### Number of GPUs. The job will run on a GPU instance (NVIDIA A100, A10G, etc.).
+   *
+   * ---
+   *
+   * Omit for CPU-only workloads.
+   */
+  gpu?: number;
+  /**
+   * #### A list of specific EC2 instance types to use for the job.
+   * ---
+   * By default, Stacktape allows AWS to select an optimal instance type based on your resource requirements.
+   * You can override this by providing a list of allowed instance types.
+   * For a full list, see the [AWS EC2 instance types documentation](https://aws.amazon.com/ec2/instance-types/).
+   */
+  // instanceTypes?: string[];
+}
+
+interface BatchJobLogging extends LogForwardingBase {
+  /**
+   * #### Disable logging to CloudWatch.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * #### How many days to keep logs.
+   * @default 90
+   */
+  retentionDays?: 1 | 3 | 5 | 7 | 14 | 30 | 60 | 90 | 120 | 150 | 180 | 365 | 400 | 545 | 731 | 1827 | 3653;
+}
+
+type BatchJobReferencableParam = 'jobDefinitionArn' | 'stateMachineArn' | 'logGroupArn';
+```