@mawaru/sdk 0.5.0

package/templates/CLAUDE.md

@@ -0,0 +1,23 @@
+# mawaru 実行 repo
+
+この repo は mawaru（loop＝回路で業務を自動化するサービス）の**実行リポジトリ**。
+ここにはユーザーのカスタマイズ（Program / AI ノードの実装）とその履歴だけを置き、
+実行基盤の実態は npm パッケージ側にある（repo に焼くものは最小・本体は npm で解決）。
+
+## 構成
+
+- `nodes/program/<dir>/` — Program ノード（`config.json` ＋ `main.ts`）。`main.ts` は
+  `run(input, ctx)` を export し、戻り値は `{ <出口ポートのkey>: <データ> }` の単一キー封筒
+- `nodes/ai/<dir>/` — AI ノード定義（`config.json`。prompt / model / skills / 入出力スキーマ / env）
+- `.github/workflows/mawaru-runner.yml` — mawaru 所有の実行シム。**編集しない**
+  （`npx @mawaru/sdk init` が再生成する）
+
+## 開発の進め方（AI エージェント向け）
+
+loop / node 開発にとりかかる前に、必ず `node_modules/@mawaru/sdk/docs/` の開発ドキュメントを読むこと。
+契約（config.json・graph API）の正は `node_modules/@mawaru/sdk/_schemas/` の Zod スキーマ
+（日本語コメント付き）。ドキュメントとスキーマが食い違ったらスキーマが正。
+
+- 型生成：`npx mawaru typegen`（config.json → `types.d.ts`）
+- 規約検証：`npx mawaru validate`（CI 向け。error で exit 1）
+- ループの作成・更新：`.claude/skills/create-loop` スキルに従う

package/templates/README.md

@@ -0,0 +1,12 @@
+# mawaru 実行リポジトリ
+
+この repo は [mawaru](https://mawaru.ai) の実行リポジトリです。loop（回路）につないだ
+Program / AI ノードの実装をここに置き、実行は mawaru が GitHub Actions
+（`.github/workflows/mawaru-runner.yml`）経由で起動します。
+
+- `nodes/program/<dir>/` — Program ノードの実装（`config.json` ＋ `main.ts`）
+- `nodes/ai/<dir>/` — AI ノードの定義（`config.json`）
+- `mawaru-runner.yml` は mawaru 所有です。編集せず、更新は `npx @mawaru/sdk init` の再実行で行ってください
+
+開発の詳細は `CLAUDE.md`（AI エージェント向けの入口）と
+`node_modules/@mawaru/sdk/docs/` を参照してください。

package/templates/echo/config.json

@@ -0,0 +1,23 @@
+{
+  "name": "エコー",
+  "description": "入力をそのまま出力するサンプル Program。動作確認用",
+  "env": [],
+  "inputs": {
+    "in": {
+      "type": "object",
+      "properties": {
+        "message": { "type": "string", "description": "そのまま返す文字列" }
+      },
+      "required": ["message"]
+    }
+  },
+  "outputs": {
+    "main": {
+      "type": "object",
+      "properties": {
+        "message": { "type": "string" }
+      },
+      "required": ["message"]
+    }
+  }
+}

package/templates/echo/main.ts

@@ -0,0 +1,4 @@
+// サンプル handler：入力をそのまま main 出口へ返す。
+// 戻り値は { <出口ポートのkey>: <データ> } の単一キー封筒（出口の選別を戻り値自身が運ぶ）。
+// 入出力の形は同じディレクトリの config.json が正（`npx mawaru typegen` で型も生成できる）
+export const run = async (input: { message: string }) => ({ main: input })

package/templates/mawaru-runner.yml

@@ -0,0 +1,71 @@
+# mawaru の汎用ランナー（mawaru が所有。`npx @mawaru/sdk init` が生成・再生成する。編集しない）。
+# デフォルトブランチに .github/workflows/mawaru-runner.yml として置くこと
+# （repository_dispatch はデフォルトブランチの workflow 定義でしか起動しない）。
+#
+# 実行の分岐（handler=Program / agent=AI）は yml では持たず、ラッパー
+# （client_payload.runner が npm 指定。既定 @mawaru/agent-runner）が payload.json を読んで
+# 自分で分岐する。ラッパーは config.json（nodes/program/<dir>/・nodes/ai/<dir>/）の env 宣言で
+# secrets を絞り、結果を検証して end_url へ「自分で」報告する。
+# Program handler は main.ts が run(input, ctx) を export し、戻り値＝{ <出口ポートのkey>: <データ> }
+# の単一キー封筒（出口の選別を戻り値自身が運ぶ）か "pending"（完了保留）で結末を表す。
+# ファイル I/O（input.json / output.json / pending.json）はラッパーが肩代わりする
+# （run を export しない旧スクリプト規約も後方互換で動く）。
+# client_payload.step_id は冪等キー：is_irreversible な処理は step_id で二重実行を弾くこと。
+name: mawaru-runner
+# title＝「{loop名}#{run連番}」（backend が payload で配る。無い旧 payload は従来表記）
+run-name: "${{ github.event.client_payload.title || format('mawaru {0}', github.event.client_payload.step_id) }}"
+on:
+  repository_dispatch:
+    types: [mawaru-run]
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      # 自分の Actions run の URL を mawaru に自己申告する（画面のリンク表示用）。
+      # repository_dispatch は起動した run の ID を返さないため、URL を知っているのは
+      # run の中だけ。checkout より前に置く＝以降のどの失敗でもログへ飛べる。
+      # 表示専用なので失敗しても実行は続ける（continue-on-error）。
+      # 旧 backend からの payload（resource_url 無し）では if でスキップ
+      - name: report run url
+        if: ${{ github.event.client_payload.resource_url }}
+        continue-on-error: true
+        run: |
+          curl -sf --retry 2 --retry-connrefused --retry-delay 2 \
+            -X PATCH "${{ github.event.client_payload.resource_url }}" \
+            -H "content-type: application/json" \
+            -H "x-api-key: ${{ github.event.client_payload.api_key }}" \
+            -d "{\"action_url\": \"${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}\"}"
+
+      - uses: actions/checkout@v7
+        with: { ref: "${{ github.event.client_payload.ref || github.ref }}" }
+      - uses: actions/setup-node@v7
+        with: { node-version: 22 }
+
+      # handler（Program）の依存だけ npm ci する（agent はラッパー自身を npx が入れる）
+      - name: install deps
+        if: ${{ github.event.client_payload.handler }}
+        run: npm ci
+
+      - name: write payload.json
+        run: echo '${{ toJSON(github.event.client_payload) }}' > payload.json
+      # SECRETS_JSON は全 repo secrets を注入するが、子プロセス（handler / Claude Code）には
+      # ラッパーが config.json の env 宣言分だけを展開して渡す（最小権限）
+      # 実行時間の上限はラッパーが config.json の timeout_minutes（既定：program 30分 /
+      # ai 360分）で締めて理由付きの failed を報告する。ここでは縛らず、暴走の最終
+      # backstop は GHA のジョブ上限（6時間）に任せる。step の停止は mawaru の run キャンセル
+      - name: run
+        id: run
+        env: { SECRETS_JSON: "${{ toJSON(secrets) }}" }
+        run: npx --yes "${{ github.event.client_payload.runner }}" payload.json
+
+      # ラッパー自体が起動できなかった事故（npx 失敗等）の backstop。
+      # ラッパーが報告済みで exit 1 したケースは /end 側の条件付き UPDATE が no-op にする。
+      # failure() が無いと暗黙の success() が付いて失敗後に発火しない（GitHub Actions の if 仕様）
+      - name: report failure (backstop)
+        if: ${{ failure() && steps.run.outcome == 'failure' }}
+        run: |
+          curl -sf --retry 5 --retry-connrefused --retry-delay 2 \
+            -X POST "${{ github.event.client_payload.end_url }}" \
+            -H "content-type: application/json" \
+            -H "x-api-key: ${{ github.event.client_payload.api_key }}" \
+            -d '{"status": "failed", "error": "runner failed in GitHub Actions"}'