@mawaru/sdk 0.35.0 → 0.37.0

package/_schemas/extract-component.test.ts

@@ -417,3 +417,78 @@ describe("buildExtractPlan（子グラフと親置換の生成）", () => {
     })
   })
 })
+
+// forで配列を要素ごとに処理する（繰り返しの枠）.md：繰り返しは結果を配列で返すので出口はちょうど1つ
+describe("buildExtractPlan（singleExit：繰り返しの出口は1つ）", () => {
+  const childEndNode = (): GraphNode => ({
+    id: uuid(),
+    kind: "end",
+    name: "終了",
+    ports: [port("in", "in", {}), port("out", "main", {})],
+    hooks: [],
+    position_x: 560,
+    position_y: 200,
+  })
+  const plan = (
+    nodes: GraphNode[],
+    connections: { from_port_id: string; to_port_id: string }[],
+    selectedIds: string[],
+    childEnd = childEndNode(),
+  ) =>
+    buildExtractPlan({
+      nodes,
+      connections,
+      selectedIds,
+      name: "繰り返し",
+      componentLoopId: uuid(),
+      childStartOutPortId: uuid(),
+      childEnd,
+      newId: uuid,
+      singleExit: true,
+    })
+
+  it("外へ出る線が無ければ、線の出ていない唯一の出力を出口にする（結果を返す）", () => {
+    const { d, nodes, connections } = chain()
+    const childEnd = childEndNode()
+
+    const result = plan(nodes, connections, [d.id], childEnd)
+
+    if (!result.ok) throw new Error(result.reason)
+    const [nd] = result.childNodes
+    if (!nd) throw new Error("コピーがない")
+    expect(result.childConnections).toContainEqual({
+      from_port_id: outOf(nd).id,
+      to_port_id: inOf(childEnd).id,
+    })
+    expect(result.groupNode.ports.filter((p) => p.io === "out")).toHaveLength(1)
+  })
+
+  it("外へ出る線があればそれが出口（ふだんの抽出と同じ）", () => {
+    const { b, c, nodes, connections } = chain()
+
+    const result = plan(nodes, connections, [b.id, c.id])
+
+    if (!result.ok) throw new Error(result.reason)
+    expect(result.childEnd.ports.filter((p) => p.io === "in")).toHaveLength(1)
+  })
+
+  it("出口が2つ以上・出口にできる出力が決まらない選択は拒否する", () => {
+    const a = makeNode("program", "A")
+    const b = makeNode("program", "B")
+    const c = makeNode("program", "C")
+    const d = makeNode("program", "D")
+    // B と C を選ぶ：B → D、C → D の2つの出口
+    const twoExits = plan(
+      [a, b, c, d],
+      [connect(a, b), connect(a, c), connect(b, d), connect(c, d)],
+      [b.id, c.id],
+    )
+    expect(twoExits.ok).toBe(false)
+    if (twoExits.ok) return
+    expect(twoExits.reason).toContain("出口を1つ")
+
+    // 外へ出る線が無く、線の出ていない出力が2つ（B と C）
+    const ambiguous = plan([b, c], [], [b.id, c.id])
+    expect(ambiguous.ok).toBe(false)
+  })
+})

package/_schemas/extract-component.ts

@@ -118,6 +118,10 @@ export const buildExtractPlan = (params: {
   childStartOutPortId: string
   childEnd: GraphNode
   newId: () => string
+  // 繰り返し（for）：結果を配列で返すので出口はちょうど1つ。外へ出る線が無ければ、
+  // 選択の中で線の出ていない唯一の出力を出口にする
+  // （forで配列を要素ごとに処理する（繰り返しの枠）.md）
+  singleExit?: boolean
 }): { ok: false; reason: string } | ({ ok: true } & ExtractPlan) => {
   const {
     nodes,
@@ -128,11 +132,30 @@ export const buildExtractPlan = (params: {
     childStartOutPortId,
     childEnd,
     newId,
+    singleExit = false,
   } = params
   const analysis = analyzeExtractSelection(nodes, connections, selectedIds)
   if (!analysis.ok) return analysis
 
   const selected = new Set(selectedIds)
+  let exitPortIds = analysis.exitPortIds
+  if (singleExit) {
+    if (exitPortIds.length === 0) {
+      const wiredOut = new Set(analysis.internal.map((c) => c.from_port_id))
+      const free = nodes
+        .filter((n) => selected.has(n.id))
+        .flatMap((n) =>
+          n.ports
+            .filter((p) => p.io === "out" && !wiredOut.has(p.id))
+            .map((p) => p.id),
+        )
+      exitPortIds = free.length === 1 ? free : []
+    }
+    if (exitPortIds.length !== 1) {
+      return { ok: false, reason: "繰り返しの出口を1つにしてください" }
+    }
+  }
+
   // ノード・ポートとも新 id を採番してコピー（kind 別設定・hooks は共有参照で問題ない
   // ＝この後 JSON 化して保存 API に渡すだけで、エディタ状態には子側を持たない）。
   // node_key は親の版の行との突き合わせ用なので子へは持ち込まない（子 loop の draft に
@@ -185,7 +208,7 @@ export const buildExtractPlan = (params: {
       }
     }
   }
-  const exits = analysis.exitPortIds.map((exitPortId, i) => {
+  const exits = exitPortIds.map((exitPortId, i) => {
     const exitName = portById.get(exitPortId)?.name ?? "出力"
     const seeded = i === 0 ? seededEndIns[0] : undefined
     const endIn: GraphPort = seeded

package/_schemas/graph.test.ts

@@ -997,22 +997,69 @@ describe("saveGraphBodySchema：開始/終了ノード（start/end kind）", ()
     ).toThrow(/in ポートはちょうど1つ/)
   })
 
-  it("start への接続・end からの接続を拒否する", () => {
-    const s = startNode()
+  it("end からの接続を拒否する", () => {
     const e = endNode()
     const other = makeNode()
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [e, other],
+        connections: [connect(e, other)],
+      }),
+    ).toThrow(/終了ノード/)
+  })
+
+  // start の入口へ戻すと次の周回になる
+  // （docs/tasks/wip/startノードに入力をつないで周回する（runの周回）.md）
+  it("start の入口へ1本つなげる（周回の最後から戻す）", () => {
+    const s = startNode()
+    const other = { ...makeNode(simplePorts()), kind: "wait" }
     expect(() =>
       saveGraphBodySchema.parse({
         nodes: [s, other],
-        connections: [connect(other, s)],
+        connections: [connect(s, other), connect(other, s)],
       }),
-    ).toThrow(/開始ノード/)
+    ).not.toThrow()
+  })
+
+  it("start の入口につなげる線は1本だけ", () => {
+    const s = startNode()
+    const a = makeNode()
+    const b = makeNode()
     expect(() =>
       saveGraphBodySchema.parse({
-        nodes: [e, other],
-        connections: [connect(e, other)],
+        nodes: [s, a, b],
+        connections: [connect(a, s), connect(b, s)],
       }),
-    ).toThrow(/終了ノード/)
+    ).toThrow(/開始ノードの入口につなげる線は1本だけです/)
+  })
+
+  it("start の入口の型（直後のノードが受ける型）に合わない線を拒否する", () => {
+    const s = startNode()
+    const objectIn = {
+      type: "object",
+      properties: { title: { type: "string" } },
+      required: ["title"],
+    }
+    const next = {
+      ...makeNode([
+        { ...port("in", "in"), schema: objectIn },
+        port("out", "main"),
+      ]),
+      kind: "program",
+    }
+    const last = {
+      ...makeNode([
+        port("in", "in"),
+        { ...port("out", "main"), schema: { type: "string" } },
+      ]),
+      kind: "program",
+    }
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [s, next, last],
+        connections: [connect(s, next), connect(next, last), connect(last, s)],
+      }),
+    ).toThrow(/入力スキーマに適合しません/)
   })
 })
 

package/_schemas/graph.ts

@@ -292,9 +292,10 @@ export const graphNodeSchema = z.object({
   position_y: z.number(),
   // 表示アイコン（全 kind 共通の任意設定。human はフロントが担当から導出するので通常設定しない）
   icon: nodeIconSchema.optional(),
-  // Slack ビュー（全 kind 共通の任意設定。承認待ち・完了メッセージの見せ方）。
-  // human の view と同じ「不透明なキー」で、実在・可視性の検証は保存時に mawaru 側が行う
-  // （カタログは非公開。@mawaru/common の slack-view.ts）。
+  // Slack ビュー（全 kind 共通の任意設定。実行中（human は承認待ち）・完了メッセージの見せ方）。
+  // human の view と同じ「不透明なキー」で、選べる key は GET slack-views が返す。
+  // <slug>/<name> は実行 repo の views/slack/<name>/（@mawaru/sdk/slack-view の契約で書く）。
+  // 保存時に mawaru が見るのは common/* の実在と <slug>/* の可視性だけ。
   // 省略＝承認待ちは承認ボタンだけ・完了は ✅ の1行（データは出さない）。
   // ポートの型には一切影響しない
   slack_view: z.string().min(1).optional(),
@@ -521,12 +522,16 @@ export const saveGraphBodySchema = z
       const toNode = nodeByPortId.get(conn.to_port_id)
       if (!from || !to || !fromNode || !toNode) return // 構造違反は検出済み
 
-      // start には引き込めない（run payload だけが入口）、end からは引き出せない（終端）
-      if (toNode.kind === "start") {
+      // end からは引き出せない（終端）。start の入口へは戻せる（次の周回になる）が、
+      // 線は1本だけ（2本あると両方が着いたときに周回が2本並んで走る）
+      if (
+        toNode.kind === "start" &&
+        (inboundByPort.get(conn.to_port_id)?.length ?? 0) > 1
+      ) {
         ctx.addIssue({
           code: "custom",
           path: ["connections", i, "to_port_id"],
-          message: "開始ノードには接続できません",
+          message: "開始ノードの入口につなげる線は1本だけです",
         })
       }
       if (fromNode.kind === "end") {

package/_schemas/port-spec.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest"
 import type { GraphPort, JsonSchema } from "./node.js"
 import {
+  arrayOf,
   dataFormatOf,
   dataSchemaOf,
   fileSchema,
@@ -1116,3 +1117,30 @@ describe("schemaTypeKey（型としての同一性）", () => {
     ).not.toBe(schemaTypeKey({ type: "array", items: [{ type: "number" }] }))
   })
 })
+
+describe("arrayOf（for の配置ポート：1件分の型を配列に包む）", () => {
+  it("宣言された型は items に入れた配列になる", () => {
+    const error = { type: "object", properties: { id: { type: "string" } } }
+    expect(arrayOf(error)).toEqual({ type: "array", items: error })
+  })
+
+  it("未宣言の型は items を持たない配列になる（要素の型は判断できないまま）", () => {
+    expect(arrayOf(UNDECLARED_SCHEMA)).toEqual({ type: "array" })
+  })
+
+  it("配列にした型同士は要素の型で適合を判定する", () => {
+    const narrow = {
+      type: "object",
+      properties: { id: { type: "string" }, title: { type: "string" } },
+      required: ["id", "title"],
+    }
+    const wide = {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    }
+    expect(schemaFit(arrayOf(narrow), arrayOf(wide))).toBe("ok")
+    expect(schemaFit(arrayOf(wide), arrayOf(narrow))).toBe("mismatch")
+    expect(schemaFit(wide, arrayOf(wide))).toBe("mismatch")
+  })
+})

package/_schemas/port-spec.ts

@@ -15,6 +15,14 @@ export const UNDECLARED_SCHEMA: JsonSchema = {}
 export const isUndeclaredSchema = (schema: JsonSchema): boolean =>
   Object.keys(schema).length === 0 || schema.type === undefined
 
+// 1件分の型を配列に包む（for の配置ポート：in ＝ 中身の start.in の配列、out ＝ 中身の
+// end の in の配列。docs/tasks/done/forで配列を要素ごとに処理する（繰り返しの枠）.md）。
+// 未宣言は items を持たせない（要素の型は判断できないまま）
+export const arrayOf = (schema: JsonSchema): JsonSchema =>
+  isUndeclaredSchema(schema)
+    ? { type: "array" }
+    : { type: "array", items: schema }
+
 // ---- file 型（docs/tasks/done/AIノードのファイル入力（file型と添付）.md） ----
 // schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
 // ではなく storage path の参照で、署名 URL はどこにも焼き込まない。

package/dist/_cli/previewApi.d.ts

@@ -0,0 +1,10 @@
+import { type Credentials } from "./credentials.js";
+export type MawaruApi = (method: "GET" | "POST", path: string, body?: unknown) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare const mawaruApiFor: (credentials: Credentials, tenantId: string) => MawaruApi;
+export declare const expectOk: (what: string, res: {
+    status: number;
+    body: unknown;
+}) => unknown;

package/dist/_cli/previewApi.js

@@ -0,0 +1,28 @@
+import { accessTokenFrom } from "./credentials.js";
+export const mawaruApiFor = (credentials, tenantId) => async (method, path, body) => {
+    const token = await accessTokenFrom(credentials);
+    const res = await fetch(`${credentials.api_url}/tenants/${tenantId}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    try {
+        return { status: res.status, body: text ? JSON.parse(text) : null };
+    }
+    catch {
+        return { status: res.status, body: { message: text } };
+    }
+};
+// 2xx 以外は API の message を添えて失敗にする（403 は admin でない・409 は Slack 未接続 等）
+export const expectOk = (what, res) => {
+    if (res.status >= 200 && res.status < 300)
+        return res.body;
+    const message = res.body && typeof res.body === "object" && "message" in res.body
+        ? String(res.body.message)
+        : `HTTP ${res.status}`;
+    throw new Error(`${what}に失敗しました（${res.status}）: ${message}`);
+};

package/dist/_cli/previewCommand.d.ts

@@ -0,0 +1,18 @@
+import { type MawaruApi } from "./previewApi.js";
+import { type SlackSurface } from "./previewSlack.js";
+export type PreviewOptions = {
+    target: string;
+    case?: string;
+    surface?: SlackSurface;
+    channel?: string;
+};
+export declare const parsePreviewArgs: (args: string[]) => PreviewOptions;
+type Log = (line: string) => void;
+export declare const runPreviewWith: (params: {
+    root: string;
+    options: PreviewOptions;
+    api: MawaruApi;
+    log: Log;
+}) => Promise<number>;
+export declare const runPreview: (args: string[]) => Promise<number>;
+export {};

package/dist/_cli/previewCommand.js

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { requireCredentials } from "./credentials.js";
+import { expectOk, mawaruApiFor } from "./previewApi.js";
+import { readViewFiles, resolveView } from "./previewFiles.js";
+import { previewSlack, SLACK_SURFACES, } from "./previewSlack.js";
+// `mawaru preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|ID>]`
+// （実行 repo のルートで実行）
+//
+// views/<種類>/<名前>/ のビューを、push せずに手元のファイルのまま確かめる。描画は mawaru API がやるので、
+// `mawaru login` のセッション（web と同じ membership）と、どのテナントのつもりで描くかの
+// MAWARU_TENANT_ID（repo の .env。create-loop スキルと同じ）が要る。
+// ファイルの集め方・cases.ts の評価・ケースの絞り込みは種類をまたいで共通で、種類ごとに「確かめ方」
+// （Slack は送る。承認ビューは repo へ移すときに足す）だけを差し替える
+// （docs/tasks/wip/Slackビューの顧客repo配置.md の「手元プレビュー」）
+const USAGE = "使い方: npx mawaru preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|チャンネル ID>]\n" +
+    "  例: npx mawaru preview slack/pr-review（views/slack/pr-review/ の cases.ts の全ケースを Slack に送る）";
+export const parsePreviewArgs = (args) => {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            case: { type: "string" },
+            surface: { type: "string" },
+            channel: { type: "string" },
+        },
+    });
+    const [target, ...extra] = positionals;
+    if (!target || extra.length > 0)
+        throw new Error(USAGE);
+    if (values.surface !== undefined &&
+        !SLACK_SURFACES.includes(values.surface)) {
+        throw new Error("--surface には running か completed を指定してください");
+    }
+    return {
+        target,
+        ...(values.case !== undefined ? { case: values.case } : {}),
+        ...(values.surface !== undefined
+            ? { surface: values.surface }
+            : {}),
+        ...(values.channel !== undefined ? { channel: values.channel } : {}),
+    };
+};
+const PREVIEWERS = {
+    slack: {
+        casesPath: "/slack-views/cases",
+        run: ({ name, files, cases, options, api, log }) => {
+            const channel = options.channel ?? process.env.MAWARU_PREVIEW_CHANNEL;
+            if (!channel) {
+                throw new Error("送り先のチャンネルを --channel か repo の .env の MAWARU_PREVIEW_CHANNEL で指定してください（#名前 かチャンネル ID）");
+            }
+            return previewSlack({
+                name,
+                files,
+                cases: cases,
+                surfaces: options.surface ? [options.surface] : SLACK_SURFACES,
+                channel,
+                api,
+                log,
+            });
+        },
+    },
+};
+// 終了コードを返す（描画に失敗したものがあれば 1）。テストはここを呼ぶ
+export const runPreviewWith = async (params) => {
+    const { root, options, api, log } = params;
+    const view = resolveView(root, options.target);
+    const files = readViewFiles(root, view);
+    const previewer = PREVIEWERS[view.kind];
+    const { cases } = expectOk("ケースの読み込み", await api("POST", previewer.casesPath, { files }));
+    const picked = options.case === undefined
+        ? cases
+        : cases.filter((c) => c.name === options.case);
+    if (picked.length === 0) {
+        throw new Error(options.case === undefined
+            ? "cases.ts にケースがありません"
+            : `ケース「${options.case}」がありません（ある: ${cases.map((c) => c.name).join(", ")}）`);
+    }
+    const failed = await previewer.run({
+        name: view.name,
+        files,
+        cases: picked,
+        options,
+        api,
+        log,
+    });
+    if (failed > 0)
+        log(`失敗 ${failed} 件`);
+    return failed > 0 ? 1 : 0;
+};
+export const runPreview = async (args) => {
+    const options = parsePreviewArgs(args);
+    const root = process.cwd();
+    const env = join(root, ".env");
+    if (existsSync(env))
+        process.loadEnvFile(env);
+    const tenantId = process.env.MAWARU_TENANT_ID;
+    if (!tenantId) {
+        throw new Error("MAWARU_TENANT_ID が未設定です。repo の .env に MAWARU_TENANT_ID=<テナントの ID> を書いてください。");
+    }
+    const credentials = requireCredentials();
+    return runPreviewWith({
+        root,
+        options,
+        api: mawaruApiFor(credentials, tenantId),
+        log: (line) => console.log(line),
+    });
+};

package/dist/_cli/previewFiles.d.ts

@@ -0,0 +1,9 @@
+export declare const VIEW_KINDS: readonly ["slack"];
+export type ViewKind = (typeof VIEW_KINDS)[number];
+export type ViewTarget = {
+    kind: ViewKind;
+    name: string;
+};
+export declare const listViews: (root: string) => ViewTarget[];
+export declare const resolveView: (root: string, spec: string) => ViewTarget;
+export declare const readViewFiles: (root: string, view: ViewTarget) => Record<string, string>;

package/dist/_cli/previewFiles.js

@@ -0,0 +1,64 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// 手元プレビュー（`mawaru preview`）が読む、実行 repo の views/<種類>/<名前>/ のファイル。
+// 描画は mawaru API がやるので、ここは「対象を決めてファイルを集める」だけで、種類をまたいで共通
+// （docs/tasks/wip/Slackビューの顧客repo配置.md の「手元プレビュー」）
+// 手元プレビューできるビューの種類（views/ 直下のディレクトリ名）。承認ビューを repo へ移すときに
+// "approval" を足す（previewCommand.ts の振り分けにも足す）
+export const VIEW_KINDS = ["slack"];
+const dirsIn = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+};
+// views/<種類>/ 直下のディレクトリ（＝ビュー）。無ければ空
+export const listViews = (root) => VIEW_KINDS.flatMap((kind) => dirsIn(join(root, "views", kind)).map((name) => ({ kind, name })));
+const labelOf = (view) => `${view.kind}/${view.name}`;
+// 指定（views/slack/pr・slack/pr・pr）をビューに決める。一覧にあるものだけを受ける
+// （../ でディレクトリの外を読ませない）。決まらなければ、あるビューを添えて失敗する
+export const resolveView = (root, spec) => {
+    const normalized = spec
+        .replace(/^\.\//, "")
+        .replace(/^views\//, "")
+        .replace(/\/+$/, "");
+    const views = listViews(root);
+    const found = normalized.includes("/")
+        ? views.filter((view) => labelOf(view) === normalized)
+        : views.filter((view) => view.name === normalized);
+    if (found.length === 1 && found[0])
+        return found[0];
+    const known = views.length === 0
+        ? "views/ にビューがありません"
+        : `ある対象: ${views.map(labelOf).join(", ")}`;
+    throw new Error(found.length > 1
+        ? `${spec} は複数の種類にあります。<種類>/<名前> で指定してください（${found.map(labelOf).join(", ")}）`
+        : `${spec} が見つかりません（${known}）`);
+};
+// mawaru API へ送る files（{ ビューのディレクトリからの相対パス（/ 区切り）: 中身 }）。
+// .ts だけをサブディレクトリまで集める（上限の検証は API 側）
+export const readViewFiles = (root, view) => {
+    const dir = join(root, "views", view.kind, view.name);
+    const files = {};
+    const walk = (relative) => {
+        for (const entry of readdirSync(join(dir, relative), {
+            withFileTypes: true,
+        })) {
+            if (entry.name.startsWith("."))
+                continue;
+            const path = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile() && entry.name.endsWith(".ts")) {
+                files[path] = readFileSync(join(dir, path), "utf8");
+            }
+        }
+    };
+    walk("");
+    return files;
+};

package/dist/_cli/previewSlack.d.ts

@@ -0,0 +1,24 @@
+import type { SlackViewCase } from "../slack-view.js";
+import { type MawaruApi } from "./previewApi.js";
+export type SlackSurface = "running" | "completed";
+export declare const SLACK_SURFACES: SlackSurface[];
+export declare const previewBodyOf: (files: Record<string, string>, testCase: SlackViewCase, surface: SlackSurface) => {
+    refs?: {} | null | undefined;
+    output_schema?: Record<string, unknown> | undefined;
+    output?: {} | null | undefined;
+    input_schema?: Record<string, unknown> | undefined;
+    files: Record<string, string>;
+    surface: SlackSurface;
+    kind: "start" | "join" | "ai" | "human" | "program" | "guardrail" | "wait" | "end" | "component";
+    node_name: string;
+    input: unknown;
+};
+export declare const previewSlack: (params: {
+    name: string;
+    files: Record<string, string>;
+    cases: SlackViewCase[];
+    surfaces: SlackSurface[];
+    channel: string;
+    api: MawaruApi;
+    log: (line: string) => void;
+}) => Promise<number>;

package/dist/_cli/previewSlack.js

@@ -0,0 +1,67 @@
+import { expectOk } from "./previewApi.js";
+export const SLACK_SURFACES = ["running", "completed"];
+const SURFACE_LABEL = {
+    running: "実行中",
+    completed: "完了",
+};
+// ケース（cases.ts の SlackViewCase）を mawaru のプレビュー API の body にする
+export const previewBodyOf = (files, testCase, surface) => ({
+    files,
+    surface,
+    kind: testCase.kind ?? "human",
+    node_name: testCase.nodeName ?? testCase.name,
+    input: testCase.input,
+    ...(testCase.inputSchema !== undefined
+        ? { input_schema: testCase.inputSchema }
+        : {}),
+    ...(testCase.output !== undefined ? { output: testCase.output } : {}),
+    ...(testCase.outputSchema !== undefined
+        ? { output_schema: testCase.outputSchema }
+        : {}),
+    ...(testCase.refs !== undefined ? { refs: testCase.refs } : {}),
+});
+// 送り先：チャンネル ID はそのまま、#名前（または名前）は mawaru のボットが見えるチャンネルから引き直す
+const CHANNEL_ID = /^[CGD][A-Z0-9]{6,}$/;
+const resolveChannel = async (api, channel) => {
+    if (!channel.startsWith("#") && CHANNEL_ID.test(channel))
+        return channel;
+    const name = channel.replace(/^#/, "");
+    const body = expectOk("チャンネルの一覧の取得", await api("GET", "/integrations/slack/channels"));
+    const found = (body.channels ?? []).find((c) => c.name === name);
+    if (!found) {
+        throw new Error(`#${name} が見つかりません（mawaru のボットが参加しているチャンネルを指定してください）`);
+    }
+    return found.id;
+};
+// 送ったうちの、描画に失敗した（フォールバックした理由がある）数を返す
+export const previewSlack = async (params) => {
+    const { name, files, cases, surfaces, api, log } = params;
+    const channelId = await resolveChannel(api, params.channel);
+    log(`🧪 ${name}：${cases.length} ケース × ${surfaces.length} 面を ${params.channel} に送ります`);
+    let thread;
+    let failed = 0;
+    for (const testCase of cases) {
+        for (const surface of surfaces) {
+            const result = expectOk("Slack への送信", await api("POST", "/slack-views/test-post", {
+                ...previewBodyOf(files, testCase, surface),
+                channel_id: channelId,
+                ...(thread
+                    ? { thread_ts: thread }
+                    : { header: `🧪 ${name} のプレビュー` }),
+            }));
+            thread ??= result.thread_ts;
+            const label = `${testCase.name}／${SURFACE_LABEL[surface]}`;
+            if (result.error) {
+                failed += 1;
+                log(`⚠ ${label}：フォールバック（${result.error}）`);
+            }
+            else if (result.fallback) {
+                log(`– ${label}：未実装（mawaru の既定の表示）`);
+            }
+            else {
+                log(`✔ ${label}`);
+            }
+        }
+    }
+    return failed;
+};

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

@@ -78,8 +78,8 @@ export declare const aiManifestSchema: z.ZodObject<{
         "gpt-5.6-luna": "gpt-5.6-luna";
     }>>;
     auth_mode: z.ZodOptional<z.ZodEnum<{
-        subscription: "subscription";
         api: "api";
+        subscription: "subscription";
     }>>;
     skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
     env: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/_schemas/extract-component.d.ts

@@ -28,6 +28,7 @@ export declare const buildExtractPlan: (params: {
     childStartOutPortId: string;
     childEnd: GraphNode;
     newId: () => string;
+    singleExit?: boolean;
 }) => {
     ok: false;
     reason: string;

package/dist/_schemas/extract-component.js

@@ -55,11 +55,26 @@ export const analyzeExtractSelection = (nodes, connections, selectedIds) => {
 // end の in が1つの loop は out main の1口として振る舞う）
 const SINGLE_OUT_KEY = "main";
 export const buildExtractPlan = (params) => {
-    const { nodes, connections, selectedIds, name, componentLoopId, childStartOutPortId, childEnd, newId, } = params;
+    const { nodes, connections, selectedIds, name, componentLoopId, childStartOutPortId, childEnd, newId, singleExit = false, } = params;
     const analysis = analyzeExtractSelection(nodes, connections, selectedIds);
     if (!analysis.ok)
         return analysis;
     const selected = new Set(selectedIds);
+    let exitPortIds = analysis.exitPortIds;
+    if (singleExit) {
+        if (exitPortIds.length === 0) {
+            const wiredOut = new Set(analysis.internal.map((c) => c.from_port_id));
+            const free = nodes
+                .filter((n) => selected.has(n.id))
+                .flatMap((n) => n.ports
+                .filter((p) => p.io === "out" && !wiredOut.has(p.id))
+                .map((p) => p.id));
+            exitPortIds = free.length === 1 ? free : [];
+        }
+        if (exitPortIds.length !== 1) {
+            return { ok: false, reason: "繰り返しの出口を1つにしてください" };
+        }
+    }
     // ノード・ポートとも新 id を採番してコピー（kind 別設定・hooks は共有参照で問題ない
     // ＝この後 JSON 化して保存 API に渡すだけで、エディタ状態には子側を持たない）。
     // node_key は親の版の行との突き合わせ用なので子へは持ち込まない（子 loop の draft に
@@ -108,7 +123,7 @@ export const buildExtractPlan = (params) => {
             }
         }
     };
-    const exits = analysis.exitPortIds.map((exitPortId, i) => {
+    const exits = exitPortIds.map((exitPortId, i) => {
         const exitName = portById.get(exitPortId)?.name ?? "出力";
         const seeded = i === 0 ? seededEndIns[0] : undefined;
         const endIn = seeded

package/dist/_schemas/graph.js

@@ -235,9 +235,10 @@ export const graphNodeSchema = z.object({
     position_y: z.number(),
     // 表示アイコン（全 kind 共通の任意設定。human はフロントが担当から導出するので通常設定しない）
     icon: nodeIconSchema.optional(),
-    // Slack ビュー（全 kind 共通の任意設定。承認待ち・完了メッセージの見せ方）。
-    // human の view と同じ「不透明なキー」で、実在・可視性の検証は保存時に mawaru 側が行う
-    // （カタログは非公開。@mawaru/common の slack-view.ts）。
+    // Slack ビュー（全 kind 共通の任意設定。実行中（human は承認待ち）・完了メッセージの見せ方）。
+    // human の view と同じ「不透明なキー」で、選べる key は GET slack-views が返す。
+    // <slug>/<name> は実行 repo の views/slack/<name>/（@mawaru/sdk/slack-view の契約で書く）。
+    // 保存時に mawaru が見るのは common/* の実在と <slug>/* の可視性だけ。
     // 省略＝承認待ちは承認ボタンだけ・完了は ✅ の1行（データは出さない）。
     // ポートの型には一切影響しない
     slack_view: z.string().min(1).optional(),
@@ -447,12 +448,14 @@ export const saveGraphBodySchema = z
         const toNode = nodeByPortId.get(conn.to_port_id);
         if (!from || !to || !fromNode || !toNode)
             return; // 構造違反は検出済み
-        // start には引き込めない（run payload だけが入口）、end からは引き出せない（終端）
-        if (toNode.kind === "start") {
+        // end からは引き出せない（終端）。start の入口へは戻せる（次の周回になる）が、
+        // 線は1本だけ（2本あると両方が着いたときに周回が2本並んで走る）
+        if (toNode.kind === "start" &&
+            (inboundByPort.get(conn.to_port_id)?.length ?? 0) > 1) {
             ctx.addIssue({
                 code: "custom",
                 path: ["connections", i, "to_port_id"],
-                message: "開始ノードには接続できません",
+                message: "開始ノードの入口につなげる線は1本だけです",
             });
         }
         if (fromNode.kind === "end") {

package/dist/_schemas/port-spec.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { GraphPort, JsonSchema } from "./node.js";
 export declare const UNDECLARED_SCHEMA: JsonSchema;
 export declare const isUndeclaredSchema: (schema: JsonSchema) => boolean;
+export declare const arrayOf: (schema: JsonSchema) => JsonSchema;
 export declare const FILE_SCHEMA_MARKER = "x-mawaru-type";
 export declare const FILE_SCHEMA_TYPE = "file";
 export declare const fileSchema: () => JsonSchema;

package/dist/_schemas/port-spec.js

@@ -9,6 +9,12 @@ import { z } from "zod";
 // （docs/tasks/done/ポートスキーマのany撲滅.md）
 export const UNDECLARED_SCHEMA = {};
 export const isUndeclaredSchema = (schema) => Object.keys(schema).length === 0 || schema.type === undefined;
+// 1件分の型を配列に包む（for の配置ポート：in ＝ 中身の start.in の配列、out ＝ 中身の
+// end の in の配列。docs/tasks/done/forで配列を要素ごとに処理する（繰り返しの枠）.md）。
+// 未宣言は items を持たせない（要素の型は判断できないまま）
+export const arrayOf = (schema) => isUndeclaredSchema(schema)
+    ? { type: "array" }
+    : { type: "array", items: schema };
 // ---- file 型（docs/tasks/done/AIノードのファイル入力（file型と添付）.md） ----
 // schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
 // ではなく storage path の参照で、署名 URL はどこにも焼き込まない。

package/dist/cli.js

@@ -2,11 +2,12 @@
 import { relative } from "node:path";
 import { clearCredentials, loadCredentials } from "./_cli/credentials.js";
 import { runLogin } from "./_cli/login.js";
+import { runPreview } from "./_cli/previewCommand.js";
 import { runSessionResume } from "./_cli/sessionCommand.js";
 import { runInit } from "./init.js";
 import { runTypegen } from "./typegen.js";
 import { validateRepo } from "./validate.js";
-// 使い方: mawaru <init|typegen|validate|login|logout|session> [引数]
+// 使い方: mawaru <init|typegen|validate|login|logout|session|preview> [引数]
 const USAGE = `使い方: mawaru <command> [引数]
 
 コマンド:
@@ -16,7 +17,9 @@ const USAGE = `使い方: mawaru <command> [引数]
   login      ブラウザで承認して mawaru にログインする（~/.mawaru/credentials.json）
   logout     保存した資格情報を消す
   session resume <step URL>
-             AI ノードのセッションを手元に復元して CLI（claude / codex）の resume で再開する`;
+             AI ノードのセッションを手元に復元して CLI（claude / codex）の resume で再開する
+  preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|ID>]
+             views/ のビューを push せずに手元のファイルで確かめる（slack：cases.ts のケースを Slack に送る）`;
 const [command, ...rest] = process.argv.slice(2);
 // init / typegen / validate は repo ルートを任意で受ける（省略時はカレント）
 const root = rest[0] ?? process.cwd();
@@ -92,6 +95,15 @@ switch (command) {
         }
         break;
     }
+    case "preview": {
+        try {
+            process.exit(await runPreview(rest));
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e));
+        }
+        break;
+    }
     default: {
         console.error(USAGE);
         process.exit(command === undefined || command === "--help" ? 0 : 1);

package/dist/slack-view.d.ts

@@ -0,0 +1,58 @@
+import type { JsonSchema, NodeKind } from "./_schemas/node.js";
+export type SlackBlocks = unknown[];
+export type FileRef = {
+    path: string;
+    name: string;
+    mime_type?: string;
+    size?: number;
+};
+export type { JsonSchema, NodeKind };
+export type SlackViewMaterial<TIn = unknown, TOut = unknown> = {
+    input: TIn;
+    output?: TOut;
+};
+export type SlackViewContext<TIn = unknown> = {
+    kind: NodeKind;
+    input: TIn;
+    inputSchema: JsonSchema;
+    refs?: unknown;
+    additionalOutputs?: {
+        key: string;
+        name: string;
+        schema: JsonSchema;
+    }[];
+    nodeName: string;
+    stepUrl: string;
+    fileUrls: Record<string, string>;
+};
+export type SlackCompletedContext<TIn = unknown, TOut = unknown> = {
+    input: TIn;
+    output: TOut;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    refs?: unknown;
+    nodeName: string;
+    runUrl: string;
+    fileUrls: Record<string, string>;
+};
+export type SlackView<TIn = unknown, TOut = unknown> = {
+    files?: (m: SlackViewMaterial<TIn, TOut>) => FileRef[];
+    renderRunning?: (ctx: SlackViewContext<TIn>) => SlackBlocks;
+    renderCompleted?: (ctx: SlackCompletedContext<TIn, TOut>) => SlackBlocks;
+};
+export type SlackViewCase = {
+    name: string;
+    kind?: NodeKind;
+    nodeName?: string;
+    input: unknown;
+    inputSchema?: JsonSchema;
+    output?: unknown;
+    outputSchema?: JsonSchema;
+    refs?: unknown;
+};
+export declare const decisionActionId: (portKey: string) => string;
+export declare const decisionFormActionId: (portKey: string) => string;
+export declare const parseDecisionActionId: (actionId: string | undefined) => {
+    port_key: string;
+    form: boolean;
+} | null;

package/dist/slack-view.js

@@ -0,0 +1,21 @@
+// ---- 決定ボタンのプロトコル ----
+// ビューはボタンの action_id だけで「どの出口ポートへ流すか」を宣言する
+// （step の特定は message ts の逆引き。value は使わない）：
+//   decision:<port_key>      … そのまま確定。ホストが { [port_key]: step.input } で確定する
+//   decision-form:<port_key> … そのノードの out ポート <port_key> のスキーマから生成した
+//                              モーダルで値を集め、{ [port_key]: 入力値 } で確定する
+// human の出口が approve / reject 以外に増えても、ビューがボタンを置くだけで流せる。
+// 既存の "approve"（標準ビュー・投稿済みメッセージ）は従来の承認経路のまま動く
+const DECISION_PREFIX = "decision:";
+const DECISION_FORM_PREFIX = "decision-form:";
+export const decisionActionId = (portKey) => `${DECISION_PREFIX}${portKey}`;
+export const decisionFormActionId = (portKey) => `${DECISION_FORM_PREFIX}${portKey}`;
+export const parseDecisionActionId = (actionId) => {
+    if (actionId?.startsWith(DECISION_FORM_PREFIX)) {
+        return { port_key: actionId.slice(DECISION_FORM_PREFIX.length), form: true };
+    }
+    if (actionId?.startsWith(DECISION_PREFIX)) {
+        return { port_key: actionId.slice(DECISION_PREFIX.length), form: false };
+    }
+    return null;
+};

package/docs/development.md

@@ -20,6 +20,8 @@ nodes/
   ai/<dir>/        # AI ノード定義：config.json
   hook/<dir>/      # NodeIOHook：config.json ＋ main.ts（ノードに付く観測フック）
 skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
+views/
+  slack/<name>/    # Slack ビュー：index.ts（＋手元プレビュー用の cases.ts）
 ```
 
 ## Program ノード（`nodes/program/<dir>/`）
@@ -70,6 +72,31 @@ skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
 - ノードの入出力・外部シグナルを観測する独立実行。正は `_schemas/hook-manifest.ts`
   （`on`: input / output / signal の宣言・`env`）
 
+## Slack ビュー（`views/slack/<name>/`）
+
+- ノードの Slack メッセージの本文を描く。**実行中**（全 kind。human は承認待ち）と**完了**の2面。
+  ノードの「Slack ビュー」に `<テナントの slug>/<name>` を選ぶと使われる（エディタの選択肢に
+  ディレクトリ名で出る）。タイトル行・追加出口のボタン・投稿は mawaru が描く
+- `index.ts` — `export default { files?, renderRunning?, renderCompleted? } satisfies SlackView<入力の型>`。
+  契約（型・ctx の中身・決定ボタンの `decisionActionId` / `decisionFormActionId`）の正は
+  `@mawaru/sdk/slack-view`。実装した関数の面だけが変わる
+- **純関数**にする：mawaru が隔離環境（QuickJS）で動かすので、`fetch` / `process` / `require` / タイマー /
+  `console` は無い。1回の呼び出しは 200ms・32MB まで。ctx も戻り値も JSON で受け渡す
+- import できるのは同じディレクトリ内の相対パスと `@mawaru/sdk/slack-view` だけ（npm パッケージは不可）。
+  ビルドしない（mawaru が TypeScript の型を外して読む。`enum` など型を外すだけで JS にならない書き方は不可）
+- 入力は崩れて届くことがある（`input` が `null` 等）。例外を投げない書き方にする。失敗すると、承認待ちは
+  承認ボタンだけ・完了は1行のフォールバックになる
+- 版：ループの**公開版は publish 時のデフォルトブランチの commit に固定**される。push しただけでは本番の
+  通知は変わらず、ループを publish し直すと次の run から変わる。テスト実行は push だけで変わる
+- `cases.ts` — 手元プレビューのケース（`SlackViewCase[]` を `export default`）。本番の描画では読まない
+- 手元プレビュー：`npx mawaru login` のあと、repo ルートで `npx mawaru preview slack/<name>`。push せずに
+  手元のファイルのまま、`cases.ts` の全ケースを実行中・完了の両方の面で実際の Slack に送る（mawaru API が本番と
+  同じ組み立てで描く。1回の実行ごとに見出しを1つ立て、全部をそのスレッドに入れる）
+  - `--case <ケース名>`・`--surface running|completed` で絞る。送り先は `--channel`（`#名前` かチャンネル ID）か
+    `.env` の `MAWARU_PREVIEW_CHANNEL`。`.env` の `MAWARU_TENANT_ID` も要る。送れるのはテナントの admin だけ
+  - 端末に1通ごとの結果が出る（`✔` 成功・`⚠` 描画に失敗して理由つき・`–` 未実装の面）。失敗が1つでもあれば exit 1。
+    ビューを直したら同じコマンドで送り直して確かめる
+
 ## loop（回路）の作成・更新
 
 - `.claude/skills/create-loop` スキルに従う（graph API の契約は `_schemas/graph.ts` が正）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./slack-view": {
+      "types": "./dist/slack-view.d.ts",
+      "default": "./dist/slack-view.js"
     }
   },
   "files": [
@@ -18,7 +22,8 @@
     "templates",
     "docs",
     "_schemas",
-    "index.ts"
+    "index.ts",
+    "slack-view.ts"
   ],
   "engines": {
     "node": ">=20"

package/skills/create-loop/SKILL.md

@@ -77,6 +77,12 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    1つの出口から複数の線を引くと枝が並行に走る（fan-out）。枝の結果を待ち合わせるときは
    合流（`join`）を置く：線のつながった入口が全部揃うまで待ち、`{ [入口の key]: 値 }` にまとめて
    `main` から流す。並行した枝を合流させずに同じノード（待機など）へ戻すと、枝の数だけ走り続ける。
+   配列の要素ごとに同じ手順や別ループを回すときは繰り返し（for）にする：`POST loops` に
+   `kind: "for"` と `owner_loop_id`（このループ）を渡して中身の loop を作り、その graph
+   （start → 1件分の処理 → end）を保存してから、このループに component ノード
+   （`component.component_loop_id`＝作った for）を置く。配置ノードの in / out は中身の型の配列に
+   自動で焼き込まれ、全件そろうと入力と同じ順の配列で `main` から流れる（1件ずつは同時に走る）。
+   中身の出口（end につないだ in）は1つにする。
 2. **repo 側の準備**：足りない program / ai は `nodes/program/<dir>/` / `nodes/ai/<dir>/` に作る
    （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
    **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。

package/slack-view.ts

@@ -0,0 +1,143 @@
+import type { JsonSchema, NodeKind } from "./_schemas/node.js"
+
+// Slack ビューの契約（`@mawaru/sdk/slack-view`）。ノードの Slack ビュー
+// （nodes.slack_view_key）が実装する関数と、ホスト（mawaru）が渡す ctx の形の正。
+// mawaru 内蔵のビュー（backend の _helpers/slackViews/）と、顧客の実行 repo の
+// views/slack/<name>/ のビューが同じ契約で書く
+// （docs/tasks/wip/Slackビューの顧客repo配置.md）。
+//
+// ビューは局面ごとの描画関数を**実装した分だけ**カスタマイズが効く任意のビュー：
+// - renderRunning … 全 kind の実行中メッセージ（タイトル context 行より下の全ブロック）。
+//   human では承認待ちのメッセージになる。未実装なら human は承認ボタンだけの
+//   フォールバック、human 以外は従来のタイトル1行のまま
+// - renderCompleted … 全 kind の完了メッセージ（✅ タイトル行より下の全ブロック）。
+//   未実装なら従来の1行畳みのまま
+// スレッドの解決・担当メンション・投稿・ts の保存・承認の認可はホストに残る。
+//
+// ビューは**純関数**：Slack API も DB も触らない（通知1本のために I/O するビューが
+// 生まれると、ベストエフォート通知の失敗経路が読めなくなる）。必要な値は
+// ホストが解決して ctx に載せる。ctx と戻り値は JSON で表現できる値だけにする
+// （顧客 repo のビューは隔離環境で動き、値は JSON で受け渡す）。
+//
+// このファイルは実行時の import を持たない（型の import だけ）：顧客 repo のビューは
+// 隔離環境の中でこのファイルをそのまま import する
+
+// Slack の Block Kit の blocks。形はビューの自由で、ホストは上限（50個）だけを守る
+export type SlackBlocks = unknown[]
+
+// ノード間を流れる file の値（storage path の参照）。署名 URL はホストが ctx.fileUrls で渡す
+export type FileRef = {
+  path: string
+  name: string
+  mime_type?: string
+  size?: number
+}
+
+export type { JsonSchema, NodeKind }
+
+// ビューが描く材料：input＝step の入力、output＝step の出力（選ばれた出口ポートの値。
+// 実行中の時点では undefined）。files の宣言はこの material から行う
+export type SlackViewMaterial<TIn = unknown, TOut = unknown> = {
+  input: TIn
+  output?: TOut
+}
+
+// 実行中メッセージの ctx（全 kind 共通）。TIn は in ポートの型
+// （human なら承認ビューの宣言が転写されたポートの型）
+export type SlackViewContext<TIn = unknown> = {
+  // ノードの kind。決定ボタン（承認・差し戻し）は human のときだけ意味を持つので、
+  // 複数の kind で使うビューはこれを見てボタンを描くか決める
+  kind: NodeKind
+  // ノードの in に流れてきた入力そのもの（ホストは加工しない）。
+  // human は [承認する] で確定するのもこの値なので、表示と承認内容は必ず一致する
+  input: TIn
+  // input の型（in ポートの schema そのもの）。未宣言のポートは {}。
+  // 標準ビューはこれで列と項目名を決める（宣言が無ければ値の実形から導出する）
+  inputSchema: JsonSchema
+  // run の袋（ループ変数。steps.refs＝この step 開始時点のスナップショット）。
+  // 予約キー input が run の起動入力。省略＝無し（古い run・プレビュー）
+  refs?: unknown
+  // ホストが接続済みの追加出口だけを渡す（approve / reject はビュー側が描く）。
+  // human 以外は出口がボタンにならないので常に無い
+  additionalOutputs?: { key: string; name: string; schema: JsonSchema }[]
+  nodeName: string
+  // step 画面（human なら承認画面）への URL。[修正する] / [確認する] のリンク先
+  stepUrl: string
+  // ビューが files で宣言したファイルの閲覧用署名 URL（path → URL）。
+  // ホストがベストエフォートで解決する：失敗した・tenant 外のパスは載らないので、
+  // ビューは「無いかもしれない」前提で描く（image ブロック等に使う）
+  fileUrls: Record<string, string>
+}
+
+// 完了メッセージの ctx。output は完了した step の出力そのもの（ホストは加工しない）
+export type SlackCompletedContext<TIn = unknown, TOut = unknown> = {
+  input: TIn
+  output: TOut
+  // in ポートの schema と、選ばれた出口ポート（step.output_port_key）の schema。
+  // 未宣言のポートは {}
+  inputSchema: JsonSchema
+  outputSchema: JsonSchema
+  refs?: unknown
+  nodeName: string
+  // run 詳細画面への URL（完了メッセージからの誘導先）
+  runUrl: string
+  fileUrls: Record<string, string>
+}
+
+export type SlackView<TIn = unknown, TOut = unknown> = {
+  // ビューが画像等で使いたい material 内のファイル参照（純関数のまま宣言だけする）。
+  // 署名 URL の発行という I/O はホストの仕事で、結果は ctx.fileUrls で受け取る
+  files?: (m: SlackViewMaterial<TIn, TOut>) => FileRef[]
+  // 実行中（全 kind。human は承認待ち）。タイトル context 行より下の全ブロック
+  renderRunning?: (ctx: SlackViewContext<TIn>) => SlackBlocks
+  // 完了（全 kind）。✅ タイトル context 行より下の全ブロック
+  renderCompleted?: (ctx: SlackCompletedContext<TIn, TOut>) => SlackBlocks
+}
+
+// 手元プレビュー（npx mawaru preview）のケース。顧客 repo の
+// views/slack/<name>/cases.ts が export default する。本番の描画では読まない
+export type SlackViewCase = {
+  name: string
+  // ノードの kind。省略時は human（承認待ち）
+  kind?: NodeKind
+  // タイトル行のノード名。省略時は name
+  nodeName?: string
+  // ctx.input
+  input: unknown
+  // ctx.inputSchema。省略＝未宣言（{}）
+  inputSchema?: JsonSchema
+  // 完了の ctx.output。省略時は input（approve が素通しのビューが大半）
+  output?: unknown
+  outputSchema?: JsonSchema
+  refs?: unknown
+}
+
+// ---- 決定ボタンのプロトコル ----
+// ビューはボタンの action_id だけで「どの出口ポートへ流すか」を宣言する
+// （step の特定は message ts の逆引き。value は使わない）：
+//   decision:<port_key>      … そのまま確定。ホストが { [port_key]: step.input } で確定する
+//   decision-form:<port_key> … そのノードの out ポート <port_key> のスキーマから生成した
+//                              モーダルで値を集め、{ [port_key]: 入力値 } で確定する
+// human の出口が approve / reject 以外に増えても、ビューがボタンを置くだけで流せる。
+// 既存の "approve"（標準ビュー・投稿済みメッセージ）は従来の承認経路のまま動く
+
+const DECISION_PREFIX = "decision:"
+const DECISION_FORM_PREFIX = "decision-form:"
+
+export const decisionActionId = (portKey: string): string =>
+  `${DECISION_PREFIX}${portKey}`
+
+export const decisionFormActionId = (portKey: string): string =>
+  `${DECISION_FORM_PREFIX}${portKey}`
+
+export const parseDecisionActionId = (
+  actionId: string | undefined,
+): { port_key: string; form: boolean } | null => {
+  if (actionId?.startsWith(DECISION_FORM_PREFIX)) {
+    return { port_key: actionId.slice(DECISION_FORM_PREFIX.length), form: true }
+  }
+  if (actionId?.startsWith(DECISION_PREFIX)) {
+    return { port_key: actionId.slice(DECISION_PREFIX.length), form: false }
+  }
+  return null
+}

package/templates/CLAUDE.md

@@ -9,6 +9,7 @@
 - `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）
+- `views/slack/<name>/` — Slack ビュー（実行中・承認待ち・完了メッセージの本文）。`index.ts` ＋ 手元プレビュー用の `cases.ts`
 - `.github/workflows/mawaru-runner.yml` — mawaru 所有の実行シム。**編集しない**
   （`npx @mawaru/sdk init` が再生成する）
 
@@ -21,3 +22,5 @@ loop / node 開発にとりかかる前に、必ず `node_modules/@mawaru/sdk/do
 - 型生成：`npx mawaru typegen`（config.json → `types.d.ts`）
 - 規約検証：`npx mawaru validate`（CI 向け。error で exit 1）
 - ループの作成・更新：`.claude/skills/create-loop` スキルに従う
+- Slack ビューの確認：`npx mawaru preview slack/<name>`（push せずに手元のファイルで `cases.ts` の全ケースを Slack に送る。
+  失敗は理由が端末に出て exit 1。先に `npx mawaru login`、送り先は `.env` の `MAWARU_PREVIEW_CHANNEL`）