thinkwork-cli 0.12.5 → 0.12.7

package/dist/commands/enterprise/templates/deploy-repo/docs/runbook.md

@@ -5,50 +5,218 @@
 This repository deploys a pinned ThinkWork release into the customer AWS
 account. It is a deployment repository, not a source fork.
 
-## Normal Sequence
+The exact operational path is:
+
+```text
+bootstrap -> workflow dispatch -> CI deploy -> overlay apply -> smoke summary
+```
+
+## First-Time Setup
+
+Run these commands from an operator machine with temporary customer AWS admin
+access and GitHub admin access to this repository.
+
+1. Confirm access:
+
+   ```bash
+   gh auth status
+   aws sts get-caller-identity
+   ```
+
+2. Install the CLI:
+
+   ```bash
+   npm install -g thinkwork-cli
+   thinkwork --version
+   ```
+
+3. Choose the release and checksum:
+
+   ```bash
+   VERSION="$(thinkwork --version)"
+   RELEASE="v${VERSION#v}"
+   MANIFEST_URL="https://github.com/thinkwork-ai/thinkwork/releases/download/${RELEASE}/thinkwork-release.json"
+   MANIFEST_SHA256="$(curl -fsSL "$MANIFEST_URL" | shasum -a 256 | awk '{print $1}')"
+   ```
 
-1. Bootstrap the repo once:
+4. Bootstrap AWS trust, GitHub Environments, and managed repo files:
 
    ```bash
    thinkwork enterprise bootstrap . \
      --customer {{CUSTOMER_SLUG}} \
      --repo <github-owner>/<github-repo> \
      --stage dev \
-     --stage prod
+     --stage prod \
+     --region {{REGION}} \
+     --release-version "$RELEASE" \
+     --manifest-url "$MANIFEST_URL" \
+     --manifest-sha256 "$MANIFEST_SHA256" \
+     --yes
    ```
 
-2. Review GitHub Environment settings for each stage.
-3. Add required secrets such as `TF_VAR_db_password` and
-   `TF_VAR_api_auth_secret`.
-4. Dispatch `.github/workflows/deploy.yml`.
-5. CI verifies `thinkwork.lock`, prepares release artifacts, runs Terraform,
-   updates AgentCore runtimes, applies customer overlays, runs smoke checks,
-   and writes a summary artifact.
+5. Commit and push generated files:
 
-The exact operational path is:
+   ```bash
+   git add .
+   git commit -m "chore: bootstrap ThinkWork deployment repo"
+   git push
+   ```
 
-```text
-bootstrap -> workflow dispatch -> CI deploy -> overlay apply -> smoke summary
-```
+6. Set required GitHub Environment secrets for each stage:
 
-## Release Upgrades
+   ```bash
+   gh secret set TF_VAR_DB_PASSWORD \
+     --repo <github-owner>/<github-repo> \
+     --env dev \
+     --body "$DEV_DB_PASSWORD"
+
+   gh secret set TF_VAR_API_AUTH_SECRET \
+     --repo <github-owner>/<github-repo> \
+     --env dev \
+     --body "$DEV_API_AUTH_SECRET"
+   ```
+
+   Repeat for `prod` before the production deploy.
+
+7. Verify GitHub Environment variables:
+
+   ```bash
+   gh variable list --repo <github-owner>/<github-repo> --env dev
+   gh variable list --repo <github-owner>/<github-repo> --env prod
+   ```
+
+   Expected variables are `AWS_REGION`, `AWS_ROLE_ARN`, and
+   `THINKWORK_ARTIFACT_BUCKET`.
+
+8. Review stage config:
+   - `terraform/stages/dev.tfvars`
+   - `terraform/stages/prod.tfvars`
+   - `customer/deployment.json`
 
-1. Update `thinkwork.lock` to the approved release manifest URL and checksum.
-2. Review ThinkWork release notes for schema or operator changes.
-3. Dispatch the workflow with `component=all`.
-4. Save the deploy summary artifact as evidence.
+   Do not commit plaintext secrets to `terraform/stages/*.tfvars`,
+   `customer/`, `.env`, or this runbook.
+
+9. Dispatch the first deploy:
+
+   ```bash
+   gh workflow run deploy.yml \
+     --repo <github-owner>/<github-repo> \
+     -f stage=dev \
+     -f component=all \
+     -f run_smokes=true
+   ```
+
+10. Watch the run and download evidence:
+
+    ```bash
+    RUN_ID="$(gh run list --repo <github-owner>/<github-repo> --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
+    gh run watch "$RUN_ID" --repo <github-owner>/<github-repo> --exit-status
+
+    mkdir -p "deploy-artifacts/dev-${RUN_ID}"
+    gh run download "$RUN_ID" \
+      --repo <github-owner>/<github-repo> \
+      --name "thinkwork-deploy-dev-${RUN_ID}" \
+      --dir "deploy-artifacts/dev-${RUN_ID}"
+
+    jq . "deploy-artifacts/dev-${RUN_ID}/deploy-summary.json"
+    jq . "deploy-artifacts/dev-${RUN_ID}/smoke-summary.json"
+    ```
+
+11. Log in to the deployed stack:
+
+    ```bash
+    thinkwork login --stage dev --region {{REGION}}
+    thinkwork me --stage dev --region {{REGION}}
+    ```
+
+12. Deploy production after the `prod` GitHub Environment has required
+    approvals and secrets:
+
+    ```bash
+    gh workflow run deploy.yml \
+      --repo <github-owner>/<github-repo> \
+      -f stage=prod \
+      -f component=all \
+      -f run_smokes=true
+    ```
+
+## Workflow Components
+
+| Component    | What it does                                                                                                                                           |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `all`        | First deploy and normal release upgrades: release artifact prep, Terraform apply, runtime image copy, AgentCore update, static sync, overlays, smokes. |
+| `foundation` | Terraform apply and artifact/runtime/static sync without overlays.                                                                                     |
+| `artifacts`  | Re-copy pinned Lambda/static/runtime artifacts without Terraform apply.                                                                                |
+| `overlays`   | Apply only `customer/` evals, skills, workspace defaults, seeds, and branding records.                                                                 |
+| `smokes`     | Run smoke checks against an already-deployed stage.                                                                                                    |
 
 ## Overlay-Only Changes
 
 1. Edit files under `customer/`.
-2. Run a local dry-run:
+2. Validate locally:
+
+   ```bash
+   thinkwork enterprise overlay apply . --stage dev --region {{REGION}} --dry-run --json
+   ```
+
+3. Commit and push:
 
    ```bash
-   thinkwork enterprise overlay apply . --stage dev --dry-run --json
+   git add customer
+   git commit -m "chore: update customer ThinkWork overlays"
+   git push
    ```
 
-3. Dispatch the workflow with `component=overlays`.
-4. Confirm `overlay-report.json` in the workflow artifacts.
+4. Dispatch:
+
+   ```bash
+   gh workflow run deploy.yml \
+     --repo <github-owner>/<github-repo> \
+     -f stage=dev \
+     -f component=overlays \
+     -f run_smokes=false
+   ```
+
+## Release Upgrades
+
+1. Update `thinkwork.lock`:
+
+   ```bash
+   VERSION="0.12.5"
+   RELEASE="v${VERSION#v}"
+   MANIFEST_URL="https://github.com/thinkwork-ai/thinkwork/releases/download/${RELEASE}/thinkwork-release.json"
+   MANIFEST_SHA256="$(curl -fsSL "$MANIFEST_URL" | shasum -a 256 | awk '{print $1}')"
+
+   tmp="$(mktemp)"
+   jq \
+     --arg release "$RELEASE" \
+     --arg manifestUrl "$MANIFEST_URL" \
+     --arg manifestSha256 "$MANIFEST_SHA256" \
+     --arg terraformModuleVersion "${RELEASE#v}" \
+     '.thinkwork.release = $release
+      | .thinkwork.manifestUrl = $manifestUrl
+      | .thinkwork.manifestSha256 = $manifestSha256
+      | .thinkwork.terraformModuleVersion = $terraformModuleVersion
+      | .artifacts.lambdaPrefix = ("releases/" + $release + "/lambdas")' \
+     thinkwork.lock > "$tmp"
+   mv "$tmp" thinkwork.lock
+   ```
+
+2. Commit and deploy to dev:
+
+   ```bash
+   git add thinkwork.lock
+   git commit -m "chore: bump ThinkWork to ${RELEASE}"
+   git push
+
+   gh workflow run deploy.yml \
+     --repo <github-owner>/<github-repo> \
+     -f stage=dev \
+     -f component=all \
+     -f run_smokes=true
+   ```
+
+3. Deploy to production after dev passes.
 
 ## Secrets
 
@@ -65,12 +233,14 @@ Do not store plaintext secrets in `terraform/stages/*.tfvars`, `.env`,
 ## Rollback
 
 To roll back application code, restore `thinkwork.lock` to the previously
-working release and dispatch the workflow. To roll back customer overlays,
-revert the customer repo commit and dispatch `component=overlays`.
+working release and dispatch the workflow with `component=all`.
+
+To roll back customer overlays, revert the customer repo commit and dispatch
+the workflow with `component=overlays`.
 
 If a deploy fails after Terraform apply but before smoke summary, inspect the
-workflow artifacts first: `release-manifest.json`, `overlay-report.json`, and
-the deploy summary identify which stage failed.
+workflow artifact first. `deploy-summary.json`, `overlay-report.json`, and
+`smoke-summary.json` identify which stage failed.
 
 ## Break Glass
 

package/dist/terraform/modules/app/lambda-api/handlers.tf

@@ -231,7 +231,8 @@ locals {
       ROUTINE_TASK_PYTHON_FUNCTION_NAME       = "thinkwork-${var.stage}-api-routine-task-python"
       ADMIN_OPS_MCP_FUNCTION_NAME             = "thinkwork-${var.stage}-api-admin-ops-mcp"
       SLACK_SEND_FUNCTION_NAME                = "thinkwork-${var.stage}-api-slack-send"
-      REQUESTER_IDLE_MEMORY_LEARNING_ENABLED  = tostring(var.requester_idle_memory_learning_enabled)
+      # requester idle memory learning defaults on in API code so this
+      # env-heavy Lambda can stay below AWS's 4 KB environment limit.
       # Phase 3 U10 — compliance read resolvers (complianceEvents,
       # complianceEvent, complianceEventByHash) connect to Aurora as
       # the compliance_reader role. The existing lambda_secrets policy

package/dist/terraform/modules/app/lambda-api/main.tf

@@ -535,10 +535,6 @@ resource "aws_iam_role_policy" "lambda_api_cross_invoke" {
         # decision. Calls SendTaskSuccess/SendTaskFailure on the SFN
         # task token; idempotent on already-consumed tokens.
         "arn:aws:lambda:${var.region}:${var.account_id}:function:thinkwork-${var.stage}-api-routine-resume",
-        # thread-idle-memory-learning: job-trigger invokes this
-        # RequestResponse after a 15-minute requester-thread idle timer
-        # passes its stale guard.
-        "arn:aws:lambda:${var.region}:${var.account_id}:function:thinkwork-${var.stage}-api-thread-idle-memory-learning",
         # workspace-files-efs: workspace-files invokes this (RequestResponse)
         # for Computer-target list/get to bypass the computer_tasks queue
         # and read EFS directly. Standalone resource below.
@@ -548,6 +544,25 @@ resource "aws_iam_role_policy" "lambda_api_cross_invoke" {
   })
 }
 
+resource "aws_iam_policy" "thread_idle_memory_learning_invoke" {
+  name        = "thinkwork-${var.stage}-thread-idle-memory-learning-invoke"
+  description = "Allow API job-trigger Lambda to invoke requester idle memory learning worker."
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["lambda:InvokeFunction"]
+      Resource = "arn:aws:lambda:${var.region}:${var.account_id}:function:thinkwork-${var.stage}-api-thread-idle-memory-learning"
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "lambda_thread_idle_memory_learning_invoke" {
+  role       = aws_iam_role.lambda.name
+  policy_arn = aws_iam_policy.thread_idle_memory_learning_invoke.arn
+}
+
 # Step Functions admin operations — for createRoutine / publishRoutineVersion
 # / triggerRoutineRun / updateRoutine resolvers (Phase B U7) and the
 # routine-asl-validator Lambda (Phase A U5). State-machine ARNs follow the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkwork-cli",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "description": "Thinkwork CLI — deploy, manage, and interact with your Thinkwork stack",
   "license": "Apache-2.0",
   "type": "module",