agentic-dev 0.2.11 → 0.2.12

package/sdd/99_toolchain/01_automation/ui-parity/README.md

@@ -1,60 +0,0 @@
-# UI Parity Tooling
-
-이 디렉터리는 템플릿을 복제한 각 서비스 레포에서 사용하는 repo-local parity 실행 도구의 정본이다.
-
-계층:
-
-- `core/`: parity 결과 생성과 공통 유틸
-- `cli/`: scaffold, proof, route-gap 같은 진입점
-- `contracts/`: output/metadata schema 예시
-- `interfaces/`: 실행 계약과 산출물 규약 문서
-- `runtime/`: 브라우저 런타임 adapter
-
-복제 직후 초기화:
-
-```bash
-bash sdd/99_toolchain/01_automation/agentic-dev/init_frontend_parity.sh . web
-```
-
-이 명령은 다음을 생성한다.
-
-- `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`
-- `.codex/agentic-dev.json`
-- `.claude/agentic-dev.json`
-- `sdd/02_plan/10_test/templates/ui_parity_web_contract.yaml`
-- `sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_route_gap_report.json`
-- `sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_route_gap_report.md`
-
-대상 프론트 선택:
-
-- 기본 대상은 `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`의 `frontend.default_target`에서 결정한다.
-- `web`, `mobile`, `admin`, `landing` 같은 각 프론트는 `frontend.targets.<id>`에 `dir`, `adapter_path`, `screens_path`, `routes_path`, `preview_url`을 선언한다.
-  예시 `dir` 값은 `client/web`처럼 실제 디렉터리 경로를 가리킨다.
-- `init_frontend_parity.sh`, `bootstrap_frontend_parity.sh`, `run_frontend_target.sh`는 모두 이 metadata만 읽고 동작한다.
-
-첫 proof 부트스트랩:
-
-```bash
-bash sdd/99_toolchain/01_automation/agentic-dev/bootstrap_frontend_parity.sh . web
-```
-
-이 명령은 preview 서버를 띄운 뒤 reference materialization, route-gap gate, proof gate까지 수행한다.
-`plan_audit`와 `proof` gate는 각각 route-gap/proof JSON을 schema까지 검증한 뒤 판정한다.
-
-기본 사용 예시:
-
-```bash
-node sdd/99_toolchain/01_automation/ui-parity/cli/scaffold-contract.mjs \
-  --adapter client/web/scripts/ui-parity-web-adapter.mjs \
-  --out sdd/02_plan/10_test/templates/ui_parity_web_contract.yaml
-
-node sdd/99_toolchain/01_automation/ui-parity/cli/run-proof.mjs \
-  --adapter client/web/scripts/ui-parity-web-adapter.mjs \
-  --contract sdd/02_plan/10_test/templates/ui_parity_web_contract.yaml \
-  --out sdd/03_verify/10_test/ui_parity/templates_web_agentic_dev_latest.json
-```
-
-관련 계약:
-
-- [UI Parity Proof Interface](interfaces/ui-parity-proof-interface.md)
-- [UI Parity Route Gap Interface](interfaces/ui-parity-route-gap-interface.md)

package/sdd/99_toolchain/01_automation/ui-parity/cli/extract-reference-pages.mjs

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("extract-reference-pages is a template placeholder. Replace with a service-specific planning asset extractor when references are available.");

package/sdd/99_toolchain/01_automation/ui-parity/cli/materialize-reference-assets.mjs

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { createRequire } from "node:module";
-
-import { loadAdapter } from "../core/load-adapter.mjs";
-import { loadContract } from "../core/load-contract.mjs";
-import { captureScreen, sanitizeFileName } from "../core/capture-runner.mjs";
-import { createPlaywrightRuntime } from "../runtime/playwright-runtime.mjs";
-
-function parseArgs(argv) {
-  const args = {
-    adapter: "",
-    contract: "",
-  };
-  for (let index = 2; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === "--adapter" && argv[index + 1]) {
-      args.adapter = argv[++index];
-    } else if (token === "--contract" && argv[index + 1]) {
-      args.contract = argv[++index];
-    }
-  }
-  if (!args.adapter || !args.contract) {
-    throw new Error("Usage: materialize-reference-assets.mjs --adapter <path> --contract <path>");
-  }
-  return args;
-}
-
-const args = parseArgs(process.argv);
-const { resolvedPath, adapter } = await loadAdapter(args.adapter);
-const requireFromAdapter = createRequire(resolvedPath);
-const yaml = requireFromAdapter("yaml");
-const { contract } = loadContract(args.contract, (text) => yaml.parse(text));
-const runtime = await createPlaywrightRuntime(requireFromAdapter);
-const baseUrl = adapter.targetBaseUrl ?? contract.targetBaseUrl ?? "http://127.0.0.1:4301";
-const viewport = adapter.viewport ?? { width: 1440, height: 1024 };
-const repoRoot = contract.repoRoot ?? process.cwd();
-
-let generated = 0;
-for (const screen of contract.screens) {
-  const targetPath = path.resolve(
-    repoRoot,
-    screen.referenceImage ?? `sdd/03_verify/10_test/ui_parity/reference/${sanitizeFileName(screen.id)}.png`,
-  );
-  await captureScreen({
-    browser: runtime.browser,
-    screen,
-    adapter,
-    outputPath: targetPath,
-    baseUrl,
-    viewport,
-  });
-  generated += 1;
-  console.log(`reference_image=${targetPath}`);
-}
-
-await runtime.dispose();
-console.log(`generated=${generated}`);

package/sdd/99_toolchain/01_automation/ui-parity/cli/normalize-reference-assets.mjs

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("normalize-reference-assets is a template placeholder. Replace with a service-specific reference normalization pipeline.");

package/sdd/99_toolchain/01_automation/ui-parity/cli/route-gap-report.mjs

@@ -1,187 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { ensureDirectory, writeJson } from "../core/paths.mjs";
-
-function loadJson(jsonPath) {
-  return JSON.parse(fs.readFileSync(jsonPath, "utf8"));
-}
-
-function parseArgs(argv) {
-  const args = {
-    service: "",
-    screens: "",
-    routes: "",
-    out: "",
-    markdownOut: "",
-  };
-  for (let index = 2; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === "--service" && argv[index + 1]) {
-      args.service = argv[++index];
-    } else if (token === "--screens" && argv[index + 1]) {
-      args.screens = argv[++index];
-    } else if (token === "--routes" && argv[index + 1]) {
-      args.routes = argv[++index];
-    } else if (token === "--out" && argv[index + 1]) {
-      args.out = argv[++index];
-    } else if (token === "--markdown-out" && argv[index + 1]) {
-      args.markdownOut = argv[++index];
-    }
-  }
-  if (!args.screens || !args.routes || !args.out) {
-    throw new Error(
-      "Usage: route-gap-report.mjs [--service <name>] --screens <json> --routes <json> --out <json> [--markdown-out <md>]",
-    );
-  }
-  return args;
-}
-
-function normalizeStringArray(values) {
-  if (!Array.isArray(values)) return [];
-  return [...new Set(values.map((value) => String(value ?? "").trim()).filter(Boolean))];
-}
-
-function routeStatusFor(entry, routeUsage) {
-  if (!entry) return "missing";
-  const binding = String(entry.binding ?? entry.mode ?? "direct").trim().toLowerCase();
-  if (binding === "stateful") return "stateful";
-  if (binding === "shared") return "shared";
-  if (binding === "missing") return "missing";
-  const route = String(entry.route ?? "").trim();
-  if (!route) return "missing";
-  if ((routeUsage.get(route) ?? 0) > 1) return "shared";
-  return "direct";
-}
-
-function bindingSourceFor(entry) {
-  if (!entry) return "missing";
-  return entry.binding || entry.mode ? "explicit" : "inferred";
-}
-
-function coverageStateFor(status) {
-  if (status === "direct") return "route_bound";
-  if (status === "shared") return "shared_route";
-  if (status === "stateful") return "state_transition";
-  return "unmapped";
-}
-
-function evidenceLevelFor(status, bindingSource, hasNotes, hasTags) {
-  if (status === "missing") return "missing";
-  if (status === "stateful") return "weak";
-  if (status === "shared") return hasNotes || hasTags ? "medium" : "weak";
-  if (bindingSource === "explicit" && (hasNotes || hasTags)) return "strong";
-  if (bindingSource === "explicit") return "medium";
-  return hasNotes || hasTags ? "medium" : "weak";
-}
-
-function renderMarkdown(report) {
-  const lines = [
-    "# UI Parity Route Gap Report",
-    "",
-    `- Service: ${report.service}`,
-    `- Generated At: ${report.generated_at}`,
-    `- Total: ${report.summary.total}`,
-    `- Direct: ${report.summary.direct}`,
-    `- Shared: ${report.summary.shared}`,
-    `- Stateful: ${report.summary.stateful}`,
-    `- Missing: ${report.summary.missing}`,
-    `- Coverage Ratio: ${report.summary.coverage_ratio}`,
-    `- Strong Evidence: ${report.summary.strong_evidence}`,
-    `- With Notes: ${report.summary.with_notes}`,
-    `- With Tags: ${report.summary.with_tags}`,
-    "",
-    "| ID | Title | Route | Status | Evidence | Tags | Linked Screens |",
-    "| --- | --- | --- | --- | --- | --- | --- |",
-  ];
-  for (const screen of report.screens) {
-    lines.push(
-      `| ${screen.id} | ${screen.title} | ${screen.route ?? ""} | ${screen.status} | ${screen.evidence_level} | ${screen.tags.join(", ")} | ${screen.duplicate_route_ids.join(", ")} |`,
-    );
-  }
-  return `${lines.join("\n")}\n`;
-}
-
-const args = parseArgs(process.argv);
-const screens = loadJson(path.resolve(args.screens));
-const routes = loadJson(path.resolve(args.routes));
-const routeUsage = new Map();
-for (const routeEntry of routes) {
-  const route = String(routeEntry.route ?? "").trim();
-  if (!route) continue;
-  routeUsage.set(route, (routeUsage.get(route) ?? 0) + 1);
-}
-
-const routeMap = new Map(routes.map((entry) => [entry.id, entry]));
-const duplicateRouteGroups = [];
-const rows = screens.map((screen) => {
-  const entry = routeMap.get(screen.id) ?? null;
-  const status = routeStatusFor(entry, routeUsage);
-  const route = entry?.route ?? null;
-  const duplicateRouteIds =
-    route && (routeUsage.get(route) ?? 0) > 1
-      ? routes.filter((routeEntry) => routeEntry.route === route && routeEntry.id !== screen.id).map((routeEntry) => routeEntry.id)
-      : [];
-  if (route && duplicateRouteIds.length > 0 && !duplicateRouteGroups.some((group) => group.route === route)) {
-    duplicateRouteGroups.push({
-      route,
-      screen_ids: routes.filter((routeEntry) => routeEntry.route === route).map((routeEntry) => routeEntry.id),
-    });
-  }
-  const tags = normalizeStringArray([...(screen.tags ?? []), ...(entry?.tags ?? [])]);
-  const notes = normalizeStringArray([...(screen.notes ?? []), ...(entry?.notes ?? [])]);
-  const bindingSource = bindingSourceFor(entry);
-  return {
-    id: screen.id,
-    title: screen.title,
-    route,
-    status,
-    binding: String(entry?.binding ?? entry?.mode ?? status),
-    binding_source: bindingSource,
-    coverage_state: coverageStateFor(status),
-    evidence_level: evidenceLevelFor(status, bindingSource, notes.length > 0, tags.length > 0),
-    route_defined: Boolean(route),
-    has_notes: notes.length > 0,
-    has_tags: tags.length > 0,
-    duplicate_route_ids: duplicateRouteIds,
-    tags,
-    notes,
-  };
-});
-
-const report = {
-  generated_at: new Date().toISOString(),
-  service: args.service || path.basename(path.dirname(path.resolve(args.screens))),
-  screens_path: path.resolve(args.screens),
-  routes_path: path.resolve(args.routes),
-  summary: {
-    total: rows.length,
-    direct: rows.filter((row) => row.status === "direct").length,
-    shared: rows.filter((row) => row.status === "shared").length,
-    stateful: rows.filter((row) => row.status === "stateful").length,
-    missing: rows.filter((row) => row.status === "missing").length,
-    coverage_ratio: rows.length > 0 ? Number((rows.filter((row) => row.status === "direct").length / rows.length).toFixed(4)) : 0,
-    explicit_bindings: rows.filter((row) => row.binding_source === "explicit").length,
-    strong_evidence: rows.filter((row) => row.evidence_level === "strong").length,
-    medium_evidence: rows.filter((row) => row.evidence_level === "medium").length,
-    weak_evidence: rows.filter((row) => row.evidence_level === "weak").length,
-    with_notes: rows.filter((row) => row.has_notes).length,
-    with_tags: rows.filter((row) => row.has_tags).length,
-    duplicate_route_groups: duplicateRouteGroups.length,
-  },
-  duplicate_route_groups: duplicateRouteGroups,
-  screens: rows,
-};
-
-ensureDirectory(path.dirname(path.resolve(args.out)));
-writeJson(path.resolve(args.out), report);
-
-if (args.markdownOut) {
-  ensureDirectory(path.dirname(path.resolve(args.markdownOut)));
-  fs.writeFileSync(path.resolve(args.markdownOut), renderMarkdown(report), "utf8");
-}
-
-console.log(`route_gap_output=${path.resolve(args.out)}`);
-if (args.markdownOut) {
-  console.log(`route_gap_markdown=${path.resolve(args.markdownOut)}`);
-}

package/sdd/99_toolchain/01_automation/ui-parity/cli/run-proof.mjs

@@ -1,50 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { createRequire } from "node:module";
-import { loadAdapter } from "../core/load-adapter.mjs";
-import { loadContract } from "../core/load-contract.mjs";
-import { runProof } from "../core/proof-runner.mjs";
-import { createPlaywrightRuntime } from "../runtime/playwright-runtime.mjs";
-
-function parseArgs(argv) {
-  const args = {
-    adapter: "",
-    contract: "",
-    out: "",
-  };
-  for (let index = 2; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === "--adapter" && argv[index + 1]) {
-      args.adapter = argv[++index];
-    } else if (token === "--contract" && argv[index + 1]) {
-      args.contract = argv[++index];
-    } else if (token === "--out" && argv[index + 1]) {
-      args.out = argv[++index];
-    }
-  }
-  if (!args.adapter || !args.contract || !args.out) {
-    throw new Error("Usage: run-proof.mjs --adapter <path> --contract <path> --out <path>");
-  }
-  return args;
-}
-
-const args = parseArgs(process.argv);
-const { resolvedPath, adapter } = await loadAdapter(args.adapter);
-const requireFromAdapter = createRequire(resolvedPath);
-const yaml = requireFromAdapter("yaml");
-const { resolvedPath: resolvedContractPath, contract } = loadContract(args.contract, (text) => yaml.parse(text));
-const runtime = await createPlaywrightRuntime(requireFromAdapter);
-const payload = await runProof({
-  adapterPath: path.relative(process.cwd(), resolvedPath),
-  contractPath: path.relative(process.cwd(), resolvedContractPath),
-  outPath: path.resolve(args.out),
-  adapter,
-  contract,
-  browser: runtime.browser,
-  requireFromAdapter,
-});
-await runtime.dispose();
-console.log(`proof_output=${path.resolve(args.out)}`);
-console.log(`screens=${payload.summary.total}`);
-console.log(`missing_reference=${payload.summary.missing_reference}`);
-console.log(`capture_error=${payload.summary.capture_error}`);

package/sdd/99_toolchain/01_automation/ui-parity/cli/scaffold-contract.mjs

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { loadAdapter } from "../core/load-adapter.mjs";
-import { ensureDirectory } from "../core/paths.mjs";
-
-function parseArgs(argv) {
-  const args = {
-    adapter: "",
-    out: "",
-  };
-  for (let index = 2; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === "--adapter" && argv[index + 1]) {
-      args.adapter = argv[++index];
-    } else if (token === "--out" && argv[index + 1]) {
-      args.out = argv[++index];
-    }
-  }
-  if (!args.adapter || !args.out) {
-    throw new Error("Usage: scaffold-contract.mjs --adapter <path> --out <path>");
-  }
-  return args;
-}
-
-function renderYaml(adapterPath, adapter) {
-  const screens = Array.isArray(adapter.screens) ? adapter.screens : [];
-  const lines = [
-    "kind: ui-parity",
-    "metadata:",
-    `  service: ${adapter.service ?? "replace-service-name"}`,
-    "  generated_by: sdd/99_toolchain/01_automation/ui-parity/cli/scaffold-contract.mjs",
-    "spec:",
-    `  target_base_url: ${adapter.targetBaseUrl ?? "http://127.0.0.1:4301"}`,
-    `  adapter_path: ${adapterPath}`,
-    "screens:",
-  ];
-  if (screens.length === 0) {
-    lines.push("  - id: TMP_001");
-    lines.push("    route: /");
-    lines.push("    reference_image: sdd/03_verify/10_test/ui_parity/reference/TMP_001.png");
-  } else {
-    for (const screen of screens) {
-      lines.push(`  - id: ${screen.id}`);
-      lines.push(`    route: ${screen.route}`);
-      lines.push(
-        `    reference_image: ${screen.referenceImage ?? `sdd/03_verify/10_test/ui_parity/reference/${screen.id}.png`}`,
-      );
-    }
-  }
-  return `${lines.join("\n")}\n`;
-}
-
-const args = parseArgs(process.argv);
-const { resolvedPath, adapter } = await loadAdapter(args.adapter);
-ensureDirectory(path.dirname(path.resolve(args.out)));
-fs.writeFileSync(
-  path.resolve(args.out),
-  renderYaml(path.relative(process.cwd(), resolvedPath), adapter),
-  "utf8",
-);
-console.log(`contract_output=${path.resolve(args.out)}`);

package/sdd/99_toolchain/01_automation/ui-parity/cli/upload-parity1.mjs

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("upload-parity1 is optional. Configure collector URL/API key in the cloned service before enabling uploads.");

package/sdd/99_toolchain/01_automation/ui-parity/contracts/collector-metadata.schema.json

@@ -1,33 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "ParityCollectorMetadata",
-  "type": "object",
-  "required": [
-    "project",
-    "repo",
-    "screen_code",
-    "route",
-    "diff_ratio",
-    "proof_artifacts_root"
-  ],
-  "properties": {
-    "project": {
-      "type": "string"
-    },
-    "repo": {
-      "type": "string"
-    },
-    "screen_code": {
-      "type": "string"
-    },
-    "route": {
-      "type": "string"
-    },
-    "diff_ratio": {
-      "type": "number"
-    },
-    "proof_artifacts_root": {
-      "type": "string"
-    }
-  }
-}

package/sdd/99_toolchain/01_automation/ui-parity/contracts/proof-result.schema.json

@@ -1,76 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "UIParityProofResult",
-  "type": "object",
-  "required": [
-    "generated_at",
-    "service",
-    "adapter_path",
-    "contract_path",
-    "target_base_url",
-    "default_viewport",
-    "screens",
-    "summary"
-  ],
-  "properties": {
-    "generated_at": {
-      "type": "string"
-    },
-    "service": {
-      "type": "string"
-    },
-    "adapter_path": {
-      "type": "string"
-    },
-    "contract_path": {
-      "type": "string"
-    },
-    "target_base_url": {
-      "type": "string"
-    },
-    "default_viewport": {
-      "type": "object",
-      "required": ["width", "height"],
-      "properties": {
-        "width": { "type": "number" },
-        "height": { "type": "number" }
-      }
-    },
-    "screens": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "route", "status", "diff_ratio"],
-        "properties": {
-          "id": { "type": "string" },
-          "title": { "type": ["string", "null"] },
-          "route": { "type": "string" },
-          "tags": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "status": { "type": "string" },
-          "diff_ratio": { "type": "number" },
-          "max_diff_ratio": { "type": "number" },
-          "reference_image": { "type": ["string", "null"] },
-          "actual_image": { "type": ["string", "null"] },
-          "diff_image": { "type": ["string", "null"] },
-          "detail": { "type": "string" },
-          "target_url": { "type": "string" }
-        }
-      }
-    },
-    "summary": {
-      "type": "object",
-      "required": ["total", "passed", "failed", "missing_reference", "capture_error", "matched"],
-      "properties": {
-        "total": { "type": "number" },
-        "passed": { "type": "number" },
-        "failed": { "type": "number" },
-        "missing_reference": { "type": "number" },
-        "capture_error": { "type": "number" },
-        "matched": { "type": "boolean" }
-      }
-    }
-  }
-}

package/sdd/99_toolchain/01_automation/ui-parity/contracts/route-gap-report.schema.json

@@ -1,95 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "UIParityRouteGapReport",
-  "type": "object",
-  "required": [
-    "generated_at",
-    "service",
-    "screens_path",
-    "routes_path",
-    "summary",
-    "screens"
-  ],
-  "properties": {
-    "generated_at": {
-      "type": "string"
-    },
-    "service": {
-      "type": "string"
-    },
-    "screens_path": {
-      "type": "string"
-    },
-    "routes_path": {
-      "type": "string"
-    },
-    "summary": {
-      "type": "object",
-      "required": ["total", "direct", "shared", "stateful", "missing"],
-      "properties": {
-        "total": { "type": "number" },
-        "direct": { "type": "number" },
-        "shared": { "type": "number" },
-        "stateful": { "type": "number" },
-        "missing": { "type": "number" },
-        "coverage_ratio": { "type": "number" },
-        "explicit_bindings": { "type": "number" },
-        "strong_evidence": { "type": "number" },
-        "medium_evidence": { "type": "number" },
-        "weak_evidence": { "type": "number" },
-        "with_notes": { "type": "number" },
-        "with_tags": { "type": "number" },
-        "duplicate_route_groups": { "type": "number" }
-      }
-    },
-    "duplicate_route_groups": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["route", "screen_ids"],
-        "properties": {
-          "route": { "type": "string" },
-          "screen_ids": {
-            "type": "array",
-            "items": { "type": "string" }
-          }
-        }
-      }
-    },
-    "screens": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "title", "status"],
-        "properties": {
-          "id": { "type": "string" },
-          "title": { "type": "string" },
-          "route": { "type": ["string", "null"] },
-          "binding": { "type": "string" },
-          "binding_source": { "type": "string" },
-          "coverage_state": { "type": "string" },
-          "evidence_level": { "type": "string" },
-          "route_defined": { "type": "boolean" },
-          "has_notes": { "type": "boolean" },
-          "has_tags": { "type": "boolean" },
-          "duplicate_route_ids": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "tags": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "status": {
-            "type": "string",
-            "enum": ["direct", "shared", "stateful", "missing"]
-          },
-          "notes": {
-            "type": "array",
-            "items": { "type": "string" }
-          }
-        }
-      }
-    }
-  }
-}