cyber-agentkit 1.0.0 → 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,6 +1,6 @@
 {
   "name": "cyber-agentkit",
-  "version": "1.0.0",
+  "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",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "cyber-agentkit",
-	"version": "1.0.0",
+	"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/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.