Use It Programmatically

Install as a dependency

Add the SDK to your project:

$ npm install @specforge/sdk

Parse any format

The SDK handles JSON, YAML, and TOML. You get back a typed object regardless of the source format:

import { parse } from '@specforge/sdk';

// Auto-detects format from extension
const spec = await parse('./todo-api.sf.json');

// Or parse a string directly
const spec2 = parse.json(jsonString);
const spec3 = parse.yaml(yamlString);
const spec4 = parse.toml(tomlString);

console.log(spec.project.name); // "todo-api"
console.log(spec.specforge);    // "1.0"

Validate

Programmatic validation returns structured results you can act on:

import { validate } from '@specforge/sdk';

const result = validate(spec);

if (result.valid) {
  console.log('Spec is valid');
} else {
  for (const error of result.errors) {
    console.error(`[${error.path}] ${error.message}`);
    // [/specifications/0/epics/0/tickets/0] must have required property 'status'
  }
}

// Check specific aspects
const deps = validate.dependencies(spec);
// { acyclic: true, danglingRefs: [], unreachable: [] }

Traverse the hierarchy

Walk specs, epics, and tickets without manual nesting:

import { traverse } from '@specforge/sdk';

// Visit every ticket in the spec
traverse.tickets(spec, (ticket, epic, specification) => {
  console.log(`[${specification.id}] [${epic.id}] ${ticket.title}`);
  // [spec-todo-api] [epic-core] POST /todos
  // [spec-todo-api] [epic-core] GET /todos
  // [spec-todo-api] [epic-core] DELETE /todos/:id
});

// Find a ticket by ID across all specs and epics
const ticket = traverse.findTicket(spec, 'ticket-create-todo');

// Get all tickets matching a filter
const open = traverse.filterTickets(spec, t => t.status === 'open');

Resolve the dependency graph

Build a dependency graph and query it for actionable tickets, blocked tickets, or the critical path:

import { graph } from '@specforge/sdk';

const g = graph.build(spec);

// What can be worked on right now?
const actionable = g.actionable();
// [{ id: 'ticket-create-todo', ... }]

// What is blocked and why?
const blocked = g.blocked();
// [{ id: 'ticket-list-todos', blockedBy: ['ticket-create-todo'] }, ...]

// Topological order for sequential execution
const order = g.topologicalSort();
// ['ticket-create-todo', 'ticket-list-todos', 'ticket-delete-todo']

// Critical path (longest chain)
const critical = g.criticalPath();
// ['ticket-create-todo', 'ticket-list-todos']

Convert between formats

Convert specs between JSON, YAML, and TOML:

import { convert } from '@specforge/sdk';

// JSON → YAML
const yaml = convert.toYaml(spec);

// JSON → TOML
const toml = convert.toToml(spec);

// Write to file (auto-detects from extension)
await convert.toFile(spec, './todo-api.sf.yaml');

What you can build

SpecForge is an open format. Here are some things people are building with the SDK: