glossary

Glossary management platform. Defines the protocol, parses, validates, and queries terminology sets — without owning any specific vocabulary.

glossary is the control plane for terminology management. Each team brings their own terminology data (the data plane) — glossary provides the schema, the parser, the validator, the query layer, and (in future versions) the exporters and indexes.

It is intentionally not a glossary itself: shipping no terms means every team can adopt it without forking, and the platform stays domain-agnostic.

Status

v0.1 — feature-complete. Protocol schema, CLI (validate / import / list / show), file-based storage, and the (namespace, group, term) identity model are all implemented and covered by 77 tests.

What's in this repo

glossary/
├── spec/                          ← The protocol (single source of truth)
│   ├── glossary.schema.json       ← JSON Schema (Draft 2020-12)
│   └── examples/
│       ├── minimal.json
│       ├── full.json
│       └── invalid/               ← Negative fixtures with expected error codes
│
├── docs/
│   └── cli-reference.md           ← CLI command contract (v0.1)
│
├── src/
│   ├── cli/                       ← Command-line entry (commander-based)
│   │   ├── index.ts
│   │   └── commands/              ← validate / import / list / show / reserved
│   └── core/                      ← Library API; reusable by future server/UI/MCP
│       ├── model/                 ← TypeScript types mirroring the schema
│       ├── parser/                ← JSON input → in-memory Glossary
│       ├── validator/             ← Level 1 (schema), Level 2 (references), Level 3 (plugins)
│       ├── repository/            ← Storage abstraction; FileRepository ships in v0.1
│       └── query/                 ← list / show services
│
└── test/
    ├── unit/                      ← Per-module unit tests (vitest)
    └── integration/               ← End-to-end CLI tests

Design references

The design background and decisions live alongside the rest of the myflx-home documentation:

• ../doc/glossary-design.md — definition, scope, key decisions
• ../doc/ai-coding-design.md — the broader AI-Coding platform (L0–L5)
• ./docs/cli-reference.md — CLI command contract

Quick start

# 1. Install + build (one-time)
pnpm install
pnpm build

# 2. Link the CLI globally so `glossary ...` works anywhere
pnpm link --global   # later: `pnpm unlink --global` to remove

# 3. Validate a glossary file (no writes)
glossary validate ./spec/examples/full-api-contracts.json

# 4. Import into the working directory (default ~/.glossary/store)
glossary import ./spec/examples/full-api-contracts.json
glossary import ./spec/examples/full-persistence.json

# 5. List terms
glossary list
glossary list --namespace dev-common --group api-contracts
glossary list --include-deprecated

# 6. Show a single term (fully-qualified reference required at the CLI)
glossary show dev-common:api-contracts::DTO
glossary show dev-common:api-contracts::DTO --with-relations

Without pnpm-link

If you don't want to install globally, invoke the built CLI directly:

node dist/cli/index.js validate ./spec/examples/full-api-contracts.json

--json output

Every command accepts --json to emit a structured envelope on stdout — useful for scripting, CI integration, and AI agents:

glossary --json list --namespace dev-common | jq '.data.items[].term'

Supported spec versions

This build targets glossary spec >=0.1.0 <0.2.0. See package.json → metadata.supported_spec_versions.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm lint
pnpm format

License

MIT