@hoplogic/spec 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @hoplogic/spec
+
+HopSpec / PlanSpec parser, validator, and tree operations for TypeScript.
+
+Zero external dependencies. Pure compute. Works in Node.js (>=18), Bun, and browsers.
+
+## Install
+
+```bash
+npm install @hoplogic/spec
+```
+
+## Usage
+
+### HopSpec — Parse and validate LLM agent specs
+
+```typescript
+import { parseFullSpec, validateSpec } from "@hoplogic/spec"
+
+const markdown = `# HopSpec: MyTask
+## 任务概述
+...
+## 执行流程
+### 步骤 1: analyze [LLM]
+...`
+
+const { sections, steps } = parseFullSpec(markdown)
+const errors = validateSpec(steps)
+```
+
+### PlanSpec — Structured task plans
+
+```typescript
+import { parsePlan, serializePlan, validatePlan, findStep, countSteps, countByStatus } from "@hoplogic/spec"
+
+const plan = parsePlan(`
+# Plan: Implement Feature X
+Goal: Add feature X
+Constraints:
+- No breaking changes
+## Steps
+1. [reason] Analyze codebase -> change_points
+2. [act] Implement changes -> code
+3. [act] Write tests -> tests
+`)
+
+// Validate structure
+const errors = validatePlan(plan) // []
+
+// Navigate steps
+const step = findStep(plan, "2")
+step.status = "done"
+step.result = "Changes implemented in src/feature.ts"
+
+// Serialize back to markdown
+const updated = serializePlan(plan)
+
+// Progress tracking
+const total = countSteps(plan) // 3
+const byStatus = countByStatus(plan) // { done: 1, pending: 2, active: 0, blocked: 0 }
+```
+
+### Format Repair — Fix malformed LLM JSON output
+
+```typescript
+import { parseResult, coerceToDict, repairValue, detectSerializationResidue } from "@hoplogic/spec"
+
+const raw = '{"answer": "hello", "items": "[1, 2, 3]"}'
+const parsed = parseResult(raw)
+const residue = detectSerializationResidue(parsed) // detects stringified list
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `parseSpec(markdown)` | Parse HopSpec steps from markdown |
+| `parseFullSpec(markdown)` | Parse sections + steps |
+| `validateSpec(steps)` | Validate StepInfo tree |
+| `parsePlan(markdown)` | Parse PlanSpec from markdown |
+| `serializePlan(plan)` | Serialize PlanSpec back to markdown |
+| `validatePlan(plan)` | Validate PlanSpec structure |
+| `findStep(plan, stepId)` | Find step by ID in tree |
+| `countSteps(plan)` | Count total leaf steps |
+| `countByStatus(plan)` | Count steps by status |
+| `parseResult(raw)` | Parse LLM JSON output |
+| `coerceToDict(value)` | Coerce value to dict |
+| `repairValue(value, key)` | Repair malformed values |
+| `detectSerializationResidue(obj)` | Detect stringified collections |
+
+## License
+
+MIT