@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/extensions/enact-repo/skills/aca-sandboxes/references/install.md

@@ -0,0 +1,87 @@
+# Install the `aca` CLI
+
+The `aca` CLI is the primary surface for sandboxes. It delegates
+authentication to the Azure CLI — sign in once with `az login` and the
+same Entra identity is used by `aca`.
+
+## Linux / macOS
+
+```bash
+# This same one-liner is also the install path used INSIDE a sandbox or
+# container for agent-driven self-installs — no package manager needed.
+curl -fsSL https://aka.ms/aca-cli-install | sh
+```
+
+Pin a specific version:
+
+```bash
+curl -fsSL https://aka.ms/aca-cli-install \
+  | ACA_VERSION=aca-cli-v0.1.0-early-access sh
+```
+
+## Windows (PowerShell)
+
+```powershell
+# This same one-liner is also the install path used INSIDE a Windows
+# sandbox or container for agent-driven self-installs.
+irm https://aka.ms/aca-cli-install-ps | iex
+```
+
+Pin a specific version:
+
+```powershell
+& ([scriptblock]::Create((irm https://aka.ms/aca-cli-install-ps))) -Version aca-cli-v0.1.0-early-access
+```
+
+## Verify
+
+```bash
+aca --version
+```
+
+Then sign in and run the doctor. Both `az login` and `aca auth login`
+should be **gated on a status check** — calling either one
+unconditionally opens a browser / device-code flow even when a valid
+session is already cached, which is bad UX (and breaks in environments
+with no interactive browser):
+
+```bash
+# bash / zsh
+az account show -o none 2>/dev/null || az login
+aca auth status >/dev/null 2>&1 || aca auth login
+aca doctor
+```
+
+```powershell
+# PowerShell
+az account show -o none 2>$null
+if ($LASTEXITCODE -ne 0) { az login }
+aca auth status *> $null
+if ($LASTEXITCODE -ne 0) { aca auth login }
+aca doctor
+```
+
+> The CLI verb for `aca` sign-in is **`aca auth login`**. The top-level
+> `aca` binary does not have a bare `login` subcommand — always use the
+> `auth` namespace. `aca` delegates the underlying Entra flow to
+> `az login`, so the same identity / MFA apply.
+
+## Uninstall
+
+```bash
+# Linux / macOS
+curl -fsSL https://aka.ms/aca-cli-install | sh -s -- --uninstall
+```
+
+```powershell
+# Windows
+& ([scriptblock]::Create((irm https://aka.ms/aca-cli-install-ps))) -Uninstall
+```
+
+## Supported platforms
+
+| Platform | Architecture |
+|---|---|
+| Linux   | x64    |
+| macOS   | ARM64  |
+| Windows | x64    |

package/extensions/enact-repo/skills/aca-sandboxes/references/prerequisites.md

@@ -0,0 +1,52 @@
+# CLI prerequisites
+
+## Accounts and access
+
+- **Azure subscription** — one you can create resource groups in.
+  [Create one for free](https://azure.microsoft.com/pricing/purchase-options/azure-account).
+- **Microsoft Entra ID account** — personal Microsoft accounts are **not** supported.
+- **Role** — to create sandboxes inside a group you need the
+  `Container Apps SandboxGroup Data Owner` role on the group. The
+  [quickstart](quickstart.md) shows how to grant it to yourself.
+
+## Tools
+
+- **[Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)** installed and logged in (`az login`).
+  The `aca` CLI delegates auth to `az login` — same identity, same MFA,
+  same conditional-access policies.
+- **An Azure subscription with a resource group.**
+- **`aca` CLI** — installed in one line; see [install.md](install.md).
+- **A shell** — Bash on Linux/macOS; PowerShell or Bash (Git Bash / WSL) on Windows.
+
+## Supported platforms
+
+| Platform | Architecture |
+|---|---|
+| Linux   | x64    |
+| macOS   | ARM64  |
+| Windows | x64    |
+
+## Region
+
+Sandboxes are a preview resource type. Start with a well-supported
+region such as `eastus2` or `westus2`. If a region rejects the group
+create, try another — `aca` will tell you which region the API rejected.
+
+## Doctor checklist
+
+`aca doctor` runs all of the following — green across the board means
+you are ready to create sandboxes:
+
+1. Azure CLI found on `PATH`.
+2. Azure CLI is logged in (`az account show` succeeds).
+3. A default subscription is resolved (flag, env, or config).
+4. A default resource group is resolved.
+5. A default sandbox group is resolved.
+6. A default region is resolved.
+7. The sandbox group exists in Azure.
+8. The caller has the `Container Apps SandboxGroup Data Owner` role on the group.
+
+Each line in `aca doctor` output also tells you **where** the value came
+from — `(flag)`, `(env)`, `(config: sandbox)`, or `(config)` — which is
+invaluable when debugging precedence. See
+[reference.md](reference.md#config) for the precedence model.

package/extensions/enact-repo/skills/aca-sandboxes/references/quickstart.md

@@ -0,0 +1,164 @@
+# CLI quick start
+
+Goal: log in, create a sandbox group, grant yourself access, create a
+sandbox, run a command, and clean up — all via the `aca` CLI.
+
+> Assumes `aca` is installed (see [install.md](install.md)) and the
+> Azure CLI is on your `PATH`. Full prereqs: [prerequisites.md](prerequisites.md).
+
+## Common mistakes
+
+**The `az` CLI has no sandbox commands.** Sandbox groups and
+sandboxes are managed by `aca` — **not** by `az containerapp …`. The
+`az containerapp` commands are for the older Apps / Jobs surface and
+do not touch sandboxes. If you see `az containerapp sandbox …` in a
+snippet, it's wrong.
+
+**There is no `aca sandbox-group` (hyphenated) command group.**
+Every group-level verb is `aca sandboxgroup …` (no hyphen):
+`aca sandboxgroup create / get / list / delete / role create /
+identity assign / secret set / disk list / volume create / snapshot …`.
+The hyphenated `--sandbox-group <name>` is the *flag* you pass to
+top-level commands to select the default group — it is not a verb.
+If you see `aca sandbox-group …` in a snippet (including for MCP
+connectors, credentials, or triggers), it's wrong / fabricated.
+
+```bash
+# 0. Log in to Azure — auth-aware: skip if already signed in
+#    (calling `az login` unconditionally opens a browser even when
+#    a valid session is already cached)
+az account show -o none 2>/dev/null || az login
+
+# 1. Create a resource group (skip if you have one)
+az group create --name my-rg --location eastus2
+
+# 2. Create a sandbox group (saves config automatically with --set-config)
+aca sandboxgroup create --name my-sandbox-group --location eastus2 --set-config
+
+# 3. Grant yourself data-plane access
+aca sandboxgroup role create \
+  --role "Container Apps SandboxGroup Data Owner" \
+  --principal-id $(az ad signed-in-user show --query id -o tsv)
+
+# 4. Verify setup
+aca doctor
+
+# 5. Create a sandbox (capture the ID for reuse)
+SANDBOX_ID=$(aca sandbox create --disk ubuntu -o json | jq -r .id)
+
+# 6. Run a command
+aca sandbox exec --id "$SANDBOX_ID" -c "echo hello world && uname -a"
+
+# 7. Clean up (snapshot first if there's state you want to keep)
+aca sandbox delete --id "$SANDBOX_ID" --yes
+```
+
+`aca doctor` should print eight green checks:
+
+```
+✓ Azure CLI found
+✓ Azure CLI logged in
+✓ Subscription: a59d7183-… (config)
+✓ Resource group: my-rg (config)
+✓ Sandbox group: my-sandbox-group (config: sandbox)
+✓ Region: eastus2 (config: sandbox)
+✓ Sandbox group 'my-sandbox-group' exists in Azure
+✓ Container Apps SandboxGroup Data Owner role assigned
+
+aca 1.0.0-beta.1 — all checks passed
+```
+
+Defaults applied when flags are omitted:
+
+| Flag | Default |
+|---|---|
+| `--cpu`    | `1000m` (1 vCPU) |
+| `--memory` | `2048Mi` (2 GiB) |
+| auto-suspend | 300s (5 min idle → suspend) |
+
+Label + selector shortcut (target sandboxes without remembering IDs):
+
+```bash
+aca sandbox create --disk ubuntu --label name=dev
+aca sandbox exec -l "name=dev" -c "echo hello"
+```
+
+Tear down the whole group later:
+
+```bash
+aca sandboxgroup delete --name my-sandbox-group --yes
+```
+
+## Common follow-up tasks
+
+Once a sandbox is running, these are the most-used data-plane verbs.
+
+### Open an interactive shell
+
+```bash
+aca sandbox shell --id "$SANDBOX_ID"
+```
+
+`exec` runs one command and returns; `shell` gives you a real PTY. There
+is no SSH daemon — these two are the only paths into the sandbox.
+
+### Copy a file in and out
+
+```bash
+aca sandbox fs write --id "$SANDBOX_ID" --path /tmp/data.csv --file ./data.csv
+aca sandbox fs cat   --id "$SANDBOX_ID" --path /tmp/out.json > ./out.json
+```
+
+`fs` also has `ls`, `stat`, `mkdir`, `rm [--recursive]`.
+
+### Expose a port publicly (preview)
+
+```bash
+URL=$(aca sandbox port add --id "$SANDBOX_ID" --port 8080 --anonymous -o json | jq -r .url)
+curl "$URL"
+
+# When done:
+aca sandbox port remove --id "$SANDBOX_ID" --port 8080
+```
+
+`--anonymous` makes the URL reachable by anyone who has it (public
+preview). For per-user gating, swap to `--email <entra-mail>`.
+
+### Mount a shared volume
+
+```bash
+# Once, at the group:
+aca sandboxgroup volume create --name shared --type AzureBlob
+
+# Each sandbox that needs it:
+aca sandbox mount --id "$SANDBOX_ID" --volume shared --path /mnt/shared
+```
+
+`AzureBlob` is multi-attach (shared across sandboxes); `DataDisk` is
+single-attach high-perf block storage.
+
+### Suspend and resume to save cost
+
+```bash
+aca sandbox stop   --id "$SANDBOX_ID"   # preserves memory + disk
+aca sandbox resume --id "$SANDBOX_ID"   # sub-second restore
+
+# Or set an idle policy (default 300s):
+aca sandbox lifecycle set --id "$SANDBOX_ID" --auto-suspend 60
+```
+
+Suspended sandboxes incur storage cost only — no compute.
+
+### Snapshot before destructive changes
+
+```bash
+aca sandbox snapshot --id "$SANDBOX_ID" --name pre-experiment
+# ... do risky thing ...
+# If it goes wrong, boot a clean replica from the snapshot:
+aca sandbox create --snapshot pre-experiment
+```
+
+## What next
+
+- [reference.md](reference.md) — full `aca` CLI reference (auth, config, YAML, selectors, output, verbose).
+- [scenarios.md](scenarios.md) — patterns: web apps, coding agents, swarms, MCP hosting.

package/extensions/enact-repo/skills/aca-sandboxes/references/reference-advanced.md

@@ -0,0 +1,251 @@
+# `aca` CLI reference — advanced
+
+Part 2 of 2: YAML spec workflow, selectors, output formats, verbose/debug. See [reference.md](reference.md) for auth, help, global flags, environment variables, config, and `doctor`.
+
+## Contents
+
+- [YAML spec workflow](#yaml-spec-workflow)
+- [Selectors](#selectors)
+- [Output formats](#output-formats)
+- [Verbose and debug](#verbose-and-debug)
+- [Python SDK](#python-sdk)
+
+---
+
+## YAML spec workflow
+
+Define a sandbox in YAML, validate, then apply. This is the
+infra-as-code story for sandboxes: check specs into git, code-review
+them, validate in CI before apply, and get editor autocomplete from the
+published JSON Schema.
+
+### The four commands
+
+| Command | Does |
+|---|---|
+| `aca sandbox init` | Print a starter spec to stdout |
+| `aca sandbox schema` | Print the JSON Schema for sandbox specs (for editor integration) |
+| `aca sandbox validate --file <FILE>` | Validate a spec file without creating anything |
+| `aca sandbox apply --file <FILE> [--no-wait]` | Create the sandbox from the spec |
+
+### End-to-end
+
+```bash
+aca sandbox init > sandbox.yaml
+```
+
+Generates:
+
+```yaml
+# ACA Sandbox manifest
+# Apply with: aca sandbox apply --file sandbox.yaml
+
+disk: ubuntu
+resources:
+  cpu: 1000m
+  memory: 2048Mi
+lifecycle:
+  autoSuspendPolicy:
+    enabled: true
+    interval: 300
+    mode: Memory
+egressPolicy:
+  defaultAction: Deny
+```
+
+Edit it (set labels, change `cpu` / `memory`, tighten egress), then:
+
+```bash
+aca sandbox validate --file sandbox.yaml
+aca sandbox apply --file sandbox.yaml
+```
+
+Add `--no-wait` to return as soon as the create is accepted (don't wait
+for `Running`).
+
+### Editor integration via `schema`
+
+```bash
+aca sandbox schema > sandbox.schema.json
+```
+
+Point your editor at it (`yaml.schemas` in VS Code, `yaml-language-server`
+in Neovim) for autocomplete and inline validation.
+
+### Validate in CI
+
+```bash
+aca sandbox validate --file sandbox.yaml
+```
+
+Exit code is non-zero on failure — drop this into a pre-merge check to
+catch spec drift before it hits Azure.
+
+---
+
+## Selectors
+
+Every command that operates on a sandbox accepts either a UUID or a
+label selector. UUIDs are unmemorable and ephemeral. Selectors let you
+script against labels you control. `-l "env=ci,role=worker"` works the
+same in your dev shell, your cleanup cron, your dashboard, and your
+alerting.
+
+### The two forms
+
+```bash
+# By ID (UUID)
+aca sandbox exec --id 0d9b1c4e-… -c "echo hello"
+
+# By label selector
+aca sandbox exec -l "name=dev" -c "echo hello"
+```
+
+### Selector grammar
+
+- `key=value` — match exactly
+- `key1=v1,key2=v2` — AND (all pairs must match)
+- Spaces around `=` and `,` are **not** allowed
+- For `get` and `delete`, the CLI matches the **first** sandbox satisfying the selector
+
+### Set labels at create-time
+
+The flag is `--label key=value`, repeatable:
+
+```bash
+aca sandbox create --disk ubuntu \
+  --label env=ci \
+  --label role=worker \
+  --label owner=alice
+```
+
+Then operate on it without quoting the UUID:
+
+```bash
+aca sandbox exec   -l "env=ci,role=worker" -c "./run.sh"
+aca sandbox stop   -l "env=ci,role=worker"
+aca sandbox delete -l "env=ci,role=worker"
+```
+
+### When to pick which
+
+| Use | Form |
+|---|---|
+| Long-lived dev sandbox       | Selector — friendlier in shell history |
+| Output of a previous command | UUID — already in your shell variable |
+| Batch over many              | `list -o json` + `jq` + UUID loop |
+| Cleanup by ownership tag     | Selector — labels are your contract |
+
+---
+
+## Output formats
+
+Every command supports `-o table|json`. Default is `table`.
+
+| Format | Use |
+|---|---|
+| `table` | Humans, interactive shells |
+| `json`  | Scripts, CI, pipelines |
+
+### Pipe JSON to `jq`
+
+Pull just the IDs:
+
+```bash
+aca sandbox list -o json | jq -r '.[].id'
+```
+
+Find Running sandboxes labeled `env=ci`:
+
+```bash
+aca sandbox list -o json | jq -r '.[] | select(.state=="Running" and .labels.env=="ci") | .id'
+```
+
+Bulk delete by tag:
+
+```bash
+aca sandbox list -o json \
+  | jq -r '.[] | select(.labels.env=="ci") | .id' \
+  | xargs -I{} aca sandbox delete --id {} --yes
+```
+
+### Diffing snapshots of the same resource
+
+```bash
+ID=<sandbox-id>
+aca sandbox get --id $ID -o json | jq -S . > before.json
+# ... do something ...
+aca sandbox get --id $ID -o json | jq -S . > after.json
+diff before.json after.json
+```
+
+---
+
+## Verbose and debug
+
+When a command does the wrong thing, `--verbose` shows exactly what.
+
+### `--verbose`
+
+```bash
+aca sandbox list --verbose
+```
+
+Outputs:
+
+- The **resolved config** dump (where each value came from: flag, env, sandbox-config, shared-config)
+- HTTP **request line**, headers, and status for each call
+- Response headers (bodies elided)
+
+### `--debug`
+
+```bash
+aca sandbox list --debug
+```
+
+Includes everything `--verbose` does **plus** transport-level details
+(TLS, retries, raw response bodies).
+
+> Warning: `--debug` may log sensitive data (secret values, tokens in error
+> bodies). Don't share the output of a `--debug` run without reviewing
+> it first.
+
+### Capture to a file
+
+```bash
+aca sandbox apply --file sandbox.yaml --verbose 2> aca.log
+```
+
+Stdout stays clean for piping; verbose / debug traces go to stderr so
+you can capture them separately.
+
+---
+
+## Python SDK
+
+The Python SDK ([`azure-containerapps-sandbox`](https://pypi.org/project/azure-containerapps-sandbox/)) is the programmatic counterpart to the `aca` CLI and is in public preview. Install from PyPI (preflight `uv` first — install the upstream installer if it's missing):
+
+```bash
+# Linux / macOS
+command -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
+uv pip install azure-containerapps-sandbox
+```
+
+```powershell
+# Windows
+if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+  irm https://astral.sh/uv/install.ps1 | iex
+}
+uv pip install azure-containerapps-sandbox
+```
+
+Import as:
+
+```python
+from azure_containerapps_sandbox import SandboxGroupsClient
+```
+
+The SDK and the `aca` CLI are interchangeable surfaces over the same
+control plane — pick whichever fits your runtime (CLI for shells /
+agents / scripts, SDK for service code). When in doubt or for
+agent-driven self-installs, prefer the CLI install path above.