@skilly-hand/skilly-hand 0.1.0

package/packages/core/src/index.js

@@ -0,0 +1,304 @@
+import { cp, lstat, mkdir, readFile, realpath, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { copySkillTo, loadAllSkills, renderAgentsMarkdown, verifyCatalogFiles } from "../../catalog/src/index.js";
+import { detectProject, inspectProjectFiles } from "../../detectors/src/index.js";
+
+const DEFAULT_AGENTS = ["codex", "claude", "cursor", "gemini", "copilot"];
+const MANAGED_MARKER = "<!-- Managed by skilly-hand.";
+
+function uniq(values) {
+  return [...new Set(values)];
+}
+
+async function exists(targetPath) {
+  try {
+    await lstat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+async function writeJson(filePath, data) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeAgentList(agents) {
+  if (!agents || agents.length === 0) {
+    return [...DEFAULT_AGENTS];
+  }
+
+  return uniq(agents.flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter(Boolean));
+}
+
+function parseTags(input) {
+  return uniq((input || []).flatMap((value) => String(value).split(",")).map((value) => value.trim()).filter(Boolean));
+}
+
+export function resolveSkillSelection({ catalog, detections, includeTags = [], excludeTags = [] }) {
+  const coreSkills = catalog.filter((skill) => skill.tags.includes("core"));
+  const requested = new Set(coreSkills.map((skill) => skill.id));
+
+  for (const detection of detections) {
+    for (const skillId of detection.recommendedSkillIds) {
+      requested.add(skillId);
+    }
+  }
+
+  let selected = catalog.filter((skill) => requested.has(skill.id) && skill.portable);
+
+  if (includeTags.length > 0) {
+    selected = selected.filter((skill) => includeTags.every((tag) => skill.tags.includes(tag)));
+  }
+
+  if (excludeTags.length > 0) {
+    selected = selected.filter((skill) => !excludeTags.some((tag) => skill.tags.includes(tag)));
+  }
+
+  return selected.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function buildInstallPlan({ cwd, detections, skills, agents }) {
+  return {
+    cwd,
+    detections,
+    agents,
+    skills: skills.map((skill) => ({
+      id: skill.id,
+      title: skill.title,
+      tags: skill.tags
+    })),
+    installRoot: path.join(cwd, ".skilly-hand"),
+    generatedAt: nowIso()
+  };
+}
+
+async function backupPathIfNeeded(targetPath, backupsDir, lockData) {
+  if (!(await exists(targetPath))) {
+    return null;
+  }
+
+  const backupName = targetPath.replaceAll(path.sep, "__").replace(/^__+/, "");
+  const backupPath = path.join(backupsDir, backupName);
+
+  if (!(await exists(backupPath))) {
+    await mkdir(path.dirname(backupPath), { recursive: true });
+    await cp(targetPath, backupPath, { recursive: true, force: true });
+  }
+
+  lockData.backups[targetPath] = backupPath;
+  return backupPath;
+}
+
+async function ensureManagedTextFile(targetPath, content, backupsDir, lockData) {
+  if (await exists(targetPath)) {
+    const current = await readFile(targetPath, "utf8");
+    if (current === content) {
+      lockData.managedFiles.push(targetPath);
+      return;
+    }
+
+    await backupPathIfNeeded(targetPath, backupsDir, lockData);
+  }
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, content, "utf8");
+  lockData.managedFiles.push(targetPath);
+}
+
+async function ensureSymlink(targetPath, sourcePath, backupsDir, lockData) {
+  if (await exists(targetPath)) {
+    const info = await lstat(targetPath);
+    if (info.isSymbolicLink()) {
+      const resolved = await realpath(targetPath);
+      if (resolved === sourcePath) {
+        lockData.managedSymlinks.push(targetPath);
+        return;
+      }
+
+      await unlink(targetPath);
+    } else {
+      await backupPathIfNeeded(targetPath, backupsDir, lockData);
+      await rm(targetPath, { recursive: true, force: true });
+    }
+  }
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await symlink(sourcePath, targetPath, "dir");
+  lockData.managedSymlinks.push(targetPath);
+}
+
+function buildInstructionFiles({ agentsMarkdown, selectedAgents }) {
+  const files = [];
+
+  if (selectedAgents.includes("codex")) {
+    files.push({ pathParts: ["AGENTS.md"], content: agentsMarkdown });
+  }
+
+  if (selectedAgents.includes("claude")) {
+    files.push({ pathParts: ["CLAUDE.md"], content: agentsMarkdown });
+  }
+
+  if (selectedAgents.includes("gemini")) {
+    files.push({ pathParts: ["GEMINI.md"], content: agentsMarkdown });
+  }
+
+  if (selectedAgents.includes("cursor")) {
+    files.push({ pathParts: ["cursor-instructions.md"], content: agentsMarkdown });
+  }
+
+  if (selectedAgents.includes("copilot")) {
+    files.push({ pathParts: [".github", "copilot-instructions.md"], content: agentsMarkdown });
+  }
+
+  return files;
+}
+
+export async function installProject({
+  cwd,
+  agents,
+  dryRun = false,
+  includeTags = [],
+  excludeTags = []
+}) {
+  const selectedAgents = normalizeAgentList(agents);
+  const catalog = await loadAllSkills();
+  const detections = await detectProject(cwd);
+  const skills = resolveSkillSelection({
+    catalog,
+    detections,
+    includeTags: parseTags(includeTags),
+    excludeTags: parseTags(excludeTags)
+  });
+  const plan = buildInstallPlan({ cwd, detections, skills, agents: selectedAgents });
+
+  if (dryRun) {
+    return { plan, applied: false };
+  }
+
+  const installRoot = plan.installRoot;
+  const targetCatalogDir = path.join(installRoot, "catalog");
+  const backupsDir = path.join(installRoot, "backups");
+  const lockPath = path.join(installRoot, "manifest.lock.json");
+  const lockData = {
+    version: 1,
+    generatedAt: plan.generatedAt,
+    cwd,
+    agents: selectedAgents,
+    skills: skills.map((skill) => skill.id),
+    detections,
+    managedFiles: [],
+    managedSymlinks: [],
+    backups: {}
+  };
+
+  await mkdir(installRoot, { recursive: true });
+  await mkdir(targetCatalogDir, { recursive: true });
+  await mkdir(backupsDir, { recursive: true });
+
+  for (const skill of skills) {
+    await copySkillTo(targetCatalogDir, skill.id);
+  }
+
+  const agentsMarkdown = renderAgentsMarkdown({
+    skills,
+    detections,
+    generatedAt: plan.generatedAt,
+    projectName: path.basename(cwd)
+  });
+
+  await writeFile(path.join(installRoot, "AGENTS.md"), agentsMarkdown, "utf8");
+
+  for (const instructionFile of buildInstructionFiles({ agentsMarkdown, selectedAgents })) {
+    await ensureManagedTextFile(path.join(cwd, ...instructionFile.pathParts), instructionFile.content, backupsDir, lockData);
+  }
+
+  const skillsSourcePath = path.join(installRoot, "catalog");
+
+  if (selectedAgents.includes("codex")) {
+    await ensureSymlink(path.join(cwd, ".codex", "skills"), skillsSourcePath, backupsDir, lockData);
+  }
+  if (selectedAgents.includes("claude")) {
+    await ensureSymlink(path.join(cwd, ".claude", "skills"), skillsSourcePath, backupsDir, lockData);
+  }
+  if (selectedAgents.includes("gemini")) {
+    await ensureSymlink(path.join(cwd, ".gemini", "skills"), skillsSourcePath, backupsDir, lockData);
+  }
+  if (selectedAgents.includes("cursor")) {
+    await ensureSymlink(path.join(cwd, ".cursor", "skills"), skillsSourcePath, backupsDir, lockData);
+  }
+
+  await writeJson(lockPath, lockData);
+
+  return { plan, applied: true, lockPath };
+}
+
+export async function uninstallProject(cwd) {
+  const installRoot = path.join(cwd, ".skilly-hand");
+  const lockPath = path.join(installRoot, "manifest.lock.json");
+
+  if (!(await exists(lockPath))) {
+    return { removed: false, reason: "No skilly-hand installation found." };
+  }
+
+  const lockData = await readJson(lockPath);
+
+  for (const symlinkPath of lockData.managedSymlinks || []) {
+    if (await exists(symlinkPath)) {
+      await rm(symlinkPath, { recursive: true, force: true });
+    }
+  }
+
+  for (const filePath of lockData.managedFiles || []) {
+    if (await exists(filePath)) {
+      const content = await readFile(filePath, "utf8");
+      if (content.includes(MANAGED_MARKER)) {
+        await rm(filePath, { force: true });
+      }
+    }
+  }
+
+  for (const [targetPath, backupPath] of Object.entries(lockData.backups || {})) {
+    if (await exists(backupPath)) {
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await cp(backupPath, targetPath, { recursive: true, force: true });
+    }
+  }
+
+  await rm(installRoot, { recursive: true, force: true });
+  return { removed: true };
+}
+
+export async function runDoctor(cwd) {
+  const installRoot = path.join(cwd, ".skilly-hand");
+  const lockPath = path.join(installRoot, "manifest.lock.json");
+  const fileStatus = await inspectProjectFiles(cwd);
+  const catalogIssues = await verifyCatalogFiles();
+  const installed = await exists(lockPath);
+  const result = {
+    cwd,
+    installed,
+    catalogIssues,
+    fileStatus
+  };
+
+  if (installed) {
+    const lock = await readJson(lockPath);
+    result.lock = {
+      agents: lock.agents,
+      skills: lock.skills,
+      generatedAt: lock.generatedAt
+    };
+  }
+
+  return result;
+}

package/packages/detectors/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@skilly-hand/detectors",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module"
+}

package/packages/detectors/src/index.js

@@ -0,0 +1,169 @@
+import { access, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath) {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+function addDetection(results, detection) {
+  const existing = results.find((item) => item.technology === detection.technology);
+  if (existing) {
+    existing.confidence = Math.max(existing.confidence, detection.confidence);
+    existing.reasons.push(...detection.reasons);
+    existing.recommendedSkillIds = [
+      ...new Set([...existing.recommendedSkillIds, ...detection.recommendedSkillIds])
+    ];
+    return;
+  }
+
+  results.push({
+    technology: detection.technology,
+    confidence: detection.confidence,
+    reasons: [...detection.reasons],
+    recommendedSkillIds: [...new Set(detection.recommendedSkillIds)]
+  });
+}
+
+export async function detectProject(cwd) {
+  const packageJson = await readJson(path.join(cwd, "package.json"));
+  const tsconfigExists = await pathExists(path.join(cwd, "tsconfig.json"));
+  const angularJsonExists = await pathExists(path.join(cwd, "angular.json"));
+  const viteConfigExists =
+    (await pathExists(path.join(cwd, "vite.config.js"))) ||
+    (await pathExists(path.join(cwd, "vite.config.ts")));
+  const nextConfigExists =
+    (await pathExists(path.join(cwd, "next.config.js"))) ||
+    (await pathExists(path.join(cwd, "next.config.mjs"))) ||
+    (await pathExists(path.join(cwd, "next.config.ts")));
+  const storybookDirExists = await pathExists(path.join(cwd, ".storybook"));
+  const results = [];
+
+  if (packageJson) {
+    addDetection(results, {
+      technology: "nodejs",
+      confidence: 1,
+      reasons: ["Found package.json"],
+      recommendedSkillIds: ["token-optimizer", "commit-writer", "pr-writer", "spec-driven-development"]
+    });
+  }
+
+  if (packageJson || tsconfigExists) {
+    addDetection(results, {
+      technology: "typescript",
+      confidence: tsconfigExists ? 0.95 : 0.7,
+      reasons: tsconfigExists ? ["Found tsconfig.json"] : ["TypeScript inferred from project layout"],
+      recommendedSkillIds: ["token-optimizer"]
+    });
+  }
+
+  const deps = packageJson ? { ...packageJson.dependencies, ...packageJson.devDependencies } : {};
+
+  if ("react" in deps) {
+    addDetection(results, {
+      technology: "react",
+      confidence: 0.95,
+      reasons: ['Dependency "react" found in package.json'],
+      recommendedSkillIds: ["accessibility-audit", "storybook-component-stories", "playwright-ui-testing"]
+    });
+  }
+
+  if ("next" in deps || nextConfigExists) {
+    addDetection(results, {
+      technology: "nextjs",
+      confidence: nextConfigExists ? 1 : 0.9,
+      reasons: nextConfigExists ? ["Found next.config.*"] : ['Dependency "next" found in package.json'],
+      recommendedSkillIds: ["accessibility-audit", "playwright-ui-testing", "spec-driven-development"]
+    });
+  }
+
+  if ("@angular/core" in deps || angularJsonExists) {
+    addDetection(results, {
+      technology: "angular",
+      confidence: angularJsonExists ? 1 : 0.95,
+      reasons: angularJsonExists ? ["Found angular.json"] : ['Dependency "@angular/core" found in package.json'],
+      recommendedSkillIds: [
+        "angular-guidelines",
+        "vitest-component-testing",
+        "storybook-component-stories",
+        "accessibility-audit"
+      ]
+    });
+  }
+
+  if ("vite" in deps || viteConfigExists) {
+    addDetection(results, {
+      technology: "vite",
+      confidence: viteConfigExists ? 1 : 0.9,
+      reasons: viteConfigExists ? ["Found vite.config.*"] : ['Dependency "vite" found in package.json'],
+      recommendedSkillIds: ["storybook-component-stories", "playwright-ui-testing"]
+    });
+  }
+
+  if ("@playwright/test" in deps) {
+    addDetection(results, {
+      technology: "playwright",
+      confidence: 0.95,
+      reasons: ['Dependency "@playwright/test" found in package.json'],
+      recommendedSkillIds: ["playwright-ui-testing"]
+    });
+  }
+
+  if ("vitest" in deps) {
+    addDetection(results, {
+      technology: "vitest",
+      confidence: 0.95,
+      reasons: ['Dependency "vitest" found in package.json'],
+      recommendedSkillIds: ["vitest-component-testing"]
+    });
+  }
+
+  if ("tailwindcss" in deps || (await pathExists(path.join(cwd, "tailwind.config.js"))) || (await pathExists(path.join(cwd, "tailwind.config.ts")))) {
+    addDetection(results, {
+      technology: "tailwindcss",
+      confidence: 0.9,
+      reasons: ['Dependency "tailwindcss" or config file found'],
+      recommendedSkillIds: ["accessibility-audit", "css-modules"]
+    });
+  }
+
+  if ("@storybook/react" in deps || "@storybook/angular" in deps || storybookDirExists) {
+    addDetection(results, {
+      technology: "storybook",
+      confidence: storybookDirExists ? 1 : 0.9,
+      reasons: storybookDirExists ? ["Found .storybook directory"] : ["Storybook dependency found"],
+      recommendedSkillIds: ["storybook-component-stories", "playwright-ui-testing"]
+    });
+  }
+
+  return results.sort((a, b) => b.confidence - a.confidence || a.technology.localeCompare(b.technology));
+}
+
+export async function inspectProjectFiles(cwd) {
+  const probes = ["package.json", "tsconfig.json", "angular.json", ".storybook"];
+  const statuses = [];
+
+  for (const probe of probes) {
+    const probePath = path.join(cwd, probe);
+    try {
+      const info = await stat(probePath);
+      statuses.push({ path: probe, exists: true, type: info.isDirectory() ? "directory" : "file" });
+    } catch {
+      statuses.push({ path: probe, exists: false, type: null });
+    }
+  }
+
+  return statuses;
+}