@moskala/oneagent-core 0.1.0 → 0.2.2

package/package.json

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

package/src/apply-template.ts

@@ -0,0 +1,123 @@
+import path from "path";
+import fs from "fs/promises";
+
+export interface TemplateDefinition {
+  name: string;
+  description: string;
+  skills: string[];
+  instructions: string;
+  rules: Array<{ name: string; content: string }>;
+}
+
+// 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");
+
+  await fs.mkdir(path.join(oneagentDir, "rules"), { recursive: true });
+  await fs.mkdir(path.join(oneagentDir, "skills"), { recursive: true });
+
+  await Bun.write(path.join(oneagentDir, "instructions.md"), template.instructions);
+
+  for (const rule of template.rules) {
+    await Bun.write(path.join(oneagentDir, "rules", `${rule.name}.md`), rule.content);
+  }
+}
+
+// Phase 2: installs skills via `bunx skills add <identifier> --yes`.
+// Call this AFTER generate() so agent directories (symlinks) already exist.
+export async function installTemplateSkills(
+  root: string,
+  template: TemplateDefinition,
+  onSkillInstalled?: (identifier: string) => void,
+): Promise<void> {
+  for (const identifier of template.skills) {
+    try {
+      await Bun.$`bunx skills add ${identifier} --agent universal --yes`.cwd(root).quiet();
+      onSkillInstalled?.(identifier);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Failed to install skill "${identifier}": ${message}`);
+    }
+  }
+}
+
+// Fetches a template from a GitHub URL.
+// Expects the repository to contain: template.yml, instructions.md, and optionally rules/*.md
+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 [yamlText, instructions] = await Promise.all([
+    fetchText(`${rawBase}/template.yml`),
+    fetchText(`${rawBase}/instructions.md`),
+  ]);
+
+  const descMatch = yamlText.match(/^description:\s*(.+)$/m);
+  const description = descMatch?.[1]?.trim() ?? "";
+
+  const nameMatch = yamlText.match(/^name:\s*(.+)$/m);
+  const name = nameMatch?.[1]?.trim() ?? "custom";
+
+  const skills: string[] = [];
+  const skillsBlockMatch = yamlText.match(/^skills:\s*\n((?:  - .+\n?)*)/m);
+  if (skillsBlockMatch) {
+    const lines = skillsBlockMatch[1]!.split("\n").filter(Boolean);
+    for (const line of lines) {
+      const skill = line.replace(/^\s*-\s*/, "").trim();
+      if (skill) skills.push(skill);
+    }
+  }
+
+  // Try to list rules via GitHub API
+  const rules = await fetchGitHubRules(url);
+
+  return { name, description, skills, instructions, rules };
+}
+
+async function fetchText(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+
+function githubUrlToRawBase(url: string): string {
+  // Handle https://github.com/owner/repo/tree/branch or https://github.com/owner/repo
+  const match = url.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\/tree\/([^/]+))?(?:\/.*)?$/);
+  if (!match) {
+    throw new Error(`Invalid GitHub URL: "${url}". Expected format: https://github.com/owner/repo`);
+  }
+  const [, owner, repo, branch = "main"] = match;
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}`;
+}
+
+async function fetchGitHubRules(repoUrl: string): Promise<Array<{ name: string; content: string }>> {
+  // Parse owner/repo from URL
+  const match = repoUrl.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\/tree\/([^/]+))?(?:\/.*)?$/);
+  if (!match) return [];
+  const [, owner, repo, branch = "main"] = match;
+
+  const apiUrl = `https://api.github.com/repos/${owner}/${repo}/contents/rules?ref=${branch}`;
+  try {
+    const response = await fetch(apiUrl, {
+      headers: { Accept: "application/vnd.github.v3+json" },
+    });
+    if (!response.ok) return [];
+
+    const files = (await response.json()) as Array<{ name: string; download_url: string | null }>;
+    const mdFiles = files.filter((f) => f.name.endsWith(".md") && f.download_url);
+
+    const rules = await Promise.all(
+      mdFiles.map(async (f) => {
+        const content = await fetchText(f.download_url!);
+        return { name: path.basename(f.name, ".md"), content };
+      }),
+    );
+    return rules;
+  } catch {
+    return [];
+  }
+}

package/src/config.ts

@@ -1,9 +1,19 @@
 import { parse, stringify } from "yaml";
 import path from "path";
-import type { Config } from "./types.ts";
+import type { AgentTarget, Config } from "./types.ts";
 
 const CONFIG_REL = ".oneagent/config.yml";
 
+export const ALL_AGENT_TARGETS: AgentTarget[] = ["claude", "cursor", "windsurf", "opencode", "copilot"];
+
+export function activeTargets(config: Config): AgentTarget[] {
+  return ALL_AGENT_TARGETS.filter((t) => config.targets[t]);
+}
+
+export function makeTargets(...enabled: AgentTarget[]): Record<AgentTarget, boolean> {
+  return Object.fromEntries(ALL_AGENT_TARGETS.map((t) => [t, enabled.includes(t)])) as Record<AgentTarget, boolean>;
+}
+
 export async function configExists(root: string): Promise<boolean> {
   return Bun.file(path.join(root, CONFIG_REL)).exists();
 }

package/src/copilot.ts

@@ -1,6 +1,6 @@
 import path from "path";
 import fs from "fs/promises";
-import type { RuleFile } from "./types.ts";
+import type { RuleFile, SkillFile } from "./types.ts";
 
 export function buildCopilotContent(rule: RuleFile): string {
   return `---\napplyTo: "${rule.applyTo}"\n---\n${rule.content}`;
@@ -19,3 +19,24 @@ export async function generateCopilotRule(root: string, rule: RuleFile): Promise
 export async function generateCopilotRules(root: string, rules: RuleFile[]): Promise<void> {
   await Promise.all(rules.map((rule) => generateCopilotRule(root, rule)));
 }
+
+export function buildCopilotPromptContent(skill: SkillFile): string {
+  const lines = ["---", `mode: "${skill.mode}"`];
+  if (skill.description) lines.push(`description: "${skill.description}"`);
+  lines.push("---", skill.content);
+  return lines.join("\n");
+}
+
+export function copilotPromptFilePath(root: string, skillName: string): string {
+  return path.join(root, ".github/prompts", `${skillName}.prompt.md`);
+}
+
+export async function generateCopilotSkill(root: string, skill: SkillFile): Promise<void> {
+  const filePath = copilotPromptFilePath(root, skill.name);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await Bun.write(filePath, buildCopilotPromptContent(skill));
+}
+
+export async function generateCopilotSkills(root: string, skills: SkillFile[]): Promise<void> {
+  await Promise.all(skills.map((skill) => generateCopilotSkill(root, skill)));
+}

package/src/detect.ts

@@ -45,3 +45,29 @@ export function filesHaveSameContent(files: DetectedFile[]): boolean {
   const first = files[0]!.content;
   return files.every((f) => f.content === first);
 }
+
+const DEPRECATED_FILES = [".cursorrules"];
+
+export async function removeDeprecatedFiles(root: string): Promise<void> {
+  for (const rel of DEPRECATED_FILES) {
+    const absPath = path.join(root, rel);
+    try {
+      const stat = await fs.lstat(absPath);
+      if (!stat.isSymbolicLink()) await fs.unlink(absPath);
+    } catch {
+      // doesn't exist — no-op
+    }
+  }
+}
+
+export async function detectDeprecatedCommandFiles(root: string): Promise<string[]> {
+  const commandsDir = path.join(root, ".claude/commands");
+  try {
+    const entries = await fs.readdir(commandsDir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile())
+      .map((e) => path.join(".claude/commands", e.name));
+  } catch {
+    return [];
+  }
+}

package/src/generate.ts

@@ -1,21 +1,86 @@
-import type { Config } from "./types.ts";
+import path from "path";
+import fs from "fs/promises";
+import type { Config, DetectedFile } from "./types.ts";
+import { activeTargets } from "./config.ts";
 import { readRules } from "./rules.ts";
-import { buildMainSymlinks, buildRulesSymlinks, createAllSymlinks } from "./symlinks.ts";
-import { generateCopilotRules } from "./copilot.ts";
+import { readSkills } from "./skills.ts";
+import { buildMainSymlinks, buildRulesSymlinks, buildSkillSymlinks, buildAgentsDirSymlinks, createAllSymlinks, migrateRuleAndSkillFiles } from "./symlinks.ts";
+import { buildCopilotContent, copilotFilePath, buildCopilotPromptContent, copilotPromptFilePath, generateCopilotRules, generateCopilotSkills } from "./copilot.ts";
 import { writeOpencode } from "./opencode.ts";
+import { readDetectedFile } from "./detect.ts";
+
+export interface GenerateCollisions {
+  mainFiles: DetectedFile[];
+  ruleSkillFiles: DetectedFile[];
+}
+
+export async function detectGenerateCollisions(root: string, config: Config): Promise<GenerateCollisions> {
+  const [rules, skills] = await Promise.all([readRules(root), readSkills(root)]);
+  const targets = activeTargets(config);
+
+  // 1. Main instruction file symlinks (CLAUDE.md, AGENTS.md, .windsurfrules, etc.)
+  const mainEntries = buildMainSymlinks(root, targets);
+  // 2. Rule/skill symlink paths
+  const ruleSkillEntries = [
+    ...buildRulesSymlinks(root, targets, rules),
+    ...buildSkillSymlinks(root, targets, skills),
+    // .agents/skills skipped — handled by migrateAgentsSkillsDir
+  ];
+
+  const [mainCollisions, ruleSkillSymlinkCollisions] = await Promise.all([
+    Promise.all(mainEntries.map((entry) => readDetectedFile(root, path.relative(root, entry.symlinkPath))))
+      .then((files) => files.filter((f): f is DetectedFile => f !== null)),
+    Promise.all(ruleSkillEntries.map((entry) => readDetectedFile(root, path.relative(root, entry.symlinkPath))))
+      .then((files) => files.filter((f): f is DetectedFile => f !== null)),
+  ]);
+
+  // 3. Copilot generated files — collision only if content differs (idempotent-safe)
+  const copilotCollisions: DetectedFile[] = [];
+  if (targets.includes("copilot")) {
+    const checks = await Promise.all([
+      ...rules.map(async (rule): Promise<DetectedFile | null> => {
+        const filePath = copilotFilePath(root, rule.name);
+        try {
+          const content = await Bun.file(filePath).text();
+          if (content === buildCopilotContent(rule)) return null;
+          const stat = await fs.lstat(filePath);
+          return { relativePath: path.relative(root, filePath), absolutePath: filePath, sizeBytes: stat.size, modifiedAt: stat.mtime, content };
+        } catch { return null; }
+      }),
+      ...skills.map(async (skill): Promise<DetectedFile | null> => {
+        const filePath = copilotPromptFilePath(root, skill.name);
+        try {
+          const content = await Bun.file(filePath).text();
+          if (content === buildCopilotPromptContent(skill)) return null;
+          const stat = await fs.lstat(filePath);
+          return { relativePath: path.relative(root, filePath), absolutePath: filePath, sizeBytes: stat.size, modifiedAt: stat.mtime, content };
+        } catch { return null; }
+      }),
+    ]);
+    copilotCollisions.push(...checks.filter((c): c is DetectedFile => c !== null));
+  }
+
+  return {
+    mainFiles: mainCollisions,
+    ruleSkillFiles: [...ruleSkillSymlinkCollisions, ...copilotCollisions],
+  };
+}
 
 export async function generate(root: string, config: Config): Promise<void> {
-  const rules = await readRules(root);
+  const [rules, skills] = await Promise.all([readRules(root), readSkills(root)]);
+  const targets = activeTargets(config);
 
-  const mainSymlinks = buildMainSymlinks(root, config.targets);
-  const rulesSymlinks = buildRulesSymlinks(root, config.targets, rules);
-  await createAllSymlinks([...mainSymlinks, ...rulesSymlinks]);
+  const mainSymlinks = buildMainSymlinks(root, targets);
+  const rulesSymlinks = buildRulesSymlinks(root, targets, rules);
+  const skillSymlinks = buildSkillSymlinks(root, targets, skills);
+  await migrateRuleAndSkillFiles(root);
+  await createAllSymlinks([...mainSymlinks, ...rulesSymlinks, ...skillSymlinks, ...buildAgentsDirSymlinks(root)]);
 
-  if (config.targets.includes("copilot")) {
-    await generateCopilotRules(root, rules);
+  if (targets.includes("copilot")) {
+    await Promise.all([generateCopilotRules(root, rules), generateCopilotSkills(root, skills)]);
   }
 
-  if (config.targets.includes("opencode")) {
+  if (targets.includes("opencode")) {
     await writeOpencode(root, rules);
   }
 }

package/src/index.ts

@@ -2,8 +2,10 @@ export * from "./types.ts";
 export * from "./config.ts";
 export * from "./detect.ts";
 export * from "./rules.ts";
+export * from "./skills.ts";
 export * from "./symlinks.ts";
 export * from "./copilot.ts";
 export * from "./opencode.ts";
 export * from "./generate.ts";
 export * from "./status.ts";
+export * from "./apply-template.ts";

package/src/skills.ts

@@ -0,0 +1,42 @@
+import path from "path";
+import fs from "fs/promises";
+import type { SkillFile } from "./types.ts";
+
+const VALID_MODES = ["ask", "edit", "agent"] as const;
+type SkillMode = (typeof VALID_MODES)[number];
+
+export function parseSkillFrontmatter(raw: string): { description: string; mode: SkillMode; content: string } {
+  const match = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!match) return { description: "", mode: "agent", content: raw };
+
+  const frontmatter = match[1] ?? "";
+  const content = match[2] ?? "";
+
+  const descMatch = frontmatter.match(/description:\s*["']?([^"'\n]+)["']?/);
+  const description = descMatch?.[1]?.trim() ?? "";
+
+  const modeMatch = frontmatter.match(/mode:\s*["']?([^"'\n]+)["']?/);
+  const modeRaw = modeMatch?.[1]?.trim() ?? "agent";
+  const mode: SkillMode = (VALID_MODES as readonly string[]).includes(modeRaw) ? (modeRaw as SkillMode) : "agent";
+
+  return { description, mode, content };
+}
+
+export async function readSkillFile(filePath: string): Promise<SkillFile> {
+  const raw = await Bun.file(filePath).text();
+  const { description, mode, content } = parseSkillFrontmatter(raw);
+  return { name: path.basename(filePath, ".md"), path: filePath, description, mode, content };
+}
+
+export async function readSkills(root: string): Promise<SkillFile[]> {
+  const skillsDir = path.join(root, ".oneagent/skills");
+  try {
+    const files = await fs.readdir(skillsDir);
+    const mdFiles = files.filter((f) => f.endsWith(".md"));
+    const skills = await Promise.all(mdFiles.map((f) => readSkillFile(path.join(skillsDir, f))));
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+

package/src/status.ts

@@ -1,7 +1,9 @@
 import type { Config, GeneratedFileCheck, OpenCodeCheck, RuleFile, StatusResult } from "./types.ts";
+import { activeTargets } from "./config.ts";
 import { readRules } from "./rules.ts";
-import { buildMainSymlinks, buildRulesSymlinks, checkSymlink } from "./symlinks.ts";
-import { buildCopilotContent, copilotFilePath } from "./copilot.ts";
+import { readSkills } from "./skills.ts";
+import { buildMainSymlinks, buildRulesSymlinks, buildSkillSymlinks, buildAgentsDirSymlinks, checkSymlink } from "./symlinks.ts";
+import { buildCopilotContent, buildCopilotPromptContent, copilotFilePath, copilotPromptFilePath } from "./copilot.ts";
 import { readOpencode } from "./opencode.ts";
 
 export async function checkGeneratedFile(root: string, rule: RuleFile): Promise<GeneratedFileCheck> {
@@ -24,18 +26,35 @@ export async function checkOpencodeStatus(
   return { exists: true, valid: existing["instructions"] === ".oneagent/instructions.md" };
 }
 
+export async function checkCopilotPrompt(root: string, skill: import("./types.ts").SkillFile): Promise<GeneratedFileCheck> {
+  const filePath = copilotPromptFilePath(root, skill.name);
+  const expected = buildCopilotPromptContent(skill);
+  try {
+    const content = await Bun.file(filePath).text();
+    return { path: filePath, exists: true, upToDate: content === expected };
+  } catch {
+    return { path: filePath, exists: false, upToDate: false };
+  }
+}
+
 export async function checkStatus(root: string, config: Config): Promise<StatusResult> {
-  const rules = await readRules(root);
+  const [rules, skills] = await Promise.all([readRules(root), readSkills(root)]);
+  const targets = activeTargets(config);
 
   const allEntries = [
-    ...buildMainSymlinks(root, config.targets),
-    ...buildRulesSymlinks(root, config.targets, rules),
+    ...buildMainSymlinks(root, targets),
+    ...buildRulesSymlinks(root, targets, rules),
+    ...buildSkillSymlinks(root, targets, skills),
+    ...buildAgentsDirSymlinks(root),
   ];
 
   const symlinks = await Promise.all(allEntries.map(checkSymlink));
 
-  const generatedFiles = config.targets.includes("copilot")
-    ? await Promise.all(rules.map((rule) => checkGeneratedFile(root, rule)))
+  const generatedFiles = targets.includes("copilot")
+    ? await Promise.all([
+        ...rules.map((rule) => checkGeneratedFile(root, rule)),
+        ...skills.map((skill) => checkCopilotPrompt(root, skill)),
+      ])
     : [];
 
   const opencode = await checkOpencodeStatus(root, rules);

package/src/symlinks.ts

@@ -1,6 +1,6 @@
 import path from "path";
 import fs from "fs/promises";
-import type { AgentTarget, RuleFile, SymlinkCheck, SymlinkEntry } from "./types.ts";
+import type { AgentTarget, RuleFile, SkillFile, SymlinkCheck, SymlinkEntry } from "./types.ts";
 
 export async function ensureDir(dirPath: string): Promise<void> {
   await fs.mkdir(dirPath, { recursive: true });
@@ -98,6 +98,93 @@ export function buildRulesSymlinks(
   return entries;
 }
 
+export function buildSkillSymlinks(root: string, targets: AgentTarget[], skills: SkillFile[]): SymlinkEntry[] {
+  if (!targets.includes("claude")) return [];
+
+  const commandsDir = path.join(root, ".claude/commands");
+  return skills.map((skill) => {
+    const symlinkPath = path.join(commandsDir, `${skill.name}.md`);
+    return {
+      symlinkPath,
+      target: relativeTarget(symlinkPath, skill.path),
+      label: path.relative(root, symlinkPath),
+    };
+  });
+}
+
+export function buildAgentsDirSymlinks(root: string): SymlinkEntry[] {
+  const symlinkPath = path.join(root, ".agents/skills");
+  const targetAbs = path.join(root, ".oneagent/skills");
+  return [{ symlinkPath, target: relativeTarget(symlinkPath, targetAbs), label: ".agents/skills" }];
+}
+
+async function migrateFilesFromDir(srcDir: string, destDir: string, root: string): Promise<void> {
+  await fs.mkdir(destDir, { recursive: true });
+  let entries: import("fs").Dirent[];
+  try {
+    entries = await fs.readdir(srcDir, { withFileTypes: true });
+  } catch {
+    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 destFile = path.join(destDir, entry.name);
+
+    let destExists = false;
+    try {
+      await fs.access(destFile);
+      destExists = true;
+    } catch {
+      // dest doesn't exist
+    }
+
+    if (destExists) {
+      // dest exists — compare content before deleting source
+      const [srcContent, destContent] = await Promise.all([
+        Bun.file(srcFile).text(),
+        Bun.file(destFile).text(),
+      ]);
+      if (srcContent !== destContent) {
+        // Different content — backup source before deleting
+        const backupDir = path.join(root, ".oneagent/backup");
+        await fs.mkdir(backupDir, { recursive: true });
+        const safeName = path.relative(root, srcFile).replace(/\//g, "_");
+        await Bun.write(path.join(backupDir, safeName), srcContent);
+      }
+      await fs.unlink(srcFile); // safe to delete — dest has the content (or backup was created)
+    } else {
+      await fs.rename(srcFile, destFile);
+    }
+  }
+}
+
+async function migrateAndRemoveDir(src: string, dest: string, root: string): Promise<void> {
+  let stat;
+  try {
+    stat = await fs.lstat(src);
+  } catch {
+    return; // doesn't exist — no-op
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) return;
+  await migrateFilesFromDir(src, dest, root);
+  await fs.rm(src, { recursive: true, force: true });
+}
+
+export async function migrateRuleAndSkillFiles(root: string): Promise<void> {
+  const destRules = path.join(root, ".oneagent/rules");
+  const destSkills = path.join(root, ".oneagent/skills");
+  // Rules dirs: only individual files become symlinks, so we only move the files.
+  // The directories themselves stay — generate() recreates per-file symlinks inside them.
+  // Sequential to avoid same-name conflicts across dirs.
+  await migrateFilesFromDir(path.join(root, ".cursor/rules"), destRules, root);
+  await migrateFilesFromDir(path.join(root, ".claude/rules"), destRules, root);
+  await migrateFilesFromDir(path.join(root, ".windsurf/rules"), destRules, root);
+  // .agents/skills is different: the entire directory becomes a symlink to .oneagent/skills,
+  // so the real directory must be removed first to make room for the symlink.
+  await migrateAndRemoveDir(path.join(root, ".agents/skills"), destSkills, root);
+}
+
 export async function createAllSymlinks(entries: SymlinkEntry[]): Promise<void> {
   await Promise.all(entries.map((e) => createSymlink(e.symlinkPath, e.target)));
 }

package/src/types.ts

@@ -2,7 +2,7 @@ export type AgentTarget = "claude" | "cursor" | "windsurf" | "opencode" | "copil
 
 export interface Config {
   version: 1;
-  targets: AgentTarget[];
+  targets: Record<AgentTarget, boolean>;
 }
 
 export interface DetectedFile {
@@ -20,6 +20,14 @@ export interface RuleFile {
   content: string;
 }
 
+export interface SkillFile {
+  name: string;
+  path: string;
+  description: string;
+  mode: "ask" | "edit" | "agent";
+  content: string;
+}
+
 export interface SymlinkEntry {
   symlinkPath: string;
   target: string;