avenic 1.0.0

package/vendor/core-src/skills/catalog.mjs

@@ -0,0 +1,130 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fail } from "../util/fail.mjs";
+import { readJson } from "../util/json.mjs";
+import { git, normalizeRepositoryInput, repositoryIdentity } from "./git.mjs";
+import { loadPacks } from "./packs.mjs";
+import { catalogCacheRoot, defaultCatalogFile, deprecatedEnvironmentValue, knownCatalogsFile } from "./paths.mjs";
+
+const DEFAULT_CATALOG_SPEC = "Echo-Kang-hub/avenic-catalog#main";
+
+export function parseCatalogSpec(spec) {
+  if (typeof spec !== "string" || spec.length === 0) {
+    fail(`Invalid catalog spec: ${spec}`);
+  }
+  const hashIndex = spec.lastIndexOf("#");
+  const repository = hashIndex === -1 ? spec : spec.slice(0, hashIndex);
+  const ref = hashIndex === -1 ? "main" : spec.slice(hashIndex + 1) || "main";
+  return { repository: normalizeRepositoryInput(repository), ref };
+}
+
+export async function loadDefaultCatalogSpec(environment = process.env) {
+  const catalogSpec = deprecatedEnvironmentValue(environment, "AVENIC_CATALOG_SPEC", "AGENTHOME_CATALOG_SPEC");
+  if (catalogSpec) {
+    return catalogSpec;
+  }
+  const file = defaultCatalogFile(environment);
+  if (existsSync(file)) {
+    const config = await readJson(file);
+    if (typeof config.spec === "string" && config.spec.length > 0) {
+      return config.spec;
+    }
+  }
+  return DEFAULT_CATALOG_SPEC;
+}
+
+export async function setDefaultCatalogSpec(environment = process.env, spec) {
+  const file = defaultCatalogFile(environment);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify({ schemaVersion: 1, spec }, null, 2)}\n`, "utf8");
+}
+
+// Short label for a catalog spec: "owner/repo" for remotes, the directory
+// name for local paths. Preserves the original spelling for display.
+export function catalogDisplayName(spec) {
+  const { repository } = parseCatalogSpec(spec);
+  if (/^(https?:\/\/|ssh:\/\/)/i.test(repository)) {
+    const clean = repository.replace(/\.git$/i, "").replace(/\/+$/, "");
+    return clean.split("/").slice(-2).join("/");
+  }
+  if (/^git@/i.test(repository)) {
+    return repository.replace(/\.git$/i, "").split(":").at(-1);
+  }
+  return repository.split(/[\\/]/).filter(Boolean).at(-1) ?? repository;
+}
+
+export async function loadKnownCatalogs(environment = process.env) {
+  const file = knownCatalogsFile(environment);
+  if (!existsSync(file)) {
+    return [];
+  }
+  const config = await readJson(file);
+  const catalogs = Array.isArray(config.catalogs) ? config.catalogs : [];
+  return catalogs.filter((entry) => typeof entry.spec === "string" && entry.spec.length > 0);
+}
+
+// Record a catalog in the registry (most recently used first, deduplicated by
+// spec). The registry drives `catalog select`; the current spec stays in the
+// default catalog file.
+export async function registerKnownCatalog(environment = process.env, spec) {
+  const known = await loadKnownCatalogs(environment);
+  const next = [{ name: catalogDisplayName(spec), spec }, ...known.filter((entry) => entry.spec !== spec)];
+  const file = knownCatalogsFile(environment);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify({ schemaVersion: 1, catalogs: next }, null, 2)}\n`, "utf8");
+}
+
+function cacheDirectory(environment, repository) {
+  const identity = repositoryIdentity(repository).replace(/\\/g, "/");
+  const parts = identity.split("/").filter(Boolean);
+  const owner = parts.at(-2) ?? "catalog";
+  const name = parts.at(-1) ?? "catalog";
+  const slug = `${owner}-${name}`
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
+  return path.join(catalogCacheRoot(environment), slug);
+}
+
+export async function ensureCatalog(spec, options = {}) {
+  const environment = options.environment ?? process.env;
+  const { repository, ref } = parseCatalogSpec(spec);
+  const directory = cacheDirectory(environment, repository);
+  try {
+    if (existsSync(path.join(directory, ".git"))) {
+      git(["-C", directory, "fetch", "--depth", "1", "origin", ref], { capture: true });
+    } else {
+      await mkdir(directory, { recursive: true });
+      git(["-C", directory, "init", "--quiet"], { capture: true });
+      git(["-C", directory, "remote", "add", "origin", repository], { capture: true });
+      git(["-C", directory, "fetch", "--depth", "1", "origin", ref], { capture: true });
+    }
+    git(["-C", directory, "checkout", "--quiet", "--detach", "FETCH_HEAD"], { capture: true });
+    const revision = git(["-C", directory, "rev-parse", "HEAD"], { capture: true });
+    return { catalogRoot: directory, repository, ref, revision, spec };
+  } catch (error) {
+    fail(
+      `${error.message}\nUnable to fetch catalog: ${spec}\n` +
+      "Check your GitHub authentication (gh auth login, SSH key, or credential helper) and the catalog spec.\n" +
+      "To point Avenic at your own catalog: avenic catalog add <owner/repo>",
+    );
+  }
+}
+
+// Register a catalog: save the default spec and the known-catalog entry
+// first, then try to fetch and preview its Packs. The spec stays configured
+// even when the preview fails (offline, missing credentials, no Packs yet).
+export async function registerCatalog(spec, options = {}) {
+  const io = options.io ?? console;
+  parseCatalogSpec(spec);
+  await setDefaultCatalogSpec(options.environment, spec);
+  await registerKnownCatalog(options.environment, spec);
+  try {
+    const catalogInfo = await ensureCatalog(spec, { environment: options.environment, io });
+    const packs = [...(await loadPacks(catalogInfo.catalogRoot)).values()];
+    return { spec, catalogInfo, packs, previewFailed: false };
+  } catch (error) {
+    return { spec, packs: [], previewFailed: true, error };
+  }
+}

package/vendor/core-src/skills/direct.mjs

@@ -0,0 +1,209 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fail } from "../util/fail.mjs";
+import { isInside, removeEmptyDirectory } from "../util/fs.mjs";
+import { readJson, writeJson } from "../util/json.mjs";
+import { cloneHead, deriveSourceId, git, normalizeRepositoryInput } from "./git.mjs";
+import { assertSafeSkillName } from "./ids.mjs";
+import { previousManagedState, removeSkillDirectories } from "./install.mjs";
+import { stateRoot } from "./paths.mjs";
+import { detectSkillRoot, discoverSourceSkills } from "./sources.mjs";
+
+export function directRoot(context) {
+  return context.global
+    ? path.join(stateRoot(context.environment), "direct")
+    : path.join(context.root, ".agents", "direct");
+}
+
+export function directLicensesRoot(context) {
+  return context.global
+    ? path.join(stateRoot(context.environment), "licenses")
+    : path.join(context.root, ".agents", "licenses");
+}
+
+export async function readDirectState(context) {
+  if (!existsSync(context.lockFile)) {
+    return { directSources: [] };
+  }
+  const lock = await readJson(context.lockFile);
+  return { directSources: lock.directSources ?? [] };
+}
+
+export async function writeDirectState(context, state) {
+  await mkdir(path.dirname(context.lockFile), { recursive: true });
+  const previousLock = existsSync(context.lockFile) ? await readJson(context.lockFile) : {};
+  const lock = { ...previousLock, schemaVersion: 3, directSources: state.directSources };
+  await writeJson(context.lockFile, lock);
+  const previousConfig = existsSync(context.configFile) ? await readJson(context.configFile) : {};
+  const config = {
+    ...previousConfig,
+    schemaVersion: 3,
+    direct: state.directSources.map((source) => ({
+      source: source.repository,
+      skills: source.skills,
+    })),
+  };
+  await writeJson(context.configFile, config);
+}
+
+async function ensureDirectClone(repository, directory) {
+  if (existsSync(path.join(directory, ".git"))) {
+    git(["-C", directory, "fetch", "--depth", "1", "origin"], { capture: true });
+    git(["-C", directory, "checkout", "--quiet", "--detach", "FETCH_HEAD"], { capture: true });
+  } else {
+    await cloneHead({ repository }, directory);
+  }
+  return git(["-C", directory, "rev-parse", "HEAD"], { capture: true });
+}
+
+async function findLicenseFile(cloneDirectory) {
+  const entries = await readdir(cloneDirectory, { withFileTypes: true });
+  return (
+    entries.find((entry) => entry.isFile() && /^licen[cs]e(?:\.|$)/i.test(entry.name))?.name ?? null
+  );
+}
+
+export async function addDirectSkills(context, sourceReference, skillNames, options = {}) {
+  const io = options.io ?? console;
+  if (sourceReference.includes("#")) {
+    fail(
+      `Refs are not supported for direct sources: ${sourceReference}. Add the source to the catalog to pin a revision.`,
+    );
+  }
+  const repository = normalizeRepositoryInput(sourceReference);
+  const sourceId = deriveSourceId(repository);
+  const state = await readDirectState(context);
+  const existing = state.directSources.find((source) => source.id === sourceId);
+  const directory = path.join(directRoot(context), sourceId);
+  const revision = await ensureDirectClone(repository, directory);
+
+  const source = {
+    id: sourceId,
+    name: sourceReference.replace(/\.git$/i, ""),
+    repository,
+    revision,
+    skillRoot: existing?.skillRoot,
+  };
+  if (!source.skillRoot) {
+    source.skillRoot = await detectSkillRoot(directory);
+  }
+  const discovered = await discoverSourceSkills(source, directory);
+  const requestedNames = [...new Set(skillNames.length > 0 ? skillNames : discovered.names)];
+  requestedNames.forEach(assertSafeSkillName);
+  for (const name of requestedNames) {
+    if (!discovered.names.includes(name)) {
+      fail(`Skill not found upstream: ${name}`);
+    }
+  }
+
+  const managed = await previousManagedState(context);
+  const managedNames = requestedNames.filter((name) => managed.has(name));
+  if (managedNames.length > 0) {
+    fail(
+      `Managed by configured Packs: ${managedNames.join(", ")}. Uninstall the Pack or remove the Skill from the Catalog`,
+    );
+  }
+  for (const other of state.directSources.filter((item) => item.id !== sourceId)) {
+    const conflicts = requestedNames.filter((name) => other.skills.includes(name));
+    if (conflicts.length > 0) {
+      fail(`Skill ${conflicts.join(", ")} already belongs to source ${other.id}`);
+    }
+  }
+
+  if (
+    existing &&
+    existing.revision === revision &&
+    requestedNames.every((name) => existing.skills.includes(name))
+  ) {
+    io.log(
+      `Already installed: ${sourceId} (${requestedNames.length} Skill${requestedNames.length === 1 ? "" : "s"})`,
+    );
+    return { names: requestedNames, sourceId, revision, alreadyInstalled: true };
+  }
+
+  for (const targetConfig of context.targets) {
+    const destination = targetConfig.destination;
+    await mkdir(destination, { recursive: true });
+    for (const name of requestedNames) {
+      const target = path.join(destination, name);
+      if (!isInside(destination, target)) {
+        fail(`Install path escaped its target: ${target}`);
+      }
+      await rm(target, { recursive: true, force: true });
+      const upstreamPath = source.skillPaths?.[name] ?? name;
+      await cp(path.join(directory, source.skillRoot, upstreamPath), target, { recursive: true });
+    }
+    io.log(`✓ ${targetConfig.label}`);
+    io.log(`  Path: ${destination}`);
+    io.log(`  Added ${requestedNames.length} direct Skill${requestedNames.length === 1 ? "" : "s"}`);
+  }
+
+  const licenseName = await findLicenseFile(directory);
+  if (licenseName) {
+    const licenseDirectory = path.join(directLicensesRoot(context), sourceId);
+    await mkdir(licenseDirectory, { recursive: true });
+    await cp(path.join(directory, licenseName), path.join(licenseDirectory, "LICENSE"));
+  }
+
+  const combined = {
+    ...source,
+    skillRoot: source.skillRoot.replace(/\\/g, "/"),
+    skills: [...new Set([...(existing?.skills ?? []), ...requestedNames])],
+  };
+  if (source.skillPaths) {
+    combined.skillPaths = source.skillPaths;
+  }
+  const directSources = [...state.directSources.filter((item) => item.id !== sourceId), combined];
+  await writeDirectState(context, { directSources });
+  return { names: requestedNames, sourceId, revision };
+}
+
+export async function removeDirectSkills(context, skillNames) {
+  if (skillNames.length === 0) {
+    return [];
+  }
+  const state = await readDirectState(context);
+  const removedNames = new Set();
+  const keptSources = [];
+  const removedSources = [];
+  for (const source of state.directSources) {
+    const removed = source.skills.filter((name) => skillNames.includes(name));
+    removed.forEach((name) => removedNames.add(name));
+    const remaining = source.skills.filter((name) => !skillNames.includes(name));
+    if (remaining.length > 0) {
+      keptSources.push({ ...source, skills: remaining });
+    } else if (removed.length > 0) {
+      removedSources.push(source);
+    }
+  }
+  if (removedNames.size === 0) {
+    return [];
+  }
+  await writeDirectState(context, { directSources: keptSources });
+  for (const source of removedSources) {
+    await rm(path.join(directRoot(context), source.id), { recursive: true, force: true });
+    await rm(path.join(directLicensesRoot(context), source.id), { recursive: true, force: true });
+  }
+  await removeEmptyDirectory(directRoot(context));
+  await removeEmptyDirectory(directLicensesRoot(context));
+  return [...removedNames];
+}
+
+// Remove externally installed Skills: managed Skills are rejected (they
+// belong to Packs), then the direct records and the target directories go.
+export async function removeExternalSkills(context, skillNames, options = {}) {
+  const io = options.io ?? console;
+  const uniqueNames = [...new Set(skillNames)];
+  uniqueNames.forEach(assertSafeSkillName);
+  const managed = await previousManagedState(context);
+  const managedNames = uniqueNames.filter((skillName) => managed.has(skillName));
+  if (managedNames.length > 0) {
+    fail(
+      `Managed by configured Packs: ${managedNames.join(", ")}. Uninstall the Pack or remove the Skill from the Catalog`,
+    );
+  }
+  const directRemoved = await removeDirectSkills(context, uniqueNames);
+  const removedDirectories = await removeSkillDirectories(context, uniqueNames, io);
+  return { directRemoved, removedDirectories };
+}

package/vendor/core-src/skills/git.mjs

@@ -0,0 +1,93 @@
+import { spawnSync } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import process from "node:process";
+import { fail } from "../util/fail.mjs";
+
+export { fail };
+
+export function run(command, argumentsList, options = {}) {
+  const result = spawnSync(command, argumentsList, {
+    cwd: options.cwd,
+    encoding: options.capture ? "utf8" : undefined,
+    env: options.env ?? process.env,
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+  if (result.error) {
+    fail(`Unable to run ${command}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const details = options.capture ? result.stderr.trim() : "";
+    fail(`${command} failed${details ? `: ${details}` : ""}`);
+  }
+  return options.capture ? result.stdout.trim() : "";
+}
+
+export function git(argumentsList, options = {}) {
+  return run("git", argumentsList, options);
+}
+
+export function normalizeRepositoryInput(repository) {
+  if (/^[^\s/:@]+\/[^\s/]+$/.test(repository)) {
+    return `https://github.com/${repository.replace(/\.git$/i, "")}.git`;
+  }
+  return repository;
+}
+
+export function repositoryIdentity(repository) {
+  return normalizeRepositoryInput(repository)
+    .replace(/^git\+/, "")
+    .replace(/^git@github\.com:/i, "https://github.com/")
+    .replace(/\.git$/i, "")
+    .replace(/\/$/, "")
+    .toLowerCase();
+}
+
+export function deriveSourceId(repository) {
+  const parts = repositoryIdentity(repository).split(/[/:]/).filter(Boolean);
+  const owner = parts.at(-2) ?? "source";
+  const name = parts.at(-1) ?? "skills";
+  return `${owner}-${name}`
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
+}
+
+export function currentRepositoryState(catalogRoot) {
+  let repository = null;
+  let revision = null;
+  let dirty = null;
+  try {
+    const remotes = git(["-C", catalogRoot, "remote"], { capture: true })
+      .split(/\r?\n/)
+      .filter(Boolean);
+    if (remotes.length > 0) {
+      repository = git(["-C", catalogRoot, "remote", "get-url", remotes[0]], { capture: true });
+    }
+    revision = git(["-C", catalogRoot, "rev-parse", "HEAD"], { capture: true });
+    dirty = Boolean(git(["-C", catalogRoot, "status", "--porcelain"], { capture: true }));
+  } catch {
+    // npm's cache copy is intentionally not a Git working tree.
+  }
+  return { repository, revision, dirty };
+}
+
+export async function cloneHead(source, destination) {
+  git(["clone", "--depth", "1", source.repository, destination]);
+  return git(["-C", destination, "rev-parse", "HEAD"], { capture: true });
+}
+
+export async function cloneRevision(source, destination) {
+  await mkdir(destination, { recursive: true });
+  git(["-C", destination, "init", "--quiet"]);
+  git(["-C", destination, "remote", "add", "origin", source.repository]);
+  git(["-C", destination, "fetch", "--depth", "1", "origin", source.revision]);
+  git(["-C", destination, "checkout", "--quiet", "--detach", "FETCH_HEAD"]);
+}
+
+export function remoteHead(source) {
+  const output = git(["ls-remote", source.repository, "HEAD"], { capture: true });
+  const revision = output.split(/\s+/)[0];
+  if (!/^[0-9a-f]{40}$/i.test(revision)) {
+    fail(`Unable to read upstream HEAD: ${source.id}`);
+  }
+  return revision;
+}

package/vendor/core-src/skills/ids.mjs

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { fail } from "../util/fail.mjs";
+
+export function assertSafeId(value, label) {
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(value)) {
+    fail(`${label} must contain only lowercase letters, numbers, dots, underscores, or hyphens: ${value}`);
+  }
+}
+
+export function assertSafeSkillName(value) {
+  if (!value || value === "." || value === ".." || path.basename(value) !== value) {
+    fail(`Invalid Skill name: ${value}`);
+  }
+}
+
+export function assertSafeRelativePath(value, label) {
+  const normalized = value?.replace(/\\/g, "/");
+  if (
+    !normalized ||
+    path.isAbsolute(normalized) ||
+    normalized.split("/").some((part) => !part || part === "." || part === "..")
+  ) {
+    fail(`Invalid ${label}: ${value}`);
+  }
+  return normalized;
+}
+
+export function assertSafeSkillRoot(value) {
+  if (value === ".") {
+    return value;
+  }
+  return assertSafeRelativePath(value, "Skill root");
+}
+
+export function assertSafeSkillPath(value, label) {
+  if (value === ".") {
+    return value;
+  }
+  return assertSafeRelativePath(value, label);
+}