@dujavi/ai-md 0.5.0 → 0.6.1

package/lib/config.js

@@ -1,22 +1,19 @@
 "use strict";
 
 const fs = require("fs");
-const os = require("os");
 const path = require("path");
+const { execFileSync } = require("child_process");
+const { expandHome } = require("./config-paths");
+const { detectDefaultRemote } = require("./remote");
 
-const DEFAULT_REMOTE = "https://github.com/dujavi/.ai-md.git";
+/** @deprecated No hardcoded personal default — use detectDefaultRemote(). */
+const DEFAULT_REMOTE = null;
 
-function expandHome(p) {
-  if (!p) return p;
-  if (p === "~") return os.homedir();
-  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
-/** Machine-local config (not inside the private content repo). */
 function machineConfigPath(env = process.env) {
   if (env.AI_MD_CONFIG) return expandHome(env.AI_MD_CONFIG);
-  const xdg = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  const xdg =
+    env.XDG_CONFIG_HOME ||
+    path.join(require("os").homedir(), ".config");
   return path.join(xdg, "ai-md", "config.json");
 }
 
@@ -36,20 +33,16 @@ function readMachineConfig(env = process.env) {
   }
 }
 
-function writeMachineConfig({ dir, remote }, env = process.env, { dryRun = false } = {}) {
+function writeMachineConfig(patch, env = process.env, { dryRun = false } = {}) {
   const configPath = machineConfigPath(env);
   const existing = readMachineConfig(env).raw || {};
   const next = {
     ...existing,
-    ...(dir != null ? { dir: expandHome(dir) } : {}),
-    ...(remote != null ? { remote: String(remote) } : {}),
+    ...patch,
     updatedAt: new Date().toISOString(),
   };
-  if (!next.dir && !next.remote) {
-    const err = new Error("nothing to write: provide --dir and/or --remote");
-    err.code = "EINVAL";
-    throw err;
-  }
+  if (patch.dir != null) next.dir = expandHome(patch.dir);
+  if (patch.remote != null) next.remote = String(patch.remote);
   if (dryRun) {
     return { action: "would_write", path: configPath, config: next };
   }
@@ -65,11 +58,9 @@ function writeMachineConfig({ dir, remote }, env = process.env, { dryRun = false
   return { action: "wrote", path: configPath, config: next };
 }
 
-/**
- * Precedence: explicit opts > env > machine config file > defaults.
- * @param {{ dir?: string, remote?: string }} [opts]
- */
 function resolveConfig(env = process.env, opts = {}) {
+  const os = require("os");
+  const { defaultLinkMode } = require("./config-paths");
   const home = os.homedir();
   const stored = readMachineConfig(env);
   const defaultDir = path.join(home, ".ai-md");
@@ -77,11 +68,25 @@ function resolveConfig(env = process.env, opts = {}) {
   const envDir = env.AI_MD_DIR || env.CURSOR_MD_DIR || null;
   const envRemote = env.AI_MD_REMOTE || env.CURSOR_MD_REMOTE || null;
 
-  const dir = expandHome(
-    opts.dir || envDir || stored.dir || defaultDir
-  );
-  const remote =
-    opts.remote || envRemote || stored.remote || DEFAULT_REMOTE;
+  const dir = expandHome(opts.dir || envDir || stored.dir || defaultDir);
+
+  let remote = opts.remote || envRemote || stored.remote || null;
+  let remoteSource = opts.remote
+    ? "flag"
+    : envRemote
+      ? "env"
+      : stored.remote
+        ? "config"
+        : "none";
+  let remoteDetection = null;
+
+  if (!remote && opts.skipRemoteDetect !== true) {
+    remoteDetection = detectDefaultRemote();
+    if (remoteDetection.remote) {
+      remote = remoteDetection.remote;
+      remoteSource = "detected";
+    }
+  }
 
   const sources = {
     dir: opts.dir
@@ -91,38 +96,53 @@ function resolveConfig(env = process.env, opts = {}) {
         : stored.dir
           ? "config"
           : "default",
-    remote: opts.remote
-      ? "flag"
-      : envRemote && !(stored.remote && envRemote === stored.remote)
-        ? "env"
-        : stored.remote
-          ? "config"
-          : "default",
+    remote: remoteSource,
   };
 
+  const raw = stored.raw || {};
+  const agents = Array.isArray(raw.agents) && raw.agents.length
+    ? raw.agents.map((a) => String(a).toLowerCase())
+    : ["cursor"];
+  const linkMode = opts.linkMode || raw.linkMode || defaultLinkMode();
+
   const templatesDir = path.join(dir, "templates");
   return {
     home,
     dir,
     remote,
     sources,
+    remoteDetection,
+    agents,
+    linkMode,
     machineConfigPath: stored.path,
-    machineConfig: stored.raw,
+    machineConfig: raw,
     cursorSkills: path.join(home, ".cursor", "skills"),
     cursorRules: path.join(home, ".cursor", "rules"),
     projectsDir: path.join(dir, "projects"),
     templatesDir,
     templateDir: path.join(templatesDir, "base"),
-    skillsDir: path.join(dir, "skills"),
-    rulesDir: path.join(dir, "rules"),
+    // legacy aliases → shared (build uses shared/)
+    skillsDir: path.join(dir, "shared", "skills"),
+    rulesDir: path.join(dir, "shared", "rules"),
+    sharedDir: path.join(dir, "shared"),
+    agentsDir: path.join(dir, "agents"),
+    distDir: path.join(dir, "dist"),
   };
 }
 
 function applyEnvFromConfig(cfg) {
   process.env.AI_MD_DIR = cfg.dir;
-  process.env.AI_MD_REMOTE = cfg.remote;
   process.env.CURSOR_MD_DIR = cfg.dir;
-  process.env.CURSOR_MD_REMOTE = cfg.remote;
+  // Never invent remotes into the environment (avoids fake defaults and
+  // flipping sources.remote to "env" on re-resolve). Only pass through when
+  // the process already had one, or the caller passed --remote (flag).
+  if (
+    cfg.remote &&
+    (cfg.sources.remote === "env" || cfg.sources.remote === "flag")
+  ) {
+    process.env.AI_MD_REMOTE = cfg.remote;
+    process.env.CURSOR_MD_REMOTE = cfg.remote;
+  }
 }
 
 function templatePath(cfg, name = "base") {
@@ -142,16 +162,14 @@ function countRules(rulesDir) {
   if (!fs.existsSync(rulesDir)) return 0;
   return fs
     .readdirSync(rulesDir)
-    .filter((f) => f.endsWith(".mdc") || f.endsWith(".md"))
-    .length;
+    .filter((f) => f.endsWith(".mdc") || f.endsWith(".md")).length;
 }
 
 function countSkills(skillsDir) {
   if (!fs.existsSync(skillsDir)) return 0;
   return fs
     .readdirSync(skillsDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
-    .length;
+    .filter((d) => d.isDirectory() && !d.name.startsWith(".")).length;
 }
 
 function listSkillNames(skillsDir) {
@@ -172,33 +190,24 @@ function listRuleNames(rulesDir) {
 }
 
 function symlinkState(linkPath, expected) {
-  let stat;
-  try {
-    stat = fs.lstatSync(linkPath);
-  } catch {
-    return { path: linkPath, state: "missing", target: null, expected };
-  }
-  if (!stat.isSymbolicLink()) {
-    return { path: linkPath, state: "not_symlink", target: null, expected };
-  }
-  const target = fs.readlinkSync(linkPath);
-  if (target === expected) {
-    return { path: linkPath, state: "ok", target, expected };
-  }
-  return { path: linkPath, state: "wrong_target", target, expected };
+  const { linkState } = require("./link");
+  return linkState(linkPath, expected);
 }
 
+/** @deprecated use harnesses.selectHarnesses */
 function agentSkillTargets(home, agents) {
-  const map = {
-    cursor: path.join(home, ".cursor", "skills"),
-    claude: path.join(home, ".claude", "skills"),
-    agents: path.join(home, ".agents", "skills"),
-  };
+  const { resolveHarness } = require("./harnesses");
+  const cfg = { home, machineConfig: {} };
   return (agents || [])
-    .map((a) => String(a).trim().toLowerCase())
-    .filter(Boolean)
-    .filter((name) => map[name])
-    .map((name) => ({ name, path: map[name] }));
+    .map((a) => {
+      try {
+        const h = resolveHarness(a, { ...cfg, home });
+        return h.skills ? { name: h.id, path: h.skills } : null;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
 }
 
 function migrateLegacyTemplate(cfg, { dryRun = false } = {}) {
@@ -213,6 +222,51 @@ function migrateLegacyTemplate(cfg, { dryRun = false } = {}) {
   return { action: "migrated", from: legacy, to: dest };
 }
 
+function gitClone(remote, dir, { dryRun = false } = {}) {
+  if (!remote) {
+    const err = new Error(
+      "git clone requires a remote URL (pass --remote or set AI_MD_REMOTE)"
+    );
+    err.code = "EINVAL";
+    throw err;
+  }
+  if (dryRun) return { action: "would_clone", remote, dir };
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  execFileSync("git", ["clone", remote, dir], { stdio: "inherit" });
+  return { action: "cloned", remote, dir };
+}
+
+function gitPull(dir, { dryRun = false } = {}) {
+  if (dryRun) return { action: "would_pull", dir };
+  execFileSync("git", ["-C", dir, "pull", "--rebase", "--autostash"], {
+    stdio: "inherit",
+  });
+  return { action: "pulled", dir };
+}
+
+function gitPush(dir, { message, dryRun = false } = {}) {
+  if (dryRun) return { action: "would_push", dir, message };
+  execFileSync("git", ["-C", dir, "add", "-A"], { stdio: "inherit" });
+  let dirty = true;
+  try {
+    execFileSync("git", ["-C", dir, "diff", "--cached", "--quiet"], {
+      stdio: "pipe",
+    });
+    dirty = false;
+  } catch {
+    dirty = true;
+  }
+  if (dirty) {
+    execFileSync(
+      "git",
+      ["-C", dir, "commit", "-m", message || "Update personal AI skills/rules"],
+      { stdio: "inherit" }
+    );
+  }
+  execFileSync("git", ["-C", dir, "push"], { stdio: "inherit" });
+  return { action: "pushed", dir, committed: dirty };
+}
+
 module.exports = {
   DEFAULT_REMOTE,
   machineConfigPath,
@@ -230,4 +284,7 @@ module.exports = {
   listRuleNames,
   symlinkState,
   agentSkillTargets,
+  gitClone,
+  gitPull,
+  gitPush,
 };

package/lib/harnesses/index.js

@@ -0,0 +1,309 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { expandHome } = require("../config-paths");
+
+/** Built-in harness registry. codex aliases agents (shared ~/.agents/skills). */
+const BUILTINS = {
+  cursor: {
+    id: "cursor",
+    tier: "A",
+    format: "mdc",
+    emitter: "full",
+    skills: "~/.cursor/skills",
+    rules: "~/.cursor/rules",
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.cursor"], bins: ["cursor", "agent"] },
+  },
+  claude: {
+    id: "claude",
+    tier: "A",
+    format: "md",
+    emitter: "full",
+    skills: "~/.claude/skills",
+    rules: "~/.claude/rules",
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.claude"], bins: ["claude"] },
+  },
+  agents: {
+    id: "agents",
+    tier: "A",
+    format: "skills-only",
+    emitter: "full",
+    skills: "~/.agents/skills",
+    rules: null,
+    unique: false,
+    aliasOf: null,
+    detect: { dirs: ["~/.agents", "~/.codex"], bins: ["codex"] },
+  },
+  codex: {
+    id: "codex",
+    tier: "A",
+    format: "skills-only",
+    emitter: "full",
+    skills: "~/.agents/skills",
+    rules: null,
+    unique: false,
+    aliasOf: "agents",
+    detect: { dirs: ["~/.codex", "~/.agents"], bins: ["codex"] },
+  },
+  gemini: {
+    id: "gemini",
+    tier: "A",
+    format: "skills-only",
+    emitter: "full",
+    skills: "~/.gemini/skills",
+    rules: null,
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.gemini"], bins: ["gemini"] },
+  },
+  opencode: {
+    id: "opencode",
+    tier: "A",
+    format: "skills-only",
+    emitter: "full",
+    skills: "~/.config/opencode/skills",
+    rules: null,
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.config/opencode"], bins: ["opencode"] },
+  },
+  copilot: {
+    id: "copilot",
+    tier: "B",
+    format: "skills-only",
+    emitter: "stub",
+    skills: "~/.copilot/skills",
+    rules: null,
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.copilot"], bins: ["copilot"] },
+  },
+  windsurf: {
+    id: "windsurf",
+    tier: "B",
+    format: "skills-only",
+    emitter: "stub",
+    skills: null,
+    rules: null,
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.codeium"], bins: ["windsurf"] },
+  },
+  grok: {
+    id: "grok",
+    tier: "B",
+    format: "skills-only",
+    emitter: "stub",
+    skills: null,
+    rules: null,
+    unique: true,
+    aliasOf: null,
+    detect: { dirs: ["~/.grok"], bins: ["grok"] },
+  },
+};
+
+function which(bin) {
+  const pathEnv = process.env.PATH || "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+      : [""];
+  for (const dir of pathEnv.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+        /* try next */
+      }
+    }
+  }
+  return null;
+}
+
+function dirExists(p) {
+  try {
+    return fs.statSync(expandHome(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True if the harness looks installed on this machine.
+ * Custom harnesses: installed if any configured live parent exists, or always if --force-link.
+ */
+function isHarnessInstalled(def, { forceLink = false } = {}) {
+  if (forceLink) return true;
+  if (!def) return false;
+  if (def.detect) {
+    for (const d of def.detect.dirs || []) {
+      if (dirExists(d)) return true;
+    }
+    for (const b of def.detect.bins || []) {
+      if (which(b)) return true;
+    }
+  }
+  // Custom / override: consider installed if skills or rules parent exists
+  if (def.skills && dirExists(path.dirname(expandHome(def.skills)))) return true;
+  if (def.rules && dirExists(path.dirname(expandHome(def.rules)))) return true;
+  // Built-in with no detect hit
+  if (BUILTINS[def.id] && def.emitter === "stub" && !def.skills) return false;
+  if (!BUILTINS[def.id] && (def.skills || def.rules)) {
+    // user-registered: require parent dir or force
+    return false;
+  }
+  return false;
+}
+
+function getBuiltin(id) {
+  return BUILTINS[String(id).toLowerCase()] || null;
+}
+
+function listBuiltinIds() {
+  return Object.keys(BUILTINS).sort();
+}
+
+/**
+ * Merge built-in + machine config harnesses.<id> overrides.
+ * @returns {object} resolved harness definition
+ */
+function resolveHarness(id, cfg, oneShot = {}) {
+  const key = String(id).toLowerCase();
+  const builtin = getBuiltin(key);
+  const overrides = (cfg.machineConfig && cfg.machineConfig.harnesses) || {};
+  const over = overrides[key] || {};
+
+  const base = builtin
+    ? { ...builtin }
+    : {
+        id: key,
+        tier: "C",
+        format: "skills-only",
+        emitter: "full",
+        skills: null,
+        rules: null,
+        unique: true,
+        aliasOf: null,
+        detect: null,
+        custom: true,
+      };
+
+  const skills =
+    oneShot.skills ||
+    over.skills ||
+    base.skills;
+  const rules =
+    oneShot.rules !== undefined
+      ? oneShot.rules
+      : over.rules !== undefined
+        ? over.rules
+        : base.rules;
+  const format =
+    oneShot.format ||
+    over.format ||
+    base.format ||
+    (skills && rules ? "md" : "skills-only");
+
+  const enabled =
+    over.enabled !== undefined
+      ? Boolean(over.enabled)
+      : builtin
+        ? true
+        : true;
+
+  const distId = base.aliasOf || key;
+
+  return {
+    ...base,
+    id: key,
+    skills: skills ? expandHome(skills) : null,
+    rules: rules ? expandHome(rules) : null,
+    skillsRaw: skills || null,
+    rulesRaw: rules || null,
+    format,
+    enabled,
+    distId,
+    override: Boolean(over.skills || over.rules || over.format || over.enabled !== undefined),
+  };
+}
+
+/**
+ * Expand enabled agent list: drop aliases that duplicate canonical, warn.
+ * Filters to installed harnesses unless forceLink.
+ */
+function selectHarnesses(cfg, agentIds, { forceLink = false, includeUninstalled = false } = {}) {
+  const requested = (agentIds && agentIds.length ? agentIds : cfg.agents || ["cursor"]).map(
+    (a) => String(a).trim().toLowerCase()
+  );
+  const seenLive = new Map(); // live skills path -> id
+  const selected = [];
+  const skipped = [];
+  const warnings = [];
+
+  for (const id of requested) {
+    let def;
+    try {
+      def = resolveHarness(id, cfg);
+    } catch (e) {
+      skipped.push({ id, reason: e.message });
+      continue;
+    }
+    if (!def.enabled) {
+      skipped.push({ id, reason: "disabled" });
+      continue;
+    }
+    if (def.emitter === "stub" && !def.skills && !def.rules) {
+      skipped.push({ id, reason: "stub_no_paths" });
+      continue;
+    }
+    if (!includeUninstalled && !isHarnessInstalled(def, { forceLink })) {
+      skipped.push({ id, reason: "not_installed" });
+      continue;
+    }
+    if (def.aliasOf) {
+      warnings.push(`${id} is an alias of ${def.aliasOf}; using dist/${def.distId}`);
+    }
+    const liveKey = def.skills || def.rules || def.id;
+    if (seenLive.has(liveKey)) {
+      warnings.push(
+        `skip ${id}: shares live path with ${seenLive.get(liveKey)} (${liveKey})`
+      );
+      skipped.push({ id, reason: "shared_live_path", with: seenLive.get(liveKey) });
+      continue;
+    }
+    seenLive.set(liveKey, def.distId);
+    selected.push(def);
+  }
+
+  return { selected, skipped, warnings };
+}
+
+function ensureAgentSourceDirs(cfg, harnessId) {
+  const id = harnessId === "codex" ? "agents" : harnessId;
+  const root = path.join(cfg.dir, "agents", id);
+  fs.mkdirSync(path.join(root, "rules"), { recursive: true });
+  fs.mkdirSync(path.join(root, "skills"), { recursive: true });
+  return root;
+}
+
+module.exports = {
+  BUILTINS,
+  getBuiltin,
+  listBuiltinIds,
+  resolveHarness,
+  selectHarnesses,
+  isHarnessInstalled,
+  ensureAgentSourceDirs,
+  which,
+  dirExists,
+};