cyber-agentkit 0.7.1 → 1.1.0

package/dist/{resolve-reference-Cis-Ye6T.d.ts → resolve-reference-D62VJZc0.d.ts}

@@ -39,7 +39,7 @@ type ReferenceWarning = {
   code: ReferenceWarningCode;
   message: string;
 };
-type ReferenceWarningCode = 'frontmatter-invalid' | 'merge-unknown' | 'marker-unknown' | 'marker-unmatched' | 'heading-repeated' | 'remove-body-ignored' | 'extends-invalid' | 'extends-self' | 'extends-step-missing' | 'extends-all-missing' | 'extends-not-used' | 'default-not-selected' | 'default-folder-missing' | 'default-in-tier' | 'file-ignored' | 'interface-not-composed' | 'interface-check';
+type ReferenceWarningCode = 'frontmatter-invalid' | 'merge-unknown' | 'marker-unknown' | 'marker-unmatched' | 'heading-repeated' | 'remove-body-ignored' | 'extends-invalid' | 'extends-self' | 'extends-step-missing' | 'extends-all-missing' | 'extends-not-used' | 'default-not-selected' | 'default-folder-missing' | 'default-in-tier' | 'file-ignored' | 'format-mismatch' | 'selection-invalid' | 'interface-not-composed' | 'interface-check';
 /** The code of a name that is not `found`. */
 type ReferenceCode = 'reference-missing' | 'reference-ambiguous' | 'reference-invalid';
 //#endregion
@@ -56,9 +56,15 @@ type ReferenceLayer = {
   skill?: string | undefined;
   /** Set when the layer is never read, and why: policy held in MDM, a plugin with no install folder. */
   skipped?: string | undefined;
+  /**
+   * An `assets/` layer: a file is `<name>.<ext>` with no `.default` marker, read as written. Nothing in it
+   * merges or extends; the highest layer holding the name answers whole.
+   */
+  whole?: boolean | undefined;
   /** Raised on every name resolved through this layer, such as a `--default` folder that does not exist. */
   warning?: ReferenceWarning | undefined;
 };
+type ReferenceFolder = 'references' | 'assets';
 type ReferenceLayerOptions = {
   root: string;
   home: string;
@@ -70,6 +76,8 @@ type ReferenceLayerOptions = {
   plugin?: ReferencePlugin | undefined;
   /** The calling skill's folder: its `references/<name>.default.md` forms the `default` tier. */
   defaultSkill?: string | undefined;
+  /** The folder every tier reads: `references` (the default), or `assets` for an assets call. */
+  folder?: ReferenceFolder | undefined;
   /** Detects the harness and reads its settings. Defaults to `process.env`. */
   env?: Readonly<Record<string, string | undefined>>;
 };
@@ -97,7 +105,7 @@ declare function projectReferencesDir(root: string): string;
 declare function userReferencesDir(home: string): string;
 /** The `default` tier for the skill at `folder`; a folder that does not exist warns and adds no contribution. */
 declare function defaultLayer(folder: string): ReferenceLayer;
-declare function referenceLayers({ root, home, platform, plugin, defaultSkill, env }: ReferenceLayerOptions): Promise<ReferenceLayers>;
+declare function referenceLayers({ root, home, platform, plugin, defaultSkill, folder, env }: ReferenceLayerOptions): Promise<ReferenceLayers>;
 //#endregion
 //#region src/references/reference-document.d.ts
 /**
@@ -113,6 +121,10 @@ type SectionSource = {
   operation: MergeOperation;
 };
 //#endregion
+//#region src/references/reference-format.d.ts
+/** The format of a reference file: `markdown`, or the extension of a data file. */
+type ReferenceFormat = 'markdown' | 'json' | 'yaml' | 'toml' | 'txt';
+//#endregion
 //#region src/references/reference-name.d.ts
 type ReferenceName = {
   /** As asked. */
@@ -144,7 +156,7 @@ type ReferenceTraceLayer = {
   skill?: string;
   /** The file matched, or the folder checked when none matched. */
   path: string;
-  /** The file that answered, relative to the folder: `<name>.md`, `<name>/README.md`, or `<name>.default.md`. */
+  /** The file that answered, relative to the folder: `<name>.md`, `<name>/README.md`, `<name>.default.md`, or the same with a data extension. */
   file?: string;
   /** Its frontmatter as written. */
   frontmatter?: Record<string, unknown>;
@@ -197,6 +209,8 @@ type ResolvedReference = {
   /** Why it is not `found`, for a person. */
   message?: string;
   content?: string;
+  /** Set when `found`: `markdown`, or the format of the data file that answered whole. */
+  format?: ReferenceFormat;
   /** The composed frontmatter, key by key with the higher contribution winning, without `merge` and `extends`. */
   metadata?: Record<string, unknown>;
   /** When `ambiguous`: each `<plugin>/<name>`, and `default` when the skill has one. */

package/package.json

@@ -1,93 +1,92 @@
 {
-	"name": "cyber-agentkit",
-	"version": "0.7.1",
-	"description": "An agent-harness-agnostic toolkit: the fundamental features agent tools need, working the same on every harness. Detect the running harness, check plugin dependencies, resolve layered reference documents, and lease git worktrees.",
-	"keywords": [
-		"agent-harness",
-		"claude-code",
-		"cursor",
-		"codex",
-		"copilot-cli",
-		"opencode",
-		"kilo-code",
-		"gemini-cli",
-		"qwen-code",
-		"vscode",
-		"cline",
-		"crush",
-		"openhands",
-		"auggie"
-	],
-	"homepage": "https://cyber-uni.github.io/cyber-agentkit/",
-	"bugs": {
-		"url": "https://github.com/cyber-uni/cyber-agentkit/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/cyber-uni/cyber-agentkit.git",
-		"directory": "packages/cyber-agentkit"
-	},
-	"license": "MIT",
-	"author": "unional <homawong@gmail.com>",
-	"type": "module",
-	"sideEffects": [
-		"./bin/*.mjs",
-		"./dist/cli.js",
-		"./skills/*/scripts/*.mjs"
-	],
-	"exports": {
-		".": "./dist/index.js",
-		"./commands": "./dist/commands.js",
-		"./worktrees": "./dist/worktrees.js",
-		"./package.json": "./package.json"
-	},
-	"bin": {
-		"cyber-agentkit": "./bin/cyber-agentkit.mjs"
-	},
-	"files": [
-		"LICENSE",
-		"bin",
-		"dist",
-		"skills",
-		"references",
-		"plugin.json",
-		".claude-plugin",
-		".cursor-plugin",
-		".codex-plugin"
-	],
-	"scripts": {
-		"build": "tsdown",
-		"generate:references": "tsx scripts/generate-references.ts",
-		"dev": "tsx src/index.ts",
-		"lint": "biome check .",
-		"prepack": "pnpm build",
-		"test": "pnpm build && vitest run src",
-		"test:watch": "vitest",
-		"typecheck": "tsc --noEmit",
-		"verify": "pnpm typecheck && pnpm lint && pnpm test"
-	},
-	"peerDependencies": {
-		"clibuilder": "^12.0.0"
-	},
-	"peerDependenciesMeta": {
-		"clibuilder": {
-			"optional": true
-		}
-	},
-	"devDependencies": {
-		"@types/node": "^24.10.1",
-		"clibuilder": "^12.0.0",
-		"tsdown": "^0.23.0",
-		"tsx": "^4.22.3",
-		"typescript": "^7.0.0",
-		"vitest": "^5.0.0",
-		"yaml": "^2.9.0"
-	},
-	"engines": {
-		"node": ">=22"
-	},
-	"publishConfig": {
-		"access": "public",
-		"provenance": true
-	}
-}
+  "name": "cyber-agentkit",
+  "version": "1.1.0",
+  "description": "An agent-harness-agnostic toolkit: the fundamental features agent tools need, working the same on every harness. Detect the running harness, check plugin dependencies, resolve layered reference documents, and lease git worktrees.",
+  "keywords": [
+    "agent-harness",
+    "claude-code",
+    "cursor",
+    "codex",
+    "copilot-cli",
+    "opencode",
+    "kilo-code",
+    "gemini-cli",
+    "qwen-code",
+    "vscode",
+    "cline",
+    "crush",
+    "openhands",
+    "auggie"
+  ],
+  "homepage": "https://cyber-uni.github.io/cyber-agentkit/",
+  "bugs": {
+    "url": "https://github.com/cyber-uni/cyber-agentkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyber-uni/cyber-agentkit.git",
+    "directory": "packages/cyber-agentkit"
+  },
+  "license": "MIT",
+  "author": "unional <homawong@gmail.com>",
+  "type": "module",
+  "sideEffects": [
+    "./bin/*.mjs",
+    "./dist/cli.js",
+    "./skills/*/scripts/*.mjs"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./commands": "./dist/commands.js",
+    "./worktrees": "./dist/worktrees.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "cyber-agentkit": "bin/cyber-agentkit.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "bin",
+    "dist",
+    "skills",
+    "references",
+    "plugin.json",
+    ".claude-plugin",
+    ".cursor-plugin",
+    ".codex-plugin"
+  ],
+  "peerDependencies": {
+    "clibuilder": "^12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "clibuilder": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "clibuilder": "^12.0.0",
+    "tsdown": "^0.23.0",
+    "tsx": "^4.22.3",
+    "typescript": "^7.0.0",
+    "vitest": "^5.0.0",
+    "yaml": "^2.9.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "generate:references": "tsx scripts/generate-references.ts",
+    "dev": "tsx src/index.ts",
+    "lint": "biome check .",
+    "test": "pnpm build && vitest run src",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm typecheck && pnpm lint && pnpm test"
+  }
+}

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "cyber-agentkit",
-	"version": "0.7.1",
+	"version": "1.1.0",
 	"description": "An agent-harness-agnostic toolkit: the fundamental features agent tools need, working the same on every harness. Detect the running harness, check plugin dependencies, resolve layered reference documents, and lease git worktrees.",
 	"author": {
 		"name": "unional"
@@ -20,7 +20,8 @@
 				"copilot-cli": {}
 			},
 			"scripts": {
-				"skills/reference/scripts/reference.mjs": "src/references/reference.skill-script.ts"
+				"skills/reference/scripts/reference.mjs": "src/references/reference.skill-script.ts",
+				"skills/asset/scripts/asset.mjs": "src/assets/asset.skill-script.ts"
 			}
 		}
 	}

package/readme.md

@@ -204,7 +204,7 @@ harness keeps no readable install record). A dependency with no marketplace reso
 declaring plugin's own marketplace, as Claude Code does, and is `unknown` when that marketplace
 cannot be found.
 
-`readPluginDependencies(pluginRoot)` reads the list from `extensions["org.spikyuni.plugin-manager"]`
+`readPluginDependencies(pluginRoot)` reads the list from `extensions["io.github.cyber-uni.plugin-manager"]`
 (or the older `extensions["org.cyberuni.universal-plugin"]`) in the root `plugin.json`, then from
 `.claude-plugin/plugin.json`. `declaredPluginDependencies(manifest)` parses a manifest you already
 hold. The how-to for a person or agent, `plugin-dependencies`, ships as a
@@ -377,8 +377,8 @@ you approve it. It runs the command from its bundled `scripts/reference.mjs`, wh
 `node_modules`.
 
 ```text
-/plugin marketplace add cyberuni/cyberplace
-/plugin install cyber-agentkit@cyberplace
+/plugin marketplace add cyber-uni/marketplace
+/plugin install cyber-agentkit@cyber-uni
 ```
 
 A skill that needs a reference names it in one line, as the skill's

package/references/plugin-dependencies.md

@@ -5,7 +5,7 @@ tags: [plugin, dependencies, install]
 
 ## What a plugin declares
 
-Only Claude Code's manifest declares dependencies: a `dependencies` array in `.claude-plugin/plugin.json` whose entries are `"name"`, `"name@marketplace"`, or `{ "name", "marketplace", "version" }` (E-DEP-1). A bare name resolves in the declaring plugin's own marketplace. A plugin can author the same list once in its root `plugin.json`, at `extensions["org.spikyuni.plugin-manager"].dependencies` or, in plugins built before that key, `extensions["org.cyberuni.universal-plugin"].dependencies` (E-DEP-6, E-DEP-7). Read it from there first, then from `.claude-plugin/plugin.json`, whichever harness you run on.
+Only Claude Code's manifest declares dependencies: a `dependencies` array in `.claude-plugin/plugin.json` whose entries are `"name"`, `"name@marketplace"`, or `{ "name", "marketplace", "version" }` (E-DEP-1). A bare name resolves in the declaring plugin's own marketplace. A plugin can author the same list once in its root `plugin.json`, at `extensions["io.github.cyber-uni.plugin-manager"].dependencies` or, in plugins built before that key, `extensions["org.cyberuni.universal-plugin"].dependencies` (E-DEP-6 to E-DEP-8). Read it from there first, then from `.claude-plugin/plugin.json`, whichever harness you run on.
 
 ## Check what is missing
 

package/skills/asset/README.md

@@ -0,0 +1,14 @@
+# Asset
+
+Lists, shows, creates, updates, and deletes the static files in a skill's `assets/` folder, such as templates, schemas, and JSON data a skill points to by path. By path: plain file operations with no tiers and no merging. By name: loads a file through the managed, project, user, and plugin tiers (the skill's own file is the default), so a plugin, the project, or the user can override which one a skill uses by placing its own. Nothing merges or extends. It runs the `asset` command from a launcher bundled in `scripts/`, and writes or deletes only after the user approves. Type `/asset` to run it yourself. Installed as a Claude Code plugin, it is `/cyber-agentkit:asset` (pnpm install: `pnpm-cyber-agentkit-asset`).
+
+| Mode | When |
+| --- | --- |
+| list | see every file under the skill's `assets/` with its size |
+| show | read a text asset |
+| create | add a new asset; never overwrites. With `--copy`, start an override in the project or user tier as a copy of a plugin's, the default, or another tier's file (never managed) |
+| update | replace an existing asset |
+| delete | remove an asset and any folder it leaves empty |
+| load, names, where, select | resolve an asset by name through the tiers, list names, show where an override goes, and choose which plugin's file answers a name several hold |
+
+For a document fetched by name and layered across the managed, project, user, and plugin tiers, use [`/reference`](../reference/README.md).

package/skills/asset/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: asset
+description: Use this skill when listing, reading, adding, changing, or deleting the static files in a skill's assets/ folder, such as templates, schemas, or JSON data a skill points to by path.
+---
+
+# Asset
+
+An **asset** is a static file in a skill's `assets/` folder: a template, a schema, a lookup table, a JSON permission list. Two kinds of work:
+
+- **By path**: manage the files themselves. No tiers, no merging.
+- **By name**: load a file the way a reference loads, so a plugin, the project, or the user can override which file a skill uses by placing its own. The managed, project (`.agents/assets/`), user (`~/.agents/assets/`), and plugin tiers read `assets/` folders, and the skill's own `assets/<name>.<ext>` is the default. The highest tier holding the name answers with the file as written. Nothing merges or extends, Markdown included: frontmatter in an asset is just text. Choosing among plugins is a selection, a one-line `<name>.select` file.
+
+For a Markdown document layered across tiers, use the `reference` skill.
+
+## Route
+
+| The request | Run |
+| --- | --- |
+| see which assets a skill holds | `list` |
+| read a text asset | `show <path>` |
+| add a new asset | `create <path>` |
+| start an override from an existing asset, to edit | `create <name> --copy <plugin\|default\|project\|user> --scope project\|user --default <skill folder>` |
+| change an existing asset | `update <path>` |
+| remove an asset | `delete <path>` |
+| read the asset a skill loads by name, after overrides | `load <name> --default <skill folder>` |
+| see which asset names exist | `names --default <skill folder>` |
+| see where an override of a name would go | `where <name> --default <skill folder>` |
+| choose which plugin's file, or the skill's own, answers a name | `select <name> <option> --default <skill folder>` |
+
+## Run
+
+Find the skill's source folder in the repository (the directory its `SKILL.md` is in), then run from anywhere:
+
+```sh
+node <this skill's folder>/scripts/asset.mjs <mode> [<path>] --skill <skill folder> --root <repository root>
+```
+
+- `<path>` is relative to `assets/`, with `/` separators and no `..`, such as `data/rules.json`.
+- `create` and `update` take the text with `--content "<text>"` or a local file with `--from <file>`; pass exactly one.
+- Never use `npx`, `pnpm dlx`, or any package runner, and never download anything.
+
+`load`, `names`, and `where` read only. `create --copy` never copies from the managed tier: it is policy, a copy would leak it into the repository or home folder and read as in effect when the managed file still wins. If asked, refuse and offer `load` to read it.
+
+Ask the user before `create`, `update`, `delete`, or `select`, and name the file.
+
+To make a skill use a different file, place one of the same name in a higher tier: `.agents/assets/<name>.<ext>` for the project, `~/.agents/assets/<name>.<ext>` for the user. When two plugins hold a name and no tier does, `load` reports it ambiguous and lists the options: run `select <name> <option>` (a plugin name, or `default` for the skill's own file; `--scope user` for yourself, `--clear` to undo), ask for `<plugin>/<name>`, or place the file in a tier. `where <name>` shows the folders. `create` never overwrites and `update` needs the file to exist.
+
+## Read the result
+
+Exit 0 means it did what was asked. Exit 1 is a refusal, and stderr says `error: <code>: <message>`: `exists`, `no-file`, `binary`, or `folder-invalid` (the folder is not a skill folder, or is an installed copy or outside the repository). Exit 2 is misuse: a path that leaves `assets/`, or both or neither of `--content` and `--from`. Report the message; do not retry with a different path to get around it.
+
+`show` prints text only. A binary asset is pointed to by path, not shown.