@mawaru/sdk 0.38.0 → 0.40.0

package/_schemas/port-spec.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from "vitest"
+import type { HumanDeclaration } from "./human-manifest.js"
 import type { GraphPort, JsonSchema } from "./node.js"
 import {
   arrayOf,
+  connectionAccepted,
   dataFormatOf,
   dataSchemaOf,
   fileSchema,
@@ -12,6 +14,7 @@ import {
   kindPortsViolation,
   mergeInboundSchemas,
   propagateDerivedPorts,
+  resolveFlexiblePorts,
   resolvePortSchemas,
   schemaFit,
   schemaTypeKey,
@@ -151,6 +154,15 @@ describe("kindPortsViolation（kind 別ポート構成）", () => {
   })
 })
 
+// human ノードに実装の宣言の写し（node_humans.declaration）を持たせる
+const withViewDeclaration = <N extends { kind: string }>(
+  nodes: N[],
+  declaration: HumanDeclaration,
+) =>
+  nodes.map((node) =>
+    node.kind === "human" ? { ...node, human: { declaration } } : node,
+  )
+
 describe("型伝播（導出ポートの解決）", () => {
   it.each([
     "notion_task",
@@ -171,13 +183,14 @@ describe("型伝播（導出ポートの解決）", () => {
         extra,
       ],
     }
-    const resolved = resolvePortSchemas([human], [], {
-      viewPortSchemasOf: () => ({
+    const resolved = resolvePortSchemas(
+      withViewDeclaration([human], {
         in: { type: "string" },
         approve: { type: "string" },
         reject: { type: "string" },
       }),
-    })
+      [],
+    )
     expect(resolved.get(extra.id)).toEqual(extra.schema)
   })
 
@@ -189,7 +202,7 @@ describe("型伝播（導出ポートの解決）", () => {
   }
 
   // human の in / approve / reject はビューの宣言をそのまま転写する（上流の kind は見ない）。
-  // sdk はカタログを知らないので、呼び出し元が viewPortSchemasOf で解決して渡す
+  // 宣言はノードの写し（declaration）を読む（sdk はカタログを知らない）
   // → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
   it("ai → human 直結（コピー宣言）：in も approve も上流の out と同型、reject はビューの宣言型", () => {
     const aiOut = port("out", "main", declaredOut)
@@ -207,15 +220,12 @@ describe("型伝播（導出ポートの解決）", () => {
       ports: [humanIn, approve, reject],
     }
     const resolved = resolvePortSchemas(
-      [ai, human],
+      withViewDeclaration([ai, human], {
+        in: "T",
+        approve: "T",
+        reject: instructionSchema(),
+      }),
       [{ from_port_id: aiOut.id, to_port_id: humanIn.id }],
-      {
-        viewPortSchemasOf: () => ({
-          in: "T",
-          approve: "T",
-          reject: instructionSchema(),
-        }),
-      },
     )
     // 上流が AI でも中身を取り出さない：AI の出力形式がそのまま下流へ流れる
     expect(resolved.get(humanIn.id)).toEqual(declaredOut)
@@ -223,7 +233,7 @@ describe("型伝播（導出ポートの解決）", () => {
     expect(resolved.get(reject.id)).toEqual(instructionSchema())
   })
 
-  describe("承認ビューの宣言を human のポートへ転写する", () => {
+  describe("実装の宣言を human のポートへ転写する", () => {
     const viewIn = {
       type: "object",
       properties: {
@@ -272,15 +282,12 @@ describe("型伝播（導出ポートの解決）", () => {
           declaredOut,
         )
         const resolved = resolvePortSchemas(
-          [upstream, human],
+          withViewDeclaration([upstream, human], {
+            in: viewIn,
+            approve: viewOut,
+            reject: viewReject,
+          }),
           [{ from_port_id: out.id, to_port_id: humanIn.id }],
-          {
-            viewPortSchemasOf: () => ({
-              in: viewIn,
-              approve: viewOut,
-              reject: viewReject,
-            }),
-          },
         )
         expect(resolved.get(humanIn.id)).toEqual(viewIn)
         expect(resolved.get(approve.id)).toEqual(viewOut)
@@ -291,15 +298,12 @@ describe("型伝播（導出ポートの解決）", () => {
     it("上流の out は書き換えない（逆伝播しない）", () => {
       const { upstream, human, out, humanIn } = build("ai", declaredOut)
       const resolved = resolvePortSchemas(
-        [upstream, human],
+        withViewDeclaration([upstream, human], {
+          in: viewIn,
+          approve: viewOut,
+          reject: viewReject,
+        }),
         [{ from_port_id: out.id, to_port_id: humanIn.id }],
-        {
-          viewPortSchemasOf: () => ({
-            in: viewIn,
-            approve: viewOut,
-            reject: viewReject,
-          }),
-        },
       )
       expect(resolved.get(out.id)).toEqual(declaredOut)
     })
@@ -310,15 +314,12 @@ describe("型伝播（導出ポートの解決）", () => {
         declaredOut,
       )
       const resolved = resolvePortSchemas(
-        [upstream, human],
+        withViewDeclaration([upstream, human], {
+          in: "T",
+          approve: "T",
+          reject: viewReject,
+        }),
         [{ from_port_id: out.id, to_port_id: humanIn.id }],
-        {
-          viewPortSchemasOf: () => ({
-            in: "T",
-            approve: "T",
-            reject: viewReject,
-          }),
-        },
       )
       expect(resolved.get(humanIn.id)).toEqual(declaredOut)
       expect(resolved.get(approve.id)).toEqual(declaredOut)
@@ -333,13 +334,14 @@ describe("型伝播（導出ポートの解決）", () => {
         kind: "human",
         ports: [humanIn, approve, reject],
       }
-      const resolved = resolvePortSchemas([human], [], {
-        viewPortSchemasOf: () => ({
+      const resolved = resolvePortSchemas(
+        withViewDeclaration([human], {
           in: viewIn,
           approve: viewOut,
           reject: viewReject,
         }),
-      })
+        [],
+      )
       expect(resolved.get(humanIn.id)).toEqual(viewIn)
       expect(resolved.get(approve.id)).toEqual(viewOut)
       expect(resolved.get(reject.id)).toEqual(viewReject)
@@ -661,6 +663,128 @@ describe("型伝播（導出ポートの解決）", () => {
     expect(resolved.get(start.outMain.id)).toEqual(UNDECLARED_SCHEMA)
   })
 
+  // flexible：AI の in の型属性。宣言（推奨型）を維持し、接続の型を問わない。
+  // start へは型と同じ経路で導出される（AIノード入力のflexible属性（任意の型で呼べるループ）.md）
+  describe("flexible（推奨型を維持して任意の型を受ける in）", () => {
+    const flexibleAi = (declared: JsonSchema) => {
+      const inPort: GraphPort = {
+        ...port("in", "in", declared),
+        flexible: true,
+      }
+      return {
+        node: { id: uuid(), kind: "ai", ports: [inPort, port("out", "main")] },
+        inPort,
+      }
+    }
+    const recommended = {
+      type: "object",
+      properties: { prompt: { type: "string" } },
+      required: ["prompt"],
+    }
+
+    it("flexible な in は接続元の具体型で上書きしない（宣言＝推奨型を維持）", () => {
+      const program = programNode({ type: "string" })
+      const progOut = program.node.ports.find(
+        (p) => p.io === "out",
+      ) as GraphPort
+      progOut.schema = declaredOut
+      const ai = flexibleAi(recommended)
+      const resolved = resolvePortSchemas(
+        [program.node, ai.node],
+        [{ from_port_id: progOut.id, to_port_id: ai.inPort.id }],
+      )
+      expect(resolved.get(ai.inPort.id)).toEqual(recommended)
+    })
+
+    it("flexible な in は型の割れた fan-in でも推奨型を維持する", () => {
+      const a = programNode({ type: "string" })
+      const aOut = a.node.ports.find((p) => p.io === "out") as GraphPort
+      aOut.schema = { type: "string" }
+      const b = programNode({ type: "string" })
+      const bOut = b.node.ports.find((p) => p.io === "out") as GraphPort
+      bOut.schema = { type: "number" }
+      const ai = flexibleAi(recommended)
+      const resolved = resolvePortSchemas(
+        [a.node, b.node, ai.node],
+        [
+          { from_port_id: aOut.id, to_port_id: ai.inPort.id },
+          { from_port_id: bOut.id, to_port_id: ai.inPort.id },
+        ],
+      )
+      expect(resolved.get(ai.inPort.id)).toEqual(recommended)
+    })
+
+    it("start → AI(flexible) 直結：start の in / out main が推奨型で flexible になる", () => {
+      const start = startNode()
+      const ai = flexibleAi(recommended)
+      const connections = [
+        { from_port_id: start.outMain.id, to_port_id: ai.inPort.id },
+      ]
+      expect(resolveFlexiblePorts([start.node, ai.node], connections)).toEqual(
+        new Set([start.inPort.id, start.outMain.id]),
+      )
+      const propagated = propagateDerivedPorts(
+        [start.node, ai.node],
+        connections,
+      )[0]
+      if (!propagated) throw new Error("start not propagated")
+      for (const p of propagated.ports) {
+        expect(p.schema).toEqual(recommended)
+        expect(p.flexible).toBe(true)
+      }
+    })
+
+    it("start → [AI(flexible), program]：非 flexible の接続先が混ざれば start は flexible にならない", () => {
+      const start = startNode()
+      const ai = flexibleAi(recommended)
+      const program = programNode(recommended)
+      const connections = [
+        { from_port_id: start.outMain.id, to_port_id: ai.inPort.id },
+        { from_port_id: start.outMain.id, to_port_id: program.inPort.id },
+      ]
+      expect(
+        resolveFlexiblePorts([start.node, ai.node, program.node], connections),
+      ).toEqual(new Set())
+    })
+
+    it("start：未接続なら flexible にならず、ports に残った古い flexible は落とす", () => {
+      const inPort: GraphPort = { ...port("in", "in"), flexible: true }
+      const outMain: GraphPort = { ...port("out", "main"), flexible: true }
+      const start = { id: uuid(), kind: "start", ports: [inPort, outMain] }
+      const propagated = propagateDerivedPorts([start], [])[0]
+      if (!propagated) throw new Error("start not propagated")
+      for (const p of propagated.ports) expect(p.flexible).toBeUndefined()
+    })
+
+    it("component の in（契約の焼き込みで flexible）に直結した start も flexible（推移）", () => {
+      const start = startNode()
+      const compIn: GraphPort = {
+        ...port("in", "in", recommended),
+        flexible: true,
+      }
+      const component = {
+        id: uuid(),
+        kind: "component",
+        ports: [compIn, port("out", "main")],
+      }
+      expect(
+        resolveFlexiblePorts(
+          [start.node, component],
+          [{ from_port_id: start.outMain.id, to_port_id: compIn.id }],
+        ),
+      ).toEqual(new Set([start.inPort.id, start.outMain.id]))
+    })
+
+    it("connectionAccepted：受け側が flexible なら型を問わず可、そうでなければ isSchemaSubset", () => {
+      const to = port("in", "in", recommended)
+      expect(connectionAccepted({ type: "string" }, to)).toBe(false)
+      expect(
+        connectionAccepted({ type: "string" }, { ...to, flexible: true }),
+      ).toBe(true)
+      expect(connectionAccepted(recommended, to)).toBe(true)
+    })
+  })
+
   it("propagateDerivedPorts：schema を書き戻し、変化のないノードは同じ参照を返す", () => {
     const progOut = port("out", "main", declaredOut)
     const program = {

package/_schemas/port-spec.ts

@@ -1,8 +1,9 @@
 import { z } from "zod"
+import type { HumanDeclaration } from "./human-manifest.js"
 import type { GraphPort, JsonSchema, PortIo } from "./node.js"
 
 // ポートの kind 別型システム（docs/tasks/done/ポートのkind別仕様.md）。
-// 型の決まり方は2分類：宣言（program / ai の in・out。human はビューの宣言を転写）／
+// 型の決まり方は2分類：宣言（program / ai の in・out。human は実装（nodes/human/）の宣言を転写）／
 // 導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）。
 // mawaru がコードで型を固定するポートは無い
 // （docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md）
@@ -265,7 +266,7 @@ export const kindPortsViolation = (
 // ---- 型伝播（導出ポートの解決） ----
 // 接続の両端は同じスキーマになる（値入力フォームのSchemaForm統一.md）。
 // wait は素通し（パラメトリック）ノード：in は接続元の out、out は in と同型。
-// human はビューの宣言を転写（"T" は素通しと同じ挙動。reject もビューの宣言）。
+// human は実装（nodes/human/）の宣言を転写（"T" は素通しと同じ挙動。reject もビューの宣言）。
 // 宣言 out（program / ai）は触らない。
 // program / ai の in は**全ての口が**接続鏡映（sticky）：接続元 out が具体型のときだけ
 // 上書きし、未接続・型割れ・未宣言は現スキーマ（宣言）を維持する（鏡映結果は repo の
@@ -328,6 +329,9 @@ type PropagationNode = {
   id: string
   kind: string
   ports: GraphPort[]
+  // human のときだけ意味を持つ：実装（nodes/human/<dir>/）の宣言の写し（node_humans.declaration）。
+  // 無ければ in・approve は上流のコピー、reject は触らない
+  human?: { declaration?: HumanDeclaration } | null
 }
 type PortLink = { from_port_id: string; to_port_id: string }
 
@@ -338,23 +342,6 @@ export const COPY_UPSTREAM_SCHEMA = "T"
 // ポートの型宣言：具体型か、上流からのコピー指示か
 export type DeclaredPortSchema = JsonSchema | typeof COPY_UPSTREAM_SCHEMA
 
-// 伝播のオプション。sdk は承認ビューのカタログを知らない（非公開。企業向けビューの
-// キーが npm 公開物に載るのを避ける）ので、呼び出し元が解決して渡す
-// → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
-export type PropagationOptions<N> = {
-  // human の in / approve / reject に転写する型（承認ビューの宣言）。null / undefined
-  // ならその node は対象外（human 以外）。上流ノードの kind は一切見ない。
-  // reject は具体型のみ（上流からのコピー指示は意味を持たない）
-  viewPortSchemasOf?: (node: N) =>
-    | {
-        in: DeclaredPortSchema
-        approve: DeclaredPortSchema
-        reject: JsonSchema
-      }
-    | null
-    | undefined
-}
-
 // end も導出ノード（各 in は上流から、out main は未宣言）。個別処理は
 // resolvePortSchemas 内で行うが、初期スキーマを未宣言にするためここに含める。
 // start も導出ノード：out main は接続先の in から逆向きに転写し、in は out と同型
@@ -380,7 +367,6 @@ const isDerivedPort = (kind: string, port: Pick<GraphPort, "io" | "key">) =>
 export const resolvePortSchemas = <N extends PropagationNode>(
   nodes: N[],
   connections: PortLink[],
-  options?: PropagationOptions<N>,
 ): Map<string, JsonSchema> => {
   const resolved = new Map<string, JsonSchema>()
   const kindByPortId = new Map<string, string>()
@@ -487,6 +473,8 @@ export const resolvePortSchemas = <N extends PropagationNode>(
       if (isMirror) {
         for (const port of node.ports) {
           if (port.io !== "in") continue
+          // flexible な in は宣言（推奨型）を維持する（接続の型を問わない口）
+          if (port.flexible === true) continue
           const sources = inbound.get(port.id) ?? []
           const inSchema = mergeInboundSchemas(
             sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA),
@@ -502,13 +490,14 @@ export const resolvePortSchemas = <N extends PropagationNode>(
       const inSchema = mergeInboundSchemas(
         sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA),
       )
-      // 承認ビューの宣言を human のポートへそのまま転写する（上流ノードの kind は見ない）。
+      // 実装（nodes/human/<dir>/）の宣言を human のポートへそのまま転写する（上流ノードの kind は見ない）。
       // "T" は「上流の out をコピー」（in）／「in と同型」（approve）。reject は具体型の宣言
       // のみで、宣言が無ければ未宣言のまま（mawaru が型を焼き込むことはしない）。
       // 上流の out は書き換えない：逆伝播すると fan-out 先のビューが食い違ったとき
       // 型割れが config.json へ write-through され、元の出力宣言を黙って壊す。
       // ズレは接続の型エラーで見せてユーザーの [修正する] で直す
-      const declared = options?.viewPortSchemasOf?.(node)
+      const declared =
+        node.kind === "human" ? node.human?.declaration : undefined
       const effectiveIn =
         declared && declared.in !== COPY_UPSTREAM_SCHEMA
           ? declared.in
@@ -535,19 +524,81 @@ export const resolvePortSchemas = <N extends PropagationNode>(
 
 // ノード配列へ伝播結果を書き戻す（接続変更時のポートデータ自動更新）。
 // schema が変わらないポート・ノードは同じ参照を返す
+// flexible の導出：start の in / out main は、接続先の in が1つ以上あり**全て** flexible
+// （AI の宣言 in・契約で焼き込まれた component の in）のときだけ flexible。
+// 非 flexible の接続先（program 等）が1つでも混ざれば型どおりの入力が要るので false。
+// 直結のみ（wait 等の素通し経由は型と同じく流さない）。戻りは flexible になる port_id の集合
+export const resolveFlexiblePorts = (
+  nodes: PropagationNode[],
+  connections: PortLink[],
+): Set<string> => {
+  const flexibleByPortId = new Map<string, boolean>()
+  for (const node of nodes) {
+    if (node.kind === "start") continue
+    for (const port of node.ports) {
+      if (port.io === "in")
+        flexibleByPortId.set(port.id, port.flexible === true)
+    }
+  }
+  const outbound = new Map<string, string[]>()
+  for (const conn of connections) {
+    const outs = outbound.get(conn.from_port_id) ?? []
+    outs.push(conn.to_port_id)
+    outbound.set(conn.from_port_id, outs)
+  }
+  const flexible = new Set<string>()
+  for (const node of nodes) {
+    if (node.kind !== "start") continue
+    const inPort = node.ports.find((p) => p.io === "in")
+    const outMain = node.ports.find((p) => p.io === "out" && p.key === "main")
+    if (!inPort || !outMain) continue
+    const targets = outbound.get(outMain.id) ?? []
+    if (
+      targets.length > 0 &&
+      targets.every((id) => flexibleByPortId.get(id) === true)
+    ) {
+      flexible.add(inPort.id)
+      flexible.add(outMain.id)
+    }
+  }
+  return flexible
+}
+
+// 接続の型が受け入れられるか：受け側が flexible なら常に可、それ以外は 伝播型 ⊆ 宣言。
+// sdk の保存契約・backend の保存時チェック・エディタの表示はすべてこれを使う
+// （判定が散ると表示と保存がズレる）
+export const connectionAccepted = (
+  from: JsonSchema,
+  to: Pick<GraphPort, "schema" | "flexible">,
+): boolean => to.flexible === true || isSchemaSubset(from, to.schema)
+
 export const propagateDerivedPorts = <N extends PropagationNode>(
   nodes: N[],
   connections: PortLink[],
-  options?: PropagationOptions<N>,
 ): N[] => {
-  const resolved = resolvePortSchemas(nodes, connections, options)
+  const resolved = resolvePortSchemas(nodes, connections)
+  const flexiblePorts = resolveFlexiblePorts(nodes, connections)
   return nodes.map((node) => {
     let touched = false
     const ports = node.ports.map((port) => {
       const schema = resolved.get(port.id) ?? port.schema
-      if (JSON.stringify(schema) === JSON.stringify(port.schema)) return port
+      // start の flexible は導出結果で置き換える（false は省略＝キー無し）
+      const flexible =
+        node.kind === "start"
+          ? flexiblePorts.has(port.id) || undefined
+          : port.flexible
+      if (
+        JSON.stringify(schema) === JSON.stringify(port.schema) &&
+        flexible === port.flexible
+      )
+        return port
       touched = true
-      return { ...port, schema }
+      const { flexible: _dropped, ...rest } = port
+      return {
+        ...rest,
+        schema,
+        ...(flexible ? { flexible } : {}),
+      } as typeof port
     })
     return touched ? { ...node, ports } : node
   })

package/dist/_cli/login.js

@@ -1,7 +1,7 @@
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { saveCredentials } from "./credentials.js";
+import { openBrowser } from "./openBrowser.js";
 // `gh auth login` と同じループバック方式（RFC 8252）。
 // CLI が 127.0.0.1 の一時ポートで待ち受け、ブラウザで mawaru の /cli-auth を開く。
 // 承認するとブラウザがループバック URL へ**遷移**してトークンを渡す
@@ -11,20 +11,6 @@ const page = (title, message) => `<!doctype html><meta charset="utf-8"><title>${
     `<body style="font-family:system-ui;display:grid;place-items:center;height:100vh;margin:0">` +
     `<div style="text-align:center"><h1 style="font-size:1.25rem">${title}</h1>` +
     `<p style="color:#666">${message}</p></div></body>`;
-// ブラウザを開く（開けなければ URL を出して手で開いてもらう。依存は足さない）
-const openBrowser = (url) => {
-    const [command, args] = process.platform === "darwin"
-        ? ["open", [url]]
-        : process.platform === "win32"
-            ? ["cmd", ["/c", "start", "", url]]
-            : ["xdg-open", [url]];
-    try {
-        spawn(command, args, { stdio: "ignore", detached: true }).unref();
-    }
-    catch {
-        // 何もしない（URL は既に印字済み）
-    }
-};
 export const runLogin = async (timeoutMs = 5 * 60 * 1000) => {
     // 別のローカルプロセスが投げ込んだ応答を受け付けないための照合値
     const state = randomUUID();

package/dist/_cli/openBrowser.d.ts

@@ -0,0 +1 @@
+export declare const openBrowser: (url: string) => void;

package/dist/_cli/openBrowser.js

@@ -0,0 +1,15 @@
+import { spawn } from "node:child_process";
+// ブラウザを開く（開けなければ URL を出して手で開いてもらう。依存は足さない）
+export const openBrowser = (url) => {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        spawn(command, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        // 何もしない（URL は既に印字済み）
+    }
+};

package/dist/_cli/previewApi.d.ts

@@ -1,5 +1,5 @@
 import { type Credentials } from "./credentials.js";
-export type MawaruApi = (method: "GET" | "POST", path: string, body?: unknown) => Promise<{
+export type MawaruApi = (method: "GET" | "POST" | "PUT", path: string, body?: unknown) => Promise<{
     status: number;
     body: unknown;
 }>;

package/dist/_cli/previewCommand.d.ts

@@ -5,14 +5,22 @@ export type PreviewOptions = {
     case?: string;
     surface?: SlackSurface;
     channel?: string;
+    once?: boolean;
 };
 export declare const parsePreviewArgs: (args: string[]) => PreviewOptions;
 type Log = (line: string) => void;
+export type PreviewEnv = {
+    tenantId: string;
+    appUrl: string;
+    openUrl: (url: string) => void;
+    watch: (dir: string, onChange: () => Promise<void>) => Promise<void>;
+};
 export declare const runPreviewWith: (params: {
     root: string;
     options: PreviewOptions;
     api: MawaruApi;
     log: Log;
+    env?: Partial<PreviewEnv>;
 }) => Promise<number>;
 export declare const runPreview: (args: string[]) => Promise<number>;
 export {};