@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/project/deployment-doc.js

@@ -0,0 +1,432 @@
+const STANDARD_TOPO_ORDER = [
+    "permission", "treasury", "allocation", "guard", "machine",
+    "service", "order", "progress", "arb", "reward",
+    "proof", "repository", "demand", "contact",
+    "personal", "payment",
+];
+const D_CHECK_ITEMS = [
+    { id: "D-01", description: "All objects are defined in §1.1" },
+    { id: "D-02", description: "All dependencies have no dangling references" },
+    { id: "D-03", description: "All declared scenarios are covered by steps" },
+    { id: "D-04", description: "All objects follow the naming convention" },
+    { id: "D-05", description: "testnet network field is 'testnet'" },
+    { id: "D-06", description: "testnet replaceExistName is true" },
+    { id: "D-07", description: "All JSON blocks are valid JSON" },
+    { id: "D-08", description: "All step IDs are sequential and unique" },
+    { id: "D-09", description: "All substep IDs are unique" },
+    { id: "D-10", description: "Substep linkage is complete (no dangling/circular)" },
+    { id: "D-11", description: "All `${var}` references resolve to defined outputs" },
+    { id: "D-12", description: "mainnet network field is 'mainnet'" },
+    { id: "D-13", description: "mainnet replaceExistName is false (unless force claim)" },
+    { id: "D-14", description: "Naming convention: ^[a-z][a-z0-9_]{2,63}$" },
+    { id: "D-15", description: "All publish operations come after create" },
+    { id: "D-16", description: "No CRITICAL risks remain (risk_status=RISK_PASSED)" },
+    { id: "D-17", description: "All HIGH risks are user-confirmed" },
+    { id: "D-18", description: "Version numbers are consistent across the document" },
+];
+function isoNow() {
+    return new Date().toISOString();
+}
+function indent(s, n) {
+    const pad = " ".repeat(n);
+    return s
+        .split("\n")
+        .map((l) => pad + l)
+        .join("\n");
+}
+function tableRow(cells) {
+    return "| " + cells.join(" | ") + " |";
+}
+function tableHeader(headers) {
+    return [
+        tableRow(headers),
+        "|" + headers.map(() => "---").join("|") + "|",
+    ].join("\n");
+}
+function jsonBlock(label, data) {
+    const header = label ? `#### ${label}\n\n` : "";
+    let body;
+    try {
+        body = JSON.stringify(data, null, 2);
+    }
+    catch {
+        body = "{}";
+    }
+    return `${header}\`\`\`json\n${body}\n\`\`\`\n`;
+}
+function renderMeta(input) {
+    const lines = ["## 0. Project Metadata", ""];
+    lines.push(tableHeader(["Field", "Value"]));
+    lines.push(tableRow(["Project Name", input.project_prefix]));
+    lines.push(tableRow(["Business Intent", input.business_intent]));
+    lines.push(tableRow(["Industry Mode", input.industry]));
+    lines.push(tableRow(["Version", input.version]));
+    lines.push(tableRow(["Created At", isoNow()]));
+    lines.push(tableRow(["namespace tag", `${input.project_prefix}_${input.version}`]));
+    if (input.scenario_mode) {
+        lines.push(tableRow(["scenario_mode", input.scenario_mode]));
+    }
+    if (input.author) {
+        lines.push(tableRow(["author", input.author]));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderODG(input) {
+    const lines = ["## 1. Object Dependency Graph (ODG)", ""];
+    lines.push("### 1.1 Object List");
+    lines.push("");
+    lines.push(tableHeader([
+        "entry_id", "object_type", "name", "reused_from", "publish_required", "description",
+    ]));
+    for (const o of input.objects) {
+        lines.push(tableRow([
+            o.entry_id,
+            o.object_type,
+            o.name,
+            o.reused_from ?? "",
+            String(o.publish_required),
+            o.description ?? "",
+        ]));
+    }
+    lines.push("");
+    lines.push("### 1.2 Dependencies");
+    lines.push("");
+    lines.push(tableHeader([
+        "from", "to", "edge_kind", "field_path", "required_at_publish",
+    ]));
+    for (const e of input.edges) {
+        lines.push(tableRow([
+            e.from, e.to, e.edge_kind, e.field_path, String(e.required_at_publish),
+        ]));
+    }
+    lines.push("");
+    if (input.scenarios && input.scenarios.length > 0) {
+        lines.push("### 1.3 Scenario Matrix");
+        lines.push("");
+        lines.push(tableHeader([
+            "scenario_id", "description", "primary_object", "supporting_objects", "test_step_refs",
+        ]));
+        for (const s of input.scenarios) {
+            lines.push(tableRow([
+                s.scenario_id,
+                s.description,
+                s.primary_object,
+                s.supporting_objects.join(", "),
+                (s.test_step_refs ?? []).join(", "),
+            ]));
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function renderTopoPlan(input) {
+    const lines = ["## 2. Topological Execution Plan", ""];
+    lines.push(tableHeader([
+        "step", "object_type", "operation", "substep_count", "depends_on", "entry_id", "network_phase",
+    ]));
+    for (const s of input.steps) {
+        lines.push(tableRow([
+            String(s.step),
+            s.object_type,
+            s.operation,
+            String(s.substep_count),
+            `[${s.depends_on.join(", ")}]`,
+            s.entry_id,
+            s.network_phase,
+        ]));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderNetworkSection(sectionNum, network, input) {
+    const title = network === "testnet" ? "testnet Deployment Checklist" : "mainnet Deployment Checklist";
+    const lines = [`## ${sectionNum}. ${title}`, ""];
+    lines.push(`### ${sectionNum}.1 ${network} Metadata`);
+    lines.push("");
+    lines.push(tableHeader(["Field", "Value"]));
+    lines.push(tableRow(["network", network]));
+    lines.push(tableRow([
+        "rpc",
+        network === "testnet"
+            ? "https://rpc.testnet.wowok.io"
+            : "https://rpc.mainnet.wowok.io",
+    ]));
+    lines.push(tableRow([
+        "replaceExistName",
+        network === "testnet" ? "true" : "false",
+    ]));
+    lines.push(tableRow(["gas_budget", "100000000"]));
+    lines.push(tableRow(["account", `${input.project_prefix}_merchant_${network}`]));
+    lines.push(tableRow(["dry_run", "false"]));
+    lines.push("");
+    lines.push(`### ${sectionNum}.2 ${network} JSON Operation Sequence`);
+    lines.push("");
+    for (const step of input.steps) {
+        if (step.network_phase !== "both" && step.network_phase !== network)
+            continue;
+        const block = {
+            step: step.step,
+            operation: "onchain_operations",
+            operation_type: step.object_type,
+            data: {
+                object: { name: objectNameForStep(step, input), replaceExistName: network === "testnet" },
+                description: stepDescription(step),
+            },
+            env: {
+                account: `${input.project_prefix}_merchant_${network}`,
+                network,
+                replaceExistName: network === "testnet",
+                confirmed: true,
+            },
+            substeps: generateSubstepStubs(step),
+        };
+        lines.push(jsonBlock(`Step T${step.step}: ${step.operation} ${step.object_type}`, block));
+    }
+    lines.push(`### ${sectionNum}.3 ${network} Verification Checklist`);
+    lines.push("");
+    const items = network === "testnet"
+        ? ["V-T-01", "V-T-02", "V-T-03", "V-T-04", "V-T-05", "V-T-06", "V-T-07", "V-T-08", "V-T-09", "V-T-10", "V-T-11"]
+        : ["V-M-01", "V-M-02", "V-M-03", "V-M-04", "V-M-05"];
+    lines.push(tableHeader(["Verification ID", "Verification Item", "Status", "Notes"]));
+    for (const v of items) {
+        lines.push(tableRow([v, "(to be filled)", "⚪ Pending", ""]));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function objectNameForStep(step, input) {
+    const obj = input.objects.find((o) => o.entry_id === step.entry_id);
+    return obj?.name ?? `${step.object_type}_${step.step}`;
+}
+function stepDescription(step) {
+    return `${step.operation} ${step.object_type} (step ${step.step})`;
+}
+function generateSubstepStubs(step) {
+    const stubs = [];
+    for (let i = 1; i <= Math.max(1, step.substep_count); i++) {
+        stubs.push({
+            id: `T${step.step}.${i}`,
+            name: `substep ${i}`,
+            inputs: i === 1 ? [] : [`T${step.step}.${i - 1}`],
+            outputs: i === step.substep_count ? [`T${step.step}.output`] : [],
+        });
+    }
+    return stubs;
+}
+function renderVerification(input) {
+    const lines = ["## 5. Verification Checklist", ""];
+    lines.push("### 5.1 testnet Verification Items");
+    lines.push("");
+    lines.push("- V-T-01..V-T-11: see §3.3");
+    lines.push("");
+    lines.push("### 5.2 mainnet Verification Items");
+    lines.push("");
+    lines.push("- V-M-01..V-M-05: see §4.3");
+    lines.push("");
+    return lines.join("\n");
+}
+function renderChecklist(input) {
+    const lines = ["## 6. Completeness Checklist (D-01 ~ D-18)", ""];
+    lines.push(tableHeader(["check_id", "description", "status", "notes"]));
+    const validation = validateDeploymentDoc(input);
+    for (const c of validation.checks) {
+        lines.push(tableRow([c.check_id, c.description, c.status, c.notes ?? ""]));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderScenarios(input) {
+    if (!input.scenarios || input.scenarios.length === 0)
+        return "";
+    const lines = ["## 7. Scenario Matrix", ""];
+    lines.push(tableHeader(["scenario_id", "description", "primary_object", "supporting_objects"]));
+    for (const s of input.scenarios) {
+        lines.push(tableRow([
+            s.scenario_id,
+            s.description,
+            s.primary_object,
+            s.supporting_objects.join(", "),
+        ]));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderAppendices(input) {
+    const lines = [];
+    lines.push("## Appendix A: JSON Block Format Standard");
+    lines.push("");
+    lines.push("- Each JSON block must contain `step`, `operation`, `operation_type`, `data`, `env` fields.");
+    lines.push("- Field naming: MCP schema uses camelCase (e.g. `replaceExistName`, `namedOperator`).");
+    lines.push("- Variable references: use `${T1.permission_address}` syntax to reference outputs across steps.");
+    lines.push("");
+    lines.push("## Appendix B: Naming Convention");
+    lines.push("");
+    lines.push("- Regex: `^[a-z][a-z0-9_]{2,63}$`");
+    lines.push("- Object naming format: `<project>_<type>_v<n>`");
+    lines.push("- Version rule: first `_v1`, rebuild `_v2`, `_v3`...");
+    lines.push("");
+    lines.push("## Appendix C: Status Enumeration");
+    lines.push("");
+    lines.push("- Deployment document lifecycle: draft → calibrated → scanned → testnet_executing → testnet_passed → mainnet_executing → mainnet_passed → completed");
+    lines.push("- Failure states: failed / rolled_back");
+    lines.push("");
+    return lines.join("\n");
+}
+export function generateDeploymentDoc(input) {
+    if (!input || !input.project_prefix) {
+        throw new Error("generateDeploymentDoc: input.project_prefix is required");
+    }
+    if (!input.objects || input.objects.length === 0) {
+        throw new Error("generateDeploymentDoc: input.objects is empty");
+    }
+    const header = [
+        `# ${input.project_prefix} Deployment Document`,
+        "",
+        "> Project-based deployment document, generated by the WoWok MCP tool. Follows the 71-deployment-list-spec specification.",
+        "",
+    ].join("\n");
+    const sections = [
+        header,
+        renderMeta(input),
+        renderODG(input),
+        renderTopoPlan(input),
+        renderNetworkSection(3, "testnet", input),
+        renderNetworkSection(4, "mainnet", input),
+        renderVerification(input),
+        renderChecklist(input),
+        renderScenarios(input),
+        renderAppendices(input),
+    ];
+    return sections.filter((s) => s.length > 0).join("\n");
+}
+export function validateDeploymentDoc(input) {
+    const errors = [];
+    const checks = [];
+    let valid = true;
+    for (const item of D_CHECK_ITEMS) {
+        const r = runDCheck(item, input);
+        checks.push({
+            check_id: item.id,
+            description: item.description,
+            status: r.status,
+            notes: r.notes,
+        });
+        if (r.status === "FAIL") {
+            valid = false;
+            errors.push(`${item.id}: ${r.notes ?? "(no detail)"}`);
+        }
+    }
+    return { valid, checks, errors };
+}
+function runDCheck(item, input) {
+    switch (item.id) {
+        case "D-01": {
+            const empty = !input.objects || input.objects.length === 0;
+            return empty
+                ? { status: "FAIL", notes: "no objects defined" }
+                : { status: "PASS" };
+        }
+        case "D-02": {
+            const ids = new Set(input.objects.map((o) => o.entry_id));
+            const dangling = [];
+            for (const e of input.edges) {
+                if (!ids.has(e.from))
+                    dangling.push(e.from);
+                if (!ids.has(e.to))
+                    dangling.push(e.to);
+            }
+            return dangling.length > 0
+                ? { status: "FAIL", notes: `dangling: ${dangling.join(", ")}` }
+                : { status: "PASS" };
+        }
+        case "D-03": {
+            return { status: "PASS", notes: "scenarios optional" };
+        }
+        case "D-04": {
+            const bad = (input.objects ?? [])
+                .map((o) => o.name)
+                .filter((n) => !/^[a-z][a-z0-9_]{2,63}$/.test(n));
+            return bad.length > 0
+                ? { status: "FAIL", notes: `bad names: ${bad.join(", ")}` }
+                : { status: "PASS" };
+        }
+        case "D-05":
+        case "D-06":
+        case "D-07":
+        case "D-08": {
+            return { status: "PASS" };
+        }
+        case "D-09": {
+            return { status: "PASS", notes: "delegated to substep-trace" };
+        }
+        case "D-10": {
+            return { status: "PASS", notes: "delegated to substep-trace" };
+        }
+        case "D-11": {
+            return { status: "PASS", notes: "variable refs checked at execution" };
+        }
+        case "D-12":
+        case "D-13": {
+            return { status: "PASS" };
+        }
+        case "D-14": {
+            const bad = (input.objects ?? [])
+                .map((o) => o.name)
+                .filter((n) => !/^[a-z][a-z0-9_]{2,63}$/.test(n));
+            return bad.length > 0
+                ? { status: "FAIL", notes: `bad names: ${bad.join(", ")}` }
+                : { status: "PASS" };
+        }
+        case "D-15": {
+            const createByType = new Map();
+            const publishSteps = [];
+            for (const s of input.steps) {
+                if (s.operation === "create")
+                    createByType.set(s.object_type, s.step);
+                if (s.operation === "publish")
+                    publishSteps.push(s);
+            }
+            for (const p of publishSteps) {
+                const created = createByType.get(p.object_type);
+                if (created === undefined || created > p.step) {
+                    return { status: "FAIL", notes: `publish ${p.step} before create for ${p.object_type}` };
+                }
+            }
+            return { status: "PASS" };
+        }
+        case "D-16": {
+            if (input.risk_status === "RISK_BLOCKED") {
+                return { status: "FAIL", notes: "CRITICAL risks remain" };
+            }
+            if ((input.risk_critical_count ?? 0) > 0) {
+                return { status: "FAIL", notes: `${input.risk_critical_count} CRITICAL risks` };
+            }
+            return { status: "PASS" };
+        }
+        case "D-17": {
+            if (input.risk_status === "RISK_PENDING_CONFIRM") {
+                return { status: "WARN", notes: "HIGH risks pending user confirmation" };
+            }
+            return { status: "PASS" };
+        }
+        case "D-18": {
+            const expected = input.version;
+            const mismatches = [];
+            for (const o of input.objects) {
+                const m = o.name.match(/_v(\d+)$/);
+                if (m && `_v${m[1]}` !== expected) {
+                    mismatches.push(o.name);
+                }
+            }
+            return mismatches.length > 0
+                ? { status: "FAIL", notes: `version mismatch: ${mismatches.join(", ")}` }
+                : { status: "PASS" };
+        }
+        default:
+            return { status: "WARN", notes: "unknown check" };
+    }
+}
+export function getStandardTopoOrder() {
+    return [...STANDARD_TOPO_ORDER];
+}

package/dist/project/risk-aggregator.d.ts

@@ -0,0 +1,50 @@
+import type { ProjectObjectType, IndustryMode } from "./namespace.js";
+import type { ObjectPuzzleEntry } from "./business-puzzle.js";
+export type RiskSeverity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export interface RiskAggregationInput {
+    project_prefix: string;
+    version: string;
+    industry?: IndustryMode | string;
+    puzzles: Record<string, ObjectPuzzleEntry>;
+    severity_threshold?: RiskSeverity;
+    user_confirmed_high_risks?: string[];
+}
+export interface AggregatedRisk {
+    risk_rule_id: string;
+    object_type: ProjectObjectType;
+    entry_id: string;
+    severity: RiskSeverity;
+    message: string;
+    fix_suggestion: string;
+    details?: {
+        field_path?: string;
+        actual_value?: unknown;
+        expected_value?: unknown;
+        rule_source?: string;
+    };
+}
+export interface RiskAggregationResult {
+    namespace: {
+        prefix: string;
+        version: string;
+        industry?: IndustryMode;
+    };
+    findings: AggregatedRisk[];
+    severity_summary: Record<RiskSeverity, number>;
+    status: "RISK_PASSED" | "RISK_BLOCKED" | "RISK_PENDING_CONFIRM" | "RISK_CANCELLED";
+    pending_confirmations?: Array<{
+        risk_rule_id: string;
+        description: string;
+        fix_suggestion: string;
+        object_type: ProjectObjectType;
+        entry_id: string;
+    }>;
+    calibrated_at: number;
+    warnings: string[];
+}
+export declare function aggregateProjectRisks(input: RiskAggregationInput): RiskAggregationResult;
+export declare function sortFindings(findings: AggregatedRisk[]): AggregatedRisk[];
+export declare function countBySeverity(findings: AggregatedRisk[]): Record<RiskSeverity, number>;
+export declare function determineStatus(severity_summary: Record<RiskSeverity, number>, threshold: RiskSeverity, user_confirmed_high_risks: string[], findings: AggregatedRisk[]): RiskAggregationResult["status"];
+export declare function getCriticalRisks(result: RiskAggregationResult): AggregatedRisk[];
+export declare function summarizeRiskReport(result: RiskAggregationResult): string;