stacktape 3.5.7 → 3.6.0-beta.0

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

@@ -0,0 +1,81 @@
+---
+docType: config-ref
+title: Nuxt Web
+resourceType: nuxt-web
+tags:
+  - nuxt-web
+  - nuxt
+  - nuxt.js
+source: types/stacktape-config/nuxt-web.d.ts
+priority: 1
+---
+
+# Nuxt Web
+
+Deploy a Nuxt SSR app with Lambda (Nitro aws-lambda preset), S3 for static assets, and CloudFront CDN.
+
+For static-only Nuxt sites, use `hosting-bucket` with `hostingContentType: 'nuxt-static-website'` instead.
+
+Resource type: `nuxt-web`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Deploy a Nuxt SSR app with Lambda (Nitro aws-lambda preset), S3 for static assets, and CloudFront CDN.
+ *
+ * ---
+ *
+ * For static-only Nuxt sites, use `hosting-bucket` with `hostingContentType: 'nuxt-static-website'` instead.
+ */
+interface NuxtWeb {
+  type: 'nuxt-web';
+  properties: NuxtWebProps;
+  overrides?: ResourceOverrides;
+}
+
+interface NuxtWebProps extends ResourceAccessProps {
+  /**
+   * #### Directory containing your `nuxt.config.ts`. For monorepos, point to the Nuxt workspace.
+   *
+   * @default "."
+   */
+  appDirectory?: string;
+  /**
+   * #### Override the default `nuxt 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?: SsrWebServerLambdaConfig;
+  /**
+   * #### 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 `nuxt dev`.
+   */
+  dev?: SsrWebDevConfig;
+  /**
+   * #### 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;
+}
+```

package/ai-docs/config-ref/open-search.md

@@ -0,0 +1,206 @@
+---
+docType: config-ref
+title: Open Search Domain
+resourceType: open-search
+tags:
+  - open-search
+  - opensearch
+  - elasticsearch
+  - elastic
+source: types/stacktape-config/open-search.d.ts
+priority: 1
+---
+
+# Open Search Domain
+
+Managed search and analytics engine (OpenSearch/Elasticsearch compatible).
+
+Full-text search, log analytics, and real-time dashboards. Use for search features in your app,
+centralized logging, or time-series data analysis. Costs start at ~$50/month (single small node).
+
+Resource type: `open-search`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Managed search and analytics engine (OpenSearch/Elasticsearch compatible).
+ *
+ * ---
+ *
+ * Full-text search, log analytics, and real-time dashboards. Use for search features in your app,
+ * centralized logging, or time-series data analysis. Costs start at ~$50/month (single small node).
+ */
+interface OpenSearchDomain {
+  type: 'open-search-domain'; // open-search?
+  properties?: OpenSearchDomainProps;
+  overrides?: ResourceOverrides;
+}
+
+interface OpenSearchDomainProps {
+  /**
+   * #### OpenSearch engine version. Pin this to avoid surprises when the default changes.
+   *
+   * @default '2.17'
+   */
+  version?: '2.17' | '2.15' | '2.13' | '2.11' | '2.9' | '2.7' | '2.5' | '2.3' | '1.3' | '1.2' | '1.1' | '1.0';
+  /**
+   * #### Instance types, counts, and cluster topology (data nodes, master nodes, warm storage).
+   *
+   * ---
+   *
+   * Defaults to a single `m4.large.search` node if not specified.
+   */
+  clusterConfig?: OpenSearchClusterConfig;
+  /**
+   * #### EBS volume size, IOPS, and throughput per data node. Only for EBS-backed instance types.
+   *
+   * ---
+   *
+   * `iops` and `throughput` settings only apply to GP3 volumes.
+   */
+  storage?: OpenSearchStorage;
+  /**
+   * #### Name of a `user-pool` resource in your config. Enables login to OpenSearch Dashboards via Cognito.
+   */
+  userPool?: string;
+  /**
+   * #### Error logs, search slow logs, and indexing slow logs. Sent to CloudWatch automatically.
+   */
+  logging?: OpenSearchLogConfiguration;
+  /**
+   * #### Network access mode: public internet (default), VPC-only, or VPC with security-group scoping.
+   *
+   * ---
+   *
+   * Even in `internet` mode, access requires IAM credentials. VPC modes add network-level isolation.
+   * **Warning:** you cannot switch between `internet` and `vpc`/`scoping-workloads-in-vpc` after creation.
+   */
+  accessibility?: OpenSearchAccessibility;
+}
+
+interface OpenSearchAccessibility {
+  /**
+   * #### How the domain can be reached.
+   *
+   * ---
+   *
+   * - **`internet`**: Accessible from anywhere (still requires IAM credentials).
+   * - **`vpc`**: Only accessible from resources inside your VPC (functions with `joinDefaultVpc: true`, containers, batch jobs).
+   * - **`scoping-workloads-in-vpc`**: Like `vpc`, but also requires security-group access via `connectTo`.
+   *
+   * **Cannot be changed after creation** — switching between internet and VPC modes requires a new domain.
+   *
+   * @default internet
+   */
+  accessibilityMode: 'internet' | 'vpc' | 'scoping-workloads-in-vpc';
+}
+
+interface OpenSearchClusterConfig {
+  /**
+   * #### Instance type for data nodes (e.g., `t3.medium.search`, `r6g.large.search`).
+   *
+   * ---
+   *
+   * Data nodes store data and handle queries. For production, pair with dedicated master nodes.
+   */
+  instanceType: string;
+  /**
+   * #### Number of data nodes. More nodes = more storage capacity and query throughput.
+   */
+  instanceCount: number;
+  /**
+   * #### Instance type for dedicated master nodes (e.g., `m5.large.search`). Manages cluster state, not data.
+   *
+   * ---
+   *
+   * Recommended for clusters with 3+ data nodes to prevent split-brain. Use an odd count (3, 5, or 7).
+   */
+  dedicatedMasterType?: string;
+  /**
+   * #### Number of dedicated master nodes. Must be odd (3, 5, or 7) for quorum.
+   */
+  dedicatedMasterCount?: number;
+  /**
+   * #### Instance type for warm (UltraWarm) nodes — cheaper storage for infrequently accessed data.
+   *
+   * ---
+   *
+   * Data on warm nodes is still searchable but with higher query latency. Great for retaining old logs
+   * or time-series data at lower cost.
+   */
+  warmType?: string;
+  /**
+   * #### Number of warm (UltraWarm) nodes for lower-cost storage of older data.
+   */
+  warmCount?: number;
+  /**
+   * #### Disable Multi-AZ replication. Not recommended — reduces availability and data durability.
+   *
+   * ---
+   *
+   * Multi-AZ is auto-enabled for clusters with 2+ nodes. It distributes nodes across availability zones
+   * so the cluster survives an AZ outage.
+   *
+   * @default false
+   */
+  multiAzDisabled?: boolean;
+  /**
+   * #### Enable Multi-AZ with a standby AZ for highest availability (99.99% SLA).
+   *
+   * ---
+   *
+   * Distributes nodes across 3 AZs with one as standby. The standby takes over instantly during failures
+   * without re-balancing. Requires: version 1.3+, 3 dedicated master + data nodes, GP3/SSD instances.
+   *
+   * @default false
+   */
+  standbyEnabled?: boolean;
+}
+
+interface OpenSearchStorage {
+  /**
+   * #### EBS volume size per data node in GiB. Min/max depends on instance type (typically 10–16,384 GiB).
+   */
+  size: number;
+  /**
+   * #### Provisioned IOPS per data node. GP3 volumes only.
+   * @default 3000
+   */
+  iops?: number;
+  /**
+   * #### Provisioned throughput per data node in MiB/s. GP3 volumes only.
+   * @default 125
+   */
+  throughput?: number;
+}
+interface OpenSearchLogConfiguration {
+  /**
+   * #### Error logs — script compilation errors, invalid queries, indexing issues, snapshot failures.
+   */
+  errorLogs?: OpenSearchLogRetentionSettings;
+  /**
+   * #### Search slow logs — queries exceeding thresholds you configure in OpenSearch index settings.
+   */
+  searchSlowLogs?: OpenSearchLogRetentionSettings;
+  /**
+   * #### Indexing slow logs — indexing operations exceeding thresholds you configure in OpenSearch index settings.
+   */
+  indexSlowLogs?: OpenSearchLogRetentionSettings;
+}
+
+interface OpenSearchLogRetentionSettings {
+  /**
+   * #### Disable this log type.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * #### Days to keep logs in CloudWatch before automatic deletion.
+   * @default 14
+   */
+  retentionDays?: 1 | 3 | 5 | 7 | 14 | 30 | 60 | 90 | 120 | 150 | 180 | 365 | 400 | 545 | 731 | 1827 | 3653;
+}
+
+type OpenSearchDomainReferencableParams = 'arn' | 'domainEndpoint';
+```

package/ai-docs/config-ref/private-service.md

@@ -0,0 +1,75 @@
+---
+docType: config-ref
+title: Private Service
+resourceType: private-service
+tags:
+  - private-service
+  - internal-service
+  - vpc-service
+source: types/stacktape-config/private-services.d.ts
+priority: 1
+---
+
+# Private Service
+
+Always-on container with a private endpoint, reachable only from other resources in your stack.
+
+Use for internal APIs, microservices, or gRPC servers that shouldn't be publicly accessible.
+Other containers in the same stack can reach it by name (e.g., `http://myService:3000`).
+
+Resource type: `private-service`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Always-on container with a private endpoint, reachable only from other resources in your stack.
+ *
+ * ---
+ *
+ * Use for internal APIs, microservices, or gRPC servers that shouldn't be publicly accessible.
+ * Other containers in the same stack can reach it by name (e.g., `http://myService:3000`).
+ */
+interface PrivateService {
+  type: 'private-service';
+  properties: PrivateServiceProps;
+  overrides?: ResourceOverrides;
+}
+
+interface PrivateServiceProps extends SimpleServiceContainer {
+  // /**
+  //  * #### Alias name under which other resources of the stack (web-services, private-services, worker-services, multi-container-workloads) can find this service
+  //  * ---
+  //  * - Combination of `alias`(host) and `port` creates a unique identifier(address). You can then reach service on the address, i.e. using URL in form `protocol://alias:port` for example `http://my-service:8080` or `grpc://appserver:8080`.
+  //  * - By default alias is lowercased name of the resource.
+  //  */
+  // alias?: string;
+  /**
+   * #### Port this service listens on. Injected as the `PORT` env var.
+   * @default 3000
+   */
+  port?: number;
+  /**
+   * #### Protocol for metrics collection. Set to enable protocol-specific metrics (e.g., HTTP 5xx tracking).
+   */
+  protocol?: 'http' | 'http2' | 'grpc';
+  /**
+   * #### How traffic reaches this service from other resources.
+   *
+   * ---
+   *
+   * - **`service-connect`** (default, ~$0.50/mo): Direct container-to-container. Cheapest option.
+   *   Only reachable from other container-based resources in the stack.
+   * - **`application-load-balancer`** (~$18/mo): HTTP load balancer. Reachable from any VPC resource.
+   *
+   * @default service-connect
+   */
+  loadBalancing?: PrivateServiceLoadBalancing;
+}
+
+interface PrivateServiceLoadBalancing {
+  type: ContainerWorkloadServiceConnectIntegration['type'] | ApplicationLoadBalancer['type'];
+}
+
+type PrivateServiceReferencableParams = ContainerWorkloadReferencableParam | 'address';
+```

package/ai-docs/config-ref/redis-cluster.md

@@ -0,0 +1,223 @@
+---
+docType: config-ref
+title: Redis Cluster
+resourceType: redis-cluster
+tags:
+  - redis-cluster
+  - elasticache
+  - redis
+  - cache
+source: types/stacktape-config/redis-cluster.d.ts
+priority: 1
+---
+
+# Redis Cluster
+
+In-memory data store for caching, sessions, queues, and real-time data. Sub-millisecond latency.
+
+Resource type: `redis-cluster`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### In-memory data store for caching, sessions, queues, and real-time data. Sub-millisecond latency.
+ */
+interface RedisCluster {
+  type: 'redis-cluster';
+  properties: RedisClusterProps;
+  overrides?: ResourceOverrides;
+}
+
+interface RedisClusterProps {
+  /**
+   * #### Split data across multiple shards for horizontal scaling.
+   *
+   * ---
+   *
+   * Each shard has its own primary + replicas. Routing is automatic.
+   *
+   * > **Must be set at creation time** — can't be added later.
+   * > Requires `numReplicaNodes >= 1`. Replica count can't be changed after creation.
+   */
+  enableSharding?: boolean;
+  /**
+   * #### Number of shards (only with `enableSharding: true`).
+   * @default 1
+   */
+  numShards?: number;
+  /**
+   * #### Read replicas per shard. Increases read throughput and availability.
+   *
+   * ---
+   *
+   * If the primary fails and `enableAutomaticFailover` is on, a replica takes over.
+   * Can't be changed after creation for sharded clusters.
+   *
+   * @default 0
+   */
+  numReplicaNodes?: number;
+  /**
+   * #### Auto-promote a replica to primary if the primary node fails.
+   *
+   * ---
+   *
+   * Requires `numReplicaNodes >= 1`. Always enabled for sharded clusters.
+   *
+   * > Deploy replicas first, then enable failover in a separate deployment.
+   */
+  enableAutomaticFailover?: boolean;
+  /**
+   * #### The size of each Redis node. Affects memory, performance, and cost.
+   *
+   * ---
+   *
+   * **Quick guide:**
+   * - **`cache.t4g.micro`** (~$0.016/hr, 0.5 GB): Development, testing, low-traffic apps.
+   * - **`cache.t4g.small`** (~$0.032/hr, 1.37 GB): Small production apps, session stores.
+   * - **`cache.m7g.large`** (~$0.15/hr, 6.38 GB): Production workloads with moderate data.
+   * - **`cache.r7g.large`** (~$0.20/hr, 13.07 GB): Large datasets, memory-heavy caching.
+   *
+   * **Families:** `t` = burstable (cheap, variable). `m` = general purpose. `r` = memory-optimized.
+   * Suffix `g` = ARM/Graviton (better price-performance).
+   *
+   * This size applies to every node (primary + replicas). You can change it later without data loss.
+   */
+  instanceSize:
+    | 'cache.t3.micro'
+    | 'cache.t3.small'
+    | 'cache.t3.medium'
+    | 'cache.t4g.micro'
+    | 'cache.t4g.small'
+    | 'cache.t4g.medium'
+    | 'cache.m6g.large'
+    | 'cache.m6g.xlarge'
+    | 'cache.m6g.2xlarge'
+    | 'cache.m6g.4xlarge'
+    | 'cache.m6g.8xlarge'
+    | 'cache.m6g.12xlarge'
+    | 'cache.m6g.16xlarge'
+    | 'cache.m7g.large'
+    | 'cache.m7g.xlarge'
+    | 'cache.m7g.2xlarge'
+    | 'cache.m7g.4xlarge'
+    | 'cache.m7g.8xlarge'
+    | 'cache.m7g.12xlarge'
+    | 'cache.m7g.16xlarge'
+    | 'cache.m5.large'
+    | 'cache.m5.xlarge'
+    | 'cache.m5.2xlarge'
+    | 'cache.m5.4xlarge'
+    | 'cache.m5.12xlarge'
+    | 'cache.m5.24xlarge'
+    | 'cache.m4.large'
+    | 'cache.m4.xlarge'
+    | 'cache.m4.2xlarge'
+    | 'cache.m4.4xlarge'
+    | 'cache.m4.10xlarge'
+    | 'cache.t2.micro'
+    | 'cache.t2.small'
+    | 'cache.t2.medium'
+    | 'cache.r6g.large'
+    | 'cache.r6g.xlarge'
+    | 'cache.r6g.2xlarge'
+    | 'cache.r6g.4xlarge'
+    | 'cache.r6g.8xlarge'
+    | 'cache.r6g.12xlarge'
+    | 'cache.r6g.16xlarge'
+    | 'cache.r7g.large'
+    | 'cache.r7g.xlarge'
+    | 'cache.r7g.2xlarge'
+    | 'cache.r7g.4xlarge'
+    | 'cache.r7g.8xlarge'
+    | 'cache.r7g.12xlarge'
+    | 'cache.r7g.16xlarge'
+    | 'cache.r5.large'
+    | 'cache.r5.xlarge'
+    | 'cache.r5.2xlarge'
+    | 'cache.r5.4xlarge'
+    | 'cache.r5.12xlarge'
+    | 'cache.r5.24xlarge'
+    | 'cache.r4.large'
+    | 'cache.r4.xlarge'
+    | 'cache.r4.2xlarge'
+    | 'cache.r4.4xlarge'
+    | 'cache.r4.8xlarge'
+    | 'cache.r4.16xlarge';
+  /**
+   * #### Slow query logging. Sent to CloudWatch; view with `stacktape logs`.
+   */
+  logging?: RedisLogging;
+  /**
+   * #### Days to keep automated daily backups. Set to 0 to disable.
+   * @default 0
+   */
+  automatedBackupRetentionDays?: number;
+  /**
+   * #### Port the cluster listens on.
+   * @default 6379
+   */
+  port?: number;
+  /**
+   * #### Cluster password. 16-128 chars, printable ASCII only. Cannot contain `/`, `"`, or `@`.
+   *
+   * ---
+   *
+   * All traffic is encrypted in transit. Use `$Secret()` instead of hardcoding:
+   * ```yaml
+   * defaultUserPassword: $Secret('redis.password')
+   * ```
+   */
+  defaultUserPassword: string;
+  /**
+   * #### Network access control: `vpc` (default) or `scoping-workloads-in-vpc` (most restrictive).
+   */
+  accessibility?: RedisAccessibility;
+  /**
+   * #### Redis engine version.
+   * @default "6.2"
+   */
+  engineVersion?: '7.1' | '7.0' | '6.2' | '6.0';
+  /**
+   * #### Dev mode: runs locally in Docker by default. Set `remote: true` to use the deployed cluster.
+   */
+  dev?: DevModeConfig;
+}
+
+interface RedisLogging extends LogForwardingBase {
+  /**
+   * #### Disable slow query logging.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * #### Log format.
+   * @default json
+   */
+  format?: 'text' | 'json';
+  /**
+   * #### 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;
+}
+
+interface RedisAccessibility {
+  /**
+   * #### Who can connect to this cluster.
+   *
+   * ---
+   *
+   * - **`vpc`** (default): Any resource in the same VPC (functions with `joinDefaultVpc: true`, containers, batch jobs).
+   * - **`scoping-workloads-in-vpc`**: Only resources that list this cluster in their `connectTo`.
+   *
+   * Redis clusters don't have public IPs — you can't connect from your local machine directly.
+   * Use a bastion host for local access.
+   *
+   * @default vpc
+   */
+  accessibilityMode: 'vpc' | 'scoping-workloads-in-vpc';
+}
+
+type RedisClusterReferencableParam = 'host' | 'readerHost' | 'port' | 'readerPort' | 'connectionString' | 'sharding';
+```