@mawaru/sdk 0.36.0 → 0.38.0

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(),

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/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(),

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.36.0",
+  "version": "0.38.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

@@ -59,7 +59,7 @@ secret）でも、**足りない値を推測・生成・空文字で代用しな
 
 疎通確認のあと `GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/openapi.json`
 （ヘッダ `x-api-key: $MAWARU_API_KEY`）を取得すると、機械 API 面
-（loops の一覧・作成・詳細・graph PUT、runs/start、runs/{runId}/cancel、runs/{runId}/complete、members、api-keys、steps の end / decision）の
+（loops の一覧・作成・詳細・graph PUT・versions/publish、runs/start、runs/{runId} の参照・cancel・complete、members、api-keys、steps の end / decision）の
 パス・メソッド・リクエストボディ（Zod 由来の JSON Schema）が載っている。ここが常に正。
 段階導入中で未掲載のエンドポイントもある（その場合だけ `api/index.ts` 相当を辿る）。
 
@@ -73,7 +73,15 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 
 ## 手順
 
-1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決め、ユーザーに一言で確認する。
+ループは次の4段階で作る。**言われなくても必ず 1 のスケルトンから始め、段階を飛ばさない。**
+graph の保存（`PUT loops/{loopId}/graph`）は常に下書き（draft）に入り、4 で publish するまで
+本番の run には使われない。
+
+### 1. スケルトンを作って合意する
+
+ノードの配置と接続だけを下書きに保存する。中身（repo のプログラム・prompt）はまだ作らない。
+
+1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決める。
    1つの出口から複数の線を引くと枝が並行に走る（fan-out）。枝の結果を待ち合わせるときは
    合流（`join`）を置く：線のつながった入口が全部揃うまで待ち、`{ [入口の key]: 値 }` にまとめて
    `main` から流す。並行した枝を合流させずに同じノード（待機など）へ戻すと、枝の数だけ走り続ける。
@@ -83,26 +91,56 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    （`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` に書く**（下記）。
-   **作った・変えたものは GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で
-   読むため、未 push だと graph 保存の検証・書き戻しと食い違って 409 になる）。
-3. **ループ作成**：`POST loops`。
-4. **graph ボディを組む**：
+2. **ループ作成**：`POST loops`（既存ループの更新なら不要）。
+3. **graph ボディを組む**（中身は空のまま）：
    - node / port の `id` はクライアント採番（`uuidgen` などで UUID を作る）
-   - program / ai ノードの ports は repo の config.json の inputs / outputs をそのまま写す
-     （in ポート key は `in`、out ポートは outputs の各 key）
-   - kind 別の固定ポート構成（human / wait / ai / join）は `port-spec.ts` の `kindPortsViolation` に従う。
-     join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`。出口の型は自動で決まる
+   - program / ai ノードには `program` / `ai`（dir の指定）を付けない。dir 未設定のノードは
+     repo へ書き戻されないので、repo 側に何も無くても保存できる
+   - ポートは kind 別の固定構成（`port-spec.ts` の `kindPortsViolation`）と分岐する出口の key だけ
+     決め、`schema` は `{}`（未宣言）でよい。型は 2 で config.json と一緒に決める。
+     program の in は `in`。join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`
+   - human は担当（`human.assignment.units`）が保存に必須なので、誰が承認するかもここで決める
    - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
      ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
      `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）。
      キー `input` は予約（run の起動入力が自動で入る。定義に置くと 422）
    - `position_x` / `position_y` は左→右に流れる単純配置（例: x を 320 刻み、y は 240）
-5. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
-6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、
-   見た目の確認と run はユーザーに委ねる。
+4. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
+5. **合意**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、ノードの並びと
+   つながりを見てもらう。**OK をもらうまで 2 へ進まない**（直しの依頼は graph を直して保存し、
+   もう一度見てもらう）。
+
+### 2. 各ノードの中身を実装し、1つずつ確かめる
+
+上流のノードから順に、1つずつ次を繰り返す：
+
+1. **repo 側の実装**：`nodes/program/<dir>/` / `nodes/ai/<dir>/` を作る
+   （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
+   config.json の inputs / outputs はスケルトンのポートの key に合わせ、ここで型を決める。
+   **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。
+   **GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で読むため、未 push だと
+   graph 保存の書き戻しと食い違って 409 になり、テスト実行も古い中身で走る）。
+2. **ノードに結びつける**：graph の該当ノードに `program.program_dir` / `ai.ai_dir` を設定し、
+   ports を config.json の inputs / outputs の写しにして保存する（in ポート key は `in`、
+   out ポートは outputs の各 key）。human は承認ビュー、wait は待ち方もここで設定する。
+3. **単体で確かめる**：そのノードだけをテスト実行する。`POST runs/start` に `kind: "test"`・
+   `test_scope: "only"`・`start_node_id`（そのノード）・`payload`（サンプル入力。上流を確かめ済みなら
+   その output を使う）・`start_by`（ユーザーの user_id。`GET members` で引く。API キー起動では必須）を
+   渡し、`GET runs/{runId}` で step の status と output を見る。下書きの program / ai は
+   ブランチ先頭の commit で走る。失敗したら直して push し、もう一度実行する。
+   human はテスト実行の担当が起動者になるので、承認・差し戻しはユーザーに操作してもらう。
+
+### 3. 全体を通して確かめる
+
+開始ノード（kind `start`）を `start_node_id` に、`test_scope: "from"` でテスト実行し、end まで
+流れることを確かめる（分岐があれば主な道を一通り）。human を通る道はユーザーに操作してもらう。
+結果をユーザーに報告する。
+
+### 4. publish して起動する
+
+ユーザーの OK をもらってから `POST loops/{loopId}/versions/publish` で下書きを公開する
+（AI / Program の実行 commit はここで固定される）。続けて `POST runs/start`（`loop_id`・`payload`。
+`kind` を省くと本番 run）で起動し、run の URL `{MAWARU_APP_URL}/runs/{runId}` をユーザーに渡す。
 
 ## AI ノード：出力は短く（既定）
 

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`）