maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/skill-generator/templates/script-template.md

@@ -0,0 +1,368 @@
+# Script Template
+
+Unified script template covering both Bash and Python runtimes.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Optional | Use when declaring `## Scripts` in Phase/Action |
+| Execution | Invoke via `ExecuteScript('script-id', params)` |
+| Output Location | `.claude/skills/{skill-name}/scripts/{script-id}.{ext}` |
+
+---
+
+## Invocation Interface Specification
+
+All scripts share the same calling convention:
+
+```
+Caller
+    | ExecuteScript('script-id', { key: value })
+    |
+Script Entry
+    ├─ Parameter parsing (--key value)
+    ├─ Input validation (required parameter checks, file exists)
+    ├─ Core processing (data read -> transform -> write)
+    └─ Output result (last line: single-line JSON -> stdout)
+         ├─ Success: {"status":"success", "output_file":"...", ...}
+         └─ Failure: stderr output error message, exit 1
+```
+
+### Return Format
+
+```typescript
+interface ScriptResult {
+  success: boolean;    // exit code === 0
+  stdout: string;      // Standard output
+  stderr: string;      // Standard error
+  outputs: object;     // JSON output parsed from stdout last line
+}
+```
+
+### Parameter Convention
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--input-path` | Yes | Input file path |
+| `--output-dir` | Yes | Output directory (specified by caller) |
+| Others | Optional | Script-specific parameters |
+
+---
+
+## Bash Implementation
+
+```bash
+#!/bin/bash
+# {{script_description}}
+
+set -euo pipefail
+
+# ============================================================
+# Parameter Parsing
+# ============================================================
+
+INPUT_PATH=""
+OUTPUT_DIR=""
+
+while [[ "$#" -gt 0 ]]; do
+    case $1 in
+        --input-path)  INPUT_PATH="$2"; shift ;;
+        --output-dir)  OUTPUT_DIR="$2"; shift ;;
+        --help)
+            echo "Usage: $0 --input-path <path> --output-dir <dir>"
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown parameter $1" >&2
+            exit 1
+            ;;
+    esac
+    shift
+done
+
+# ============================================================
+# Parameter Validation
+# ============================================================
+
+[[ -z "$INPUT_PATH" ]] && { echo "Error: --input-path is required parameter" >&2; exit 1; }
+[[ -z "$OUTPUT_DIR" ]] && { echo "Error: --output-dir is required parameter" >&2; exit 1; }
+[[ ! -f "$INPUT_PATH" ]] && { echo "Error: Input file does not exist: $INPUT_PATH" >&2; exit 1; }
+command -v jq &> /dev/null || { echo "Error: jq is required" >&2; exit 1; }
+
+mkdir -p "$OUTPUT_DIR"
+
+# ============================================================
+# Core Logic
+# ============================================================
+
+OUTPUT_FILE="$OUTPUT_DIR/result.txt"
+ITEMS_COUNT=0
+
+# TODO: Implement processing logic
+while IFS= read -r line; do
+    echo "$line" >> "$OUTPUT_FILE"
+    ((ITEMS_COUNT++))
+done < "$INPUT_PATH"
+
+# ============================================================
+# Output JSON Result (use jq to build, avoid escaping issues)
+# ============================================================
+
+jq -n \
+    --arg output_file "$OUTPUT_FILE" \
+    --argjson items_processed "$ITEMS_COUNT" \
+    '{output_file: $output_file, items_processed: $items_processed, status: "success"}'
+```
+
+### Bash Common Patterns
+
+```bash
+# File iteration
+for file in "$INPUT_DIR"/*.json; do
+    [[ -f "$file" ]] || continue
+    # Processing logic...
+done
+
+# Temp file (auto cleanup)
+TEMP_FILE=$(mktemp)
+trap "rm -f $TEMP_FILE" EXIT
+
+# Tool dependency check
+require_command() {
+    command -v "$1" &> /dev/null || { echo "Error: $1 required" >&2; exit 1; }
+}
+require_command jq
+
+# jq processing
+VALUE=$(jq -r '.field' "$INPUT_PATH")                    # Read field
+jq '.field = "new"' input.json > output.json             # Modify field
+jq -s 'add' file1.json file2.json > merged.json          # Merge files
+```
+
+---
+
+## Python Implementation
+
+```python
+#!/usr/bin/env python3
+"""
+{{script_description}}
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description='{{script_description}}')
+    parser.add_argument('--input-path', type=str, required=True, help='Input file path')
+    parser.add_argument('--output-dir', type=str, required=True, help='Output directory')
+    args = parser.parse_args()
+
+    # Validate input
+    input_path = Path(args.input_path)
+    if not input_path.exists():
+        print(f"Error: Input file does not exist: {input_path}", file=sys.stderr)
+        sys.exit(1)
+
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Execute processing
+    try:
+        result = process(input_path, output_dir)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Output JSON result
+    print(json.dumps(result))
+
+
+def process(input_path: Path, output_dir: Path) -> dict:
+    """Core processing logic"""
+    # TODO: Implement processing logic
+
+    output_file = output_dir / 'result.json'
+
+    with open(input_path, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+
+    processed_count = len(data) if isinstance(data, list) else 1
+
+    with open(output_file, 'w', encoding='utf-8') as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+
+    return {
+        'output_file': str(output_file),
+        'items_processed': processed_count,
+        'status': 'success'
+    }
+
+
+if __name__ == '__main__':
+    main()
+```
+
+### Python Common Patterns
+
+```python
+# File iteration
+def process_files(input_dir: Path, pattern: str = '*.json') -> list:
+    return [
+        {'file': str(f), 'data': json.load(f.open())}
+        for f in input_dir.glob(pattern)
+    ]
+
+# Data transformation
+def transform(data: dict) -> dict:
+    return {
+        'id': data.get('id'),
+        'name': data.get('name', '').strip(),
+        'timestamp': datetime.now().isoformat()
+    }
+
+# External command invocation
+import subprocess
+
+def run_command(cmd: list) -> str:
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr)
+    return result.stdout
+```
+
+---
+
+## Runtime Selection Guide
+
+```
+Task Characteristics
+    |
+    ├─ File processing / system commands / pipeline operations
+    │   └─ Choose shell(.sh)
+    │
+    ├─ JSON data processing / complex transformation / data analysis
+    │   └─ Choose Python (.py)
+    │
+    └─ Simple read/write / format conversion
+        └─ Either (Bash is lighter)
+```
+
+---
+
+## Generation Function
+
+```javascript
+function generateScript(scriptConfig) {
+  const runtime = scriptConfig.runtime || 'bash';  // 'bash' | 'python'
+  const ext = runtime === 'python' ? '.py' : '.sh';
+
+  if (runtime === 'python') {
+    return generatePythonScript(scriptConfig);
+  }
+  return generateBashScript(scriptConfig);
+}
+
+function generateBashScript(scriptConfig) {
+  const { description, inputs = [], outputs = [] } = scriptConfig;
+
+  const paramDefs = inputs.map(i =>
+    `${i.name.toUpperCase().replace(/-/g, '_')}="${i.default || ''}"`
+  ).join('\n');
+
+  const paramParse = inputs.map(i =>
+    `        --${i.name}) ${i.name.toUpperCase().replace(/-/g, '_')}="$2"; shift ;;`
+  ).join('\n');
+
+  const paramValidation = inputs.filter(i => i.required).map(i => {
+    const VAR = i.name.toUpperCase().replace(/-/g, '_');
+    return `[[ -z "$${VAR}" ]] && { echo "Error: --${i.name} is required parameter" >&2; exit 1; }`;
+  }).join('\n');
+
+  return `#!/bin/bash
+# ${description}
+
+set -euo pipefail
+
+${paramDefs}
+
+while [[ "$#" -gt 0 ]]; do
+    case $1 in
+${paramParse}
+        *) echo "Unknown parameter: $1" >&2; exit 1 ;;
+    esac
+    shift
+done
+
+${paramValidation}
+
+# TODO: Implement processing logic
+
+# Output result (jq build)
+jq -n ${outputs.map(o =>
+  `--arg ${o.name} "$${o.name.toUpperCase().replace(/-/g, '_')}"`
+).join(' \\\n    ')} \
+    '{${outputs.map(o => `${o.name}: $${o.name}`).join(', ')}}'
+`;
+}
+
+function generatePythonScript(scriptConfig) {
+  const { description, inputs = [], outputs = [] } = scriptConfig;
+
+  const argDefs = inputs.map(i =>
+    `    parser.add_argument('--${i.name}', type=${i.type || 'str'}, ${
+      i.required ? 'required=True' : `default='${i.default || ''}'`
+    }, help='${i.description || i.name}')`
+  ).join('\n');
+
+  const resultFields = outputs.map(o =>
+    `        '${o.name}': None  # ${o.description || o.name}`
+  ).join(',\n');
+
+  return `#!/usr/bin/env python3
+"""
+${description}
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description='${description}')
+${argDefs}
+    args = parser.parse_args()
+
+    # TODO: Implement processing logic
+    result = {
+${resultFields}
+    }
+
+    print(json.dumps(result))
+
+
+if __name__ == '__main__':
+    main()
+`;
+}
+```
+
+---
+
+## Directory Convention
+
+```
+scripts/
+├── process-data.py    # id: process-data, runtime: python
+├── validate.sh        # id: validate, runtime: bash
+└── transform.js       # id: transform, runtime: node
+```
+
+- **Name is ID**: Filename (without extension) = script ID
+- **Extension is runtime**: `.py` -> python, `.sh` -> bash, `.js` -> node