Merge pull request #1 from zAbuQasem/develop

feat: support tag-based targeting via new 'targets' input

Author: zAbuQasem

.github/workflows/lint.yml

@@ -6,7 +6,7 @@ on:
       - main
 
 env:
-  MINIMUM_PACKAGE_AGE_HOURS: 48
+  MINIMUM_PACKAGE_AGE_HOURS: 0
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
   SAFE_CHAIN_VERSION: "1.4.7"
   SAFE_CHAIN_SHA256: "54c750232d149106ecf4f5f28fee82ba49d2428f1e411e0ed961c0263ae19eaf"

.github/workflows/tester.yml

@@ -2,8 +2,16 @@ name: ci
 
 on:
   workflow_dispatch:
+    inputs:
+      environment:
+        description: "Tag-targeting environment (used by the tag-targeting job)"
+        required: false
+        default: production
+        type: choice
+        options: [staging, production]
   push:
     branches:
+      - develop
       - main
 
 env:
@@ -17,8 +25,9 @@ permissions:
   contents: read
 
 jobs:
-  test:
-    name: Integration test
+  # ── Job 1: target by instance ID ─────────────────────────────────────────────
+  test-instance-ids:
+    name: Integration test — instance-ids
     runs-on: ubuntu-latest
 
     steps:
@@ -46,14 +55,69 @@ jobs:
           role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
           aws-region: ${{ secrets.AWS_REGION }}
 
-      - name: Run SSM command
+      - name: Run SSM command (instance-ids)
+        id: ssm
         uses: ./
         with:
           aws-region: ${{ secrets.AWS_REGION }}
           instance-ids: ${{ secrets.INSTANCE_ID }}
           working-directory: /home/ec2-user
-          comment: aws-ssm-action CI test
+          wait-for-output: true
+          wait-timeout: 180
+          comment: ci — instance-ids — ${{ github.sha }}
           command: |
             echo "Hello from GitHub Actions!" >> logs.txt
             echo $(date) >> logs.txt
             cat logs.txt
+
+      - name: Print output
+        run: echo "${{ steps.ssm.outputs.output }}"
+
+  # ── Job 2: target by tag ──────────────────────────────────────────────────────
+  test-tag-targeting:
+    name: Integration test — tag targeting
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
+
+      - name: Install safe-chain
+        run: |
+          curl -fsSL "https://github.com/AikidoSec/safe-chain/releases/download/${SAFE_CHAIN_VERSION}/install-safe-chain.sh" \
+            -o install-safe-chain.sh
+          echo "${SAFE_CHAIN_SHA256}  install-safe-chain.sh" | sha256sum --check
+          sh install-safe-chain.sh --ci
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          SAFE_CHAIN_MINIMUM_PACKAGE_AGE_HOURS: ${{ env.MINIMUM_PACKAGE_AGE_HOURS }}
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@ec61189d14ec14c8efccab744f656cffd0e33f37 # v6.1.0
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ${{ secrets.AWS_REGION }}
+
+      - name: Run SSM command (tag targeting)
+        id: ssm
+        uses: ./
+        with:
+          aws-region: ${{ secrets.AWS_REGION }}
+          targets: |
+            Key=tag:env,Values=${{ inputs.environment || 'production' }}
+            Key=tag:role,Values=web
+          working-directory: /home/ec2-user
+          wait-for-output: true
+          wait-timeout: 180
+          comment: ci — tags — ${{ github.sha }}
+          command: |
+            echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) Hello from tag-targeting CI" >> logs.txt
+            cat logs.txt
+
+      - name: Print output
+        run: echo "${{ steps.ssm.outputs.output }}"

CLAUDE.md

@@ -7,25 +7,41 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ```bash
 bun install                  # install dependencies
 bun run typecheck            # tsc --noEmit (type check only, no emit)
+bun test                     # run unit tests (bun:test) for input validation
 bun run build                # bundle src/index.ts → dist/index.js
 ```
 
-Run both before committing any source change — the runner executes `dist/index.js` directly, so it must always be up to date.
+Run typecheck, tests, and build before committing any source change — the runner executes `dist/index.js` directly, so it must always be up to date.
 
-There are no unit tests. The CI workflow (`tester.yml`) validates against a live AWS environment via OIDC.
+Unit tests live in `src/inputs.test.ts` and exercise `sanitizeInputs()` by setting `INPUT_*` env vars (the same mechanism `@actions/core` uses at runtime). Test files are excluded from `tsconfig.json` so bun test handles their typing directly. The CI workflow (`tester.yml`) additionally validates against a live AWS environment via OIDC.
 
 ## Architecture
 
 Single-file GitHub Action (`src/index.ts`) that wraps the AWS SSM `SendCommand` API to run bash commands on EC2 instances without SSH.
 
 **Entry points:**
 - `action.yml` — input/output schema and runtime declaration (`node24`)
-- `src/index.ts` — reads inputs, validates them, calls `SSMClient.send(SendCommandCommand(...))`
+- `src/index.ts` — `run()` entry; wires SDK client, calls `SendCommandCommand`, optionally calls `waitForOutput()` which polls `GetCommandInvocationCommand` / `ListCommandInvocationsCommand`
+- `src/inputs.ts` — `sanitizeInputs()` reads inputs via `@actions/core`, validates them, and returns a typed `SanitizedInputs` (or `null` on failure). Pure enough to unit-test by setting `INPUT_*` env vars.
+- `src/inputs.test.ts` — bun:test unit tests for `sanitizeInputs()`
 - `dist/index.js` — Bun-bundled self-contained output; **must be committed** (runners have no build step)
 
 **Input validation in `sanitizeInputs()`** (returns `null` and calls `core.setFailed` on any error):
-- `aws-region` — validated against `/^[a-z]{2}-[a-z]+-\d+$/`
+- `aws-region` — validated against `/^[a-z]{2}-[a-z]+(-[a-z]+)?-\d+$/` (supports commercial, GovCloud, and ISO regions)
 - `instance-ids` — each line validated against `/^i-[0-9a-f]{8}([0-9a-f]{9})?$/`; max 50
+- `targets` — each line parsed as `Key=<k>,Values=<v1>[,<v2>...]`; key matched against `/^(InstanceIds|tag:[\w.\-:/+=@ ]{1,128}|resource-groups:(Name|ResourceTypeFilters))$/`; max 5 targets, 50 values per target, 256 chars per value (AWS SSM limits)
+- `document-name` — optional, defaults to `AWS-RunShellScript`. Validated as either a simple SSM document name (`[A-Za-z0-9._-]{3,128}`) or a full document ARN (commercial / cn / us-gov / iso / iso-b partitions)
+- `wait-for-output` — parsed via `core.getBooleanInput`; must be `"true"` or `"false"` (case-insensitive), defaults to `false`
+- `wait-timeout` — parsed as integer, must be 1–3600 inclusive; rejects floats and non-numeric strings; defaults to `60`
+
+**Output polling (when `waitForOutput` is true) in `src/index.ts`:**
+- For `instance-ids` mode: polls `GetCommandInvocationCommand` directly for each known ID
+- For `targets` mode: calls `ListCommandInvocationsCommand` first to discover instance IDs (requires `ssm:ListCommandInvocations`), then polls each
+- Exponential backoff: starts at 3 s, caps at 15 s
+- Terminal statuses: `Success`, `Failed`, `TimedOut`, `Cancelled`, `DeliveryTimedOut`, `ExecutionTimedOut`
+- Logs per-instance stdout/stderr in collapsible groups; sets `output` action output; fails action on non-success or timeout
+- AWS truncates `StandardOutputContent` at 24 000 bytes per invocation
+- Exactly one of `instance-ids` / `targets` must be set — both or neither is rejected. In `SendCommand`, the action sends `InstanceIds` *or* `Targets`, never both
 - `working-directory` — validated against `/^\/[a-zA-Z0-9._\-/]*$/`; no `..`
 - `command` — split on newlines; empty result is rejected
 - `comment` — newlines stripped, truncated to 100 chars (AWS API limit)