@moskala/oneagent-core 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moskala/oneagent-core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Core library for oneagent — one source of truth for AI agent rules",
   "license": "MIT",

package/src/agents.ts

@@ -64,7 +64,7 @@ export const AGENT_DEFINITIONS: AgentDefinition[] = [
     target: "copilot",
     displayName: "GitHub Copilot",
     hint: ".github/instructions/*.instructions.md",
-    detectIndicators: [".github/copilot-instructions.md", ".github"],
+    detectIndicators: [".github/copilot-instructions.md", ".github/instructions"],
     mainFile: ".github/copilot-instructions.md",
     skillsDir: ".github/skills",
     // rules: generated as <name>.instructions.md files, not symlinks

package/src/apply-template.ts

@@ -4,6 +4,7 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import type { AgentTarget } from "./types.ts";
 import { addOpenCodePlugin } from "./opencode.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -29,16 +30,19 @@ export interface TemplateDefinition {
 // Parses name, description, skills and plugins from a template.yml string.
 // This is the single source of truth for the template.yml format — used by
 // both builtin template loading and GitHub URL template fetching.
-export function parseTemplateYaml(yamlText: string, fallbackName = "custom"): Pick<TemplateDefinition, "name" | "description" | "skills" | "plugins"> {
+export function parseTemplateYaml(yamlText: string, fallbackName = "custom"): Pick<TemplateDefinition, "name" | "description" | "skills" | "plugins"> & { extends?: string } {
   const nameMatch = yamlText.match(/^name:\s*(.+)$/m);
   const name = nameMatch?.[1]?.trim() ?? fallbackName;
 
   const descMatch = yamlText.match(/^description:\s*(.+)$/m);
   const description = descMatch?.[1]?.trim() ?? "";
 
+  const extendsMatch = yamlText.match(/^extends:\s*(.+)$/m);
+  const extendsValue = extendsMatch?.[1]?.trim();
+
   const skills = parseSkillsFromYaml(yamlText);
   const plugins = parsePluginsFromYaml(yamlText);
-  return { name, description, skills, plugins };
+  return { name, description, skills, plugins, ...(extendsValue ? { extends: extendsValue } : {}) };
 }
 
 // Parses the `skills:` block from a template.yml string.
@@ -86,10 +90,40 @@ export function parsePluginsFromYaml(yamlText: string): TemplatePlugin[] {
   return plugins;
 }
 
+// Resolves the `extends` field — loads parent template from builtin name or GitHub URL.
+// Merges skills, plugins, rules (parent first, then child).
+// Instructions are NOT inherited — each template has its own.
+export async function resolveExtends(
+  child: TemplateDefinition & { extends?: string },
+  resolveBuiltin?: (name: string) => Promise<TemplateDefinition | null>,
+): Promise<TemplateDefinition> {
+  if (!child.extends) return child;
+
+  let parent: TemplateDefinition;
+  if (child.extends.startsWith("https://")) {
+    parent = await fetchTemplateFromGitHub(child.extends);
+  } else if (resolveBuiltin) {
+    const resolved = await resolveBuiltin(child.extends);
+    if (!resolved) throw new Error(`Unknown builtin template: "${child.extends}"`);
+    parent = resolved;
+  } else {
+    throw new Error(`Cannot resolve extends: "${child.extends}"`);
+  }
+
+  return {
+    name: child.name,
+    description: child.description,
+    instructions: child.instructions,
+    skills: [...parent.skills, ...child.skills],
+    plugins: [...parent.plugins, ...child.plugins],
+    rules: [...parent.rules, ...child.rules],
+  };
+}
+
 // Phase 1: writes instructions.md and rules/*.md.
 // Call this BEFORE generate() so symlinks to rules are created.
 export async function applyTemplateFiles(root: string, template: TemplateDefinition): Promise<void> {
-  const oneagentDir = path.join(root, ".oneagent");
+  const oneagentDir = path.join(root, ONEAGENT_DIR);
 
   await fs.mkdir(path.join(oneagentDir, "rules"), { recursive: true });
   await fs.mkdir(path.join(oneagentDir, "skills"), { recursive: true });
@@ -107,28 +141,42 @@ export interface SkillInstallResult {
 }
 
 // Phase 2: installs skills via `npx skills add <repo> --skill <name>`.
-// All skills are installed in parallel. Call this AFTER generate() so agent directories exist.
+// Skills are installed sequentially to avoid race conditions — each `npx skills add` call
+// sets up agent directories and running them in parallel causes "skills 2" naming conflicts.
+// Call this AFTER generate() so agent directories exist.
 // Never throws — failed skills are collected and returned in the result.
 export async function installTemplateSkills(
   root: string,
   template: TemplateDefinition,
 ): Promise<SkillInstallResult> {
-  const results = await Promise.all(
-    template.skills.map(async (entry) => {
-      try {
-        await execFileAsync("npx", ["skills", "add", entry.repo, "--skill", entry.skill, "--agent", "universal", "--yes"], { cwd: root });
-        return { entry, ok: true as const };
-      } catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        return { entry, ok: false as const, reason };
-      }
-    }),
-  );
+  const installed: SkillEntry[] = [];
+  const failed: Array<{ entry: SkillEntry; reason: string }> = [];
 
-  return {
-    installed: results.filter((r) => r.ok).map((r) => r.entry),
-    failed: results.filter((r) => !r.ok).map((r) => ({ entry: r.entry, reason: (r as { reason: string }).reason })),
-  };
+  for (const entry of template.skills) {
+    try {
+      await execFileAsync("npx", ["skills", "add", entry.repo, "--skill", entry.skill, "--agent", "universal", "--yes"], { cwd: root });
+      installed.push(entry);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      failed.push({ entry, reason });
+    }
+  }
+
+  return { installed, failed };
+}
+
+const BUILTIN_SKILL_REPO = "https://github.com/moskalakamil/oneagent";
+const BUILTIN_SKILL_NAME = "oneagent";
+
+// Installs the built-in oneagent skill that teaches agents how to work with the .oneagent/ directory.
+// Never throws — returns true if installed, false if failed.
+export async function installBuiltinSkill(root: string): Promise<boolean> {
+  try {
+    await execFileAsync("npx", ["skills", "add", BUILTIN_SKILL_REPO, "--skill", BUILTIN_SKILL_NAME, "--agent", "universal", "--yes"], { cwd: root });
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 export interface PluginInstallResult {
@@ -192,22 +240,39 @@ export async function installTemplatePlugins(
 
 // Fetches a template from a GitHub URL.
 // Expects the repository to contain: template.yml, instructions.md, and optionally rules/*.md
+// When no branch is specified in the URL, queries the GitHub API for the default branch.
 export async function fetchTemplateFromGitHub(url: string): Promise<TemplateDefinition> {
-  // Convert GitHub URL to raw content base URL
-  // e.g. https://github.com/owner/repo → https://raw.githubusercontent.com/owner/repo/main
-  const rawBase = githubUrlToRawBase(url);
+  const { owner, repo, branch, subdir } = parseGitHubUrl(url);
+  const branchExplicit = url.includes("/tree/");
+
+  const resolvedBranch = branchExplicit ? branch : await fetchDefaultBranch(owner, repo);
+  const rawBase = `https://raw.githubusercontent.com/${owner}/${repo}/${resolvedBranch}${subdir ? `/${subdir}` : ""}`;
 
   const [yamlText, instructions] = await Promise.all([
     fetchText(`${rawBase}/template.yml`),
     fetchText(`${rawBase}/instructions.md`),
   ]);
 
-  const { name, description, skills, plugins } = parseTemplateYaml(yamlText);
+  const parsed = parseTemplateYaml(yamlText);
 
   // Try to list rules via GitHub API
   const rules = await fetchGitHubRules(url);
 
-  return { name, description, skills, plugins, instructions, rules };
+  const base = { ...parsed, instructions, rules };
+  return resolveExtends(base);
+}
+
+async function fetchDefaultBranch(owner: string, repo: string): Promise<string> {
+  try {
+    const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
+      headers: { Accept: "application/vnd.github.v3+json" },
+    });
+    if (!response.ok) return "main";
+    const data = (await response.json()) as { default_branch?: string };
+    return data.default_branch ?? "main";
+  } catch {
+    return "main";
+  }
 }
 
 async function fetchText(url: string): Promise<string> {

package/src/commands.ts

@@ -1,9 +1,10 @@
 import path from "path";
 import fs from "fs/promises";
 import type { CommandFile } from "./types.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 export async function readCommands(root: string): Promise<CommandFile[]> {
-  const commandsDir = path.join(root, ".oneagent/commands");
+  const commandsDir = path.join(root, ONEAGENT_DIR, "commands");
   try {
     const files = await fs.readdir(commandsDir);
     return files

package/src/config.ts

@@ -2,8 +2,9 @@ import { parse, stringify } from "yaml";
 import path from "path";
 import fs from "fs/promises";
 import type { AgentTarget, Config } from "./types.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
-const CONFIG_REL = ".oneagent/config.yml";
+const CONFIG_REL = `${ONEAGENT_DIR}/config.yml`;
 
 export const ALL_AGENT_TARGETS: AgentTarget[] = ["claude", "cursor", "windsurf", "opencode", "copilot"];
 

package/src/constants.ts

@@ -0,0 +1 @@
+export const ONEAGENT_DIR = ".oneagent";

package/src/detect.ts

@@ -2,6 +2,7 @@ import path from "path";
 import fs from "fs/promises";
 import type { DetectedFile } from "./types.ts";
 import { AGENT_DEFINITIONS } from "./agents.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 export const AGENT_FILES = [
   "CLAUDE.md",
@@ -20,7 +21,7 @@ export async function readDetectedFile(root: string, rel: string): Promise<Detec
     if (stat.isSymbolicLink()) {
       const linkTarget = await fs.readlink(absolutePath);
       const resolved = path.resolve(path.dirname(absolutePath), linkTarget);
-      if (resolved.startsWith(path.join(root, ".one"))) return null;
+      if (resolved.startsWith(path.join(root, ONEAGENT_DIR))) return null;
     }
 
     const content = await fs.readFile(absolutePath, "utf-8");

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./constants.ts";
 export * from "./types.ts";
 export * from "./agents.ts";
 export * from "./config.ts";

package/src/opencode.ts

@@ -1,6 +1,7 @@
 import path from "path";
 import fs from "fs/promises";
 import type { RuleFile } from "./types.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 export async function readOpencode(root: string): Promise<Record<string, unknown> | null> {
   try {
@@ -14,7 +15,7 @@ export async function readOpencode(root: string): Promise<Record<string, unknown
 export function buildOpencodeConfig(existing: Record<string, unknown> | null): object {
   return {
     ...existing,
-    instructions: ".oneagent/instructions.md",
+    instructions: `${ONEAGENT_DIR}/instructions.md`,
   };
 }
 

package/src/rules.ts

@@ -1,9 +1,10 @@
 import path from "path";
 import fs from "fs/promises";
 import type { RuleFile } from "./types.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 export async function readRules(root: string): Promise<RuleFile[]> {
-  const rulesDir = path.join(root, ".oneagent/rules");
+  const rulesDir = path.join(root, ONEAGENT_DIR, "rules");
   try {
     const files = await fs.readdir(rulesDir);
     return files

package/src/skills.ts

@@ -1,6 +1,7 @@
 import path from "path";
 import fs from "fs/promises";
 import type { SkillFile } from "./types.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 const VALID_MODES = ["ask", "edit", "agent"] as const;
 type SkillMode = (typeof VALID_MODES)[number];
@@ -29,7 +30,7 @@ export async function readSkillFile(filePath: string): Promise<SkillFile> {
 }
 
 export async function readSkills(root: string): Promise<SkillFile[]> {
-  const skillsDir = path.join(root, ".oneagent/skills");
+  const skillsDir = path.join(root, ONEAGENT_DIR, "skills");
   try {
     const files = await fs.readdir(skillsDir);
     const mdFiles = files.filter((f) => f.endsWith(".md"));

package/src/status.ts

@@ -1,6 +1,7 @@
 import fs from "fs/promises";
 import type { Config, GeneratedFileCheck, OpenCodeCheck, RuleFile, StatusResult } from "./types.ts";
 import { activeTargets } from "./config.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 import { readRules } from "./rules.ts";
 import { readSkills } from "./skills.ts";
 import { buildMainSymlinks, buildRulesSymlinks, buildSkillSymlinks, buildCommandSymlinks, buildAgentsDirSymlinks, checkSymlink } from "./symlinks.ts";
@@ -26,7 +27,7 @@ export async function checkOpencodeStatus(
 ): Promise<OpenCodeCheck> {
   const existing = await readOpencode(root);
   if (!existing) return { exists: false, valid: false };
-  return { exists: true, valid: existing["instructions"] === ".oneagent/instructions.md" };
+  return { exists: true, valid: existing["instructions"] === `${ONEAGENT_DIR}/instructions.md` };
 }
 
 export async function checkCopilotPrompt(root: string, skill: import("./types.ts").SkillFile): Promise<GeneratedFileCheck> {

package/src/symlinks.ts

@@ -2,6 +2,7 @@ import path from "path";
 import fs from "fs/promises";
 import type { AgentTarget, SymlinkCheck, SymlinkEntry } from "./types.ts";
 import { AGENT_DEFINITIONS } from "./agents.ts";
+import { ONEAGENT_DIR } from "./constants.ts";
 
 export async function ensureDir(dirPath: string): Promise<void> {
   await fs.mkdir(dirPath, { recursive: true });
@@ -9,12 +10,27 @@ export async function ensureDir(dirPath: string): Promise<void> {
 
 export async function createSymlink(symlinkPath: string, target: string): Promise<void> {
   await ensureDir(path.dirname(symlinkPath));
+
+  // Skip if already a correct symlink — avoids unnecessary rm/create that can
+  // race with external filesystem watchers (e.g. Cursor IDE recreating .cursor/rules)
   try {
-    await fs.rm(symlinkPath, { recursive: true });
+    const stat = await fs.lstat(symlinkPath);
+    if (stat.isSymbolicLink() && (await fs.readlink(symlinkPath)) === target) return;
   } catch {
-    // doesn't exist — that's fine
+    // path doesn't exist — proceed
+  }
+
+  // Retry up to 3 times: external tools can recreate the path between our rm
+  // and symlink calls, causing EEXIST and macOS conflict copies (e.g. "rules 2")
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await fs.rm(symlinkPath, { recursive: true, force: true });
+    try {
+      await fs.symlink(target, symlinkPath);
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST" || attempt === 2) throw err;
+    }
   }
-  await fs.symlink(target, symlinkPath);
 }
 
 function relativeTarget(symlinkPath: string, targetAbsPath: string): string {
@@ -22,7 +38,7 @@ function relativeTarget(symlinkPath: string, targetAbsPath: string): string {
 }
 
 export function buildMainSymlinks(root: string, targets: AgentTarget[]): SymlinkEntry[] {
-  const instructionsAbs = path.join(root, ".oneagent/instructions.md");
+  const instructionsAbs = path.join(root, ONEAGENT_DIR, "instructions.md");
   const seen = new Map<string, SymlinkEntry>();
 
   for (const target of targets) {
@@ -41,7 +57,7 @@ export function buildMainSymlinks(root: string, targets: AgentTarget[]): Symlink
 }
 
 export function buildRulesSymlinks(root: string, targets: AgentTarget[]): SymlinkEntry[] {
-  const targetAbs = path.join(root, ".oneagent/rules");
+  const targetAbs = path.join(root, ONEAGENT_DIR, "rules");
   return AGENT_DEFINITIONS
     .filter((d) => targets.includes(d.target) && d.rulesDir)
     .map((d) => {
@@ -51,7 +67,7 @@ export function buildRulesSymlinks(root: string, targets: AgentTarget[]): Symlin
 }
 
 export function buildSkillSymlinks(root: string, targets: AgentTarget[]): SymlinkEntry[] {
-  const targetAbs = path.join(root, ".oneagent/skills");
+  const targetAbs = path.join(root, ONEAGENT_DIR, "skills");
   return AGENT_DEFINITIONS
     .filter((d) => targets.includes(d.target) && d.skillsDir)
     .map((d) => {
@@ -61,7 +77,7 @@ export function buildSkillSymlinks(root: string, targets: AgentTarget[]): Symlin
 }
 
 export function buildCommandSymlinks(root: string, targets: AgentTarget[]): SymlinkEntry[] {
-  const targetAbs = path.join(root, ".oneagent/commands");
+  const targetAbs = path.join(root, ONEAGENT_DIR, "commands");
   return AGENT_DEFINITIONS
     .filter((d) => targets.includes(d.target) && d.commandsDir)
     .map((d) => {
@@ -72,7 +88,7 @@ export function buildCommandSymlinks(root: string, targets: AgentTarget[]): Syml
 
 export function buildAgentsDirSymlinks(root: string): SymlinkEntry[] {
   const symlinkPath = path.join(root, ".agents/skills");
-  const targetAbs = path.join(root, ".oneagent/skills");
+  const targetAbs = path.join(root, ONEAGENT_DIR, "skills");
   return [{ symlinkPath, target: relativeTarget(symlinkPath, targetAbs), label: ".agents/skills" }];
 }
 
@@ -85,8 +101,21 @@ async function migrateFilesFromDir(srcDir: string, destDir: string, root: string
     return; // srcDir doesn't exist — no-op
   }
   for (const entry of entries) {
-    if (!entry.isFile()) continue; // skip symlinks and subdirs
     const srcFile = path.join(srcDir, entry.name);
+    const fileStat = await fs.lstat(srcFile);
+    if (fileStat.isSymbolicLink()) continue;
+
+    // Move subdirectories as whole units (e.g. skills.sh skill packages)
+    if (fileStat.isDirectory()) {
+      const destSub = path.join(destDir, entry.name);
+      try { await fs.access(destSub); } catch {
+        await fs.mkdir(destDir, { recursive: true });
+        await fs.rename(srcFile, destSub);
+      }
+      continue;
+    }
+
+    if (!fileStat.isFile()) continue;
     const destFile = path.join(destDir, entry.name);
 
     let destExists = false;
@@ -105,7 +134,7 @@ async function migrateFilesFromDir(srcDir: string, destDir: string, root: string
       ]);
       if (srcContent !== destContent) {
         // Different content — backup source before deleting
-        const backupDir = path.join(root, ".oneagent/backup");
+        const backupDir = path.join(root, ONEAGENT_DIR, "backup");
         await fs.mkdir(backupDir, { recursive: true });
         const safeName = path.relative(root, srcFile).replace(/\//g, "_");
         await fs.writeFile(path.join(backupDir, safeName), srcContent);
@@ -130,13 +159,16 @@ async function migrateAndRemoveDir(src: string, dest: string, root: string): Pro
 }
 
 export async function migrateRuleAndSkillFiles(root: string): Promise<void> {
-  const destRules = path.join(root, ".oneagent/rules");
-  const destSkills = path.join(root, ".oneagent/skills");
-  const destCommands = path.join(root, ".oneagent/commands");
+  const destRules = path.join(root, ONEAGENT_DIR, "rules");
+  const destSkills = path.join(root, ONEAGENT_DIR, "skills");
+  const destCommands = path.join(root, ONEAGENT_DIR, "commands");
   // Derive migration sources from agent definitions — sequential to avoid same-name conflicts.
   for (const def of AGENT_DEFINITIONS) {
     if (def.rulesDir) await migrateAndRemoveDir(path.join(root, def.rulesDir), destRules, root);
   }
+  for (const def of AGENT_DEFINITIONS) {
+    if (def.skillsDir) await migrateAndRemoveDir(path.join(root, def.skillsDir), destSkills, root);
+  }
   // .agents/skills — standard skills.sh path, not represented in agent definitions
   await migrateAndRemoveDir(path.join(root, ".agents/skills"), destSkills, root);
   for (const def of AGENT_DEFINITIONS) {
@@ -144,8 +176,57 @@ export async function migrateRuleAndSkillFiles(root: string): Promise<void> {
   }
 }
 
+async function backupDirRecursive(srcDir: string, backupDir: string, prefix: string): Promise<void> {
+  let entries: import("fs").Dirent[];
+  try { entries = await fs.readdir(srcDir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const lstat = await fs.lstat(srcPath);
+    if (lstat.isSymbolicLink()) continue;
+    if (lstat.isDirectory()) {
+      await backupDirRecursive(srcPath, backupDir, `${prefix}_${entry.name}`);
+    } else if (lstat.isFile()) {
+      await fs.mkdir(backupDir, { recursive: true });
+      await fs.copyFile(srcPath, path.join(backupDir, `${prefix}_${entry.name}`));
+    }
+  }
+}
+
+export async function cleanupAgentDir(root: string, target: import("./types.ts").AgentTarget): Promise<void> {
+  const def = AGENT_DEFINITIONS.find((d) => d.target === target)!;
+  const backupDir = path.join(root, ONEAGENT_DIR, "backup");
+
+  const agentDir = [def.rulesDir, def.skillsDir, def.commandsDir]
+    .filter(Boolean)
+    .map((d) => d!.split("/")[0]!)
+    .find((d) => d !== ".github");
+
+  if (agentDir) {
+    const agentDirAbs = path.join(root, agentDir);
+    let stat;
+    try { stat = await fs.lstat(agentDirAbs); } catch {}
+    if (stat && stat.isDirectory() && !stat.isSymbolicLink()) {
+      await backupDirRecursive(agentDirAbs, backupDir, agentDir);
+      await fs.rm(agentDirAbs, { recursive: true, force: true });
+    }
+  }
+
+  if (target === "opencode") {
+    const opPath = path.join(root, "opencode.json");
+    try {
+      const content = await fs.readFile(opPath, "utf-8");
+      await fs.mkdir(backupDir, { recursive: true });
+      await fs.writeFile(path.join(backupDir, "opencode.json"), content);
+    } catch {}
+    try { await fs.unlink(opPath); } catch {}
+  }
+}
+
 export async function createAllSymlinks(entries: SymlinkEntry[]): Promise<void> {
-  for (const e of entries) {
+  // Deduplicate by symlink path — last entry wins
+  const deduped = new Map<string, SymlinkEntry>();
+  for (const e of entries) deduped.set(e.symlinkPath, e);
+  for (const e of deduped.values()) {
     await createSymlink(e.symlinkPath, e.target);
   }
 }