From 1a7d7c0688c04308524a4ea84a39314b79422dec Mon Sep 17 00:00:00 2001 From: krokoko Date: Thu, 9 Apr 2026 10:28:34 -0500 Subject: [PATCH 1/2] feat(project): add git hooks --- .claude/settings.json | 2 +- .github/CODEOWNERS | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- .github/SECURITY.md | 2 +- .github/pull_request_template.md | 2 +- .pre-commit-config.yaml | 71 +++++++++++++++++++ .../components/applicationInfo.tc.json | 2 +- .../architectureDescription.tc.json | 2 +- .../components/dataflowDescription.tc.json | 2 +- .../components/mitigations.tc.json | 2 +- .../20260331-1834/components/threats.tc.json | 2 +- .../20260331-1834/config/config.json | 2 +- .../config/environment-vars.json | 2 +- .../20260331-1834/config/run-metadata.json | 2 +- .../hashes/applicationInfo.tc.json.hash | 2 +- .../architectureDescription.tc.json.hash | 2 +- .../hashes/architectureDiagram.svg.hash | 2 +- .../hashes/dataflowDescription.tc.json.hash | 2 +- .../hashes/dataflowDiagram.svg.hash | 2 +- .../hashes/mitigations.tc.json.hash | 2 +- .../20260331-1834/hashes/threats.tc.json.hash | 2 +- .../multi_agent.json | 2 +- .../session_20260331-1834/session.json | 2 +- .../20260331-1834/threatmodel.tc.json | 2 +- AGENTS.md | 3 + CONTRIBUTING.md | 23 ++++++ README.md | 2 +- agent/.python_version | 2 +- cdk/header.js | 2 +- docs/README.md | 2 +- docs/design/API_CONTRACT.md | 1 - docs/design/ARCHITECTURE.md | 2 +- docs/design/INPUT_GATEWAY.md | 58 +++++++-------- docs/guides/DEVELOPER_GUIDE.md | 6 +- docs/src/content/docs/design/Api-contract.md | 1 - docs/src/content/docs/design/Architecture.md | 2 +- docs/src/content/docs/design/Input-gateway.md | 58 +++++++-------- .../docs/developer-guide/Contributing.md | 23 ++++++ .../docs/developer-guide/Installation.md | 6 +- .../docs/developer-guide/Introduction.md | 2 +- .../docs/developer-guide/Project-structure.md | 2 +- .../developer-guide/Repository-preparation.md | 2 +- .../developer-guide/Where-to-make-changes.md | 2 +- docs/src/content/docs/index.md | 1 - .../content/docs/user-guide/Authentication.md | 2 +- .../content/docs/user-guide/Introduction.md | 2 +- docs/src/content/docs/user-guide/Overview.md | 2 +- .../content/docs/user-guide/Prerequisites.md | 2 +- .../docs/user-guide/Repository-onboarding.md | 2 +- .../content/docs/user-guide/Task-lifecycle.md | 2 +- docs/src/content/docs/user-guide/Tips.md | 2 +- .../content/docs/user-guide/Using-the-cli.md | 2 +- .../docs/user-guide/Using-the-rest-api.md | 2 +- .../content/docs/user-guide/Viewing-logs.md | 2 +- .../docs/user-guide/Webhook-integration.md | 2 +- .../docs/user-guide/What-the-agent-does.md | 2 +- mise.toml | 26 ++++++- 57 files changed, 253 insertions(+), 114 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.claude/settings.json b/.claude/settings.json index 2d8365d..c9879d3 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -4,4 +4,4 @@ "code-review@claude-plugins-official": true, "pr-review-toolkit@claude-plugins-official": true } -} \ No newline at end of file +} diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7dc7701..794959c 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -6,4 +6,4 @@ ## File must end with CODEOWNERS file -.github/CODEOWNERS @aws-samples/coding-agents-admin \ No newline at end of file +.github/CODEOWNERS @aws-samples/coding-agents-admin diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 6b8951a..a58498a 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -34,7 +34,7 @@ body: id: use-case attributes: label: Use case - description: Why do you need this? For example: "I'm always frustrated when..." + description: "Why do you need this? For example: I'm always frustrated when..." validations: required: true - type: textarea diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 03a266e..f97d030 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -3,4 +3,4 @@ If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](https://aws.amazon.com/security/vulnerability-reporting/) or directly via email to aws-security@amazon.com. > [!IMPORTANT] -> Please do not create a GitHub issue, pull request, or other public announcements. \ No newline at end of file +> Please do not create a GitHub issue, pull request, or other public announcements. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 29f0c2e..c655d2d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -22,4 +22,4 @@ Tip: [AGENTS.md](https://github.com/aws-samples/sample-autonomous-cloud-coding-a #### Acknowledgment -By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the [project license](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/LICENSE). \ No newline at end of file +By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the [project license](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/LICENSE). diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..2a1c4f5 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,71 @@ +# Git hooks via https://github.com/j178/prek (installed by `mise run install` in a Git checkout; re-run `mise run hooks:install` after edits). +# Config format matches pre-commit; run hooks with `prek` from mise (`mise.toml` [tools]). + +default_install_hook_types: [pre-commit, pre-push] +fail_fast: false +exclude: ^\.threat-composer/ + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: trailing-whitespace + # Skip generated trees and paths often checked in read-only (0444); mutating hooks must not touch them. + exclude: (cdk/cdk\.out/|node_modules/|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$|\.(snap|lock)$) + - id: end-of-file-fixer + exclude: (cdk/cdk\.out/|node_modules/|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$) + - id: check-merge-conflict + - id: check-yaml + exclude: ^(cdk/cdk\.out/|cdk\.out/|node_modules/|agent/\.venv/) + - id: check-json + exclude: ^(cdk/cdk\.out/|node_modules/) + + - repo: local + hooks: + - id: gitleaks-staged + name: gitleaks (staged) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run security:secrets:staged' + language: system + pass_filenames: false + stages: [pre-commit] + + - id: cdk-eslint + name: eslint (cdk) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && export MISE_EXPERIMENTAL=1 && mise //cdk:eslint' + language: system + pass_filenames: false + files: ^cdk/.*\.(ts|tsx|cjs|mjs|js)$ + exclude: ^cdk/cdk\.out/ + stages: [pre-commit] + + - id: cli-eslint + name: eslint (cli) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && export MISE_EXPERIMENTAL=1 && mise //cli:eslint' + language: system + pass_filenames: false + files: ^cli/.*\.(ts|tsx|cjs|mjs|js)$ + stages: [pre-commit] + + - id: agent-quality + name: quality (agent) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/agent" && mise run quality' + language: system + pass_filenames: false + files: ^agent/.*\.py$ + stages: [pre-commit] + + - id: docs-astro-check + name: astro check (docs) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && ./node_modules/.bin/astro check' + language: system + pass_filenames: false + files: ^docs/ + exclude: ^docs/node_modules/ + stages: [pre-commit] + + - id: monorepo-security-pre-push + name: security scans (pre-push) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run security' + language: system + pass_filenames: false + stages: [pre-push] diff --git a/.threat-composer/20260331-1834/components/applicationInfo.tc.json b/.threat-composer/20260331-1834/components/applicationInfo.tc.json index 6e15fc3..7316712 100644 --- a/.threat-composer/20260331-1834/components/applicationInfo.tc.json +++ b/.threat-composer/20260331-1834/components/applicationInfo.tc.json @@ -92,4 +92,4 @@ "threats": [], "mitigations": [], "mitigationLinks": [] -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/components/architectureDescription.tc.json b/.threat-composer/20260331-1834/components/architectureDescription.tc.json index a3768b1..c85c4be 100644 --- a/.threat-composer/20260331-1834/components/architectureDescription.tc.json +++ b/.threat-composer/20260331-1834/components/architectureDescription.tc.json @@ -123,4 +123,4 @@ "threats": [], "mitigations": [], "mitigationLinks": [] -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/components/dataflowDescription.tc.json b/.threat-composer/20260331-1834/components/dataflowDescription.tc.json index 91c82a7..23f0482 100644 --- a/.threat-composer/20260331-1834/components/dataflowDescription.tc.json +++ b/.threat-composer/20260331-1834/components/dataflowDescription.tc.json @@ -123,4 +123,4 @@ "threats": [], "mitigations": [], "mitigationLinks": [] -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/components/mitigations.tc.json b/.threat-composer/20260331-1834/components/mitigations.tc.json index f545c15..2e7f1e0 100644 --- a/.threat-composer/20260331-1834/components/mitigations.tc.json +++ b/.threat-composer/20260331-1834/components/mitigations.tc.json @@ -450,4 +450,4 @@ "linkedId": "30b38afc-9930-4602-8637-56ddb166d2a5" } ] -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/components/threats.tc.json b/.threat-composer/20260331-1834/components/threats.tc.json index 81002bd..a87d03f 100644 --- a/.threat-composer/20260331-1834/components/threats.tc.json +++ b/.threat-composer/20260331-1834/components/threats.tc.json @@ -741,4 +741,4 @@ ], "mitigations": [], "mitigationLinks": [] -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/config/config.json b/.threat-composer/20260331-1834/config/config.json index c0c5b23..4d298ae 100644 --- a/.threat-composer/20260331-1834/config/config.json +++ b/.threat-composer/20260331-1834/config/config.json @@ -18,4 +18,4 @@ "show_tool_use": true, "agent_auto_context": true } -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/config/environment-vars.json b/.threat-composer/20260331-1834/config/environment-vars.json index c138373..0affec2 100644 --- a/.threat-composer/20260331-1834/config/environment-vars.json +++ b/.threat-composer/20260331-1834/config/environment-vars.json @@ -14,4 +14,4 @@ "THREAT_COMPOSER_AI_GENERATED_TAG": null }, "note": "Only non-sensitive environment variables are logged. Credentials and secrets are never exported." -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/config/run-metadata.json b/.threat-composer/20260331-1834/config/run-metadata.json index ba0d18b..d489f40 100644 --- a/.threat-composer/20260331-1834/config/run-metadata.json +++ b/.threat-composer/20260331-1834/config/run-metadata.json @@ -34,4 +34,4 @@ "output_tokens": 26992, "total_tokens": 1254413 } -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/applicationInfo.tc.json.hash b/.threat-composer/20260331-1834/hashes/applicationInfo.tc.json.hash index 20f7cd1..64dd2ae 100644 --- a/.threat-composer/20260331-1834/hashes/applicationInfo.tc.json.hash +++ b/.threat-composer/20260331-1834/hashes/applicationInfo.tc.json.hash @@ -1,4 +1,4 @@ { "hash": "sha256:8e04446db0fa8d5b2691dac847b5f154dd190b6ef6d9cebbba72f2bf46baf02d", "timestamp": "2026-03-31T18:36:37.928352Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/architectureDescription.tc.json.hash b/.threat-composer/20260331-1834/hashes/architectureDescription.tc.json.hash index 9ff55d7..59248d8 100644 --- a/.threat-composer/20260331-1834/hashes/architectureDescription.tc.json.hash +++ b/.threat-composer/20260331-1834/hashes/architectureDescription.tc.json.hash @@ -1,4 +1,4 @@ { "hash": "sha256:b771f3e8d9a92e49a20ccc5d927ce42c87a520a65bfbb5bdbd7f0580b310fe34", "timestamp": "2026-03-31T18:39:40.535180Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/architectureDiagram.svg.hash b/.threat-composer/20260331-1834/hashes/architectureDiagram.svg.hash index 54372a6..77bf538 100644 --- a/.threat-composer/20260331-1834/hashes/architectureDiagram.svg.hash +++ b/.threat-composer/20260331-1834/hashes/architectureDiagram.svg.hash @@ -1,4 +1,4 @@ { "hash": "sha256:83fe0f76a33b1d0a4f1d0b4077e444f184873432c996fa947f654b9c7b037aeb", "timestamp": "2026-03-31T18:40:29.327880Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/dataflowDescription.tc.json.hash b/.threat-composer/20260331-1834/hashes/dataflowDescription.tc.json.hash index 97d651b..6bfea61 100644 --- a/.threat-composer/20260331-1834/hashes/dataflowDescription.tc.json.hash +++ b/.threat-composer/20260331-1834/hashes/dataflowDescription.tc.json.hash @@ -1,4 +1,4 @@ { "hash": "sha256:4c8d99ef15fbfa1ebad8fcff8de40d48899924259f5b663fefd242d80b1aa939", "timestamp": "2026-03-31T18:42:33.090247Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/dataflowDiagram.svg.hash b/.threat-composer/20260331-1834/hashes/dataflowDiagram.svg.hash index 5f74e6f..a44f80a 100644 --- a/.threat-composer/20260331-1834/hashes/dataflowDiagram.svg.hash +++ b/.threat-composer/20260331-1834/hashes/dataflowDiagram.svg.hash @@ -1,4 +1,4 @@ { "hash": "sha256:7ad487991f9f3486f5cc86a4919f22b2c6d9e3b9947ade2756c2baac6e023401", "timestamp": "2026-03-31T18:43:01.992971Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/mitigations.tc.json.hash b/.threat-composer/20260331-1834/hashes/mitigations.tc.json.hash index faf81ae..b247dde 100644 --- a/.threat-composer/20260331-1834/hashes/mitigations.tc.json.hash +++ b/.threat-composer/20260331-1834/hashes/mitigations.tc.json.hash @@ -1,4 +1,4 @@ { "hash": "sha256:d8861d31dbabf23236dd0b86b2eb8cf27f567c60a2f31076750249f1c1fdc5d6", "timestamp": "2026-03-31T18:48:46.207662Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/hashes/threats.tc.json.hash b/.threat-composer/20260331-1834/hashes/threats.tc.json.hash index 11a4d43..4de67b4 100644 --- a/.threat-composer/20260331-1834/hashes/threats.tc.json.hash +++ b/.threat-composer/20260331-1834/hashes/threats.tc.json.hash @@ -1,4 +1,4 @@ { "hash": "sha256:4a3e44367ba33cefafd2fe22c44b2db73abd9bb839746014dd1f64bd57c4061e", "timestamp": "2026-03-31T18:45:20.201511Z" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/session_20260331-1834/multi_agents/multi_agent_default_graph/multi_agent.json b/.threat-composer/20260331-1834/session_20260331-1834/multi_agents/multi_agent_default_graph/multi_agent.json index fb2319a..d87888f 100644 --- a/.threat-composer/20260331-1834/session_20260331-1834/multi_agents/multi_agent_default_graph/multi_agent.json +++ b/.threat-composer/20260331-1834/session_20260331-1834/multi_agents/multi_agent_default_graph/multi_agent.json @@ -259,4 +259,4 @@ "activated": false } } -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/session_20260331-1834/session.json b/.threat-composer/20260331-1834/session_20260331-1834/session.json index b64140f..6692da9 100644 --- a/.threat-composer/20260331-1834/session_20260331-1834/session.json +++ b/.threat-composer/20260331-1834/session_20260331-1834/session.json @@ -3,4 +3,4 @@ "session_type": "AGENT", "created_at": "2026-03-31T18:34:16.261021+00:00", "updated_at": "2026-03-31T18:34:16.261028+00:00" -} \ No newline at end of file +} diff --git a/.threat-composer/20260331-1834/threatmodel.tc.json b/.threat-composer/20260331-1834/threatmodel.tc.json index e1d8e7f..57627b1 100644 --- a/.threat-composer/20260331-1834/threatmodel.tc.json +++ b/.threat-composer/20260331-1834/threatmodel.tc.json @@ -1990,4 +1990,4 @@ ] } ] -} \ No newline at end of file +} diff --git a/AGENTS.md b/AGENTS.md index a622d13..89b1a99 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,7 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task. - Running raw **`jest`/`tsc`/`cdk`** from muscle memory — prefer **`mise //cdk:test`**, **`mise //cdk:compile`**, **`mise //cdk:synth`** (see [Commands you can use](#commands-you-can-use)). - **`MISE_EXPERIMENTAL=1`** — required for namespaced tasks like **`mise //cdk:build`** (see [CONTRIBUTING.md](./CONTRIBUTING.md)). - **`mise run build`** runs **`//agent:quality`** before CDK — the deployed image bundles **`agent/`**; agent changes belong in that tree. +- **`prek install`** fails if Git **`core.hooksPath`** is set — another hook manager owns hooks; see [CONTRIBUTING.md](./CONTRIBUTING.md). ### Tech stack @@ -105,6 +106,8 @@ Run `mise tasks --all` (with `MISE_EXPERIMENTAL=1`) for the full list. Common co - **`mise run security:deps`** — OSV Scanner on **`yarn.lock`** (all JS workspaces) and **`agent/uv.lock`**. - **`mise run security`** — Runs **`security:secrets`** then **`security:sast`**. - **`mise run security:retire`** — Retire.js on CDK, CLI, and docs packages. +- **`mise run hooks:install`** — Re-install **[prek](https://github.com/j178/prek)** git hooks (also run automatically at the end of **`mise run install`** inside a Git checkout). See [CONTRIBUTING.md](./CONTRIBUTING.md) if `core.hooksPath` blocks install. +- **`mise run hooks:run`** — Run the same **pre-commit** and **pre-push** hook stages on all files (local verification). Use these instead of running `tsc`, `jest`, or `cdk` directly when possible, so the project's scripts and config stay consistent. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index abfab6c..98998c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,6 +50,29 @@ This repository uses [mise](https://mise.jdx.dev/) for tool versions and tasks. Project configuration is hand-owned in this repository. Prefer `mise` tasks from the repo root (`mise run install`, `mise run build`) or package-level tasks (`mise //cdk:build`, `mise //cli:build`, `mise //docs:build`). +### Git hooks ([prek](https://github.com/j178/prek)) + +**`mise run install`** already runs **`prek install --prepare-hooks`** when the current directory is inside a **Git** working tree (it is skipped if there is no `.git`, e.g. a source tarball). [`prek`](https://github.com/j178/prek) is pinned in the root **`mise.toml`** and reads **`.pre-commit-config.yaml`**. + +Re-apply hook shims after you change hook config or if install was skipped: + +```bash +mise run hooks:install +``` + +| Stage | What runs | +|-------|-----------| +| **pre-commit** | Trailing whitespace / EOF / merge-conflict / YAML+JSON checks; **gitleaks** on **staged** changes only; **eslint** (cdk, cli), **ruff** (agent), **astro check** (docs) when matching paths are touched. | +| **pre-push** | **`mise run security`** — same as the root security task (gitleaks, OSV, Semgrep, Grype, Retire.js, agent Bandit + image scan when Docker is available). | + +Dry-run or reproduce locally without committing: + +```bash +mise run hooks:run +``` + +If **`prek install`** exits with *refusing to install hooks with `core.hooksPath` set* — another tool owns your hooks. Either unset it (`git config --unset-all core.hooksPath` for **local** and/or **global**) or integrate these checks into that hook manager instead. + ### Step 1: Open Issue If there isn't one already, open an issue describing what you intend to contribute. It's useful to communicate in advance, because sometimes, someone is already working in this space, so maybe it's worth collaborating with them instead of duplicating the efforts. diff --git a/README.md b/README.md index ed997e2..4e80c7f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Autonomous Background Coding Agents on AWS - +

diff --git a/agent/.python_version b/agent/.python_version index 3a4f41e..24ee5b1 100644 --- a/agent/.python_version +++ b/agent/.python_version @@ -1 +1 @@ -3.13 \ No newline at end of file +3.13 diff --git a/cdk/header.js b/cdk/header.js index 447a486..dab76e1 100644 --- a/cdk/header.js +++ b/cdk/header.js @@ -15,4 +15,4 @@ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. - */ \ No newline at end of file + */ diff --git a/docs/README.md b/docs/README.md index b3fa7dd..23279d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1 +1 @@ -# replace this \ No newline at end of file +# replace this diff --git a/docs/design/API_CONTRACT.md b/docs/design/API_CONTRACT.md index 41bb83a..2946981 100644 --- a/docs/design/API_CONTRACT.md +++ b/docs/design/API_CONTRACT.md @@ -661,4 +661,3 @@ The API is implemented as an **Amazon API Gateway REST API** (or HTTP API) with ### Relationship to internal message schema The API request/response schemas defined here are the **external** contract. The input gateway normalizes API requests into the **internal message schema** (see [INPUT_GATEWAY.md](./INPUT_GATEWAY.md)) before dispatching to the task pipeline. The internal schema may include additional fields (e.g. `channel_metadata`, `normalized_at`) that are not exposed in the API. - diff --git a/docs/design/ARCHITECTURE.md b/docs/design/ARCHITECTURE.md index 7db666c..fabba88 100644 --- a/docs/design/ARCHITECTURE.md +++ b/docs/design/ARCHITECTURE.md @@ -211,4 +211,4 @@ Different tasks and repos may benefit from different models. The `model_id` fiel - **Implementation tasks (`new_task`):** Claude Sonnet 4 (good balance of quality and cost) - **PR iteration tasks (`pr_iteration`):** Claude Sonnet 4 (needs to understand review feedback and make code changes — similar complexity to implementation) - **PR review tasks (`pr_review`):** Claude Haiku (fast, cheap — review is read-only analysis) -- **Complex/critical repos:** Claude Opus 4 (highest quality, highest cost — opt-in per repo) \ No newline at end of file +- **Complex/critical repos:** Claude Opus 4 (highest quality, highest cost — opt-in per repo) diff --git a/docs/design/INPUT_GATEWAY.md b/docs/design/INPUT_GATEWAY.md index f1e37e8..b279ffc 100644 --- a/docs/design/INPUT_GATEWAY.md +++ b/docs/design/INPUT_GATEWAY.md @@ -28,39 +28,39 @@ In short: **every input channel connects through this central point; the gateway ### Inbound (requests from users) -- **Single entry point** +- **Single entry point** All channels must go through the gateway. No channel should talk directly to task storage or orchestration. -- **Channel-specific authentication and verification** +- **Channel-specific authentication and verification** Each channel has its own way to prove legitimacy (Cognito JWT, Slack signing secret, webhook secrets, etc.). The gateway (or per-channel adapters) must verify every request before processing. -- **Normalization to an internal message schema** +- **Normalization to an internal message schema** Every channel-specific payload must be transformed into the same internal message structure. The rest of the system only ever sees this normalized form. -- **Validation** +- **Validation** The gateway must validate normalized messages (required fields, types, allowed actions, target repo/issue refs, size limits) and reject malformed or invalid requests with clear errors. -- **Access control** +- **Access control** The gateway enforces who can do what (e.g. only the task owner can cancel; only authenticated users can create tasks). This may be defined per channel or globally. -- **Support for multiple action types** +- **Support for multiple action types** At minimum: create task, get task(s), cancel task. If the product supports human-in-the-loop, add approve/reject and possibly free-form message. The internal schema must represent these distinctly. -- **Multi-modal input** +- **Multi-modal input** Users can send text and, where the channel allows it, images or other attachments. The internal message format must carry these in a channel-agnostic way (e.g. type + URL or inline data). -- **Channel metadata preservation** +- **Channel metadata preservation** Enough channel-specific metadata (e.g. Slack channel + thread, CLI request id) must be stored with the task so that outbound notifications can be delivered to the right place. ### Outbound (notifications to users) -- **Single internal notification format** +- **Single internal notification format** The core emits one canonical structure for all outbound events (e.g. status change, task completed, error, approval requested). Channel adapters consume only this. -- **Channel-specific rendering and delivery** +- **Channel-specific rendering and delivery** Each channel gets a renderer that turns the internal notification into the right format (Slack blocks, CLI text, email HTML, etc.) and sends it using the channel’s API or protocol. -- **Routing and preferences** +- **Routing and preferences** The system must know where to send notifications (e.g. only to the channel the task was created from, or to multiple channels per user preferences). Routing rules are part of the gateway/notification design, not of the core task logic. ### User channel preferences (future) @@ -90,22 +90,22 @@ MVP can use **implicit routing**: send notifications only to the channel the tas The gateway defines a single **internal message** format that all channels produce. The rest of the system (task creation, orchestration) depends only on this. The following is a conceptual schema, not an implementation spec. -- **Message identity** +- **Message identity** A unique id (e.g. ULID) for deduplication and tracing. - **Channel source** Which channel the message came from (e.g. `api`, `webhook`, `slack`, `web`, `github_actions`). -- **Channel metadata** +- **Channel metadata** Opaque or structured data needed to route replies (e.g. Slack channel id, thread ts; CLI session or request id). Stored with the task for outbound. -- **User identity** +- **User identity** A stable platform user id (e.g. Cognito sub or mapped id). All channels must map to this so authorization and “my tasks” work consistently. -- **Action type** +- **Action type** One of: create task, get task(s), get one task, cancel task, approve/reject (if HITL), or other defined actions. -- **Payload** +- **Payload** Action-specific data, for example: - **Create task:** user message text, repo URL or org/repo, issue/PR ref (e.g. issue number), optional attachments (images, files) with type and URL or inline data. - **Cancel / approve:** task id, and for approve: approval decision and optional response text. @@ -118,16 +118,16 @@ Validation rules (e.g. required fields per action, max message length, allowed U When the core needs to notify the user, it produces a single **internal notification** format. Channel adapters turn this into Slack messages, CLI output, emails, etc. -- **Notification identity** +- **Notification identity** Unique id for the notification. -- **Task and user** +- **Task and user** Task id and user id so adapters can route and filter. -- **Notification type** +- **Notification type** E.g. status change, task completed, error, approval requested, log or progress update. -- **Payload** +- **Payload** Type-specific content: status value, short message, approval question, PR URL, error message, log snippet, etc. Adapters are responsible for rendering this into channel-specific formats (e.g. Slack Block Kit, plain text for CLI) and delivering via the channel’s API or protocol. @@ -140,35 +140,35 @@ Adapters are responsible for rendering this into channel-specific formats (e.g. - User runs: `bgagent submit --repo org/myapp --issue 42` (and optionally adds a message or attachment). - The CLI sends an HTTP request to the gateway with Cognito JWT. -- **Gateway (inbound):** - - Verifies the JWT. - - Normalizes the request into the internal message: action = create task, repo = org/myapp, issue_ref = 42, user message from args, channel_source = cli, user_id from JWT. - - Validates required fields and allowed values. +- **Gateway (inbound):** + - Verifies the JWT. + - Normalizes the request into the internal message: action = create task, repo = org/myapp, issue_ref = 42, user message from args, channel_source = cli, user_id from JWT. + - Validates required fields and allowed values. - Dispatches to the task pipeline (create task). - The task pipeline creates the task and starts orchestration. Later, when status changes or the task completes, the core emits internal notifications. -- **Gateway (outbound):** +- **Gateway (outbound):** In MVP with CLI-only, “outbound” may be implicit (e.g. user polls `GET /tasks/{id}` and sees status in the response). When push is added, an adapter could stream or push these notifications to the CLI (e.g. over WebSocket or SSE). ### Example 2: User checks status from the CLI - User runs: `bgagent status abc-123`. - CLI sends `GET /tasks/abc-123` with Cognito JWT. -- **Gateway:** +- **Gateway:** Verifies JWT, normalizes to internal “get one task” action with task_id = abc-123 and user_id from JWT, validates, dispatches. The handler loads the task, enforces that the user owns it, and returns status (and optionally PR URL, error message, etc.) in a consistent response format. The CLI renders that as text. ### Example 3: User cancels a task - User runs: `bgagent cancel abc-123`. -- **Gateway:** +- **Gateway:** Verifies JWT, normalizes to “cancel task” with task_id and user_id, validates ownership (or delegates to a downstream service), dispatches. The task pipeline marks the task cancelled and stops the agent run. Outbound notifications (if any) can inform the user that the task was cancelled. ### Example 4: Future — User submits a task from Slack - User sends: “Implement the feature from issue #42 in org/myapp” in a Slack channel (or via a slash command). - Slack sends an HTTP POST to the gateway (e.g. `/channels/slack/events`) with its own signing and payload. -- **Gateway (inbound):** +- **Gateway (inbound):** Verifies Slack signing secret, normalizes to the same internal message: action = create task, repo = org/myapp, issue_ref = 42, user message from Slack text, channel_source = slack, channel_metadata = { channel_id, thread_ts }, user_id = mapped from Slack user (e.g. via a Slack→Cognito or Slack→platform-user mapping). Validates and dispatches. -- **Gateway (outbound):** +- **Gateway (outbound):** When the task completes or needs approval, the core emits an internal notification. The Slack adapter renders it (e.g. Block Kit with “Task completed” and PR link, or approval buttons), and sends it to the right channel/thread using the stored channel_metadata. ### Example 5: Same user, different channels diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md index 08fc5a7..c4f32a9 100644 --- a/docs/guides/DEVELOPER_GUIDE.md +++ b/docs/guides/DEVELOPER_GUIDE.md @@ -80,10 +80,10 @@ cd sample-autonomous-cloud-coding-agents - [AWS CLI](https://aws.amazon.com/cli/): configure your credentials ``` -aws configure --profile [your-profile] +aws configure --profile [your-profile] AWS Access Key ID [None]: xxxxxx AWS Secret Access Key [None]:yyyyyyyyyy -Default region name [None]: us-east-1 +Default region name [None]: us-east-1 Default output format [None]: json ``` @@ -471,4 +471,4 @@ cdk/test/ ├── repo-config.test.ts ├── response.test.ts └── validation.test.ts -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/design/Api-contract.md b/docs/src/content/docs/design/Api-contract.md index 1586441..528823d 100644 --- a/docs/src/content/docs/design/Api-contract.md +++ b/docs/src/content/docs/design/Api-contract.md @@ -665,4 +665,3 @@ The API is implemented as an **Amazon API Gateway REST API** (or HTTP API) with ### Relationship to internal message schema The API request/response schemas defined here are the **external** contract. The input gateway normalizes API requests into the **internal message schema** (see [INPUT_GATEWAY.md](/design/input-gateway)) before dispatching to the task pipeline. The internal schema may include additional fields (e.g. `channel_metadata`, `normalized_at`) that are not exposed in the API. - diff --git a/docs/src/content/docs/design/Architecture.md b/docs/src/content/docs/design/Architecture.md index 9504b89..3d3de1a 100644 --- a/docs/src/content/docs/design/Architecture.md +++ b/docs/src/content/docs/design/Architecture.md @@ -215,4 +215,4 @@ Different tasks and repos may benefit from different models. The `model_id` fiel - **Implementation tasks (`new_task`):** Claude Sonnet 4 (good balance of quality and cost) - **PR iteration tasks (`pr_iteration`):** Claude Sonnet 4 (needs to understand review feedback and make code changes — similar complexity to implementation) - **PR review tasks (`pr_review`):** Claude Haiku (fast, cheap — review is read-only analysis) -- **Complex/critical repos:** Claude Opus 4 (highest quality, highest cost — opt-in per repo) \ No newline at end of file +- **Complex/critical repos:** Claude Opus 4 (highest quality, highest cost — opt-in per repo) diff --git a/docs/src/content/docs/design/Input-gateway.md b/docs/src/content/docs/design/Input-gateway.md index 2f1b3cd..db89e53 100644 --- a/docs/src/content/docs/design/Input-gateway.md +++ b/docs/src/content/docs/design/Input-gateway.md @@ -32,39 +32,39 @@ In short: **every input channel connects through this central point; the gateway ### Inbound (requests from users) -- **Single entry point** +- **Single entry point** All channels must go through the gateway. No channel should talk directly to task storage or orchestration. -- **Channel-specific authentication and verification** +- **Channel-specific authentication and verification** Each channel has its own way to prove legitimacy (Cognito JWT, Slack signing secret, webhook secrets, etc.). The gateway (or per-channel adapters) must verify every request before processing. -- **Normalization to an internal message schema** +- **Normalization to an internal message schema** Every channel-specific payload must be transformed into the same internal message structure. The rest of the system only ever sees this normalized form. -- **Validation** +- **Validation** The gateway must validate normalized messages (required fields, types, allowed actions, target repo/issue refs, size limits) and reject malformed or invalid requests with clear errors. -- **Access control** +- **Access control** The gateway enforces who can do what (e.g. only the task owner can cancel; only authenticated users can create tasks). This may be defined per channel or globally. -- **Support for multiple action types** +- **Support for multiple action types** At minimum: create task, get task(s), cancel task. If the product supports human-in-the-loop, add approve/reject and possibly free-form message. The internal schema must represent these distinctly. -- **Multi-modal input** +- **Multi-modal input** Users can send text and, where the channel allows it, images or other attachments. The internal message format must carry these in a channel-agnostic way (e.g. type + URL or inline data). -- **Channel metadata preservation** +- **Channel metadata preservation** Enough channel-specific metadata (e.g. Slack channel + thread, CLI request id) must be stored with the task so that outbound notifications can be delivered to the right place. ### Outbound (notifications to users) -- **Single internal notification format** +- **Single internal notification format** The core emits one canonical structure for all outbound events (e.g. status change, task completed, error, approval requested). Channel adapters consume only this. -- **Channel-specific rendering and delivery** +- **Channel-specific rendering and delivery** Each channel gets a renderer that turns the internal notification into the right format (Slack blocks, CLI text, email HTML, etc.) and sends it using the channel’s API or protocol. -- **Routing and preferences** +- **Routing and preferences** The system must know where to send notifications (e.g. only to the channel the task was created from, or to multiple channels per user preferences). Routing rules are part of the gateway/notification design, not of the core task logic. ### User channel preferences (future) @@ -94,22 +94,22 @@ MVP can use **implicit routing**: send notifications only to the channel the tas The gateway defines a single **internal message** format that all channels produce. The rest of the system (task creation, orchestration) depends only on this. The following is a conceptual schema, not an implementation spec. -- **Message identity** +- **Message identity** A unique id (e.g. ULID) for deduplication and tracing. - **Channel source** Which channel the message came from (e.g. `api`, `webhook`, `slack`, `web`, `github_actions`). -- **Channel metadata** +- **Channel metadata** Opaque or structured data needed to route replies (e.g. Slack channel id, thread ts; CLI session or request id). Stored with the task for outbound. -- **User identity** +- **User identity** A stable platform user id (e.g. Cognito sub or mapped id). All channels must map to this so authorization and “my tasks” work consistently. -- **Action type** +- **Action type** One of: create task, get task(s), get one task, cancel task, approve/reject (if HITL), or other defined actions. -- **Payload** +- **Payload** Action-specific data, for example: - **Create task:** user message text, repo URL or org/repo, issue/PR ref (e.g. issue number), optional attachments (images, files) with type and URL or inline data. - **Cancel / approve:** task id, and for approve: approval decision and optional response text. @@ -122,16 +122,16 @@ Validation rules (e.g. required fields per action, max message length, allowed U When the core needs to notify the user, it produces a single **internal notification** format. Channel adapters turn this into Slack messages, CLI output, emails, etc. -- **Notification identity** +- **Notification identity** Unique id for the notification. -- **Task and user** +- **Task and user** Task id and user id so adapters can route and filter. -- **Notification type** +- **Notification type** E.g. status change, task completed, error, approval requested, log or progress update. -- **Payload** +- **Payload** Type-specific content: status value, short message, approval question, PR URL, error message, log snippet, etc. Adapters are responsible for rendering this into channel-specific formats (e.g. Slack Block Kit, plain text for CLI) and delivering via the channel’s API or protocol. @@ -144,35 +144,35 @@ Adapters are responsible for rendering this into channel-specific formats (e.g. - User runs: `bgagent submit --repo org/myapp --issue 42` (and optionally adds a message or attachment). - The CLI sends an HTTP request to the gateway with Cognito JWT. -- **Gateway (inbound):** - - Verifies the JWT. - - Normalizes the request into the internal message: action = create task, repo = org/myapp, issue_ref = 42, user message from args, channel_source = cli, user_id from JWT. - - Validates required fields and allowed values. +- **Gateway (inbound):** + - Verifies the JWT. + - Normalizes the request into the internal message: action = create task, repo = org/myapp, issue_ref = 42, user message from args, channel_source = cli, user_id from JWT. + - Validates required fields and allowed values. - Dispatches to the task pipeline (create task). - The task pipeline creates the task and starts orchestration. Later, when status changes or the task completes, the core emits internal notifications. -- **Gateway (outbound):** +- **Gateway (outbound):** In MVP with CLI-only, “outbound” may be implicit (e.g. user polls `GET /tasks/{id}` and sees status in the response). When push is added, an adapter could stream or push these notifications to the CLI (e.g. over WebSocket or SSE). ### Example 2: User checks status from the CLI - User runs: `bgagent status abc-123`. - CLI sends `GET /tasks/abc-123` with Cognito JWT. -- **Gateway:** +- **Gateway:** Verifies JWT, normalizes to internal “get one task” action with task_id = abc-123 and user_id from JWT, validates, dispatches. The handler loads the task, enforces that the user owns it, and returns status (and optionally PR URL, error message, etc.) in a consistent response format. The CLI renders that as text. ### Example 3: User cancels a task - User runs: `bgagent cancel abc-123`. -- **Gateway:** +- **Gateway:** Verifies JWT, normalizes to “cancel task” with task_id and user_id, validates ownership (or delegates to a downstream service), dispatches. The task pipeline marks the task cancelled and stops the agent run. Outbound notifications (if any) can inform the user that the task was cancelled. ### Example 4: Future — User submits a task from Slack - User sends: “Implement the feature from issue #42 in org/myapp” in a Slack channel (or via a slash command). - Slack sends an HTTP POST to the gateway (e.g. `/channels/slack/events`) with its own signing and payload. -- **Gateway (inbound):** +- **Gateway (inbound):** Verifies Slack signing secret, normalizes to the same internal message: action = create task, repo = org/myapp, issue_ref = 42, user message from Slack text, channel_source = slack, channel_metadata = { channel_id, thread_ts }, user_id = mapped from Slack user (e.g. via a Slack→Cognito or Slack→platform-user mapping). Validates and dispatches. -- **Gateway (outbound):** +- **Gateway (outbound):** When the task completes or needs approval, the core emits an internal notification. The Slack adapter renders it (e.g. Block Kit with “Task completed” and PR link, or approval buttons), and sends it to the right channel/thread using the stored channel_metadata. ### Example 5: Same user, different channels diff --git a/docs/src/content/docs/developer-guide/Contributing.md b/docs/src/content/docs/developer-guide/Contributing.md index 21ab021..1b3dc7e 100644 --- a/docs/src/content/docs/developer-guide/Contributing.md +++ b/docs/src/content/docs/developer-guide/Contributing.md @@ -54,6 +54,29 @@ This repository uses [mise](https://mise.jdx.dev/) for tool versions and tasks. Project configuration is hand-owned in this repository. Prefer `mise` tasks from the repo root (`mise run install`, `mise run build`) or package-level tasks (`mise //cdk:build`, `mise //cli:build`, `mise //docs:build`). +### Git hooks ([prek](https://github.com/j178/prek)) + +**`mise run install`** already runs **`prek install --prepare-hooks`** when the current directory is inside a **Git** working tree (it is skipped if there is no `.git`, e.g. a source tarball). [`prek`](https://github.com/j178/prek) is pinned in the root **`mise.toml`** and reads **`.pre-commit-config.yaml`**. + +Re-apply hook shims after you change hook config or if install was skipped: + +```bash +mise run hooks:install +``` + +| Stage | What runs | +|-------|-----------| +| **pre-commit** | Trailing whitespace / EOF / merge-conflict / YAML+JSON checks; **gitleaks** on **staged** changes only; **eslint** (cdk, cli), **ruff** (agent), **astro check** (docs) when matching paths are touched. | +| **pre-push** | **`mise run security`** — same as the root security task (gitleaks, OSV, Semgrep, Grype, Retire.js, agent Bandit + image scan when Docker is available). | + +Dry-run or reproduce locally without committing: + +```bash +mise run hooks:run +``` + +If **`prek install`** exits with *refusing to install hooks with `core.hooksPath` set* — another tool owns your hooks. Either unset it (`git config --unset-all core.hooksPath` for **local** and/or **global**) or integrate these checks into that hook manager instead. + ### Step 1: Open Issue If there isn't one already, open an issue describing what you intend to contribute. It's useful to communicate in advance, because sometimes, someone is already working in this space, so maybe it's worth collaborating with them instead of duplicating the efforts. diff --git a/docs/src/content/docs/developer-guide/Installation.md b/docs/src/content/docs/developer-guide/Installation.md index 65e9950..0e674c7 100644 --- a/docs/src/content/docs/developer-guide/Installation.md +++ b/docs/src/content/docs/developer-guide/Installation.md @@ -15,10 +15,10 @@ cd sample-autonomous-cloud-coding-agents - [AWS CLI](https://aws.amazon.com/cli/): configure your credentials ``` -aws configure --profile [your-profile] +aws configure --profile [your-profile] AWS Access Key ID [None]: xxxxxx AWS Secret Access Key [None]:yyyyyyyyyy -Default region name [None]: us-east-1 +Default region name [None]: us-east-1 Default output format [None]: json ``` @@ -314,4 +314,4 @@ curl -s -X POST "$API_URL/tasks" \ -d '{"repo": "owner/repo", "task_description": "Test task"}' | jq . ``` -For the full API reference, see the [User guide](/user-guide/introduction). \ No newline at end of file +For the full API reference, see the [User guide](/user-guide/introduction). diff --git a/docs/src/content/docs/developer-guide/Introduction.md b/docs/src/content/docs/developer-guide/Introduction.md index b4b786a..e27e881 100644 --- a/docs/src/content/docs/developer-guide/Introduction.md +++ b/docs/src/content/docs/developer-guide/Introduction.md @@ -13,4 +13,4 @@ The repository is organized around four main pieces: - **Agent runtime code** in Python under `agent/` — runtime entrypoint, task execution loop, memory writes, observability hooks, and local container tooling. - **Infrastructure as code** in AWS CDK under `cdk/src/` — stacks, constructs, and handlers that define and deploy the platform on AWS. - **Documentation site** under `docs/` — source guides/design docs plus the generated Astro/Starlight documentation site. -- **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. \ No newline at end of file +- **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. diff --git a/docs/src/content/docs/developer-guide/Project-structure.md b/docs/src/content/docs/developer-guide/Project-structure.md index 4679f76..1d406e7 100644 --- a/docs/src/content/docs/developer-guide/Project-structure.md +++ b/docs/src/content/docs/developer-guide/Project-structure.md @@ -90,4 +90,4 @@ cdk/test/ ├── repo-config.test.ts ├── response.test.ts └── validation.test.ts -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/developer-guide/Repository-preparation.md b/docs/src/content/docs/developer-guide/Repository-preparation.md index e7ed169..cba47cd 100644 --- a/docs/src/content/docs/developer-guide/Repository-preparation.md +++ b/docs/src/content/docs/developer-guide/Repository-preparation.md @@ -38,4 +38,4 @@ If you maintain your own fork, you will typically also replace **clone URLs**, * ### 6. Make target repositories easy for the agent -Keep each repo you onboard **clear and automatable**: documented build/test commands, consistent layout, and project-level agent hints (`CLAUDE.md`, `.claude/`). See [Make your codebase AI ready](https://medium.com/@alain.krok/make-your-codebase-ai-ready-05d6a160f1d5) for practical guidance. \ No newline at end of file +Keep each repo you onboard **clear and automatable**: documented build/test commands, consistent layout, and project-level agent hints (`CLAUDE.md`, `.claude/`). See [Make your codebase AI ready](https://medium.com/@alain.krok/make-your-codebase-ai-ready-05d6a160f1d5) for practical guidance. diff --git a/docs/src/content/docs/developer-guide/Where-to-make-changes.md b/docs/src/content/docs/developer-guide/Where-to-make-changes.md index e6ca46c..9d921a4 100644 --- a/docs/src/content/docs/developer-guide/Where-to-make-changes.md +++ b/docs/src/content/docs/developer-guide/Where-to-make-changes.md @@ -12,4 +12,4 @@ Before editing, decide which part of the monorepo owns the behavior. This keeps | Agent runtime | `agent/` | Bundled into the image CDK deploys; run `mise run quality` in `agent/` or root build. | | Docs (source) | `docs/guides/`, `docs/design/` | After edits, run **`mise //docs:sync`** or **`mise //docs:build`**. Do not edit `docs/src/content/docs/` directly. | -For a concise duplicate of this table, common pitfalls, and a CDK test file map, see **[AGENTS.md](/design/agents)** at the repo root (oriented toward automation-assisted contributors). \ No newline at end of file +For a concise duplicate of this table, common pitfalls, and a CDK test file map, see **[AGENTS.md](/design/agents)** at the repo root (oriented toward automation-assisted contributors). diff --git a/docs/src/content/docs/index.md b/docs/src/content/docs/index.md index cf481bc..d39dd01 100644 --- a/docs/src/content/docs/index.md +++ b/docs/src/content/docs/index.md @@ -37,4 +37,3 @@ Each task follows a **blueprint** — a hybrid workflow that mixes deterministic 3. **Pre-flight** — fail-closed readiness checks verify GitHub API reachability and repository access before consuming compute. Doomed tasks fail fast with a clear reason (`GITHUB_UNREACHABLE`, `REPO_NOT_FOUND_OR_NO_ACCESS`) instead of burning runtime. 4. **Agent execution** — the agent runs in an isolated MicroVM with persistent session storage for select caches: clones the repo, creates a branch, edits code, commits, runs tests and lint. The orchestrator polls for completion without blocking compute. 5. **Finalization** — the orchestrator infers the result (PR created or not), runs optional validation (lint, tests), extracts learnings into memory, and updates task status. - diff --git a/docs/src/content/docs/user-guide/Authentication.md b/docs/src/content/docs/user-guide/Authentication.md index 6241073..3de9219 100644 --- a/docs/src/content/docs/user-guide/Authentication.md +++ b/docs/src/content/docs/user-guide/Authentication.md @@ -52,4 +52,4 @@ TOKEN=$(aws cognito-idp initiate-auth \ --query 'AuthenticationResult.IdToken' --output text) ``` -Use this token in the `Authorization` header for all API requests. \ No newline at end of file +Use this token in the `Authorization` header for all API requests. diff --git a/docs/src/content/docs/user-guide/Introduction.md b/docs/src/content/docs/user-guide/Introduction.md index 99217bd..3f7d75c 100644 --- a/docs/src/content/docs/user-guide/Introduction.md +++ b/docs/src/content/docs/user-guide/Introduction.md @@ -4,4 +4,4 @@ title: User guide introduction # User guide -This guide covers how to use ABCA to submit coding tasks and monitor their progress. \ No newline at end of file +This guide covers how to use ABCA to submit coding tasks and monitor their progress. diff --git a/docs/src/content/docs/user-guide/Overview.md b/docs/src/content/docs/user-guide/Overview.md index aae436b..64e374b 100644 --- a/docs/src/content/docs/user-guide/Overview.md +++ b/docs/src/content/docs/user-guide/Overview.md @@ -8,4 +8,4 @@ There are three ways to interact with the platform: 1. **CLI** (recommended) — The `bgagent` CLI authenticates via Cognito and calls the Task API. Handles login, token caching, and output formatting. 2. **REST API** (direct) — Call the Task API endpoints directly with a JWT token. Full validation, audit logging, and idempotency support. -3. **Webhook** — External systems (CI pipelines, GitHub Actions) can create tasks via HMAC-authenticated HTTP requests. No Cognito credentials needed; uses a shared secret per integration. \ No newline at end of file +3. **Webhook** — External systems (CI pipelines, GitHub Actions) can create tasks via HMAC-authenticated HTTP requests. No Cognito credentials needed; uses a shared secret per integration. diff --git a/docs/src/content/docs/user-guide/Prerequisites.md b/docs/src/content/docs/user-guide/Prerequisites.md index ac987bf..fb8ec26 100644 --- a/docs/src/content/docs/user-guide/Prerequisites.md +++ b/docs/src/content/docs/user-guide/Prerequisites.md @@ -5,4 +5,4 @@ title: Prerequisites - The CDK stack deployed (see [Developer guide](/developer-guide/introduction)) - A Cognito user account (see [Authentication](#authentication) below) - **Repositories must be onboarded** before tasks can target them (see [Repository onboarding](#repository-onboarding) below) -- For the **CLI**: Node.js installed; build the CLI with `cd cli && mise run build` \ No newline at end of file +- For the **CLI**: Node.js installed; build the CLI with `cd cli && mise run build` diff --git a/docs/src/content/docs/user-guide/Repository-onboarding.md b/docs/src/content/docs/user-guide/Repository-onboarding.md index 639c770..81519d7 100644 --- a/docs/src/content/docs/user-guide/Repository-onboarding.md +++ b/docs/src/content/docs/user-guide/Repository-onboarding.md @@ -32,4 +32,4 @@ Blueprints can configure per-repository settings that override platform defaults | `github_token_secret_arn` | Per-repo GitHub token (Secrets Manager ARN) | Platform default | | `poll_interval_ms` | Poll interval for awaiting completion (5000–300000) | 30000 | -When you specify `--max-turns` (CLI) or `max_turns` (API) on a task, your value takes precedence over the Blueprint default. If neither is specified, the platform default (100) is used. The same override pattern applies to `--max-budget` / `max_budget_usd`, except there is no platform default — if neither the task nor the Blueprint specifies a budget, no cost limit is applied. \ No newline at end of file +When you specify `--max-turns` (CLI) or `max_turns` (API) on a task, your value takes precedence over the Blueprint default. If neither is specified, the platform default (100) is used. The same override pattern applies to `--max-budget` / `max_budget_usd`, except there is no platform default — if neither the task nor the Blueprint specifies a budget, no cost limit is applied. diff --git a/docs/src/content/docs/user-guide/Task-lifecycle.md b/docs/src/content/docs/user-guide/Task-lifecycle.md index ddfc787..8049cc6 100644 --- a/docs/src/content/docs/user-guide/Task-lifecycle.md +++ b/docs/src/content/docs/user-guide/Task-lifecycle.md @@ -42,4 +42,4 @@ Each lifecycle transition is recorded as an audit event. Use the events endpoint curl "$API_URL/tasks//events" -H "Authorization: $TOKEN" ``` -Events include: `task_created`, `admission_rejected`, `preflight_failed`, `hydration_started`, `hydration_complete`, `session_started`, `pr_created`, `pr_updated`, `task_completed`, `task_failed`, `task_cancelled`, `task_timed_out`. Event records are subject to the same 90-day retention as task records and are automatically deleted after that period. \ No newline at end of file +Events include: `task_created`, `admission_rejected`, `preflight_failed`, `hydration_started`, `hydration_complete`, `session_started`, `pr_created`, `pr_updated`, `task_completed`, `task_failed`, `task_cancelled`, `task_timed_out`. Event records are subject to the same 90-day retention as task records and are automatically deleted after that period. diff --git a/docs/src/content/docs/user-guide/Tips.md b/docs/src/content/docs/user-guide/Tips.md index 55b84c2..c2bef49 100644 --- a/docs/src/content/docs/user-guide/Tips.md +++ b/docs/src/content/docs/user-guide/Tips.md @@ -7,4 +7,4 @@ title: Tips - **Add a CLAUDE.md**: The agent automatically loads project-level configuration from your repository — `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, `.claude/agents/`, and `.mcp.json`. Use these to provide project-specific build commands, conventions, constraints, custom subagents, and architecture notes. See the [Prompt guide](/user-guide/prompt-guide#repo-level-customization) for details and examples. - **Issue vs text**: When using `--issue` (CLI) or `issue_number` (API), the agent fetches the full issue body from GitHub, including any labels, comments, and linked context. This is usually better than a short text description. - **Cost**: Cost depends on the model and number of turns. Use `--max-turns` (CLI) or `max_turns` (API) to cap the number of agent iterations per task (range: 1–500). If not specified, the per-repo Blueprint default applies, falling back to the platform default (100). Use `--max-budget` (CLI) or `max_budget_usd` (API) to set a hard cost limit in USD ($0.01–$100) — when the budget is reached, the agent stops regardless of remaining turns. If no budget is specified, the per-repo Blueprint default applies; if that is also absent, no cost limit is enforced. Check the task status after completion to see the reported cost. -- **Idempotency**: Use the `Idempotency-Key` header when creating tasks via the API to safely retry requests without creating duplicate tasks. \ No newline at end of file +- **Idempotency**: Use the `Idempotency-Key` header when creating tasks via the API to safely retry requests without creating duplicate tasks. diff --git a/docs/src/content/docs/user-guide/Using-the-cli.md b/docs/src/content/docs/user-guide/Using-the-cli.md index d721420..73c8eb0 100644 --- a/docs/src/content/docs/user-guide/Using-the-cli.md +++ b/docs/src/content/docs/user-guide/Using-the-cli.md @@ -133,4 +133,4 @@ node lib/bin/bgagent.js events --limit 20 ```bash node lib/bin/bgagent.js cancel -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/user-guide/Using-the-rest-api.md b/docs/src/content/docs/user-guide/Using-the-rest-api.md index 526c7b6..8a21590 100644 --- a/docs/src/content/docs/user-guide/Using-the-rest-api.md +++ b/docs/src/content/docs/user-guide/Using-the-rest-api.md @@ -160,4 +160,4 @@ Transitions the task to `CANCELLED` and records a cancellation event. Only tasks curl "$API_URL/tasks//events" -H "Authorization: $TOKEN" ``` -Returns the chronological event log for a task (e.g., `task_created`, `session_started`, `task_completed`). Supports `limit` and `next_token` pagination parameters. \ No newline at end of file +Returns the chronological event log for a task (e.g., `task_created`, `session_started`, `task_completed`). Supports `limit` and `next_token` pagination parameters. diff --git a/docs/src/content/docs/user-guide/Viewing-logs.md b/docs/src/content/docs/user-guide/Viewing-logs.md index a438bb5..ef7e53b 100644 --- a/docs/src/content/docs/user-guide/Viewing-logs.md +++ b/docs/src/content/docs/user-guide/Viewing-logs.md @@ -10,4 +10,4 @@ Alternatively, the application logs are in the CloudWatch log group: /aws/vendedlogs/bedrock-agentcore/runtime/APPLICATION_LOGS/jean_cloude ``` -Filter by task ID to find logs for a specific task. \ No newline at end of file +Filter by task ID to find logs for a specific task. diff --git a/docs/src/content/docs/user-guide/Webhook-integration.md b/docs/src/content/docs/user-guide/Webhook-integration.md index cd898d7..a985753 100644 --- a/docs/src/content/docs/user-guide/Webhook-integration.md +++ b/docs/src/content/docs/user-guide/Webhook-integration.md @@ -98,4 +98,4 @@ Tasks created via webhook are owned by the Cognito user who created the webhook 4. The handler computes `HMAC-SHA256(secret, request_body)` and performs a constant-time comparison with the provided signature. 5. On success, the task is created under the webhook owner's identity. On failure, a `401 Unauthorized` response is returned. -**Note:** HMAC verification is performed by the handler (not the authorizer) because API Gateway REST API v1 does not pass the request body to Lambda REQUEST authorizers. Authorizer result caching is disabled (`resultsCacheTtl: 0`) because each request has a unique signature. \ No newline at end of file +**Note:** HMAC verification is performed by the handler (not the authorizer) because API Gateway REST API v1 does not pass the request body to Lambda REQUEST authorizers. Authorizer result caching is disabled (`resultsCacheTtl: 0`) because each request has a unique signature. diff --git a/docs/src/content/docs/user-guide/What-the-agent-does.md b/docs/src/content/docs/user-guide/What-the-agent-does.md index 02f564b..859e633 100644 --- a/docs/src/content/docs/user-guide/What-the-agent-does.md +++ b/docs/src/content/docs/user-guide/What-the-agent-does.md @@ -48,4 +48,4 @@ When a `pr_review` task is submitted, the agent: 8. Posts the review via the GitHub Reviews API (`gh api repos/{repo}/pulls/{pr_number}/reviews`) as a single batch review 9. Posts a summary conversation comment on the PR -The agent operates in **read-only mode** — it does not modify any files, create commits, or push changes. The `Write` and `Edit` tools are not available during `pr_review` tasks. \ No newline at end of file +The agent operates in **read-only mode** — it does not modify any files, create commits, or push changes. The `Write` and `Edit` tools are not available during `pr_review` tasks. diff --git a/mise.toml b/mise.toml index c42b88f..0f9d778 100644 --- a/mise.toml +++ b/mise.toml @@ -9,6 +9,7 @@ experimental = true [tools] node = "22" +prek = "0.3.8" gitleaks = "latest" semgrep = "latest" osv-scanner = "latest" @@ -24,10 +25,12 @@ config_roots = ["cdk", "agent", "cli", "docs"] # One `yarn install` at the repo root installs every Yarn workspace (`cdk`, `cli`, `docs`). # `//cdk:install`, `//cli:install`, and `//docs:install` are thin wrappers around the same command. [tasks.install] -description = "Yarn workspaces (cdk, cli, docs) + agent Python (uv)" +description = "Yarn workspaces (cdk, cli, docs) + agent Python (uv) + prek git hooks when inside a Git repo" run = [ "yarn install --check-files", "cd agent && mise run install", + # Install prek shims only in a real checkout (skip tarballs / no-.git environments). + "bash -c 'git rev-parse --git-dir >/dev/null 2>&1 || exit 0; prek install --prepare-hooks'", ] ################## @@ -51,6 +54,10 @@ run = [ description = "Scan for secrets with gitleaks" run = "gitleaks detect --source . --no-banner" +[tasks."security:secrets:staged"] +description = "gitleaks on staged changes (pre-commit hook)" +run = "gitleaks protect --staged --no-banner" + [tasks."security:sast"] description = "SAST scan with semgrep (auto + OWASP top 10)" run = "semgrep scan --config auto --config p/python --config p/typescript --config p/owasp-top-ten --config p/security-audit --error --quiet ." @@ -81,6 +88,21 @@ run = [ "MISE_EXPERIMENTAL=1 mise //agent:security", ] +################## +##### HOOKS ###### +################## + +[tasks."hooks:install"] +description = "Install or refresh prek git hooks (also runs at end of `mise run install` in a Git repo)" +run = "prek install --prepare-hooks" + +[tasks."hooks:run"] +description = "Run prek on all files (pre-commit then pre-push stages)" +run = [ + "prek run --all-files --stage pre-commit", + "prek run --all-files --stage pre-push", +] + ################## ##### BUILD ##### ################## @@ -98,4 +120,4 @@ run = [ [tasks.default] description = "Install + build" -depends = [":install", ":build"] \ No newline at end of file +depends = [":install", ":build"] From 56a230a79e1e812e9b6b88e48b8167204e3f3382 Mon Sep 17 00:00:00 2001 From: krokoko Date: Thu, 9 Apr 2026 10:48:39 -0500 Subject: [PATCH 2/2] chore(project): update hooks --- .pre-commit-config.yaml | 13 ++++++++++--- CONTRIBUTING.md | 6 +++++- .../docs/developer-guide/Contributing.md | 6 +++++- .../docs/developer-guide/Installation.md | 2 +- .../docs/developer-guide/Introduction.md | 2 +- .../docs/developer-guide/Project-structure.md | 2 +- .../developer-guide/Repository-preparation.md | 2 +- .../developer-guide/Where-to-make-changes.md | 2 +- .../content/docs/user-guide/Authentication.md | 2 +- .../content/docs/user-guide/Introduction.md | 2 +- docs/src/content/docs/user-guide/Overview.md | 2 +- .../content/docs/user-guide/Prerequisites.md | 2 +- .../docs/user-guide/Repository-onboarding.md | 2 +- .../content/docs/user-guide/Task-lifecycle.md | 2 +- docs/src/content/docs/user-guide/Tips.md | 2 +- .../content/docs/user-guide/Using-the-cli.md | 2 +- .../docs/user-guide/Using-the-rest-api.md | 2 +- .../content/docs/user-guide/Viewing-logs.md | 2 +- .../docs/user-guide/Webhook-integration.md | 2 +- .../docs/user-guide/What-the-agent-does.md | 2 +- mise.toml | 19 +++++++++++++++++++ 21 files changed, 56 insertions(+), 22 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2a1c4f5..3ff3438 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,9 +11,9 @@ repos: hooks: - id: trailing-whitespace # Skip generated trees and paths often checked in read-only (0444); mutating hooks must not touch them. - exclude: (cdk/cdk\.out/|node_modules/|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$|\.(snap|lock)$) + exclude: (cdk/cdk\.out/|node_modules/|^docs/src/content/docs/.*\.md$|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$|\.(snap|lock)$) - id: end-of-file-fixer - exclude: (cdk/cdk\.out/|node_modules/|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$) + exclude: (cdk/cdk\.out/|node_modules/|^docs/src/content/docs/.*\.md$|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$) - id: check-merge-conflict - id: check-yaml exclude: ^(cdk/cdk\.out/|cdk\.out/|node_modules/|agent/\.venv/) @@ -65,7 +65,14 @@ repos: - id: monorepo-security-pre-push name: security scans (pre-push) - entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run security' + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run hooks:pre-push:security' + language: system + pass_filenames: false + stages: [pre-push] + + - id: monorepo-tests-pre-push + name: package tests (pre-push) + entry: bash -lc 'cd "$(git rev-parse --show-toplevel)" && mise run hooks:pre-push:tests' language: system pass_filenames: false stages: [pre-push] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 98998c0..5c5edd1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,11 @@ mise run hooks:install | Stage | What runs | |-------|-----------| | **pre-commit** | Trailing whitespace / EOF / merge-conflict / YAML+JSON checks; **gitleaks** on **staged** changes only; **eslint** (cdk, cli), **ruff** (agent), **astro check** (docs) when matching paths are touched. | -| **pre-push** | **`mise run security`** — same as the root security task (gitleaks, OSV, Semgrep, Grype, Retire.js, agent Bandit + image scan when Docker is available). | +| **pre-push** | Two pre-push hooks run in order: +1. **`mise run hooks:pre-push:security`** — root security scans. +2. **`mise run hooks:pre-push:tests`** — tests in `cdk`, `cli`, and `agent` packages. + +For convenience, **`mise run hooks:pre-push`** runs both steps sequentially. | Dry-run or reproduce locally without committing: diff --git a/docs/src/content/docs/developer-guide/Contributing.md b/docs/src/content/docs/developer-guide/Contributing.md index 1b3dc7e..3a2323d 100644 --- a/docs/src/content/docs/developer-guide/Contributing.md +++ b/docs/src/content/docs/developer-guide/Contributing.md @@ -67,7 +67,11 @@ mise run hooks:install | Stage | What runs | |-------|-----------| | **pre-commit** | Trailing whitespace / EOF / merge-conflict / YAML+JSON checks; **gitleaks** on **staged** changes only; **eslint** (cdk, cli), **ruff** (agent), **astro check** (docs) when matching paths are touched. | -| **pre-push** | **`mise run security`** — same as the root security task (gitleaks, OSV, Semgrep, Grype, Retire.js, agent Bandit + image scan when Docker is available). | +| **pre-push** | Two pre-push hooks run in order: +1. **`mise run hooks:pre-push:security`** — root security scans. +2. **`mise run hooks:pre-push:tests`** — tests in `cdk`, `cli`, and `agent` packages. + +For convenience, **`mise run hooks:pre-push`** runs both steps sequentially. | Dry-run or reproduce locally without committing: diff --git a/docs/src/content/docs/developer-guide/Installation.md b/docs/src/content/docs/developer-guide/Installation.md index 0e674c7..3ee8646 100644 --- a/docs/src/content/docs/developer-guide/Installation.md +++ b/docs/src/content/docs/developer-guide/Installation.md @@ -314,4 +314,4 @@ curl -s -X POST "$API_URL/tasks" \ -d '{"repo": "owner/repo", "task_description": "Test task"}' | jq . ``` -For the full API reference, see the [User guide](/user-guide/introduction). +For the full API reference, see the [User guide](/user-guide/introduction). \ No newline at end of file diff --git a/docs/src/content/docs/developer-guide/Introduction.md b/docs/src/content/docs/developer-guide/Introduction.md index e27e881..b4b786a 100644 --- a/docs/src/content/docs/developer-guide/Introduction.md +++ b/docs/src/content/docs/developer-guide/Introduction.md @@ -13,4 +13,4 @@ The repository is organized around four main pieces: - **Agent runtime code** in Python under `agent/` — runtime entrypoint, task execution loop, memory writes, observability hooks, and local container tooling. - **Infrastructure as code** in AWS CDK under `cdk/src/` — stacks, constructs, and handlers that define and deploy the platform on AWS. - **Documentation site** under `docs/` — source guides/design docs plus the generated Astro/Starlight documentation site. -- **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. +- **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. \ No newline at end of file diff --git a/docs/src/content/docs/developer-guide/Project-structure.md b/docs/src/content/docs/developer-guide/Project-structure.md index 1d406e7..4679f76 100644 --- a/docs/src/content/docs/developer-guide/Project-structure.md +++ b/docs/src/content/docs/developer-guide/Project-structure.md @@ -90,4 +90,4 @@ cdk/test/ ├── repo-config.test.ts ├── response.test.ts └── validation.test.ts -``` +``` \ No newline at end of file diff --git a/docs/src/content/docs/developer-guide/Repository-preparation.md b/docs/src/content/docs/developer-guide/Repository-preparation.md index cba47cd..e7ed169 100644 --- a/docs/src/content/docs/developer-guide/Repository-preparation.md +++ b/docs/src/content/docs/developer-guide/Repository-preparation.md @@ -38,4 +38,4 @@ If you maintain your own fork, you will typically also replace **clone URLs**, * ### 6. Make target repositories easy for the agent -Keep each repo you onboard **clear and automatable**: documented build/test commands, consistent layout, and project-level agent hints (`CLAUDE.md`, `.claude/`). See [Make your codebase AI ready](https://medium.com/@alain.krok/make-your-codebase-ai-ready-05d6a160f1d5) for practical guidance. +Keep each repo you onboard **clear and automatable**: documented build/test commands, consistent layout, and project-level agent hints (`CLAUDE.md`, `.claude/`). See [Make your codebase AI ready](https://medium.com/@alain.krok/make-your-codebase-ai-ready-05d6a160f1d5) for practical guidance. \ No newline at end of file diff --git a/docs/src/content/docs/developer-guide/Where-to-make-changes.md b/docs/src/content/docs/developer-guide/Where-to-make-changes.md index 9d921a4..e6ca46c 100644 --- a/docs/src/content/docs/developer-guide/Where-to-make-changes.md +++ b/docs/src/content/docs/developer-guide/Where-to-make-changes.md @@ -12,4 +12,4 @@ Before editing, decide which part of the monorepo owns the behavior. This keeps | Agent runtime | `agent/` | Bundled into the image CDK deploys; run `mise run quality` in `agent/` or root build. | | Docs (source) | `docs/guides/`, `docs/design/` | After edits, run **`mise //docs:sync`** or **`mise //docs:build`**. Do not edit `docs/src/content/docs/` directly. | -For a concise duplicate of this table, common pitfalls, and a CDK test file map, see **[AGENTS.md](/design/agents)** at the repo root (oriented toward automation-assisted contributors). +For a concise duplicate of this table, common pitfalls, and a CDK test file map, see **[AGENTS.md](/design/agents)** at the repo root (oriented toward automation-assisted contributors). \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Authentication.md b/docs/src/content/docs/user-guide/Authentication.md index 3de9219..6241073 100644 --- a/docs/src/content/docs/user-guide/Authentication.md +++ b/docs/src/content/docs/user-guide/Authentication.md @@ -52,4 +52,4 @@ TOKEN=$(aws cognito-idp initiate-auth \ --query 'AuthenticationResult.IdToken' --output text) ``` -Use this token in the `Authorization` header for all API requests. +Use this token in the `Authorization` header for all API requests. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Introduction.md b/docs/src/content/docs/user-guide/Introduction.md index 3f7d75c..99217bd 100644 --- a/docs/src/content/docs/user-guide/Introduction.md +++ b/docs/src/content/docs/user-guide/Introduction.md @@ -4,4 +4,4 @@ title: User guide introduction # User guide -This guide covers how to use ABCA to submit coding tasks and monitor their progress. +This guide covers how to use ABCA to submit coding tasks and monitor their progress. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Overview.md b/docs/src/content/docs/user-guide/Overview.md index 64e374b..aae436b 100644 --- a/docs/src/content/docs/user-guide/Overview.md +++ b/docs/src/content/docs/user-guide/Overview.md @@ -8,4 +8,4 @@ There are three ways to interact with the platform: 1. **CLI** (recommended) — The `bgagent` CLI authenticates via Cognito and calls the Task API. Handles login, token caching, and output formatting. 2. **REST API** (direct) — Call the Task API endpoints directly with a JWT token. Full validation, audit logging, and idempotency support. -3. **Webhook** — External systems (CI pipelines, GitHub Actions) can create tasks via HMAC-authenticated HTTP requests. No Cognito credentials needed; uses a shared secret per integration. +3. **Webhook** — External systems (CI pipelines, GitHub Actions) can create tasks via HMAC-authenticated HTTP requests. No Cognito credentials needed; uses a shared secret per integration. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Prerequisites.md b/docs/src/content/docs/user-guide/Prerequisites.md index fb8ec26..ac987bf 100644 --- a/docs/src/content/docs/user-guide/Prerequisites.md +++ b/docs/src/content/docs/user-guide/Prerequisites.md @@ -5,4 +5,4 @@ title: Prerequisites - The CDK stack deployed (see [Developer guide](/developer-guide/introduction)) - A Cognito user account (see [Authentication](#authentication) below) - **Repositories must be onboarded** before tasks can target them (see [Repository onboarding](#repository-onboarding) below) -- For the **CLI**: Node.js installed; build the CLI with `cd cli && mise run build` +- For the **CLI**: Node.js installed; build the CLI with `cd cli && mise run build` \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Repository-onboarding.md b/docs/src/content/docs/user-guide/Repository-onboarding.md index 81519d7..639c770 100644 --- a/docs/src/content/docs/user-guide/Repository-onboarding.md +++ b/docs/src/content/docs/user-guide/Repository-onboarding.md @@ -32,4 +32,4 @@ Blueprints can configure per-repository settings that override platform defaults | `github_token_secret_arn` | Per-repo GitHub token (Secrets Manager ARN) | Platform default | | `poll_interval_ms` | Poll interval for awaiting completion (5000–300000) | 30000 | -When you specify `--max-turns` (CLI) or `max_turns` (API) on a task, your value takes precedence over the Blueprint default. If neither is specified, the platform default (100) is used. The same override pattern applies to `--max-budget` / `max_budget_usd`, except there is no platform default — if neither the task nor the Blueprint specifies a budget, no cost limit is applied. +When you specify `--max-turns` (CLI) or `max_turns` (API) on a task, your value takes precedence over the Blueprint default. If neither is specified, the platform default (100) is used. The same override pattern applies to `--max-budget` / `max_budget_usd`, except there is no platform default — if neither the task nor the Blueprint specifies a budget, no cost limit is applied. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Task-lifecycle.md b/docs/src/content/docs/user-guide/Task-lifecycle.md index 8049cc6..ddfc787 100644 --- a/docs/src/content/docs/user-guide/Task-lifecycle.md +++ b/docs/src/content/docs/user-guide/Task-lifecycle.md @@ -42,4 +42,4 @@ Each lifecycle transition is recorded as an audit event. Use the events endpoint curl "$API_URL/tasks//events" -H "Authorization: $TOKEN" ``` -Events include: `task_created`, `admission_rejected`, `preflight_failed`, `hydration_started`, `hydration_complete`, `session_started`, `pr_created`, `pr_updated`, `task_completed`, `task_failed`, `task_cancelled`, `task_timed_out`. Event records are subject to the same 90-day retention as task records and are automatically deleted after that period. +Events include: `task_created`, `admission_rejected`, `preflight_failed`, `hydration_started`, `hydration_complete`, `session_started`, `pr_created`, `pr_updated`, `task_completed`, `task_failed`, `task_cancelled`, `task_timed_out`. Event records are subject to the same 90-day retention as task records and are automatically deleted after that period. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Tips.md b/docs/src/content/docs/user-guide/Tips.md index c2bef49..55b84c2 100644 --- a/docs/src/content/docs/user-guide/Tips.md +++ b/docs/src/content/docs/user-guide/Tips.md @@ -7,4 +7,4 @@ title: Tips - **Add a CLAUDE.md**: The agent automatically loads project-level configuration from your repository — `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, `.claude/agents/`, and `.mcp.json`. Use these to provide project-specific build commands, conventions, constraints, custom subagents, and architecture notes. See the [Prompt guide](/user-guide/prompt-guide#repo-level-customization) for details and examples. - **Issue vs text**: When using `--issue` (CLI) or `issue_number` (API), the agent fetches the full issue body from GitHub, including any labels, comments, and linked context. This is usually better than a short text description. - **Cost**: Cost depends on the model and number of turns. Use `--max-turns` (CLI) or `max_turns` (API) to cap the number of agent iterations per task (range: 1–500). If not specified, the per-repo Blueprint default applies, falling back to the platform default (100). Use `--max-budget` (CLI) or `max_budget_usd` (API) to set a hard cost limit in USD ($0.01–$100) — when the budget is reached, the agent stops regardless of remaining turns. If no budget is specified, the per-repo Blueprint default applies; if that is also absent, no cost limit is enforced. Check the task status after completion to see the reported cost. -- **Idempotency**: Use the `Idempotency-Key` header when creating tasks via the API to safely retry requests without creating duplicate tasks. +- **Idempotency**: Use the `Idempotency-Key` header when creating tasks via the API to safely retry requests without creating duplicate tasks. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Using-the-cli.md b/docs/src/content/docs/user-guide/Using-the-cli.md index 73c8eb0..d721420 100644 --- a/docs/src/content/docs/user-guide/Using-the-cli.md +++ b/docs/src/content/docs/user-guide/Using-the-cli.md @@ -133,4 +133,4 @@ node lib/bin/bgagent.js events --limit 20 ```bash node lib/bin/bgagent.js cancel -``` +``` \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Using-the-rest-api.md b/docs/src/content/docs/user-guide/Using-the-rest-api.md index 8a21590..526c7b6 100644 --- a/docs/src/content/docs/user-guide/Using-the-rest-api.md +++ b/docs/src/content/docs/user-guide/Using-the-rest-api.md @@ -160,4 +160,4 @@ Transitions the task to `CANCELLED` and records a cancellation event. Only tasks curl "$API_URL/tasks//events" -H "Authorization: $TOKEN" ``` -Returns the chronological event log for a task (e.g., `task_created`, `session_started`, `task_completed`). Supports `limit` and `next_token` pagination parameters. +Returns the chronological event log for a task (e.g., `task_created`, `session_started`, `task_completed`). Supports `limit` and `next_token` pagination parameters. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Viewing-logs.md b/docs/src/content/docs/user-guide/Viewing-logs.md index ef7e53b..a438bb5 100644 --- a/docs/src/content/docs/user-guide/Viewing-logs.md +++ b/docs/src/content/docs/user-guide/Viewing-logs.md @@ -10,4 +10,4 @@ Alternatively, the application logs are in the CloudWatch log group: /aws/vendedlogs/bedrock-agentcore/runtime/APPLICATION_LOGS/jean_cloude ``` -Filter by task ID to find logs for a specific task. +Filter by task ID to find logs for a specific task. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/Webhook-integration.md b/docs/src/content/docs/user-guide/Webhook-integration.md index a985753..cd898d7 100644 --- a/docs/src/content/docs/user-guide/Webhook-integration.md +++ b/docs/src/content/docs/user-guide/Webhook-integration.md @@ -98,4 +98,4 @@ Tasks created via webhook are owned by the Cognito user who created the webhook 4. The handler computes `HMAC-SHA256(secret, request_body)` and performs a constant-time comparison with the provided signature. 5. On success, the task is created under the webhook owner's identity. On failure, a `401 Unauthorized` response is returned. -**Note:** HMAC verification is performed by the handler (not the authorizer) because API Gateway REST API v1 does not pass the request body to Lambda REQUEST authorizers. Authorizer result caching is disabled (`resultsCacheTtl: 0`) because each request has a unique signature. +**Note:** HMAC verification is performed by the handler (not the authorizer) because API Gateway REST API v1 does not pass the request body to Lambda REQUEST authorizers. Authorizer result caching is disabled (`resultsCacheTtl: 0`) because each request has a unique signature. \ No newline at end of file diff --git a/docs/src/content/docs/user-guide/What-the-agent-does.md b/docs/src/content/docs/user-guide/What-the-agent-does.md index 859e633..02f564b 100644 --- a/docs/src/content/docs/user-guide/What-the-agent-does.md +++ b/docs/src/content/docs/user-guide/What-the-agent-does.md @@ -48,4 +48,4 @@ When a `pr_review` task is submitted, the agent: 8. Posts the review via the GitHub Reviews API (`gh api repos/{repo}/pulls/{pr_number}/reviews`) as a single batch review 9. Posts a summary conversation comment on the PR -The agent operates in **read-only mode** — it does not modify any files, create commits, or push changes. The `Write` and `Edit` tools are not available during `pr_review` tasks. +The agent operates in **read-only mode** — it does not modify any files, create commits, or push changes. The `Write` and `Edit` tools are not available during `pr_review` tasks. \ No newline at end of file diff --git a/mise.toml b/mise.toml index 0f9d778..088c750 100644 --- a/mise.toml +++ b/mise.toml @@ -103,6 +103,25 @@ run = [ "prek run --all-files --stage pre-push", ] +[tasks."hooks:pre-push:security"] +description = "Pre-push security scans" +run = "mise run security" + +[tasks."hooks:pre-push:tests"] +description = "Pre-push tests in cdk/cli/agent" +run = [ + "MISE_EXPERIMENTAL=1 mise //cdk:test", + "MISE_EXPERIMENTAL=1 mise //cli:test", + "cd agent && mise run test", +] + +[tasks."hooks:pre-push"] +description = "Pre-push gate: security scans then tests in cdk/cli/agent" +run = [ + "mise run hooks:pre-push:security", + "mise run hooks:pre-push:tests", +] + ################## ##### BUILD ##### ##################