# Checklist: Migrating Actions to Stdin Parameter Delivery & Output Format

**Purpose:** Convert existing actions from environment variable-based parameter handling to secure stdin-based JSON parameter delivery, and ensure proper output format configuration.

**Target Audience:** Pack developers updating existing actions or creating new ones.

---

## Pre-Migration

- [ ] **Review current action** - Understand what parameters it uses
- [ ] **Identify sensitive parameters** - Note which params are secrets (API keys, passwords, tokens)
- [ ] **Check dependencies** - Ensure `jq` available for bash actions
- [ ] **Backup original files** - Copy action scripts before modifying
- [ ] **Read reference docs** - Review `attune/docs/QUICKREF-action-parameters.md`

---

## YAML Configuration Updates

- [ ] **Add parameter delivery config** to action YAML:
  ```yaml
  # Parameter delivery: stdin for secure parameter passing (no env vars)
  parameter_delivery: stdin
  parameter_format: json
  ```

- [ ] **Mark sensitive parameters** with `secret: true`:
  ```yaml
  parameters:
    properties:
      api_key:
        type: string
        secret: true  # ← Add this
  ```

- [ ] **Validate YAML syntax** - Run: `python3 -c "import yaml; yaml.safe_load(open('action.yaml'))"`

### Add Output Format Configuration

- [ ] **Add `output_format` field** to action YAML:
  ```yaml
  # Output format: text, json, or yaml
  output_format: text  # or json, or yaml
  ```

- [ ] **Choose appropriate format:**
  - `text` - Plain text output (simple messages, logs, unstructured data)
  - `json` - JSON structured data (API responses, complex results)
  - `yaml` - YAML structured data (human-readable configuration)

### Update Output Schema

- [ ] **Remove execution metadata** from output schema:
  ```yaml
  # DELETE these from output_schema:
  stdout:       # ❌ Automatically captured
    type: string
  stderr:       # ❌ Automatically captured
    type: string
  exit_code:    # ❌ Automatically captured
    type: integer
  ```

- [ ] **For text format actions** - Remove or simplify output schema:
  ```yaml
  output_format: text
  # Output schema: not applicable for text output format
  # The action outputs plain text to stdout
  ```

- [ ] **For json/yaml format actions** - Keep schema describing actual data:
  ```yaml
  output_format: json
  # Output schema: describes the JSON structure written to stdout
  output_schema:
    type: object
    properties:
      count:
        type: integer
      items:
        type: array
        items:
          type: string
      # No stdout/stderr/exit_code
  ```

---

## Bash/Shell Script Migration

### Remove Environment Variable Reading

- [ ] **Delete all `ATTUNE_ACTION_*` references**:
  ```bash
  # DELETE these lines:
  MESSAGE="${ATTUNE_ACTION_MESSAGE:-default}"
  COUNT="${ATTUNE_ACTION_COUNT:-1}"
  API_KEY="${ATTUNE_ACTION_API_KEY}"
  ```

### Add Stdin JSON Reading

- [ ] **Add stdin input reading** at script start:
  ```bash
  #!/bin/bash
  set -e
  set -o pipefail
  
  # Read JSON parameters from stdin
  INPUT=$(cat)
  ```

- [ ] **Parse parameters with jq**:
  ```bash
  MESSAGE=$(echo "$INPUT" | jq -r '.message // "default"')
  COUNT=$(echo "$INPUT" | jq -r '.count // 1')
  API_KEY=$(echo "$INPUT" | jq -r '.api_key // ""')
  ```

### Handle Optional Parameters

- [ ] **Add null checks for optional params**:
  ```bash
  if [ -n "$API_KEY" ] && [ "$API_KEY" != "null" ]; then
      # Use API key
  fi
  ```

### Boolean Parameters

- [ ] **Handle boolean values correctly** (jq outputs lowercase):
  ```bash
  ENABLED=$(echo "$INPUT" | jq -r '.enabled // false')
  if [ "$ENABLED" = "true" ]; then
      # Feature enabled
  fi
  ```

### Array Parameters

- [ ] **Parse arrays with jq -c**:
  ```bash
  ITEMS=$(echo "$INPUT" | jq -c '.items // []')
  ITEM_COUNT=$(echo "$ITEMS" | jq 'length')
  ```

---

## Python Script Migration

### Remove Environment Variable Reading

- [ ] **Delete `os.environ` references**:
  ```python
  # DELETE these lines:
  import os
  message = os.environ.get('ATTUNE_ACTION_MESSAGE', 'default')
  ```

- [ ] **Remove environment helper functions** like `get_env_param()`, `parse_json_param()`, etc.

### Add Stdin JSON Reading

- [ ] **Add parameter reading function**:
  ```python
  import json
  import sys
  from typing import Dict, Any
  
  def read_parameters() -> Dict[str, Any]:
      """Read and parse JSON parameters from stdin."""
      try:
          input_data = sys.stdin.read()
          if not input_data:
              return {}
          return json.loads(input_data)
      except json.JSONDecodeError as e:
          print(f"ERROR: Invalid JSON input: {e}", file=sys.stderr)
          sys.exit(1)
  ```

- [ ] **Call reading function in main()**:
  ```python
  def main():
      params = read_parameters()
      message = params.get('message', 'default')
      count = params.get('count', 1)
  ```

### Update Parameter Access

- [ ] **Replace all parameter reads** with `.get()`:
  ```python
  # OLD: get_env_param('message', 'default')
  # NEW: params.get('message', 'default')
  ```

- [ ] **Update required parameter validation**:
  ```python
  if not params.get('url'):
      print("ERROR: 'url' parameter is required", file=sys.stderr)
      sys.exit(1)
  ```

---

## Node.js Script Migration

### Remove Environment Variable Reading

- [ ] **Delete `process.env` references**:
  ```javascript
  // DELETE these lines:
  const message = process.env.ATTUNE_ACTION_MESSAGE || 'default';
  ```

### Add Stdin JSON Reading

- [ ] **Add parameter reading function**:
  ```javascript
  const readline = require('readline');
  
  async function readParameters() {
      const rl = readline.createInterface({
          input: process.stdin,
          terminal: false
      });
  
      let input = '';
      for await (const line of rl) {
          input += line;
      }
  
      try {
          return JSON.parse(input || '{}');
      } catch (err) {
          console.error('ERROR: Invalid JSON input:', err.message);
          process.exit(1);
      }
  }
  ```

- [ ] **Update main function** to use async/await:
  ```javascript
  async function main() {
      const params = await readParameters();
      const message = params.message || 'default';
  }
  
  main().catch(err => {
      console.error('ERROR:', err.message);
      process.exit(1);
  });
  ```

---

## Testing

### Local Testing

- [ ] **Test with specific parameters**:
  ```bash
  echo '{"message": "test", "count": 5}' | ./action.sh
  ```

- [ ] **Test with empty JSON (defaults)**:
  ```bash
  echo '{}' | ./action.sh
  ```

- [ ] **Test with file input**:
  ```bash
  cat test-params.json | ./action.sh
  ```

- [ ] **Test required parameters** - Verify error when missing:
  ```bash
  echo '{"count": 5}' | ./action.sh  # Should fail if 'message' required
  ```

- [ ] **Test optional parameters** - Verify defaults work:
  ```bash
  echo '{"message": "test"}' | ./action.sh  # count should use default
  ```

- [ ] **Test null handling**:
  ```bash
  echo '{"message": "test", "api_key": null}' | ./action.sh
  ```

### Integration Testing

- [ ] **Test via Attune API** - Execute action through API endpoint
- [ ] **Test in workflow** - Run action as part of a workflow
- [ ] **Test with secrets** - Verify secret parameters are not exposed
- [ ] **Verify no env var exposure** - Check `ps` output during execution

---

## Security Review

- [ ] **No secrets in logs** - Ensure sensitive params aren't printed
- [ ] **No parameter echoing** - Don't include input JSON in error messages
- [ ] **Generic error messages** - Don't expose parameter values in errors
- [ ] **Marked all secrets** - All sensitive parameters have `secret: true`

---

## Documentation

- [ ] **Update action README** - Document parameter changes if exists
- [ ] **Add usage examples** - Show how to call action with new format
- [ ] **Update pack CHANGELOG** - Note breaking change from env vars to stdin
- [ ] **Document default values** - List all parameter defaults

---

## Post-Migration Cleanup

- [ ] **Remove old helper functions** - Delete unused env var parsers
- [ ] **Remove unused imports** - Clean up `os` import in Python if not needed
- [ ] **Update comments** - Fix any comments mentioning environment variables
- [ ] **Validate YAML again** - Final check of action.yaml syntax
- [ ] **Run linters** - `shellcheck` for bash, `pylint`/`flake8` for Python
- [ ] **Commit changes** - Commit with clear message about stdin migration

---

## Verification

- [ ] **Script runs with stdin** - Basic execution works
- [ ] **Defaults work correctly** - Empty JSON triggers default values
- [ ] **Required params validated** - Missing required params cause error
- [ ] **Optional params work** - Optional params with null/missing handled
- [ ] **Exit codes correct** - Success = 0, errors = non-zero
- [ ] **Output format unchanged** - Stdout/stderr output still correct
- [ ] **No breaking changes to output** - JSON output schema maintained

---

## Example: Complete Migration

### Before (Environment Variables)

```bash
#!/bin/bash
set -e

MESSAGE="${ATTUNE_ACTION_MESSAGE:-Hello}"
COUNT="${ATTUNE_ACTION_COUNT:-1}"

echo "Message: $MESSAGE (repeated $COUNT times)"
```

### After (Stdin JSON)

```bash
#!/bin/bash
set -e
set -o pipefail

# Read JSON parameters from stdin
INPUT=$(cat)

# Parse parameters with defaults
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Hello"')
COUNT=$(echo "$INPUT" | jq -r '.count // 1')

# Validate required parameters
if ! [[ "$COUNT" =~ ^[0-9]+$ ]]; then
    echo "ERROR: count must be a positive integer" >&2
    exit 1
fi

echo "Message: $MESSAGE (repeated $COUNT times)"
```

---

## References

- [Quick Reference: Action Parameters](./QUICKREF-action-parameters.md)
- [Quick Reference: Action Output Format](./QUICKREF-action-output-format.md)
- [Core Pack Actions README](../packs/core/actions/README.md)
- [Worker Service Architecture](./architecture/worker-service.md)

---

## Common Issues

### Issue: `jq: command not found`
**Solution:** Ensure `jq` is installed in worker container/environment

### Issue: Parameters showing as `null`
**Solution:** Check for both empty string and "null" literal:
```bash
if [ -n "$PARAM" ] && [ "$PARAM" != "null" ]; then
```

### Issue: Boolean not working as expected
**Solution:** jq outputs lowercase "true"/"false", compare as strings:
```bash
if [ "$ENABLED" = "true" ]; then
```

### Issue: Array not parsing correctly
**Solution:** Use `jq -c` for compact JSON output:
```bash
ITEMS=$(echo "$INPUT" | jq -c '.items // []')
```

### Issue: Action hangs waiting for input
**Solution:** Ensure JSON is being passed to stdin, or pass empty object:
```bash
echo '{}' | ./action.sh
```

---

## Success Criteria

✅ **Migration complete when:**
- Action reads ALL parameters from stdin JSON
- NO environment variables used for parameters
- All tests pass with new parameter format
- YAML updated with `parameter_delivery: stdin`
- YAML includes `output_format: text|json|yaml`
- Output schema describes data structure only (no stdout/stderr/exit_code)
- Sensitive parameters marked with `secret: true`
- Documentation updated
- Local testing confirms functionality