@mawaru/sdk 0.9.0 → 0.11.0

package/_schemas/ai-manifest.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { aiManifestSchema } from "./ai-manifest.js"
+import { AI_MODELS, aiManifestSchema } from "./ai-manifest.js"
 import { envelopeSchemaOf, instructionSchema } from "./port-spec.js"
 
 const envelope = envelopeSchemaOf({ type: "string" })
@@ -32,11 +32,18 @@ describe("aiManifestSchema", () => {
       outputs: { main: envelope },
     })
     expect(manifest.name).toBeUndefined()
-    expect(manifest.model).toBe("claude-opus-4-8")
+    expect(manifest.model).toBe("claude-opus-5")
     expect(manifest.skills).toEqual([])
     expect(manifest.env).toEqual([])
   })
 
+  it("model は AI_MODELS の enum（バージョン固定。外の値は拒否）", () => {
+    for (const model of AI_MODELS) {
+      expect(aiManifestSchema.parse({ ...valid, model }).model).toBe(model)
+    }
+    expect(() => aiManifestSchema.parse({ ...valid, model: "opus" })).toThrow()
+  })
+
   it("prompt は必須・非空（repo に置く時点で完成品）", () => {
     expect(() => aiManifestSchema.parse({ ...valid, prompt: "" })).toThrow()
     const { prompt: _prompt, ...rest } = valid

package/_schemas/ai-manifest.ts

@@ -2,15 +2,18 @@ import { z } from "zod"
 import { jsonSchemaSchema } from "./node.js"
 import { isAiEnvelopeSchema, manifestInKeysViolation } from "./port-spec.js"
 
-// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）
+// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）。
+// エイリアス（"opus" 等）は採らずバージョンを固定する：実行のたびに黙って別モデルへ
+// 乗り換わると品質も費用も再現しないため。新モデルが出たらこの配列を足して SDK を publish する
 export const AI_MODELS = [
+  "claude-opus-5",
   "claude-opus-4-8",
   "claude-sonnet-5",
   "claude-haiku-4-5",
 ] as const
 export const aiModelSchema = z.enum(AI_MODELS)
 export type AiModel = z.infer<typeof aiModelSchema>
-export const DEFAULT_AI_MODEL = "claude-opus-4-8" satisfies AiModel
+export const DEFAULT_AI_MODEL = "claude-opus-5" satisfies AiModel
 
 // nodes/ai/<dir>/config.json（実行repoの構造見直し）。AI ノードの定義（prompt/model/skills/
 // 入出力スキーマ/env）は repo 側が正で、エディタが取り込んで ports を自動生成する

package/dist/_schemas/ai-manifest.d.ts

@@ -1,17 +1,19 @@
 import { z } from "zod";
-export declare const AI_MODELS: readonly ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"];
+export declare const AI_MODELS: readonly ["claude-opus-5", "claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"];
 export declare const aiModelSchema: z.ZodEnum<{
+    "claude-opus-5": "claude-opus-5";
     "claude-opus-4-8": "claude-opus-4-8";
     "claude-sonnet-5": "claude-sonnet-5";
     "claude-haiku-4-5": "claude-haiku-4-5";
 }>;
 export type AiModel = z.infer<typeof aiModelSchema>;
-export declare const DEFAULT_AI_MODEL = "claude-opus-4-8";
+export declare const DEFAULT_AI_MODEL = "claude-opus-5";
 export declare const aiManifestSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     prompt: z.ZodString;
     model: z.ZodDefault<z.ZodEnum<{
+        "claude-opus-5": "claude-opus-5";
         "claude-opus-4-8": "claude-opus-4-8";
         "claude-sonnet-5": "claude-sonnet-5";
         "claude-haiku-4-5": "claude-haiku-4-5";

package/dist/_schemas/ai-manifest.js

@@ -1,14 +1,17 @@
 import { z } from "zod";
 import { jsonSchemaSchema } from "./node.js";
 import { isAiEnvelopeSchema, manifestInKeysViolation } from "./port-spec.js";
-// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）
+// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）。
+// エイリアス（"opus" 等）は採らずバージョンを固定する：実行のたびに黙って別モデルへ
+// 乗り換わると品質も費用も再現しないため。新モデルが出たらこの配列を足して SDK を publish する
 export const AI_MODELS = [
+    "claude-opus-5",
     "claude-opus-4-8",
     "claude-sonnet-5",
     "claude-haiku-4-5",
 ];
 export const aiModelSchema = z.enum(AI_MODELS);
-export const DEFAULT_AI_MODEL = "claude-opus-4-8";
+export const DEFAULT_AI_MODEL = "claude-opus-5";
 // nodes/ai/<dir>/config.json（実行repoの構造見直し）。AI ノードの定義（prompt/model/skills/
 // 入出力スキーマ/env）は repo 側が正で、エディタが取り込んで ports を自動生成する
 // （実行時の正は ports テーブルのまま。プログラム規約 v2 と同じ関係）。

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
     "mawaru": "dist/cli.js"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     }
   },
   "files": [
@@ -23,6 +28,14 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "sh -c 'pnpm typecheck && pnpm test && npm version --no-git-tag-version ${1:-minor} && npm publish --access public' release"
+  },
   "dependencies": {
     "zod": "^4.4.3",
     "zod-from-json-schema": "^0.5.3"
@@ -31,11 +44,5 @@
     "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}

package/skills/create-loop/SKILL.md

@@ -14,19 +14,33 @@ repo ルートの `.env` に以下の4変数が揃っているか確認する。
 セットアップまで面倒を見る**（ユーザーに手作業のセットアップを求めない）：
 
 1. `.gitignore` に `.env` が入っていることを確認する。無ければ追加する（API キーをコミットさせない）。
-2. `.env` を作成・追記する：
+2. `.env` を作成・追記する。**足りない変数は推測で埋めず、その場でユーザーに聞く**（下の
+   「環境変数が足りないとき」の原則に従う）：
    - `MAWARU_API_URL` — API のベース URL（例: `https://api.mawaru.ai`。ローカル開発は `http://localhost:9000`）
    - `MAWARU_APP_URL` — フロントの URL（例: `https://app.mawaru.ai`。ローカル開発は `http://localhost:3000`）
    - `MAWARU_TENANT_ID` — tenant の ID
    - `MAWARU_API_KEY` — tenant の API キー
-   接続先が本番かローカルかはユーザーに確認する。API キーは mawaru のテナント設定画面
-   （`{MAWARU_APP_URL}/settings` の「API キー」。admin のみ）で発行・コピーできるので、
-   ユーザーに案内して値を入力してもらう。**キーの値をチャット・ログ・コミットに出さない。**
+   接続先が本番かローカルかはユーザーに確認する（URL 2つはこれで決まる）。API キーは mawaru の
+   テナント設定画面（`{MAWARU_APP_URL}/settings` の「API キー」。admin のみ）で発行・コピーできるので、
+   発行手順を案内したうえで `.env` に入れてもらう。**キーの値をチャット・ログ・コミットに出さない。**
 3. 疎通確認：`GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/loops` が 200 を返せば完了。
    401 なら API キー、404 なら tenant ID を疑う。
 
 認証は全リクエスト共通でヘッダ `x-api-key: $MAWARU_API_KEY`。
 
+## 環境変数が足りないとき（全体の原則）
+
+このスキルの `.env` でも、ノードの `env` 宣言（program / ai の handler・setup.sh・prompt が使う
+secret）でも、**足りない値を推測・生成・空文字で代用しない。作業を止めてユーザーに対話的に聞く。**
+
+- 足りないものは**まとめて1回で聞く**：変数名・何に使う値か・どこで取れるか（画面・発行手順）・
+  形式の例を添える。答えを待ってから作業を再開する（タイムアウトを承認扱いにしない）。
+- **秘密の値はチャットに書かせない・出力しない**。`.env` へはユーザー自身の手で追記してもらう
+  （例: `echo 'MAWARU_API_KEY=xxxx' >> .env` を実行してもらう）。ノードの `env` 宣言分は
+  実行 repo の Settings → Secrets and variables → Actions に登録してもらい、こちらは**名前だけ**扱う。
+- 受け取ったら「効いていること」まで確かめてから次へ進む（`.env` なら疎通確認、
+  Actions secrets なら名前が config.json の `env` と一致していること）。
+
 ## 契約の読み方（最重要）
 
 **API のボディ形をこの文書は説明しない。正はこのパッケージ内の Zod スキーマなので、必ずソースを読むこと**：
@@ -62,6 +76,7 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 1. **設計**：要件から必要なノード（program / ai / human / wait）と流れを決め、ユーザーに一言で確認する。
 2. **repo 側の準備**：足りない program / ai は `nodes/program/<dir>/` / `nodes/ai/<dir>/` に作る
    （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
+   **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。
    **作った・変えたものは GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で
    読むため、未 push だと graph 保存の検証・書き戻しと食い違って 409 になる）。
 3. **ループ作成**：`POST loops`。
@@ -78,6 +93,35 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、
    見た目の確認と run はユーザーに委ねる。
 
+## AI ノード：決定論的な処理は prompt でなく setup.sh に書く
+
+やることが決まっている準備＝**外部 repo の clone / skill の持ち込み / 認証キーのファイル化 /
+ツールの用意**は、prompt で AI にやらせず `nodes/ai/<dir>/setup.sh` に書く。prompt には
+「どこに何が置いてあるか」と、そこから先の判断だけを書く。
+
+理由：LLM にやらせるとトークンを食い flaky で、失敗が「セットアップの失敗」として明瞭に出ない。
+skill の配置は Claude Code 起動前に完了している必要もある。
+
+規約（実行 repo 側。config.json への宣言は不要、ファイルの存在が正）：
+
+```bash
+# nodes/ai/<dir>/setup.sh
+set -euo pipefail
+git clone --depth 1 "https://x-access-token:${SOME_REPO_TOKEN}@github.com/owner/repo.git" workspace/repo
+cp -r workspace/repo/.claude/skills/some-skill skills/   # copySkills の前に走るので自動発見に乗る
+printf '%s' "$SOME_SA_KEY" > workspace/key.json
+```
+
+- 実行順は `env 注入 → input.json 書き出し → setup.sh → copySkills → 本体（Claude Code）`。
+  `bash nodes/ai/<dir>/setup.sh "$INPUT_JSON"`（実行ビット不要）、cwd は checkout ルート。
+- **入力は `$1`（JSON 文字列）か `input.json`** で参照できる（`jq` はランナー同梱）。
+- **環境変数は config.json の `env` 宣言分だけ**が注入される。必要な secret は `env` に宣言し、
+  実行 repo の Actions secrets に登録してもらう（→「環境変数が足りないとき」）。
+- **受け渡しはファイルで**。別プロセスなので `export` は本体に引き継がれない。clone 先・キーは
+  ワークスペース内の既知パス（`workspace/` 配下を推奨）に置き、prompt / skill はそのパスを参照する。
+- **非 0 exit は step failed**（本体は実行されない）。`set -euo pipefail` を付ける。
+- program ノードにも同じ規約が効く（`nodes/program/<dir>/setup.sh`）。
+
 ## 注意
 
 - **graph PUT は全量置換**。既存ループを更新するときは、必ず先に `GET loops/{loopId}` で