Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to Beskid Nexus Open feature in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

Public catalog

Section titled “Public catalog”

GET /api/catalog

Section titled “GET /api/catalog”

Returns:

{
  "entries": [
    {
      "id": "beskid",
      "displayName": "Beskid",
      "description": "Language platform superrepo",
      "gitUrl": "https://github.com/Cyber-Nomad-Collective/beskid",
      "defaultBranch": "main",
      "sortOrder": 0,
      "indexed": true,
      "registryName": "beskid-main",
      "lastIndexedCommit": "abc123",
      "indexedAt": "2026-05-30T12:00:00.000Z",
      "stats": { "nodes": 12000, "relationships": 45000 },
      "docStatus": "ready"
    }
  ]
}
RulePolicy
NX-01Response must not expose internal paths, OpenRouter model names, or prompt text
NX-02Entries with indexed: false may appear in catalog but must not be selected as landing default
NX-03docStatus is coarse public state only — no AI pipeline error strings

GET /api/catalog/:id

Section titled “GET /api/catalog/:id”

Returns: single PublicCatalogEntry or 404.

Public graph

Section titled “Public graph”

GET /api/graph?repo=<registryName>

Section titled “GET /api/graph?repo=<registryName>”

Returns:

{
  "nodes": [
    {
      "id": "n_42",
      "labels": ["Function"],
      "properties": {
        "name": "resolveImports",
        "path": "compiler/crates/beskid_analysis/src/resolve/mod.rs",
        "codeDoc": "Resolves import declarations against the module index for the active compilation unit.",
        "specLinks": [
          {
            "title": "Dependency graph and cycle policy",
            "href": "/platform-spec/compiler/resolution-and-projects/dependency-graph-and-cycle-policy/"
          }
        ]
      }
    }
  ],
  "relationships": []
}
RulePolicy
NX-G-01repo query must match registryName of an indexed catalog entry
NX-G-02properties.codeDoc and properties.specLinks must be omitted when no CodeDocRecord exists
NX-G-03When present, codeDoc and specLinks must be attached separately — never concatenated into one string
NX-G-04Graph stream must be the cached LadybugDB export; clients must not trigger analyze from this route

Authenticated session

Section titled “Authenticated session”

GET /api/auth/me

Section titled “GET /api/auth/me”

Returns:

{
  "login": "octocat",
  "name": "Octocat",
  "avatarUrl": "https://avatars.githubusercontent.com/u/1?v=4",
  "ownedRepoIds": ["my-demo", "beskid"]
}
RulePolicy
NX-A-01ownedRepoIds lists catalog id values where the session user is GitHub owner or admin
NX-A-02Unauthenticated requests must return 401
NX-A-03Ownership must be verified via GitHub API with hub user token — not a static env roster

Repo-owner admin

Section titled “Repo-owner admin”

All routes below require authenticated session and GitHub ownership of the target entry’s gitUrl.

POST /api/admin/catalog

Section titled “POST /api/admin/catalog”

Body:

{
  "displayName": "My Demo",
  "description": "Example Beskid repo",
  "gitUrl": "https://github.com/octocat/demo",
  "defaultBranch": "main"
}

Returns: created PublicCatalogEntry or 403 when user is not repo owner.

PATCH /api/admin/catalog/:id

Section titled “PATCH /api/admin/catalog/:id”

Body: partial metadata fields (displayName, description, gitUrl, defaultBranch, sortOrder).

DELETE /api/admin/catalog/:id

Section titled “DELETE /api/admin/catalog/:id”

Removes entry from global registry and associated index artifacts.

POST /api/admin/catalog/:id/analyze

Section titled “POST /api/admin/catalog/:id/analyze”

Enqueues clone + analyze worker for the entry.

POST /api/admin/catalog/:id/refresh-docs

Section titled “POST /api/admin/catalog/:id/refresh-docs”

Enqueues code-doc maintenance for the entry (server-side only).

RulePolicy
NX-ADM-01Non-owners must receive 403 — not 404 — to avoid catalog id enumeration ambiguity
NX-ADM-02Operator requireAdmin must remain only for setup pairing (POST /api/admin/auth/pair) and instance bootstrap
NX-ADM-03Ownership checks may be cached up to 15 minutes per (login, gitUrl) pair

CodeDocRecord validation

Section titled “CodeDocRecord validation”
RulePolicy
NX-DOC-01codeDoc must describe what the code does in the repo — generated from graph metadata and short file snippets only
NX-DOC-02codeDoc must not contain platform-spec MDX body text or long excerpts from the spec link index
NX-DOC-03Anti-copy guard must reject records where codeDoc contains ≥40 consecutive characters matching any spec index excerpt
NX-DOC-04specLinks must contain 0–3 entries; each href must exist in the built spec link index
NX-DOC-05Unknown href values must be dropped at commit time — never stored or exposed
NX-DOC-06Regeneration must skip entities whose contentHash is unchanged
NX-DOC-07Similar sibling codeDoc text (Jaccard > 0.85) should be deduplicated before persist
Section titled “Spec link index (read-only)”

Built at boot from NEXUS_SPEC_ROOT (default: site/website/src/content/docs/platform-spec). Index stores slug, title, href, and heading outline for link lookup only — full MDX bodies must not be fed into code-doc generation prompts.

MCP

Section titled “MCP”

POST /api/mcp (Streamable HTTP)

Section titled “POST /api/mcp (Streamable HTTP)”
RulePolicy
NX-MCP-01Endpoint must be mounted at /api/mcp on the Nexus origin
NX-MCP-02Requests must include Authorization: Bearer <NEXUS_MCP_AUTH_TOKEN>
NX-MCP-03Missing or invalid Bearer must return 401
NX-MCP-04MCP tools expose graph query capabilities from the cached index — same data plane as public graph API
NX-MCP-05Connect MCP dialog must document endpoint and header format; token is operator-supplied via deployment env

Example client configuration:

URL: https://nexus.beskid-lang.org/api/mcp
Header: Authorization: Bearer $NEXUS_MCP_AUTH_TOKEN

Edge cases

Section titled “Edge cases”
ScenarioExpected behavior
Catalog emptyLanding empty state; repo selector disabled
Entry registered but not indexedVisible in selector with disabled graph; owner may trigger analyze
Analyze in progressGraph route returns 409 or stale export per server policy; UI shows loading state
Doc job faileddocStatus: failed; graph still served; codeDoc absent on affected entities
Non-GitHub gitUrl on create400 — ownership cannot be verified
GitHub API rate limitOwnership cache reduces calls; transient failures must fail closed (403)
Spec index stale after site deployOperator restarts Nexus or triggers spec index rebuild at boot

Type reference

Section titled “Type reference”
interface PublicCatalogEntry {
  id: string;
  displayName: string;
  description: string;
  gitUrl: string;
  defaultBranch?: string;
  sortOrder: number;
  indexed: boolean;
  registryName?: string;
  lastIndexedCommit?: string;
  indexedAt?: string;
  stats?: { nodes: number; relationships: number };
  docStatus?: 'idle' | 'running' | 'failed' | 'ready';
}

Normative TypeScript mirrors live in beskid_nexus/gitnexus/src/server/nexus/types.ts.