agent-ctrl-cli 0.1.1 → 0.1.6

package/README.md

@@ -2,14 +2,34 @@
 
 # agent-ctrl
 
-[![Bun](https://img.shields.io/badge/Bun-000000?style=flat&logo=bun&logoColor=white)](https://bun.sh)
-[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](./LICENSE)
+[![NPM Downloads](https://img.shields.io/npm/dm/agent-ctrl-cli)](https://www.npmjs.com/package/agent-ctrl-cli)
 [![GitHub stars](https://img.shields.io/github/stars/ahmet-cetinkaya/agent-ctrl?style=social)](https://github.com/ahmet-cetinkaya/agent-ctrl/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/ahmet-cetinkaya/agent-ctrl?style=social)](https://github.com/ahmet-cetinkaya/agent-ctrl/network/members)
+[![GitHub contributors](https://img.shields.io/github/contributors/ahmet-cetinkaya/agent-ctrl)](https://github.com/ahmet-cetinkaya/agent-ctrl/graphs/contributors)
+[![GitHub issues](https://img.shields.io/github/issues/ahmet-cetinkaya/agent-ctrl)](https://github.com/ahmet-cetinkaya/agent-ctrl/issues)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?logo=buy-me-a-coffee&logoColor=black&style=flat)](https://ahmetcetinkaya.me/donate)
 
 A centralized CLI tool for managing AI agent configurations using a **standard directory-based configuration pattern**. Define agent behavior through rules, skills, agents, commands, and MCP servers in a structured, shareable way that works across multiple AI platforms.
 
-**Status:** 🚧 Early Development phase.
+**Download:**
+[![NPM Release](https://img.shields.io/npm/v/agent-ctrl-cli?color=cb3837)](https://www.npmjs.com/package/agent-ctrl-cli)
+[![GitHub release](https://img.shields.io/github/v/release/ahmet-cetinkaya/agent-ctrl)](https://github.com/ahmet-cetinkaya/agent-ctrl/releases)
+
+**Supported platforms:**
+![Antigravity](https://img.shields.io/badge/Antigravity-black)
+![Claude Code](https://img.shields.io/badge/Claude%20Code-D49A5A)
+![Codex](https://img.shields.io/badge/Codex-black)
+![Cursor](https://img.shields.io/badge/Cursor-black)
+![Gemini](https://img.shields.io/badge/Gemini-4285F4)
+![KiloCode](https://img.shields.io/badge/KiloCode-F8F674)
+![OpenCode](https://img.shields.io/badge/OpenCode-black)
+![QwenCode](https://img.shields.io/badge/QwenCode-6C63F5)
+![Windsurf](https://img.shields.io/badge/Windsurf-007ACC)
+
+**Core Techs:**
+[![Bun](https://img.shields.io/badge/Bun-000000?style=flat&logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 
 ---
 
@@ -50,18 +70,6 @@ agent-ctrl apply claude
 - `init [path]` - Initialize the global configuration structure (default: `~/.agent-ctrl`).
 - `apply <platform>` - Sync local artifacts to a platform's native configuration.
 
-**Supported platforms:**
-
-![Antigravity](https://img.shields.io/badge/Antigravity-black)
-![Claude Code](https://img.shields.io/badge/Claude%20Code-D49A5A)
-![Codex](https://img.shields.io/badge/Codex-black)
-![Cursor](https://img.shields.io/badge/Cursor-black)
-![Gemini](https://img.shields.io/badge/Gemini-4285F4)
-![KiloCode](https://img.shields.io/badge/KiloCode-F8F674)
-![OpenCode](https://img.shields.io/badge/OpenCode-black)
-![QwenCode](https://img.shields.io/badge/QwenCode-6C63F5)
-![Windsurf](https://img.shields.io/badge/Windsurf-007ACC)
-
 ### Artifact Management
 
 #### Rules (`rules/`)
@@ -83,7 +91,7 @@ Capabilities following the `SKILL.md` standard.
 
 #### Commands (`commands/`)
 
-Grouped command prompts or scripts.
+Grouped command prompts or scripts (mapped to skills for Codex).
 
 - `agent-ctrl command ls` - List available commands.
 

package/dist/index.js

@@ -3471,6 +3471,28 @@ function createMissingApiKeyError(registryName, envVarName) {
   }
   return new Error(`${registryName} API key is missing. Configure ${envVarName} in .agent-ctrl/.env or pass --api-key.`);
 }
+function createSkillNotFoundError(skillRef, cause) {
+  const baseMessage = `Skill "${skillRef}" could not be found.`;
+  const hint = `Try: agent-ctrl skill search <query> to find available skills.`;
+  const causeSuffix = cause ? `
+Cause: ${cause}` : "";
+  return new Error(`${baseMessage}${causeSuffix}
+
+${hint}`);
+}
+function createSkillAccessBlockedError(skillRef) {
+  return new Error(`The SkillsMP service is blocking requests for "${skillRef}".
+
+` + `Hint: The service may be restricting access from this environment.
+` + `Try: agent-ctrl skill search <query> to find available skills locally.`);
+}
+function createSkillRepositoryNotAccessibleError(skillRef, repositoryUrl) {
+  return new Error(`The repository for "${skillRef}" could not be accessed.
+
+` + `Expected repository: ${repositoryUrl}
+
+` + `Hint: Verify the repository exists and is publicly accessible, or search ` + `for an alternative skill using: agent-ctrl skill search <query>`);
+}
 
 // src/infrastructure/features/catalog/clients/SkillsMpClient.ts
 class SkillsMpClient {
@@ -3589,14 +3611,21 @@ class SkillsMpClient {
             }
           });
         }
+        const repositoryUrl = slugFallbackRecord.metadata?.repository;
+        if (typeof repositoryUrl === "string") {
+          return err(createSkillRepositoryNotAccessibleError(skillId, repositoryUrl));
+        }
       }
       const detailUrl = exact?.sourceUrl ?? `${this.baseUrl}/skills/${skillId}`;
       const detailResponse = await this.fetchText(detailUrl, apiKey);
       if (!detailResponse.success) {
+        if (detailResponse.error.message.includes("403") || detailResponse.error.message.includes("blocked")) {
+          return err(createSkillAccessBlockedError(skillId));
+        }
         if (exact) {
           return ok({ ...exact, installation: exact.metadata?.installation });
         }
-        return detailResponse;
+        return err(createSkillNotFoundError(skillId, detailResponse.error.message));
       }
       if (this.isCloudflareBlockPage(detailResponse.data) && exact) {
         return ok({ ...exact, installation: exact.metadata?.installation });
@@ -3810,7 +3839,8 @@ class SkillsMpClient {
         repository: guessedUrl,
         raw: {
           resolver: "slug-repository-fallback",
-          sourceSkillId: skillId
+          sourceSkillId: skillId,
+          warning: `This skill was resolved from a GitHub path format. Verify the repository exists at: ${guessedUrl}`
         }
       }
     };
@@ -7533,12 +7563,13 @@ async function syncRulesAsFiles(rules, targetRoot, renderer, dryRun) {
   }));
   return syncRenderedFiles(targetRoot, rendered, dryRun);
 }
-async function syncCommandsAsMarkdown(commands, targetRoot, dryRun, renderer) {
+async function syncCommandsAsMarkdown(commands, targetRoot, dryRun, renderer, flattenSeparator) {
   const commandRenderer = renderer ?? CommandRendererFactory.getRenderer("opencode");
   const rendered = await Promise.all(commands.map(async (command) => {
     const source = await readFile5(command.path, "utf-8");
+    const relativePath = flattenSeparator ? `${command.id.replaceAll("/", flattenSeparator)}${commandRenderer.fileExtension}` : `${command.id}${commandRenderer.fileExtension}`;
     return {
-      relativePath: `${command.id}${commandRenderer.fileExtension}`,
+      relativePath,
       content: commandRenderer.renderCommand(source, command.id)
     };
   }));
@@ -7555,6 +7586,29 @@ async function syncCommandsAsToml(commands, targetRoot, dryRun, renderer) {
   }));
   return syncRenderedFiles(targetRoot, rendered, dryRun);
 }
+async function syncCommandsAsSkills(commands, targetRoot, dryRun) {
+  let changed = false;
+  const paths = [];
+  for (const command of commands) {
+    const source = await readFile5(command.path, "utf-8");
+    const skillName = command.id.replaceAll("/", "-");
+    const parsed = parseMarkdownPrompt(source, command.id);
+    const skillMd = ["---", `name: ${skillName}`, `description: ${parsed.description}`, "---", "", source.trim()].join(`
+`);
+    const skillDir = resolve20(targetRoot, skillName);
+    const targetPath = resolve20(skillDir, "SKILL.md");
+    const existing = await readTextFileOrNull(targetPath);
+    if (normalizeText(existing ?? "") === normalizeText(skillMd)) {
+      continue;
+    }
+    changed = true;
+    paths.push(targetPath);
+    if (!dryRun) {
+      await writeTextFile(targetPath, skillMd);
+    }
+  }
+  return { changed, paths };
+}
 async function syncCommandsAsWorkflows(commands, targetRoot, dryRun, renderer) {
   const commandRenderer = renderer ?? CommandRendererFactory.getRenderer("workflow");
   const rendered = await Promise.all(commands.map(async (command) => {
@@ -7577,6 +7631,27 @@ async function syncSkills(skills, targetRoot, dryRun, compatibility, renderer) {
   }
   return { changed, paths };
 }
+async function syncAgentsAsCodexToml(agents, targetRoot, dryRun) {
+  let changed = false;
+  const paths = [];
+  for (const agent of agents) {
+    const source = await readFile5(agent.path, "utf-8");
+    const parsed = parseMarkdownPrompt(source, agent.id);
+    const agentName = agent.id.replaceAll("/", "-");
+    const tomlContent = buildCodexAgentToml(agentName, parsed);
+    const targetPath = resolve20(targetRoot, `${agentName}.toml`);
+    const existing = await readTextFileOrNull(targetPath);
+    if (normalizeText(existing ?? "") === normalizeText(tomlContent)) {
+      continue;
+    }
+    changed = true;
+    paths.push(targetPath);
+    if (!dryRun) {
+      await writeTextFile(targetPath, tomlContent);
+    }
+  }
+  return { changed, paths };
+}
 async function syncAgentsAsMarkdown(agents, targetRoot, dryRun, withFrontmatter, renderer) {
   const commandRenderer = renderer ?? CommandRendererFactory.getRenderer("opencode");
   const rendered = await Promise.all(agents.map(async (agent) => {
@@ -7716,6 +7791,21 @@ function renderSkillMarkdown(source, skillName, compatibility, renderer) {
   return lines.join(`
 `);
 }
+function buildCodexAgentToml(name, parsed) {
+  const lines = [
+    `name = "${escapeTomlString(name)}"`,
+    `description = "${escapeTomlString(parsed.description)}"`,
+    `developer_instructions = """`,
+    parsed.body || parsed.title,
+    `"""`,
+    ""
+  ];
+  return lines.join(`
+`);
+}
+function escapeTomlString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+}
 function parseMarkdownPrompt(source, id) {
   const trimmed = source.trim();
   const lines = trimmed.split(/\r?\n/);
@@ -8333,7 +8423,7 @@ class KiloAdapter {
     const rulesResult = await syncRulesAsFiles(source.rules, resolve26(target.configPath, "rules"), (rule, content) => ({ relativePath: `${rule.id}.md`, content: content.trimEnd() }), Boolean(request.dryRun));
     changed = rulesResult.changed || changed;
     fileChanges.push(...rulesResult.paths);
-    const workflowsResult = await syncCommandsAsWorkflows(source.commands, resolve26(target.configPath, "workflows"), Boolean(request.dryRun));
+    const workflowsResult = await syncCommandsAsMarkdown(source.commands, resolve26(target.configPath, "workflows"), Boolean(request.dryRun), CommandRendererFactory.getRenderer("workflow"), "-");
     changed = workflowsResult.changed || changed;
     fileChanges.push(...workflowsResult.paths);
     const skillsResult = await syncSkills(source.skills, resolve26(target.configPath, "skills"), Boolean(request.dryRun));
@@ -8342,7 +8432,7 @@ class KiloAdapter {
     const agentsResult = await syncAgentsAsMarkdown(source.agents, resolve26(target.configPath, "agents"), Boolean(request.dryRun), true);
     changed = agentsResult.changed || changed;
     fileChanges.push(...agentsResult.paths);
-    const mcpResult = await mergeJsonObjectFile(resolve26(target.configPath, "opencode.json"), (existing) => renderOpencodeMcpConfig(existing, source.mcpServers), Boolean(request.dryRun));
+    const mcpResult = await mergeJsonObjectFile(resolve26(target.configPath, "kilo.json"), (existing) => renderOpencodeMcpConfig(existing, source.mcpServers), Boolean(request.dryRun));
     changed = mcpResult.changed || changed;
     fileChanges.push(...mcpResult.paths);
     return {
@@ -8440,14 +8530,13 @@ class CodexAdapter {
     return {
       configPath: scope === "project" ? resolve28(projectPath, "AGENTS.md") : resolve28(userRoot, "AGENTS.md"),
       scope,
-      surface: "agents-md-prompts-skills-config-toml"
+      surface: "agents-md-skills-config-toml"
     };
   }
   async applyAppyIntegration(request) {
     const target = await this.resolveTarget(request.projectPath, request);
     const userRoot = request.userConfigRootPath ? resolve28(request.userConfigRootPath) : resolve28(homedir17(), ".codex");
     const skillRoot = target.scope === "project" ? resolve28(request.projectPath, ".agents", "skills") : resolve28(userRoot, "skills");
-    const promptRoot = resolve28(userRoot, "prompts");
     const configPath = target.scope === "project" ? resolve28(request.projectPath, ".codex", "config.toml") : resolve28(userRoot, "config.toml");
     const source = await this.sourceLoader.load(request.projectPath);
     let changed = false;
@@ -8459,9 +8548,15 @@ class CodexAdapter {
     changed = skillsResult.changed || changed;
     fileChanges.push(...skillsResult.paths);
     if (target.scope === "user") {
-      const promptsResult = await syncCommandsAsMarkdown(source.commands, promptRoot, Boolean(request.dryRun));
-      changed = promptsResult.changed || changed;
-      fileChanges.push(...promptsResult.paths);
+      const commandsAsSkillsResult = await syncCommandsAsSkills(source.commands, skillRoot, Boolean(request.dryRun));
+      changed = commandsAsSkillsResult.changed || changed;
+      fileChanges.push(...commandsAsSkillsResult.paths);
+    }
+    if (source.agents.length > 0) {
+      const agentsDir = target.scope === "project" ? resolve28(request.projectPath, ".codex", "agents") : resolve28(userRoot, "agents");
+      const agentsResult = await syncAgentsAsCodexToml(source.agents, agentsDir, Boolean(request.dryRun));
+      changed = agentsResult.changed || changed;
+      fileChanges.push(...agentsResult.paths);
     }
     if (source.mcpServers.length > 0) {
       const mcpResult = await mergeManagedTomlSection(configPath, renderCodexMcpServers(source.mcpServers), CodexAdapter.mcpMarkers, Boolean(request.dryRun));
@@ -8474,11 +8569,11 @@ class CodexAdapter {
       scope: target.scope,
       surface: target.surface,
       status: toStatus(changed),
-      message: "Applied Codex guidance, prompts, skills, and MCP servers.",
+      message: "Applied Codex guidance, skills, agents, and MCP servers.",
       fileChanges,
       warnings: [
         ...source.warnings,
-        ...countUnsupportedArtifacts("Codex", source, target.scope === "project" ? ["commands", "agents"] : ["agents"])
+        ...countUnsupportedArtifacts("Codex", source, target.scope === "project" ? ["commands"] : [])
       ]
     };
   }
@@ -8782,12 +8877,23 @@ function createApplyCommand() {
         }
         console.log(`Duration: ${durationMs}ms`);
       }
-      if (verbose && warnings.length > 0) {
-        const filteredWarnings = warnings.filter((w) => !w.includes("Skipped .gitkeep") && !w.includes("invalid extension"));
-        if (filteredWarnings.length > 0) {
-          console.log(`
+      const criticalWarnings = warnings.filter((w) => w.includes("does not have a documented apply target for"));
+      const noiseWarnings = warnings.filter((w) => !w.includes("does not have a documented apply target for"));
+      if (criticalWarnings.length > 0) {
+        console.log(`
+Warnings:`);
+        for (const warning of criticalWarnings) {
+          console.log(`  - ${warning}`);
+        }
+      }
+      if (verbose && noiseWarnings.length > 0) {
+        const filteredNoiseWarnings = noiseWarnings.filter((w) => !w.includes("Skipped .gitkeep") && !w.includes("invalid extension"));
+        if (filteredNoiseWarnings.length > 0) {
+          if (criticalWarnings.length === 0) {
+            console.log(`
 Warnings:`);
-          for (const warning of filteredWarnings) {
+          }
+          for (const warning of filteredNoiseWarnings) {
             console.log(`  - ${warning}`);
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-ctrl-cli",
-  "version": "0.1.1",
+  "version": "0.1.6",
   "description": "A centralized CLI tool for managing AI agent configurations with standard directory-based patterns.",
   "author": "Ahmet Cetinkaya <ahmetcetinkaya@tutamail.com> (https://github.com/ahmet-cetinkaya)",
   "license": "GPL-3.0",
@@ -23,7 +23,10 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": "./dist/index.js",
+  "bin": {
+    "agent-ctrl-cli": "./dist/index.js",
+    "agent-ctrl": "./dist/index.js"
+  },
   "files": [
     "dist/",
     "README.md",