awesome-agents 0.1.0

package/src/installer.js

@@ -0,0 +1,315 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_AGENT, SUPPORTED_AGENTS } from "./constants.js";
+import { contentHash, isGeneratedContent, normalizeAgentList, renderForAgent, resolveTargetPath } from "./renderers.js";
+import { loadCatalog, materializeSource, splitSourceSpec } from "./source.js";
+import { readRegistry, registryPath, removeInstall, upsertInstall, writeRegistry } from "./registry.js";
+
+export async function listAvailable(sourceInput, options = {}) {
+  const { source } = splitSourceSpec(sourceInput);
+  const materialized = await materializeSource(source, options);
+  try {
+    const catalog = await loadCatalog(materialized.path);
+    return catalog.profiles.map((profile) => profileSummary(profile, materialized.source));
+  } finally {
+    await materialized.cleanup();
+  }
+}
+
+export async function installFromSource(sourceSpec, options = {}) {
+  const split = splitSourceSpec(sourceSpec);
+  const source = split.source;
+  const optionProfiles = normalizeProfileSelectors(options.profiles ?? options.profile ?? options.skills ?? options.skill);
+  const selectors = split.profile ? [...optionProfiles, split.profile] : optionProfiles;
+  const scope = resolveScope(options);
+  const harnesses = normalizeAgentList(options.agents ?? options.agent, {
+    all: options.all,
+    defaultAgent: DEFAULT_AGENT
+  });
+
+  const materialized = await materializeSource(source, options);
+  try {
+    const catalog = await loadCatalog(materialized.path);
+    const profiles = selectProfiles(catalog.profiles, selectors, options.all);
+    const registryOptions = { ...options, scope };
+    const registry = await readRegistry(registryOptions);
+    const operations = [];
+    const installedAt = new Date().toISOString();
+
+    for (const profile of profiles) {
+      for (const harness of harnesses) {
+        const content = renderForAgent(profile, harness, { source: materialized.source });
+        const target = resolveTargetPath(profile, harness, { ...options, scope });
+        await writeManagedFile(target, content, options);
+
+        const install = {
+          profile: profile.slug,
+          name: profile.name,
+          summary: profile.summary,
+          harness,
+          scope,
+          source: materialized.source,
+          sourceKind: materialized.kind,
+          target,
+          installedAt,
+          contentSha256: contentHash(content),
+          dryRun: Boolean(options.dryRun)
+        };
+
+        if (!options.dryRun) {
+          upsertInstall(registry, install);
+        }
+
+        operations.push({
+          action: options.dryRun ? "would-install" : "installed",
+          ...install
+        });
+      }
+    }
+
+    if (!options.dryRun) {
+      await writeRegistry(registry, registryOptions);
+    }
+
+    return { operations, registryPath: registryPath(registryOptions) };
+  } finally {
+    await materialized.cleanup();
+  }
+}
+
+export async function useFromSource(sourceSpec, options = {}) {
+  const split = splitSourceSpec(sourceSpec);
+  const profileSelector = options.profile ?? options.skill ?? split.profile;
+  if (!profileSelector) {
+    throw new Error("Specify a profile with source@profile or --profile <profile>.");
+  }
+
+  const harness = normalizeAgentList(options.agent ? [options.agent] : options.agents, {
+    defaultAgent: DEFAULT_AGENT
+  })[0];
+  const materialized = await materializeSource(split.source, options);
+  try {
+    const catalog = await loadCatalog(materialized.path);
+    const [profile] = selectProfiles(catalog.profiles, [profileSelector], false);
+    const content = renderForAgent(profile, harness, { source: materialized.source });
+    return {
+      profile: profile.slug,
+      harness,
+      source: materialized.source,
+      content
+    };
+  } finally {
+    await materialized.cleanup();
+  }
+}
+
+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 installs = registry.installs
+    .filter((install) => !harnessFilter || harnessFilter.has(install.harness))
+    .map((install) => ({
+      ...install,
+      exists: existsSync(install.target)
+    }));
+
+  return {
+    scope,
+    registryPath: registryPath({ ...options, scope }),
+    installs
+  };
+}
+
+export async function removeInstalled(profileArgs = [], options = {}) {
+  const scope = resolveScope(options);
+  const registryOptions = { ...options, scope };
+  const registry = await readRegistry(registryOptions);
+  const selectors = normalizeProfileSelectors(profileArgs);
+  const removeAll = Boolean(options.all);
+  if (!removeAll && selectors.length === 0) {
+    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 operations = [];
+  const matched = registry.installs.filter((install) => {
+    const profileMatch = removeAll || selectors.includes(install.profile);
+    const harnessMatch = !harnessFilter || harnessFilter.has(install.harness);
+    return install.scope === scope && profileMatch && harnessMatch;
+  });
+
+  for (const install of matched) {
+    const exists = existsSync(install.target);
+    if (exists) {
+      const content = await fs.readFile(install.target, "utf8");
+      if (!isGeneratedContent(content) && !options.force) {
+        throw new Error(`Refusing to remove unmanaged file ${install.target}. Pass --force to override.`);
+      }
+      if (!options.dryRun) {
+        await fs.rm(install.target, { force: true });
+      }
+    }
+
+    if (!options.dryRun) {
+      removeInstall(registry, install);
+    }
+
+    operations.push({
+      action: options.dryRun ? "would-remove" : "removed",
+      ...install,
+      existed: exists
+    });
+  }
+
+  if (!options.dryRun) {
+    await writeRegistry(registry, registryOptions);
+  }
+
+  return { operations, registryPath: registryPath(registryOptions) };
+}
+
+export async function updateInstalled(profileArgs = [], options = {}) {
+  const scope = resolveScope(options);
+  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 candidates = registry.installs.filter((install) => {
+    const profileMatch = selectors.length === 0 || selectors.includes(install.profile);
+    const harnessMatch = !harnessFilter || harnessFilter.has(install.harness);
+    return install.scope === scope && profileMatch && harnessMatch;
+  });
+
+  const operations = [];
+  for (const install of candidates) {
+    const result = await installFromSource(install.source, {
+      ...options,
+      profiles: [install.profile],
+      agents: [install.harness],
+      global: scope === "global",
+      project: scope === "project",
+      force: true
+    });
+    operations.push(...result.operations.map((operation) => ({
+      ...operation,
+      action: options.dryRun ? "would-update" : "updated"
+    })));
+  }
+
+  return { operations, registryPath: registryPath(registryOptions) };
+}
+
+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`);
+
+  if (!options.force) {
+    for (const target of [profilePath, adapterPath]) {
+      if (existsSync(target)) {
+        throw new Error(`${target} 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`;
+
+  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]
+  };
+}
+
+function selectProfiles(profiles, selectors, all = false) {
+  if (all || selectors.length === 0 || selectors.includes("*")) {
+    return profiles;
+  }
+
+  const selected = [];
+  for (const selector of selectors) {
+    const profile = profiles.find((candidate) => candidate.slug === selector || candidate.name === selector);
+    if (!profile) {
+      const available = profiles.map((candidate) => candidate.slug).join(", ");
+      throw new Error(`Profile "${selector}" was not found. Available profiles: ${available}`);
+    }
+    selected.push(profile);
+  }
+
+  return [...new Map(selected.map((profile) => [profile.slug, profile])).values()];
+}
+
+async function writeManagedFile(target, content, options = {}) {
+  if (options.dryRun) {
+    return;
+  }
+
+  if (existsSync(target) && !options.force) {
+    const existing = await fs.readFile(target, "utf8");
+    if (!isGeneratedContent(existing)) {
+      throw new Error(`Refusing to overwrite unmanaged file ${target}. Pass --force to override.`);
+    }
+  }
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, content);
+}
+
+function resolveScope(options = {}) {
+  if (options.project && options.global) {
+    throw new Error("Use either --global or --project, not both.");
+  }
+  return options.global ? "global" : "project";
+}
+
+function normalizeProfileSelectors(values) {
+  return [values]
+    .flat(2)
+    .filter(Boolean)
+    .flatMap((value) => String(value).split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function profileSummary(profile, source) {
+  return {
+    slug: profile.slug,
+    name: profile.name,
+    summary: profile.summary,
+    kind: profile.attributes.kind,
+    source,
+    adapters: Object.keys(profile.adapters)
+  };
+}
+
+function slugify(value) {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "new-agent-profile";
+}
+
+function titleCase(slug) {
+  return slug
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+export { SUPPORTED_AGENTS };

package/src/registry.js

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { REGISTRY_DIRNAME, REGISTRY_FILENAME } from "./constants.js";
+import { expandHome } from "./source.js";
+
+export function registryPath(options = {}) {
+  const scope = options.scope ?? "global";
+  const cwd = options.cwd ?? process.cwd();
+  const home = path.resolve(expandHome(options.home ?? os.homedir()));
+
+  if (scope === "project") {
+    return path.join(cwd, REGISTRY_DIRNAME, REGISTRY_FILENAME);
+  }
+
+  return path.join(home, REGISTRY_DIRNAME, REGISTRY_FILENAME);
+}
+
+export async function readRegistry(options = {}) {
+  const filePath = registryPath(options);
+  if (!existsSync(filePath)) {
+    return { version: 1, installs: [] };
+  }
+
+  const raw = await fs.readFile(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  return {
+    version: parsed.version ?? 1,
+    installs: Array.isArray(parsed.installs) ? parsed.installs : []
+  };
+}
+
+export async function writeRegistry(registry, options = {}) {
+  const filePath = registryPath(options);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
+}
+
+export function upsertInstall(registry, install) {
+  const key = installKey(install);
+  const index = registry.installs.findIndex((entry) => installKey(entry) === key);
+  if (index >= 0) {
+    registry.installs[index] = { ...registry.installs[index], ...install };
+  } else {
+    registry.installs.push(install);
+  }
+  registry.installs.sort((a, b) => installKey(a).localeCompare(installKey(b)));
+}
+
+export function removeInstall(registry, install) {
+  const key = installKey(install);
+  registry.installs = registry.installs.filter((entry) => installKey(entry) !== key);
+}
+
+export function installKey(install) {
+  return `${install.scope}:${install.harness}:${install.profile}`;
+}

package/src/renderers.js

@@ -0,0 +1,256 @@
+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 { stringifyFrontmatter } from "./frontmatter.js";
+import { expandHome } from "./source.js";
+
+export function normalizeAgent(agent) {
+  const normalized = AGENT_ALIASES.get(String(agent).toLowerCase());
+  if (!normalized) {
+    throw new Error(`Unsupported agent "${agent}". Supported agents: ${SUPPORTED_AGENTS.join(", ")}`);
+  }
+  return normalized;
+}
+
+export function normalizeAgentList(input, options = {}) {
+  if (options.all) {
+    return SUPPORTED_AGENTS;
+  }
+
+  const rawAgents = flattenValues(input);
+  if (rawAgents.length === 0) {
+    return [options.defaultAgent ?? "codex"];
+  }
+
+  if (rawAgents.includes("*")) {
+    return SUPPORTED_AGENTS;
+  }
+
+  return [...new Set(rawAgents.map(normalizeAgent))];
+}
+
+export function renderForAgent(profile, agent, context) {
+  const normalized = normalizeAgent(agent);
+  if (normalized === "codex") {
+    return renderCodex(profile, context);
+  }
+  if (normalized === "claude-code") {
+    return renderClaudeCode(profile, context);
+  }
+  if (normalized === "opencode") {
+    return renderOpenCode(profile, context);
+  }
+  throw new Error(`Unsupported agent "${agent}"`);
+}
+
+export function resolveTargetPath(profile, agent, options = {}) {
+  const normalized = normalizeAgent(agent);
+  const scope = options.scope ?? "global";
+  const cwd = options.cwd ?? process.cwd();
+  const home = path.resolve(expandHome(options.home ?? os.homedir()));
+
+  if (normalized === "codex") {
+    const codexHome = options.codexHome
+      ? path.resolve(expandHome(options.codexHome, home))
+      : 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`);
+  }
+
+  if (normalized === "claude-code") {
+    if (scope === "project") {
+      return path.join(cwd, ".claude", "agents", `${profile.slug}.md`);
+    }
+
+    const claudeHome = options.claudeHome
+      ? path.resolve(expandHome(options.claudeHome, home))
+      : process.env.CLAUDE_HOME
+        ? path.resolve(expandHome(process.env.CLAUDE_HOME, home))
+        : path.join(home, ".claude");
+    return path.join(claudeHome, "agents", `${profile.slug}.md`);
+  }
+
+  if (normalized === "opencode") {
+    if (scope === "project") {
+      return path.join(cwd, ".opencode", "agents", `${profile.slug}.md`);
+    }
+
+    const opencodeHome = options.opencodeHome
+      ? path.resolve(expandHome(options.opencodeHome, home))
+      : process.env.OPENCODE_CONFIG_DIR
+        ? path.resolve(expandHome(process.env.OPENCODE_CONFIG_DIR, home))
+        : path.join(process.env.XDG_CONFIG_HOME ? path.resolve(expandHome(process.env.XDG_CONFIG_HOME, home)) : path.join(home, ".config"), "opencode");
+    return path.join(opencodeHome, "agents", `${profile.slug}.md`);
+  }
+
+  throw new Error(`Unsupported agent "${agent}"`);
+}
+
+export function contentHash(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+export function isGeneratedContent(content) {
+  return content.includes(GENERATED_MARKER);
+}
+
+function renderCodex(profile, context) {
+  const adapter = profile.adapters.codex;
+  const model = adapter?.attributes.model ?? profile.attributes.recommended_model ?? first(profile.attributes.recommended_models);
+  const effort = adapter?.attributes.reasoning_effort ?? profile.attributes.recommended_reasoning_effort;
+  const instructions = buildInstructionBody(profile, adapter, "codex");
+  const lines = [
+    `# ${GENERATED_MARKER}.`,
+    `# Source: ${context.source}`,
+    `# Profile: ${profile.slug}`,
+    "",
+    `name = ${tomlString(profile.slug)}`,
+    `description = ${tomlString(profile.summary || profile.name)}`
+  ];
+
+  if (model && model !== "inherit") {
+    lines.push(`model = ${tomlString(model)}`);
+  }
+  if (effort && effort !== "inherit") {
+    lines.push(`model_reasoning_effort = ${tomlString(effort)}`);
+  }
+  lines.push("");
+  lines.push(`developer_instructions = ${tomlMultiline(instructions)}`);
+  return `${lines.join("\n")}\n`;
+}
+
+function renderClaudeCode(profile, context) {
+  const attributes = {
+    name: profile.slug,
+    description: profile.summary || profile.name
+  };
+  const model = chooseClaudeModel(profile);
+  const effort = profile.attributes.recommended_reasoning_effort;
+
+  if (model && model !== "inherit") {
+    attributes.model = model;
+  }
+  if (effort && effort !== "inherit" && ["low", "medium", "high", "xhigh", "max"].includes(effort)) {
+    attributes.effort = effort;
+  }
+
+  attributes.tools = "Bash";
+
+  const marker = htmlMarker(profile, "claude-code", context);
+  return stringifyFrontmatter(attributes, `${marker}\n\n${buildInstructionBody(profile, undefined, "claude-code")}`);
+}
+
+function renderOpenCode(profile, context) {
+  const attributes = {
+    description: profile.summary || profile.name,
+    mode: "subagent",
+    permission: {
+      edit: "deny"
+    }
+  };
+  const model = chooseOpenCodeModel(profile);
+  if (model) {
+    attributes.model = model;
+  }
+
+  const marker = htmlMarker(profile, "opencode", context);
+  return stringifyFrontmatter(attributes, `${marker}\n\n${buildInstructionBody(profile, undefined, "opencode")}`);
+}
+
+function buildInstructionBody(profile, adapter, harness) {
+  const parts = [
+    profile.body.trimEnd(),
+    "",
+    "## Installed Profile Context",
+    "",
+    `- Canonical profile slug: \`${profile.slug}\``,
+    `- Installed for: \`${harness}\``,
+    "- This profile is a reusable operational agent profile, not local machine setup.",
+    "- The runtime agent manages any profile-specific home directory and notes at task time."
+  ];
+
+  if (adapter?.body) {
+    parts.push("", "## Harness Adapter", "", adapter.body.trimEnd());
+  }
+
+  return parts.join("\n");
+}
+
+function htmlMarker(profile, harness, context) {
+  const payload = JSON.stringify({
+    package: "awesome-agents",
+    profile: profile.slug,
+    harness,
+    source: context.source
+  });
+  return `<!-- ${GENERATED_MARKER}: ${payload} -->`;
+}
+
+function chooseClaudeModel(profile) {
+  const candidates = [
+    profile.attributes.recommended_model,
+    ...arrayify(profile.attributes.recommended_models)
+  ].filter(Boolean).map((value) => String(value).toLowerCase());
+
+  if (candidates.some((model) => model.includes("opus"))) {
+    return "opus";
+  }
+  if (candidates.some((model) => model.includes("sonnet"))) {
+    return "sonnet";
+  }
+  if (candidates.some((model) => model.includes("haiku"))) {
+    return "haiku";
+  }
+  if (candidates.some((model) => model.includes("fable"))) {
+    return "fable";
+  }
+  return "inherit";
+}
+
+function chooseOpenCodeModel(profile) {
+  const candidates = [
+    profile.attributes.recommended_model,
+    ...arrayify(profile.attributes.recommended_models)
+  ].filter(Boolean).map(String);
+  return candidates.find((model) => model.includes("/"));
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function tomlMultiline(value) {
+  const text = String(value).trimEnd();
+  if (!text.includes("'''")) {
+    return `'''\n${text}\n'''`;
+  }
+  return `"""\n${text.replaceAll("\\", "\\\\").replaceAll('"""', '\\"\\"\\"')}\n"""`;
+}
+
+function first(value) {
+  return arrayify(value)[0];
+}
+
+function arrayify(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return [value];
+}
+
+function flattenValues(values) {
+  return arrayify(values)
+    .flatMap((value) => String(value).split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}