awesome-agents 0.1.0 → 0.1.3

package/scripts/changelog.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "..");
+const changelogPath = path.join(root, "CHANGELOG.md");
+const packagePath = path.join(root, "package.json");
+const changelogHeader = "# Changelog\n\nThis file is maintained by `npm run changelog` and `npm run release`. Release entries are generated from git commit history.\n\n";
+const categoryOrder = ["Breaking", "Added", "Fixed", "Changed", "Documentation", "Tests", "Maintenance"];
+
+export async function updateChangelog(options = {}) {
+  const version = options.version ?? await readPackageVersion();
+  const date = options.date ?? new Date().toISOString().slice(0, 10);
+  const from = options.from ?? latestVersionTag();
+  const to = options.to ?? "HEAD";
+  const commits = readCommits(from, to);
+  const entry = formatEntry({ version, date, from, commits });
+
+  if (!options.write) {
+    return { changelogPath, entry, commits, from, to, version };
+  }
+
+  const existing = await readExistingChangelog();
+  await fs.writeFile(changelogPath, upsertEntry(existing, entry, version));
+  return { changelogPath, entry, commits, from, to, version };
+}
+
+function readCommits(from, to) {
+  const range = from ? `${from}..${to}` : to;
+  const output = git(["log", "--no-merges", "--pretty=format:%H%x1f%s", range], { allowEmpty: true });
+  if (!output) {
+    return [];
+  }
+
+  return output.split("\n").map((line) => {
+    const [hash, subject] = line.split("\x1f");
+    return {
+      hash,
+      shortHash: hash.slice(0, 7),
+      subject: subject.trim()
+    };
+  }).filter((commit) => commit.subject);
+}
+
+function formatEntry({ version, date, from, commits }) {
+  const lines = [`## ${version} - ${date}`, ""];
+  lines.push(from ? `Changes since \`${from}\`.` : "Initial tracked release.");
+  lines.push("");
+
+  if (commits.length === 0) {
+    lines.push("- No commits found for this release.");
+    return `${lines.join("\n")}\n`;
+  }
+
+  const groups = new Map(categoryOrder.map((category) => [category, []]));
+  for (const commit of commits) {
+    groups.get(categoryFor(commit.subject)).push(commit);
+  }
+
+  for (const category of categoryOrder) {
+    const entries = groups.get(category);
+    if (entries.length === 0) {
+      continue;
+    }
+
+    lines.push(`### ${category}`, "");
+    for (const commit of entries) {
+      lines.push(`- ${cleanSubject(commit.subject)} (${commit.shortHash})`);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function upsertEntry(existing, entry, version) {
+  const body = normalizeBody(existing);
+  const escapedVersion = escapeRegExp(version);
+  const existingEntry = new RegExp(`^## ${escapedVersion} - [^\\n]*\\n[\\s\\S]*?(?=^## \\d+\\.\\d+\\.\\d+ - |(?![\\s\\S]))`, "m");
+
+  if (existingEntry.test(body)) {
+    return `${changelogHeader}${body.replace(existingEntry, entry.trimEnd()).trimStart()}`;
+  }
+
+  return `${changelogHeader}${entry.trimEnd()}\n\n${body.trimStart()}`.trimEnd() + "\n";
+}
+
+function normalizeBody(existing) {
+  if (!existing) {
+    return "";
+  }
+
+  if (existing.startsWith(changelogHeader)) {
+    return existing.slice(changelogHeader.length);
+  }
+
+  return existing.replace(/^# Changelog\s*/i, "").trimStart();
+}
+
+function categoryFor(subject) {
+  const normalized = subject.toLowerCase();
+  if (/^[a-z]+(?:\([^)]+\))?!:/.test(normalized) || normalized.includes("breaking")) {
+    return "Breaking";
+  }
+  if (/^(feat|add)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Added";
+  }
+  if (/^(fix|repair)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Fixed";
+  }
+  if (/^(docs?|readme)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Documentation";
+  }
+  if (/^(test|tests)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Tests";
+  }
+  if (/^(build|chore|ci|release|bump)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Maintenance";
+  }
+  return "Changed";
+}
+
+function cleanSubject(subject) {
+  return subject
+    .replace(/^[a-z]+(?:\([^)]+\))?!?:\s*/i, "")
+    .trim();
+}
+
+function latestVersionTag() {
+  return git(["tag", "--list", "v[0-9]*", "--sort=-version:refname"], { allowEmpty: true })
+    .split("\n")
+    .find(Boolean);
+}
+
+async function readPackageVersion() {
+  const pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+  return pkg.version;
+}
+
+async function readExistingChangelog() {
+  try {
+    return await fs.readFile(changelogPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function git(args, options = {}) {
+  const result = spawnSync("git", args, {
+    cwd: root,
+    encoding: "utf8"
+  });
+
+  if (result.status !== 0 && !(options.allowEmpty && result.status === 128)) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `git exited with ${result.status}`;
+    throw new Error(detail);
+  }
+
+  return result.stdout.trim();
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function parseArgs(argv) {
+  const options = { write: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--write") {
+      options.write = true;
+    } else if (arg === "--version") {
+      options.version = argv[++index];
+    } else if (arg === "--from") {
+      options.from = argv[++index];
+    } else if (arg === "--to") {
+      options.to = argv[++index];
+    } else if (arg === "--date") {
+      options.date = argv[++index];
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else {
+      throw new Error(`Unknown option ${arg}`);
+    }
+  }
+  return options;
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/changelog.js [options]
+
+Options:
+  --write              Update CHANGELOG.md instead of printing the next entry
+  --version <version>  Release version to write; defaults to package.json
+  --from <ref>         Starting git ref; defaults to latest v* tag
+  --to <ref>           Ending git ref; defaults to HEAD
+  --date <date>        Release date; defaults to today
+`);
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const result = await updateChangelog(options);
+  if (options.write) {
+    console.log(`Updated ${path.relative(root, result.changelogPath)} for ${result.version} with ${result.commits.length} commit(s).`);
+  } else {
+    process.stdout.write(result.entry);
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/release.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { updateChangelog } from "./changelog.js";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "..");
+const packagePath = path.join(root, "package.json");
+const lockPath = path.join(root, "package-lock.json");
+const constantsPath = path.join(root, "src", "constants.js");
+const trackedReleaseFiles = [
+  "package.json",
+  "package-lock.json",
+  "src/constants.js",
+  "CHANGELOG.md"
+];
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const currentVersion = await readPackageVersion();
+  const nextVersion = resolveNextVersion(currentVersion, options.bump);
+  const tag = `v${nextVersion}`;
+
+  if (!options.dryRun) {
+    assertCleanWorktree();
+  }
+
+  console.log(`Release plan: ${currentVersion} -> ${nextVersion}`);
+
+  if (options.dryRun) {
+    const changelog = await updateChangelog({ version: nextVersion, write: false });
+    console.log("\nFiles that would be updated:");
+    for (const file of trackedReleaseFiles) {
+      console.log(`- ${file}`);
+    }
+    console.log("\nChangelog entry preview:\n");
+    process.stdout.write(changelog.entry);
+    return;
+  }
+
+  await updatePackageJson(nextVersion);
+  await updatePackageLock(nextVersion);
+  await updateConstants(nextVersion);
+  await updateChangelog({ version: nextVersion, write: true });
+
+  if (!options.skipChecks) {
+    run("npm", ["run", "lint"]);
+    run("npm", ["test"]);
+  }
+
+  git(["add", ...trackedReleaseFiles]);
+  git(["commit", "-m", `Release ${tag}`]);
+  git(["tag", "-a", tag, "-m", `Release ${tag}`]);
+
+  if (options.push) {
+    const branch = git(["branch", "--show-current"], { capture: true });
+    if (!branch) {
+      throw new Error("Cannot push from a detached HEAD.");
+    }
+    git(["push", "origin", branch]);
+    git(["push", "origin", tag]);
+  }
+
+  console.log(`Cut ${tag}.`);
+  if (!options.push) {
+    console.log(`Push with: git push origin HEAD && git push origin ${tag}`);
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    bump: "patch",
+    dryRun: false,
+    push: false,
+    skipChecks: false
+  };
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--push") {
+      options.push = true;
+    } else if (arg === "--skip-checks") {
+      options.skipChecks = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  if (positional.length > 1) {
+    throw new Error(`Expected one bump argument, received: ${positional.join(", ")}`);
+  }
+  if (positional[0]) {
+    options.bump = positional[0];
+  }
+
+  return options;
+}
+
+function resolveNextVersion(currentVersion, bump) {
+  const explicit = bump.replace(/^v/, "");
+  if (/^\d+\.\d+\.\d+$/.test(explicit)) {
+    return explicit;
+  }
+
+  const match = currentVersion.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) {
+    throw new Error(`Cannot bump non-standard version ${currentVersion}. Pass an explicit x.y.z version.`);
+  }
+
+  const parts = match.slice(1).map(Number);
+  if (bump === "major") {
+    return `${parts[0] + 1}.0.0`;
+  }
+  if (bump === "minor") {
+    return `${parts[0]}.${parts[1] + 1}.0`;
+  }
+  if (bump === "patch") {
+    return `${parts[0]}.${parts[1]}.${parts[2] + 1}`;
+  }
+
+  throw new Error(`Unsupported release bump "${bump}". Use patch, minor, major, or x.y.z.`);
+}
+
+async function readPackageVersion() {
+  const pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+  return pkg.version;
+}
+
+async function updatePackageJson(version) {
+  const pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+  pkg.version = version;
+  await writeJson(packagePath, pkg);
+}
+
+async function updatePackageLock(version) {
+  const lock = JSON.parse(await fs.readFile(lockPath, "utf8"));
+  lock.version = version;
+  if (lock.packages?.[""]) {
+    lock.packages[""].version = version;
+  }
+  await writeJson(lockPath, lock);
+}
+
+async function updateConstants(version) {
+  const content = await fs.readFile(constantsPath, "utf8");
+  const next = content.replace(
+    /export const PACKAGE_VERSION = "[^"]+";/,
+    `export const PACKAGE_VERSION = "${version}";`
+  );
+  if (next === content) {
+    throw new Error("Could not find PACKAGE_VERSION in src/constants.js.");
+  }
+  await fs.writeFile(constantsPath, next);
+}
+
+async function writeJson(filePath, value) {
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function assertCleanWorktree() {
+  const status = git(["status", "--short"], { capture: true });
+  if (status) {
+    throw new Error(`Release requires a clean worktree:\n${status}`);
+  }
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} failed with ${result.status}`);
+  }
+}
+
+function git(args, options = {}) {
+  const result = spawnSync("git", args, {
+    cwd: root,
+    encoding: "utf8",
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit"
+  });
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim() || `git exited with ${result.status}`;
+    throw new Error(detail);
+  }
+  return options.capture ? result.stdout.trim() : "";
+}
+
+function printHelp() {
+  console.log(`Usage: npm run release -- [patch|minor|major|x.y.z] [options]
+
+Cuts a release commit and annotated git tag. It does not publish to npm.
+
+Options:
+  --dry-run       Preview version and changelog changes
+  --push          Push the current branch and release tag after tagging
+  --skip-checks   Skip npm run lint and npm test
+`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/src/cli.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { PACKAGE_NAME, PACKAGE_VERSION, SUPPORTED_AGENTS } from "./constants.js";
+import { configureHelp, formatMissingSourceError, ui } from "./help.js";
 import {
   initProfile,
   installFromSource,
@@ -19,16 +20,20 @@ export async function run(argv = process.argv) {
     .helpOption("-h, --help", "Show this help message")
     .showHelpAfterError();
 
+  configureHelp(program);
+
   addInstallCommand(program, "add");
   addInstallCommand(program, "install");
 
   program
     .command("use")
-    .argument("[source]", "Source plus profile, for example pablof7z/touch-grass@ios-tester")
+    .argument("<source>", "Source plus profile, for example owner/repo@profile")
     .description("Print one rendered agent profile without installing it")
     .option("-s, --profile <profile>", "Profile slug to use")
     .option("--skill <profile>", "Compatibility alias for --profile")
-    .option("-a, --agent <agent>", `Target agent harness (${SUPPORTED_AGENTS.join(", ")})`)
+    .option("-a, --agent <agent>", "Agent profile slug to use; accepts a harness name for backward compatibility")
+    .option("--harness <harness>", `Target harness (${SUPPORTED_AGENTS.join(", ")})`)
+    .option("--target <harness>", "Compatibility alias for --harness")
     .option("--json", "Output JSON")
     .option("--home <dir>", "Override HOME for path expansion")
     .action(async (source = undefined, options) => {
@@ -77,7 +82,7 @@ export async function run(argv = process.argv) {
       if (options.json) {
         printJson(result);
       } else {
-        printOperations(result.operations, result.registryPath);
+        printOperations(result.operations, result.registryPath, result.runInstructions);
       }
     });
 
@@ -98,7 +103,7 @@ export async function run(argv = process.argv) {
       if (options.json) {
         printJson(result);
       } else {
-        printOperations(result.operations, result.registryPath);
+        printOperations(result.operations, result.registryPath, result.runInstructions);
       }
     });
 
@@ -114,9 +119,9 @@ export async function run(argv = process.argv) {
       if (options.json) {
         printJson(result);
       } else {
-        console.log(`${result.action}:`);
+        console.log(`${ui.success(result.action)}:`);
         for (const file of result.files) {
-          console.log(`  ${file}`);
+          console.log(`  ${ui.path(file)}`);
         }
       }
     });
@@ -135,8 +140,10 @@ function addInstallCommand(program, commandName) {
     .argument("[source]", "Local path, GitHub owner/repo, or GitHub URL")
     .description(commandName === "install" ? "Alias for add" : "Install agent profiles from a source")
     .option("-g, --global", "Install globally")
-    .option("-p, --project", "Install into the current project (default)")
-    .option("-a, --agent <agents...>", `Target agent harnesses (${SUPPORTED_AGENTS.join(", ")}, or *)`)
+    .option("-p, --project", "Install into the current project; not supported for Codex profiles")
+    .option("-a, --agent <agents...>", "Agent profile slugs to install; accepts harness names for backward compatibility")
+    .option("--harness <harnesses...>", `Target harnesses (${SUPPORTED_AGENTS.join(", ")}, or *)`)
+    .option("--target <harnesses...>", "Compatibility alias for --harness")
     .option("-s, --profile <profiles...>", "Profile slugs to install (or *)")
     .option("--skill <profiles...>", "Compatibility alias for --profile")
     .option("-l, --list", "List available profiles in the source without installing")
@@ -147,6 +154,12 @@ function addInstallCommand(program, commandName) {
     .option("--json", "Output JSON")
     .option("--home <dir>", "Override HOME for path expansion")
     .action(async (source = undefined, options) => {
+      if (!source) {
+        process.stderr.write(formatMissingSourceError(commandName));
+        process.exitCode = 1;
+        return;
+      }
+
       if (options.list) {
         const profiles = await listAvailable(source, options);
         if (options.json) {
@@ -161,48 +174,72 @@ function addInstallCommand(program, commandName) {
       if (options.json) {
         printJson(result);
       } else {
-        printOperations(result.operations, result.registryPath);
+        printOperations(result.operations, result.registryPath, result.runInstructions);
       }
     });
 }
 
 function printAvailable(profiles) {
   if (profiles.length === 0) {
-    console.log("No profiles found.");
+    console.log(ui.warning("No profiles found."));
     return;
   }
+  console.log(ui.bold("Available profiles:"));
   for (const profile of profiles) {
-    console.log(`${profile.slug}  ${profile.summary || profile.name}`);
+    console.log(`  ${ui.profile(profile.slug)}  ${profile.summary || profile.name}`);
   }
 }
 
 function printInstalled(result) {
   if (result.installs.length === 0) {
-    console.log(`No ${result.scope} profiles installed.`);
+    console.log(ui.warning(`No ${result.scope} profiles installed.`));
     return;
   }
 
+  console.log(ui.bold(`${result.scope} profiles:`));
   for (const install of result.installs) {
-    const missing = install.exists ? "" : " (missing target)";
-    console.log(`${install.profile}  ${install.harness}  ${install.target}${missing}`);
+    const missing = install.exists ? "" : ` ${ui.warning("(missing target)")}`;
+    console.log(`  ${ui.profile(install.profile)}  ${ui.command(install.harness)}  ${ui.path(install.target)}${missing}`);
   }
-  console.log(`Registry: ${result.registryPath}`);
+  console.log(`${ui.bold("Registry:")} ${ui.path(result.registryPath)}`);
 }
 
-function printOperations(operations, registryPath) {
+function printOperations(operations, registryPath, runInstructions = []) {
   if (operations.length === 0) {
-    console.log("No matching profiles.");
+    console.log(ui.warning("No matching profiles."));
     return;
   }
 
   for (const operation of operations) {
-    console.log(`${operation.action}: ${operation.profile} -> ${operation.harness} at ${operation.target}`);
+    console.log(`${formatAction(operation.action)}: ${ui.profile(operation.profile)} -> ${ui.command(operation.harness)} at ${ui.path(operation.target)}`);
   }
   if (registryPath) {
-    console.log(`Registry: ${registryPath}`);
+    console.log(`${ui.bold("Registry:")} ${ui.path(registryPath)}`);
+  }
+  printRunInstructions(runInstructions);
+}
+
+function printRunInstructions(runInstructions = []) {
+  if (runInstructions.length === 0) {
+    return;
+  }
+
+  console.log(ui.bold("Run installed profiles:"));
+  for (const instruction of runInstructions) {
+    console.log(`  ${ui.profile(instruction.profile)} via ${ui.command(instruction.harness)}: ${ui.command(instruction.command)}`);
+    if (instruction.note) {
+      console.log(`    ${instruction.note}`);
+    }
   }
 }
 
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
+
+function formatAction(action) {
+  if (action.startsWith("would-")) {
+    return ui.warning(action);
+  }
+  return ui.success(action);
+}

package/src/constants.js

@@ -1,6 +1,5 @@
 export const PACKAGE_NAME = "awesome-agents";
-export const PACKAGE_VERSION = "0.1.0";
-export const DEFAULT_SOURCE = "pablof7z/touch-grass";
+export const PACKAGE_VERSION = "0.1.3";
 export const DEFAULT_AGENT = "codex";
 export const SUPPORTED_AGENTS = ["codex", "claude-code", "opencode"];
 export const REGISTRY_DIRNAME = ".awesome-agents";