https://github.com/kryptobaseddev/ckm
CKM — Codebase Knowledge Manifest SDK. Machine-readable operational knowledge for CLI tools. Rust core, Node.js/Python/Go wrappers.
https://github.com/kryptobaseddev/ckm
Last synced: 2 months ago
JSON representation
CKM — Codebase Knowledge Manifest SDK. Machine-readable operational knowledge for CLI tools. Rust core, Node.js/Python/Go wrappers.
- Host: GitHub
- URL: https://github.com/kryptobaseddev/ckm
- Owner: kryptobaseddev
- License: mit
- Created: 2026-03-29T22:59:11.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T19:01:20.000Z (2 months ago)
- Last Synced: 2026-04-03T17:40:37.051Z (2 months ago)
- Language: Rust
- Size: 330 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# CKM — Codebase Knowledge Manifest
**Machine-readable operational knowledge for CLI tools. Any language. Any framework. One implementation.**
[](https://crates.io/crates/ckm)
[](https://www.npmjs.com/package/ckm-sdk)
[](LICENSE)
---
## What is CKM?
CKM bridges the gap between API documentation and actionable help. While `--help` gives you flags and `llms.txt` gives you API signatures, CKM tells you what your tool **does**, what **concepts** it has, what **config** controls what **behavior**, and what **constraints** are enforced.
A `ckm.json` manifest captures structured knowledge about a CLI tool. The CKM SDK reads it and provides:
- **Auto-derived topics** — every concept becomes browsable, zero manual mapping
- **Progressive disclosure** — 4 levels from discovery to full API dump
- **Human + machine output** — terminal text for humans, JSON for LLM agents
- **Producer + consumer APIs** — build manifests with type safety, serve them with one import
```
$ mytool ckm calver
# Configures CalVer validation rules.
## Concepts
CalVerConfig — Configures CalVer validation rules.
format: CalVerFormat = YYYY.MM.DD
preventFutureDates: boolean = true
## Operations
validate() — Validates a CalVer string against formatting and date rules.
@param version: Version string to validate.
## Config Fields
calver.format: CalVerFormat = YYYY.MM.DD
calver.preventFutureDates: boolean = true
```
---
## Install
```bash
npm install ckm-sdk
```
One package. Library + CLI + TypeScript types. Powered by a Rust core via napi-rs.
---
## CLI Usage
The CLI is built into `ckm-sdk`. No separate package needed.
```bash
# Browse topics
npx ckm-sdk browse --file docs/ckm.json
npx ckm-sdk browse calver --file docs/ckm.json
npx ckm-sdk browse --json --file docs/ckm.json
# Validate a manifest
npx ckm-sdk validate docs/ckm.json
# Inspect manifest stats
npx ckm-sdk inspect docs/ckm.json
# Migrate v1 to v2
npx ckm-sdk migrate docs/ckm.json --dry-run
```
Also available as a native Rust binary: `cargo install ckm-cli`
---
## Consumer API (reading manifests)
For CLI tools that want to add `mytool ckm [topic]`:
```javascript
const { createCkmEngine } = require('ckm-sdk');
const fs = require('fs');
// Load ckm.json (generated by forge-ts or hand-authored)
const manifest = JSON.parse(fs.readFileSync('docs/ckm.json', 'utf-8'));
const engine = createCkmEngine(manifest);
// Progressive disclosure — 4 levels
engine.getTopicIndex('mytool') // Level 0: topic list (300 tokens)
engine.getTopicContent('calver') // Level 1: topic detail (800 tokens)
engine.getTopicJson('calver') // Level 1J: structured JSON (1200 tokens)
engine.getTopicJson() // Level 2: full index (3000 tokens)
// Metadata
engine.getManifest() // Raw v2 manifest
engine.inspect() // Counts and topic names
engine.topicsCount // Number of topics (property)
```
### Wire into Commander.js (3 lines + handler)
```javascript
const { createCkmEngine } = require('ckm-sdk');
const manifest = JSON.parse(fs.readFileSync('docs/ckm.json', 'utf-8'));
const engine = createCkmEngine(manifest);
program
.command('ckm [topic]')
.option('--json', 'Machine-readable output')
.action((topic, { json }) => {
if (json) console.log(JSON.stringify(engine.getTopicJson(topic), null, 2));
else if (topic) console.log(engine.getTopicContent(topic) || engine.getTopicIndex('mytool'));
else console.log(engine.getTopicIndex('mytool'));
});
```
This is exactly what VersionGuard does. It replaced 690 lines of handrolled code with a 3-line import.
---
## Producer API (building manifests)
For documentation generators that create `ckm.json`:
### TypeScript Types (compile-time contract)
```typescript
import type { CkmManifest, CkmConcept, CkmOperation, CkmTypeRef } from 'ckm-sdk';
```
15+ types exported. Your generator output is type-checked at compile time — no more `unknown[]` arrays.
### Manifest Builder (fluent API)
```javascript
const { createManifestBuilder, validateManifest } = require('ckm-sdk');
const builder = createManifestBuilder('my-tool', 'typescript')
.generator('my-generator@1.0.0')
.sourceUrl('https://github.com/org/repo')
.addConcept('CalVerConfig', 'calver', 'Configures CalVer.', ['config'])
.addConceptProperty('calver', 'format', 'string', 'Calendar format.', true, 'YYYY.MM.DD')
.addOperation('validate', 'Validates a CalVer string.', ['calver'])
.addOperationInput('validate', 'version', 'string', true, 'Version string.')
.addConstraint('No future dates', 'validate', 'error')
.addConfig('calver.format', 'string', 'Calendar format.', true, 'YYYY.MM.DD');
const manifest = builder.buildJson(); // Returns a typed CkmManifest object
// Always validate before writing
const result = validateManifest(manifest);
if (!result.valid) throw new Error(JSON.stringify(result.errors));
fs.writeFileSync('docs/ckm.json', JSON.stringify(manifest, null, 2));
```
### Other SDK Functions
```javascript
validateManifest(data) // Validate any manifest → { valid, errors[] }
migrateV1toV2(data) // Migrate v1 → v2 format
detectVersion(data) // Returns 1 or 2
```
All functions accept objects or JSON strings.
---
## Rust Consumer
```bash
cargo add ckm
```
```rust
use ckm::CkmEngine;
let data: serde_json::Value = serde_json::from_str(&manifest_json).unwrap();
let engine = CkmEngine::new(data);
println!("{}", engine.topic_index("mytool"));
if let Some(content) = engine.topic_content("calver") {
println!("{}", content);
}
```
The Rust crate IS the engine. Node.js calls into it via napi-rs. Same code, same behavior.
---
## Python Consumer
```bash
pip install ckm # (PyPI — coming soon, available via maturin develop)
```
```python
from ckm import create_engine
engine = create_engine(open('docs/ckm.json').read())
print(engine.get_topic_index('mytool'))
print(engine.get_topic_content('calver'))
```
Python wrapper calls the same Rust core via PyO3.
---
## The ckm.json Manifest
A `ckm.json` file captures five dimensions of CLI tool knowledge:
| Section | What it answers |
|---------|----------------|
| **concepts** | What domain objects does this tool have? |
| **operations** | What can I do with this tool? |
| **constraints** | What rules are enforced? |
| **workflows** | How do I accomplish multi-step goals? |
| **configSchema** | What config controls what behavior? |
### Generating ckm.json
**With [forge-ts](https://github.com/kryptobaseddev/forge-ts)** (for TypeScript projects):
```bash
npx forge-ts build # generates docs/ckm.json from TSDoc annotations
```
**With the builder** (for any generator):
```javascript
const { createManifestBuilder } = require('ckm-sdk');
const manifest = createManifestBuilder('my-tool', 'python')
.generator('my-docgen@1.0')
.addConcept('Config', 'config', 'Main configuration.', ['config'])
.buildJson();
```
**By hand** (for any language):
```json
{
"$schema": "https://ckm.dev/schemas/v2.json",
"version": "2.0.0",
"meta": { "project": "my-tool", "language": "typescript", "generator": "hand-authored", "generated": "2026-03-30T00:00:00Z" },
"concepts": [{ "id": "concept-config", "name": "Config", "slug": "config", "what": "Main configuration.", "tags": ["config"] }],
"operations": [],
"constraints": [],
"workflows": [],
"configSchema": []
}
```
### Topic Control
**Auto-derived (default):** Every concept with a non-empty `slug` becomes a browsable topic. Operations, constraints, and config are grouped by tag overlap and keyword matching.
**Producer-declared (full control):** Add a `topics` array to the manifest:
```json
{
"topics": [
{ "name": "getting-started", "summary": "First-time setup.", "conceptIds": ["concept-config"], "operationIds": ["op-init"] }
]
}
```
### Extensions
Every entity supports an `extensions` field for custom metadata:
```json
{
"id": "concept-config",
"name": "Config",
"slug": "config",
"what": "Main configuration.",
"tags": ["config"],
"extensions": { "myGenerator.sourceFile": "src/config.ts", "myGenerator.lineNumber": 42 }
}
```
CKM passes extensions through untouched. The schema stays strict; your tooling reads the custom data.
---
## Architecture: Rust Core SSoT
CKM is implemented **once in Rust** and exposed to every language through thin FFI wrappers:
```
ckm.json v2 (input)
│
▼
┌─────────────┐
│ rust-core │ ← THE implementation (types, engine, builder, migration, validation, formatting)
└──────┬──────┘
│
┌───┼───┬───────┐
│ │ │ │
▼ ▼ ▼ ▼
napi PyO3 CGo Direct
(npm) (PyPI)(Go) (Rust)
```
When the algorithm changes, it changes once in Rust. All languages follow. Zero drift by construction.
---
## Progressive Disclosure Protocol
| Level | Command | Audience | Token Budget |
|-------|---------|----------|-------------|
| 0 | `mytool ckm` | Human / Agent discovery | 300 |
| 1 | `mytool ckm calver` | Drill-down | 800 |
| 1J | `mytool ckm calver --json` | Agent structured | 1200 |
| 2 | `mytool ckm --json` | Agent full index | 3000 |
---
## Packages
| Package | Registry | Install |
|---------|----------|---------|
| `ckm-sdk` | npm | `npm install ckm-sdk` (library + CLI + types) |
| `ckm` | crates.io | `cargo add ckm` (Rust core) |
| `ckm-cli` | crates.io | `cargo install ckm-cli` (native binary) |
| `ckm` | PyPI | Coming soon (via PyO3 + Maturin) |
All packages use [CalVer](https://calver.org/) (YYYY.M.MICRO) versioning, enforced by [VersionGuard](https://github.com/kryptobaseddev/versionguard).
---
## Guides
- **[Producer Guide](docs/GUIDE-PRODUCER.md)** — how to generate `ckm.json` using the SDK (for forge-ts and other generators)
- **[Consumer Guide](docs/GUIDE-CONSUMER.md)** — how to add `ckm [topic]` to your CLI (for VersionGuard and other tools)
---
## Origin
CKM originated as a module inside [VersionGuard](https://github.com/kryptobaseddev/versionguard). After proving the concept — auto-derived topics, progressive disclosure for LLM agents, zero-config integration — it was extracted into a standalone SDK. forge-ts is the primary generator; any tool can produce a valid `ckm.json`.
## License
MIT