i-repo 2.11.0 → 2.13.0

package/dist/bin/irepo.js

@@ -23,6 +23,7 @@ import { reportsCommand } from "../commands/reports/index.js";
 import { definitionBatchesCommand } from "../commands/definition-batches/index.js";
 import { reportBatchesCommand } from "../commands/report-batches/index.js";
 import { systemsCommand } from "../commands/systems/index.js";
+import { deliverCommand } from "../commands/deliver/index.js";
 import { rawCommand } from "../commands/raw.js";
 import { schemaCommand } from "../commands/schema.js";
 import { pluginCommand } from "../commands/plugin.js";
@@ -154,6 +155,7 @@ program.addCommand(reportsCommand);
 program.addCommand(definitionBatchesCommand);
 program.addCommand(reportBatchesCommand);
 program.addCommand(systemsCommand);
+program.addCommand(deliverCommand);
 program.addCommand(rawCommand);
 program.addCommand(schemaCommand);
 program.addCommand(pluginCommand);

package/dist/commands/deliver/aggregate.d.ts

@@ -0,0 +1,90 @@
+/**
+ * run 集約 `deliver-run` の組み立て（spec.md §9.7 / catalog.schema.json deliverRun）。
+ *
+ * per-sink「成功(delivered)」と run status の唯一の判定をここに集約する（§9.2）。
+ * CLI は catalog/watermark を書かず、この 1 オブジェクトを stdout に出す。
+ */
+import type { SinkKind } from "./spec.js";
+export type SinkStatus = "success" | "partial" | "failed" | "skipped";
+export type RunStatus = "success" | "partial" | "failed";
+export interface SinkResult {
+    id: string;
+    plugin: string;
+    kind: SinkKind;
+    storeKind?: string;
+    dest?: string | null;
+    canonicalLandedUri?: string | null;
+    /** alreadyDelivered によりスキップしたか。 */
+    skipped: boolean;
+    skippedReason?: string;
+    /** capture の exit code（skipped のときは undefined）。 */
+    code?: number;
+    /** その sink の receipt 行（skipped は []）。 */
+    receipts: Record<string, unknown>[];
+    /** 失敗時の人間可読メモ。 */
+    failure?: string;
+}
+export interface DeliverRunMeta {
+    batchId: string;
+    flowId?: string;
+    flowName?: string;
+    trigger?: string;
+    startedAt: string;
+    finishedAtIso: string;
+    dryRun: boolean;
+    archiveOk: boolean;
+    archivePath: string | null;
+    /** archive 抽出のレコード件数（counts.target）。 */
+    archiveCount: number;
+}
+export interface DeliverRunSink {
+    id: string;
+    plugin: string;
+    kind: SinkKind;
+    storeKind?: string;
+    status: SinkStatus;
+    delivered: boolean;
+    skippedReason?: string;
+    dest?: string | null;
+    canonicalLandedUri?: string | null;
+    failure?: string;
+    receipts: Record<string, unknown>[];
+}
+export interface DeliverRun {
+    recordType: "deliver-run";
+    schemaVersion: string;
+    contract: "gemba-deliver/1.0";
+    deliverApi: string[];
+    batchId: string;
+    flowId?: string;
+    flowName?: string;
+    trigger?: string;
+    startedAt: string;
+    finishedAtIso: string;
+    status: RunStatus;
+    delivered: boolean;
+    dryRun: boolean;
+    watermarkAdvanced: boolean;
+    archivePath: string | null;
+    counts: {
+        target: number;
+        success: number;
+        failed: number;
+    };
+    sinks: DeliverRunSink[];
+    deliveredSinkIds: string[];
+    retrySinkIds: string[];
+    pluginReceipts: Record<string, unknown>[];
+}
+/**
+ * verify-phase receipt が verified:true && failedCount==0 を出したか（§0.1 原則1）。
+ * failedCount は**実数 0** を要求する（欠落/null を 0 と推定して成功扱いしない＝
+ * 壊れた receipt から delivered を導かない）。
+ */
+export declare function receiptVerifiedOk(receipts: Record<string, unknown>[]): boolean;
+/**
+ * userinfo（`scheme://user:pass@host`）を含む secret を receipt から落とす（§6.2）。
+ * elastic dest 等への混入が実在するため、stdout へ出す前に必ず通す。
+ */
+export declare function maskUserinfo<T>(value: T): T;
+export declare function buildDeliverRun(meta: DeliverRunMeta, sinks: SinkResult[]): DeliverRun;

package/dist/commands/deliver/aggregate.js

@@ -0,0 +1,130 @@
+/**
+ * verify-phase receipt が verified:true && failedCount==0 を出したか（§0.1 原則1）。
+ * failedCount は**実数 0** を要求する（欠落/null を 0 と推定して成功扱いしない＝
+ * 壊れた receipt から delivered を導かない）。
+ */
+export function receiptVerifiedOk(receipts) {
+    return receipts.some((r) => r.phase === "verify" && r.verified === true && typeof r.failedCount === "number" && r.failedCount === 0);
+}
+/**
+ * verify-phase receipt の failedCount（数値のみ）。無ければ undefined。
+ * write 相の failedCount を拾わない — 失敗 sink の write receipt が failedCount:0
+ * を持っていても、それで「失敗 0 件」と誤計上しないため（verify が真実の相）。
+ */
+function verifyFailedCount(receipts) {
+    for (let i = receipts.length - 1; i >= 0; i--) {
+        const r = receipts[i];
+        if (r.phase === "verify" && typeof r.failedCount === "number")
+            return r.failedCount;
+    }
+    return undefined;
+}
+/**
+ * userinfo（`scheme://user:pass@host`）を含む secret を receipt から落とす（§6.2）。
+ * elastic dest 等への混入が実在するため、stdout へ出す前に必ず通す。
+ */
+export function maskUserinfo(value) {
+    if (typeof value === "string") {
+        return value.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@\s]+@/g, "$1***@");
+    }
+    if (Array.isArray(value))
+        return value.map((v) => maskUserinfo(v));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = maskUserinfo(v);
+        return out;
+    }
+    return value;
+}
+export function buildDeliverRun(meta, sinks) {
+    const dryRun = meta.dryRun;
+    const outSinks = sinks.map((s) => {
+        let status;
+        let delivered;
+        if (s.skipped) {
+            status = "skipped";
+            // already-delivered は前回 verify 済みを継承（§9.2）。dry-run は何も配信
+            // しないので delivered:false（run も !dryRun を要求するので整合）。
+            delivered = !dryRun;
+        }
+        else if (dryRun) {
+            // dry-run は配信/検証しない: exit 0 を実行成功とみなすが delivered は false。
+            status = s.code === 0 ? "success" : "failed";
+            delivered = false;
+        }
+        else {
+            const ok = receiptVerifiedOk(s.receipts);
+            status = ok ? "success" : "failed";
+            delivered = ok;
+        }
+        return {
+            id: s.id,
+            plugin: s.plugin,
+            kind: s.kind,
+            ...(s.storeKind ? { storeKind: s.storeKind } : {}),
+            status,
+            delivered,
+            ...(s.skippedReason ? { skippedReason: s.skippedReason } : {}),
+            ...(s.dest !== undefined ? { dest: s.dest } : {}),
+            ...(s.canonicalLandedUri !== undefined ? { canonicalLandedUri: s.canonicalLandedUri } : {}),
+            ...(s.failure ? { failure: s.failure } : {}),
+            receipts: maskUserinfo(s.receipts),
+        };
+    });
+    // run status（§9.7）: archive 失敗は failed。以降は sink 実行結果で判定。
+    let status;
+    if (!meta.archiveOk) {
+        status = "failed";
+    }
+    else {
+        const execOk = (x) => x.status === "success" || x.status === "skipped";
+        const allOk = outSinks.every(execOk);
+        const anyOk = outSinks.some(execOk);
+        const anyFail = outSinks.some((x) => x.status === "failed");
+        if (allOk)
+            status = "success";
+        else if (anyOk && anyFail)
+            status = "partial";
+        else
+            status = "failed";
+    }
+    const delivered = meta.archiveOk && outSinks.every((s) => s.delivered) && !dryRun;
+    const watermarkAdvanced = status === "success" && !dryRun;
+    // counts はレコード件数（archive 由来。sink 数ではない）。最悪 sink の
+    // failedCount を run 全体の失敗とみなす（fan-out は全 sink 到達で1件成功）。
+    const target = meta.archiveCount;
+    let failed = 0;
+    for (const s of sinks) {
+        if (s.skipped)
+            continue;
+        const ok = !dryRun && receiptVerifiedOk(s.receipts);
+        const f = ok ? 0 : (verifyFailedCount(s.receipts) ?? (dryRun ? 0 : target));
+        if (f > failed)
+            failed = f;
+    }
+    const success = Math.max(0, target - failed);
+    const pluginReceipts = maskUserinfo(sinks.flatMap((s) => s.receipts));
+    return {
+        recordType: "deliver-run",
+        schemaVersion: "1.0",
+        contract: "gemba-deliver/1.0",
+        deliverApi: ["1"],
+        batchId: meta.batchId,
+        ...(meta.flowId ? { flowId: meta.flowId } : {}),
+        ...(meta.flowName ? { flowName: meta.flowName } : {}),
+        ...(meta.trigger ? { trigger: meta.trigger } : {}),
+        startedAt: meta.startedAt,
+        finishedAtIso: meta.finishedAtIso,
+        status,
+        delivered,
+        dryRun,
+        watermarkAdvanced,
+        archivePath: meta.archivePath,
+        counts: { target, success, failed },
+        sinks: outSinks,
+        deliveredSinkIds: outSinks.filter((s) => s.delivered).map((s) => s.id),
+        retrySinkIds: outSinks.filter((s) => s.status === "failed").map((s) => s.id),
+        pluginReceipts,
+    };
+}

package/dist/commands/deliver/enrich.d.ts

@@ -0,0 +1,17 @@
+/**
+ * locator enrich Transform（spec.md §9.4）。
+ *
+ * archive bundle の reports.ndjson と stream sink の stdin の間に挟まり、各封筒
+ * レコードへ `canonicalLandedUri` を注入する。`values` は触らない。stream-end
+ * トレーラ（§2.6）は完全性検証に必須なので**無加工で透過**。壊れた行も透過
+ * （fail-open・§4.7）＝enrich の不調で sink ストリームからレコードを落とさない。
+ *
+ * 実パス（landedPrefix + objectKey）の解決は resolveLocator が担う（locator.ts。
+ * landedPrefix は bundle sink の push receipt 由来・objectKey は archive receipt
+ * 由来）。解決できないレコード（text-only・bundle 未着地）は null＝「既知の不在」を
+ * 明示注入する。
+ */
+import { Transform } from "node:stream";
+/** レコード（封筒）から locator を解決する。実パスが確定できなければ null。 */
+export type LocatorResolver = (record: Record<string, unknown>) => string | null;
+export declare function createLocatorEnrich(resolveLocator: LocatorResolver): Transform;

package/dist/commands/deliver/enrich.js

@@ -0,0 +1,64 @@
+/**
+ * locator enrich Transform（spec.md §9.4）。
+ *
+ * archive bundle の reports.ndjson と stream sink の stdin の間に挟まり、各封筒
+ * レコードへ `canonicalLandedUri` を注入する。`values` は触らない。stream-end
+ * トレーラ（§2.6）は完全性検証に必須なので**無加工で透過**。壊れた行も透過
+ * （fail-open・§4.7）＝enrich の不調で sink ストリームからレコードを落とさない。
+ *
+ * 実パス（landedPrefix + objectKey）の解決は resolveLocator が担う（locator.ts。
+ * landedPrefix は bundle sink の push receipt 由来・objectKey は archive receipt
+ * 由来）。解決できないレコード（text-only・bundle 未着地）は null＝「既知の不在」を
+ * 明示注入する。
+ */
+import { Transform } from "node:stream";
+export function createLocatorEnrich(resolveLocator) {
+    let buffer = "";
+    const transformLine = (line) => {
+        if (line.length === 0)
+            return "";
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            // 壊れた行は透過（fail-open）。sink 側の完全性検証に委ねる。
+            process.stderr.write("deliver: passing through a non-JSON manifest line unchanged\n");
+            return line;
+        }
+        if (rec === null || typeof rec !== "object" || Array.isArray(rec))
+            return line;
+        const obj = rec;
+        // トレーラは無加工で透過（count/形を変えない）。
+        if (obj.recordType === "stream-end")
+            return line;
+        obj.canonicalLandedUri = resolveLocator(obj);
+        return JSON.stringify(obj);
+    };
+    return new Transform({
+        readableObjectMode: false,
+        writableObjectMode: false,
+        transform(chunk, _enc, cb) {
+            buffer += chunk.toString("utf-8");
+            let nl = buffer.indexOf("\n");
+            const out = [];
+            while (nl !== -1) {
+                const line = buffer.slice(0, nl);
+                out.push(transformLine(line));
+                buffer = buffer.slice(nl + 1);
+                nl = buffer.indexOf("\n");
+            }
+            cb(null, out.length ? out.join("\n") + "\n" : "");
+        },
+        flush(cb) {
+            // 末尾改行が無いまま終端した最終行も取りこぼさない。
+            if (buffer.length > 0) {
+                const last = transformLine(buffer);
+                buffer = "";
+                cb(null, last.length ? last + "\n" : "");
+                return;
+            }
+            cb();
+        },
+    });
+}

package/dist/commands/deliver/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * irepo deliver — fan-out オーケストレータ（spec.md §9 / SCHEMA.md §9）。
+ *
+ * 1 回の抽出（archive create）を複数 sink へ同時配信する host 動詞。既存単機能
+ * sink（elastic/sqlite/mongo, archive push-*）は不変のまま並べて呼ぶ。run 集約
+ * `deliver-run` を stdout に 1 オブジェクトとして出す（CLI は catalog を書かない）。
+ */
+import { Command } from "commander";
+export declare const deliverCommand: Command;

package/dist/commands/deliver/index.js

@@ -0,0 +1,36 @@
+/**
+ * irepo deliver — fan-out オーケストレータ（spec.md §9 / SCHEMA.md §9）。
+ *
+ * 1 回の抽出（archive create）を複数 sink へ同時配信する host 動詞。既存単機能
+ * sink（elastic/sqlite/mongo, archive push-*）は不変のまま並べて呼ぶ。run 集約
+ * `deliver-run` を stdout に 1 オブジェクトとして出す（CLI は catalog を書かない）。
+ */
+import { Command } from "commander";
+import { ExitCode } from "../../core/errors.js";
+import { loadDeliverSpec } from "./spec.js";
+import { runDeliver } from "./orchestrator.js";
+export const deliverCommand = new Command("deliver")
+    .description("Fan out one extraction to multiple sinks (SCHEMA.md §9)")
+    .option("--spec <file>", "deliver job spec JSON (gemba-deliver/1.0); reads stdin when omitted")
+    .option("--dry-run", "validate the spec and check extraction feasibility without delivering")
+    .option("--archive-clean", "remove the archive bundle dir on a full success")
+    .action(async (opts, cmd) => {
+    const globals = cmd.optsWithGlobals();
+    const spec = loadDeliverSpec(opts.spec);
+    const dryRun = !!opts.dryRun || spec.dryRun === true;
+    const ctx = {
+        endpoint: globals.endpoint,
+        user: globals.user,
+        format: globals.format,
+        quiet: globals.quiet,
+        timeout: globals.timeout,
+    };
+    const run = await runDeliver(spec, ctx, { dryRun, archiveClean: !!opts.archiveClean });
+    // run 集約は常に stdout へ（DC が結果に依らず永続化できる・§9.7）。
+    process.stdout.write(JSON.stringify(run) + "\n");
+    // exit code: success=0 / partial=7（失敗 sink だけ再送）/ failed=1（全体リトライ）。
+    process.exitCode =
+        run.status === "success" ? ExitCode.Success
+            : run.status === "partial" ? ExitCode.PartialFailure
+                : 1;
+});

package/dist/commands/deliver/locator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * artifact locator の実パス解決（spec.md §9.4・Phase 3）。
+ *
+ * canonicalLandedUri = bundle sink の**実 landed prefix**（push receipt 由来＝
+ * `<--to>/<実行フォルダ>`）＋ archive receipt の per-record `objectKey`。
+ * どちらも「実際に着地した」値で、予測計算ではない（幽霊リンク無し）。
+ */
+import type { LocatorResolver } from "./enrich.js";
+/** 封筒レコードの同定キー（itemId[+revNo]）。archive receipt 側と同形。 */
+export declare function recordKey(itemId: string, revNo: string | null): string;
+/**
+ * archive create の receipt 群（`artifacts:[{itemId,revNo,type,objectKey}]`）から
+ * record → objectKey マップを作る。1 レコードに複数 type があるときは pdf を優先。
+ */
+export declare function buildObjectKeyMap(archiveReceipts: Record<string, unknown>[]): Map<string, string>;
+/**
+ * bundle sink の receipt から**実 landed prefix**（`<--to>/<実行フォルダ>`）を取り出す。
+ * 既知キーのみを見る（`/Prefix$/` の広すぎる一致で無関係フィールドを拾わない）。
+ * `localPrefix` は push-local が生のファイルパスを焼くため、§4.4.1 の
+ * `dir:<absPath>/…` 形へ正規化する（scheme でディスパッチする消費側が認識できるように）。
+ */
+export declare function extractLandedPrefix(sinkReceipts: Record<string, unknown>[]): string | null;
+/**
+ * resolver を作る。landedPrefix が無い（bundle 未着地）／objectKey が無い
+ * （当該レコードに着地成果物が無い＝text 行・要求タイプ不在）レコードは null（§9.4）。
+ */
+export declare function makeLocatorResolver(landedPrefix: string | null, objectKeyMap: Map<string, string>): LocatorResolver;

package/dist/commands/deliver/locator.js

@@ -0,0 +1,87 @@
+/** 封筒レコードの同定キー（itemId[+revNo]）。archive receipt 側と同形。 */
+export function recordKey(itemId, revNo) {
+    return `${itemId}::${revNo ?? ""}`;
+}
+function recordKeyOf(record) {
+    const id = record.itemId ?? record.topId;
+    const itemId = id == null ? "" : String(id);
+    const revNo = record.revNo == null ? "" : String(record.revNo);
+    return recordKey(itemId, revNo);
+}
+/**
+ * archive create の receipt 群（`artifacts:[{itemId,revNo,type,objectKey}]`）から
+ * record → objectKey マップを作る。1 レコードに複数 type があるときは pdf を優先。
+ */
+export function buildObjectKeyMap(archiveReceipts) {
+    const map = new Map();
+    const isPdf = new Set();
+    for (const r of archiveReceipts) {
+        const arts = r.artifacts;
+        if (!Array.isArray(arts))
+            continue;
+        for (const a of arts) {
+            if (a === null || typeof a !== "object")
+                continue;
+            const e = a;
+            if (typeof e.itemId !== "string" || typeof e.objectKey !== "string")
+                continue;
+            const k = recordKey(e.itemId, e.revNo == null ? null : String(e.revNo));
+            // pdf を最優先。既に pdf を採用済みのキーは上書きしない。
+            if (isPdf.has(k))
+                continue;
+            map.set(k, e.objectKey);
+            if (e.type === "pdf")
+                isPdf.add(k);
+        }
+    }
+    return map;
+}
+/** push プラグインが実 landed base URI を焼く receipt フィールド（store 別・閉じた集合）。 */
+const LANDED_PREFIX_KEYS = ["s3Prefix", "gcsPrefix", "azurePrefix", "localPrefix"];
+/**
+ * bundle sink の receipt から**実 landed prefix**（`<--to>/<実行フォルダ>`）を取り出す。
+ * 既知キーのみを見る（`/Prefix$/` の広すぎる一致で無関係フィールドを拾わない）。
+ * `localPrefix` は push-local が生のファイルパスを焼くため、§4.4.1 の
+ * `dir:<absPath>/…` 形へ正規化する（scheme でディスパッチする消費側が認識できるように）。
+ */
+export function extractLandedPrefix(sinkReceipts) {
+    for (const r of sinkReceipts) {
+        for (const k of LANDED_PREFIX_KEYS) {
+            const v = r[k];
+            if (typeof v !== "string" || v.length === 0)
+                continue;
+            // push の prefix（--prefix/{flow} 等）は予約文字（空白・`#`・`@`）を残しうる
+            // （プラグインの無害化は `/\<>:"|?*` のみ）。round-trippable な URI にするため
+            // パスセグメントを percent-encode する（§4.4.1/§6.2）。
+            // - local: 生パス全体を `dir:` + encode。
+            // - cloud: scheme://authority は保持し、その後のパスだけ encode。
+            if (k === "localPrefix")
+                return v.startsWith("dir:") ? v : `dir:${encodePathSegments(v)}`;
+            return encodeUriPrefixPath(v);
+        }
+    }
+    return null;
+}
+/** `/` 区切りの各セグメントを percent-encode（区切りは保持）。`#`・空白・`@` で URI が壊れない（§4.4.1/§6.2）。 */
+function encodePathSegments(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+/** `scheme://authority` を保持し、その後のパスセグメントだけ percent-encode する。 */
+function encodeUriPrefixPath(uri) {
+    const m = /^([a-z][a-z0-9+.-]*:\/\/[^/]+)(\/.*)?$/i.exec(uri);
+    if (!m)
+        return uri; // scheme://authority 形でなければ触らない
+    return m[1] + (m[2] ? encodePathSegments(m[2]) : "");
+}
+/**
+ * resolver を作る。landedPrefix が無い（bundle 未着地）／objectKey が無い
+ * （当該レコードに着地成果物が無い＝text 行・要求タイプ不在）レコードは null（§9.4）。
+ */
+export function makeLocatorResolver(landedPrefix, objectKeyMap) {
+    return (record) => {
+        if (!landedPrefix)
+            return null;
+        const objectKey = objectKeyMap.get(recordKeyOf(record));
+        return objectKey ? `${landedPrefix}/${encodePathSegments(objectKey)}` : null;
+    };
+}

package/dist/commands/deliver/orchestrator.d.ts

@@ -0,0 +1,9 @@
+import type { PluginContext } from "../../plugins/dispatch.js";
+import { type DeliverRun } from "./aggregate.js";
+import type { DeliverSpec } from "./spec.js";
+export interface DeliverRunOptions {
+    dryRun: boolean;
+    /** full success のときだけ bundle dir を削除（任意・将来 --archive-clean）。 */
+    archiveClean?: boolean;
+}
+export declare function runDeliver(spec: DeliverSpec, ctx: PluginContext, opts: DeliverRunOptions): Promise<DeliverRun>;