@sightmap/sightmap

Library and CLI for the Sightmap spec.

• Spec & docs: sightmap.org · github.com/sightmap/spec
• Package: @sightmap/sightmap on npm
• Source: github.com/sightmap/sightmap-js

A Sightmap is a YAML description of a web app's views, components, and API requests — the runtime semantics agents need to navigate and interact with the app. This package gives a coding agent a reliable, machine-readable toolkit for curating the .sightmap/ directory in a customer's repo.

npm install -D @sightmap/sightmap

CLI

sightmap validate [path]                                         # default path: .sightmap
sightmap lint [path] [--strict] [--rules <list>]
sightmap check [path] [--stdin] [--level schema|quality]         # combined validate + lint
sightmap match <url> [path] [--method <m>] [--require-view]
sightmap explain <query> [path] [--by name|path] [--type view|component|request] [--require-hit]
sightmap fmt [path] [--check] [--write]                          # default path: .sightmap
sightmap check-conventions [path]                                # default path: .

check powers the WI-2 advisory hooks: --stdin reads YAML from stdin and validates it as a virtual <stdin> source. --level schema skips lint rules; the default quality runs both.

Every command supports --json for machine-readable output and --cwd <dir> for invocation from outside the project.

Examples

# Validate the schema of every YAML file under .sightmap/
$ sightmap validate
ok    .sightmap/views.yaml
ok    .sightmap/components.yaml
2 file(s) checked.

# Lint, asking for JSON
$ sightmap lint --json
{
  "ok": true,
  "command": "lint",
  "diagnostics": [
    { "severity": "warning", "code": "duplicate-route", "message": "Route \"/\" is defined by both ..." }
  ],
  "result": {}
}

# Resolve everything an agent needs to drive the URL /list/abc123
$ sightmap match /list/abc123
view  ListDetailScreen  (route /list/*)
  source  app/list/[id].tsx
comp  BottomTabBar  global  selector=[role="tablist"]
comp  ListCard      global  selector=[data-testid="list-card"]
...

# Find every entry tied to a particular source file
$ sightmap explain 'app/(tabs)/index.tsx'
4 hit(s) for "app/(tabs)/index.tsx":
  view       ArcList            matchedAs=path  src=app/(tabs)/index.tsx
  component  CreateArcButton    matchedAs=path  src=app/(tabs)/index.tsx
  component  StatusFilter       matchedAs=path  src=app/(tabs)/index.tsx
  component  ArcCard            matchedAs=path  src=app/(tabs)/index.tsx

sightmap fmt [path]

Canonicalize .sightmap/*.yaml files per the spec's normative formatting rules. Comment- and HEADER-preserving.

sightmap fmt --check         # exit 1 if any file is not canonical (CI mode)
sightmap fmt --write         # rewrite non-canonical files in place

Diagnostics: fmt.not-canonical (warning), fmt.parse-error (error), fmt.schema-invalid (error). Files with parse or schema errors are left untouched.

Exit codes: 0 (canonical / no rewrites needed), 1 (--check found non-canonical files), 2 (parse / schema / IO error).

sightmap check-conventions [path]

Validate that the repo at <path> (default .) follows the filename conventions for SEPs (seps/NNNN-{slug}.md) and conformance fixtures (conformance/NNN-{slug}.fixture/). Exit code 0 if clean, 1 if any violations. Pass --json for machine-readable output.

sightmap check-conventions .
sightmap check-conventions /path/to/repo --json

Unlike validate/lint/match/explain, this command takes a repo root, not a .sightmap/ directory. It only inspects seps/ and conformance/; everything else (including spec/, docs/, and top-level project files) is ignored.

Exit codes

• 0 — success
• 1 — logical failure (validation error, --strict warning, --require-view/--require-hit miss)
• 2 — usage error

For lint, default mode exits 0 even with warnings. Pass --strict to upgrade all warnings (including merge-time collisions surfaced by loadDirectory) to errors.

URL handling for match

match accepts either a pathname (/foo/bar) or an absolute URL (https://example.com/foo/bar). It strips scheme, host, query string, and fragment before resolving. Trailing slashes are normalized. Matching is case-sensitive.

Routes use the spec's glob syntax: * matches one segment, ** matches any depth, :param segments normalize to *.

--json envelope

Every command emits the same top-level shape so agents can dispatch on command:

{
  "ok": true,
  "command": "match",
  "diagnostics": [],
  "result": { "...": "command-specific" }
}

Library

import {
  parse,
  validate,
  merge,
  loadDirectory,
  match,
  explain,
  lint,
} from "@sightmap/sightmap";

const sightmap = await loadDirectory(".sightmap");

const r = match(sightmap, { url: "/search" });
console.log(r.view?.name, r.components.length);

const hits = explain(sightmap, "src/components/Foo.tsx");
const issues = await lint(sightmap, { root: process.cwd() });

parse() throws on invalid input; validate() returns a non-throwing Result. Downstream packages should consume validate(), not parse(). parse() is sugar for end-user code that knows the input is valid.

For the canonical spec semantics — schema fields, route glob syntax, scope rules, and the design rationale — see sightmap.org and spec/v1/schema.md in the spec repo.

Diagnostics

Lint and validate share a Diagnostic shape:

type Diagnostic = {
  severity: "error" | "warning" | "info";
  code: string;
  message: string;
  file?: string;
  path?: string;                       // JSON pointer within the file
  loc?: { line: number; column: number };
  source?: string;
};

Codes are stable, kebab-case, and exported as constants:

| Code | Severity | Source | | ----------------------------- | -------- | ------------------------- | | parse-error | error | parse / loadDirectory | | schema-validation-failed | error | validate | | unknown-version | error | validate | | merge-collision-view | warning | merge / loadDirectory | | merge-collision-component | warning | merge / loadDirectory | | duplicate-view-name | warning | lint | | duplicate-route | warning | lint | | route-shadowing | warning | lint | | unknown-source | warning | lint | | selector-syntax | warning | lint | | convention.sep-filename | error | check-conventions | | convention.fixture-dirname | error | check-conventions | | convention.invalid-slug | error | check-conventions | | convention.unexpected-file | error | check-conventions | | fmt.not-canonical | warning | fmt --check | | fmt.parse-error | error | fmt | | fmt.schema-invalid | error | fmt |

Renames require an SEP. Future SDK ports (Python, Go) MUST emit identical codes for the same conditions.

Initialize a project

For a new adopter, the fastest path from zero to a working Sightmap loop is:

npx @sightmap/sightmap init

This detects your framework (React/Next/Vite/RR7), the coding-agent harness(es) in use (Claude Code, Codex, Cursor, OpenCode), and any Sightmap-aware browser MCP already installed (Subtext today). It then runs framework setup (adapter install + <SightmapProvider> codemod) and offers two install paths:

• Plugin (recommended): two copy-paste commands per host. Skills, hooks, MCP — all together.
• Manual: writes MCP config + copies skills/hooks into this repo.

Pass --yes to skip all prompts and accept defaults. Other flags:

--plugin / --manual         Force install path
--host <names>              Comma-separated: claude-code,codex,cursor,opencode
--with-browser              Force bundled Playwright + sightmap_* browser tools
--curate-only               Force curation-only MCP
--no-provider               Skip <SightmapProvider> codemod

See docs/superpowers/specs/2026-05-11-sightmap-init-design.md for the full design.

License

MIT.