UniSpec Portal

Next.js Portal runtime package for UniSpec: multi-service aggregation, workspace state, and UniSpec Tests execution

This repository contains the @unispechq/unispec-portal package. It is a Next.js application with server-side API routes and a small CLI launcher (bin).

In the current architecture, the portal process is typically started by unispec-platform (launcher).

Ecosystem dependencies:

• unispec-spec — UniSpec + UniSpec Tests format definition (schemas + reference docs)
• @unispechq/unispec-core — Core Engine (loader/validator/normalizer/diff/converters)

Repository Status

This repository is in active development. Current focus:

• Stable portal package contract for unispec-platform (dev|start, --config, stable exit codes)
• Local multi-service aggregation (/unispec.json)
• Workspace state (/workspace/state) stored as JSON
• UniSpec Tests execution (/tests/run) validated via @unispechq/unispec-core

Launch Contract (CLI bin)

The package exports a unispec-portal binary:

unispec-portal dev --config ./unispec.config.json
unispec-portal start --config ./unispec.config.json

In practice this is launched through unispec-platform:

unispec portal start --config ./unispec.config.json

Options

• --config <path|url> — path or HTTP(S) URL to unispec.config.json (required)
• --host <host> — bind host (default: 127.0.0.1)
• --port <port> — bind port (default: 3000)
• --storage <type> — json|sqlite (currently json implemented, sqlite planned)
• --data-dir <path> — data directory (default: <configDir>/.unispec)
• --open — open browser
• --verbose — verbose diagnostic output
• --json-errors — print errors as stable JSON

Registry / private access:

• UNISPEC_PORTAL_REGISTRY_TOKEN — optional Bearer token used for fetching remote config/specs

Process Behavior (DX)

start runs a prebuilt Next.js standalone bundle shipped with the package (no runtime build).

• Exit codes
  • 0 — clean shutdown
  • != 0 — startup/config/runtime error
• Signals
  • clean shutdown on SIGINT/SIGTERM
• Output
  • errors to stderr
  • normal logs to stdout
  • with --json-errors, errors are printed as stable JSON

Auto-build for start

In start mode, if .next/ is missing, the portal automatically runs next build and then runs next start. This is important for scenarios where the portal is started as an installed npm dependency via unispec-platform.

unispec.config.json Format

{
  "version": 1,
  "services": [
    { "name": "users", "spec": "./services/users/unispec.yaml" },
    { "name": "billing", "spec": "./services/billing/unispec.yaml" }
  ]
}

services[].spec can be either:

• a file path (relative to the config directory)
• an absolute path
• an HTTP(S) URL
• a relative URL (only when --config is an HTTP(S) URL; resolved against the config URL)

Config validation is performed on startup (fail-fast):

• validates schema and version
• enforces unique services[].name
• checks that each spec exists
  • file specs are checked via filesystem access
  • URL specs are checked via HTTP HEAD (with a fallback to GET if HEAD is not supported)

Remote sources are fetched using conditional requests when possible (ETag / Last-Modified) to keep data fresh while minimizing payload transfer.

HTTP API (server-side)

Base endpoints:

• GET /health — healthcheck
• GET /unispec.json — aggregated UniSpec (if any service is invalid: HTTP 422)
• GET /workspace.json — workspace metadata (urls, config, storage)
• GET /workspace/state — JSON workspace state
• PUT /workspace/state — atomically replace workspace state
• POST /tests/run — execute UniSpec Tests (YAML)

/unispec.json

• loads and parses YAML specs
• validates each document via @unispechq/unispec-core (validateUniSpec)

Development

Requirements:

• Node.js 18+

Install:

npm install

Run (as a Next.js app directly):

npm run dev

Run (through the CLI bin, like the launcher does):

node bin/cli.js dev --config ./unispec.config.json

Tests:

npm test

Publishing

The package is published as @unispechq/unispec-portal.

A files whitelist is used in package.json to control what is included in the npm tarball.

Related Repositories

| Repository | Purpose | |---|---| | unispec-spec | UniSpec format + UniSpec Tests schemas/examples | | unispec-core | Core Engine (validation/normalize/diff/converters) | | unispec-platform | CLI launcher (в т.ч. unispec portal dev|start) |