awesome-agents 0.1.1 → 0.1.5

package/src/installer.js

@@ -1,9 +1,10 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
-import { AGENT_ALIASES, DEFAULT_AGENT, SUPPORTED_AGENTS } from "./constants.js";
+import { AGENT_ALIASES, HARNESS_COMMANDS, SUPPORTED_AGENTS } from "./constants.js";
 import { contentHash, isGeneratedContent, normalizeAgentList, renderForAgent, resolveTargetPath } from "./renderers.js";
-import { loadCatalog, materializeSource, splitSourceSpec } from "./source.js";
+import { expandHome, loadCatalog, materializeSource, splitSourceSpec } from "./source.js";
 import { readRegistry, registryPath, removeInstall, upsertInstall, writeRegistry } from "./registry.js";
 
 export async function listAvailable(sourceInput, options = {}) {
@@ -21,11 +22,11 @@ export async function installFromSource(sourceSpec, options = {}) {
   const split = splitSourceSpec(sourceSpec);
   const source = split.source;
   const { selectors, harnessInput } = resolveInstallSelection(split, options);
-  const scope = resolveScope(options);
   const harnesses = normalizeAgentList(harnessInput, {
     all: options.all,
-    defaultAgent: DEFAULT_AGENT
+    defaultAgent: detectAvailableHarnesses()
   });
+  const scope = resolveScope(options, harnesses);
 
   const materialized = await materializeSource(source, options);
   try {
@@ -37,6 +38,7 @@ export async function installFromSource(sourceSpec, options = {}) {
     const installedAt = new Date().toISOString();
 
     for (const profile of profiles) {
+      const supportTargets = await installProfileSupport(profile, options);
       for (const harness of harnesses) {
         const content = renderForAgent(profile, harness, { source: materialized.source });
         const target = resolveTargetPath(profile, harness, { ...options, scope });
@@ -53,6 +55,7 @@ export async function installFromSource(sourceSpec, options = {}) {
           target,
           installedAt,
           contentSha256: contentHash(content),
+          supportTargets,
           dryRun: Boolean(options.dryRun)
         };
 
@@ -71,7 +74,11 @@ export async function installFromSource(sourceSpec, options = {}) {
       await writeRegistry(registry, registryOptions);
     }
 
-    return { operations, registryPath: registryPath(registryOptions) };
+    return {
+      operations,
+      registryPath: registryPath(registryOptions),
+      runInstructions: buildRunInstructions(operations)
+    };
   } finally {
     await materialized.cleanup();
   }
@@ -85,7 +92,7 @@ export async function useFromSource(sourceSpec, options = {}) {
   }
 
   const harness = normalizeAgentList(harnessInput, {
-    defaultAgent: DEFAULT_AGENT
+    defaultAgent: detectAvailableHarnesses()
   })[0];
   const materialized = await materializeSource(split.source, options);
   try {
@@ -104,10 +111,11 @@ export async function useFromSource(sourceSpec, options = {}) {
 }
 
 export async function listInstalled(options = {}) {
-  const scope = resolveScope(options);
-  const registry = await readRegistry({ ...options, scope });
   const harnessInput = options.agents ?? options.agent;
-  const harnessFilter = harnessInput ? new Set(normalizeAgentList(harnessInput)) : undefined;
+  const harnesses = harnessInput ? normalizeAgentList(harnessInput) : [];
+  const scope = resolveScope(options, harnesses);
+  const registry = await readRegistry({ ...options, scope });
+  const harnessFilter = harnesses.length > 0 ? new Set(harnesses) : undefined;
   const installs = registry.installs
     .filter((install) => !harnessFilter || harnessFilter.has(install.harness))
     .map((install) => ({
@@ -123,7 +131,9 @@ export async function listInstalled(options = {}) {
 }
 
 export async function removeInstalled(profileArgs = [], options = {}) {
-  const scope = resolveScope(options);
+  const harnessInput = options.agents ?? options.agent;
+  const harnesses = harnessInput ? normalizeAgentList(harnessInput) : [];
+  const scope = resolveScope(options, harnesses);
   const registryOptions = { ...options, scope };
   const registry = await readRegistry(registryOptions);
   const selectors = normalizeProfileSelectors(profileArgs);
@@ -132,8 +142,7 @@ export async function removeInstalled(profileArgs = [], options = {}) {
     throw new Error("Specify at least one profile to remove, or pass --all.");
   }
 
-  const harnessInput = options.agents ?? options.agent;
-  const harnessFilter = harnessInput ? new Set(normalizeAgentList(harnessInput)) : undefined;
+  const harnessFilter = harnesses.length > 0 ? new Set(harnesses) : undefined;
   const operations = [];
   const matched = registry.installs.filter((install) => {
     const profileMatch = removeAll || selectors.includes(install.profile);
@@ -172,12 +181,13 @@ export async function removeInstalled(profileArgs = [], options = {}) {
 }
 
 export async function updateInstalled(profileArgs = [], options = {}) {
-  const scope = resolveScope(options);
+  const harnessInput = options.agents ?? options.agent;
+  const harnesses = harnessInput ? normalizeAgentList(harnessInput) : [];
+  const scope = resolveScope(options, harnesses);
   const registryOptions = { ...options, scope };
   const registry = await readRegistry(registryOptions);
   const selectors = normalizeProfileSelectors(profileArgs);
-  const harnessInput = options.agents ?? options.agent;
-  const harnessFilter = harnessInput ? new Set(normalizeAgentList(harnessInput)) : undefined;
+  const harnessFilter = harnesses.length > 0 ? new Set(harnesses) : undefined;
   const candidates = registry.installs.filter((install) => {
     const profileMatch = selectors.length === 0 || selectors.includes(install.profile);
     const harnessMatch = !harnessFilter || harnessFilter.has(install.harness);
@@ -185,6 +195,7 @@ export async function updateInstalled(profileArgs = [], options = {}) {
   });
 
   const operations = [];
+  const runInstructions = [];
   for (const install of candidates) {
     const result = await installFromSource(install.source, {
       ...options,
@@ -198,42 +209,169 @@ export async function updateInstalled(profileArgs = [], options = {}) {
       ...operation,
       action: options.dryRun ? "would-update" : "updated"
     })));
+    runInstructions.push(...result.runInstructions);
   }
 
-  return { operations, registryPath: registryPath(registryOptions) };
+  return { operations, registryPath: registryPath(registryOptions), runInstructions };
 }
 
 export async function initProfile(name, options = {}) {
   const slug = slugify(name || "new-agent-profile");
   const root = options.cwd ?? process.cwd();
-  const profilePath = path.join(root, "agents", "profiles", `${slug}.md`);
-  const adapterPath = path.join(root, "agents", "adapters", "codex", `${slug}.md`);
+  const profilePath = path.join(root, "agents", slug, "agent.yaml");
 
   if (!options.force) {
-    for (const target of [profilePath, adapterPath]) {
-      if (existsSync(target)) {
-        throw new Error(`${target} already exists. Pass --force to overwrite.`);
-      }
+    if (existsSync(profilePath)) {
+      throw new Error(`${profilePath} already exists. Pass --force to overwrite.`);
     }
   }
 
   const title = titleCase(slug);
-  const profileContent = `---\nslug: ${slug}\nname: ${title}\nkind: operational-agent-profile\nsummary: Describe when to use this agent profile.\nrecommended_model: inherit\nrecommended_reasoning_effort: medium\nhome_notes_template: "~/.agents/homes/${slug}/<project>/notes"\n---\n\n# ${title}\n\nDescribe the agent's mission, boundaries, tools, coordination model, notes, and reporting style.\n`;
-  const adapterContent = `---\nslug: ${slug}\nprofile: ../../profiles/${slug}.md\nharness: codex\nmodel: inherit\nreasoning_effort: medium\nrequired_skills: []\n---\n\n# Codex Adapter: ${title}\n\nLoad the canonical profile at \`agents/profiles/${slug}.md\`.\n`;
+  const profileContent = `schema: awesome-agents/v1\nid: ${slug}\nname: ${title}\ndescription: Describe when to use this agent profile.\nmodel: inherit\nreasoning_effort: medium\nhome_notes_template: "~/.agents/homes/${slug}/<project>/notes"\ninstructions: |\n  Describe the agent's mission, boundaries, tools, coordination model, notes,\n  and reporting style.\n`;
 
   if (!options.dryRun) {
     await fs.mkdir(path.dirname(profilePath), { recursive: true });
-    await fs.mkdir(path.dirname(adapterPath), { recursive: true });
     await fs.writeFile(profilePath, profileContent);
-    await fs.writeFile(adapterPath, adapterContent);
   }
 
   return {
     action: options.dryRun ? "would-init" : "initialized",
-    files: [profilePath, adapterPath]
+    files: [profilePath]
   };
 }
 
+async function installProfileSupport(profile, options = {}) {
+  if (!profile.supportDirs?.length) {
+    return [];
+  }
+
+  const home = path.resolve(expandHome(options.home ?? os.homedir()));
+  const agentHome = path.join(home, ".agents", "homes", profile.slug);
+  const targets = [];
+
+  for (const supportDir of profile.supportDirs) {
+    const files = await listFilesRecursive(supportDir.sourcePath);
+    for (const source of files) {
+      const relative = path.relative(supportDir.sourcePath, source);
+      const target = path.join(agentHome, supportDir.kind, relative);
+      targets.push(target);
+      if (!options.dryRun) {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.copyFile(source, target);
+      }
+    }
+  }
+
+  return targets;
+}
+
+async function listFilesRecursive(root) {
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursive(entryPath));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+  return files.sort();
+}
+
+function buildRunInstructions(operations, env = process.env) {
+  const instructions = [];
+  const seen = new Set();
+
+  for (const operation of operations) {
+    if (String(operation.action).startsWith("would-")) {
+      continue;
+    }
+
+    const instruction = runInstructionForOperation(operation, env);
+    if (!instruction) {
+      continue;
+    }
+
+    const key = `${instruction.harness}:${instruction.profile}:${instruction.command}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    instructions.push(instruction);
+  }
+
+  return instructions;
+}
+
+function runInstructionForOperation(operation, env) {
+  if (operation.harness === "codex") {
+    if (!commandExists("codex", env)) {
+      return undefined;
+    }
+    return {
+      profile: operation.profile,
+      harness: operation.harness,
+      command: `codex --profile ${shellWord(operation.profile)}`,
+      note: "Starts Codex with this installed profile."
+    };
+  }
+
+  if (operation.harness === "claude-code") {
+    if (!commandExists("claude", env)) {
+      return undefined;
+    }
+    return {
+      profile: operation.profile,
+      harness: operation.harness,
+      command: `claude --agent ${shellWord(operation.profile)}`,
+      note: "Starts Claude Code with this installed agent profile."
+    };
+  }
+
+  if (operation.harness === "opencode") {
+    if (!commandExists("opencode", env)) {
+      return undefined;
+    }
+    return {
+      profile: operation.profile,
+      harness: operation.harness,
+      command: "opencode",
+      note: `Start OpenCode, then invoke @${operation.profile} in the session.`
+    };
+  }
+
+  return undefined;
+}
+
+function detectAvailableHarnesses(env = process.env) {
+  return SUPPORTED_AGENTS.filter((harness) => commandExists(HARNESS_COMMANDS.get(harness), env));
+}
+
+function commandExists(command, env) {
+  const pathValue = env.PATH ?? "";
+  if (!pathValue) {
+    return false;
+  }
+
+  const extensions = process.platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+
+  return pathValue
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((directory) => extensions.some((extension) => existsSync(path.join(directory, `${command}${extension}`))));
+}
+
+function shellWord(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9._/@:-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
 function selectProfiles(profiles, selectors, all = false) {
   if (all || selectors.length === 0 || selectors.includes("*")) {
     return profiles;
@@ -268,11 +406,23 @@ async function writeManagedFile(target, content, options = {}) {
   await fs.writeFile(target, content);
 }
 
-function resolveScope(options = {}) {
+function resolveScope(options = {}, harnesses = []) {
   if (options.project && options.global) {
     throw new Error("Use either --global or --project, not both.");
   }
-  return options.global ? "global" : "project";
+  if (options.project && harnesses.includes("codex")) {
+    throw new Error("Codex profiles are loaded from $CODEX_HOME/<name>.config.toml and cannot be installed project-locally. Use --global or choose a different harness.");
+  }
+  if (options.global) {
+    return "global";
+  }
+  if (options.project) {
+    return "project";
+  }
+  if (harnesses.includes("codex")) {
+    return "global";
+  }
+  return "project";
 }
 
 function normalizeProfileSelectors(values) {

package/src/renderers.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { AGENT_ALIASES, GENERATED_MARKER, SUPPORTED_AGENTS } from "./constants.js";
+import { AGENT_ALIASES, DEFAULT_AGENT, GENERATED_MARKER, SUPPORTED_AGENTS } from "./constants.js";
 import { stringifyFrontmatter } from "./frontmatter.js";
 import { expandHome } from "./source.js";
 
@@ -20,7 +20,8 @@ export function normalizeAgentList(input, options = {}) {
 
   const rawAgents = flattenValues(input);
   if (rawAgents.length === 0) {
-    return [options.defaultAgent ?? "codex"];
+    const fallback = arrayify(options.defaultAgent);
+    return fallback.length > 0 ? fallback : [DEFAULT_AGENT];
   }
 
   if (rawAgents.includes("*")) {
@@ -56,12 +57,7 @@ export function resolveTargetPath(profile, agent, options = {}) {
       : process.env.CODEX_HOME
         ? path.resolve(expandHome(process.env.CODEX_HOME, home))
         : path.join(home, ".codex");
-
-    if (scope === "project") {
-      return path.join(cwd, ".codex", "agents", `${profile.slug}.toml`);
-    }
-
-    return path.join(codexHome, "agents", `${profile.slug}.toml`);
+    return path.join(codexHome, `${profile.slug}.config.toml`);
   }
 
   if (normalized === "claude-code") {
@@ -110,9 +106,9 @@ function renderCodex(profile, context) {
     `# ${GENERATED_MARKER}.`,
     `# Source: ${context.source}`,
     `# Profile: ${profile.slug}`,
-    "",
-    `name = ${tomlString(profile.slug)}`,
-    `description = ${tomlString(profile.summary || profile.name)}`
+    `# Display name: ${tomlComment(profile.name)}`,
+    `# Summary: ${tomlComment(profile.summary || profile.name)}`,
+    ""
   ];
 
   if (model && model !== "inherit") {
@@ -170,9 +166,11 @@ function buildInstructionBody(profile, adapter, harness) {
     "",
     "## Installed Profile Context",
     "",
-    `- Canonical profile slug: \`${profile.slug}\``,
+    `- Installed identity: \`${profile.slug}\``,
+    `- Role/name: \`${profile.name}\``,
     `- Installed for: \`${harness}\``,
-    "- This profile is a reusable operational agent profile, not local machine setup.",
+    "- When asked who you are, what agent is running, or what role you are acting as, answer with this identity and role.",
+    "- This profile is a reusable operational agent profile, not a skill or local machine setup.",
     "- The runtime agent manages any profile-specific home directory and notes at task time."
   ];
 
@@ -226,6 +224,10 @@ function tomlString(value) {
   return JSON.stringify(String(value));
 }
 
+function tomlComment(value) {
+  return String(value).replace(/\s+/g, " ").trim();
+}
+
 function tomlMultiline(value) {
   const text = String(value).trimEnd();
   if (!text.includes("'''")) {