frontend-harness 0.1.0

package/dist/runtime/policy-provenance.js

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { discoverSkills } from "./skills.js";
+import { discoverKnowledgeCards } from "./knowledge.js";
+const canonicalSkillKeywords = {
+    "frontend-discovery": ["discovery", "inspect", "convention", "stack", "profile", "探查", "约定", "技术栈"],
+    "architecture-boundary": ["architecture", "boundary", "placement", "layer", "route", "permission", "menu", "store", "composable", "架构", "边界", "路由", "权限"],
+    "prd-to-knowledge": ["prd", "product", "requirement", "knowledge", "document"],
+    "design-to-project-ui": ["design", "ui", "stitch", "figma", "html", "component", "page"],
+    "ui-implementation": ["design", "ui", "stitch", "figma", "html", "component", "page", "implementation", "dashboard", "table", "dialog", "drawer"],
+    "prd-knowledge": ["prd", "product", "requirement", "knowledge", "document"],
+    "api-integration": ["api", "swagger", "openapi", "interface", "request", "endpoint", "response", "dto", "pagination"],
+    "form-workflow": ["form", "validation", "submit", "upload", "modal", "drawer", "create", "edit", "表单", "校验", "提交"],
+    "frontend-test": ["test", "e2e", "integration", "vitest", "playwright", "msw", "smoke"],
+    "bug-fix": ["bug", "fix", "error", "regression", "failure", "stale", "race"],
+    "frontend-change-review": ["review", "code review", "handoff", "validation evidence", "评审", "复核", "交付"],
+    "git-commit": ["git", "commit", "stage", "staging"],
+    "requirement-change": ["change", "sync", "requirement", "knowledge"],
+    "requirement-change-sync": ["change", "sync", "requirement", "knowledge"]
+};
+const workflowSkillNames = {
+    ui_implementation: "ui-implementation",
+    prd_knowledge: "prd-knowledge",
+    api_integration: "api-integration",
+    frontend_test: "frontend-test",
+    bug_fix: "bug-fix",
+    requirement_change: "requirement-change"
+};
+const stopTokens = new Set([
+    "project",
+    "skill",
+    "skills",
+    "frontend",
+    "harness",
+    "implementation",
+    "implement",
+    "agent",
+    "task",
+    "code"
+]);
+export function buildPolicyProvenance(projectRoot, taskText, workflowKind) {
+    const normalizedTask = normalize(taskText);
+    const skills = discoverSkills(projectRoot);
+    const skillRoutes = routeSkills(skills, normalizedTask, workflowKind);
+    const knowledgeReferences = discoverKnowledgeReferences(projectRoot, normalizedTask, workflowKind);
+    return {
+        selectedSkills: skillRoutes.map((skill) => skill.name),
+        skillPaths: skillRoutes.map((skill) => skill.path),
+        skillRoutes,
+        knowledgeReferences: knowledgeReferences.map((item) => item.path),
+        knowledgeSha256: Object.fromEntries(knowledgeReferences.map((item) => [item.path, item.sha256])),
+        selectionReason: buildSelectionReason(skillRoutes.length, knowledgeReferences.length)
+    };
+}
+function routeSkills(skills, normalizedTask, workflowKind) {
+    return skills
+        .map((skill) => routeSkill(skill, normalizedTask, workflowKind))
+        .filter((candidate) => Boolean(candidate))
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.name.localeCompare(right.name);
+    });
+}
+function routeSkill(skill, normalizedTask, workflowKind) {
+    const metadataMatches = [
+        ...matchPhrases(normalizedTask, skill.triggers ?? [], "trigger"),
+        ...matchPhrases(normalizedTask, skill.intents ?? [], "intent"),
+        ...matchPhrases(normalizedTask, skill.examples ?? [], "example")
+    ];
+    if (metadataMatches.length) {
+        return {
+            name: skill.name,
+            path: skill.path,
+            score: clampScore(0.7 + metadataMatches.length * 0.05),
+            source: "metadata",
+            reasons: metadataMatches
+        };
+    }
+    if (workflowKind && workflowSkillNames[workflowKind] === skill.name) {
+        return {
+            name: skill.name,
+            path: skill.path,
+            score: 0.65,
+            source: "workflow",
+            reasons: [`matched workflow kind: ${workflowKind}`]
+        };
+    }
+    const reasons = [];
+    if (normalizedTask.includes(normalize(skill.name))) {
+        reasons.push(`matched skill name: ${skill.name}`);
+    }
+    const candidate = normalize(`${skill.title} ${skill.description ?? ""}`);
+    const overlap = findTokenOverlap(normalizedTask, candidate);
+    if (overlap.length) {
+        reasons.push(`matched token(s): ${overlap.slice(0, 3).join(", ")}`);
+    }
+    const keywordMatches = matchPhrases(normalizedTask, canonicalSkillKeywords[skill.name] ?? [], "keyword");
+    reasons.push(...keywordMatches);
+    if (!reasons.length) {
+        return null;
+    }
+    return {
+        name: skill.name,
+        path: skill.path,
+        score: clampScore(0.45 + reasons.length * 0.05),
+        source: "keyword",
+        reasons
+    };
+}
+function matchPhrases(normalizedTask, phrases, label) {
+    return phrases
+        .map((phrase) => normalize(phrase))
+        .filter((phrase) => phrase && normalizedTask.includes(phrase))
+        .map((phrase) => `matched ${label}: ${phrase}`);
+}
+function discoverKnowledgeReferences(projectRoot, normalizedTask, workflowKind) {
+    const preferredTypes = workflowKind ? workflowKnowledgeTypes[workflowKind] : [];
+    return discoverKnowledgeCards(projectRoot)
+        .filter((card) => card.status === "active")
+        .map((card) => ({
+        card,
+        score: scoreKnowledgeCard(card, normalizedTask, preferredTypes)
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.card.path.localeCompare(right.card.path);
+    })
+        .slice(0, 8)
+        .map(({ card }) => ({
+        path: card.path,
+        sha256: sha256File(path.join(projectRoot, card.path))
+    }));
+}
+function sha256File(filePath) {
+    return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+const workflowKnowledgeTypes = {
+    ui_implementation: ["prd_semantics", "project_convention", "glossary"],
+    prd_knowledge: ["prd_semantics", "glossary"],
+    api_integration: ["project_convention", "glossary", "decision_record"],
+    frontend_test: ["prd_semantics", "project_convention", "pitfall"],
+    bug_fix: ["decision_record", "pitfall", "prd_semantics"],
+    requirement_change: ["prd_semantics", "decision_record", "project_convention"]
+};
+function scoreKnowledgeCard(card, normalizedTask, preferredTypes) {
+    if (!normalizedTask) {
+        return 0;
+    }
+    let score = 0;
+    if (hasTokenOverlap(normalizedTask, card.searchable)) {
+        score += 4;
+    }
+    if (normalizedTask.includes("knowledge") || normalizedTask.includes("prd") || normalizedTask.includes("知识库") || normalizedTask.includes("需求")) {
+        score += card.type === "prd_semantics" ? 3 : 1;
+    }
+    if (preferredTypes.includes(card.type)) {
+        score += 2;
+    }
+    if (card.stability === "stable") {
+        score += 1;
+    }
+    return score;
+}
+function buildSelectionReason(skillCount, knowledgeCount) {
+    const parts = [
+        `${skillCount} project skill(s) selected by deterministic metadata/keyword providers`,
+        `${knowledgeCount} knowledge artifact(s) selected by deterministic card metadata matching`
+    ];
+    return `${parts.join("; ")}. Provenance is advisory metadata only.`;
+}
+function hasTokenOverlap(left, right) {
+    return findTokenOverlap(left, right).length > 0;
+}
+function findTokenOverlap(left, right) {
+    const rightTokens = new Set(tokens(right));
+    return [...new Set(tokens(left).filter((token) => rightTokens.has(token)))];
+}
+function tokens(value) {
+    return value
+        .split(/\s+/)
+        .filter((token) => token.length >= 4 && !stopTokens.has(token));
+}
+function clampScore(value) {
+    return Math.min(1, Number(value.toFixed(2)));
+}
+function normalize(value) {
+    return value.toLowerCase().replace(/[^\p{L}\p{N}-]+/gu, " ").trim();
+}
+//# sourceMappingURL=policy-provenance.js.map

package/dist/runtime/policy-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-provenance.js","sourceRoot":"","sources":["../../src/runtime/policy-provenance.ts"],"names":[],"mappings":"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"}

package/dist/runtime/project-discovery.d.ts

@@ -0,0 +1,17 @@
+export interface DetectedStack {
+    packageManager: string;
+    framework: string;
+    language: string;
+}
+export interface ProjectSurface {
+    sourceRoots: string[];
+    entryFiles: string[];
+    fileExtensions: string[];
+}
+export declare function detectProjectStack(projectRoot: string): DetectedStack;
+export declare function discoverProjectSurface(projectRoot: string): ProjectSurface;
+export declare function resolveComponentPlacement(projectRoot: string, scope: string): {
+    sourceRoot: string;
+    extension: string;
+};
+export declare function chooseComponentExtension(fileExtensions: string[], stack: DetectedStack): string;

package/dist/runtime/project-discovery.js

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import path from "node:path";
+const SOURCE_ROOT_CANDIDATES = [
+    "src/pages",
+    "src/app",
+    "src/components",
+    "src/views",
+    "src/features",
+    "src",
+    "app",
+    "pages",
+    "components",
+    "views",
+    "features"
+];
+const ENTRY_FILE_CANDIDATES = [
+    "src/main.tsx",
+    "src/main.ts",
+    "src/main.jsx",
+    "src/main.js",
+    "src/index.tsx",
+    "src/index.ts",
+    "src/index.jsx",
+    "src/index.js",
+    "src/App.vue",
+    "src/App.tsx",
+    "src/App.ts",
+    "src/App.jsx",
+    "src/App.js",
+    "app/main.tsx",
+    "app/main.ts",
+    "app/main.jsx",
+    "app/main.js",
+    "app/page.tsx",
+    "app/page.ts",
+    "app/page.jsx",
+    "app/page.js"
+];
+const IGNORED_DIRECTORIES = new Set([
+    ".frontend-harness",
+    ".git",
+    ".omx",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    ".cache",
+    ".turbo"
+]);
+const EXTENSION_PRIORITY = [".vue", ".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs"];
+export function detectProjectStack(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, "package.json");
+    const packageJson = fs.existsSync(packageJsonPath)
+        ? JSON.parse(fs.readFileSync(packageJsonPath, "utf8"))
+        : {};
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    return {
+        packageManager: detectPackageManager(projectRoot, packageJson),
+        framework: deps["vite"]
+            ? "vite"
+            : deps["next"]
+                ? "next"
+                : deps["vue"]
+                    ? "vue"
+                    : deps["react"]
+                        ? "react"
+                        : "unknown",
+        language: deps["typescript"] || fs.existsSync(path.join(projectRoot, "tsconfig.json"))
+            ? "typescript"
+            : "unknown"
+    };
+}
+export function discoverProjectSurface(projectRoot) {
+    const sourceRoots = SOURCE_ROOT_CANDIDATES.filter((candidate) => directoryHasFiles(path.join(projectRoot, candidate)));
+    const entryFiles = ENTRY_FILE_CANDIDATES.filter((candidate) => fs.existsSync(path.join(projectRoot, candidate)));
+    const fileExtensions = EXTENSION_PRIORITY.filter((extension) => sourceRoots.some((root) => hasExtensionInDirectory(path.join(projectRoot, root), extension)));
+    return {
+        sourceRoots,
+        entryFiles,
+        fileExtensions
+    };
+}
+export function resolveComponentPlacement(projectRoot, scope) {
+    const stack = detectProjectStack(projectRoot);
+    const surface = discoverProjectSurface(projectRoot);
+    return {
+        sourceRoot: chooseSourceRoot(surface.sourceRoots, scope),
+        extension: chooseComponentExtension(surface.fileExtensions, stack)
+    };
+}
+export function chooseComponentExtension(fileExtensions, stack) {
+    for (const extension of EXTENSION_PRIORITY) {
+        if (fileExtensions.includes(extension)) {
+            return extension;
+        }
+    }
+    if (stack.framework === "vue") {
+        return ".vue";
+    }
+    if (stack.framework === "react") {
+        return ".tsx";
+    }
+    if (stack.language === "typescript") {
+        return ".tsx";
+    }
+    return ".js";
+}
+function chooseSourceRoot(sourceRoots, scope) {
+    if (sourceRoots.length === 0) {
+        return "src";
+    }
+    const normalized = scope.toLowerCase();
+    const preferComponentRoots = /\b(component|widget|card|modal|dialog|button|form|table|input|select)\b/.test(normalized);
+    const preferPageRoots = /\b(page|screen|dashboard|list|detail|view|route|layout)\b/.test(normalized);
+    const preferredRoots = preferComponentRoots
+        ? sourceRoots.filter((root) => root.includes("components") || root.includes("widgets"))
+        : preferPageRoots
+            ? sourceRoots.filter((root) => root.includes("pages") || root.includes("app") || root.includes("views") || root.includes("features"))
+            : [];
+    return preferredRoots[0] ?? sourceRoots[0] ?? "src";
+}
+function detectPackageManager(projectRoot, packageJson) {
+    const declared = packageJson.packageManager?.split("@", 1)[0];
+    if (declared && ["npm", "pnpm", "yarn", "bun"].includes(declared)) {
+        return declared;
+    }
+    if (fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (fs.existsSync(path.join(projectRoot, "yarn.lock"))) {
+        return "yarn";
+    }
+    if (fs.existsSync(path.join(projectRoot, "bun.lock")) || fs.existsSync(path.join(projectRoot, "bun.lockb"))) {
+        return "bun";
+    }
+    if (fs.existsSync(path.join(projectRoot, "package-lock.json"))) {
+        return "npm";
+    }
+    return "unknown";
+}
+function directoryHasFiles(directory) {
+    return listFiles(directory, 4).length > 0;
+}
+function hasExtensionInDirectory(directory, extension) {
+    return listFiles(directory, 4).some((file) => file.endsWith(extension));
+}
+function listFiles(directory, maxDepth, depth = 0) {
+    if (!fs.existsSync(directory) || depth > maxDepth) {
+        return [];
+    }
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRECTORIES.has(entry.name)) {
+                continue;
+            }
+            files.push(...listFiles(fullPath, maxDepth, depth + 1));
+            continue;
+        }
+        files.push(fullPath);
+    }
+    return files;
+}
+//# sourceMappingURL=project-discovery.js.map

package/dist/runtime/project-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-discovery.js","sourceRoot":"","sources":["../../src/runtime/project-discovery.ts"],"names":[],"mappings":"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"}

package/dist/runtime/project-paths.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeProjectRelativePath(value: string, label: string): string;
+export declare function resolveProjectRelativePath(projectRoot: string, value: string, label: string): {
+    relativePath: string;
+    fullPath: string;
+};
+export declare function isProjectRelativeSubpath(value: string, subtree: string): boolean;

package/dist/runtime/project-paths.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+export function normalizeProjectRelativePath(value, label) {
+    if (value.includes("\0")) {
+        throw new Error(`${label} cannot contain null bytes`);
+    }
+    if (path.isAbsolute(value)) {
+        throw new Error(`${label} must be a project-relative path`);
+    }
+    if (value.includes("\\")) {
+        throw new Error(`${label} must use POSIX-style relative paths`);
+    }
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized.endsWith("/")) {
+        throw new Error(`${label} must be a safe project-relative path`);
+    }
+    const firstSegment = normalized.split("/")[0];
+    if (firstSegment === ".frontend-harness" || firstSegment === ".omx") {
+        throw new Error(`${label} must target project files, not harness or workflow state`);
+    }
+    return normalized;
+}
+export function resolveProjectRelativePath(projectRoot, value, label) {
+    const relativePath = normalizeProjectRelativePath(value, label);
+    const fullPath = path.resolve(projectRoot, relativePath);
+    const rootRelativePath = path.relative(projectRoot, fullPath);
+    if (rootRelativePath.startsWith("..") || path.isAbsolute(rootRelativePath)) {
+        throw new Error(`${label} must stay inside the project root`);
+    }
+    return { relativePath, fullPath };
+}
+export function isProjectRelativeSubpath(value, subtree) {
+    if (value.includes("\0") || value.includes("\\")) {
+        return false;
+    }
+    if (path.isAbsolute(value)) {
+        return false;
+    }
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        return false;
+    }
+    return normalized === subtree || normalized.startsWith(`${subtree}/`);
+}
+//# sourceMappingURL=project-paths.js.map

package/dist/runtime/project-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-paths.js","sourceRoot":"","sources":["../../src/runtime/project-paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,4BAA4B,CAAC,KAAa,EAAE,KAAa;IACvE,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,4BAA4B,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,sCAAsC,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/C,IACE,UAAU,KAAK,GAAG;QAClB,UAAU,KAAK,IAAI;QACnB,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;QAC5B,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EACxB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,uCAAuC,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,YAAY,KAAK,mBAAmB,IAAI,YAAY,KAAK,MAAM,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,2DAA2D,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,WAAmB,EACnB,KAAa,EACb,KAAa;IAEb,MAAM,YAAY,GAAG,4BAA4B,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACzD,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC9D,IAAI,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,oCAAoC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAa,EAAE,OAAe;IACrE,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,UAAU,KAAK,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC;AACxE,CAAC"}

package/dist/runtime/protocol-init.d.ts

@@ -0,0 +1,50 @@
+export interface ProtocolInitResult {
+    contractVersion: 1;
+    createdAt: string;
+    projectRoot: string;
+    dryRun: boolean;
+    needsUpdate: boolean;
+    files: ProtocolFileResult[];
+    skills: ProtocolSkillResult[];
+    artifacts: {
+        protocol: string;
+        skillsRoot: string;
+    };
+}
+export interface ProtocolCheckResult {
+    status: "passed" | "failed" | "not_initialized";
+    artifactPath: string;
+    provenance: {
+        exists: boolean;
+        current: boolean;
+    };
+    files: ProtocolFileCheck[];
+    errors: string[];
+    warnings: string[];
+}
+export interface ProtocolFileResult {
+    path: "AGENTS.md" | "CLAUDE.md";
+    action: "created" | "updated" | "unchanged";
+    sha256: string;
+    managedBlockSha256: string;
+    managedBlockStart: string;
+    managedBlockEnd: string;
+}
+export interface ProtocolFileCheck {
+    path: "AGENTS.md" | "CLAUDE.md";
+    exists: boolean;
+    hasManagedBlock: boolean;
+    managedBlockCurrent: boolean;
+    sha256: string | null;
+    managedBlockSha256: string | null;
+}
+export interface ProtocolSkillResult {
+    name: string;
+    path: string;
+    action: "created" | "unchanged";
+    sha256: string;
+}
+export declare function initializeProtocol(projectRoot: string, options?: {
+    dryRun?: boolean;
+}): ProtocolInitResult;
+export declare function checkProtocol(projectRoot: string): ProtocolCheckResult;