@aikdna/kdna-cli 0.25.1 → 0.26.0

package/README.md

@@ -11,6 +11,11 @@ handled by KDNA Studio CLI and Studio Core.
 KDNA Core v1 does not require a public registry, marketplace, quality badge, or
 signature system. The current first-run path uses local `.kdna` files.
 
+Authorization and runtime-load decisions are defined in `aikdna/kdna`, not in
+this repository. `kdna plan-load` is the CLI diagnostic surface for that
+contract and MUST call the LoadPlan API from `@aikdna/kdna-core` instead of
+deriving authorization state directly from manifest fields.
+
 ## Install
 
 ```bash
@@ -23,6 +28,7 @@ npm install -g @aikdna/kdna-cli
 kdna demo minimal ./minimal
 kdna inspect ./minimal
 kdna validate ./minimal
+kdna plan-load ./minimal --json
 kdna pack ./minimal ./minimal.kdna
 kdna validate ./minimal.kdna
 kdna load ./minimal.kdna --profile=compact --as=prompt
@@ -49,6 +55,9 @@ Successful validation returns:
 | `kdna demo minimal <dir>` | Create a minimal v1 source directory |
 | `kdna inspect <path>` | Inspect a v1 source dir or `.kdna` container |
 | `kdna validate <path>` | Validate format, schema, payload, checksums, and load contract |
+| `kdna plan-load <path> --json` | Return the Core LoadPlan before runtime load |
+| `kdna plan-load <path> --json --has-password` | Diagnose password-authorized load state |
+| `kdna plan-load <path> --json --entitlement-status active` | Diagnose receipt/entitlement load state |
 | `kdna pack <source-dir> <output.kdna>` | Pack a v1 source directory |
 | `kdna unpack <input.kdna> <output-dir>` | Unpack a v1 container |
 | `kdna load <path> --profile=<index|compact|scenario|full> --as=<json|prompt>` | Render judgment context for agents or tools |
@@ -79,10 +88,38 @@ New integrations should use the v1 Core route:
 source or Studio project
 → v1 .kdna container
 → kdna validate
+→ kdna plan-load
 → kdna load
 → agent/runtime context
 ```
 
+## Runtime Authorization Contract
+
+The source of truth is `aikdna/kdna`:
+
+- `specs/kdna-authorization-contract.md`
+- `schema/load-plan.schema.json`
+- `conformance/authorization/cases.json`
+- `conformance/authorization/goldens/*.loadplan.json`
+
+This CLI is a diagnostic control plane. It may display, validate, and transport
+LoadPlan results, but it must not define access modes, entitlement profiles,
+issue codes, crypto profiles, or fail-closed policy independently.
+
+Current local authorization path:
+
+```bash
+kdna validate ./asset.kdna --json
+kdna plan-load ./asset.kdna --json
+kdna plan-load ./asset.kdna --json --has-password
+kdna plan-load ./asset.kdna --json --entitlement-status active
+kdna load ./asset.kdna --profile=compact --as=prompt
+```
+
+`plan-load` requires a version of `@aikdna/kdna-core` that exports the LoadPlan
+v1 API. Until that dependency is released and installed, the command fails with
+a version-gate error instead of falling back to duplicated CLI-side parsing.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "KDNA CLI — runtime control plane for verifying, installing, loading, comparing, publishing, and auditing existing .kdna assets.",
   "type": "commonjs",
   "bin": {
@@ -55,7 +55,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-core": "^0.11.0"
+    "@aikdna/kdna-core": "^0.12.0"
   },
   "optionalDependencies": {
     "ajv": "^8.20.0",

package/src/cli.js

@@ -89,6 +89,8 @@ Start here:
 Core v1:
   inspect  <path>                   Inspect v1 source dir or .kdna container
   validate <path>                   Validate v1 source dir or .kdna container
+  plan-load <path>                  Return a LoadPlan before runtime load
+                                  Add --has-password or --entitlement-status for diagnostics
   pack     <src> <out>              Deterministic pack into .kdna container
   unpack   <in>  <out>              Extract .kdna container
 
@@ -109,6 +111,8 @@ function showHelpAdvanced() {
 Core v1:
   inspect  <path>                   Inspect v1 source dir or .kdna container
   validate <path>                   Validate v1 source dir or .kdna container
+  plan-load <path> [--has-password] [--entitlement-status <status>]
+                                  Return a LoadPlan before runtime load
   pack     <src> <out>              Deterministic pack into .kdna container
   unpack   <in>  <out>              Extract .kdna container
   demo     minimal <dir> [--force]  Create a minimal v1 fixture
@@ -271,6 +275,33 @@ switch (cmd) {
     );
     break;
   }
+  case 'plan-load': {
+    const v1Target = args.filter((a) => !a.startsWith('--'))[1];
+    if (!v1Target) error('Usage: kdna plan-load <path> [--json] [--has-password] [--entitlement-status <status>]', EXIT.INPUT_ERROR);
+    const core = require('@aikdna/kdna-core');
+    const abs = require('node:path').resolve(v1Target);
+    if (!(core.isV1SourceDir(abs) || core.detectContainerFormat(abs) === 'v1')) {
+      error('plan-load requires a KDNA Core v1 source dir or .kdna container', EXIT.INPUT_ERROR);
+    }
+    if (typeof core.planLoad !== 'function') {
+      error(
+        'kdna plan-load requires @aikdna/kdna-core with the LoadPlan v1 API. Update @aikdna/kdna-core before enabling runtime authorization diagnostics.',
+        EXIT.PROVIDER_ERROR,
+      );
+    }
+    const entitlementStatusIndex = args.indexOf('--entitlement-status');
+    const entitlementStatus = entitlementStatusIndex >= 0 ? args[entitlementStatusIndex + 1] : null;
+    const allowedEntitlementStatuses = new Set(['active', 'expired', 'revoked', 'offline_grace']);
+    if (entitlementStatusIndex >= 0 && !allowedEntitlementStatuses.has(entitlementStatus)) {
+      error('Invalid --entitlement-status. Use active, expired, revoked, or offline_grace.', EXIT.INPUT_ERROR);
+    }
+    const plan = core.planLoad(v1Target, {
+      hasPassword: args.includes('--has-password'),
+      entitlement: entitlementStatus ? { status: entitlementStatus } : undefined,
+    });
+    console.log(JSON.stringify(plan, null, 2));
+    process.exit(plan.state === 'invalid' ? 1 : 0);
+  }
   case 'pack': {
     const v1Target = args.filter((a) => !a.startsWith('--'))[1];
     if (v1Target) {