@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/skills/cc-technical-diagrams/scripts/png-qa.mjs

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { segmentHits } from "./diagram-layout.mjs";
+import { pathToFileURL } from "node:url";
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.png || args.help) {
+  printHelp();
+  process.exit(args.help ? 0 : 1);
+}
+
+try {
+  const image = readPng(args.png);
+  const manifest = args.manifest ? readManifest(args.manifest) : undefined;
+  const report = analyze(image, manifest, Boolean(args.strict));
+  if ((args.format ?? "markdown") === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderMarkdown(report));
+  }
+  process.exit(report.ok ? 0 : 2);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+}
+
+function parseArgs(values) {
+  const parsed = { format: "markdown", strict: false, help: false };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--help" || value === "-h") parsed.help = true;
+    else if (value === "--strict") parsed.strict = true;
+    else if (value === "--png") parsed.png = values[++index];
+    else if (value === "--manifest") parsed.manifest = values[++index];
+    else if (value === "--format") parsed.format = values[++index];
+    else throw new Error(`Unknown argument: ${value}`);
+  }
+  if (parsed.format !== "json" && parsed.format !== "markdown") {
+    throw new Error("--format must be json or markdown");
+  }
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Usage: node skills/cc-technical-diagrams/scripts/png-qa.mjs --png <file> [--manifest <layout.json>] [--format json|markdown] [--strict]`);
+}
+
+function readManifest(filePath) {
+  const manifest = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return {
+    ...manifest,
+    canvas: manifest.canvas,
+    boxes: Array.isArray(manifest.boxes) ? manifest.boxes : [],
+    connectors: Array.isArray(manifest.connectors) ? manifest.connectors : [],
+  };
+}
+
+function readPng(filePath) {
+  const buffer = fs.readFileSync(filePath);
+  const signature = "89504e470d0a1a0a";
+  if (buffer.subarray(0, 8).toString("hex") !== signature) {
+    throw new Error(`Not a PNG file: ${filePath}`);
+  }
+
+  let offset = 8;
+  let ihdr;
+  const idat = [];
+  while (offset < buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.subarray(offset + 4, offset + 8).toString("ascii");
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+    if (type === "IHDR") {
+      ihdr = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data[8],
+        colorType: data[9],
+        compression: data[10],
+        filter: data[11],
+        interlace: data[12],
+      };
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+
+  if (!ihdr) throw new Error("PNG is missing IHDR");
+  if (ihdr.bitDepth !== 8) throw new Error(`Unsupported PNG bit depth: ${ihdr.bitDepth}`);
+  if (ihdr.compression !== 0 || ihdr.filter !== 0 || ihdr.interlace !== 0) {
+    throw new Error("Unsupported PNG compression/filter/interlace settings");
+  }
+
+  const channels = channelsForColorType(ihdr.colorType);
+  const inflated = zlib.inflateSync(Buffer.concat(idat));
+  const pixels = unfilter(inflated, ihdr.width, ihdr.height, channels);
+  return {
+    path: path.resolve(filePath),
+    width: ihdr.width,
+    height: ihdr.height,
+    colorType: ihdr.colorType,
+    channels,
+    pixels,
+  };
+}
+
+function channelsForColorType(colorType) {
+  if (colorType === 0) return 1;
+  if (colorType === 2) return 3;
+  if (colorType === 4) return 2;
+  if (colorType === 6) return 4;
+  throw new Error(`Unsupported PNG color type: ${colorType}`);
+}
+
+function unfilter(data, width, height, channels) {
+  const stride = width * channels;
+  const output = Buffer.alloc(stride * height);
+  let sourceOffset = 0;
+
+  for (let y = 0; y < height; y += 1) {
+    const filterType = data[sourceOffset];
+    sourceOffset += 1;
+    const rowOffset = y * stride;
+    const previousRowOffset = (y - 1) * stride;
+
+    for (let x = 0; x < stride; x += 1) {
+      const raw = data[sourceOffset + x];
+      const left = x >= channels ? output[rowOffset + x - channels] : 0;
+      const up = y > 0 ? output[previousRowOffset + x] : 0;
+      const upLeft = y > 0 && x >= channels ? output[previousRowOffset + x - channels] : 0;
+      let value;
+      if (filterType === 0) value = raw;
+      else if (filterType === 1) value = raw + left;
+      else if (filterType === 2) value = raw + up;
+      else if (filterType === 3) value = raw + Math.floor((left + up) / 2);
+      else if (filterType === 4) value = raw + paeth(left, up, upLeft);
+      else throw new Error(`Unsupported PNG filter type: ${filterType}`);
+      output[rowOffset + x] = value & 0xff;
+    }
+    sourceOffset += stride;
+  }
+
+  return output;
+}
+
+function paeth(left, up, upLeft) {
+  const estimate = left + up - upLeft;
+  const leftDistance = Math.abs(estimate - left);
+  const upDistance = Math.abs(estimate - up);
+  const upLeftDistance = Math.abs(estimate - upLeft);
+  if (leftDistance <= upDistance && leftDistance <= upLeftDistance) return left;
+  if (upDistance <= upLeftDistance) return up;
+  return upLeft;
+}
+
+function analyze(image, manifest, strict) {
+  const issues = [];
+  const nextActions = new Set();
+  const ink = measureInk(image, strict ? 10 : 18);
+
+  if (image.width < 64 || image.height < 64) {
+    addIssue(issues, nextActions, "image-too-small", "PNG is too small for reliable visual QA.", "Export a larger PNG before review.");
+  }
+
+  if (ink.coverage < (strict ? 0.001 : 0.0002)) {
+    addIssue(issues, nextActions, "blank-image", "PNG appears blank or nearly blank.", "Check the renderer/export target and regenerate the image.");
+  }
+
+  if (ink.bounds) {
+    const pad = strict ? 6 : 3;
+    if (ink.bounds.minX <= pad || ink.bounds.minY <= pad || image.width - ink.bounds.maxX <= pad || image.height - ink.bounds.maxY <= pad) {
+      addIssue(issues, nextActions, "edge-clipping", "Visible content is very close to the PNG edge.", "Increase canvas/viewBox padding or reduce subject scale.");
+    }
+  }
+
+  if (manifest) analyzeManifest(image, manifest, issues, nextActions, strict);
+
+  return {
+    ok: issues.length === 0,
+    image: {
+      path: image.path,
+      width: image.width,
+      height: image.height,
+      colorType: image.colorType,
+      inkCoverage: Number(ink.coverage.toFixed(6)),
+      inkBounds: ink.bounds,
+    },
+    measurement: manifest?.measurement ?? "image-only",
+    verification: { image: "checked", geometry: manifest ? "checked" : "unavailable", text: manifest?.measurement === "browser" ? "browser-measured" : "estimated-or-unavailable", visual: "pending" },
+    issues,
+    nextActions: [...nextActions],
+  };
+}
+
+function measureInk(image, threshold) {
+  const first = samplePixel(image, 0, 0);
+  let inkPixels = 0;
+  let minX = image.width;
+  let minY = image.height;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      const pixel = samplePixel(image, x, y);
+      const differs = colorDistance(pixel, first) > threshold && pixel.a > 8;
+      if (differs) {
+        inkPixels += 1;
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+
+  return {
+    coverage: inkPixels / (image.width * image.height),
+    bounds: inkPixels > 0 ? { minX, minY, maxX, maxY } : null,
+  };
+}
+
+function samplePixel(image, x, y) {
+  const offset = (y * image.width + x) * image.channels;
+  if (image.channels === 1) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: 255 };
+  }
+  if (image.channels === 2) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: image.pixels[offset + 1] };
+  }
+  return {
+    r: image.pixels[offset],
+    g: image.pixels[offset + 1],
+    b: image.pixels[offset + 2],
+    a: image.channels === 4 ? image.pixels[offset + 3] : 255,
+  };
+}
+
+function colorDistance(left, right) {
+  return Math.abs(left.r - right.r) + Math.abs(left.g - right.g) + Math.abs(left.b - right.b) + Math.abs(left.a - right.a);
+}
+
+export function analyzeManifest(image, manifest, issues, nextActions, strict) {
+  if (manifest.canvas && (manifest.canvas.width !== image.width || manifest.canvas.height !== image.height)) {
+    addIssue(
+      issues,
+      nextActions,
+      "manifest-canvas-mismatch",
+      `Manifest canvas ${manifest.canvas.width}x${manifest.canvas.height} does not match PNG ${image.width}x${image.height}.`,
+      "Regenerate the manifest from the final export dimensions.",
+    );
+  }
+
+  for (const box of manifest.boxes) if (![box.x,box.y,box.width,box.height].every(Number.isFinite) || box.width <= 0 || box.height <= 0) addIssue(issues,nextActions,"invalid-box-geometry",`Invalid geometry for "${box.id}".`,"Correct source dimensions.");
+  const allBoxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  const boxes = allBoxes.filter((box) => box.kind !== "group");
+  for (const issue of manifest.issues ?? []) addIssue(issues, nextActions, issue.code, issue.message, "Fix the source layout and render again.");
+  const labels = manifest.labels ?? [];
+  for (const label of labels) {
+    const owner = allBoxes.find((box) => box.id === label.owner);
+    if (label.kind === "node" && !owner) addIssue(issues,nextActions,"label-owner-missing",`Label "${label.id}" has an unknown node owner.`,"Correct label ownership in the manifest.");
+    if (![label.x,label.y,label.width,label.height].every(Number.isFinite) || label.width < 0 || label.height < 0) addIssue(issues,nextActions,"invalid-label-geometry",`Label "${label.id}" has invalid bounds.`,"Measure source labels again.");
+    if (label.x < 0 || label.y < 0 || label.x + label.width > image.width || label.y + label.height > image.height) addIssue(issues, nextActions, "label-out-of-bounds", `Label "${label.id}" exceeds the canvas.`, "Expand the canvas or adjust the source label position.");
+    if (label.kind === "node" && owner && (label.x < owner.x || label.y < owner.y || label.x + label.width > owner.x + owner.width || label.y + label.height > owner.y + owner.height)) addIssue(issues, nextActions, "node-text-overflow", `Label "${label.id}" exceeds node "${owner.id}".`, "Expand the source node or adjust its text layout.");
+    if (Array.isArray(label.lines) && label.lines.join("").replace(/\r?\n/g, "") !== String(label.text ?? "").replace(/\r?\n/g, "")) addIssue(issues, nextActions, "label-content-loss", `Label "${label.id}" does not preserve source text.`, "Restore the complete source label.");
+    if (label.kind === "edge") for (const box of boxes) if (overlapArea(label, box) > 0) addIssue(issues, nextActions, "edge-label-collision", `Label "${label.id}" overlaps node "${box.id}".`, "Move the edge label to a clear route segment.");
+  }
+  for (let i = 0; i < labels.length; i++) for (let j = i + 1; j < labels.length; j++) if (overlapArea(labels[i], labels[j]) > 0) addIssue(issues, nextActions, "text-overlap", `Labels "${labels[i].id}" and "${labels[j].id}" overlap.`, "Increase label spacing in the source.");
+  for (const box of boxes) {
+    if (box.x < 0 || box.y < 0 || box.x + box.width > image.width || box.y + box.height > image.height) {
+      addIssue(issues, nextActions, "box-out-of-bounds", `Box "${box.id}" is outside the canvas.`, "Move out-of-bounds nodes inside the canvas or expand the canvas.");
+    }
+    if (!labels.length && box.label && estimateLabelOverflow(box, strict)) {
+      addIssue(issues, nextActions, "label-overflow", `Box "${box.id}" label is likely to overflow.`, "Wrap or shorten labels, widen boxes, or increase export scale.");
+    }
+  }
+
+  for (let i = 0; i < boxes.length; i += 1) {
+    for (let j = i + 1; j < boxes.length; j += 1) {
+      const overlap = overlapArea(boxes[i], boxes[j]);
+      if (overlap > 0) {
+        addIssue(issues, nextActions, "box-overlap", `Boxes "${boxes[i].id}" and "${boxes[j].id}" overlap by ${Math.round(overlap)}px^2.`, "Increase node spacing or split dense groups.");
+      }
+    }
+  }
+
+  const boxById = new Map(boxes.map((box) => [box.id, box]));
+  const segments = [];
+  for (const connector of manifest.connectors) {
+    const points = normalizePoints(connector.points);
+    if(points.some(point=>point.x<0||point.y<0||point.x>image.width||point.y>image.height)) addIssue(issues,nextActions,"connector-out-of-bounds",`Connector "${connector.id}" exceeds the canvas.`,"Correct explicit waypoints or expand the source canvas.");
+    if (points.length < 2 || points.every((point) => point.x === points[0].x && point.y === points[0].y)) addIssue(issues, nextActions, "degenerate-connector", `Connector "${connector.id ?? "unnamed"}" has no visible path.`, "Give self calls a loop and other connectors distinct endpoints.");
+    for (let index = 0; index < points.length - 1; index += 1) {
+      const segment = { connector, a: points[index], b: points[index + 1] };
+      segments.push(segment);
+      for (const label of labels) if (segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],label)) addIssue(issues,nextActions,"connector-through-text",`Connector "${connector.id}" crosses label "${label.id}".`,"Move the source label or route around its text.");
+      for (const box of boxes) {
+        if (box.id === connector.from || box.id === connector.to) continue;
+        if (segmentIntersectsBox(segment, box)) {
+          addIssue(issues, nextActions, "connector-through-label", `Connector "${connector.id ?? "unnamed"}" crosses box "${box.id}".`, "Add waypoints around labels or use orthogonal routing.");
+        }
+      }
+    }
+    if ((connector.from && !boxById.has(connector.from)) || (connector.to && !boxById.has(connector.to))) {
+      addIssue(issues, nextActions, "connector-endpoint-missing", `Connector "${connector.id ?? "unnamed"}" references a missing endpoint.`, "Update connector endpoints to match manifest box ids.");
+    }
+  }
+
+  for (let i = 0; i < segments.length; i += 1) {
+    for (let j = i + 1; j < segments.length; j += 1) {
+      if (segments[i].connector === segments[j].connector) continue;
+      if (segmentsStack(segments[i], segments[j], strict ? 4 : 2)) {
+        addIssue(issues, nextActions, "connector-stacking", "Two connector segments are stacked or nearly stacked.", "Offset parallel connectors or bundle them into a labeled shared route.");
+      }
+    }
+  }
+}
+
+function normalizeBox(box) {
+  if (!box || typeof box.id !== "string") return null;
+  const normalized = {
+    id: box.id,
+    kind: box.kind,
+    x: Number(box.x),
+    y: Number(box.y),
+    width: Number(box.width),
+    height: Number(box.height),
+    label: typeof box.label === "string" ? box.label : "",
+  };
+  if ([normalized.x, normalized.y, normalized.width, normalized.height].some((value) => !Number.isFinite(value))) return null;
+  return normalized;
+}
+
+function normalizePoints(points) {
+  if (!Array.isArray(points)) return [];
+  return points
+    .map((point) => {
+      if (Array.isArray(point)) return { x: Number(point[0]), y: Number(point[1]) };
+      return { x: Number(point?.x), y: Number(point?.y) };
+    })
+    .filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y));
+}
+
+function estimateLabelOverflow(box, strict) {
+  const label = box.label.trim();
+  if (!label) return false;
+  const lines = label.split(/\r?\n/);
+  const maxLine = Math.max(...lines.map((line) => visualLength(line)));
+  const estimatedWidth = maxLine * (strict ? 7.5 : 7);
+  const estimatedHeight = lines.length * (strict ? 18 : 16);
+  return estimatedWidth > Math.max(0, box.width - 12) || estimatedHeight > Math.max(0, box.height - 8);
+}
+
+function visualLength(value) {
+  return [...value].reduce((total, char) => total + (/[\u4e00-\u9fff]/.test(char) ? 2 : 1), 0);
+}
+
+function overlapArea(left, right) {
+  const width = Math.max(0, Math.min(left.x + left.width, right.x + right.width) - Math.max(left.x, right.x));
+  const height = Math.max(0, Math.min(left.y + left.height, right.y + right.height) - Math.max(left.y, right.y));
+  return width * height;
+}
+
+function segmentIntersectsBox(segment, box) {
+  return segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],box);
+}
+
+function legacySegmentIntersectsBox(segment, box) {
+  if (pointInsideBox(segment.a, box) || pointInsideBox(segment.b, box)) return true;
+  const edges = [
+    [{ x: box.x, y: box.y }, { x: box.x + box.width, y: box.y }],
+    [{ x: box.x + box.width, y: box.y }, { x: box.x + box.width, y: box.y + box.height }],
+    [{ x: box.x + box.width, y: box.y + box.height }, { x: box.x, y: box.y + box.height }],
+    [{ x: box.x, y: box.y + box.height }, { x: box.x, y: box.y }],
+  ];
+  return edges.some(([a, b]) => segmentsIntersect(segment.a, segment.b, a, b));
+}
+
+function pointInsideBox(point, box) {
+  return point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height;
+}
+
+function segmentsIntersect(a, b, c, d) {
+  const o1 = orientation(a, b, c);
+  const o2 = orientation(a, b, d);
+  const o3 = orientation(c, d, a);
+  const o4 = orientation(c, d, b);
+  if (o1 !== o2 && o3 !== o4) return true;
+  return false;
+}
+
+function orientation(a, b, c) {
+  const value = (b.y - a.y) * (c.x - b.x) - (b.x - a.x) * (c.y - b.y);
+  if (Math.abs(value) < 0.0001) return 0;
+  return value > 0 ? 1 : 2;
+}
+
+function segmentsStack(left, right, tolerance) {
+  const leftHorizontal = Math.abs(left.a.y - left.b.y) <= tolerance;
+  const rightHorizontal = Math.abs(right.a.y - right.b.y) <= tolerance;
+  const leftVertical = Math.abs(left.a.x - left.b.x) <= tolerance;
+  const rightVertical = Math.abs(right.a.x - right.b.x) <= tolerance;
+
+  if (leftHorizontal && rightHorizontal && Math.abs(left.a.y - right.a.y) <= tolerance) {
+    return rangesOverlap([left.a.x, left.b.x], [right.a.x, right.b.x]) > tolerance;
+  }
+  if (leftVertical && rightVertical && Math.abs(left.a.x - right.a.x) <= tolerance) {
+    return rangesOverlap([left.a.y, left.b.y], [right.a.y, right.b.y]) > tolerance;
+  }
+  return false;
+}
+
+function rangesOverlap(left, right) {
+  const a = [Math.min(...left), Math.max(...left)];
+  const b = [Math.min(...right), Math.max(...right)];
+  return Math.max(0, Math.min(a[1], b[1]) - Math.max(a[0], b[0]));
+}
+
+function addIssue(issues, nextActions, code, message, action) {
+  issues.push({ code, message, action });
+  if (typeof nextActions.add === "function") nextActions.add(action);
+  else if (!nextActions.includes(action)) nextActions.push(action);
+}
+
+function renderMarkdown(report) {
+  const lines = [
+    "# PNG QA Report",
+    "",
+    `- Status: ${report.ok ? "ok" : "issues-found"}`,
+    `- Image: ${report.image.width}x${report.image.height}`,
+    `- Ink coverage: ${report.image.inkCoverage}`,
+  ];
+  if (report.image.inkBounds) {
+    lines.push(`- Ink bounds: ${JSON.stringify(report.image.inkBounds)}`);
+  }
+  lines.push("", "## Issues");
+  if (report.issues.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const issue of report.issues) {
+      lines.push(`- ${issue.code}: ${issue.message}`);
+    }
+  }
+  lines.push("", "## Next Actions");
+  if (report.nextActions.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const action of report.nextActions) lines.push(`- ${action}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/skills/{fec-typescript-project-standard → cc-typescript-project-standard}/SKILL.md

@@ -1,10 +1,12 @@
 ---
-name: fec-typescript-project-standard
-description: Use when creating, configuring, reviewing, or debugging TypeScript project standards across frontend apps, libraries, SDKs, CLIs, monorepo packages, tsconfig, strictness, module/moduleResolution, path aliases, project references, declaration files, package exports, public API types, DTOs, advanced generics, discriminated unions, type guards, type narrowing, or type-level regressions. Prefer framework project skills for React/Vue/Next/Nuxt component architecture; Chinese triggers include TypeScript project specification, TS project specification, TypeScript type safety, type modeling, generics, discriminative unions, type narrowing, tsconfig, declaration files.
+name: cc-typescript-project-standard
+description: Use when TypeScript configuration, module resolution, public API types, declarations, package exports, narrowing or generic contracts need design or review in applications, SDKs, CLI tools, desktop processes or libraries.
 ---
 
 # TypeScript project specifications
 
+Apply to libraries, CLI tools, desktop cores and services. Determine the application role from the actual project; a frontend/backend product name does not constrain the language.
+
 ## Purpose
 
 Unify project configuration, type boundaries, and release product rules for the TypeScript layer. Works with front-end applications, component libraries, SDKs, CLIs, monorepo packages, and pure TypeScript tool libraries, but does not take over the framework architecture responsibilities of React, Vue, Next.js, Nuxt, or Vite.
@@ -19,7 +21,7 @@ Unify project configuration, type boundaries, and release product rules for the
    - The component architecture, routing organization, and state management of frameworks such as React, Vue, Next.js, and Nuxt belong to the corresponding framework skills; this process only deals with cross-framework TypeScript contracts and project boundaries.
 
 2. Convergence `tsconfig`
-   - Turn on `strict` by default, do not turn off key constraints such as `noImplicitAny`, `strictNullChecks` or `exactOptionalPropertyTypes` for pass builds.
+   - Prefer `strict` for new code and preserve existing checks; do not disable `noImplicitAny` or `strictNullChecks` merely to hide a defect. `exactOptionalPropertyTypes` is a separate option; introduce stricter settings through a scoped, compatible migration when justified.
    - Select `target`, `lib`, `module` and `moduleResolution` according to the running environment; browser applications, Node scripts, and library packages should not share an ambiguous configuration.
    - Separate basic configuration, application configuration, test configuration and build declaration configuration to avoid testing global types from polluting production code.
    - Path aliases must be understood by TypeScript, bundler, test runner, and published products at the same time; library packages must not publish source code aliases that cannot be resolved.
@@ -43,7 +45,7 @@ Unify project configuration, type boundaries, and release product rules for the
 
 ## Constraints
 
-- Don't use `skipLibCheck`, `any`, unguarded non-null assertions or the wide `as` to mask real boundary issues.
+- Do not use `any`, unguarded non-null assertions or broad `as` to conceal an unverified boundary. A justified `skipLibCheck` dependency policy is separate from checking your own public API; record its limits.
 - Do not rely on release package private deep paths in application code.
 - Do not put framework directory structure, component layering, routing organization or state management decisions into this process; these are left to the corresponding framework or dedicated process.
 - Don't pollute browser running code with generated, test, or Node-only types.
@@ -52,3 +54,7 @@ Unify project configuration, type boundaries, and release product rules for the
 ## Expected Output
 
 The output should include TypeScript context determinations, key `tsconfig`/package type entry suggestions, type boundary schemes, declaration file or public API risks, and verification commands. After completion, the project should be able to independently typecheck, public types can be parsed by consumers, and type safety issues should have clear narrowing or modeling solutions.
+
+## Engineering practices
+
+Read the [local engineering decisions](references/engineering-practices.md) for this task and follow their links to relevant shared principles. Apply levels and exceptions against actual project contracts; product frontend/backend labels do not constrain language or role.

package/skills/cc-typescript-project-standard/examples/engineering/README.md

@@ -0,0 +1,9 @@
+# External input boundary — EP-TS-01
+
+Use a separate writable copy of this directory. This example targets Node >=22.18 for native type stripping, with explicitly declared TypeScript and Node types; it does not change the parent project's supported versions.
+
+Prepare once: `pnpm install --ignore-scripts --frozen-lockfile`. Then `pnpm typecheck` and `pnpm test`. In PowerShell set `$env:CRAFT_ENGINEERING_DEFECTIVE='1'` and run the same test: the named invalid-input assertion must fail after successful preparation/type checking. Set it to `'0'` (or remove it) and rerun: both tests pass. POSIX: prefix the test command with `CRAFT_ENGINEERING_DEFECTIVE=1` or `=0`.
+
+The callback records real effects before/after validation; the defective branch deliberately replaces validation with a cast. Default behavior is protected. This does not test a payment backend, browser, async state or declaration publishing; those require their own consumer checks. No test imports parent-repository source. Install/build output belongs only to the writable copy.
+
+[Node.js type-stripping history and limitations](https://nodejs.org/api/typescript.html): runtime stripping is separate from the explicit TypeScript type check.

package/skills/cc-typescript-project-standard/examples/engineering/boundary.test.ts

@@ -0,0 +1,16 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { acceptAmount } from "./input.ts";
+
+test("EP-TS-01 rejects invalid input before any effect", () => {
+  const effects: number[] = [];
+  for (const input of [{ amount: "10" }, { amount: -1 }, { amount: Number.MAX_SAFE_INTEGER + 1 }, null]) {
+    assert.throws(() => acceptAmount(input, amount => effects.push(amount)), /invalid amount/);
+    assert.deepEqual(effects, []);
+  }
+});
+test("EP-TS-01 accepts a valid input exactly once", () => {
+  const effects: number[] = [];
+  acceptAmount({ amount: 10 }, amount => effects.push(amount));
+  assert.deepEqual(effects, [10]);
+});

package/skills/cc-typescript-project-standard/examples/engineering/input.ts

@@ -0,0 +1,12 @@
+/** Test switch only; normal use always validates the external boundary. */
+export function acceptAmount(value: unknown, effect: (amount: number) => void): void {
+  if (process.env.CRAFT_ENGINEERING_DEFECTIVE === "1") {
+    effect((value as { amount: number }).amount);
+    return;
+  }
+  if (typeof value !== "object" || value === null || !("amount" in value)
+      || typeof value.amount !== "number" || !Number.isSafeInteger(value.amount) || value.amount <= 0) {
+    throw new TypeError("invalid amount");
+  }
+  effect(value.amount);
+}

package/skills/cc-typescript-project-standard/examples/engineering/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "engineering-typescript-boundary-example",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": { "node": ">=22.18.0" },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test --test-reporter=tap boundary.test.ts"
+  },
+  "devDependencies": { "typescript": "5.9.3", "@types/node": "22.20.5" }
+}

package/skills/cc-typescript-project-standard/examples/engineering/pnpm-lock.yaml

@@ -0,0 +1,39 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      '@types/node':
+        specifier: 22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+
+packages:
+
+  '@types/node@22.20.5':
+    resolution: {integrity: sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==}
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+snapshots:
+
+  '@types/node@22.20.5':
+    dependencies:
+      undici-types: 6.21.0
+
+  typescript@5.9.3: {}
+
+  undici-types@6.21.0: {}

package/skills/cc-typescript-project-standard/examples/engineering/pnpm-workspace.yaml

@@ -0,0 +1 @@
+packages: []

package/skills/cc-typescript-project-standard/examples/engineering/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "strict": true, "noEmit": true, "allowImportingTsExtensions": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts"]
+}