@dujavi/ai-md 0.5.0 → 0.6.1

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/remote.js

@@ -0,0 +1,116 @@
+"use strict";
+
+const { execFileSync } = require("child_process");
+
+function runCapture(cmd, args, opts = {}) {
+  try {
+    return execFileSync(cmd, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: opts.timeout || 20000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * GitHub login from authenticated `gh`, else git config github.user.
+ */
+function detectGithubUser() {
+  const fromGh = runCapture("gh", ["api", "user", "-q", ".login"]);
+  if (fromGh && !fromGh.includes(" ") && /^[A-Za-z0-9-]+$/.test(fromGh)) {
+    return { user: fromGh, via: "gh" };
+  }
+  const fromGit = runCapture("git", ["config", "--global", "github.user"]);
+  if (fromGit && /^[A-Za-z0-9-]+$/.test(fromGit)) {
+    return { user: fromGit, via: "git" };
+  }
+  return { user: null, via: null };
+}
+
+function candidateRemotes(user) {
+  return [
+    `https://github.com/${user}/.ai-md.git`,
+    `git@github.com:${user}/.ai-md.git`,
+  ];
+}
+
+function remoteReachable(url) {
+  const out = runCapture("git", ["ls-remote", "--exit-code", url, "HEAD"], {
+    timeout: 25000,
+  });
+  // ls-remote --exit-code returns null from runCapture on failure
+  // success returns stdout (may be empty-ish but non-null string with sha)
+  return out != null;
+}
+
+function repoExistsViaGh(user) {
+  const url = runCapture("gh", [
+    "repo",
+    "view",
+    `${user}/.ai-md`,
+    "--json",
+    "url",
+    "-q",
+    ".url",
+  ]);
+  return Boolean(url);
+}
+
+/**
+ * Only invent a default remote when gh/git identifies a user AND
+ * github.com/{user}/.ai-md exists.
+ */
+function detectDefaultRemote() {
+  const { user, via } = detectGithubUser();
+  if (!user) {
+    return {
+      remote: null,
+      source: "none",
+      githubUser: null,
+      githubVia: null,
+      verified: false,
+    };
+  }
+
+  if (repoExistsViaGh(user)) {
+    return {
+      remote: `https://github.com/${user}/.ai-md.git`,
+      source: "detected",
+      githubUser: user,
+      githubVia: via,
+      verified: true,
+    };
+  }
+
+  for (const url of candidateRemotes(user)) {
+    if (remoteReachable(url)) {
+      return {
+        remote: url.startsWith("git@")
+          ? `https://github.com/${user}/.ai-md.git`
+          : url,
+        source: "detected",
+        githubUser: user,
+        githubVia: via,
+        verified: true,
+      };
+    }
+  }
+
+  return {
+    remote: null,
+    source: "none",
+    githubUser: user,
+    githubVia: via,
+    verified: false,
+    hint: `No github.com/${user}/.ai-md repo found (create it or pass --remote)`,
+  };
+}
+
+module.exports = {
+  detectGithubUser,
+  detectDefaultRemote,
+  remoteReachable,
+  candidateRemotes,
+};

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