@knolo/cli 4.0.0 → 5.1.0

package/README.md

@@ -1,7 +1,9 @@
 # @knolo/cli
 
-The CLI targets the Knolo v4 pack contract. Normal builds emit v4; the ICP
-legacy build path explicitly emits v3 until the canister gains a v4 profile.
+The CLI preserves the Knolo V4 pack workflow and adds read-only V5 Knowledge
+Image inspection. Normal builds emit V4; the ICP legacy build path explicitly
+emits V3 until the canister gains a V4 profile. V5 Studio output is a verified
+management snapshot, not a mutation interface.
 
 The official CLI for building `.knolo` knowledge packs.
 
@@ -50,6 +52,20 @@ knolo explain receipt.json --pack dist/knowledge.knolo
 knolo diff old.knolo new.knolo
 ```
 
+V5 runtime diagnostics:
+
+```bash
+knolo v5 info ./dist/knowledge.v5
+knolo v5 health ./dist/knowledge.v5
+knolo v5 studio ./dist/knowledge.v5
+knolo v5 info ./dist/knowledge.v5 --index ./dist/query-index.v5 --history ./dist/query-history.v5
+```
+
+These commands verify the V5 image and optional state-root-bound runtime
+artifacts before printing deterministic diagnostics. The `studio` variant
+prints the KIP-0026 read-only management snapshot with artifact-panel
+availability and a management root. All variants are read-only.
+
 ### ICP Canister Workflow (LIVE)
 
 Deploy a Knolo knowledge canister on a local ICP replica, upload a `.knolo` pack, and query it with no middleware.
@@ -152,10 +168,9 @@ This ensures:
 
 ## 🗺 Roadmap
 
-* Watch mode
-* Incremental indexing
-* Rust-powered build engine
-* WASM build output
+The active roadmap is maintained in [`../../docs/ROADMAP.md`](../../docs/ROADMAP.md).
+The current release focuses on V5 verification, migration, diagnostics, and
+read-only Studio management while preserving the V4 CLI behavior.
 
 ---
 

package/bin/knolo.mjs

@@ -33,7 +33,7 @@ const DEFAULT_CONFIG = {
 };
 const SUPPORTED_EXTENSIONS = new Set(['.md', '.txt', '.json']);
 const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', '.dfx', '.cargo-target']);
-const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'inspect', 'migrate', 'verify', 'explain', 'diff', 'dev', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
+const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'inspect', 'migrate', 'verify', 'explain', 'diff', 'dev', 'v5', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
 const ICP_SUBCOMMANDS = new Set(['init', 'build-pack', 'upload', 'query', 'health', 'info', 'clear']);
 const ICP_TEMPLATE_CANDIDATES = [
   path.resolve(__dirname, '../templates/icp-knowledge-canister'),
@@ -88,6 +88,7 @@ Commands:
   explain <receipt>       Verify and explain a query receipt
   diff <pack-a> <pack-b>  Compare pack identities and source/chunk counts
   dev                     Watch config/sources and rebuild on change
+  v5                      Inspect, health-check, and manage a V5 Knowledge Image
   icp                     Scaffold and operate an ICP-native knowledge canister
 
 Global options:
@@ -109,6 +110,7 @@ function printCommandHelp(command) {
     explain: 'Usage: knolo explain <receipt.json> --pack <pack.knolo>',
     diff: 'Usage: knolo diff <pack-a.knolo> <pack-b.knolo>',
     dev: 'Usage: knolo dev',
+    v5: 'Usage: knolo v5 <info|health|studio> <image.v5> [--index <file>] [--history <file>] [--run <file>] [--replay <file>]',
     icp: 'Usage: knolo icp <command> [options]',
     'semantic:index': 'Usage: knolo semantic:index --pack <path> [--out <path>] [--model <id>] [--endpoint <url>]',
     'semantic:inspect': 'Usage: knolo semantic:inspect --sidecar <path>',
@@ -773,6 +775,41 @@ async function cmdDiff(core, args) {
   console.log(JSON.stringify({ equal: aDigest === bDigest, a: { packDigest: aDigest, blocks: a.pack.blocks.length, terms: a.pack.lexicon.size }, b: { packDigest: bDigest, blocks: b.pack.blocks.length, terms: b.pack.lexicon.size }, addedSources: [...bSources].filter((id) => !aSources.has(id)).sort(), removedSources: [...aSources].filter((id) => !bSources.has(id)).sort() }, null, 2));
 }
 
+function parseV5Args(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--image' || arg === '--index' || arg === '--history' || arg === '--run' || arg === '--replay') flags[arg.slice(2)] = args[++i];
+    else if (arg.startsWith('--')) throw createError(`Unknown flag for v5: ${arg}`);
+    else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+async function cmdV5(core, args) {
+  const subcommand = args[0] || 'info';
+  if (!['info', 'health', 'studio'].includes(subcommand)) throw createError(`Unknown V5 command: ${subcommand}`);
+  const { positional, flags } = parseV5Args(args.slice(['info', 'health', 'studio'].includes(args[0]) ? 1 : 0));
+  const imagePath = path.resolve(process.cwd(), flags.image || positional[0] || 'dist/knowledge.v5');
+  if (!existsSync(imagePath)) throw createError(`V5 image file not found at ${path.relative(process.cwd(), imagePath)}.`);
+  const readOptional = (file, decode) => file ? decode(Uint8Array.from(readFileSync(path.resolve(process.cwd(), file)))) : undefined;
+  const input = {
+    image: Uint8Array.from(readFileSync(imagePath)),
+    ...(flags.index ? { queryIndex: readOptional(flags.index, core.deserializeKnowledgeQueryIndexV1) } : {}),
+    ...(flags.history ? { queryHistory: readOptional(flags.history, core.deserializeKnowledgeQueryHistoryV1) } : {}),
+    ...(flags.run ? { run: readOptional(flags.run, core.deserializeKnowledgeRunV1) } : {}),
+    ...(flags.replay ? { replayState: readOptional(flags.replay, core.deserializeKnowledgeSyncReplayStateV1) } : {}),
+  };
+  if (subcommand === 'studio') {
+    console.log(JSON.stringify(core.inspectKnowledgeStudioManagementV5(input), null, 2));
+    return;
+  }
+  const diagnostics = core.inspectKnowledgeRuntimeV5(input);
+  if (subcommand === 'health') console.log(JSON.stringify({ healthy: true, ...diagnostics }, null, 2));
+  else console.log(JSON.stringify(diagnostics, null, 2));
+}
+
 function parseKeyValueArgs(args) {
   const out = {};
   for (let i = 0; i < args.length; i++) {
@@ -1142,6 +1179,7 @@ async function main() {
       if (command === 'explain') return await cmdExplain(core, commandArgs);
       if (command === 'diff') return await cmdDiff(core, commandArgs);
       if (command === 'dev') return await cmdDev(core);
+      if (command === 'v5') return await cmdV5(core, commandArgs);
       if (command === 'semantic:index') return await cmdSemanticIndex(core, commandArgs);
       if (command === 'semantic:inspect') return await cmdSemanticInspect(core, commandArgs);
       if (command === 'semantic:validate') return await cmdSemanticValidate(core, commandArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/cli",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
@@ -9,12 +9,29 @@
     "bin/",
     "templates/"
   ],
+  "description": "CLI for building, inspecting, verifying, and operating Knolo V4 packs and V5 Knowledge Images.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HiveForensics-AI/knolo-core.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/HiveForensics-AI/knolo-core#readme",
+  "bugs": {
+    "url": "https://github.com/HiveForensics-AI/knolo-core/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "node -e \"console.log('cli is executable via bin/knolo.mjs')\"",
     "test": "npm run build --prefix ../core && node --test test/cli.test.mjs"
   },
   "dependencies": {
-    "@knolo/core": "^4.0.0"
+    "@knolo/core": "^5.1.0"
   },
   "private": false
 }

package/templates/icp-knowledge-canister/README.md

@@ -2,6 +2,11 @@
 
 Minimal local `dfx` example for deploying a Knolo ICP canister without any middleware server.
 
+This scaffold remains on the legacy ICP V3 profile. The V5 foundation is
+available in the TypeScript/Rust runtimes and through the root CLI’s read-only
+Knowledge Image commands; see the repository `docs/ROADMAP.md` for the staged
+ICP upgrade path.
+
 This scaffold:
 
 - builds a real `.knolo` pack from local sample docs

package/templates/icp-knowledge-canister/canisters/knolo-core-rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "knolo-core-rust"
-version = "4.0.0"
+version = "5.1.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "Rust runtime support for reading and querying .knolo packs"