@mhmdreza-rafiei/agentry 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,23 @@
-# 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.
+<img src="docs/agentry-logo.png" alt="agentry" width="800" />
+
+**A raw installer for AI agent tooling.**
+
+`agentry` fetches **agents, skills, rules, scripts, and profiles** from any Git repo (or local path) and installs the ones you pick into your project — or globally — under each target provider's directory (`.cursor/`, `.claude/skills/`, `.agents/skills/`, …). The CLI ships no assets of its own; you point it at a source.
+
+It mirrors the clean Clack-style UX of [`vercel-labs/skills`](https://github.com/vercel-labs/skills) and extends it beyond skills-only. Supports **70+ agent providers**.
+
+[![npm version](https://img.shields.io/npm/v/@mhmdreza-rafiei/agentry.svg?style=flat&color=cyan)](https://www.npmjs.com/package/@mhmdreza-rafiei/agentry)
+[![license](https://img.shields.io/badge/license-MIT-cyan.svg?style=flat)](#license)
+[![node](https://img.shields.io/badge/node-%3E%3D22.20-cyan.svg?style=flat)](#development--test)
+[![stars](https://img.shields.io/github/stars/mhmdreza-rafiei/agentry?style=social)](https://github.com/mhmdreza-rafiei/agentry)
+
+⭐ If agentry saves you time, [star the repo](https://github.com/mhmdreza-rafiei/agentry) — it helps others find it.
+
+</div>
+
+---
 
 ## Install / run
 
@@ -13,82 +30,229 @@ npm install -g agentry@latest
 
 # Update / uninstall the CLI
 agentry update
-agentry --uninstall
+agentry uninstall
 ```
 
-> Publishing to npm is pending. Until then, run from a clone: `node bin/agentry.js …` or `npx . …`.
+> Publishing to npm is pending. Until then, run from a clone: `node dist/cli.mjs …` (after `npm run build`) or `npm run dev -- …`.
 
 ## Usage
 
 ```
-agentry add <type> <source> [category/name | category] [options]
+agentry add <kind> <source> [category/name | category] [options]
 agentry add profile <name> [source] [options]
-agentry remove <type> [category/name | category] [options]
-agentry list <source> [type]
-agentry update
+agentry remove <kind> [category/name | category] [options]
+agentry list [source] [kind]
+agentry update [kind] [source] [selector]
+agentry uninstall
 ```
 
-`<source>` is a GitHub shorthand `author/repo`, a full git URL, or a local path.
+`<kind>` is `skill | rule | agent | profile | script` (singular; plurals like `skills` are accepted and normalized). `<source>` is a GitHub shorthand `author/repo`, a full GitHub URL, a GitHub tree subdir URL, a GitLab URL, any git URL, or a local path.
 
 ```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 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
+agentry add skills ./my-skills --list                            # preview only, no install
+agentry add skills ./my-skills prompt/enhance-prompt -a cursor -a claude-code  # install to 2 providers
+agentry add agents author/repo frontend-developer               # one agent (.mdc file)
+agentry add rules author/repo ask-dont-guess                    # one rule (.mdc file)
+agentry add scripts author/repo lint                            # one script (usecase folder)
+agentry add profile frontend author/repo                        # apply profile/frontend.yaml
+agentry remove skills document-skills/docx                      # remove an installed artifact
+agentry list author/repo
+agentry update                                                  # self-update (checks version first)
+agentry update skills author/repo prompt/enhance-prompt         # re-install one artifact from source
+agentry update skills                                           # re-install all skills from lockfile sources
+agentry uninstall                                               # remove the CLI
 ```
 
-Flags: `-g, --global` (into `~/.cursor`), `--project` (current folder, default), `--dir <path>`, `-y, --yes` (no prompts; install everything matched), `-v, --version`, `-h, --help`, `--uninstall`.
+Flags: `-g, --global` (into `~`), `--project` (current folder, default), `--dir <path>`, `-a, --agent <name>` (repeatable; `*` for all; default: prompt to choose), `-l, --list` (preview, no install), `--copy` (copy files instead of symlinking), `--all` (install everything to all agents, no prompts), `-y, --yes` (no prompts), `-v, --version`, `-h, --help`.
 
-When neither `--global` nor `--project` is given, an interactive terminal asks where to install; non‑interactive runs (agents/CI) default to the current project.
+When you run `agentry add` without `--agent`, it shows a **fetch animation** (parsing source → discovering → found N), lets you **pick artifacts** (with an `All` toggle), then prompts **"Which agents do you want to install to?"** — universal providers (`.agents/skills`) are locked in and others are selectable, defaulting to the providers you already have installed. The interactive UI (animated robot logo, spinners, prompts) is suppressed automatically when running inside an agent or CI; non-interactive runs default to the current project and auto-detected providers.
 
 ## How sources are discovered
 
-For each type, `agentry` finds assets in two ways and merges them:
+For each kind, `agentry` finds artifacts in two ways and merges them:
 
-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. Under an explicit `<kind>s/` folder (see artifact layouts below).
+2. At the repo root by marker — a folder with `SKILL.md` is a skill; a `.mdc` file at root is an agent or rule. (Scripts and profiles are folder/file kinds found only under their `scripts/` and `profiles/` folders.)
 
-Selectors after the source: `category/name` (one asset), `name` (one asset when uncategorized), `category` (whole category), or omit to list-and-pick.
+Selectors after the source: `category/name` (one artifact), `name` (one artifact when uncategorized), `category` (whole category), or omit to list-and-pick.
 
-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.
+Artifacts install to the provider's directory and are tracked in `.agentry/lock.json` for idempotent installs and clean removal. `remove` works purely on installed files, so it needs no source.
 
-## Profiles
+## Artifact layouts (how to create installable tools)
+
+Create artifacts in your repo using these layouts, then `agentry add` from your repo:
 
-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 — folder per skill
 
-```json
-{
-  "repo": "author/repo",
-  "agents":  ["frontend"],
-  "skills":  ["prompt/enhance-prompt"],
-  "rules":   ["workflow/ask-dont-guess"]
-}
+```
+skills/
+  enhance-prompt/
+    SKILL.md            # YAML frontmatter: name, description
+    references/
+      TEMPLATE.md       # optional supporting docs
+    ...
 ```
 
-`repo` is optional — the command-line `<source>` wins when given. See [`profile/frontend.json`](profile/frontend.json) and [`profile/backend.json`](profile/backend.json).
+`SKILL.md` frontmatter:
 
-## Publish to npm (maintainers)
+```yaml
+---
+name: enhance-prompt
+description: Rewrite a user message into a precise, portable agent prompt.
+---
+# enhance-prompt
+Instructions for the agent...
+```
+
+Categorized skills: `skills/<category>/<name>/SKILL.md`.
+
+### Agents — single `.mdc` file
+
+```
+agents/
+  frontend-developer.mdc
+```
+
+`.mdc` frontmatter (same shape as skills):
+
+```yaml
+---
+name: frontend-developer
+description: Senior frontend engineer agent.
+---
+# frontend-developer
+Agent instructions...
+```
+
+Categorized agents: `agents/<category>/<name>.mdc`.
+
+### Rules — single `.mdc` file
+
+```
+rules/
+  ask-dont-guess.mdc
+```
+
+Same frontmatter and body shape as agents. Categorized rules: `rules/<category>/<name>.mdc`.
+
+### Scripts — folder per use case
+
+```
+scripts/
+  lint/
+    run.js            # entrypoint (any language; a folder with files = one script)
+    README.md         # optional docs
+  format/
+    run.js
+```
+
+A script is a **folder** containing its files (entrypoint, helpers, docs). Categorized scripts: `scripts/<category>/<usecase>/`.
+
+### Profiles — single `.yaml` file (in a source repo)
+
+```
+profiles/
+  frontend.yaml
+```
+
+A profile bundles artifact selectors + target agents + scope into one config. See the **Profiles** section below for the schema. Categorized profiles: `profiles/<category>/<name>.yaml`.
+
+## How to install tools with agentry
 
 ```bash
-# ensure package.json "name" is available (or scope it: @you/agentry)
-npm login
-npm publish --access public
-# verify
-npx agentry@latest --version
+# From a GitHub repo (author/repo shorthand)
+agentry add skills Prat011/awesome-llm-skills
+
+# From a full GitHub URL
+agentry add skills https://github.com/Prat011/awesome-llm-skills
+
+# From a subdirectory of a repo (GitHub tree URL)
+agentry add skills https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design
+
+# From a GitLab URL
+agentry add skills https://gitlab.com/org/repo
+
+# From any git URL
+agentry add skills git@github.com:owner/repo.git
+
+# From a local path
+agentry add skills ./my-skills
+
+# Install to specific providers
+agentry add skills ./my-skills enhance-prompt --agent cursor --agent claude-code
+
+# Install to all providers
+agentry add skills ./my-skills enhance-prompt --agent '*'
+
+# Preview without installing
+agentry add skills ./my-skills --list
+```
+
+## Supported providers
+
+`agentry` installs into 70+ agent providers, mirroring vercel-labs/skills. Each provider has a project skills directory and a global one. A few common ones:
+
+| Provider       | `--agent`        | Project path        | Global path                   |
+| -------------- | ---------------- | ------------------- | ----------------------------- |
+| Cursor         | `cursor`         | `.agents/skills/`   | `~/.cursor/skills/`           |
+| Claude Code    | `claude-code`    | `.claude/skills/`   | `~/.claude/skills/`           |
+| Codex          | `codex`          | `.agents/skills/`   | `~/.codex/skills/`            |
+| OpenCode       | `opencode`       | `.agents/skills/`   | `~/.config/opencode/skills/`  |
+| Gemini CLI     | `gemini-cli`     | `.agents/skills/`   | `~/.gemini/skills/`           |
+| Windsurf       | `windsurf`       | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
+| Cline          | `cline`          | `.agents/skills/`   | `~/.agents/skills/`           |
+| Amp            | `amp`            | `.agents/skills/`   | `~/.config/agents/skills/`    |
+| Goose          | `goose`          | `.goose/skills/`    | `~/.config/goose/skills/`     |
+| Roo Code       | `roo`            | `.roo/skills/`      | `~/.roo/skills/`              |
+| GitHub Copilot | `github-copilot` | `.agents/skills/`   | `~/.copilot/skills/`          |
+| Augment        | `augment`        | `.augment/skills/`  | `~/.augment/skills/`          |
+| Continue       | `continue`       | `.continue/skills/` | `~/.continue/skills/`         |
+| Zed            | `zed`            | `.agents/skills/`   | `~/.agents/skills/`           |
+| Warp           | `warp`           | `.agents/skills/`   | `~/.agents/skills/`           |
+
+...and 55+ more. The CLI auto-detects installed providers; pass `--agent` to target specific ones or `--agent '*'` for all.
+
+### Universal install (`.agents/skills`)
+
+Providers whose skills directory is `.agents/skills/` (Cursor, Codex, OpenCode, Gemini CLI, Cline, Amp, Zed, Warp, GitHub Copilot, …) are **universal**: a skill is installed **once** to `.agents/skills/<id>` and every universal provider reads it from there. Non-universal providers (Claude Code, Windsurf, Goose, Roo, Augment, Continue, …) get a **symlink** from their own skills directory to the canonical `.agents/skills/<id>` copy, so a single install reaches all of them with no duplication. Use `--copy` to make independent copies instead of symlinks.
+
+## Profiles
+
+A profile is a YAML file at `profile/<name>.yaml` in your project. It bundles artifact selectors, target agents, and scope; `agentry add profile <name> <source>` fetches the source once and installs everything the profile lists.
+
+```yaml
+name: frontend
+description: Frontend agents, rules, and skills
+scope: project # project | global
+targets:
+  agents: [cursor, claude-code] # target providers; '*' = all
+artifacts:
+  skills:
+    - id: prompt/enhance-prompt
+  agents:
+    - id: frontend-developer
+  rules:
+    - id: ask-dont-guess
+  scripts:
+    - id: lint
 ```
 
+Each artifact ref may override the CLI source with its own `source:`. The command-line `<source>` is the default for refs without one.
+
 ## Development / test
 
 ```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 run typecheck        # tsc --noEmit
+npm test                 # vitest (discovery, source parser, agents registry, install/remove, profiles)
+npm run build            # obuild -> dist/cli.mjs
+npm run dev -- …         # run via tsx (no build needed)
+node dist/cli.mjs …      # run the built CLI
 ```
 
-`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).
+`src/` holds the logic: `cli.ts` (router), `commands.ts` (handlers), `core/` (types, source-parser, git, lock), `registry/agents.ts` (70+ providers), `artifacts/` (discovery, profiles), `ui/` (theme, prompts, detect). Runtime deps are minimal and UI libs are bundled by `obuild`.
 
 ## License
 

package/dist/_chunks/source_parser.mjs

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

package/dist/_chunks/source_parser2.mjs

@@ -0,0 +1,74 @@
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+function isLocalPath(source) {
+	if (!source) return false;
+	if (source === "." || source === "..") return true;
+	if (source.startsWith("./") || source.startsWith("../") || source.startsWith("/") || source.startsWith("~")) return true;
+	try {
+		return existsSync(source) && statSync(source).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function parseGithubTreeUrl(url) {
+	const m = url.match(/^https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)\/tree\/([^/]+)\/(.+)$/);
+	if (!m) return null;
+	return {
+		ownerRepo: m[1],
+		ref: m[2],
+		subpath: m[3].replace(/\/+$/, "")
+	};
+}
+function parseSource(source) {
+	if (!source || typeof source !== "string") throw new Error("Empty source.");
+	const raw = source;
+	if (isLocalPath(source)) return {
+		kind: "local",
+		raw,
+		url: null,
+		subpath: "",
+		local: resolve(source.replace(/^~/, homedir()))
+	};
+	const tree = parseGithubTreeUrl(source);
+	if (tree) return {
+		kind: "github-url",
+		raw,
+		url: `https://github.com/${tree.ownerRepo}.git`,
+		subpath: tree.subpath,
+		ref: tree.ref,
+		local: null
+	};
+	let m = source.match(/^https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/);
+	if (m) return {
+		kind: "github-url",
+		raw,
+		url: `https://github.com/${m[1]}.git`,
+		subpath: "",
+		local: null
+	};
+	m = source.match(/^https?:\/\/gitlab\.com\/([\w./-]+?)(?:\.git)?\/?$/);
+	if (m) return {
+		kind: "gitlab-url",
+		raw,
+		url: `https://gitlab.com/${m[1]}.git`,
+		subpath: "",
+		local: null
+	};
+	if (source.startsWith("git@") || /^https?:\/\/.*\.git$/.test(source)) return {
+		kind: "git-url",
+		raw,
+		url: source,
+		subpath: "",
+		local: null
+	};
+	if (/^[\w.-]+\/[\w.-]+$/.test(source)) return {
+		kind: "github-shorthand",
+		raw,
+		url: `https://github.com/${source}.git`,
+		subpath: "",
+		local: null
+	};
+	throw new Error(`Cannot parse source "${source}". Use author/repo, a GitHub/GitLab URL, a git URL, or a local path.`);
+}
+export { isLocalPath, parseSource };

package/dist/_chunks/theme.mjs

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

package/dist/_chunks/theme2.mjs

@@ -0,0 +1,123 @@
+import c from "picocolors";
+const PALETTE = {
+	primary: c.blue,
+	success: c.green,
+	error: c.red,
+	warn: c.yellow,
+	info: c.blue,
+	dim: c.dim,
+	bold: c.bold,
+	text: c.white
+};
+const theme = PALETTE;
+c.blue(process.stdout.isTTY ? "✓" : "v"), c.red(process.stdout.isTTY ? "✗" : "x"), c.yellow(process.stdout.isTTY ? "⚠" : "!"), c.blue(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 c.bgBlue(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(c.blue(title));
+}
+function cmd(s) {
+	return c.cyan(s);
+}
+function flag(s) {
+	return c.blue(s);
+}
+function dim(s) {
+	return c.dim(s);
+}
+function bullet(s) {
+	return `  ${c.blue("•")} ${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> [selector] [options]")}`,
+		`  ${cmd("agentry")} ${flag("list")}    ${dim("[source] [kind]")}`,
+		`  ${cmd("agentry")} ${flag("update")}  ${dim("[kind] [source] [selector]")}`,
+		`  ${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")} Prat011/awesome-llm-skills`),
+		bullet(`${cmd("agentry add skills")} ./my-skills ${flag("--list")}`),
+		bullet(`${cmd("agentry add skills")} ./my-skills enhance-prompt ${flag("-a")} cursor ${flag("-a")} claude-code`),
+		bullet(`${cmd("agentry add agents")} author/repo frontend-developer`),
+		bullet(`${cmd("agentry add profile")} frontend author/repo`),
+		bullet(`${cmd("agentry remove skills")} enhance-prompt`),
+		bullet(`${cmd("agentry update")}`),
+		bullet(`${cmd("agentry update skills")} author/repo enhance-prompt`),
+		"",
+		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("-v, --version")}    ${dim("Print version")}`,
+		`  ${flag("-h, --help")}       ${dim("Show this help")}`,
+		"",
+		dim("Tip: omit --agent to pick providers interactively (universal locked + searchable list)."),
+		""
+	];
+	process.stdout.write(lines.join("\n"));
+}
+export { PALETTE, animateLogo, badge, delay, logo, printHelp, tagline, theme };

package/dist/cli.d.mts

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