@mawaru/sdk 0.5.0

package/dist/_schemas/node.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+export declare const nodeKindSchema: z.ZodEnum<{
+    ai: "ai";
+    human: "human";
+    program: "program";
+    guardrail: "guardrail";
+    wait: "wait";
+    start: "start";
+    end: "end";
+}>;
+export type NodeKind = z.infer<typeof nodeKindSchema>;
+export declare const PORT_KEY_PATTERN: RegExp;
+export declare const portKeySchema: z.ZodString;
+export declare const DEFAULT_OUTPUT_PORT = "main";
+export declare const DEFAULT_INPUT_PORT = "in";
+export declare const jsonSchemaSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type JsonSchema = z.infer<typeof jsonSchemaSchema>;
+export declare const portIoSchema: z.ZodEnum<{
+    in: "in";
+    out: "out";
+}>;
+export type PortIo = z.infer<typeof portIoSchema>;
+export declare const portSideSchema: z.ZodEnum<{
+    top: "top";
+    right: "right";
+    bottom: "bottom";
+    left: "left";
+}>;
+export type PortSide = z.infer<typeof portSideSchema>;
+export declare const graphPortSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    io: z.ZodEnum<{
+        in: "in";
+        out: "out";
+    }>;
+    key: z.ZodString;
+    name: z.ZodString;
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    side: z.ZodOptional<z.ZodEnum<{
+        top: "top";
+        right: "right";
+        bottom: "bottom";
+        left: "left";
+    }>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type GraphPort = z.infer<typeof graphPortSchema>;

package/dist/_schemas/node.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+export const nodeKindSchema = z.enum([
+    "ai",
+    "human",
+    "program",
+    "guardrail",
+    "wait",
+    // 開始・終了ノード（恒等パススルー。run は必ず start から始まり end で終わる。
+    // docs/tasks/wip/開始・終了ノードの定義.md）
+    "start",
+    "end",
+]);
+// ポート key（input/output 用の参照キー）の規則（db.md §2）。
+// name（ユーザーが見る表示名）は自由テキスト
+export const PORT_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+export const portKeySchema = z.string().regex(PORT_KEY_PATTERN);
+// 単一出口の既定ポート key／入力ポート key（db.md §2）
+export const DEFAULT_OUTPUT_PORT = "main";
+export const DEFAULT_INPUT_PORT = "in";
+// JSON Schema そのもの（中身の妥当性はここでは検証しない）
+export const jsonSchemaSchema = z.record(z.string(), z.unknown());
+export const portIoSchema = z.enum(["in", "out"]);
+// ポートの表示位置＝ノード境界上の「辺＋辺上の比率」（top/bottom は左→右、
+// left/right は上→下）。エディタの見た目のみで実行・接続の意味には関与しない。
+// 未指定は自動配置（先頭=右辺中央・以降=下辺等間隔）
+export const portSideSchema = z.enum(["top", "right", "bottom", "left"]);
+// グラフ保存契約のポート（ports テーブルの1行。id はクライアント採番。
+// docs/tasks/wip/ポートのテーブル化.md）
+export const graphPortSchema = z
+    .object({
+    id: z.uuid(),
+    io: portIoSchema,
+    key: portKeySchema,
+    name: z.string().min(1),
+    schema: jsonSchemaSchema,
+    side: portSideSchema.optional(),
+    offset: z.number().min(0).max(1).optional(),
+})
+    .refine((p) => (p.side === undefined) === (p.offset === undefined), {
+    message: "side と offset は両方指定するか両方省略します",
+    path: ["side"],
+});

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

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { GraphPort, JsonSchema } from "./node.js";
+export declare const ANY_SCHEMA: JsonSchema;
+export declare const isAnySchema: (schema: JsonSchema) => boolean;
+export declare const FILE_SCHEMA_MARKER = "x-mawaru-type";
+export declare const FILE_SCHEMA_TYPE = "file";
+export declare const fileSchema: () => JsonSchema;
+export declare const isFileSchema: (schema: JsonSchema) => boolean;
+export declare const LIST_COLUMN_TYPES: readonly ["string", "number", "boolean", "date"];
+export declare const listColumnTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    date: "date";
+}>;
+export type ListColumnType = z.infer<typeof listColumnTypeSchema>;
+export declare const listColumnSchema: z.ZodObject<{
+    key: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+    }>;
+}, z.core.$strip>;
+export type ListColumn = z.infer<typeof listColumnSchema>;
+export declare const dataFormatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    format: z.ZodLiteral<"text">;
+}, z.core.$strip>, z.ZodObject<{
+    format: z.ZodLiteral<"list">;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "format">;
+export type DataFormat = z.infer<typeof dataFormatSchema>;
+export declare const dataSchemaOf: (format: DataFormat) => JsonSchema;
+export declare const dataFormatOf: (schema: JsonSchema) => DataFormat | null;
+export declare const envelopeSchemaOf: (dataSchema: JsonSchema) => JsonSchema;
+export declare const envelopeDataSchemaOf: (schema: JsonSchema) => JsonSchema | null;
+export declare const isAiEnvelopeSchema: (schema: JsonSchema) => boolean;
+export declare const kindPortsViolation: (kind: string, ports: Pick<GraphPort, "io" | "key">[]) => string | null;
+type PropagationNode = {
+    id: string;
+    kind: string;
+    ports: GraphPort[];
+};
+type PortLink = {
+    from_port_id: string;
+    to_port_id: string;
+};
+export declare const resolvePortSchemas: <N extends PropagationNode>(nodes: N[], connections: PortLink[]) => Map<string, JsonSchema>;
+export declare const propagateDerivedPorts: <N extends PropagationNode>(nodes: N[], connections: PortLink[]) => N[];
+export declare const isSchemaSubset: (sub: JsonSchema, sup: JsonSchema) => boolean;
+export {};

package/dist/_schemas/port-spec.js

@@ -0,0 +1,336 @@
+import { z } from "zod";
+// ポートの kind 別型システム（docs/tasks/wip/ポートのkind別仕様.md）。
+// 型の決まり方は3分類：宣言（program / AI の in・out）／固定（human reject の
+// content 型）／導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）
+// content 型・未接続の導出ポートは any（{}）で表す。content の意味（エンジンが
+// content に変換して注入する口）はスキーマではなく kind が決める
+export const ANY_SCHEMA = {};
+export const isAnySchema = (schema) => Object.keys(schema).length === 0 || schema.type === undefined;
+// ---- file 型（AI ノードのファイル入力。docs/tasks/wip/AIノードのファイル入力（file型と添付）.md） ----
+// schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
+// ではなく storage path の参照（url は startAiStep の dispatch 時に発行して client_payload に
+// のみ載せる）。ajv は strict:false で未知キーワードを無視するので検証は素の JSON Schema のまま。
+export const FILE_SCHEMA_MARKER = "x-mawaru-type";
+export const FILE_SCHEMA_TYPE = "file";
+export const fileSchema = () => ({
+    type: "object",
+    [FILE_SCHEMA_MARKER]: FILE_SCHEMA_TYPE,
+    properties: {
+        path: { type: "string" },
+        name: { type: "string" },
+        mime_type: { type: "string" },
+        size: { type: "number" },
+    },
+    required: ["path", "name"],
+});
+export const isFileSchema = (schema) => schema[FILE_SCHEMA_MARKER] === FILE_SCHEMA_TYPE;
+// ---- データフォーマットカタログ ----
+// human 承認 UI の表示・編集フォームの出し分けに使う（テキスト＝string（markdown）／
+// リスト＝Array<Row>（列定義つき））。バリデーションには使わない（data は任意の型）
+export const LIST_COLUMN_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+];
+export const listColumnTypeSchema = z.enum(LIST_COLUMN_TYPES);
+export const listColumnSchema = z.object({
+    key: z.string().min(1),
+    name: z.string().min(1),
+    type: listColumnTypeSchema,
+});
+export const dataFormatSchema = z.discriminatedUnion("format", [
+    z.object({ format: z.literal("text") }),
+    z.object({
+        format: z.literal("list"),
+        columns: z.array(listColumnSchema).min(1),
+    }),
+]);
+const columnTypeToJsonSchema = (type) => type === "date" ? { type: "string", format: "date" } : { type };
+const columnTypeFromJsonSchema = (schema) => {
+    if (schema.type === "string") {
+        return schema.format === "date" ? "date" : "string";
+    }
+    if (schema.type === "number" || schema.type === "boolean")
+        return schema.type;
+    return null;
+};
+// フォーマット → S の JSON Schema。列の表示名は title に載せる
+export const dataSchemaOf = (format) => {
+    if (format.format === "text")
+        return { type: "string" };
+    return {
+        type: "array",
+        items: {
+            type: "object",
+            properties: Object.fromEntries(format.columns.map((col) => [
+                col.key,
+                { ...columnTypeToJsonSchema(col.type), title: col.name },
+            ])),
+            required: format.columns.map((col) => col.key),
+        },
+    };
+};
+// S の JSON Schema → フォーマット（構造マッチの逆引き。カタログ外は null）
+export const dataFormatOf = (schema) => {
+    if (schema.type === "string" && schema.format === undefined) {
+        return { format: "text" };
+    }
+    if (schema.type !== "array")
+        return null;
+    const items = schema.items;
+    if (items?.type !== "object")
+        return null;
+    const properties = (items.properties ?? {});
+    const columns = [];
+    for (const [key, prop] of Object.entries(properties)) {
+        const type = columnTypeFromJsonSchema(prop);
+        if (!type)
+            return null;
+        columns.push({ key, name: prop.title ?? key, type });
+    }
+    if (columns.length === 0)
+        return null;
+    return { format: "list", columns };
+};
+// 封筒型 { data: T, description: string }。T は任意の JSON Schema、description は
+// AI によるデータの説明（AI が必ず生成する）。AI の全出口に強制する
+export const envelopeSchemaOf = (dataSchema) => ({
+    type: "object",
+    properties: {
+        data: dataSchema,
+        description: { type: "string" },
+    },
+    required: ["data", "description"],
+});
+// 封筒型なら data のサブスキーマを返す（data キー必須の object。それ以外は null）
+export const envelopeDataSchemaOf = (schema) => {
+    if (schema.type !== "object")
+        return null;
+    const properties = (schema.properties ?? {});
+    const required = (schema.required ?? []);
+    const data = properties.data;
+    if (!data || !required.includes("data"))
+        return null;
+    return data;
+};
+// AI の出口として妥当な封筒型か：data と description: string の両方が必須
+export const isAiEnvelopeSchema = (schema) => {
+    if (envelopeDataSchemaOf(schema) === null)
+        return false;
+    const properties = (schema.properties ?? {});
+    const required = (schema.required ?? []);
+    return (properties.description?.type === "string" &&
+        required.includes("description"));
+};
+// ---- kind 別ポート構成 ----
+// human / wait は構成（数・key・io）が固定。program / ai は in 1つ＋out 1つ以上
+// （key 自由。複数 out＝分岐。AIノードの複数出口（分岐）.md）
+const FIXED_PORT_KEYS = {
+    human: { in: ["in"], out: ["approve", "reject"] },
+    wait: { in: ["in"], out: ["main"] },
+    // start は in 1つ（run 入力契約）＋ out main 1つの恒等パススルー
+    start: { in: ["in"], out: ["main"] },
+};
+const FREE_OUT_KINDS = new Set(["program", "ai"]);
+// kind 別のポート構成違反を返す（適合なら null）。in=1/out>=1 の構造ルールは
+// graph.ts 側の既存チェックが担い、ここは key の固定だけ見る
+export const kindPortsViolation = (kind, ports) => {
+    // end は out が main 1つ固定・in は1つ以上（複数ルートを別々の in で集約する。
+    // 開始・終了ノードの定義.md）。in の key は自由（自動採番）
+    if (kind === "end") {
+        const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key);
+        if (outKeys.length !== 1 || outKeys[0] !== "main") {
+            return `end の out ポートは "main" ちょうど1つです`;
+        }
+        if (!ports.some((p) => p.io === "in")) {
+            return `end には in ポートが1つ以上必要です`;
+        }
+        return null;
+    }
+    const fixed = FIXED_PORT_KEYS[kind];
+    if (!fixed) {
+        // program / ai（自由 out）：in の key だけ "in" 固定
+        if (FREE_OUT_KINDS.has(kind) &&
+            ports.some((p) => p.io === "in" && p.key !== "in"))
+            return `${kind} の in ポートの key は "in" です`;
+        return null;
+    }
+    const keysOf = (io) => ports
+        .filter((p) => p.io === io)
+        .map((p) => p.key)
+        .sort();
+    const expect = (io) => [...fixed[io]].sort();
+    if (keysOf("in").join(",") !== expect("in").join(",") ||
+        keysOf("out").join(",") !== expect("out").join(",")) {
+        return `${kind} のポート構成は in(${fixed.in.join(",")}) / out(${fixed.out.join(",")}) 固定です`;
+    }
+    return null;
+};
+// end も導出ノード（各 in は上流から、out main は any）。個別処理は
+// resolvePortSchemas 内で行うが、初期スキーマを any にするためここに含める。
+// start も導出ノード：out main は接続先の in から逆向きに転写し、in は out と同型
+// （run 入力契約＝接続先の入力宣言。開始ノードの入力契約を接続先から導出.md）
+const DERIVED_KINDS = new Set(["wait", "human", "end", "start"]);
+// in を接続鏡映（sticky）するノード：接続元 out が具体型のときだけ上書き
+const MIRROR_KINDS = new Set(["program", "ai"]);
+const isDerivedPort = (kind, port) => DERIVED_KINDS.has(kind) &&
+    (port.io === "in" || port.key === "main" || port.key === "approve");
+// AI の in は nodes/ai/<dir>/config.json の inputs.in 由来の宣言型が初期値で、
+// 接続時は program と同じ鏡映で接続元と同値に同期される（const 扱い廃止。
+// 接続バリデーションの「ai の in は常に許可」は維持）
+const isConstPort = (kind, port) => kind === "human" && port.io === "out" && port.key === "reject";
+// port_id → 解決済みスキーマ。導出は接続を遡って固定点まで反復し、
+// 未接続・複数流入・純パラメトリック閉路は any に落とす（MVP の割り切り）
+export const resolvePortSchemas = (nodes, connections) => {
+    const resolved = new Map();
+    const kindByPortId = new Map();
+    for (const node of nodes) {
+        for (const port of node.ports) {
+            kindByPortId.set(port.id, node.kind);
+            resolved.set(port.id, isDerivedPort(node.kind, port) || isConstPort(node.kind, port)
+                ? ANY_SCHEMA
+                : port.schema);
+        }
+    }
+    // in ポートへの流入（差し戻しの fan-in があり得る。1本のときだけ型を採用）
+    const inbound = new Map();
+    // out ポートからの流出（start の逆向き転写が接続先の in を引くのに使う）
+    const outbound = new Map();
+    for (const conn of connections) {
+        const list = inbound.get(conn.to_port_id) ?? [];
+        list.push(conn.from_port_id);
+        inbound.set(conn.to_port_id, list);
+        const outs = outbound.get(conn.from_port_id) ?? [];
+        outs.push(conn.to_port_id);
+        outbound.set(conn.from_port_id, outs);
+    }
+    for (let i = 0; i < nodes.length + 1; i++) {
+        let changed = false;
+        for (const node of nodes) {
+            const assign = (portId, schema) => {
+                if (JSON.stringify(resolved.get(portId)) !== JSON.stringify(schema)) {
+                    resolved.set(portId, schema);
+                    changed = true;
+                }
+            };
+            // start：out main は接続先 in の解決値を転写（逆向き導出）。fan-out は
+            // 非 any が1種類（JSON 等値）のときだけ採用し、未接続・型割れは any。
+            // in は out main と同型（恒等の向きを out→in に逆転。run 入力契約は
+            // 接続先の入力宣言から自動で決まる）
+            if (node.kind === "start") {
+                const inPort = node.ports.find((p) => p.io === "in");
+                const outMain = node.ports.find((p) => p.io === "out" && p.key === "main");
+                if (inPort && outMain) {
+                    const targets = (outbound.get(outMain.id) ?? [])
+                        .map((id) => resolved.get(id) ?? ANY_SCHEMA)
+                        .filter((s) => !isAnySchema(s))
+                        .map((s) => JSON.stringify(s));
+                    const uniq = [...new Set(targets)];
+                    const schema = uniq.length === 1 && uniq[0] !== undefined
+                        ? JSON.parse(uniq[0])
+                        : ANY_SCHEMA;
+                    assign(outMain.id, schema);
+                    assign(inPort.id, schema);
+                }
+                continue;
+            }
+            // end：各 in を自分の単一上流から導出（複数ルートを別 in で集約）。
+            // out main は any 固定（ルートごとに型が違いうる。Loop-in-Loop で詰める）
+            if (node.kind === "end") {
+                for (const port of node.ports) {
+                    if (port.io !== "in")
+                        continue;
+                    const srcs = inbound.get(port.id) ?? [];
+                    assign(port.id, srcs.length === 1 && srcs[0] !== undefined
+                        ? (resolved.get(srcs[0]) ?? ANY_SCHEMA)
+                        : ANY_SCHEMA);
+                }
+                continue;
+            }
+            const isMirror = MIRROR_KINDS.has(node.kind);
+            if (!DERIVED_KINDS.has(node.kind) && !isMirror)
+                continue;
+            const inPort = node.ports.find((p) => p.io === "in");
+            if (!inPort)
+                continue;
+            const sources = inbound.get(inPort.id) ?? [];
+            const inSchema = sources.length === 1 && sources[0] !== undefined
+                ? (resolved.get(sources[0]) ?? ANY_SCHEMA)
+                : ANY_SCHEMA;
+            // 鏡映（program）は具体型が流れてきたときだけ上書き（宣言を any で潰さない）
+            if (isMirror) {
+                if (!isAnySchema(inSchema))
+                    assign(inPort.id, inSchema);
+                continue;
+            }
+            assign(inPort.id, inSchema);
+            // human の approve：接続元が AI ノードなら封筒 { data, description } を剥がして
+            // data 型を流す（承認は data だけを下流へ渡す）。それ以外の上流は従来どおり素通し
+            const fromAiNode = sources.length === 1 &&
+                sources[0] !== undefined &&
+                kindByPortId.get(sources[0]) === "ai";
+            for (const port of node.ports) {
+                if (port.io === "out" && isDerivedPort(node.kind, port)) {
+                    assign(port.id, node.kind === "human" && port.key === "approve" && fromAiNode
+                        ? (envelopeDataSchemaOf(inSchema) ?? ANY_SCHEMA)
+                        : inSchema);
+                }
+            }
+        }
+        if (!changed)
+            break;
+    }
+    return resolved;
+};
+// ノード配列へ伝播結果を書き戻す（接続変更時のポートデータ自動更新）。
+// schema が変わらないポート・ノードは同じ参照を返す
+export const propagateDerivedPorts = (nodes, connections) => {
+    const resolved = resolvePortSchemas(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;
+            touched = true;
+            return { ...port, schema };
+        });
+        return touched ? { ...node, ports } : node;
+    });
+};
+// ---- 接続バリデーション（伝播型 ⊆ 宣言スキーマ） ----
+// 完全な JSON Schema 包含ではなく実用的な構造チェック：any は素通し、type 一致、
+// object は宣言側 required の存在と型互換、array は items 互換
+export const isSchemaSubset = (sub, sup) => {
+    if (isAnySchema(sup) || isAnySchema(sub))
+        return true;
+    // file は nominal：マーカー一致の file 同士だけ可（file → any は上の any 判定で許可）。
+    // 構造が同じだけの普通の object は file に繋がない／file は普通の object に繋がない
+    if (isFileSchema(sub) || isFileSchema(sup))
+        return isFileSchema(sub) && isFileSchema(sup);
+    if (sub.type !== sup.type)
+        return false;
+    if (sup.type === "object") {
+        const subProps = (sub.properties ?? {});
+        const subRequired = (sub.required ?? []);
+        const supProps = (sup.properties ?? {});
+        for (const key of (sup.required ?? [])) {
+            const subProp = subProps[key];
+            if (!subProp || !subRequired.includes(key))
+                return false;
+            const supProp = supProps[key];
+            if (supProp && !isSchemaSubset(subProp, supProp))
+                return false;
+        }
+        return true;
+    }
+    if (sup.type === "array") {
+        const supItems = sup.items;
+        const subItems = sub.items;
+        if (!supItems || !subItems)
+            return true;
+        return isSchemaSubset(subItems, supItems);
+    }
+    return true;
+};

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

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const programManifestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    env: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    inputs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    outputs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    refs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type ProgramManifest = z.infer<typeof programManifestSchema>;

package/dist/_schemas/program-manifest.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { jsonSchemaSchema, portKeySchema } from "./node.js";
+// nodes/program/<dir>/config.json（リポジトリ規約 v2）。プログラム自身が入出力スキーマを宣言し、
+// エディタが取り込んで ports を自動生成する（実行時の正は ports テーブルのまま。
+// docs/tasks/wip/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
+// inputs / outputs は「ポート key → JSON Schema」のマップ。将来 join（in 複数）を導入しても
+// 形式が変わらないよう最初から複数形にしてある
+export const programManifestSchema = z
+    .object({
+    // 表示名（省略時はディレクトリ名）
+    name: z.string().min(1).optional(),
+    description: z.string().optional(),
+    // 実行に必要な secret 名の宣言（runner が宣言分だけを子プロセスへ渡す。
+    // 実行repoの構造見直し）
+    env: z.array(z.string().min(1)).default([]),
+    inputs: z.record(z.string(), jsonSchemaSchema),
+    outputs: z.record(z.string(), jsonSchemaSchema),
+    // refs＝ループ変数の定義の転写（key → 値から推定した JSON Schema）。
+    // loop（エディタ）が正で、このセクションはグラフ保存が一方向に上書きする生成物。
+    // handler 実装者が「refs.json に何が来るか」を repo 側で見るためにある。
+    // 値そのものは repo に書かない（上流出力の参照（refs）.md）
+    refs: z.record(portKeySchema, jsonSchemaSchema).default({}),
+})
+    .superRefine((manifest, ctx) => {
+    // グラフ側の既存制約（in ポートちょうど1つ・key "in" 固定）に整合させる
+    const inKeys = Object.keys(manifest.inputs);
+    if (inKeys.length !== 1 || inKeys[0] !== "in") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["inputs"],
+            message: 'inputs は "in" の1件だけ宣言してください（join 導入まで）',
+        });
+    }
+    if (Object.keys(manifest.outputs).length < 1) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["outputs"],
+            message: "outputs は1件以上宣言してください",
+        });
+    }
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { relative } from "node:path";
+import { runInit } from "./init.js";
+import { runTypegen } from "./typegen.js";
+import { validateRepo } from "./validate.js";
+// 使い方: mawaru <init|typegen|validate> [repoルート]（省略時はカレントディレクトリ）
+const USAGE = `使い方: mawaru <command> [repoルート]
+
+コマンド:
+  init       repo を mawaru 実行用に初期化する（runner yml・nodes/ 骨組み・スキルポインタ等。再実行は冪等）
+  typegen    nodes/program/<dir>/config.json から types.d.ts（Input / Outputs / Output 型）を生成する
+  validate   リポジトリ規約を検証する（error があれば exit 1。CI 向け）`;
+const [command, rootArg] = process.argv.slice(2);
+const root = rootArg ?? process.cwd();
+switch (command) {
+    case "init": {
+        const result = runInit(root);
+        for (const path of result.written)
+            console.log(`生成: ${path}`);
+        for (const path of result.skipped)
+            console.log(`保持: ${path}（既存）`);
+        for (const note of result.notes)
+            console.log(`→ ${note}`);
+        break;
+    }
+    case "typegen": {
+        const result = runTypegen(root);
+        for (const path of result.written) {
+            console.log(`生成: ${relative(root, path)}`);
+        }
+        for (const error of result.errors) {
+            console.error(`✖ ${error.dir}: ${error.message}`);
+        }
+        process.exit(result.errors.length > 0 ? 1 : 0);
+        break;
+    }
+    case "validate": {
+        const issues = validateRepo(root);
+        for (const issue of issues) {
+            const mark = issue.level === "error" ? "✖" : "⚠";
+            console.log(`${mark} ${issue.path}: ${issue.message}`);
+        }
+        const errorCount = issues.filter((i) => i.level === "error").length;
+        console.log(issues.length === 0
+            ? "問題は見つかりませんでした"
+            : `error ${errorCount} 件 / warning ${issues.length - errorCount} 件`);
+        process.exit(errorCount > 0 ? 1 : 0);
+        break;
+    }
+    default: {
+        console.error(USAGE);
+        process.exit(command === undefined || command === "--help" ? 0 : 1);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./_schemas/ai-manifest.js";
+export * from "./_schemas/graph.js";
+export * from "./_schemas/hook-manifest.js";
+export * from "./_schemas/node.js";
+export * from "./_schemas/port-spec.js";
+export * from "./_schemas/program-manifest.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// mawaru の契約スキーマ（実行 repo の config.json 規約＋ループ graph API のボディ）。
+// 正はここ（npm 公開）で、@mawaru/common（private）が re-export して
+// backend / frontend が使う。CLI（typegen / validate）の実装は export しない
+export * from "./_schemas/ai-manifest.js";
+export * from "./_schemas/graph.js";
+export * from "./_schemas/hook-manifest.js";
+export * from "./_schemas/node.js";
+export * from "./_schemas/port-spec.js";
+export * from "./_schemas/program-manifest.js";

package/dist/init.d.ts

@@ -0,0 +1,6 @@
+export type InitResult = {
+    written: string[];
+    skipped: string[];
+    notes: string[];
+};
+export declare const runInit: (root: string) => InitResult;