npm - frontend-harness - Versions diffs - 0.1.0 - Mend

frontend-harness 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/AGENTS.md +48 -0
package/CLAUDE.md +48 -0
package/README.md +262 -0
package/dist/cli/index.d.ts +2 -0
package/dist/cli/index.js +380 -0
package/dist/cli/index.js.map +1 -0
package/dist/runtime/builtin-skills.d.ts +6 -0
package/dist/runtime/builtin-skills.js +269 -0
package/dist/runtime/builtin-skills.js.map +1 -0
package/dist/runtime/clean.d.ts +11 -0
package/dist/runtime/clean.js +85 -0
package/dist/runtime/clean.js.map +1 -0
package/dist/runtime/command-taxonomy.d.ts +12 -0
package/dist/runtime/command-taxonomy.js +72 -0
package/dist/runtime/command-taxonomy.js.map +1 -0
package/dist/runtime/context.d.ts +71 -0
package/dist/runtime/context.js +153 -0
package/dist/runtime/context.js.map +1 -0
package/dist/runtime/graph.d.ts +12 -0
package/dist/runtime/graph.js +211 -0
package/dist/runtime/graph.js.map +1 -0
package/dist/runtime/knowledge.d.ts +48 -0
package/dist/runtime/knowledge.js +383 -0
package/dist/runtime/knowledge.js.map +1 -0
package/dist/runtime/plan.d.ts +18 -0
package/dist/runtime/plan.js +571 -0
package/dist/runtime/plan.js.map +1 -0
package/dist/runtime/policy-provenance.d.ts +17 -0
package/dist/runtime/policy-provenance.js +195 -0
package/dist/runtime/policy-provenance.js.map +1 -0
package/dist/runtime/project-discovery.d.ts +17 -0
package/dist/runtime/project-discovery.js +166 -0
package/dist/runtime/project-discovery.js.map +1 -0
package/dist/runtime/project-paths.d.ts +6 -0
package/dist/runtime/project-paths.js +47 -0
package/dist/runtime/project-paths.js.map +1 -0
package/dist/runtime/protocol-init.d.ts +50 -0
package/dist/runtime/protocol-init.js +256 -0
package/dist/runtime/protocol-init.js.map +1 -0
package/dist/runtime/repair-decision.d.ts +3 -0
package/dist/runtime/repair-decision.js +195 -0
package/dist/runtime/repair-decision.js.map +1 -0
package/dist/runtime/repair-packet.d.ts +7 -0
package/dist/runtime/repair-packet.js +159 -0
package/dist/runtime/repair-packet.js.map +1 -0
package/dist/runtime/skills.d.ts +19 -0
package/dist/runtime/skills.js +230 -0
package/dist/runtime/skills.js.map +1 -0
package/dist/runtime/state-explain.d.ts +2 -0
package/dist/runtime/state-explain.js +106 -0
package/dist/runtime/state-explain.js.map +1 -0
package/dist/runtime/state.d.ts +10 -0
package/dist/runtime/state.js +237 -0
package/dist/runtime/state.js.map +1 -0
package/dist/runtime/units.d.ts +10 -0
package/dist/runtime/units.js +181 -0
package/dist/runtime/units.js.map +1 -0
package/dist/runtime/verification-commands.d.ts +11 -0
package/dist/runtime/verification-commands.js +89 -0
package/dist/runtime/verification-commands.js.map +1 -0
package/dist/runtime/verify.d.ts +7 -0
package/dist/runtime/verify.js +192 -0
package/dist/runtime/verify.js.map +1 -0
package/dist/schemas/types.d.ts +244 -0
package/dist/schemas/types.js +2 -0
package/dist/schemas/types.js.map +1 -0
package/dist/schemas/validation.d.ts +2 -0
package/dist/schemas/validation.js +21 -0
package/dist/schemas/validation.js.map +1 -0
package/dist/storage/json.d.ts +5 -0
package/dist/storage/json.js +24 -0
package/dist/storage/json.js.map +1 -0
package/dist/storage/paths.d.ts +3 -0
package/dist/storage/paths.js +9 -0
package/dist/storage/paths.js.map +1 -0
package/docs/DIRECTION.md +67 -0
package/package.json +35 -0

package/AGENTS.md ADDED Viewed

@@ -0,0 +1,48 @@
+<!-- frontend-harness:managed:start -->
+# Frontend Harness Execution Policy for Codex
+This project uses `frontend-harness` as a project-level execution policy layer.
+The coding agent runtime remains responsible for its own agent loop, tools, context management, permissions, retries, subagents, and skill loading.
+`frontend-harness` owns only deterministic project facts, execution contracts, validation evidence, project-local knowledge, and repair artifacts.
+Required loop:
+1. Run `frontend-harness context --json` before planning edits.
+2. If agent planning input is useful, write only bounded hints (`intentSuggestion`, `constraintHints`, `componentHints`) to an agent decision JSON file and validate it with `frontend-harness decision check --json --file <agent-decision.json>`.
+3. Run `frontend-harness plan --json "<task>"` with optional `--agent-decision <agent-decision.json>`, or consume the existing `.frontend-harness/plans/latest.json` before editing.
+4. Edit only project files required by the system-owned plan and current task.
+5. Record every changed project file with `frontend-harness state record-change <file>`.
+6. Run `frontend-harness verify --json` and inspect the JSON result.
+7. If verification fails, run `frontend-harness repair packet --json`, inspect `.frontend-harness/repair/latest.json`, patch the relevant project files, record changes, and verify again.
+8. Before committing, inspect relevant project-local skills under `.frontend-harness/skills/` and follow the repository commit protocol.
+9. Stop only when `frontend-harness state next --json` returns `done` for the unchanged task scope.
+Commit protocol:
+- Use commit header format: `<type>(<scope>): <short description>`.
+- Allowed commit types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`.
+- Keep the header concise and include verification evidence in the commit body or trailers when available.
+Boundaries:
+- Do not treat `frontend-harness` as an agent launcher or runtime wrapper.
+- Do not edit `.frontend-harness/` generated artifacts manually; let harness commands write them.
+- Do not interpret planning or repair decision JSON as shell commands, patch content, scheduler directives, graph execution, skill routing, or RAG instructions.
+- Do not put workflow type, execution units, file paths, dependency graph, execution order, or verification commands into agent planning input; the system plan always owns those structures.
+- Keep durable project knowledge under `.frontend-harness/knowledge/` and project-local skills under `.frontend-harness/skills/` when intentionally authored.
+Useful commands:
+- `frontend-harness context --json`
+- `frontend-harness plan --json "<task>"`
+- `frontend-harness state record-change <file>`
+- `frontend-harness state record-change --from-git`
+- `frontend-harness verify --json`
+- `frontend-harness repair packet --json`
+- `frontend-harness state next --json`
+- `frontend-harness state explain --json`
+- `frontend-harness skills list --json`
+- `frontend-harness skills check --json`
+- `frontend-harness knowledge promote --json --title "<title>" --body "<body>"`
+- `frontend-harness knowledge check --json`
+- `frontend-harness decision check --json --file <agent-decision.json>`
+- `frontend-harness units check --json`
+- `frontend-harness graph check --json`
+- `frontend-harness repair decision check --json --file <repair-decision.json>`
+<!-- frontend-harness:managed:end -->

package/CLAUDE.md ADDED Viewed

@@ -0,0 +1,48 @@
+<!-- frontend-harness:managed:start -->
+# Frontend Harness Execution Policy for Claude Code
+This project uses `frontend-harness` as a project-level execution policy layer.
+The coding agent runtime remains responsible for its own agent loop, tools, context management, permissions, retries, subagents, and skill loading.
+`frontend-harness` owns only deterministic project facts, execution contracts, validation evidence, project-local knowledge, and repair artifacts.
+Required loop:
+1. Run `frontend-harness context --json` before planning edits.
+2. If agent planning input is useful, write only bounded hints (`intentSuggestion`, `constraintHints`, `componentHints`) to an agent decision JSON file and validate it with `frontend-harness decision check --json --file <agent-decision.json>`.
+3. Run `frontend-harness plan --json "<task>"` with optional `--agent-decision <agent-decision.json>`, or consume the existing `.frontend-harness/plans/latest.json` before editing.
+4. Edit only project files required by the system-owned plan and current task.
+5. Record every changed project file with `frontend-harness state record-change <file>`.
+6. Run `frontend-harness verify --json` and inspect the JSON result.
+7. If verification fails, run `frontend-harness repair packet --json`, inspect `.frontend-harness/repair/latest.json`, patch the relevant project files, record changes, and verify again.
+8. Before committing, inspect relevant project-local skills under `.frontend-harness/skills/` and follow the repository commit protocol.
+9. Stop only when `frontend-harness state next --json` returns `done` for the unchanged task scope.
+Commit protocol:
+- Use commit header format: `<type>(<scope>): <short description>`.
+- Allowed commit types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`.
+- Keep the header concise and include verification evidence in the commit body or trailers when available.
+Boundaries:
+- Do not treat `frontend-harness` as an agent launcher or runtime wrapper.
+- Do not edit `.frontend-harness/` generated artifacts manually; let harness commands write them.
+- Do not interpret planning or repair decision JSON as shell commands, patch content, scheduler directives, graph execution, skill routing, or RAG instructions.
+- Do not put workflow type, execution units, file paths, dependency graph, execution order, or verification commands into agent planning input; the system plan always owns those structures.
+- Keep durable project knowledge under `.frontend-harness/knowledge/` and project-local skills under `.frontend-harness/skills/` when intentionally authored.
+Useful commands:
+- `frontend-harness context --json`
+- `frontend-harness plan --json "<task>"`
+- `frontend-harness state record-change <file>`
+- `frontend-harness state record-change --from-git`
+- `frontend-harness verify --json`
+- `frontend-harness repair packet --json`
+- `frontend-harness state next --json`
+- `frontend-harness state explain --json`
+- `frontend-harness skills list --json`
+- `frontend-harness skills check --json`
+- `frontend-harness knowledge promote --json --title "<title>" --body "<body>"`
+- `frontend-harness knowledge check --json`
+- `frontend-harness decision check --json --file <agent-decision.json>`
+- `frontend-harness units check --json`
+- `frontend-harness graph check --json`
+- `frontend-harness repair decision check --json --file <repair-decision.json>`
+<!-- frontend-harness:managed:end -->

package/README.md ADDED Viewed

@@ -0,0 +1,262 @@
+# frontend-harness
+`frontend-harness` is an Execution Policy Layer for frontend teams using Codex or Claude Code.
+It does not replace the agent runtime. Codex and Claude Code already provide the loop, tool execution, context handling, permissions, retries, subagents, and skill loading. `frontend-harness` adds the project-level rules those agents should follow inside a frontend repository.
+The product goal is simple:
+```text
+install once -> inject AGENTS.md / CLAUDE.md -> work normally with AI
+```
+After initialization, team members should not need to manually run the harness loop. They keep asking Codex or Claude Code for frontend work in plain language. The injected project protocol and built-in project skills tell the agent how to plan, edit, verify, and repair.
+## What It Does
+`frontend-harness` gives a project a deterministic execution contract:
+```text
+context -> plan -> implement -> record changes -> verify -> repair -> done
+```
+The CLI exists mainly as a protocol API for AI agents. Humans use it to install, initialize, and occasionally check health.
+## What It Is Not
+`frontend-harness` is not another agent platform.
+It should not rebuild:
+- agent loops
+- generic tool execution
+- permission systems
+- subagent orchestration
+- long-running runtime launchers or supervised agent wrappers
+- replacement workflows for Codex or Claude Code
+Those belong to the official agent runtimes. This package owns only the frontend project policy around them.
+## Install
+```bash
+npm install frontend-harness --save-dev
+npx frontend-harness init
+```
+`init` injects managed protocol blocks into:
+- `AGENTS.md`
+- `CLAUDE.md`
+It also scaffolds built-in project skills under `.frontend-harness/skills/`:
+- `frontend-discovery.md`
+- `architecture-boundary.md`
+- `ui-implementation.md`
+- `prd-knowledge.md`
+- `api-integration.md`
+- `form-workflow.md`
+- `frontend-test.md`
+- `bug-fix.md`
+- `requirement-change.md`
+- `frontend-change-review.md`
+- `git-commit.md`
+Existing project skill files are preserved. Rerun `init` after package upgrades to add newly introduced built-in skills.
+The built-in git commit skill uses `<type>(<scope>): <short description>` with `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, or `chore`.
+Once those files are present, the normal team workflow is:
+```text
+Open Codex or Claude Code.
+Ask for the frontend change.
+Let the injected protocol drive planning, verification, and repair.
+```
+## Human Commands
+Most team members only need these commands.
+```bash
+npx frontend-harness init
+npx frontend-harness init --json
+npx frontend-harness init --dry-run --json
+npx frontend-harness init --check --json
+npx frontend-harness protocol check
+npx frontend-harness protocol check --json
+npx frontend-harness clean --json
+```
+Use `init` after installation or package upgrades. Use `protocol check` when you want to verify that `AGENTS.md` and `CLAUDE.md` are current. Use `clean` to remove ignored runtime artifacts while preserving durable project skills, knowledge, and config.
+## Agent Protocol Commands
+These commands are intended for Codex / Claude Code through the injected protocol:
+```bash
+frontend-harness context --json
+frontend-harness decision check --json --file <agent-decision.json>
+frontend-harness plan --json "<task>"
+frontend-harness plan --json "<task>" --agent-decision <agent-decision.json>
+frontend-harness state record-change <file>
+frontend-harness state record-change --from-git
+frontend-harness verify --json
+frontend-harness repair packet --json
+frontend-harness state next --json
+frontend-harness state explain --json
+```
+The agent should call them automatically while doing work. They persist state under `.frontend-harness/` and provide deterministic evidence for each step.
+`verify --json` discovers the default `typecheck`, `test`, and `build` scripts when present. Projects can also declare custom verification commands in `.frontend-harness/config.json`:
+```json
+{
+  "verification": {
+    "commands": [
+      { "name": "lint", "command": "npm run lint" },
+      { "name": "e2e", "command": "npm run test:e2e" }
+    ]
+  }
+}
+```
+`plan --json` also classifies the frontend workflow and emits policy guidance for the agent. The current workflow classes are:
+- `ui_implementation`
+- `prd_knowledge`
+- `api_integration`
+- `frontend_test`
+- `bug_fix`
+- `requirement_change`
+Each plan includes required knowledge actions, implementation constraints, and verification focus. This keeps generated UI imports, PRD digestion, Swagger/API work, tests, bug fixes, and requirement changes inside the same controlled policy loop without turning skills into executable runtime commands.
+### Agent Plan Hints
+The plan is deterministic and system-owned. An agent may provide bounded hints before planning, but those hints cannot change workflow classification, execution units, file paths, dependency graph, scheduling, or verification commands.
+Valid hint input:
+```json
+{
+  "contractVersion": 1,
+  "decision": {
+    "intentSuggestion": "implement_page",
+    "constraintHints": ["Handle loading, empty, and error states."],
+    "componentHints": [
+      {
+        "name": "OrderSearchForm",
+        "responsibility": "query filters and submit behavior"
+      }
+    ]
+  }
+}
+```
+Validate the hint file before planning:
+```bash
+frontend-harness decision check --json --file agent-decision.json
+frontend-harness plan --json "<task>" --agent-decision agent-decision.json
+```
+The final plan still owns components, units, file paths, dependency graph, and verification requirements.
+## Advisory Commands
+These commands expose project-local knowledge and workflow guidance as provenance only. They do not launch agents, execute skills, or turn markdown into commands.
+```bash
+frontend-harness skills list --json
+frontend-harness skills check --json
+frontend-harness knowledge promote --json --title "<title>" --body "<body>"
+frontend-harness knowledge check --json
+```
+## Runtime Boundary
+The boundary is strict:
+- Codex / Claude Code owns execution.
+- `frontend-harness` owns policy.
+- The project owns durable state and knowledge.
+Project skills under `.frontend-harness/skills/` are policy guidance and provenance for planning. They are intentionally separate from Codex or Claude runtime skills installed in the developer environment.
+That means `frontend-harness` should stay small and focused. Its job is to make frontend work repeatable, not to become a second runtime.
+## Project State
+The package writes project-local artifacts under `.frontend-harness/`:
+```text
+.frontend-harness/
+  context/
+  plans/
+  execution-units/
+  component-graph/
+  guidance/
+  state.json
+  verification/
+  logs/
+  repair/
+  repair-decision/
+  state-explain/
+  protocol/
+  knowledge/
+  skills/
+  config.json
+```
+Runtime artifacts such as `context/`, `plans/`, `state.json`, `verification/`, `logs/`, `repair/`, `state-explain/`, `execution-units/`, and `component-graph/` are generated continuity and evidence. They are ignored by git and can be removed with `frontend-harness clean --json`.
+Durable project assets such as `knowledge/`, `skills/`, `config.json`, and protocol provenance are intentionally preserved by `clean` and may be committed when they represent project policy.
+## New Direction
+The project is being recentered around the original idea:
+1. Keep `AGENTS.md` and `CLAUDE.md` injection as the primary product surface.
+2. Treat CLI commands as the agent-facing protocol API, not the daily human UI.
+3. Keep the public human workflow to install, initialize, and check protocol health.
+4. Preserve deterministic context, plan, verify, repair, and state primitives.
+5. Delete launcher/runtime features that duplicate Codex or Claude Code.
+6. Keep removed `agent *` and `run --agent` surfaces out of the product unless the direction is explicitly revisited.
+7. Ship a small built-in set of project skills for common frontend workflows, while preserving project-local overrides.
+8. Keep documentation short, current, and product-oriented.
+The success criterion is not more commands. The success criterion is that a team member can install the package, initialize the protocol, and then use AI-assisted frontend development normally while the agent follows a controlled engineering loop.
+## Development
+Build:
+```bash
+npm run build
+```
+Run the CLI from this source checkout without linking:
+```bash
+npm run harness -- context --json
+npm run harness -- plan --json "<task>"
+npm run harness -- verify --json
+```
+The bare `frontend-harness ...` command is the installed-package entry point for consumer projects. In this repository, use `npm run harness -- ...` unless you intentionally install or link the package.
+Verify:
+```bash
+npm run verify
+```
+Package dry-run:
+```bash
+npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --dry-run
+```
+The temporary npm cache avoids local global-cache permission issues on machines where `~/.npm` contains root-owned files.

package/dist/cli/index.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ #!/usr/bin/env node
2	+ export {};