use-agentz 0.1.0

package/README.md

@@ -0,0 +1,308 @@
+# AgentZ
+
+AgentZ is a Bun-native installer for portable AI-agent configuration. It resolves typed registry items, writes target-native files, records ownership in a lock file, and preserves user-owned configuration.
+
+One catalog supports six targets: OpenCode, GitHub Copilot, Claude Code, Codex CLI, KiloCode, and Hermes.
+
+## Requirements
+
+- Bun `>=1.3.8`.
+- A target is optional until selected.
+- Bun runs the CLI, build, package, registry, and local verification commands.
+
+## Install
+
+Install `use-agentz` from npm:
+
+```bash
+bun add --dev use-agentz
+agentz --version
+agentz --help
+```
+
+Build and link a checkout for local use:
+
+```bash
+bun install
+bun run codegen
+bun run registry
+bun run build
+bun link
+
+# In another project
+bun link use-agentz
+agentz --help
+```
+
+Build a local package instead of linking:
+
+```bash
+bun pm pack --destination /tmp/use-agentz-pack
+bun add --dev /tmp/use-agentz-pack/use-agentz-*.tgz
+agentz catalog
+```
+
+## Quick start
+
+Interactive setup detects installed targets when possible, otherwise starts with OpenCode:
+
+```bash
+agentz init
+```
+
+Non-interactive setup requires a preset:
+
+```bash
+agentz init --yes --preset cost-aware-trio --model-pack optimized --target opencode
+```
+
+Manage items later:
+
+```bash
+agentz add skill:typescript-dev skill:db-schema-design
+agentz list --type skill
+agentz update --dry-run
+agentz remove skill:db-schema-design --yes
+```
+
+`init`, `add`, `update`, `remove`, and `prune` show plans before changing files. Use `--dry-run` to print the plan without writes.
+
+## Command grammar
+
+Flags may appear before or after a command. `--` is not a separator.
+
+```text
+agentz [global flags] init [init flags]
+agentz --version
+agentz [global flags] ui [--port <0..65535>]
+agentz [global flags] add <ref>... [add flags]
+agentz [global flags] catalog [--type <type>] [--registry <namespace>]
+agentz [global flags] list [--type <type>] [--registry <namespace>]
+agentz [global flags] update [ref...] [update flags]
+agentz [global flags] remove <ref>... [--dry-run] [--yes]
+agentz [global flags] prune [--dry-run] [--yes]
+agentz registry [build|scaffold] [--write]
+agentz help
+```
+
+No command, `--help`, or `-h` prints the reference. `--version` prints the package version. `install` remains an `init` compatibility alias. `registry build` is the default registry subcommand. `catalog` writes a short advisory to stderr, then emits the same grouped listing as `list` to stdout.
+
+### Commands
+
+| Command | Behavior |
+| --- | --- |
+| `init` | Terminal wizard. Writes `agentz.json`, saves install preferences, then installs selected preset closure. `--yes` or `--dry-run` needs one or more `--preset` values. |
+| `ui` | Starts a local setup UI on `127.0.0.1`. `--port 0` or omitted picks a free port. |
+| `add <ref...>` | Resolves refs and typed dependencies, installs them, then updates `agentz.lock`. |
+| `catalog`, `list` | Lists registry items. Installed items show `●`; group-only skills stay hidden from an unfiltered skill listing. |
+| `update [ref...]` | Re-resolves locked refs. No ref updates all lock-backed refs. Detects drift before reapplying. |
+| `remove <ref...>` | Removes only lock-owned files, JSON entries, and marker blocks. Refuses unowned refs. |
+| `prune` | Plans removal of `*.bak` files and retired singular `agent/`, `skill/`, and `tool/` directories under selected target roots. Warns before deleting an unmirrored entry. |
+| `registry build` | Authoring command. Builds static registry JSON from `catalog/`. Requires a source checkout and Bun. |
+| `registry scaffold` | Reports discovered content without matching config. `--write` appends generated stubs to catalog config. |
+
+### Flags
+
+| Flag | Applies to | Meaning |
+| --- | --- | --- |
+| `--target <opencode|copilot|claude|codex|kilocode|hermes>` | `init`, `add`, `update`, `prune` | Repeatable target override. Otherwise configured targets apply. |
+| `--scope <project|global>` | all target-planning commands | Target file scope. Default `project`. `global` writes into target user directories. |
+| `--dir <path>` | all commands | Project directory. Defaults to current directory. Missing paths are created. |
+| `--dry-run` | `init`, `add`, `update`, `remove`, `prune` | Print plan and make no writes. |
+| `--yes`, `-y` | `init`, `add`, `update`, `remove`, `prune` | Skip normal confirmation. Does not bypass local command trust gates. |
+| `--preset <ref>` | `init --yes`, `init --dry-run` | Repeatable. Comma-separated values are also accepted. |
+| `--model-pack <basic|opus-fable|gpt-5-6|optimized>` | `init` | Model pack. Default `optimized`. |
+| `--overwrite` | `add` | Unconditionally replace managed-file writes. |
+| `--force` | `update` | Proceed after on-disk drift. A user file without a managed header still remains preserved. |
+| `--prune` | `update` | Confirm removal of lock refs proven absent from their owning registry. |
+| `--skip-deps` | `init`, `add`, `update` | Skip host-level MCP and LSP dependency installation. |
+| `--yes-deps` | `init`, `add`, `update` | Approve host-level dependency commands after they are shown. |
+| `--type <skill|group|agent|tool|mcp|lsp|pack|plugin|command|preset|rule>` | `catalog`, `list` | Item-type filter. |
+| `--registry <namespace>` | `catalog`, `list` | Registry namespace filter. |
+| `--port <0..65535>` | `ui` | Local UI port. Omit or use `0` for a free port. |
+| `--write` | `registry scaffold` | Write generated catalog-config stubs. |
+
+Normal mutations need an interactive TTY or `--yes`; dry runs do not. Parser and ordinary command failures exit `1`. A wizard usage failure exits `2`.
+
+## Reference grammar
+
+Every item identity is `(type, name)`. Typed refs are safest:
+
+```text
+skill:caveman             typed builtin ref
+lsp:proto                 typed language-server ref
+caveman                   bare ref; must be unique across item types
+@team/skill:caveman       namespace declared in agentz.json
+https://host/r/x.json     direct remote manifest; warning and confirmation
+file:./local/x.json       direct local manifest; warning and confirmation
+```
+
+Item types are `skill`, `group`, `agent`, `tool`, `mcp`, `lsp`, `pack`, `plugin`, `command`, `preset`, and `rule`. Dependencies in manifests are typed refs and resolve before their dependents.
+
+## Project configuration and state
+
+`agentz.json` is committed project configuration. `agentz.lock` is committed ownership and integrity state.
+
+```jsonc
+{
+  "$schema": "./node_modules/use-agentz/schema/agentz.schema.json",
+  "schemaVersion": 2,
+  "targets": ["opencode", "claude"],
+  "scope": "project",
+  "modelPack": "optimized",
+  "registries": {
+    "@official": "builtin:",
+    "@team": "https://agents.example.invalid/registry"
+  },
+  "vars": {
+    "scratchpad": true,
+    "model.normal": "github-copilot/claude-opus-4.8"
+  },
+  "tierThinking": {
+    "normal": { "reasoningEffort": "high" }
+  },
+  "agents": {
+    "developer": {
+      "thinking": { "textVerbosity": "low" },
+      "pinModel": true
+    }
+  },
+  "mcps": {
+    "playwright": { "options": { "headless": true } }
+  },
+  "options": { "backup": true }
+}
+```
+
+`schemaVersion` is `1` or `2`. `targets` must contain at least one of the six target ids. `registries` must declare `@official`; `builtin:` is the packaged catalog. `vars` values are strings or booleans for template substitution. `tierThinking` has `cheap`, `normal`, and `expert` entries. Agent overrides support model, pinning, sampling fields, permission values, thinking, and provider options. MCP overrides currently choose declarative option booleans.
+
+The command-line `--scope global` maps to `"scope": "user"` in `agentz.json`. Project config uses `project|user`; command planning uses `project|global`.
+
+### Config and state paths
+
+| Purpose | Paths |
+| --- | --- |
+| Project config | `agentz.json`, `agentz.jsonc`, `agentz.yaml`, `agentz.yml`, `agentz.toml`, `agentz.config.ts`, `agentz.config.js`, or `agentz.config.mjs`. Keep exactly one. `init` writes only `agentz.json`. |
+| Project lock | `agentz.lock` |
+| Project user settings | `agentz.config.yaml`, `agentz.config.yml`, `agentz.config.toml`, `agentz.config.jsonc`, or `agentz.config.json` |
+| Global user settings | `$XDG_CONFIG_HOME/agentz/config.<format>`; default root is `~/.config/agentz/` |
+| Schema in installed package | `schema/agentz.schema.json` |
+| Migration journal | `.agentz/state-migration.json` |
+
+User settings layer global first, then project, then `AGENTZ_*` environment variables. Useful variables:
+
+```text
+AGENTZ_MODEL_CHEAP=<model>
+AGENTZ_MODEL_NORMAL_<TARGET>=<model>
+AGENTZ_MODEL_EXPERT_<TARGET>=<model>
+AGENTZ_<TARGET>_PROJECT_DIR=<path>
+AGENTZ_<TARGET>_GLOBAL_DIR=<path>
+AGENTZ_<TARGET>_AGENTS_MD=<path>
+AGENTZ_MODELS_CACHE=<path>
+AGENTZ_AUTH_JSON=<path>
+```
+
+`<TARGET>` is one of `OPENCODE`, `COPILOT`, `CLAUDE`, `CODEX`, `KILOCODE`, or `HERMES`. Project state and user configuration from an earlier state family are read-only until an explicit, confirmed migration creates verified backups and a journal.
+
+The lock records each item ref, source, version, SHA-256 hashes for files it owns, marker blocks, selected JSON entries, and host dependency command hashes. `remove` therefore deletes only owned output. `update` reports missing or modified locked files. The installer preserves unowned target configuration and user values during merges.
+
+## Security and ownership
+
+- Registry manifests are strict. Executable fields exist only for MCP and LSP item shapes.
+- Registered remote registries require HTTPS; loopback HTTP is reserved for local development.
+- `agentz.json` registries are an allowlist. Direct `https:` and `file:` refs show an extra warning and need confirmation.
+- A non-builtin MCP or LSP local command is printed verbatim and needs an explicit confirmation. `--yes` cannot bypass this. Non-interactive execution fails closed.
+- Host-level MCP and LSP dependencies run only after the file plan succeeds. AgentZ shows exact argument vectors, never shells them, and requires confirmation or `--yes-deps`. `--skip-deps` leaves them untouched.
+- Content changing at the same locked version triggers a trust-on-first-use warning.
+- `update --prune` removes only refs proven gone from their owning registry. `prune` prints every candidate before removal.
+- Managed files keep a header. Replacing it with user content protects that file from normal refreshes.
+
+## Targets and degradation
+
+All targets get selected skills, supported tools, MCP configuration where available, and lock ownership. Target-native gaps are reported as install notes.
+
+| Target | Project output | Global output and behavior |
+| --- | --- | --- |
+| OpenCode | `.opencode/opencode.json`, `agents/`, `skills/`, `tools/`, `plugins/`, `commands/`, `rules/`, and managed `AGENTS.md` | `~/.config/opencode/`. Full support for agent thinking, plugins, commands, LSPs, and default-agent configuration. Restart OpenCode after installation. |
+| GitHub Copilot | `.github/agents/`, `skills/`, `tools/`, `copilot-instructions.md` | `~/.copilot/`. MCP servers are global at `~/.copilot/mcp-config.json`. Orchestrator text becomes instructions. |
+| Claude Code | `.claude/agents/`, `skills/`, `tools/`, root `CLAUDE.md`, and `.mcp.json` | `~/.claude/`. Orchestrator text becomes `CLAUDE.md`. Project tools become MCP servers; global tool registration is shown for manual use. |
+| Codex CLI | root `AGENTS.md`, `.codex/skills/`, `.codex/tools/` | `~/.codex/`. Agent roles become cards in `AGENTS.md`; profiles and MCP entries are global `~/.codex/config.toml` blocks. |
+| KiloCode | `.kilocode/skills/`, `tools/`, `rules/agentz.md`, `mcp.json`, and project `.kilocodemodes` | `~/.kilocode/`. Custom modes are project-only; global installs report this limitation. |
+| Hermes | `.hermes/agents/`, `skills/`, `tools/`, `mcp.json`, and `AGENTS.md` | `~/.hermes/`. Layout is convention-based and can be redirected through settings paths or `AGENTZ_HERMES_*_DIR`. |
+
+Agent thinking, plugins, custom commands, and language servers are OpenCode-only. Other targets drop those selected items with a note. Disabling a target's built-in agents is also OpenCode-only. A tool without a source for a selected target is not emitted for that target.
+
+## UI
+
+`agentz ui` serves a local React interface only on `127.0.0.1`, prints the URL, and best-effort opens it in a browser. Ctrl-C stops the server.
+
+The UI uses the same wizard resolution and install pipeline as `init`. It can browse catalog items, select multiple presets, select a model pack, preview plans and selected OpenCode files, set template variables and per-agent overrides, add extra items, inspect a bounded monorepo project list, and install into the chosen project. Discovery recognizes AgentZ config files and `agentz.lock`; legacy state remains visible for migration. Its API stays loopback-only. Local model cache and authentication paths can be overridden with `AGENTZ_MODELS_CACHE` and `AGENTZ_AUTH_JSON`.
+
+## Portable catalog
+
+The builtin catalog contains 102 portable items:
+
+| Type | Count |
+| --- | ---: |
+| Agents | 10 |
+| Skills | 47 |
+| Skill groups | 10 |
+| Tools | 8 |
+| MCP servers | 2 |
+| Language servers | 1 |
+| Model packs | 4 |
+| Plugins | 1 |
+| Commands | 2 |
+| Presets | 6 |
+| Rules | 11 |
+
+Model packs are `basic`, `opus-fable`, `gpt-5-6`, and `optimized`. Presets are `cost-aware-trio`, `full`, `design`, `fable-pack`, `cross-model-review`, and `caveman-only`. The catalog contains portable engineering, design, document, language, and CLI material only; no organization-specific platform bundle is shipped.
+
+## Registry authoring
+
+`catalog/config/*.ts` defines typed catalog records. `catalog/content/**` contains prompts, skills, rules, commands, providers, and tool content. `registry.config.ts` composes the builtin registry.
+
+```bash
+# After catalog additions, removals, or identifier changes
+bun run codegen
+bun run registry
+
+# Inspect missing config entries
+bun run src/cli.ts registry scaffold
+
+# Append scaffold stubs intentionally
+bun run src/cli.ts registry scaffold --write
+```
+
+`registry build` writes:
+
+```text
+registry/registry.json
+registry/r/<type>.<name>.json
+```
+
+The directory is static-hostable. Consumers declare a namespace in `agentz.json`:
+
+```jsonc
+{
+  "registries": {
+    "@official": "builtin:",
+    "@team": "https://agents.example.invalid/registry"
+  }
+}
+```
+
+AgentZ reads `<base>/registry.json` and `<base>/r/<type>.<name>.json` by default. Custom registries must preserve strict manifest shapes and typed dependency refs.
+
+## Develop and package locally
+
+```bash
+bun install
+bun run typecheck
+bun run codegen
+bun run registry
+bun run build
+bun run verify-pack
+```
+
+`build` creates Bun-targeted `dist/cli.js`, copies UI web assets, and generates `schema/agentz.schema.json`. The package includes only `dist/`, `registry/`, `schema/`, `README.md`, and package metadata. `verify-pack` creates a temporary tarball, checks its contents, installs it into an isolated Bun project, and verifies `agentz --version`, `agentz --help`, and `agentz catalog`.

package/dist/authoring/define.js

@@ -0,0 +1,132 @@
+// @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/authoring/define.ts
+function defineRegistry(input) {
+  return input;
+}
+function defineTier(input) {
+  return input;
+}
+function defineTiers(input) {
+  return input;
+}
+function defineModelPack(input) {
+  return input;
+}
+function defineModelPacks(input) {
+  return input;
+}
+function definePlugin(input) {
+  return input;
+}
+function definePlugins(input) {
+  return input;
+}
+function defineCommand(input) {
+  return input;
+}
+function defineCommands(input) {
+  return input;
+}
+function defineSkill(input) {
+  return input;
+}
+function defineSkills(input) {
+  return input;
+}
+function defineSkillGroup(input) {
+  return input;
+}
+function defineSkillGroups(input) {
+  return input;
+}
+function defineAgent(input) {
+  return input;
+}
+function defineAgents(input) {
+  return input;
+}
+function defineTool(input) {
+  return input;
+}
+function defineTools(input) {
+  return input;
+}
+function defineMcp(input) {
+  return input;
+}
+function defineMcps(input) {
+  return input;
+}
+function defineLsp(input) {
+  return input;
+}
+function defineLsps(input) {
+  return input;
+}
+function definePreset(input) {
+  return input;
+}
+function definePresets(input) {
+  return input;
+}
+function defineRule(input) {
+  return input;
+}
+function defineRules(input) {
+  return input;
+}
+export {
+  defineTools,
+  defineTool,
+  defineTiers,
+  defineTier,
+  defineSkills,
+  defineSkillGroups,
+  defineSkillGroup,
+  defineSkill,
+  defineRules,
+  defineRule,
+  defineRegistry,
+  definePresets,
+  definePreset,
+  definePlugins,
+  definePlugin,
+  defineModelPacks,
+  defineModelPack,
+  defineMcps,
+  defineMcp,
+  defineLsps,
+  defineLsp,
+  defineCommands,
+  defineCommand,
+  defineAgents,
+  defineAgent
+};