@dujavi/ai-md 0.4.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/scripts.js

@@ -0,0 +1,104 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function scriptsDir(cfg) {
+  return path.join(cfg.dir, "scripts");
+}
+
+/**
+ * Resolve a private script by basename only (no path separators).
+ * Prefers exact name, then `<name>.sh`.
+ */
+function resolveScript(cfg, name) {
+  const raw = String(name || "").trim();
+  if (!raw || !NAME_RE.test(raw) || raw.includes("..")) {
+    const err = new Error(
+      `invalid script name: ${JSON.stringify(name)} (use a single basename)`
+    );
+    err.code = "EINVAL";
+    throw err;
+  }
+
+  const dir = scriptsDir(cfg);
+  const exact = path.join(dir, raw);
+  const withSh = raw.endsWith(".sh") ? null : path.join(dir, `${raw}.sh`);
+
+  if (fs.existsSync(exact) && fs.statSync(exact).isFile()) {
+    return { name: raw, path: exact, dir };
+  }
+  if (withSh && fs.existsSync(withSh) && fs.statSync(withSh).isFile()) {
+    return { name: raw, path: withSh, dir };
+  }
+
+  const err = new Error(
+    `script not found: ${raw} (looked in ${dir}/${raw} and ${dir}/${raw}.sh)`
+  );
+  err.code = "ENOENT";
+  throw err;
+}
+
+/**
+ * Run a private script with forwarded args. Returns { name, args, path, exitCode }.
+ * Uses bash for .sh; otherwise executes the file directly.
+ */
+function runScript(cfg, name, args = [], { dryRun = false } = {}) {
+  const resolved = resolveScript(cfg, name);
+  const scriptArgs = Array.isArray(args) ? args.map(String) : [];
+  const useBash = resolved.path.endsWith(".sh");
+  const argv = useBash
+    ? ["bash", resolved.path, ...scriptArgs]
+    : [resolved.path, ...scriptArgs];
+
+  if (dryRun) {
+    return {
+      name: resolved.name,
+      args: scriptArgs,
+      path: resolved.path,
+      exitCode: 0,
+      dryRun: true,
+      command: argv,
+    };
+  }
+
+  const result = spawnSync(argv[0], argv.slice(1), {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  if (result.error) {
+    const err = new Error(result.error.message);
+    err.code = result.error.code || "EEXEC";
+    throw err;
+  }
+
+  return {
+    name: resolved.name,
+    args: scriptArgs,
+    path: resolved.path,
+    exitCode: result.status === null ? 1 : result.status,
+  };
+}
+
+function runScripts(cfg, names, args = [], { dryRun = false } = {}) {
+  const results = [];
+  for (const name of names) {
+    const result = runScript(cfg, name, args, { dryRun });
+    results.push(result);
+    if (!dryRun && result.exitCode !== 0) {
+      break;
+    }
+  }
+  return results;
+}
+
+module.exports = {
+  scriptsDir,
+  resolveScript,
+  runScript,
+  runScripts,
+};

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,
+};