@kanonak-protocol/cli 6.0.1 → 6.1.0

package/dist/utils/parsePackageRef.d.ts

@@ -8,10 +8,8 @@
  *   publisher/package/instance
  *   publisher/package@version/instance
  *
- * The optional `instanceName` selects a specific named entity inside
- * the package (e.g. one Skill out of several). When omitted, callers
- * that act on instances (like `kanonak skill add`) operate on every
- * instance of the relevant type.
+ * The optional `instanceName` names one entity inside the package.
+ * `kanonak install` works on whole packages and rejects it with a hint.
  */
 export interface PackageRef {
     publisher: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanonak-protocol/cli",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Command-line tool for the Kanonak Protocol — validate, resolve, preview, and publish semantic ontology packages.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,15 +35,15 @@
     "semantic-web"
   ],
   "dependencies": {
-    "@kanonak-protocol/sdk": "^6.0.1",
-    "@kanonak-protocol/types": "^6.0.1",
-    "commander": "^13.0.0",
-    "js-yaml": "^4.1.1"
+    "@kanonak-protocol/sdk": "^6.1.0",
+    "@kanonak-protocol/types": "^6.1.0",
+    "commander": "^13.0.0"
   },
   "devDependencies": {
     "@kanonak-protocol/expression": "^1.1.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.0.0",
+    "js-yaml": "^4.1.1",
     "rimraf": "^5.0.0",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",

package/dist/agents/AgentDeploymentHandler.d.ts

@@ -1,19 +0,0 @@
-import type { DeploymentContext, DeploymentHandler, DeployedInstance, OperationContext } from '../capabilities/DeploymentHandlerRegistry.js';
-/**
- * Deployment handler for the `AgentInstanceDeployment` DeploymentTarget.
- *
- * Transforms `kanonak.org/agents/Agent` instances into the target
- * client's on-disk file format (markdown-with-frontmatter for
- * Claude Code and Gemini CLI, TOML for Codex) and writes each one
- * into the directory declared by the named Client instance selected
- * via the `--client` option (defaulting to the "agents"
- * cross-client layout).
- */
-export declare class AgentDeploymentHandler implements DeploymentHandler {
-    private readonly parser;
-    private readonly objectParser;
-    private readonly runner;
-    deploy(context: DeploymentContext): Promise<void>;
-    undeploy(name: string, context: OperationContext): Promise<void>;
-    list(context: OperationContext): Promise<DeployedInstance[]>;
-}

package/dist/agents/AgentLock.d.ts

@@ -1,15 +0,0 @@
-export interface AgentLockEntry {
-    publisher: string;
-    package_: string;
-    version: string;
-    resolved: string;
-    integrity: string;
-    fileName: string;
-}
-export interface AgentLockFile {
-    version: string;
-    lastUpdated: string;
-    agents: Record<string, AgentLockEntry>;
-}
-export declare function loadAgentLock(agentsDir: string): AgentLockFile;
-export declare function saveAgentLock(agentsDir: string, lock: AgentLockFile): void;

package/dist/agents/AgentPaths.d.ts

@@ -1,23 +0,0 @@
-import type { IKanonakDocumentRepository } from '@kanonak-protocol/sdk';
-export type AgentFileFormat = 'markdown-frontmatter' | 'toml';
-export interface AgentPathOptions {
-    client?: string;
-    scope?: string;
-}
-export interface ResolvedAgentDeployment {
-    agentsDir: string;
-    format: AgentFileFormat;
-    fileExtension: string;
-}
-export declare function detectClient(): string | undefined;
-/**
- * Resolve the agent deployment settings for the requested client
- * and scope: the target directory plus the on-disk format to write.
- *
- * Goes through the SDK object model: agent-skills is parsed, Client
- * instances are looked up by clientId, the selected Client's
- * projectAgentDir / userAgentDir and agentFileFormat are read, and
- * the AgentFileFormat reference is followed to extract the local
- * name (markdown-frontmatter / toml).
- */
-export declare function resolveAgentDeployment(options: AgentPathOptions, repository: IKanonakDocumentRepository): Promise<ResolvedAgentDeployment>;

package/dist/capabilities/CapabilityLoader.d.ts

@@ -1,61 +0,0 @@
-import { KanonakParser } from '@kanonak-protocol/sdk';
-import type { IKanonakDocumentRepository } from '@kanonak-protocol/sdk';
-import { FileCache } from '../cache/FileCache.js';
-import { EntityUri } from '@kanonak-protocol/sdk/uri-helpers';
-/**
- * Canonical URIs from the kanonak.org/capabilities ontology that the CLI
- * dispatches against. Version is intentionally omitted from matching so
- * the CLI accepts any backwards-compatible minor version.
- */
-export declare const CAPABILITIES_PUB = "kanonak.org";
-export declare const CAPABILITIES_PKG = "capabilities";
-export declare const CAPABILITY_CLASS_URI: EntityUri;
-/**
- * A loaded command argument definition.
- */
-export interface LoadedArgument {
-    argumentName: string;
-    required: boolean;
-    isOption: boolean;
-    defaultValue?: string;
-}
-/**
- * A loaded subcommand definition. `actionKey` is the canonical URI of
- * the Action this subcommand performs, formatted as
- * `publisher/package/name` (version omitted). The command registrar
- * dispatches by this key.
- */
-export interface LoadedCommand {
-    subcommandName: string;
-    description: string;
-    arguments: LoadedArgument[];
-    actionKey: string;
-}
-/**
- * A fully loaded capability with its command structure.
- * All identifier fields are canonical URI keys — not local names.
- */
-export interface LoadedCapability {
-    commandName: string;
-    description: string;
-    managesTypeKey: string;
-    deploymentTargetKey: string;
-    commands: LoadedCommand[];
-    publisher: string;
-    package_: string;
-    version: string;
-}
-/**
- * Load all installed capabilities from the capability store.
- *
- * Reads `capabilities.lock`, looks up each capability's cached
- * document, parses it through `KanonakObjectParser.parseKanonaks`
- * against a `SingleDocumentRepository` that delegates import
- * resolution to the given broader repo, then walks the resulting
- * `SubjectKanonak.statement[]` tree to extract the Capability
- * instance and its subcommands.
- *
- * Every identifier returned is a canonical URI key — alias handling
- * happens inside the SDK, never in this file.
- */
-export declare function loadInstalledCapabilities(fileCache: FileCache, parser: KanonakParser, repository: IKanonakDocumentRepository): Promise<LoadedCapability[]>;

package/dist/capabilities/CapabilityStore.d.ts

@@ -1,30 +0,0 @@
-/**
- * Entry in the capabilities lock file tracking an installed capability.
- */
-export interface CapabilityStoreEntry {
-    publisher: string;
-    package_: string;
-    version: string;
-    resolved: string;
-    integrity: string;
-}
-/**
- * The capabilities lock file structure.
- */
-export interface CapabilityStoreFile {
-    version: string;
-    lastUpdated: string;
-    capabilities: Record<string, CapabilityStoreEntry>;
-}
-/**
- * Get the path to the global capabilities lock file.
- */
-export declare function getCapabilityStorePath(): string;
-/**
- * Load the capabilities lock file.
- */
-export declare function loadCapabilityStore(): CapabilityStoreFile;
-/**
- * Save the capabilities lock file.
- */
-export declare function saveCapabilityStore(store: CapabilityStoreFile): void;

package/dist/capabilities/CommandRegistrar.d.ts

@@ -1,12 +0,0 @@
-import { Command } from 'commander';
-import type { LoadedCapability } from './CapabilityLoader.js';
-import type { GenericCapabilityHandler } from './GenericCapabilityHandler.js';
-/**
- * Register Commander.js commands dynamically from loaded capability
- * definitions. For each installed capability, create a command group
- * named after its `commandName` property and attach each subcommand
- * with its declared positional and option arguments. All routing is
- * done through the Action URI each subcommand's `performs:` resolves
- * to.
- */
-export declare function registerCapabilityCommands(program: Command, capabilities: LoadedCapability[], handler: GenericCapabilityHandler): void;

package/dist/capabilities/DeploymentHandlerRegistry.d.ts

@@ -1,69 +0,0 @@
-import type { IKanonakDocumentRepository, SubjectKanonak, Kanonak } from '@kanonak-protocol/sdk';
-/**
- * Information about a deployed instance.
- */
-export interface DeployedInstance {
-    name: string;
-    publisher: string;
-    package_: string;
-    version: string;
-    path: string;
-}
-/**
- * Context passed to a deployment handler for a `deploy` call.
- *
- * `instances` is the list of `SubjectKanonak`s (each one is an
- * instance of the capability's `managesType`) to deploy. `allKanonaks`
- * is the full parsed kanonak list from the source document — handlers
- * use it to follow references (e.g. a skill's `license` reference to
- * the actual `License` subject for its `spdxId`).
- *
- * `repository` is the broader repository (local cache + HTTP) that the
- * handler can use to fetch entities from other packages when needed
- * (e.g. a `Tool` instance or `Client` instance defined in
- * `agent-skills`).
- */
-export interface DeploymentContext {
-    instances: SubjectKanonak[];
-    allKanonaks: Kanonak[];
-    repository: IKanonakDocumentRepository;
-    options: Record<string, string>;
-}
-/**
- * Context passed to a deployment handler for lifecycle operations
- * that are NOT about deploying a fresh instance (undeploy, list).
- * Carries the broader repository so handlers can still resolve
- * ontology entities like `Client` for per-product skill paths.
- */
-export interface OperationContext {
-    repository: IKanonakDocumentRepository;
-    options: Record<string, string>;
-}
-/**
- * Handler that deploys/undeploys instances of a managed type to the
- * local system.
- *
- * Each `DeploymentTarget` instance in the `kanonak.org/capabilities`
- * ontology has a matching handler in the `DeploymentHandlerRegistry`,
- * keyed by the target's canonical URI string
- * (`{publisher}/{package}/{name}`).
- */
-export interface DeploymentHandler {
-    deploy(context: DeploymentContext): Promise<void>;
-    undeploy(name: string, context: OperationContext): Promise<void>;
-    list(context: OperationContext): Promise<DeployedInstance[]>;
-}
-/**
- * Registry that maps a DeploymentTarget URI key to its handler.
- *
- * The URI key is the canonical `{publisher}/{package}/{name}` string
- * of a named DeploymentTarget instance (e.g.
- * `kanonak.org/capabilities/AgentSkillDeployment`). Version is not
- * part of the key: new compatible versions of the ontology continue
- * to dispatch to the same handler.
- */
-export declare class DeploymentHandlerRegistry {
-    private readonly handlers;
-    register(targetUriKey: string, handler: DeploymentHandler): void;
-    get(targetUriKey: string): DeploymentHandler | null;
-}

package/dist/capabilities/GenericCapabilityHandler.d.ts

@@ -1,87 +0,0 @@
-import { KanonakParser, PublisherIndex } from '@kanonak-protocol/sdk';
-import type { AuthenticatedFetchFn, IKanonakDocumentRepository } from '@kanonak-protocol/sdk';
-import { FileCache } from '../cache/FileCache.js';
-import type { LoadedCapability } from './CapabilityLoader.js';
-import type { DeploymentHandlerRegistry } from './DeploymentHandlerRegistry.js';
-/**
- * Generic command handler that implements the standard Action set
- * (fetchAndDeploy, removeDeployed, listDeployed, updateDeployed,
- * searchAvailable, showInfo) in a type-agnostic way.
- *
- * The handler is parameterized by the LoadedCapability — specifically
- * its URI-keyed `managesTypeKey` and `deploymentTargetKey` — so the
- * same implementation supports any capability whose ontology resolves
- * cleanly through the SDK object model.
- */
-export declare class GenericCapabilityHandler {
-    private readonly fileCache;
-    private readonly parser;
-    private readonly publisherIndex;
-    private readonly fetchFn;
-    private readonly handlerRegistry;
-    private readonly repository;
-    private readonly objectParser;
-    constructor(fileCache: FileCache, parser: KanonakParser, publisherIndex: PublisherIndex, fetchFn: AuthenticatedFetchFn, handlerRegistry: DeploymentHandlerRegistry, repository: IKanonakDocumentRepository);
-    /**
-     * Fetch a package and deploy instances of the capability's managed
-     * type. If the parsed reference includes an `instanceName`, only
-     * that one instance is deployed; otherwise every matching instance
-     * in the package is deployed.
-     *
-     * Resolution order for `packageRef`:
-     *   1. Literal local file path (`./skill.kan.yml`, `C:\…\skill.kan.yml`,
-     *      or any existing path ending in `.kan.yml`) — read it directly
-     *      through the SDK parser, no workspace/cache/HTTP lookup.
-     *   2. `publisher/package[@version][/instance]` URI — resolved
-     *      against the workspace + global cache repository tiers first,
-     *      falling back to the publisher's HTTP origin only when nothing
-     *      local matches. This makes `<cap> add` work for skills/agents
-     *      that the user has authored locally and not yet published.
-     */
-    add(capability: LoadedCapability, packageRef: string, options: Record<string, string>): Promise<void>;
-    /**
-     * Try to load `packageRef` as a literal local file path. Recognizes
-     * any string that points to an existing file (typically with a
-     * `.kan.yml` suffix). Returns `undefined` for anything that doesn't
-     * look like a path — the caller falls back to URI-form parsing.
-     *
-     * Parsing goes through `KanonakParser.parse`; namespace metadata is
-     * pulled directly from the parsed document so publisher/package/
-     * version come from the file's own declarations rather than any
-     * heuristic on the path.
-     */
-    private tryLoadFromLocalFile;
-    /**
-     * Shared deployment path used by both the URI-form `add()` and the
-     * local-file-path form. Parses the document through the SDK object
-     * model, finds matching instances of the capability's managed type,
-     * and dispatches to the deployment handler keyed by deploymentTarget.
-     *
-     * `description` is the human-readable source label (a package URI
-     * or `local file <path>`) used in the user-facing output and error
-     * messages — keeping the URI flow's wording stable.
-     */
-    private deployFromDoc;
-    /**
-     * A publisher's OWN packages as pinned by its served `kanonak.lock` (keys
-     * under `<publisher>/`). The lock-derived package list — there is no index
-     * enumeration. Empty when the publisher serves no lock.
-     */
-    private lockedOwnPackages;
-    /**
-     * On a "package not found" error, scan the publisher's pinned packages for
-     * approximate name matches and print up to 5 suggestions. Helps users recover
-     * from typos and from passing a 3-segment URI to `add`.
-     */
-    private printPackageSuggestions;
-    remove(capability: LoadedCapability, name: string, options: Record<string, string>): Promise<void>;
-    list(capability: LoadedCapability, options: Record<string, string>): Promise<void>;
-    update(capability: LoadedCapability, name: string | undefined, options: Record<string, string>): Promise<void>;
-    /**
-     * Search a publisher's package index for any package that contains
-     * instances of this capability's `managesType`.
-     */
-    search(capability: LoadedCapability, options: Record<string, string>): Promise<void>;
-    info(capability: LoadedCapability, name: string, options: Record<string, string>): Promise<void>;
-    private requireHandler;
-}

package/dist/commands/capability.d.ts

@@ -1,9 +0,0 @@
-import { Command } from 'commander';
-/**
- * Create the built-in "capability" command group.
- *
- * This is the bootstrap mechanism — always available, not dynamically
- * loaded. Used to install, remove, and list capabilities that extend
- * the CLI.
- */
-export declare function capabilityCommand(): Command;

package/dist/skills/SkillDeploymentHandler.d.ts

@@ -1,18 +0,0 @@
-import type { DeploymentContext, DeploymentHandler, DeployedInstance, OperationContext } from '../capabilities/DeploymentHandlerRegistry.js';
-/**
- * Deployment handler for the `AgentSkillDeployment` DeploymentTarget.
- *
- * Transforms `kanonak.org/agent-skills/Skill` instances into SKILL.md
- * files and places them in the directory declared by the named
- * Client instance selected via the `--client` option (defaulting to
- * the "agents" cross-client layout). All path resolution and
- * reference following goes through the SDK object model.
- */
-export declare class SkillDeploymentHandler implements DeploymentHandler {
-    private readonly parser;
-    private readonly objectParser;
-    private readonly runner;
-    deploy(context: DeploymentContext): Promise<void>;
-    undeploy(name: string, context: OperationContext): Promise<void>;
-    list(context: OperationContext): Promise<DeployedInstance[]>;
-}

package/dist/skills/SkillLock.d.ts

@@ -1,26 +0,0 @@
-/**
- * Entry in the skills lock file tracking an installed skill.
- */
-export interface SkillLockEntry {
-    publisher: string;
-    package_: string;
-    version: string;
-    resolved: string;
-    integrity: string;
-}
-/**
- * The skills lock file structure.
- */
-export interface SkillLockFile {
-    version: string;
-    lastUpdated: string;
-    skills: Record<string, SkillLockEntry>;
-}
-/**
- * Load the skills lock file from a skills directory.
- */
-export declare function loadSkillLock(skillsDir: string): SkillLockFile;
-/**
- * Save the skills lock file to a skills directory.
- */
-export declare function saveSkillLock(skillsDir: string, lock: SkillLockFile): void;

package/dist/skills/SkillPaths.d.ts

@@ -1,48 +0,0 @@
-import type { IKanonakDocumentRepository } from '@kanonak-protocol/sdk';
-/**
- * Options for resolving skill discovery paths.
- */
-export interface SkillPathOptions {
-    /**
-     * clientId of a named Client instance in the agent-skills ontology
-     * (e.g. "agents", "claude-code"). When omitted, the CLI first tries
-     * `detectClient()` on process env vars, then falls back to the
-     * "agents" cross-client default.
-     */
-    client?: string;
-    /** "project" (default) or "user". */
-    scope?: string;
-}
-/**
- * Resolve the skills directory for the requested client and scope.
- *
- * This goes through the SDK object model: the agent-skills ontology
- * is parsed, Client instances are looked up by URI, and the matching
- * Client's `projectSkillDir` or `userSkillDir` is read. No hardcoded
- * path templates, no alias string-stripping — the installer adapts
- * to whatever named Client instances exist in the ontology at
- * runtime.
- */
-export declare function resolveSkillsDir(options: SkillPathOptions, repository: IKanonakDocumentRepository): Promise<string>;
-/**
- * Resolve the directory for a specific skill by name.
- */
-export declare function resolveSkillDir(skillName: string, options: SkillPathOptions, repository: IKanonakDocumentRepository): Promise<string>;
-/**
- * Resolve the file name to use inside a skill directory for the
- * configured Client. Pulled from the Client's `skillFileName` property
- * in agent-skills@1.2.0+. Defaults to `SKILL.md` when the Client
- * predates the property or doesn't declare it explicitly — which
- * matches the Agent Skills convention every shipped Client follows.
- */
-export declare function resolveSkillFileName(options: SkillPathOptions, repository: IKanonakDocumentRepository): Promise<string>;
-/**
- * Auto-detect the current AI agent client from environment variables.
- * Returns a clientId matching a named Client instance in the
- * agent-skills ontology, or undefined when nothing is detected.
- *
- * Matches the default Client instances declared in
- * kanonak.org/agent-skills@1.1.0. Extend this mapping when adding
- * new named Client instances with their own env-var signature.
- */
-export declare function detectClient(): string | undefined;