{"id":47787426,"url":"https://github.com/kryptobaseddev/ckm","last_synced_at":"2026-04-05T16:00:34.871Z","repository":{"id":348048469,"uuid":"1195643431","full_name":"kryptobaseddev/ckm","owner":"kryptobaseddev","description":"CKM — Codebase Knowledge Manifest SDK. Machine-readable operational knowledge for CLI tools. Rust core, Node.js/Python/Go wrappers.","archived":false,"fork":false,"pushed_at":"2026-03-30T19:01:20.000Z","size":338,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T17:40:37.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kryptobaseddev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-29T22:59:11.000Z","updated_at":"2026-03-30T19:01:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kryptobaseddev/ckm","commit_stats":null,"previous_names":["kryptobaseddev/ckm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kryptobaseddev/ckm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fckm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fckm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fckm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fckm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kryptobaseddev","download_url":"https://codeload.github.com/kryptobaseddev/ckm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Fckm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T14:56:35.299Z","updated_at":"2026-04-04T15:00:41.057Z","avatar_url":"https://github.com/kryptobaseddev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CKM — Codebase Knowledge Manifest\n\n**Machine-readable operational knowledge for CLI tools. Any language. Any framework. One implementation.**\n\n[![crates.io](https://img.shields.io/crates/v/ckm)](https://crates.io/crates/ckm)\n[![npm](https://img.shields.io/npm/v/ckm-sdk)](https://www.npmjs.com/package/ckm-sdk)\n[![license](https://img.shields.io/crates/l/ckm)](LICENSE)\n\n---\n\n## What is CKM?\n\nCKM 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.\n\nA `ckm.json` manifest captures structured knowledge about a CLI tool. The CKM SDK reads it and provides:\n\n- **Auto-derived topics** — every concept becomes browsable, zero manual mapping\n- **Progressive disclosure** — 4 levels from discovery to full API dump\n- **Human + machine output** — terminal text for humans, JSON for LLM agents\n- **Producer + consumer APIs** — build manifests with type safety, serve them with one import\n\n```\n$ mytool ckm calver\n\n# Configures CalVer validation rules.\n\n## Concepts\n\n  CalVerConfig — Configures CalVer validation rules.\n    format: CalVerFormat = YYYY.MM.DD\n    preventFutureDates: boolean = true\n\n## Operations\n\n  validate() — Validates a CalVer string against formatting and date rules.\n    @param version: Version string to validate.\n\n## Config Fields\n\n  calver.format: CalVerFormat = YYYY.MM.DD\n  calver.preventFutureDates: boolean = true\n```\n\n---\n\n## Install\n\n```bash\nnpm install ckm-sdk\n```\n\nOne package. Library + CLI + TypeScript types. Powered by a Rust core via napi-rs.\n\n---\n\n## CLI Usage\n\nThe CLI is built into `ckm-sdk`. No separate package needed.\n\n```bash\n# Browse topics\nnpx ckm-sdk browse --file docs/ckm.json\nnpx ckm-sdk browse calver --file docs/ckm.json\nnpx ckm-sdk browse --json --file docs/ckm.json\n\n# Validate a manifest\nnpx ckm-sdk validate docs/ckm.json\n\n# Inspect manifest stats\nnpx ckm-sdk inspect docs/ckm.json\n\n# Migrate v1 to v2\nnpx ckm-sdk migrate docs/ckm.json --dry-run\n```\n\nAlso available as a native Rust binary: `cargo install ckm-cli`\n\n---\n\n## Consumer API (reading manifests)\n\nFor CLI tools that want to add `mytool ckm [topic]`:\n\n```javascript\nconst { createCkmEngine } = require('ckm-sdk');\nconst fs = require('fs');\n\n// Load ckm.json (generated by forge-ts or hand-authored)\nconst manifest = JSON.parse(fs.readFileSync('docs/ckm.json', 'utf-8'));\nconst engine = createCkmEngine(manifest);\n\n// Progressive disclosure — 4 levels\nengine.getTopicIndex('mytool')        // Level 0: topic list (300 tokens)\nengine.getTopicContent('calver')      // Level 1: topic detail (800 tokens)\nengine.getTopicJson('calver')         // Level 1J: structured JSON (1200 tokens)\nengine.getTopicJson()                 // Level 2: full index (3000 tokens)\n\n// Metadata\nengine.getManifest()                  // Raw v2 manifest\nengine.inspect()                      // Counts and topic names\nengine.topicsCount                    // Number of topics (property)\n```\n\n### Wire into Commander.js (3 lines + handler)\n\n```javascript\nconst { createCkmEngine } = require('ckm-sdk');\nconst manifest = JSON.parse(fs.readFileSync('docs/ckm.json', 'utf-8'));\nconst engine = createCkmEngine(manifest);\n\nprogram\n  .command('ckm [topic]')\n  .option('--json', 'Machine-readable output')\n  .action((topic, { json }) =\u003e {\n    if (json) console.log(JSON.stringify(engine.getTopicJson(topic), null, 2));\n    else if (topic) console.log(engine.getTopicContent(topic) || engine.getTopicIndex('mytool'));\n    else console.log(engine.getTopicIndex('mytool'));\n  });\n```\n\nThis is exactly what VersionGuard does. It replaced 690 lines of handrolled code with a 3-line import.\n\n---\n\n## Producer API (building manifests)\n\nFor documentation generators that create `ckm.json`:\n\n### TypeScript Types (compile-time contract)\n\n```typescript\nimport type { CkmManifest, CkmConcept, CkmOperation, CkmTypeRef } from 'ckm-sdk';\n```\n\n15+ types exported. Your generator output is type-checked at compile time — no more `unknown[]` arrays.\n\n### Manifest Builder (fluent API)\n\n```javascript\nconst { createManifestBuilder, validateManifest } = require('ckm-sdk');\n\nconst builder = createManifestBuilder('my-tool', 'typescript')\n  .generator('my-generator@1.0.0')\n  .sourceUrl('https://github.com/org/repo')\n  .addConcept('CalVerConfig', 'calver', 'Configures CalVer.', ['config'])\n  .addConceptProperty('calver', 'format', 'string', 'Calendar format.', true, 'YYYY.MM.DD')\n  .addOperation('validate', 'Validates a CalVer string.', ['calver'])\n  .addOperationInput('validate', 'version', 'string', true, 'Version string.')\n  .addConstraint('No future dates', 'validate', 'error')\n  .addConfig('calver.format', 'string', 'Calendar format.', true, 'YYYY.MM.DD');\n\nconst manifest = builder.buildJson();  // Returns a typed CkmManifest object\n\n// Always validate before writing\nconst result = validateManifest(manifest);\nif (!result.valid) throw new Error(JSON.stringify(result.errors));\n\nfs.writeFileSync('docs/ckm.json', JSON.stringify(manifest, null, 2));\n```\n\n### Other SDK Functions\n\n```javascript\nvalidateManifest(data)    // Validate any manifest → { valid, errors[] }\nmigrateV1toV2(data)       // Migrate v1 → v2 format\ndetectVersion(data)       // Returns 1 or 2\n```\n\nAll functions accept objects or JSON strings.\n\n---\n\n## Rust Consumer\n\n```bash\ncargo add ckm\n```\n\n```rust\nuse ckm::CkmEngine;\n\nlet data: serde_json::Value = serde_json::from_str(\u0026manifest_json).unwrap();\nlet engine = CkmEngine::new(data);\n\nprintln!(\"{}\", engine.topic_index(\"mytool\"));\nif let Some(content) = engine.topic_content(\"calver\") {\n    println!(\"{}\", content);\n}\n```\n\nThe Rust crate IS the engine. Node.js calls into it via napi-rs. Same code, same behavior.\n\n---\n\n## Python Consumer\n\n```bash\npip install ckm  # (PyPI — coming soon, available via maturin develop)\n```\n\n```python\nfrom ckm import create_engine\n\nengine = create_engine(open('docs/ckm.json').read())\nprint(engine.get_topic_index('mytool'))\nprint(engine.get_topic_content('calver'))\n```\n\nPython wrapper calls the same Rust core via PyO3.\n\n---\n\n## The ckm.json Manifest\n\nA `ckm.json` file captures five dimensions of CLI tool knowledge:\n\n| Section | What it answers |\n|---------|----------------|\n| **concepts** | What domain objects does this tool have? |\n| **operations** | What can I do with this tool? |\n| **constraints** | What rules are enforced? |\n| **workflows** | How do I accomplish multi-step goals? |\n| **configSchema** | What config controls what behavior? |\n\n### Generating ckm.json\n\n**With [forge-ts](https://github.com/kryptobaseddev/forge-ts)** (for TypeScript projects):\n\n```bash\nnpx forge-ts build  # generates docs/ckm.json from TSDoc annotations\n```\n\n**With the builder** (for any generator):\n\n```javascript\nconst { createManifestBuilder } = require('ckm-sdk');\nconst manifest = createManifestBuilder('my-tool', 'python')\n  .generator('my-docgen@1.0')\n  .addConcept('Config', 'config', 'Main configuration.', ['config'])\n  .buildJson();\n```\n\n**By hand** (for any language):\n\n```json\n{\n  \"$schema\": \"https://ckm.dev/schemas/v2.json\",\n  \"version\": \"2.0.0\",\n  \"meta\": { \"project\": \"my-tool\", \"language\": \"typescript\", \"generator\": \"hand-authored\", \"generated\": \"2026-03-30T00:00:00Z\" },\n  \"concepts\": [{ \"id\": \"concept-config\", \"name\": \"Config\", \"slug\": \"config\", \"what\": \"Main configuration.\", \"tags\": [\"config\"] }],\n  \"operations\": [],\n  \"constraints\": [],\n  \"workflows\": [],\n  \"configSchema\": []\n}\n```\n\n### Topic Control\n\n**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.\n\n**Producer-declared (full control):** Add a `topics` array to the manifest:\n\n```json\n{\n  \"topics\": [\n    { \"name\": \"getting-started\", \"summary\": \"First-time setup.\", \"conceptIds\": [\"concept-config\"], \"operationIds\": [\"op-init\"] }\n  ]\n}\n```\n\n### Extensions\n\nEvery entity supports an `extensions` field for custom metadata:\n\n```json\n{\n  \"id\": \"concept-config\",\n  \"name\": \"Config\",\n  \"slug\": \"config\",\n  \"what\": \"Main configuration.\",\n  \"tags\": [\"config\"],\n  \"extensions\": { \"myGenerator.sourceFile\": \"src/config.ts\", \"myGenerator.lineNumber\": 42 }\n}\n```\n\nCKM passes extensions through untouched. The schema stays strict; your tooling reads the custom data.\n\n---\n\n## Architecture: Rust Core SSoT\n\nCKM is implemented **once in Rust** and exposed to every language through thin FFI wrappers:\n\n```\nckm.json v2 (input)\n      │\n      ▼\n┌─────────────┐\n│  rust-core  │ ← THE implementation (types, engine, builder, migration, validation, formatting)\n└──────┬──────┘\n       │\n   ┌───┼───┬───────┐\n   │   │   │       │\n   ▼   ▼   ▼       ▼\n napi  PyO3 CGo   Direct\n (npm) (PyPI)(Go) (Rust)\n```\n\nWhen the algorithm changes, it changes once in Rust. All languages follow. Zero drift by construction.\n\n---\n\n## Progressive Disclosure Protocol\n\n| Level | Command | Audience | Token Budget |\n|-------|---------|----------|-------------|\n| 0 | `mytool ckm` | Human / Agent discovery | 300 |\n| 1 | `mytool ckm calver` | Drill-down | 800 |\n| 1J | `mytool ckm calver --json` | Agent structured | 1200 |\n| 2 | `mytool ckm --json` | Agent full index | 3000 |\n\n---\n\n## Packages\n\n| Package | Registry | Install |\n|---------|----------|---------|\n| `ckm-sdk` | npm | `npm install ckm-sdk` (library + CLI + types) |\n| `ckm` | crates.io | `cargo add ckm` (Rust core) |\n| `ckm-cli` | crates.io | `cargo install ckm-cli` (native binary) |\n| `ckm` | PyPI | Coming soon (via PyO3 + Maturin) |\n\nAll packages use [CalVer](https://calver.org/) (YYYY.M.MICRO) versioning, enforced by [VersionGuard](https://github.com/kryptobaseddev/versionguard).\n\n---\n\n## Guides\n\n- **[Producer Guide](docs/GUIDE-PRODUCER.md)** — how to generate `ckm.json` using the SDK (for forge-ts and other generators)\n- **[Consumer Guide](docs/GUIDE-CONSUMER.md)** — how to add `ckm [topic]` to your CLI (for VersionGuard and other tools)\n\n---\n\n## Origin\n\nCKM 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`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptobaseddev%2Fckm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkryptobaseddev%2Fckm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptobaseddev%2Fckm/lists"}