@callmeradical/augy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lars Cromley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# augy
+
+**Homebrew for AI agent skills** — install, version, update, and rollback skills across OpenCode, Claude, and Codex from a single CLI.
+
+```
+augy install tdd              # install by name via a tap
+augy update                   # upgrade everything with upstream changes
+augy diff tdd                 # browse what changed before upgrading
+augy rollback tdd abc1234     # something broke — go back
+```
+
+---
+
+## Install
+
+```bash
+npm install -g augy
+```
+
+Requires Node.js ≥ 18.
+
+---
+
+## How it works
+
+Skills are directories containing a `SKILL.md` file that an AI agent loads as context. augy tracks which skills you have installed, where they came from (GitHub), and what version (commit SHA) is on disk — then lets you update, diff, and roll back just like a package manager.
+
+**Supported agents**
+
+| Agent | Default skills path |
+|---|---|
+| OpenCode | `~/.opencode/skills/` |
+| Claude | `~/.claude/skills/` |
+| Codex | `~/.codex/skills/` (or `$CODEX_HOME/skills`) |
+
+A single skill can be deployed to multiple agents simultaneously.
+
+---
+
+## Commands
+
+### `augy install [url]`
+Install skills from a GitHub URL, `owner/repo[/path]` shorthand, or a bare name resolved via a registered tap.
+
+```bash
+augy install https://github.com/mattpocock/skills/tree/main
+augy install mattpocock/skills/skills/engineering/tdd
+augy install tdd                    # resolves via taps
+augy install tdd --agent opencode   # target a specific agent
+```
+
+### `augy scan`
+Find skills already on disk that augy doesn't know about. Auto-detects provenance via git remotes and `SKILL.md` frontmatter, groups results into *detected* vs *no provenance found* with filesystem paths shown for unknown skills. Imports them into the registry.
+
+```bash
+augy scan
+```
+
+### `augy update [skill]`
+Check all installed skills for upstream SHA drift. Shows a list of available upgrades, lets you select which to apply, archives the current version before overwriting.
+
+```bash
+augy update              # check + upgrade everything
+augy update tdd          # single skill
+```
+
+### `augy diff <skill> [sha1] [sha2]`
+Interactive file-level diff browser. Three modes:
+
+```bash
+augy diff tdd                    # installed ↔ upstream HEAD
+augy diff tdd abc1234            # installed ↔ specific SHA
+augy diff tdd abc1234 def5678    # two local archives
+```
+
+### `augy rollback <skill> [sha]`
+Restore a skill to any previously archived version.
+
+```bash
+augy rollback tdd                # interactive version picker
+augy rollback tdd abc1234        # specific SHA (short or full)
+```
+
+### `augy list`
+Show all installed skills, their SHAs, agents, and update status.
+
+```bash
+augy list
+augy list --json    # raw registry JSON
+```
+
+### `augy info <skill>`
+Full metadata: source, SHA, agents with paths, version history, and a preview of the skill description.
+
+```bash
+augy info tdd
+```
+
+### `augy search [query]`
+Search all registered taps for available skills.
+
+```bash
+augy search           # full index
+augy search tdd       # filter by name
+```
+
+### `augy tap add|remove|list`
+Manage trusted repos (taps) — once added, skills can be installed by bare name.
+
+```bash
+augy tap add mattpocock/skills
+augy tap add mattpocock/skills --path skills/engineering
+augy tap list
+augy tap remove mattpocock/skills
+```
+
+### `augy set-source <skill> <url>`
+Attach a GitHub source to a skill imported without one (e.g. via `augy scan`). Enables updates and diffs. Accepts tree and blob URLs.
+
+```bash
+augy set-source commit https://github.com/owner/repo/tree/main/skills/commit
+```
+
+### `augy uninstall <skill>`
+Remove a skill from all agent paths and the registry. Optionally prune version archives.
+
+```bash
+augy uninstall tdd
+```
+
+### `augy pin|unpin <skill>`
+Pin a skill to skip it during `augy update`.
+
+```bash
+augy pin tdd
+augy unpin tdd
+```
+
+---
+
+## Taps
+
+Taps are trusted GitHub repos containing skills. Add one and install by name without knowing the full URL:
+
+```bash
+augy tap add mattpocock/skills
+augy install tdd        # resolves to mattpocock/skills automatically
+```
+
+---
+
+## Version storage
+
+Every upgrade archives the current skill to `~/.augy/versions/<skill>/<sha>/` before overwriting it — giving you a full local snapshot history to diff or rollback to at any time.
+
+```
+~/.augy/
+  registry.json             ← lockfile (human-readable JSON)
+  versions/
+    tdd/
+      7afa86d.../           ← snapshot before last upgrade
+      abc1234.../           ← older snapshot
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AUGY_HOME` | `~/.augy` | Override augy's home directory |
+| `CODEX_HOME` | `~/.codex` | Override Codex agent path |
+| `GITHUB_TOKEN` | — | Raise GitHub API rate limit from 60 to 5000 req/hr |
+
+---
+
+## Docs
+
+Full documentation at **[augy.dev](https://augy.dev)** *(coming soon — see `docs/` for the source)*.
+
+---
+
+## License
+
+MIT

package/dist/chunk-EU54UQ4C.js

@@ -0,0 +1,144 @@
+// src/github.ts
+function parseGitHubUrl(input) {
+  input = input.trim().replace(/\/$/, "");
+  if (input.startsWith("https://github.com/") || input.startsWith("http://github.com/")) {
+    const url = new URL(input.startsWith("http://") ? input.replace("http://", "https://") : input);
+    const parts2 = url.pathname.replace(/^\//, "").split("/");
+    const owner2 = parts2[0] ?? "";
+    const repo2 = parts2[1] ?? "";
+    if (parts2[2] === "tree") {
+      const ref = parts2[3];
+      const path2 = parts2.slice(4).join("/");
+      return { owner: owner2, repo: repo2, path: path2, ref };
+    }
+    if (parts2[2] === "blob") {
+      const ref = parts2[3];
+      const filePath = parts2.slice(4);
+      const lastPart = filePath.at(-1) ?? "";
+      const path2 = lastPart.includes(".") ? filePath.slice(0, -1).join("/") : filePath.join("/");
+      return { owner: owner2, repo: repo2, path: path2, ref };
+    }
+    return { owner: owner2, repo: repo2, path: parts2.slice(2).join("/"), ref: void 0 };
+  }
+  const parts = input.split("/");
+  if (parts.length < 2) throw new Error(`Cannot parse GitHub reference: "${input}"`);
+  const owner = parts[0];
+  const repo = parts[1];
+  const path = parts.slice(2).join("/");
+  return { owner, repo, path, ref: void 0 };
+}
+function apiHeaders() {
+  const token = process.env["GITHUB_TOKEN"];
+  return {
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    ...token ? { Authorization: `Bearer ${token}` } : {}
+  };
+}
+async function ghFetch(url) {
+  const res = await fetch(url, { headers: apiHeaders() });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`GitHub API ${res.status}: ${url}
+${body}`);
+  }
+  return res.json();
+}
+async function listContents(owner, repo, path, ref) {
+  const base = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
+  const url = ref ? `${base}?ref=${encodeURIComponent(ref)}` : base;
+  const result = await ghFetch(url);
+  if (!Array.isArray(result)) throw new Error(`Expected directory at "${path}", got a file`);
+  return result;
+}
+async function latestShaForPath(owner, repo, path, ref) {
+  let url = `https://api.github.com/repos/${owner}/${repo}/commits?path=${encodeURIComponent(path)}&per_page=1`;
+  if (ref) url += `&sha=${encodeURIComponent(ref)}`;
+  const commits = await ghFetch(url);
+  if (!commits.length) throw new Error(`No commits found for path "${path}" in ${owner}/${repo}`);
+  return commits[0].sha;
+}
+async function defaultBranch(owner, repo) {
+  const data = await ghFetch(
+    `https://api.github.com/repos/${owner}/${repo}`
+  );
+  return data.default_branch;
+}
+function isSkillFile(name) {
+  return name.toLowerCase() === "skill.md";
+}
+async function discoverSkills(coords) {
+  const { owner, repo, path, ref } = coords;
+  try {
+    const items = await listContents(owner, repo, path, ref);
+    if (items.some((i) => i.type === "file" && isSkillFile(i.name))) {
+      const skillName = path.split("/").filter(Boolean).at(-1) ?? repo;
+      const sha = await latestShaForPath(owner, repo, path || ".", ref);
+      return [{ name: skillName, repoPath: path, gigetSource: buildGigetSource(owner, repo, path, ref), sha }];
+    }
+  } catch {
+  }
+  const commitSha = await resolveRefToCommitSha(owner, repo, ref);
+  const { tree, truncated } = await ghFetch(
+    `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitSha}?recursive=1`
+  );
+  if (truncated) {
+    console.warn("Warning: repo tree truncated, falling back to shallow scan");
+  }
+  const prefix = path ? `${path}/` : "";
+  const skillMdPaths = tree.filter((item) => item.type === "blob" && item.path.startsWith(prefix) && isSkillFile(item.path.split("/").at(-1) ?? "")).map((item) => item.path.split("/").slice(0, -1).join("/"));
+  if (!skillMdPaths.length) return [];
+  const results = await Promise.allSettled(
+    skillMdPaths.map(async (skillPath) => {
+      const sha = await latestShaForPath(owner, repo, skillPath, ref);
+      const name = skillPath.split("/").at(-1);
+      return {
+        name,
+        repoPath: skillPath,
+        gigetSource: buildGigetSource(owner, repo, skillPath, ref),
+        sha
+      };
+    })
+  );
+  return results.filter((r) => r.status === "fulfilled").map((r) => r.value).sort((a, b) => a.name.localeCompare(b.name));
+}
+async function resolveRefToCommitSha(owner, repo, ref) {
+  const branch = ref ?? await defaultBranch(owner, repo);
+  if (/^[0-9a-f]{40}$/i.test(branch)) return branch;
+  try {
+    const data = await ghFetch(
+      `https://api.github.com/repos/${owner}/${repo}/git/refs/heads/${branch}`
+    );
+    return data.object.sha;
+  } catch {
+  }
+  try {
+    const data = await ghFetch(
+      `https://api.github.com/repos/${owner}/${repo}/git/refs/tags/${branch}`
+    );
+    return data.object.sha;
+  } catch {
+  }
+  throw new Error(`Cannot resolve ref "${branch}" in ${owner}/${repo}`);
+}
+function buildGigetSource(owner, repo, path, ref) {
+  const p = path ? `/${path}` : "";
+  const r = ref ? `#${ref}` : "";
+  return `github:${owner}/${repo}${p}${r}`;
+}
+async function downloadSkill(gigetSource, destPath) {
+  const { downloadTemplate } = await import("giget");
+  await downloadTemplate(gigetSource, {
+    dir: destPath,
+    force: true,
+    preferOffline: false
+  });
+}
+
+export {
+  parseGitHubUrl,
+  latestShaForPath,
+  discoverSkills,
+  buildGigetSource,
+  downloadSkill
+};

package/dist/chunk-KCQY4IDO.js

@@ -0,0 +1,142 @@
+// src/provenance.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative } from "path";
+var exec = promisify(execFile);
+async function detectProvenance(skillPath, _skillName) {
+  const git = await tryGitProvenance(skillPath);
+  if (git) return git;
+  const fm = await tryFrontmatterProvenance(skillPath);
+  if (fm) return fm;
+  return void 0;
+}
+async function tryGitProvenance(skillPath) {
+  try {
+    const { stdout: root } = await exec("git", [
+      "-C",
+      skillPath,
+      "rev-parse",
+      "--show-toplevel"
+    ]);
+    const repoRoot = root.trim();
+    const { stdout: remoteRaw } = await exec("git", [
+      "-C",
+      skillPath,
+      "remote",
+      "get-url",
+      "origin"
+    ]);
+    const remoteUrl = remoteRaw.trim();
+    const httpsUrl = normaliseGitUrl(remoteUrl);
+    if (!httpsUrl) return void 0;
+    const repoPath = relative(repoRoot, skillPath).replace(/\\/g, "/");
+    const { stdout: shaRaw } = await exec("git", [
+      "-C",
+      skillPath,
+      "log",
+      "-1",
+      "--format=%H",
+      "--",
+      "."
+    ]);
+    const sha = shaRaw.trim() || void 0;
+    const ownerRepo = githubOwnerRepo(httpsUrl);
+    if (!ownerRepo) return void 0;
+    const source = repoPath ? `${ownerRepo}/${repoPath}` : ownerRepo;
+    const gigetSource = repoPath ? `github:${ownerRepo}/${repoPath}` : `github:${ownerRepo}`;
+    return {
+      source,
+      gigetSource,
+      sha,
+      confidence: "git",
+      description: `git remote: ${httpsUrl}  path: ${repoPath || "(root)"}`
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function tryFrontmatterProvenance(skillPath) {
+  const skillMdPath = join(skillPath, "SKILL.md");
+  if (!existsSync(skillMdPath)) return void 0;
+  try {
+    const raw = await readFile(skillMdPath, "utf8");
+    const fm = parseFrontmatter(raw);
+    if (!fm) return void 0;
+    const sourceRaw = fm.source ?? fm.repo ?? fm.origin;
+    if (!sourceRaw) return void 0;
+    const ownerRepo = githubOwnerRepo(normaliseGitUrl(sourceRaw) ?? sourceRaw);
+    if (!ownerRepo) return void 0;
+    return {
+      source: ownerRepo,
+      gigetSource: `github:${ownerRepo}`,
+      sha: void 0,
+      // frontmatter doesn't carry a SHA
+      confidence: "frontmatter",
+      description: `SKILL.md frontmatter source: ${sourceRaw}`
+    };
+  } catch {
+    return void 0;
+  }
+}
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return void 0;
+  const block = match[1];
+  const result = {};
+  for (const line of block.split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase();
+    const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, "");
+    if (key && value) result[key] = value;
+  }
+  return result;
+}
+function normaliseGitUrl(raw) {
+  raw = raw.trim();
+  if (raw.startsWith("https://github.com/")) return raw.replace(/\.git$/, "");
+  if (raw.startsWith("http://github.com/")) return raw.replace("http://", "https://").replace(/\.git$/, "");
+  const sshMatch = raw.match(/^git@github\.com:(.+?)(?:\.git)?$/);
+  if (sshMatch) return `https://github.com/${sshMatch[1]}`;
+  if (/^[\w.-]+\/[\w.-]/.test(raw)) return `https://github.com/${raw.replace(/\.git$/, "")}`;
+  return void 0;
+}
+function githubOwnerRepo(url) {
+  if (!url) return void 0;
+  try {
+    const u = new URL(url.startsWith("http") ? url : `https://github.com/${url}`);
+    if (!u.hostname.includes("github.com")) return void 0;
+    return u.pathname.replace(/^\//, "").replace(/\.git$/, "");
+  } catch {
+    return void 0;
+  }
+}
+async function injectSourceIntoSkillMd(skillPath, source) {
+  const skillMdPath = join(skillPath, "SKILL.md");
+  if (!existsSync(skillMdPath)) return;
+  const { writeFile } = await import("fs/promises");
+  const raw = await readFile(skillMdPath, "utf8");
+  const hasFrontmatter = /^---\r?\n/.test(raw);
+  let updated;
+  if (hasFrontmatter) {
+    if (/^source\s*:/m.test(raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "")) {
+      return;
+    }
+    updated = raw.replace(/^(---\r?\n)/, `$1source: ${source}
+`);
+  } else {
+    updated = `---
+source: ${source}
+---
+
+${raw}`;
+  }
+  await writeFile(skillMdPath, updated, "utf8");
+}
+
+export {
+  detectProvenance,
+  injectSourceIntoSkillMd
+};

package/dist/chunk-PX2LVUHV.js

@@ -0,0 +1,53 @@
+import {
+  versionArchivePath
+} from "./chunk-ZW6ZKHTF.js";
+
+// src/versions.ts
+import { cp, mkdir, rm } from "fs/promises";
+import { existsSync } from "fs";
+async function archiveVersion(sourcePath, skillName, sha) {
+  const dest = versionArchivePath(skillName, sha);
+  if (existsSync(dest)) {
+    return dest;
+  }
+  await mkdir(dest, { recursive: true });
+  await cp(sourcePath, dest, { recursive: true });
+  return dest;
+}
+async function restoreVersion(skillName, sha, destPaths) {
+  const src = versionArchivePath(skillName, sha);
+  if (!existsSync(src)) {
+    throw new Error(
+      `No archived version found for "${skillName}" @ ${sha.slice(0, 7)}.
+Archive path: ${src}`
+    );
+  }
+  await Promise.all(
+    destPaths.map(async (dest) => {
+      await rm(dest, { recursive: true, force: true });
+      await mkdir(dest, { recursive: true });
+      await cp(src, dest, { recursive: true });
+    })
+  );
+}
+async function pruneVersions(skillName, keepShas = []) {
+  const { join } = await import("path");
+  const { versionArchivePath: archivePath, versionsDir } = await import("./registry-QVCNZXBZ.js");
+  const skillVersionsDir = join(versionsDir(), skillName);
+  if (!existsSync(skillVersionsDir)) return;
+  const { readdir } = await import("fs/promises");
+  const entries = await readdir(skillVersionsDir);
+  await Promise.all(
+    entries.filter((e) => !keepShas.includes(e)).map((e) => rm(join(skillVersionsDir, e), { recursive: true, force: true }))
+  );
+}
+function archiveExists(skillName, sha) {
+  return existsSync(versionArchivePath(skillName, sha));
+}
+
+export {
+  archiveVersion,
+  restoreVersion,
+  pruneVersions,
+  archiveExists
+};

package/dist/chunk-R2TJ3UDO.js

@@ -0,0 +1,43 @@
+// src/agents.ts
+import { homedir } from "os";
+import { join } from "path";
+function resolveHome(p) {
+  return p.startsWith("~") ? join(homedir(), p.slice(1)) : p;
+}
+function codexSkillsPath() {
+  const codexHome = process.env["CODEX_HOME"];
+  if (codexHome) return join(codexHome, "skills");
+  return resolveHome("~/.codex/skills");
+}
+var AGENTS = [
+  {
+    id: "opencode",
+    name: "OpenCode",
+    skillsPath: resolveHome("~/.opencode/skills"),
+    skillFile: "SKILL.md"
+  },
+  {
+    id: "claude",
+    name: "Claude",
+    skillsPath: resolveHome("~/.claude/skills"),
+    skillFile: "SKILL.md"
+  },
+  {
+    id: "codex",
+    name: "Codex",
+    skillsPath: codexSkillsPath(),
+    skillFile: "SKILL.md"
+  }
+];
+function agentById(id) {
+  return AGENTS.find((a) => a.id === id);
+}
+function agentSkillPath(agent, skillName) {
+  return join(agent.skillsPath, skillName);
+}
+
+export {
+  AGENTS,
+  agentById,
+  agentSkillPath
+};