@aipm-registry/cli 0.2.2 → 0.2.13

package/README.md

@@ -1,7 +1,25 @@
+# Search the registry at [aipm-registry.com](https://aipm-registry.com) for a skill
+
+
 # AIPM CLI
 
-AIPM installs project-ready AI skills into supported tools such as Cursor and
-Claude.
+**An Open source command-line tool for AI skills management and discovery [AIPM](https://aipm-registry.com)**
+
+## What is this?
+
+AI coding tools like Cursor and Claude can follow **skills**: small instruction files that teach the assistant how to do a job (code review, release notes, issue summaries, and more).
+
+AIPM makes skills easy to **find, install, and share** — like npm, but for AI skills.
+
+This package gives you the `aipm` command. With it you can:
+
+- **Browse and install** skills from the public registry at **[aipm-registry.com](https://aipm-registry.com)**
+- **Add skills to your project** so your whole team uses the same instructions
+- **Publish your own skills** so others can install them
+
+No other AIPM packages are required — everything is bundled in one install.
+
+**Supported tools today:** Cursor and Claude (more targets at [aipm-registry.com/targets](https://aipm-registry.com/targets)).
 
 ## Install
 
@@ -9,91 +27,109 @@ Claude.
 npm install -g @aipm-registry/cli
 aipm --version
 aipm doctor
-aipm config
 ```
 
-## Use
+`aipm doctor` checks that your setup is ready. Run it if something does not work.
 
-Initialize a project:
+## Install skills in your project
+
+Start in any project folder:
 
 ```bash
 aipm init
 ```
 
-Install a skill from the public registry:
+*Search the registry at [aipm-registry.com](https://aipm-registry.com) for a skill:*
 
 ```bash
-aipm add @scope/name@1.0.0 --target cursor --ci
+aipm search sentry
 ```
 
-List installed skills:
+Results show version, supported tools, description, publisher, license, and size.
+
+Install a skill:
 
 ```bash
-aipm list
+aipm add @scope/name@1.0.0 --target cursor
 ```
 
-Search the registry:
+See what is installed:
 
 ```bash
-aipm search sentry
+aipm list
 ```
 
-Search results include package version, supported targets, description,
-publisher identity when available, license, and package size.
-
 Update installed skills:
 
 ```bash
 aipm update
 ```
 
-This package is bundled. Installing `@aipm-registry/cli` gives you the `aipm`
-command without needing to install any other AIPM npm packages manually.
+Browse more packages on the website: **[aipm-registry.com](https://aipm-registry.com)**
+
+## Publish your skill (public / private / organization-only)
 
-Publish a public skill:
+Share a skill with your team or the public registry.
+
+1. Create a free account at **[aipm-registry.com](https://aipm-registry.com)**
+2. Create an org and reserve your package name (for example `@team/review-helper`)
+3. Scaffold a new skill package:
 
 ```bash
 aipm publish init --name @team/review-helper --template code-review
 cd review-helper
-aipm publish explain # (optional)
+```
+
+1. Add your files and push:
+
+```bash
 aipm publish add .
-aipm publish status # (optional)
-aipm publish preview # (optional)
-aipm publish validate # (optional)
-aipm publish token --package @team/review-helper # (optional)
+aipm publish preview    # optional — see what will be uploaded
+aipm publish validate   # optional — check for problems
 AIPM_TOKEN=<5-minute-token> aipm publish push --yes
 ```
 
-Create an account on `https://aipm-registry.com`, create an org, reserve the
-package name, and generate the 5-minute token from the package dashboard.
+Get the short-lived publish token from your package page on **[aipm-registry.com/dashboard](https://aipm-registry.com/dashboard)**.
+
+**Starter templates:** `blank`, `code-review`, `issue-summary`, `release-notes`. They only set the initial `SKILL.md` — edit any file before publishing.
+
+**Already have a skill file?** Import it into an AIPM package:
 
-Use `.aipmignore` to exclude local-only files from publishing. AIPM also
-rejects common private key, env, Azure connection string, publish profile, and
-large package mistakes before upload.
+```bash
+aipm publish import ~/.codex/skills/review-helper --name @team/review-helper
+cd review-helper
+aipm publish add .
+```
 
-Helpful publishing commands:
+**Helpful extras:**
 
 ```bash
-aipm publish init --name @team/issue-summary --template issue-summary
-aipm publish init --name @team/release-notes --template release-notes
-aipm publish open --docs # (optional)
-aipm publish open --package @team/review-helper # (optional)
-aipm doctor --publish # (optional)
+aipm publish explain              # what publishing does
+aipm publish status               # staged files
+aipm publish token --package @team/review-helper
+aipm publish open --docs          # open publishing docs
+aipm publish open --package @team/review-helper
+aipm doctor --publish             # check publish setup
 ```
 
-Starter templates are `blank`, `code-review`, `issue-summary`, and
-`release-notes`. They only change the starter `SKILL.md`; you can edit every
-file before staging and publishing.
+Use `.aipmignore` to skip local-only files. Before upload, AIPM blocks common mistakes such as private keys, `.env` files, and oversized packages.
 
-If your AI tool already generated a skill or rule file, import it into an AIPM package folder:
+Full publishing guide: **[aipm-registry.com/publish](https://aipm-registry.com/publish)**
+
+## Configuration
 
 ```bash
-aipm publish import ~/.codex/skills/review-helper --name @team/review-helper
-cd review-helper
-aipm publish add .
-aipm publish preview # (optional)
+aipm config
 ```
 
-The default registry API is `https://api.aipm-registry.com`. Use `--registry <url>`,
-`AIPM_REGISTRY_URL=<url>`, or `AIPM_REGISTRY=<url>` for local or private
-registries.
+Default registry API: `https://api.aipm-registry.com`
+
+For a local or private registry, use `--registry <url>`, or set `AIPM_REGISTRY_URL` / `AIPM_REGISTRY`.
+
+## Links
+
+- **Registry & browse skills:** [aipm-registry.com](https://aipm-registry.com)
+- **Publishing guide:** [aipm-registry.com/publish](https://aipm-registry.com/publish)
+- **Docs & examples:** [aipm-registry.com/examples](https://aipm-registry.com/examples)
+- **Source code:** [github.com/aipm-registry/aipm](https://github.com/aipm-registry/aipm)
+

package/dist/bin.cjs

@@ -4176,7 +4176,8 @@ var init_manifest = __esm({
       description: external_exports.string().min(1),
       entry: external_exports.string().min(1),
       targets: external_exports.array(AiToolSchema).min(1),
-      license: external_exports.string().optional()
+      license: external_exports.string().optional(),
+      usage: external_exports.string().min(1).optional()
     });
   }
 });
@@ -8015,6 +8016,10 @@ function registryFetchError(registry, cause) {
   }
   return new Error(`Registry request failed (${registry}): ${msg}`);
 }
+function registryAuthHeaders(token) {
+  if (!token) return void 0;
+  return { Authorization: `Bearer ${token}` };
+}
 async function registryFetch(url, registry, init) {
   const timeoutSignal = typeof AbortSignal !== "undefined" && "timeout" in AbortSignal ? AbortSignal.timeout(1e4) : void 0;
   try {
@@ -8023,6 +8028,12 @@ async function registryFetch(url, registry, init) {
     throw registryFetchError(registry, e);
   }
 }
+function privateInstallHint(name, status, token) {
+  if (status !== 404 || !name.startsWith("@") || token) {
+    return `Package not found: ${name} (${status})`;
+  }
+  return `Package not found: ${name} (${status}). If @org/pkg is private, set AIPM_TOKEN with an install token from the dashboard.`;
+}
 async function assertRegistryReachable(registry) {
   const base = registry.replace(/\/$/, "");
   const res = await registryFetch(`${base}/health`, base);
@@ -8053,19 +8064,19 @@ async function searchPackages(registry, query, limit = 20) {
   const data = await res.json();
   return data.packages ?? [];
 }
-async function fetchPackageMetadata(registry, name, version) {
+async function fetchPackageMetadata(registry, name, version, token) {
   const base = registry.replace(/\/$/, "");
   const url = `${base}/v1/packages/${encodePackageName(name)}/versions/${version}`;
-  const res = await registryFetch(url, base);
-  if (!res.ok) throw new Error(`Package not found: ${name}@${version} (${res.status})`);
+  const res = await registryFetch(url, base, { headers: registryAuthHeaders(token) });
+  if (!res.ok) throw new Error(privateInstallHint(`${name}@${version}`, res.status, token));
   const data = await res.json();
-  return { manifest: data.manifest, integrity: data.integrity };
+  return { manifest: data.manifest, integrity: data.integrity, deprecated: data.deprecated ?? null };
 }
-async function fetchPackageTarball(registry, name, version) {
+async function fetchPackageTarball(registry, name, version, token) {
   const base = registry.replace(/\/$/, "");
   const url = `${base}/v1/packages/${encodePackageName(name)}/versions/${version}/tarball`;
-  const res = await registryFetch(url, base);
-  if (!res.ok) throw new Error(`Tarball not found: ${name}@${version} (${res.status})`);
+  const res = await registryFetch(url, base, { headers: registryAuthHeaders(token) });
+  if (!res.ok) throw new Error(privateInstallHint(`${name}@${version}`, res.status, token));
   const ab = await res.arrayBuffer();
   return Buffer.from(ab);
 }
@@ -8163,11 +8174,17 @@ async function installOnePackage(options) {
   const configRoot = options.configRoot;
   const installRoot = options.installRoot ?? configRoot;
   await assertRegistryReachable(options.registry);
-  const { manifest, integrity: remoteIntegrity } = await fetchPackageMetadata(
+  const { manifest, integrity: remoteIntegrity, deprecated } = await fetchPackageMetadata(
     options.registry,
     options.name,
-    options.version
+    options.version,
+    options.token
   );
+  if (deprecated) {
+    console.warn(
+      `Warning: ${options.name} is deprecated${deprecated.message ? `: ${deprecated.message}` : ""}.`
+    );
+  }
   let explicitTarget = options.explicitTarget;
   let preferredTools = options.project.preferredTools;
   const { resolveInstallTools: resolveInstallTools2 } = await Promise.resolve().then(() => (init_dist4(), dist_exports));
@@ -8196,7 +8213,8 @@ async function installOnePackage(options) {
   const tarball = await fetchPackageTarball(
     options.registry,
     options.name,
-    options.version
+    options.version,
+    options.token
   );
   const skillMarkdown = await unpackTarballToBuffer(tarball, manifest.entry);
   const result = await installSkillPackage({
@@ -8543,6 +8561,26 @@ async function inferEntryFromSource(source, fallback) {
   if (entries.includes(fallback)) return fallback;
   return entries.find((entry) => entry.endsWith(".md")) ?? entries.find((entry) => entry.endsWith(".mdc")) ?? fallback;
 }
+async function copySourceIntoSkillRoot(source, root, sourceLabel) {
+  const sourceInfo = await (0, import_promises9.stat)(source);
+  await (0, import_promises9.mkdir)(root, { recursive: true });
+  if (sourceInfo.isDirectory()) {
+    const entries = await (0, import_promises9.readdir)(source);
+    for (const entry of entries) {
+      await (0, import_promises9.cp)((0, import_node_path11.join)(source, entry), (0, import_node_path11.join)(root, entry), {
+        recursive: true,
+        force: false,
+        errorOnExist: true
+      });
+    }
+    return;
+  }
+  if (sourceInfo.isFile()) {
+    await (0, import_promises9.cp)(source, (0, import_node_path11.join)(root, (0, import_node_path11.basename)(source)), { force: false, errorOnExist: true });
+    return;
+  }
+  throw new Error(`Unsupported source path: ${sourceLabel}`);
+}
 async function latestVersionForPackage(registry, name) {
   const packages = await searchPackages(registry, name, 20);
   const exact = packages.find((pkg) => pkg.name === name);
@@ -8694,7 +8732,6 @@ async function initSkill(opts) {
   if (!isValidScopeName(opts.name)) throw new Error("Invalid @scope/name");
   const root = opts.here ? (0, import_node_process5.cwd)() : (0, import_node_path11.resolve)((0, import_node_process5.cwd)(), opts.dir ?? skillFolderName(opts.name));
   const cdTarget = opts.here ? null : opts.dir ?? skillFolderName(opts.name);
-  await (0, import_promises9.mkdir)(root, { recursive: true });
   const source = opts.from ? (0, import_node_path11.resolve)(opts.from) : null;
   const entry = source ? await inferEntryFromSource(source, opts.entry) : opts.entry;
   const manifest = PackageManifestSchema.parse({
@@ -8708,14 +8745,9 @@ async function initSkill(opts) {
     license: "Apache-2.0"
   });
   if (source) {
-    const sourceInfo = await (0, import_promises9.stat)(source);
-    if (sourceInfo.isDirectory()) {
-      await (0, import_promises9.cp)(source, root, { recursive: true, force: false, errorOnExist: true });
-    } else if (sourceInfo.isFile()) {
-      await (0, import_promises9.cp)(source, (0, import_node_path11.join)(root, (0, import_node_path11.basename)(source)), { force: false, errorOnExist: true });
-    } else {
-      throw new Error(`Unsupported source path: ${opts.from}`);
-    }
+    await copySourceIntoSkillRoot(source, root, source);
+  } else {
+    await (0, import_promises9.mkdir)(root, { recursive: true });
   }
   await writeStarterFile((0, import_node_path11.join)(root, "aipm.manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
   if (!opts.from) {
@@ -8823,7 +8855,7 @@ program2.command("config").description("Show resolved AIPM CLI and project confi
   console.log(`Installed packages: ${data.installedPackages.length}`);
   console.log(`Publish guide: ${data.publishDoc}`);
 });
-program2.command("add <package>").description("Add and install a package @scope/name[@version]").option(GLOBAL_OPTION, GLOBAL_OPTION_DESC).option("--registry <url>", "Registry base URL").option("--target <tool>", "cursor, claude, or *").option("--ci", "Non-interactive; fail if prompt needed").action(async (pkgArg, opts) => {
+program2.command("add <package>").description("Add and install a package @scope/name[@version]").option(GLOBAL_OPTION, GLOBAL_OPTION_DESC).option("--registry <url>", "Registry base URL").option("--target <tool>", "cursor, claude, or *").option("--token <token>", "Install token for private packages").option("--ci", "Non-interactive; fail if prompt needed").action(async (pkgArg, opts) => {
   const { name, version: requestedVersion } = parsePackageArg(pkgArg);
   const scope = { global: opts.global };
   const configRoot = resolveConfigRoot(scope);
@@ -8846,7 +8878,8 @@ program2.command("add <package>").description("Add and install a package @scope/
     version: version.replace(/^\^/, ""),
     project,
     explicitTarget: parseTargetFlag(opts.target),
-    ci: opts.ci
+    ci: opts.ci,
+    token: opts.token ?? process.env.AIPM_TOKEN
   });
   if (!opts.ci && !program2.opts().quiet) {
     await notifyCliUpdateIfNeeded(CLI_VERSION);
@@ -8871,7 +8904,7 @@ program2.command("search [query]").description("Search public registry packages"
     console.log(`  ${meta}`);
   }
 });
-program2.command("install").description("Install all packages from aipm.package.json").option(GLOBAL_OPTION, GLOBAL_OPTION_DESC).option("--registry <url>", "Registry base URL").option("--target <tool>", "cursor, claude, or *").option("--ci", "Non-interactive").action(async (opts) => {
+program2.command("install").description("Install all packages from aipm.package.json").option(GLOBAL_OPTION, GLOBAL_OPTION_DESC).option("--registry <url>", "Registry base URL").option("--target <tool>", "cursor, claude, or *").option("--token <token>", "Install token for private packages").option("--ci", "Non-interactive").action(async (opts) => {
   const scope = { global: opts.global };
   const configRoot = resolveConfigRoot(scope);
   const installRoot = resolveInstallRoot(scope);
@@ -8888,7 +8921,8 @@ program2.command("install").description("Install all packages from aipm.package.
       version: version.replace(/^\^/, ""),
       project,
       explicitTarget: target,
-      ci: opts.ci
+      ci: opts.ci,
+      token: opts.token ?? process.env.AIPM_TOKEN
     });
   }
 });