@mhmdreza-rafiei/agentry 0.1.0 → 0.2.1

package/README.md

@@ -1,95 +1,198 @@
-# agentry
+<div align="center">
 
-A raw installer for AI/agent tooling. `agentry` fetches **agents, skills, rules, and scripts** from any Git repo (or local path) and installs the ones you pick into your project — or globally — under `.cursor/`. The CLI ships no assets of its own; you point it at a source.
+# Agentry
 
-## Install / run
+**Install agents, skills, rules, scripts, and profiles onto coding agents — from any Git repo.**
 
-```bash
-# Run without installing (recommended)
-npx agentry@latest --help
+Supports **Cursor**, **Claude Code**, **Codex**, **OpenCode**, and [70+ more](#supported-agents).
+
+[![npm](https://img.shields.io/npm/v/@mhmdreza-rafiei/agentry?style=flat&color=38bdf8)](https://www.npmjs.com/package/@mhmdreza-rafiei/agentry)
+[![node](https://img.shields.io/badge/node-%3E%3D22.20-38bdf8?style=flat)](#install)
+[![license](https://img.shields.io/badge/license-MIT-38bdf8?style=flat)](LICENSE)
+[![stars](https://img.shields.io/github/stars/mhmdreza-rafiei/agentry?style=social)](https://github.com/mhmdreza-rafiei/agentry)
+
+</div>
 
-# Or install the CLI globally
-npm install -g agentry@latest
+## Install
 
-# Update / uninstall the CLI
-agentry update
-agentry --uninstall
+```bash
+npm install -g @mhmdreza-rafiei/agentry
+# or
+npx @mhmdreza-rafiei/agentry@latest --help
 ```
 
-> Publishing to npm is pending. Until then, run from a clone: `node bin/agentry.js …` or `npx . …`.
+## Quick start
 
-## Usage
+```bash
+# Browse + install skills from a repo
+agentry add skills mhmdreza-rafiei/agent-tools
 
+# Install one skill to Cursor
+agentry add skills mhmdreza-rafiei/agent-tools enhance-prompt -a cursor
+
+# See what is installed
+agentry list
+agentry list skills
 ```
-agentry add <type> <source> [category/name | category] [options]
-agentry add profile <name> [source] [options]
-agentry remove <type> [category/name | category] [options]
-agentry list <source> [type]
-agentry update
-```
 
-`<source>` is a GitHub shorthand `author/repo`, a full git URL, or a local path.
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `agentry add <kind> <source> [selector]` | Discover and install artifacts |
+| `agentry add profile <name> [source]` | Apply a local `profile/<name>.yaml` bundle |
+| `agentry list` | List installed artifacts |
+| `agentry list <kind>` | List installed artifacts of one kind |
+| `agentry list <source> [kind] [selector]` | List what a repo/path contains |
+| `agentry remove <kind> [source] [selector]` | Remove installs (files + lock) |
+| `agentry update [kind] [source] [selector]` | Re-install from source or lockfile |
+| `agentry init <kind> [name] [category]` | Scaffold a new artifact |
+| `agentry update` | Update the Agentry CLI itself |
+| `agentry uninstall` | Uninstall the Agentry CLI |
+
+`<kind>` is `skill | rule | agent | profile | script` (plurals accepted).
+
+### Source formats
 
 ```bash
-agentry add skills Prat011/awesome-llm-skills                    # list all skills and pick
-agentry add skills Prat011/awesome-llm-skills video-downloader   # one skill (no category)
-agentry add skills Prat011/awesome-llm-skills document-skills/docx  # one skill (category/name)
-agentry add agents author/repo frontend                         # a whole category
-agentry add profile frontend author/repo                        # apply profile/frontend.json
-agentry remove skills document-skills/docx                      # remove an installed asset
-agentry list Prat011/awesome-llm-skills
+# GitHub shorthand
+agentry add skills mhmdreza-rafiei/agent-tools
+
+# Full GitHub URL
+agentry add skills https://github.com/mhmdreza-rafiei/agent-tools
+
+# Tree URL (subdir + ref)
+agentry add skills https://github.com/mhmdreza-rafiei/agent-tools/tree/main/skills
+
+# Local path
+agentry add skills ./my-skills
+
+# Any git URL
+agentry add skills git@github.com:mhmdreza-rafiei/agent-tools.git
 ```
 
-Flags: `-g, --global` (into `~/.cursor`), `--project` (current folder, default), `--dir <path>`, `-y, --yes` (no prompts; install everything matched), `-v, --version`, `-h, --help`, `--uninstall`.
+### Options
+
+| Option | Description |
+| --- | --- |
+| `-g, --global` | Install into `~` (all projects) |
+| `--project` | Install into the current folder (default) |
+| `--dir <path>` | Install into a specific folder |
+| `-a, --agent <name>` | Target provider(s); repeatable; `*` = all |
+| `-l, --list` | Preview only — write nothing |
+| `--copy` | Copy instead of symlink for non-universal agents |
+| `--all` | Install everything to all agents, no prompts |
+| `-y, --yes` | Skip prompts |
+| `--description <text>` | `init`: frontmatter description |
+| `--alwaysApply` | `init` rule: `alwaysApply: true` |
+| `--reference` / `--no-reference` | `init` skill: include `references/TEMPLATE.md` |
+| `--skills` / `--agents` / `--rules` / `--scripts` `[src]` | `init` profile: include kinds (optional source) |
+
+## Examples
 
-When neither `--global` nor `--project` is given, an interactive terminal asks where to install; non‑interactive runs (agents/CI) default to the current project.
+```bash
+# List everything in a catalog repo
+agentry list mhmdreza-rafiei/agent-tools
+agentry list mhmdreza-rafiei/agent-tools skills
+agentry list mhmdreza-rafiei/agent-tools skills enhance-prompt
+
+# Install
+agentry add skills mhmdreza-rafiei/agent-tools
+agentry add skills mhmdreza-rafiei/agent-tools enhance-prompt -a cursor -a claude-code
+agentry add rules mhmdreza-rafiei/agent-tools ask-dont-guess
+agentry add agents mhmdreza-rafiei/agent-tools frontend-developer
+
+# Inventory
+agentry list
+agentry list skills
+
+# Update / remove by selector or by install source
+agentry update skills mhmdreza-rafiei/agent-tools
+agentry remove skills enhance-prompt
+agentry remove skills mhmdreza-rafiei/agent-tools
+
+# Scaffold
+agentry init skill enhance-prompt prompt --reference
+agentry init rule ask-dont-guess --alwaysApply --description "Ask before guessing"
+agentry init profile frontend --skills mhmdreza-rafiei/agent-tools -a cursor
+```
 
-## How sources are discovered
+Example catalog used throughout this README: [`mhmdreza-rafiei/agent-tools`](https://github.com/mhmdreza-rafiei/agent-tools).
 
-For each type, `agentry` finds assets in two ways and merges them:
+## How it works
 
-1. Under an explicit folder — `<type>/<name>/` or `<type>/<category>/<name>/`.
-2. At the repo root by marker file (like `npx skills add`) — a folder with `SKILL.md` is a skill, `AGENT.md` an agent, `RULE.md` a rule. A root folder whose children carry markers becomes a category (e.g. `document-skills/docx`).
+1. Resolve a source (local path or shallow git clone).
+2. Discover artifacts under `<kind>s/` **and** root markers (`SKILL.md`, `.mdc`).
+3. Let you pick what to install (searchable list + `All`).
+4. Install once to `.agents/skills/<id>` for universal providers; symlink (or `--copy`) for others.
+5. Track installs in `.agentry/lock.json` for remove/update.
 
-Selectors after the source: `category/name` (one asset), `name` (one asset when uncategorized), `category` (whole category), or omit to list-and-pick.
+If a clone fails and a prior cache exists, Agentry asks whether to load from cache (`~/.cache/agentry/repos`).
 
-Assets install to `<root>/.cursor/<type>/[category/]<name>/` and are tracked in `.cursor/agentry.lock.json` for idempotent installs and clean removal. `remove` works purely on installed files, so it needs no source.
+## Artifact layouts
 
-## Profiles
+Author installable tools in a source repo like this:
 
-A profile is a plain JSON file at `profile/<name>.json` in your project. It lists selectors per type; `agentry add profile <name> <source>` fetches the source once and installs everything the profile lists.
+### Skills
 
-```json
-{
-  "repo": "author/repo",
-  "agents":  ["frontend"],
-  "skills":  ["prompt/enhance-prompt"],
-  "rules":   ["workflow/ask-dont-guess"]
-}
+```text
+skills/
+  enhance-prompt/
+    SKILL.md
+    references/
+      TEMPLATE.md
+  prompt/
+    rewrite/
+      SKILL.md
 ```
 
-`repo` is optional — the command-line `<source>` wins when given. See [`profile/frontend.json`](profile/frontend.json) and [`profile/backend.json`](profile/backend.json).
+### Agents / rules
 
-## Publish to npm (maintainers)
+```text
+agents/
+  frontend-developer.mdc
+rules/
+  ask-dont-guess.mdc
+```
 
-```bash
-# ensure package.json "name" is available (or scope it: @you/agentry)
-npm login
-npm publish --access public
-# verify
-npx agentry@latest --version
+### Scripts / profiles
+
+```text
+scripts/
+  deploy/
+    README.md
+profiles/
+  frontend.yaml
 ```
 
-## Development / test
+Local install profiles (consumed by `agentry add profile`) live at `profile/<name>.yaml`.
+
+## Supported agents
+
+Agentry targets **70+** providers. Universal providers share `.agents/skills/`; others get a symlink or copy.
+
+| Agent | Skills path |
+| --- | --- |
+| Cursor | `.agents/skills` |
+| Codex | `.agents/skills` |
+| OpenCode | `.agents/skills` |
+| Gemini CLI | `.agents/skills` |
+| Claude Code | `.claude/skills` |
+| Windsurf | `.windsurf/skills` |
+| … | see `src/registry/agents.ts` |
+
+## Development
 
 ```bash
-npm test                 # node --test (discovery, source resolution, install/remove, profiles)
-node bin/agentry.js …    # run the CLI locally
-node bin/agentry.js list ./examples   # try it against the bundled sample source
+npm install
+npm run typecheck
+npm test
+npm run build
+node dist/cli.mjs --help
 ```
 
-`examples/` is a sample source repo (skills/agents/rules/scripts) used by the demo — not part of the CLI. `src/` holds the logic: `registry` (discovery), `source` (fetch), `commands` (install/remove), `profile` (config).
+Requires **Node ≥ 22.20**.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/dist/_chunks/theme.mjs

@@ -0,0 +1,2 @@
+import { delay } from "./theme2.mjs";
+export { delay };

package/dist/_chunks/theme2.mjs

@@ -0,0 +1,149 @@
+import c from "picocolors";
+function fgSky(s) {
+	return `\x1b[38;2;56;189;248m${s}\x1b[0m`;
+}
+function bgSky(s) {
+	return `\x1b[48;2;14;165;233m${s}\x1b[0m`;
+}
+const sky = Object.assign((s) => fgSky(s), {
+	bold: (s) => c.bold(fgSky(s)),
+	bg: (s) => bgSky(s)
+});
+const PALETTE = {
+	primary: sky,
+	success: c.green,
+	error: c.red,
+	warn: c.yellow,
+	info: sky,
+	dim: c.dim,
+	bold: c.bold,
+	text: c.white
+};
+const theme = PALETTE;
+sky(process.stdout.isTTY ? "✓" : "v"), c.red(process.stdout.isTTY ? "✗" : "x"), c.yellow(process.stdout.isTTY ? "⚠" : "!"), sky(process.stdout.isTTY ? "ℹ" : "i"), process.stdout.isTTY, process.stdout.isTTY, process.stdout.isTTY;
+const RESET = "\x1B[0m";
+const GRAYS = [
+	"\x1B[38;5;255m",
+	"\x1B[38;5;252m",
+	"\x1B[38;5;249m",
+	"\x1B[38;5;246m",
+	"\x1B[38;5;243m",
+	"\x1B[38;5;240m"
+];
+function gradLine(line) {
+	const n = line.length || 1;
+	let out = "";
+	for (let i = 0; i < line.length; i++) {
+		const g = GRAYS[Math.min(GRAYS.length - 1, Math.floor(i / n * GRAYS.length))];
+		out += `${g}${line[i]}${RESET}`;
+	}
+	return out;
+}
+const LOGO_LINES = [
+	" █████╗  ██████╗ ███████╗███╗   ██╗████████╗██████╗ ██╗   ██╗",
+	"██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔══██╗╚██╗ ██╔╝",
+	"███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝ ╚████╔╝ ",
+	"██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗  ╚██╔╝  ",
+	"██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██║  ██║   ██║   ",
+	"╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   "
+];
+function logo() {
+	return LOGO_LINES.map((line) => gradLine(line)).join("\n");
+}
+function tagline() {
+	return c.dim("  Install agents, skills, rules & profiles");
+}
+function badge() {
+	return bgSky(c.white(c.bold(" Agentry ")));
+}
+function delay(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+async function animateLogo() {
+	process.stdout.write("\n" + logo() + "\n");
+	process.stdout.write(tagline() + "\n\n");
+	if (process.stdout.isTTY) await delay(280);
+}
+function h(title) {
+	return c.bold(sky(title));
+}
+function cmd(s) {
+	return c.cyan(s);
+}
+function flag(s) {
+	return sky(s);
+}
+function dim(s) {
+	return c.dim(s);
+}
+function bullet(s) {
+	return `  ${sky("•")} ${s}`;
+}
+function printHelp() {
+	const lines = [
+		"",
+		`${badge()}  ${dim("install agents, skills, rules, scripts & profiles")}`,
+		"",
+		h("Usage"),
+		`  ${cmd("agentry")} ${flag("add")}     ${dim("<kind> <source> [selector] [options]")}`,
+		`  ${cmd("agentry")} ${flag("add")}     ${dim("profile <name> [source] [options]")}`,
+		`  ${cmd("agentry")} ${flag("remove")}  ${dim("<kind> [source] [selector] [options]")}`,
+		`  ${cmd("agentry")} ${flag("list")}    ${dim("[source] [kind] [selector]")}`,
+		`  ${cmd("agentry")} ${flag("update")}  ${dim("[kind] [source] [selector]")}`,
+		`  ${cmd("agentry")} ${flag("init")}    ${dim("<kind> [name] [category] [options]")}`,
+		`  ${cmd("agentry")} ${flag("uninstall")}`,
+		"",
+		h("Kinds"),
+		bullet(`${c.bold("skill")}  ${c.bold("rule")}  ${c.bold("agent")}  ${c.bold("profile")}  ${c.bold("script")}  ${dim("(or all)")}`),
+		dim("  Plurals accepted: skills → skill, agents → agent, …"),
+		"",
+		h("Sources"),
+		bullet(`${cmd("author/repo")}              ${dim("GitHub shorthand")}`),
+		bullet(`${cmd("https://github.com/…")}     ${dim("GitHub URL or /tree/<ref>/<dir>")}`),
+		bullet(`${cmd("https://gitlab.com/…")}     ${dim("GitLab URL")}`),
+		bullet(`${cmd("git@host:owner/repo.git")}  ${dim("any git URL")}`),
+		bullet(`${cmd("./path")} ${dim("|")} ${cmd("/path")} ${dim("|")} ${cmd("~/path")}  ${dim("local directory")}`),
+		"",
+		h("Examples"),
+		bullet(`${cmd("agentry add skills")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry add skills")} mhmdreza-rafiei/agent-tools enhance-prompt ${flag("-a")} cursor`),
+		bullet(`${cmd("agentry list")}`),
+		bullet(`${cmd("agentry list skills")}`),
+		bullet(`${cmd("agentry list")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry list")} mhmdreza-rafiei/agent-tools skills`),
+		bullet(`${cmd("agentry list")} mhmdreza-rafiei/agent-tools skills enhance-prompt`),
+		bullet(`${cmd("agentry remove skills")} enhance-prompt`),
+		bullet(`${cmd("agentry remove skills")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry update skills")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry init skill")} enhance-prompt prompt ${flag("--reference")}`),
+		bullet(`${cmd("agentry init profile")} frontend ${flag("--skills")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry init rule")} ask-dont-guess ${flag("--alwaysApply")}`),
+		bullet(`${cmd("agentry update")}`),
+		"",
+		h("Options"),
+		`  ${flag("-g, --global")}     ${dim("Install into ~ (all projects)")}`,
+		`      ${flag("--project")}    ${dim("Install into the current folder (default)")}`,
+		`      ${flag("--dir")} ${dim("<p>")}    ${dim("Install into a specific folder")}`,
+		`  ${flag("-a, --agent")} ${dim("<n>")}  ${dim("Target provider(s); repeatable; '*' = all")}`,
+		`  ${flag("-l, --list")}       ${dim("Preview only — write nothing")}`,
+		`      ${flag("--copy")}       ${dim("Copy files instead of symlinking")}`,
+		`      ${flag("--all")}        ${dim("Install everything to all agents, no prompts")}`,
+		`  ${flag("-y, --yes")}        ${dim("Don't prompt")}`,
+		`      ${flag("--description")} ${dim("<t>")}  ${dim("init: frontmatter description")}`,
+		`      ${flag("--alwaysApply")} ${dim("init rule: alwaysApply: true")}`,
+		`      ${flag("--reference")}  ${dim("init skill: add references/TEMPLATE.md")}`,
+		`      ${flag("--no-reference")} ${dim("init skill: skip references/")}`,
+		`      ${flag("--skills")} ${dim("[src]")} ${dim("init profile: include skills (optional source)")}`,
+		`      ${flag("--agents")} ${dim("[src]")} ${dim("init profile: include agents")}`,
+		`      ${flag("--rules")} ${dim("[src]")}  ${dim("init profile: include rules")}`,
+		`      ${flag("--scripts")} ${dim("[src]")} ${dim("init profile: include scripts")}`,
+		`  ${flag("-v, --version")}    ${dim("Print version")}`,
+		`  ${flag("-h, --help")}       ${dim("Show this help")}`,
+		"",
+		dim("Tip: omit --agent to pick providers interactively (universal locked + searchable list)."),
+		dim("Tip: remove/update accept a GitHub repo or local path to filter by install source."),
+		""
+	];
+	process.stdout.write(lines.join("\n"));
+}
+export { PALETTE, animateLogo, badge, delay, logo, printHelp, sky, tagline, theme };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}