@dujavi/ai-md 0.5.0 → 0.6.0

package/lib/link.js

@@ -0,0 +1,224 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const {
+  defaultLinkMode,
+  isWsl,
+  looksLikeWindowsPath,
+  pathsEqual,
+  normalizePath,
+} = require("./config-paths");
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function linkState(linkPath, expected) {
+  let stat;
+  try {
+    stat = fs.lstatSync(linkPath);
+  } catch {
+    return { path: linkPath, state: "missing", target: null, expected };
+  }
+  if (stat.isSymbolicLink()) {
+    const target = fs.readlinkSync(linkPath);
+    const absTarget = path.isAbsolute(target)
+      ? target
+      : path.resolve(path.dirname(linkPath), target);
+    if (pathsEqual(absTarget, expected) || target === expected) {
+      return { path: linkPath, state: "ok", target, expected, mode: "symlink" };
+    }
+    return {
+      path: linkPath,
+      state: "wrong_target",
+      target,
+      expected,
+      mode: "symlink",
+    };
+  }
+  if (stat.isDirectory()) {
+    return {
+      path: linkPath,
+      state: "directory",
+      target: null,
+      expected,
+      mode: "copy_or_real",
+    };
+  }
+  return { path: linkPath, state: "not_symlink", target: null, expected };
+}
+
+function trySymlink(target, link, type) {
+  fs.symlinkSync(target, link, type);
+}
+
+/**
+ * Platform-aware directory link: symlink | junction | copy
+ */
+function linkPath(
+  target,
+  link,
+  { force = false, dryRun = false, linkMode = null } = {}
+) {
+  const absTarget = path.resolve(target);
+  ensureDir(path.dirname(link));
+  ensureDir(absTarget);
+
+  const mode = linkMode || defaultLinkMode();
+  const state = linkState(link, absTarget);
+
+  if (mode !== "copy" && state.state === "ok") {
+    return { path: link, action: "ok", target: absTarget, mode };
+  }
+
+  if (state.state === "directory" && mode !== "copy" && !force) {
+    const err = new Error(
+      `${link} exists as a real directory (use --force to replace, or --link-mode copy)`
+    );
+    err.code = "EEXIST";
+    throw err;
+  }
+
+  if (state.state === "not_symlink" && !force && mode !== "copy") {
+    const err = new Error(
+      `${link} exists and is not a symlink (use --force to replace)`
+    );
+    err.code = "EEXIST";
+    throw err;
+  }
+
+  if (dryRun) {
+    return {
+      path: link,
+      action: state.state === "missing" ? "would_link" : "would_repair",
+      target: absTarget,
+      mode,
+    };
+  }
+
+  if (mode === "copy") {
+    return syncCopyTree(absTarget, link, { force });
+  }
+
+  if (fs.existsSync(link) || state.state !== "missing") {
+    try {
+      fs.rmSync(link, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const attempts =
+    process.platform === "win32"
+      ? mode === "junction"
+        ? ["junction", "dir"]
+        : [mode === "symlink" ? "dir" : mode, "junction"]
+      : ["dir"];
+
+  let lastErr = null;
+  for (const t of attempts) {
+    try {
+      trySymlink(absTarget, link, t);
+      return {
+        path: link,
+        action: state.state === "missing" ? "linked" : "repaired",
+        target: absTarget,
+        mode: t === "junction" ? "junction" : "symlink",
+      };
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+
+  // Fallback to copy
+  const copied = syncCopyTree(absTarget, link, { force: true });
+  return {
+    ...copied,
+    warning: `symlink failed (${lastErr && lastErr.message}); used copy`,
+    mode: "copy",
+  };
+}
+
+function syncCopyTree(src, dest, { force = false } = {}) {
+  ensureDir(dest);
+  // Remove dest contents that aren't in src
+  if (fs.existsSync(dest)) {
+    for (const name of fs.readdirSync(dest)) {
+      if (name === ".ai-md-copy-marker") continue;
+      const s = path.join(src, name);
+      const d = path.join(dest, name);
+      if (!fs.existsSync(s)) {
+        fs.rmSync(d, { recursive: true, force: true });
+      }
+    }
+  }
+  fs.cpSync(src, dest, { recursive: true, force: true });
+  fs.writeFileSync(
+    path.join(dest, ".ai-md-copy-marker"),
+    JSON.stringify({ src: normalizePath(src), at: new Date().toISOString() }) +
+      "\n"
+  );
+  return { path: dest, action: "copied", target: src, mode: "copy" };
+}
+
+function wslWarnings(cfg, harnessDefs) {
+  const warnings = [];
+  if (!isWsl()) return warnings;
+  warnings.push(
+    "Running under WSL: run ai-md in the same environment as the IDE/CLI that consumes links (Windows Cursor needs Windows ai-md)."
+  );
+  for (const h of harnessDefs || []) {
+    for (const p of [h.skills, h.rules]) {
+      if (p && looksLikeWindowsPath(p)) {
+        warnings.push(
+          `Harness ${h.id} path looks Windows-native under WSL: ${p}`
+        );
+      }
+    }
+  }
+  return warnings;
+}
+
+function hashFile(filePath) {
+  const h = crypto.createHash("sha256");
+  h.update(fs.readFileSync(filePath));
+  return h.digest("hex");
+}
+
+function walkFiles(root, base = root, out = []) {
+  if (!fs.existsSync(root)) return out;
+  for (const ent of fs.readdirSync(root, { withFileTypes: true })) {
+    if (ent.name === ".build-manifest.json" || ent.name === ".ai-md-copy-marker") {
+      continue;
+    }
+    if (ent.name.startsWith(".") && ent.isDirectory()) continue;
+    const full = path.join(root, ent.name);
+    const rel = path.relative(base, full).split(path.sep).join("/");
+    if (ent.isDirectory()) walkFiles(full, base, out);
+    else if (ent.isFile()) out.push({ rel, full });
+  }
+  return out;
+}
+
+function fingerprintTree(root) {
+  const files = walkFiles(root);
+  const map = {};
+  for (const f of files) {
+    map[f.rel] = hashFile(f.full);
+  }
+  return map;
+}
+
+module.exports = {
+  ensureDir,
+  linkPath,
+  linkState,
+  syncCopyTree,
+  wslWarnings,
+  fingerprintTree,
+  walkFiles,
+  hashFile,
+  defaultLinkMode,
+};

package/lib/rescue.js

@@ -0,0 +1,95 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { distRoot, distDirty, agentRoots } = require("./build");
+const { selectHarnesses, ensureAgentSourceDirs } = require("./harnesses");
+const { ensureDir, walkFiles, hashFile } = require("./link");
+const { readManifest } = require("./build");
+
+/**
+ * Promote dirty dist files into agents/<id>/ (not shared/).
+ */
+function runRescue(cfg, opts = {}) {
+  const { agents, dryRun = false, forceLink = false } = opts;
+  const { selected, skipped, warnings } = selectHarnesses(cfg, agents, {
+    forceLink: true,
+    includeUninstalled: true,
+  });
+
+  const actions = [];
+  const byDist = new Map();
+  for (const h of selected) {
+    if (!byDist.has(h.distId)) byDist.set(h.distId, h);
+  }
+
+  for (const h of byDist.values()) {
+    const distDir = distRoot(cfg, h.distId);
+    const dirty = distDirty(distDir);
+    if (!dirty.dirty) {
+      actions.push({ id: h.id, distId: h.distId, action: "clean" });
+      continue;
+    }
+    ensureAgentSourceDirs(cfg, h.distId);
+    const agent = agentRoots(cfg, h.distId);
+    const manifest = readManifest(distDir) || { files: {} };
+
+    for (const rel of dirty.files) {
+      const src = path.join(distDir, rel);
+      if (!fs.existsSync(src)) continue;
+      let dest;
+      if (rel.startsWith("rules/")) {
+        dest = path.join(agent.rules, path.basename(rel));
+      } else if (rel.startsWith("skills/")) {
+        // skills/name/...
+        const parts = rel.split("/");
+        const skillName = parts[1];
+        if (!skillName) continue;
+        if (parts.length === 2 || fs.statSync(src).isDirectory()) {
+          dest = path.join(agent.skills, skillName);
+          if (!dryRun) {
+            if (fs.statSync(path.join(distDir, "skills", skillName)).isDirectory()) {
+              fs.cpSync(path.join(distDir, "skills", skillName), dest, {
+                recursive: true,
+                force: true,
+              });
+            }
+          }
+          actions.push({
+            id: h.id,
+            action: dryRun ? "would_rescue_skill" : "rescued_skill",
+            from: rel,
+            to: dest,
+          });
+          continue;
+        }
+        dest = path.join(agent.skills, parts.slice(1).join("/"));
+      } else {
+        continue;
+      }
+      if (dryRun) {
+        actions.push({
+          id: h.id,
+          action: "would_rescue",
+          from: rel,
+          to: dest,
+        });
+      } else {
+        ensureDir(path.dirname(dest));
+        if (fs.statSync(src).isFile()) {
+          fs.copyFileSync(src, dest);
+        }
+        actions.push({
+          id: h.id,
+          action: "rescued",
+          from: rel,
+          to: dest,
+        });
+      }
+    }
+  }
+
+  return { actions, skipped, warnings };
+}
+
+module.exports = { runRescue };

package/lib/skeleton.js

@@ -0,0 +1,117 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { ensureDir } = require("./link");
+
+const SKELETON_VERSION = 1;
+
+function packageRoot() {
+  return path.join(__dirname, "..");
+}
+
+function skeletonRoot() {
+  return path.join(packageRoot(), "skeleton");
+}
+
+function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) return true;
+  const ents = fs.readdirSync(dir).filter((n) => n !== "." && n !== "..");
+  return ents.length === 0;
+}
+
+function copySkeletonFile(src, dest, { force = false } = {}) {
+  if (fs.existsSync(dest) && !force) {
+    return { action: "keep", path: dest };
+  }
+  ensureDir(path.dirname(dest));
+  fs.cpSync(src, dest, { recursive: true, force: true });
+  return { action: force ? "replaced" : "added", path: dest };
+}
+
+function walkSkeleton(dir, base = dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, ent.name);
+    const rel = path.relative(base, full);
+    if (ent.isDirectory()) walkSkeleton(full, base, out);
+    else out.push({ rel, full });
+  }
+  return out;
+}
+
+/**
+ * Seed missing skeleton files into cfg.dir (never overwrite unless force).
+ */
+function seedSkeleton(cfg, { force = false, dryRun = false } = {}) {
+  const srcRoot = skeletonRoot();
+  if (!fs.existsSync(srcRoot)) {
+    const err = new Error(`skeleton missing in package: ${srcRoot}`);
+    err.code = "ENOENT";
+    throw err;
+  }
+  const actions = [];
+  for (const f of walkSkeleton(srcRoot)) {
+    const dest = path.join(cfg.dir, f.rel);
+    if (dryRun) {
+      actions.push({
+        action: fs.existsSync(dest) && !force ? "would_keep" : "would_add",
+        path: dest,
+      });
+      continue;
+    }
+    actions.push(copySkeletonFile(f.full, dest, { force }));
+  }
+  // ensure agent dir structure
+  for (const id of ["cursor", "claude", "agents", "gemini", "opencode"]) {
+    const r = path.join(cfg.dir, "agents", id, "rules");
+    const s = path.join(cfg.dir, "agents", id, "skills");
+    if (!dryRun) {
+      ensureDir(r);
+      ensureDir(s);
+    }
+  }
+  const verPath = path.join(cfg.dir, ".ai-md-skeleton-version");
+  if (!dryRun) {
+    fs.writeFileSync(verPath, String(SKELETON_VERSION) + "\n");
+  }
+  actions.push({
+    action: dryRun ? "would_write_version" : "version",
+    path: verPath,
+    version: SKELETON_VERSION,
+  });
+  return { actions, skeletonVersion: SKELETON_VERSION };
+}
+
+function initRepo(cfg, { noGit = false, force = false, dryRun = false } = {}) {
+  const dir = cfg.dir;
+  if (fs.existsSync(dir) && !isEmptyDir(dir) && !force) {
+    const err = new Error(
+      `${dir} is not empty. Use ai-md seed-skeleton to add missing files, or ai-md init --force`
+    );
+    err.code = "EEXIST";
+    throw err;
+  }
+  if (dryRun) {
+    return { action: "would_init", dir };
+  }
+  ensureDir(dir);
+  if (force && fs.existsSync(dir)) {
+    // only remove if force — dangerous; only clear if user asked
+    // We do not wipe; seed with force overwrite of skeleton files only
+  }
+  const seeded = seedSkeleton(cfg, { force: true, dryRun: false });
+  if (!noGit && !fs.existsSync(path.join(dir, ".git"))) {
+    execFileSync("git", ["init"], { cwd: dir, stdio: "pipe" });
+  }
+  return { action: "initialized", dir, ...seeded };
+}
+
+module.exports = {
+  SKELETON_VERSION,
+  skeletonRoot,
+  seedSkeleton,
+  initRepo,
+  isEmptyDir,
+};

package/lib/status.js

@@ -12,9 +12,16 @@ const {
   countSkills,
   listSkillNames,
   listRuleNames,
-  symlinkState,
-  agentSkillTargets,
 } = require("./config");
+const { linkState } = require("./link");
+const { distRoot, distDirty, sharedRoots } = require("./build");
+const {
+  selectHarnesses,
+  resolveHarness,
+  isHarnessInstalled,
+} = require("./harnesses");
+const { isWsl } = require("./config-paths");
+const { SKELETON_VERSION } = require("./skeleton");
 
 function git(repo, args) {
   try {
@@ -60,9 +67,7 @@ function collectProjects(cfg, { full = false, from = "base" } = {}) {
   const tmplDir = templatePath(cfg, from);
   if (!fs.existsSync(cfg.projectsDir)) return projects;
   for (const name of fs.readdirSync(cfg.projectsDir).sort()) {
-    if (name.startsWith(".")) continue;
-    // legacy leftover
-    if (name === "template") continue;
+    if (name.startsWith(".") || name === "template") continue;
     const projectDir = path.join(cfg.projectsDir, name);
     if (!fs.statSync(projectDir).isDirectory()) continue;
     const drift = templateDrift(projectDir, tmplDir);
@@ -83,25 +88,50 @@ function collectProjects(cfg, { full = false, from = "base" } = {}) {
 function collectStatus(opts = {}) {
   const cfg = resolveConfig();
   const full = Boolean(opts.full);
-  const agents = opts.agents || ["cursor"];
+  const agents = opts.agents || cfg.agents || ["cursor"];
   const from = opts.from || "base";
 
   const migration = migrateLegacyTemplate(cfg);
-
   const exists = fs.existsSync(cfg.dir);
   const isGit = exists && fs.existsSync(path.join(cfg.dir, ".git"));
+  const shared = sharedRoots(cfg);
 
-  const links = [
-    symlinkState(cfg.cursorSkills, cfg.skillsDir),
-    symlinkState(cfg.cursorRules, cfg.rulesDir),
-  ];
+  const { selected, skipped, warnings } = selectHarnesses(cfg, agents, {
+    forceLink: false,
+    includeUninstalled: true,
+  });
 
-  const agentLinks = agentSkillTargets(cfg.home, agents)
-    .filter((t) => t.name !== "cursor")
-    .map((t) => ({
-      agent: t.name,
-      ...symlinkState(t.path, cfg.skillsDir),
-    }));
+  const links = [];
+  const harnesses = [];
+  for (const h of selected) {
+    const installed = isHarnessInstalled(h);
+    const dist = distRoot(cfg, h.distId);
+    const dirty = distDirty(dist);
+    const entry = {
+      id: h.id,
+      distId: h.distId,
+      installed,
+      aliasOf: h.aliasOf,
+      format: h.format,
+      distDirty: dirty.dirty,
+      ...(full && dirty.dirty ? { dirtyFiles: dirty.files } : {}),
+    };
+    if (installed) {
+      if (h.skills) {
+        const st = linkState(h.skills, path.join(dist, "skills"));
+        links.push({ harness: h.id, kind: "skills", ...st });
+        entry.skillsLink = st.state;
+      }
+      if (h.rules && h.format !== "skills-only") {
+        const st = linkState(h.rules, path.join(dist, "rules"));
+        links.push({ harness: h.id, kind: "rules", ...st });
+        entry.rulesLink = st.state;
+      }
+    } else {
+      entry.skillsLink = "skipped_not_installed";
+    }
+    harnesses.push(entry);
+  }
 
   const templates = collectTemplates(cfg, { full });
   const projects = collectProjects(cfg, { full, from });
@@ -124,44 +154,67 @@ function collectStatus(opts = {}) {
   const problems = [];
   if (!exists) problems.push("ai_md_missing");
   else if (!isGit) problems.push("ai_md_not_git");
+  if (fs.existsSync(path.join(cfg.dir, "rules")) || fs.existsSync(path.join(cfg.dir, "skills"))) {
+    problems.push("legacy_flat_layout");
+  }
   for (const l of links) {
-    if (l.state !== "ok") problems.push(`cursor_${path.basename(l.path)}_${l.state}`);
+    if (l.state !== "ok" && l.state !== "directory") {
+      problems.push(`${l.harness}_${l.kind}_${l.state}`);
+    }
+  }
+  for (const h of harnesses) {
+    if (h.installed && h.distDirty) problems.push(`dist_dirty_${h.distId}`);
   }
   if (!fs.existsSync(templatePath(cfg, "base")) && templates.length === 0) {
     problems.push("templates_missing");
   }
 
+  let skeletonVersion = null;
+  try {
+    skeletonVersion = Number(
+      fs.readFileSync(path.join(cfg.dir, ".ai-md-skeleton-version"), "utf8").trim()
+    );
+  } catch {
+    /* none */
+  }
+  if (skeletonVersion != null && skeletonVersion < SKELETON_VERSION) {
+    problems.push("skeleton_outdated");
+  }
+
   return {
     generatedAt: new Date().toISOString(),
     dir: cfg.dir,
     remote: remote || cfg.remote,
     sources: cfg.sources,
+    linkMode: cfg.linkMode,
+    wsl: isWsl(),
     machineConfigPath: cfg.machineConfigPath,
     machineConfig: cfg.machineConfig,
     branch,
     dirty,
     statusLine: aheadBehind,
     layout: {
-      system: { rules: cfg.rulesDir, skills: cfg.skillsDir },
+      shared: { rules: shared.rules, skills: shared.skills },
+      agents: cfg.agentsDir,
+      dist: cfg.distDir,
       templates: cfg.templatesDir,
       projects: cfg.projectsDir,
     },
     migration,
     counts: {
-      rules: countRules(cfg.rulesDir),
-      skills: countSkills(cfg.skillsDir),
+      rules: countRules(shared.rules),
+      skills: countSkills(shared.skills),
       templates: templates.length,
       projects: projects.length,
       drifting: drifting.length,
       problems: problems.length,
     },
+    harnesses,
+    skipped,
+    warnings,
     links: links.map((l) => ({
-      path: l.path,
-      state: l.state,
-      ...(full ? { target: l.target, expected: l.expected } : {}),
-    })),
-    agentLinks: agentLinks.map((l) => ({
-      agent: l.agent,
+      harness: l.harness,
+      kind: l.kind,
       path: l.path,
       state: l.state,
       ...(full ? { target: l.target, expected: l.expected } : {}),
@@ -169,6 +222,8 @@ function collectStatus(opts = {}) {
     templates,
     projects,
     driftFrom: from,
+    skeletonVersion,
+    packageSkeletonVersion: SKELETON_VERSION,
     problems,
   };
 }
@@ -177,7 +232,12 @@ function statusHelp(data) {
   const help = [];
   if (data.problems.includes("ai_md_missing") || data.problems.includes("ai_md_not_git")) {
     help.push(
-      "Run `ai-md setup --remote <git-url>` (or `ai-md install --remote <git-url>`) to clone and link"
+      "Run `ai-md init` (no remote) or `ai-md setup --remote <git-url>`"
+    );
+  }
+  if (data.problems.includes("legacy_flat_layout")) {
+    help.push(
+      "Migrate flat rules/skills into shared/ (and agents/<id>/); see package README"
     );
   }
   if (!data.machineConfig) {
@@ -185,23 +245,38 @@ function statusHelp(data) {
       "Persist remote/dir with `ai-md setup --remote <url>` or `ai-md config set --remote <url> --dir ~/.ai-md`"
     );
   }
-  if (data.links.some((l) => l.state !== "ok")) {
-    help.push("Run `ai-md doctor --fix` to repair ~/.cursor skills/rules symlinks");
+  if (data.links.some((l) => l.state !== "ok" && l.state !== "directory")) {
+    help.push("Run `ai-md doctor --fix` to rebuild dist and repair links");
+  }
+  if (data.problems.some((p) => p.startsWith("dist_dirty_"))) {
+    help.push("Run `ai-md rescue --agents <id>` or `ai-md build --force`");
+  }
+  if (data.problems.includes("skeleton_outdated")) {
+    help.push("Run `ai-md seed-skeleton` to add new recommended files");
+  }
+  if (data.wsl) {
+    help.push(
+      "WSL detected: use Windows ai-md for Windows Cursor (homes differ)"
+    );
+  }
+  if (data.skipped && data.skipped.some((s) => s.reason === "not_installed")) {
+    help.push(
+      "Some harnesses skipped (AI not installed). Install the tool or use --force-link"
+    );
   }
   if (data.problems.includes("templates_missing")) {
-    help.push("Create ~/.ai-md/templates/base with project starters (system skills/rules stay in skills/ and rules/)");
+    help.push("Run `ai-md seed-skeleton` or add templates/base");
   }
   if (data.counts.drifting > 0) {
     help.push(
-      `Run \`ai-md apply-template --project <name> --from ${data.driftFrom || "base"}\` to merge missing template files`
+      `Run \`ai-md apply-template --project <name> --from ${data.driftFrom || "base"}\``
     );
   }
   if (data.dirty) {
-    help.push('Run `ai-md push -m "<why>"` to commit and push private config');
+    help.push('Run `ai-md push -m "<why>"` to commit and push');
   } else {
-    help.push("Edit system skills/rules under ~/.ai-md/{skills,rules}; project overlays under projects/");
+    help.push("Edit shared/ or agents/<id>/ only; then `ai-md build`");
   }
-  help.push("Run `ai-md init-project --repo <path> --from base` to seed a project");
   help.push("Run `ai-md status --json` for machine-readable output");
   return help;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dujavi/ai-md",
-  "version": "0.5.0",
-  "description": "AXI-shaped CLI for a private ~/.ai-md: system skills/rules, templates, projects, and private script runner for agent harnesses (Cursor, Claude, agents)",
+  "version": "0.6.0",
+  "description": "AXI-shaped CLI for private ~/.ai-md: shared+agents build to dist, multi-harness link (Cursor, Claude, agents, …)",
   "bin": {
     "ai-md": "bin/ai-md.js"
   },
@@ -9,6 +9,7 @@
     "bin/",
     "lib/",
     "scripts/",
+    "skeleton/",
     "docs/",
     "README.md",
     "LICENSE"
@@ -17,7 +18,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node bin/ai-md.js --help && node bin/ai-md.js status --json >/dev/null"
+    "test": "node bin/ai-md.js --help && node bin/ai-md.js harness list --json >/dev/null && node bin/ai-md.js status --json >/dev/null"
   },
   "dependencies": {
     "@toon-format/toon": "^2.3.1"