@jgalego/teamapi-core

@jgalego/teamapi-core

$ref resolution, org graph building, cognitive load scoring, DDD context-map derivation, and Mermaid/DOT diagram generation for the Team API as Code extended spec.

This is the shared engine behind the teamapi CLI, the REST API, the MCP server, and the chat tool-use loop — you normally don't depend on it directly unless you're building another adapter on top of the same org graph.

Install

npm install @jgalego/teamapi-core @jgalego/teamapi-schema

Usage

import { buildOrgGraph, buildTopologyDiagram, toMermaid } from "@jgalego/teamapi-core";

// seedUris are resolved file paths (expand any globs yourself, e.g. with `fast-glob`)
const graph = await buildOrgGraph({ seedUris: ["./examples/acme-org/stream-checkout/teamapi.yml"] });
console.log(toMermaid(buildTopologyDiagram(graph)));

Exports

• Resolution: buildOrgGraph, OrgGraphStore (a live, reloadable wrapper around buildOrgGraph), LoaderRegistry/FileLoader/HttpLoader (resolve/loaders), formatZodError (turns a Zod validation failure into a readable message).
• Model: OrgGraph, GraphEdge, RoleGraphEdge, ResolvedTeam types (model/org-graph); listTeams, getTeam, getInteractions, getDependencies, listServices, findServiceOwner, listRoles, listMembers, searchOrg (model/queries).
• Cognitive load: scoreCognitiveLoad, orgWideCognitiveLoadReport (cognitive-load/score).
• Gaps: planGaps, formatGaps (gaps/plan) — the accountability holes between teams, which are invisible from any single teamapi.yml and only appear once the graph is resolved. Pure: no I/O, no network.
• Shadow AI: scanForAiArtifacts (shadow-ai/scan) reads repository checkouts already on disk for MCP configs, agent instruction files, LLM SDKs in manifests and workflow steps that call a model; planShadowAi/formatShadowAi/repoNameFromUrl (shadow-ai/plan) reconcile what it found against what teams declare in agents[].
• DDD context mapping: deriveContextMap, MODE_TO_PATTERN_HEURISTIC (context-map/derive, context-map/patterns).
• Diagrams: buildTopologyDiagram, buildHierarchyDiagram, buildOrgHierarchyDiagram, buildContextMapDiagram (one per --scope), plus toMermaid/toDot renderers and the DiagramModel type they share.
• Serialization: toTeamSummaryDto, toTeamDetailDto, listTeamSummaries, toOrgGraphDto (serialize/team-dto) — the single source of truth both the REST API and the MCP server use to turn a ResolvedTeam/OrgGraph into a wire-format object, so their responses are identical by construction.
• Generators: buildCrewAiCrewConfig/buildCrewAiOrgConfig plus the toCrewAiCrewYaml/toCrewAiOrgYaml serializers (generators/crewai) — turn a team's (or the whole org's) roles into CrewAI agents.yaml/tasks.yaml. buildBackstageCatalog/ buildBackstageOrgCatalog plus toBackstageYaml (generators/backstage) — turn a team's (or the whole org's) services[]/members[] into a Backstage catalog-info.yaml (Group/User/System/Component entities).
• Diffing: diffOrgGraphs, isEmptyDiff, formatOrgGraphDiff (diff/diff-graph) — diff two resolved OrgGraphs (teams added/removed, per-team role/member/service/cognitive-load changes, edge changes) and render the result as a human-readable report. Git-agnostic — teamapi diff is what supplies "the org as of a git revision" as one side of the comparison.
• History: listRevisions, sampleRevisions, snapshotOrg, withChurn, formatHistory, historyToCsv (history/trends, git/ref-loader) — the org resolved at a series of past git revisions, as a trend rather than a pair of snapshots.
• Digest: buildOrgDigest, formatDigestText, digestToSlackMessage, digestToHtml (digest/build) — gaps + policy + topology merged with what moved since a previous snapshot.
• Metrics: collectOrgMetrics, renderPrometheus (metrics/*) — the org graph in the Prometheus exposition format, reused by serve-api --metrics.
• Semantic search: semanticSearchOrg, buildSearchDocuments, OpenAiEmbeddingProvider, EmbeddingCache, createEmbeddingScorer (search/*) — embedding-backed search and context-bundle scoring over any OpenAI-compatible /embeddings endpoint.
• Importers: importBackstageCatalog, importDirectoryGroups (Okta/Entra), importSlackChannels, importCsvRoster (import/*) — bootstrap documents from the systems an org already has.
• Write-back planners: planSlackUsergroups, planOktaGroups, planPagerDutyTeams (apply/*) — plan/execute reconciliation of memberships in external systems, same plan-then-confirm shape as the GitHub apply.
• Proposals: buildTeamProposal, openTeamProposal (propose/*) — a small, closed patch to one team document becomes a pull request, re-validated and re-formatted first.

Full docs: https://github.com/JGalego/TeamAPI

The TeamAPI toolchain

One org graph, seven doors into it — install only the ones you need:

Package	What it does
@jgalego/teamapi	The CLI — validate, diagram, check, import, reconcile, serve and chat with your org
@jgalego/teamapi-core (this package)	The engine: $ref resolution, the org graph, scoring, checks, diagrams, generators
@jgalego/teamapi-schema	Zod schemas and TypeScript types for the extended spec
@jgalego/teamapi-rest-api	REST API, live dashboard, Swagger UI, Prometheus metrics
@jgalego/teamapi-mcp-server	The org graph as MCP tools for LLM assistants
@jgalego/teamapi-chat	Chat as a team or member — Anthropic or any OpenAI-compatible endpoint
@jgalego/teamapi-backstage	Live Backstage catalog entity provider

Docs, examples and the extended spec: teamapi.dev · github.com/JGalego/TeamAPI

License

MIT