koppler 0.0.6 → 0.0.8

package/skills/koppler-run/references/stack.md

@@ -49,8 +49,8 @@ It holds facts about the apps, never secret values.
 | `notes` | Stack-wide facts. |
 | `checks` | The stack's own health checks, run when it loads (`koppler doctor`): `name`, `run` (a shell command), `ok` and `fix` texts, `kinds` to limit it to stacks with those app kinds. At most 50, each `run` up to 2000 characters. They are someone's commands, so they run only after the user approved them with `koppler doctor --approve`, and again after one changes. The same approval covers everything else the stack would run or write: an app's `start` (also per environment), a custom kind's `start` and `stop`, and `localChanges`. |
 | `apps.<id>.outside` | The app does not run on this Mac, or has nothing to run (Salesforce, a SaaS package, a managed service, an S3 bucket, a library or config repo), with a short why. It is never planned, sent or started (`koppler up` refuses it by name), needs no `slug`, and its card shows the address its `deployedUrl` gives for the board's environment (the Salesforce sandbox on QA, production on PROD). `koppler discover --deployed` drafts known ones (Salesforce) from each app's addresses per environment, with the calls to them (`outsideSuggestions`). It stays in the stack so the flow is complete: it never runs or takes a cable, and shows as a dashed read-only card next to the board apps that call it (`consumes`) or share a queue with it. |
-| `queues` | Top-level: `{ "<id>": { "name", "type", "queue"? } }`, the queues, topics and event buses between apps. `type` is `sqs`, `sns`, `eventbridge`, `kafka` or `other`; `queue` is its real name (default the id), per environment under `envs.<env>.queue`. |
-| `apps.<id>.publishes`, `apps.<id>.reads` | `koppler discover --deployed` drafts them, with `queues`, from the Terraform (who sends and reads, the settings carrying each address, what feeds a queue from outside); confirm before adding.  The queues the app sends to or takes from: `{ "<queue>": { "env"?: [settings holding the queue's URL] } }`. On the canvas an app is off its queues until its card's Queues switch is on (`queues: true` in a preset); then they draw a queue card between its apps, with a Local switch. Switched on, `koppler up` runs it locally. SQS: one AWS emulator in Docker on port 4566 holds the queue, and every app on it starts with `AWS_ENDPOINT_URL_SQS` (which current AWS SDKs read) and its `env` settings pointed at the local queue. Kafka: one broker in Docker (`apache/kafka`) on `localhost:9092` gets the topic (`queue`), and every app on it starts with its `env` settings (its broker list, e.g. `Kafka__BootstrapServers`) set to `localhost:9092`; a broker setup that needs sign-in (SASL, MSK IAM) has to be turned off for the local run, e.g. by a remembered change. SNS and EventBridge stay deployed. Off, a local reader takes messages off the deployed queue, so the deployed reader misses those; the card says so. |
+| `queues` | Top-level: `{ "<id>": { "name", "type", "queue"? } }`, the queues, topics and event buses between apps. `type` is `sqs`, `sns`, `eventbridge`, `kafka` or `other`; `queue` is its real name (default the id), per environment under `envs.<env>.queue`.; `feeds` names the queues, topics and buses it hands its messages to, and how: `{ "<queue>": { "via": "pipe" \| "rule" \| "subscription" } }` (a Kafka topic piped onto an event bus, a bus whose rule forwards to another bus, an SNS topic with an SQS subscription). |
+| `apps.<id>.publishes`, `apps.<id>.reads` | `koppler discover --deployed` drafts them, with `queues`, from the Terraform (who sends and reads, the settings carrying each address, what feeds a queue from outside); confirm before adding.  The queues the app sends to or takes from: `{ "<queue>": { "env"?: [settings holding the queue's URL] } }`. On the canvas an app is off its queues until its card's Queues switch is on (`queues: true` in a preset); then they draw a queue card between its apps, with a Local switch. Switched on, `koppler up` runs it locally. SQS: one AWS emulator in Docker on port 4566 holds the queue, and every app on it starts with `AWS_ENDPOINT_URL_SQS` (which current AWS SDKs read) and its `env` settings pointed at the local queue. Kafka: one broker in Docker (`apache/kafka`) on `localhost:9092` gets the topic (`queue`), and every app on it starts with its `env` settings (its broker list, e.g. `Kafka__BootstrapServers`) set to `localhost:9092`; a broker setup that needs sign-in (SASL, MSK IAM) has to be turned off for the local run, e.g. by a remembered change. SNS and EventBridge stay deployed. Off, a local reader takes messages off the deployed queue, so the deployed reader misses those; the card says so. A read entry can say how the app reads it when not by itself: `{ "via": "rule to Lambda" }` (a pipe or rule to a Lambda or an API destination); the canvas shows it on the link, and a local app read that way takes nothing off the deployed queue. |
 | `install` | How to install a program the stack needs, by name: `{ "cloudflared": "brew install cloudflared" }`. Which programs are needed is worked out from the stack itself: each app kind's own, and the first word of every prerequisite's `cmd`. |
 | `kind` | What the app is built with; decides how it is recognized, started and shown. See "Kinds" below. |
 | `start` | The shell command that starts the app in its repo. Needed for `other`, optional for the recipe kinds, where it replaces the usual command. |
@@ -165,7 +165,8 @@ Tests, docs, lock files and migration tools are not searched.
 - the app's deployed address (API Gateway domain, CDN alias or DNS record), marked `NEW`, `matches stack.json` or `OTHER than stack.json`;
 - the names of its settings, and which of them hold or point to a secret;
 - Secrets Manager secret names and Parameter Store paths;
-- calls: a setting whose address belongs to another app.
+- calls: a setting whose address belongs to another app;
+- queues, topics and event buses, and what feeds what (`queueSuggestions`): SQS queues and SNS topics, EventBridge buses (`aws_cloudwatch_event_bus`), Kafka topics a pipe reads (`topic_name` of an `aws_pipes_pipe` or `awscc_pipes_pipe`, one per topic of a list), pipes (source to target), rules with their targets (a bus to a queue, a Lambda, or another account's bus by its ARN), and SNS subscriptions (`aws_sns_topic_subscription`). A queue read through a pipe or rule to a Lambda or an API destination is drafted as `reads` with `via`, such as `"rule to Lambda"`. Feeds of queues the stack already has are under `queueSuggestions.feeds`.
 
 It reads out names and plain addresses only (a host, or an http(s) URL with no credentials or query); every other value stays in the repo.
 Environments come from variable files named after them (`deployment-dev.tfvars`) or, without those, from trying each stack environment and alias as the Terraform workspace.