frontend-harness 0.1.0

package/dist/schemas/types.d.ts

@@ -0,0 +1,244 @@
+export type HarnessStatus = "idle" | "planned" | "awaiting_agent_edit" | "verifying" | "passed" | "failed" | "blocked";
+export type VerificationStatus = "not_run" | "not_configured" | "passed" | "failed" | "error";
+export interface TaskUnderstanding {
+    intent: string;
+    scope: string;
+    constraints: string[];
+    frontendWorkflow?: FrontendWorkflowPolicy;
+    inputs?: {
+        prd?: string;
+        ui?: string;
+        agentDecision?: string;
+    };
+    reasoningMode?: "deterministic" | "agent_assisted";
+    policyProvenance?: PolicyProvenance;
+    agentDecision?: {
+        summary?: string | null;
+        artifactPath?: string | null;
+        contractVersion?: 1 | null;
+        intentSuggestion?: string | null;
+        constraintHints?: string[];
+        componentHints?: AgentDecisionComponentHint[];
+    };
+}
+export type FrontendWorkflowKind = "ui_implementation" | "prd_knowledge" | "api_integration" | "frontend_test" | "bug_fix" | "requirement_change";
+export interface FrontendWorkflowPolicy {
+    kind: FrontendWorkflowKind;
+    summary: string;
+    requiredKnowledgeActions: string[];
+    implementationConstraints: string[];
+    verificationFocus: string[];
+}
+export interface PolicyProvenance {
+    selectedSkills: string[];
+    skillPaths: string[];
+    skillRoutes: SkillRouteCandidate[];
+    knowledgeReferences: string[];
+    knowledgeSha256: Record<string, string>;
+    selectionReason: string;
+}
+export interface SkillRouteCandidate {
+    name: string;
+    path: string;
+    score: number;
+    source: "metadata" | "workflow" | "keyword";
+    reasons: string[];
+}
+export interface AgentDecisionComponentHint {
+    name?: string;
+    responsibility?: string;
+}
+export interface AgentPlanningDecision {
+    contractVersion?: 1;
+    intentSuggestion?: string;
+    constraintHints?: string[];
+    componentHints?: AgentDecisionComponentHint[];
+}
+export interface AgentPlanningDecisionEnvelope {
+    contractVersion: 1;
+    decision: AgentPlanningDecision;
+}
+export interface AgentDecisionCheckResult {
+    status: "passed" | "failed";
+    artifactPath: string;
+    contractVersion: 1 | null;
+    decision: AgentPlanningDecision | null;
+    errors: string[];
+}
+export interface PlanningDecisionSummary {
+    artifactPath: string | null;
+    contractVersion: 1 | null;
+    intentSuggestion: string | null;
+    constraintHints: string[];
+    componentHints: AgentDecisionComponentHint[];
+}
+export interface ComponentItem {
+    name: string;
+    file: string;
+    responsibility: string;
+    status: "new" | "existing" | "unknown";
+}
+export interface ExecutionUnit {
+    id: string;
+    file: string;
+    task: string;
+    verification: string[];
+    dependsOn: string[];
+    parallelGroup: string | null;
+}
+export type ExecutionGuidanceAction = "inspect_plan" | "edit_files" | "record_changes" | "verify" | "fix_failed_verification";
+export interface ExecutionGuidanceStep {
+    order: number;
+    action: ExecutionGuidanceAction;
+    description: string;
+    command: string | null;
+    condition: string | null;
+}
+export type StateNextAction = "plan" | "edit" | "verify" | "fix" | "configure_verification" | "done" | "blocked";
+export interface StateNextResult {
+    action: StateNextAction;
+    reason: string;
+    command: string | null;
+    stateStatus: HarnessStatus;
+    verificationStatus: VerificationStatus;
+    changedFiles: string[];
+    guidance: string[];
+    artifacts: string[];
+    checks: string[];
+    stopCondition: string;
+}
+export interface StateExplainResult {
+    contractVersion: 1;
+    createdAt: string;
+    nextAction: StateNextResult;
+    summary: string;
+    rationale: string[];
+    requiredArtifacts: string[];
+    repairPacket: {
+        path: string;
+        markdownPath: string;
+        available: boolean;
+    };
+    repairDecision: {
+        path: string;
+        available: boolean;
+        sourceArtifactPath: string | null;
+        repairPacketArtifactPath: string | null;
+        repairPacketSha256: string | null;
+        verificationArtifactPath: string | null;
+        verificationSha256: string | null;
+    };
+    recommendedCommands: string[];
+    stopCondition: string;
+}
+export interface ComponentGraphNode {
+    id: string;
+    component: string;
+    file: string;
+    executionUnitId: string;
+}
+export interface ComponentGraphEdge {
+    from: string;
+    to: string;
+    type: "depends_on";
+    source: "execution_unit_depends_on";
+}
+export interface ComponentGraphArtifact {
+    nodes: ComponentGraphNode[];
+    edges: ComponentGraphEdge[];
+}
+export interface HarnessState {
+    version: 1;
+    status: HarnessStatus;
+    task: TaskUnderstanding | null;
+    components: ComponentItem[];
+    units: ExecutionUnit[];
+    changedFiles: string[];
+    verification: {
+        status: VerificationStatus;
+        latestResultPath: string | null;
+    };
+    errors: string[];
+    retryCount: number;
+    blockers: string[];
+    updatedAt: string;
+}
+export interface VerificationCommandResult {
+    name: string;
+    command: string | null;
+    source: "flag" | "config" | "package" | "none";
+    status: VerificationStatus;
+    exitCode: number | null;
+    durationMs: number;
+    logPath: string | null;
+}
+export interface VerificationResult {
+    status: VerificationStatus;
+    results: VerificationCommandResult[];
+    retryGuidance: null | {
+        summary: string;
+        failedCommands: string[];
+        logs: string[];
+        nextAgentInstruction: string;
+    };
+}
+export interface RepairPacketArtifact {
+    contractVersion: 1;
+    createdAt: string;
+    status: "ready" | "not_applicable";
+    stateStatus: HarnessStatus;
+    verificationStatus: VerificationStatus;
+    nextAction: StateNextResult;
+    artifacts: {
+        verification: string;
+        repairPacket: string;
+        repairPacketMarkdown: string;
+    };
+    changedFiles: string[];
+    failedCommands: Array<{
+        name: string;
+        command: string | null;
+        status: VerificationStatus;
+        exitCode: number | null;
+        logPath: string | null;
+        logExcerpt: string | null;
+        logSha256: string | null;
+        logSizeBytes: number | null;
+        excerptStartByte: number | null;
+        excerptEndByte: number | null;
+        excerptTruncated: boolean;
+    }>;
+    retryGuidance: VerificationResult["retryGuidance"];
+    instructions: string[];
+}
+export interface RepairDecision {
+    intent: string;
+    hypothesis: string;
+    targetFiles: string[];
+    verificationFocus: string[];
+}
+export interface RepairDecisionEnvelope {
+    contractVersion: 1;
+    decision: RepairDecision;
+}
+export interface RepairDecisionCheckResult {
+    status: "passed" | "failed";
+    artifactPath: string;
+    acceptedArtifactPath: string | null;
+    contractVersion: 1 | null;
+    decision: RepairDecision | null;
+    errors: string[];
+}
+export interface RepairDecisionSummary {
+    artifactPath: string;
+    sourceArtifactPath: string;
+    repairPacketArtifactPath: string | null;
+    repairPacketSha256: string | null;
+    verificationArtifactPath: string | null;
+    verificationSha256: string | null;
+    contractVersion: 1;
+    intent: string;
+    hypothesis: string;
+    targetFiles: string[];
+    verificationFocus: string[];
+}

package/dist/schemas/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/schemas/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schemas/types.ts"],"names":[],"mappings":""}

package/dist/schemas/validation.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessState } from "./types.js";
+export declare function isHarnessState(value: unknown): value is HarnessState;

package/dist/schemas/validation.js

@@ -0,0 +1,21 @@
+export function isHarnessState(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const verification = value["verification"];
+    return value["version"] === 1
+        && typeof value["status"] === "string"
+        && Array.isArray(value["components"])
+        && Array.isArray(value["units"])
+        && Array.isArray(value["changedFiles"])
+        && isRecord(verification)
+        && typeof verification["status"] === "string"
+        && Array.isArray(value["errors"])
+        && typeof value["retryCount"] === "number"
+        && Array.isArray(value["blockers"])
+        && typeof value["updatedAt"] === "string";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=validation.js.map

package/dist/schemas/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/schemas/validation.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,YAAY,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC;IAC3C,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC;WACxB,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,QAAQ;WACnC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;WAClC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;WAC7B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;WACpC,QAAQ,CAAC,YAAY,CAAC;WACtB,OAAO,YAAY,CAAC,QAAQ,CAAC,KAAK,QAAQ;WAC1C,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;WAC9B,OAAO,KAAK,CAAC,YAAY,CAAC,KAAK,QAAQ;WACvC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;WAChC,OAAO,KAAK,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC;AAC9C,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}

package/dist/storage/json.d.ts

@@ -0,0 +1,5 @@
+export declare function ensureDir(dir: string): void;
+export declare function writeJson(filePath: string, value: unknown): void;
+export declare function writeJsonExclusive(filePath: string, value: unknown): void;
+export declare function readJson<T>(filePath: string): T | null;
+export declare function writeText(filePath: string, value: string): void;

package/dist/storage/json.js

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import path from "node:path";
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function writeJson(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export function writeJsonExclusive(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+}
+export function readJson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function writeText(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, value, "utf8");
+}
+//# sourceMappingURL=json.js.map

package/dist/storage/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/storage/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAc;IACxD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,KAAc;IACjE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACtG,CAAC;AAED,MAAM,UAAU,QAAQ,CAAI,QAAgB;IAC1C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAM,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAa;IACvD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC"}

package/dist/storage/paths.d.ts

@@ -0,0 +1,3 @@
+export declare const HARNESS_DIR = ".frontend-harness";
+export declare function harnessPath(projectRoot: string, ...parts: string[]): string;
+export declare function relativeHarnessPath(...parts: string[]): string;

package/dist/storage/paths.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+export const HARNESS_DIR = ".frontend-harness";
+export function harnessPath(projectRoot, ...parts) {
+    return path.join(projectRoot, HARNESS_DIR, ...parts);
+}
+export function relativeHarnessPath(...parts) {
+    return path.posix.join(HARNESS_DIR, ...parts);
+}
+//# sourceMappingURL=paths.js.map

package/dist/storage/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/storage/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAE/C,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,GAAG,KAAe;IACjE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAG,KAAe;IACpD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/docs/DIRECTION.md

@@ -0,0 +1,67 @@
+# frontend-harness Direction
+
+`frontend-harness` is a project-level Execution Policy Layer for frontend AI-assisted development.
+
+The package should make Codex and Claude Code more predictable inside a frontend repository without replacing their runtime capabilities.
+
+## Product Surface
+
+The primary product surface is protocol injection:
+
+```text
+npm install frontend-harness --save-dev
+npx frontend-harness init
+```
+
+After that, team members work normally in Codex or Claude Code. The injected `AGENTS.md` and `CLAUDE.md` protocol tells the agent to use the harness loop.
+
+## Policy Loop
+
+The stable loop is:
+
+```text
+context -> plan -> implement -> record-change -> verify -> repair -> done
+```
+
+The CLI should keep these steps deterministic and evidence-backed.
+
+`plan --json` should classify the frontend workflow before implementation. The first stable workflow policy classes are:
+
+- `ui_implementation`: hand-written UI or generated UI adaptation from MCP/Stitch/Figma/HTML.
+- `prd_knowledge`: PRD digestion into durable project knowledge.
+- `api_integration`: Swagger/API-backed frontend data integration.
+- `frontend_test`: E2E or integration testing.
+- `bug_fix`: scoped bug repair with regression evidence.
+- `requirement_change`: implementation plus knowledge/test synchronization for changed requirements.
+
+These classes are policy metadata, not skill routing and not runtime scheduling.
+
+## Boundaries
+
+`frontend-harness` owns:
+
+- project context isolation
+- frontend workflow protocol
+- verification standards
+- state continuity
+- repair evidence
+- project-local knowledge and skills
+
+Codex and Claude Code own:
+
+- agent loop
+- tool execution
+- permissions
+- retries
+- subagents
+- skill loading
+- runtime orchestration
+
+## Directional Decisions
+
+- Human-facing commands stay minimal: `init` and `protocol check`.
+- Agent-facing commands stay stable: `context`, `plan`, `state record-change`, `verify`, `repair packet`, and `state next`.
+- Low-level launcher lifecycle commands are removed from the product direction.
+- Phase planning documents are no longer the product documentation model.
+- README is the product entry point.
+- This direction document is the durable project compass.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "frontend-harness",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "docs",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "README.md"
+  ],
+  "bin": {
+    "frontend-harness": "./dist/cli/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "harness": "node dist/cli/index.js",
+    "prepare": "npm run build",
+    "smoke:phase9": "node scripts/smoke-phase9.mjs",
+    "verify": "npm test && npm run typecheck && npm run build && npm run smoke:phase9",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}