@rex0220/ksql-flownet 1.0.0

package/dist/requests/request-result.d.ts

@@ -0,0 +1,18 @@
+import type { ChildProcessResult, RunNetworkJsonOutput } from "./flownet-child-client.js";
+import type { ArchiveRunOutcome } from "../orchestration/archive-run.js";
+import type { RequestResult } from "./kintone-request-store.js";
+export declare function classifyRunNetworkResult(input: {
+    readonly output: RunNetworkJsonOutput | null;
+    readonly process: ChildProcessResult;
+}): RequestResult;
+export declare function classifyStartNetworkResult(input: {
+    readonly output: RunNetworkJsonOutput | null;
+    readonly process: ChildProcessResult;
+}): RequestResult;
+export declare function classifyCancelResult(result: ChildProcessResult, release: boolean): RequestResult;
+export declare function classifyArchiveRun(input: {
+    readonly output: ArchiveRunOutcome | null;
+    readonly process: ChildProcessResult;
+}): RequestResult;
+export declare function rejected(code: string, message: string): RequestResult;
+//# sourceMappingURL=request-result.d.ts.map

package/dist/requests/request-result.js

@@ -0,0 +1,215 @@
+export function classifyRunNetworkResult(input) {
+    const output = validRunNetworkOutput(input.output) ? input.output : null;
+    if (output !== null && output.invocation_id !== null) {
+        const retryBrakeNodeIds = output.retry_brake_node_ids ?? [];
+        if (retryBrakeNodeIds.length > 0) {
+            return {
+                state: "DONE",
+                code: "RETRY_BRAKE",
+                message: `aggregate=${output.aggregate_status ?? "UNKNOWN"}; invocation_id=${output.invocation_id}; retry_brake_node_ids=${retryBrakeNodeIds.join(",")}`,
+            };
+        }
+        return {
+            state: "DONE",
+            code: output.invocation_result_code,
+            message: `aggregate=${output.aggregate_status ?? "UNKNOWN"}; invocation_id=${output.invocation_id}`,
+        };
+    }
+    if (output?.outcome === "NOOP") {
+        return {
+            state: "DONE",
+            code: output.invocation_result_code,
+            message: `aggregate=${output.aggregate_status ?? "SUCCESS"}; invocation_id=none`,
+        };
+    }
+    if (input.process.spawnError !== undefined) {
+        return rejected("CHILD_SPAWN_FAILED", "run-network child could not be started");
+    }
+    if (output?.outcome === "REJECTED") {
+        return rejected(output.invocation_result_code, "run-network rejected the request before creating an Invocation");
+    }
+    return rejected("CHILD_RESULT_INVALID", "run-network did not return a valid machine-readable result");
+}
+export function classifyStartNetworkResult(input) {
+    const output = validRunNetworkOutput(input.output) ? input.output : null;
+    if (output !== null && output.invocation_id !== null) {
+        return classifyRunNetworkResult(input);
+    }
+    if (output?.outcome === "NOOP" && output.run_id !== null) {
+        return {
+            state: "DONE",
+            code: "NOOP_ALREADY_SUCCESS",
+            message: `既存Run #${output.run_id} はSUCCESSのため起動をスキップしました。補正実行は別のbusiness_keyを指定してください。`,
+        };
+    }
+    if (input.process.spawnError !== undefined) {
+        return rejected("CHILD_SPAWN_FAILED", "run-network child could not be started");
+    }
+    if (output?.outcome === "REJECTED") {
+        const blockedRunIds = output.blocked_run_ids ?? [];
+        if (output.invocation_result_code === "RUN_ALREADY_EXISTS") {
+            const runId = blockedRunIds[0];
+            return rejected("RUN_ALREADY_EXISTS", runId === undefined
+                ? "同一業務キーの未完了Runがあります。RERUNを使用してください。"
+                : `同一業務キーの未完了Run #${runId} があります。RERUNを使用してください。`);
+        }
+        if (output.invocation_result_code === "MAX_ACTIVE_RUNS") {
+            const runId = blockedRunIds[0] ?? "不明";
+            return rejected("MAX_ACTIVE_RUNS", `未完了Run #${runId}があるため起動できません。失敗Runのやり直しはRERUNを、整理できない場合は二次対応者へ`);
+        }
+        if (output.invocation_result_code === "LOCK_CONFLICT") {
+            return rejected("LOCK_CONFLICT", "network実行ロックが競合しました。時間をおいて再起票してください。");
+        }
+        return rejected(output.invocation_result_code, "run-network rejected the START request before creating an Invocation");
+    }
+    return rejected("CHILD_RESULT_INVALID", "run-network did not return a valid machine-readable result");
+}
+export function classifyCancelResult(result, release) {
+    if (result.spawnError !== undefined) {
+        return rejected("CHILD_SPAWN_FAILED", "cancel-run child could not be started");
+    }
+    if (result.exitCode === 0) {
+        return {
+            state: "DONE",
+            code: release ? "RELEASED" : "STOP_REQUESTED",
+            message: release
+                ? "Run hold was released; no automatic resume was started"
+                : "Run hold was requested at the next node boundary",
+        };
+    }
+    return rejected("CANCEL_RUN_REJECTED", "cancel-run rejected the request or failed before completing the operation");
+}
+const ARCHIVE_PENDING_CODES = new Set([
+    "ARCHIVE_AUDIT_FAILED",
+    "AUDIT_CONFLICT",
+    "LEASE_INTERRUPTED_AFTER_ARCHIVE",
+]);
+const ARCHIVE_REJECTED_CODES = new Set([
+    "LOCK_CONFLICT",
+    "LOCK_UNAVAILABLE",
+    "LEASE_INTERRUPTED",
+    "RUN_READ_FAILED",
+    "RUN_STATUS_NOT_CLOSABLE",
+    "RUN_UNKNOWN_NOT_CLOSABLE",
+    "RUN_NOT_TERMINAL",
+    "RUN_ON_HOLD",
+    "RUN_LIVE",
+    "ARCHIVE_WRITE_FAILED",
+]);
+export function classifyArchiveRun(input) {
+    const output = validArchiveRunOutput(input.output) ? input.output : null;
+    if (output === null ||
+        input.process.spawnError !== undefined ||
+        input.process.stdoutTruncated ||
+        input.process.stderrTruncated ||
+        input.process.exitCode !== expectedArchiveExitCode(output)) {
+        return rejected("CHILD_RESULT_INVALID", "archive-run result was invalid; the Run may already be ARCHIVED, so verify it with status --json");
+    }
+    const event = `event_id=${output.event_id}`;
+    const lockFailure = output.lock_released ? "" : " lock_release_failed=true";
+    switch (output.outcome) {
+        case "ARCHIVED":
+            if (output.audit === "PENDING") {
+                return {
+                    state: "DONE",
+                    code: "RUN_ARCHIVED_AUDIT_PENDING",
+                    message: `code=${output.code} ${event}${lockFailure}`,
+                };
+            }
+            if (!output.lock_released) {
+                return {
+                    state: "DONE",
+                    code: "RUN_ARCHIVED_LOCK_UNRELEASED",
+                    message: `${event} lock_release_failed=true`,
+                };
+            }
+            return {
+                state: "DONE",
+                code: "RUN_ARCHIVED",
+                message: event,
+            };
+        case "ALREADY_ARCHIVED":
+            return output.lock_released
+                ? {
+                    state: "DONE",
+                    code: "RUN_ALREADY_ARCHIVED",
+                    message: event,
+                }
+                : {
+                    state: "DONE",
+                    code: "RUN_ARCHIVED_LOCK_UNRELEASED",
+                    message: `${event} already_archived=true lock_release_failed=true`,
+                };
+        case "UNCONFIRMED":
+            return rejected("ARCHIVE_UNCONFIRMED", `Run archive state is unconfirmed; verify it with status --json ${event}${lockFailure}`);
+        case "REJECTED":
+            return rejected(output.code, `${event}${lockFailure}`);
+    }
+}
+export function rejected(code, message) {
+    return { state: "REJECTED", code, message };
+}
+function validRunNetworkOutput(value) {
+    return (value !== null &&
+        ["NEW", "RESUME", "NOOP", "REJECTED"].includes(value.outcome) &&
+        (typeof value.run_id === "string" || value.run_id === null) &&
+        (typeof value.invocation_id === "string" || value.invocation_id === null) &&
+        (typeof value.aggregate_status === "string" ||
+            value.aggregate_status === null) &&
+        typeof value.invocation_result_code === "string" &&
+        value.invocation_result_code !== "" &&
+        (value.retry_brake_node_ids === undefined ||
+            (Array.isArray(value.retry_brake_node_ids) &&
+                value.retry_brake_node_ids.every((nodeId) => typeof nodeId === "string"))) &&
+        (value.blocked_run_ids === undefined ||
+            (Array.isArray(value.blocked_run_ids) &&
+                value.blocked_run_ids.every((runId) => typeof runId === "string"))));
+}
+function expectedArchiveExitCode(output) {
+    return (output.outcome === "ARCHIVED" &&
+        output.audit === "RECORDED" &&
+        output.lock_released) ||
+        (output.outcome === "ALREADY_ARCHIVED" && output.lock_released)
+        ? 0
+        : 1;
+}
+function validArchiveRunOutput(value) {
+    if (value === null ||
+        typeof value !== "object" ||
+        typeof value.run_id !== "string" ||
+        value.run_id === "" ||
+        typeof value.event_id !== "string" ||
+        value.event_id === "" ||
+        typeof value.lock_released !== "boolean") {
+        return false;
+    }
+    const revision = value.run_revision;
+    switch (value.outcome) {
+        case "ARCHIVED":
+            if (typeof revision !== "number" ||
+                !Number.isSafeInteger(revision) ||
+                revision < 1)
+                return false;
+            if (value.audit === "RECORDED")
+                return !("code" in value);
+            return (value.audit === "PENDING" &&
+                "code" in value &&
+                ARCHIVE_PENDING_CODES.has(value.code));
+        case "ALREADY_ARCHIVED":
+            return (typeof revision === "number" &&
+                Number.isSafeInteger(revision) &&
+                revision >= 1 &&
+                !("code" in value));
+        case "UNCONFIRMED":
+            return revision === null && value.code === "ARCHIVE_UNCONFIRMED";
+        case "REJECTED":
+            return ((revision === null ||
+                (typeof revision === "number" &&
+                    Number.isSafeInteger(revision) &&
+                    revision >= 1)) &&
+                ARCHIVE_REJECTED_CODES.has(value.code));
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=request-result.js.map

package/dist/requests/start-request.d.ts

@@ -0,0 +1,26 @@
+import type { NetworkDefinition } from "../domain/network-definition.js";
+import type { RequestResult } from "./kintone-request-store.js";
+import type { PollRequestsNetwork } from "./poll-requests-config.js";
+import type { RequestRecord } from "./request-model.js";
+export type StartNetworkInput = {
+    readonly businessKey: string;
+    readonly scheduledFor?: string;
+} | {
+    readonly scheduledFor: string;
+    readonly businessKey?: string;
+};
+export interface PreparedStartRequest {
+    readonly definition: NetworkDefinition;
+    readonly businessKey: string;
+    readonly input: StartNetworkInput;
+}
+export type StartPreparation = {
+    readonly ok: true;
+    readonly value: PreparedStartRequest;
+} | {
+    readonly ok: false;
+    readonly result: RequestResult;
+};
+export declare function prepareStartRequest(network: PollRequestsNetwork, request: Pick<RequestRecord, "businessKey" | "scheduledFor">): StartPreparation;
+export declare function startNetworkNotAllowed(detail: "NOT_IN_ALLOWLIST" | "APP_START_DISABLED"): RequestResult;
+//# sourceMappingURL=start-request.d.ts.map

package/dist/requests/start-request.js

@@ -0,0 +1,83 @@
+import { normalizeScheduledFor, resolveBusinessKey, } from "../domain/business-key.js";
+import { loadNetworkDefinition } from "../domain/load-network.js";
+export function prepareStartRequest(network, request) {
+    const loaded = loadNetworkDefinition(network.definitionPath);
+    if (loaded.definition === undefined &&
+        loaded.errors.some(({ path, message }) => path.startsWith("$/nodes/") &&
+            message.includes("required property 'idempotent'"))) {
+        return failure("NETWORK_NOT_IDEMPOTENT", "全ノードの冪等性が確認できないためSTARTでは起動できません。");
+    }
+    if (loaded.definition === undefined ||
+        loaded.errors.length > 0 ||
+        loaded.definition.network_id !== network.networkId) {
+        return failure("NETWORK_DEFINITION_INVALID", "network定義を再読込できないため起動できません。二次対応者へ連絡してください。");
+    }
+    const definition = loaded.definition;
+    if (definition.nodes.some((node) => node.idempotent !== true)) {
+        return failure("NETWORK_NOT_IDEMPOTENT", "全ノードの冪等性が確認できないためSTARTでは起動できません。");
+    }
+    const businessKey = request.businessKey ?? undefined;
+    const scheduledForInput = request.scheduledFor ?? undefined;
+    if (definition.business_key_policy.type === "explicit") {
+        if (businessKey === undefined || scheduledForInput !== undefined) {
+            return failure("KEY_POLICY_MISMATCH", "networkの業務キー規則と入力内容が一致しません。");
+        }
+        const resolved = resolveBusinessKey({
+            networkId: definition.network_id,
+            policy: definition.business_key_policy,
+            businessKey,
+        });
+        if (resolved.businessKey === undefined || resolved.errors.length > 0) {
+            return failure("KEY_POLICY_MISMATCH", "networkの業務キー規則と入力内容が一致しません。");
+        }
+        return {
+            ok: true,
+            value: {
+                definition,
+                businessKey: resolved.businessKey,
+                input: { businessKey: resolved.businessKey },
+            },
+        };
+    }
+    if (businessKey === undefined && scheduledForInput === undefined) {
+        return failure("KEY_POLICY_MISMATCH", "networkの業務キー規則と入力内容が一致しません。");
+    }
+    if (businessKey !== undefined && scheduledForInput === undefined) {
+        return failure("AS_OF_UNDEFINED", "補正用business_keyには対象期間のscheduled_forも指定してください。");
+    }
+    const scheduledFor = normalizeScheduledFor(scheduledForInput);
+    if (scheduledFor === undefined) {
+        return failure("INVALID_TIMESTAMP_FORMAT", "scheduled_forは実在する日時を明示offset付きで指定してください。");
+    }
+    const resolved = resolveBusinessKey({
+        networkId: definition.network_id,
+        policy: definition.business_key_policy,
+        scheduledFor,
+        ...(businessKey === undefined ? {} : { businessKey }),
+    });
+    if (resolved.businessKey === undefined || resolved.errors.length > 0) {
+        return failure("KEY_POLICY_MISMATCH", "networkの業務キー規則と入力内容が一致しません。");
+    }
+    return {
+        ok: true,
+        value: {
+            definition,
+            businessKey: resolved.businessKey,
+            input: {
+                scheduledFor,
+                ...(businessKey === undefined ? {} : { businessKey }),
+            },
+        },
+    };
+}
+export function startNetworkNotAllowed(detail) {
+    return {
+        state: "REJECTED",
+        code: "NETWORK_NOT_ALLOWED",
+        message: `このnetworkはSTARTで起動できません。detail=${detail}`,
+    };
+}
+function failure(code, message) {
+    return { ok: false, result: { state: "REJECTED", code, message } };
+}
+//# sourceMappingURL=start-request.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@rex0220/ksql-flownet",
+  "version": "1.0.0",
+  "description": "Control Plane CLI for kSQL-Flow job networks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rex0220/ksql-flownet.git"
+  },
+  "homepage": "https://github.com/rex0220/ksql-flownet#readme",
+  "bugs": "https://github.com/rex0220/ksql-flownet/issues",
+  "keywords": [
+    "kintone",
+    "ksql",
+    "ksql-flow",
+    "batch",
+    "dag",
+    "orchestration",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "ksql-flownet": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/plugin",
+    "!dist/**/*.map",
+    "schemas"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:plugin": "node plugin/scripts/build.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "pack:plugin": "npm run build:plugin && kintone-plugin-packer --ppk %USERPROFILE%/.ksql-flownet/flownet-activity-plugin.ppk --out plugin/zip/flownet-activity-plugin.zip plugin",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build && npm run build:plugin",
+    "test": "node --test tests/unit/*.test.mjs",
+    "test:plugin": "npm run build:plugin && node --test tests/unit/activity-plugin-*.test.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@kintone/plugin-packer": "^9.1.2",
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "yaml": "^2.9.0"
+  }
+}

package/schemas/.gitkeep

@@ -0,0 +1 @@
+

package/schemas/network-definition.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/rex0220/ksql-flownet/schemas/network-definition.schema.json",
+  "title": "kSQL-FlowNet network definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "network_id",
+    "business_key_policy",
+    "network_lock",
+    "nodes"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "network_id": { "$ref": "#/$defs/identifier" },
+    "description": { "type": "string" },
+    "business_key_policy": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "period", "timezone", "format"],
+          "properties": {
+            "type": { "const": "scheduled_period" },
+            "period": { "enum": ["day", "month"] },
+            "timezone": { "type": "string", "minLength": 1 },
+            "format": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {
+            "type": { "const": "explicit" }
+          }
+        }
+      ]
+    },
+    "max_active_runs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1
+    },
+    "network_lock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lease_duration_sec", "heartbeat_interval_sec"],
+      "properties": {
+        "lease_duration_sec": { "type": "integer", "minimum": 1 },
+        "heartbeat_interval_sec": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "job_id",
+          "sql",
+          "depends_on",
+          "trigger_rule",
+          "idempotent"
+        ],
+        "properties": {
+          "id": { "$ref": "#/$defs/identifier" },
+          "job_id": { "$ref": "#/$defs/identifier" },
+          "sql": { "type": "string", "minLength": 1 },
+          "depends_on": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/identifier" }
+          },
+          "trigger_rule": {
+            "enum": ["all_success", "none_failed", "all_done"]
+          },
+          "idempotent": { "type": "boolean" },
+          "inputs": {
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/sourceIdentifier" },
+            "additionalProperties": { "type": "string", "minLength": 1 }
+          },
+          "outputs": {
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/sourceIdentifier" },
+            "additionalProperties": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "not": {
+        "anyOf": [
+          { "pattern": ":" },
+          { "pattern": "\\u0000" },
+          { "const": "__net__" }
+        ]
+      }
+    },
+    "sourceIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "not": {
+        "anyOf": [
+          { "pattern": "[:=]" },
+          { "pattern": "[\\u0000-\\u001f\\u007f]" },
+          { "const": "__net__" }
+        ]
+      }
+    }
+  }
+}