@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

npm install @hoplogic/spec

Usage

HopSpec — Parse and validate LLM agent specs

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

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

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