@nectary/kb

Published knowledge base for Nectary: catalog, schemas, and docs-derived reference. MCP, CLI, Figma, and widget data live in their own packages; this repo assembles an index and ships frozen artifacts to npmjs.org (@nectary/kb).

See docs/ARCHITECTURE.md for the multi-repo model.

Consumer setup

@nectary/kb is the single index for Nectary's AI surfaces. Most facets — the catalog, per-component machine JSON, structured and compressed markdown, Figma mappings, CLI compositions — are bundled inside the package and resolve from dist/. The narrative MCP component markdown is intentionally decoupled: it lives in @nectary/mcp and is referenced from the catalog by package-relative path.

Install

Published on npmjs.org alongside @nectary/components — no Nexus registry config required.

pnpm add @nectary/kb
# Only if you want to resolve paths.mcpMd (hand-curated narrative guidance):
pnpm add @nectary/mcp

Where each facet lives

| Catalog path | Resolved from | Requires | |---|---|---| | paths.md, paths.mdCompressed, paths.figma | inside @nectary/kb | @nectary/kb | | paths.componentJson (structured per-tag API: props, events, slots, tokens) | inside @nectary/kb | @nectary/kb | | paths.mcpMd (@nectary/mcp/data/components/...) | @nectary/mcp package | @nectary/kb + @nectary/mcp | | compositions/catalog.json (thin index) | inside @nectary/kb | @nectary/kb | | compositions[].paths.compositionJson (full content with inlined source files) | inside @nectary/kb | @nectary/kb | | tokens.json (design tokens) | inside @nectary/kb | @nectary/kb |

Per-component JSON (dist/components/<tag>.json)

The richest agent-facing data per primitive. Validated by schema/component.schema.json.

{
  tagName: 'sinch-button',
  docFolder: 'Button',
  description: '...',
  props: [
    { name: 'role', type: "'button' | 'tab' | 'menuitem' | ...", required: false, description: '...' },
    { name: 'aria-label', type: 'string', required: true, description: '...' },
    // ...
  ],
  events: [
    { name: '-click', payload: '(e: CustomEvent<void>) => void', description: 'Click event handler' },
    // ...
  ],
  slots: [{ name: 'left-icon' }, { name: 'icon' }, { name: 'right-icon' }],
  tokens: ['--sinch-comp-button-color-...', /* ... */],
  mcpDescription: '...',  // hand-curated blurb (null if no MCP coverage)
  mcpSchemaAttrs: [...],  // attribute allowlist from MCP schema.json (null if no coverage)
  figma: { figmaUrl, nodeId, ... } | null
}

Props/events come from each component's upstream types.ts; slots from template.html; tokens from theme CSS. Event names preserve the Nectary -click / -change convention (bind in React as on-click).

Per-composition JSON (dist/compositions/<name>.json)

CLI compositions ship with inlined source files and a parsed React prop interface so MCP, the docs chatbot, the widget, and skills can answer "what does this composition accept?" without re-parsing TSX. Validated by schema/composition.schema.json.

{
  name: 'select',
  description: '...',
  dependencies: [],
  propsInterface: 'SelectSearchProps',
  props: [
    { name: 'options', type: 'string[]', required: false, description: '' },
    { name: 'value', type: 'string', required: false, description: '' },
    { name: 'onChange', type: '(value: string) => void', required: false, description: '' },
    // ...
  ],
  files: [
    { path: 'Select/Search.tsx', content: '<full TSX>' }
  ]
}

Props are parsed from the export interface <Name>Props or export type <Name>Props = {…} block in the composition's main TSX (the file whose interface name matches the composition's PascalCase, falling back to the first match). React callback props (onClick, onChange, …) live in props — there is no separate events field for compositions because they aren't web-component custom events.

Only some primitives carry hand-curated MCP guidance — check hasMcpGuidance (or paths.mcpMd truthy) before resolving:

import catalog from '@nectary/kb/catalog'

for (const p of catalog.primitives) {
  if (!p.hasMcpGuidance || !p.paths.mcpMd) continue
  // paths.mcpMd is package-relative, e.g. '@nectary/mcp/data/components/sinch-button.md'
  const file = require.resolve(p.paths.mcpMd)
  // ...read with fs.readFile, etc.
}

Consumers that don't install @nectary/mcp should treat paths.mcpMd as absent — the bundled paths.md / paths.mdCompressed are sufficient for most use cases.

Version pinning

manifest.json records each source's provenance at build time:

{
  "sources": {
    "packages":        { "mcp": "@nectary/mcp", "cli": "@nectary/cli", "figma": "@nectary/figma-connect" },
    "packageVersions": {
      "mcp": "0.1.0",
      "cli": "0.0.1",
      "@nectary/components": "git:66fc44e7...",
      "playground": "git:bbfef3eb...",
      "figma": "git:ff4e50b5..."
    }
  }
}

Semver values come from each source repo's package.json; git:<sha> values are git revisions for sources whose monorepo root isn't a publishable package. playground is the source for dist/design-rules.md (compressed from reference-sources/DESIGN_GUIDELINES.md). For reproducible narrative content, pin @nectary/mcp to the version under packageVersions.mcp recorded in the KB build you installed — otherwise content read via paths.mcpMd may drift.

Maintainers (this repo)

pnpm install
cp kb.config.example.json kb.config.json

pnpm run kb:extract    # → .kb-staging/ (reads upstream packages)
pnpm run kb:assemble   # → dist/ (publishable)
pnpm run kb:generate   # extract + assemble
pnpm run kb:validate

@nectary/kb does not run extract/assemble at runtime — only CI / prepublishOnly builds dist/. The prepack lifecycle strips build-time fields (sources.nectaryComponents, sources.nectaryPlayground, sources.packageArtifactRoots) from the published manifest.

Config (kb.config.json)

| Field | Purpose | |-------|---------| | sources.components.root | nectary-components checkout (docs + types) | | sources.mcp | @nectary/mcp package or fallbackPath until split lands | | sources.figma | @nectary/figma-connect or components tree fallback | | stagingDir | Extract output (default .kb-staging) | | outputDir | Published tree (default dist) |

Schemas

| File | Contract | |------|----------| | schema/catalog.schema.json (v1.4.0) | dist/catalog.json | | schema/component.schema.json | dist/components/<tag>.json | | schema/composition.schema.json | dist/compositions/<name>.json |

Primitives in the catalog include hasMcpGuidance, optional relations (parent/child/slot usage, MCP-derived), and paths relative to @nectary/kb dist or upstream packages (paths.mcpMd → @nectary/mcp/...). Compositions include paths.compositionJson pointing at the per-composition record with inlined source files (compositions/{name}.json). Per-component JSON carries the structured API surface (props, events, slots, tokens) — validated strictly against component.schema.json for every primitive.

Do not commit dist/, .kb-staging/, or deps/ — they are built in CI or locally.

Extractor dispatch (one active path per source)

Each external facet has a single active read path: from-mcp.ts and from-figma.ts read from paths.X.root, which resolvePackageSource resolves to either the installed package (when present in node_modules) or sources.X.fallbackPath (a sibling repo checkout). CI sets up the fallback path via scripts/ci-clone-sources.sh. Compositions are first-party — from-compositions.ts reads from packages/compositions inside this repo. There is no parallel git-show bridge.

CI

GitLab pipeline (see .gitlab-ci.yml): typecheck → kb:generate + kb:validate → publish @nectary/kb to npmjs.org on default branch.

Publish CI/CD variable (on nectary-kb): NPM_TOKEN — npm automation token with publish access to the @nectary scope (same model as nectary-components). Optional NPM_REGISTRY override defaults to https://registry.npmjs.org/.

Verify locally: npm publish --dry-run (uses your npm login or NPM_TOKEN in the environment).

Upstream clones use scripts/ci-clone-sources.sh (sibling repos under nectary/ on branch names in docs/ARCHITECTURE.md).

Cross-repo clone access: the build job clones components, nectary-mcp, nectary-figma, nectary-playground, and nectary-widget. On each of those projects, open Settings → CI/CD → Job token permissions and allow inbound access from nectary-kb. Without that, clone fails with Authentication by CI/CD job token not allowed from nectary-kb. Alternative: add a read_repository deploy or project access token as CI variable NECTARY_DEPS_CLONE_TOKEN on nectary-kb.