agentic-dev 0.1.0 → 0.2.1

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

@@ -0,0 +1,60 @@
+# 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 . platform
+```
+
+이 명령은 다음을 생성한다.
+
+- `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_platform_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`에서 결정한다.
+- `platform`, `mobile`, `admin`, `landing` 같은 각 프론트는 `frontend.targets.<id>`에 `dir`, `adapter_path`, `screens_path`, `routes_path`, `preview_url`을 선언한다.
+  예시 `dir` 값은 `client/platform`처럼 실제 디렉터리 경로를 가리킨다.
+- `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 . platform
+```
+
+이 명령은 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/platform/scripts/ui-parity-platform-adapter.mjs \
+  --out sdd/02_plan/10_test/templates/ui_parity_platform_contract.yaml
+
+node sdd/99_toolchain/01_automation/ui-parity/cli/run-proof.mjs \
+  --adapter client/platform/scripts/ui-parity-platform-adapter.mjs \
+  --contract sdd/02_plan/10_test/templates/ui_parity_platform_contract.yaml \
+  --out sdd/04_verify/10_test/ui_parity/templates_platform_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

@@ -0,0 +1,2 @@
+#!/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

@@ -0,0 +1,58 @@
+#!/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/04_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

@@ -0,0 +1,2 @@
+#!/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

@@ -0,0 +1,187 @@
+#!/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

@@ -0,0 +1,50 @@
+#!/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

@@ -0,0 +1,62 @@
+#!/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/04_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/04_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

@@ -0,0 +1,2 @@
+#!/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

@@ -0,0 +1,33 @@
+{
+  "$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

@@ -0,0 +1,76 @@
+{
+  "$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

@@ -0,0 +1,95 @@
+{
+  "$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" }
+          }
+        }
+      }
+    }
+  }
+}