@dujavi/ai-md 0.6.0 → 0.6.1

package/README.md

@@ -33,11 +33,15 @@ Cursor / Gemini / OpenCode may *also read* `~/.agents/skills`; enabling `agents`
 ```bash
 npm i -g @dujavi/ai-md
 
-# A) No private remote yet
+# A) Existing private git repo (clone/sync first — never skeleton-before-sync)
+ai-md setup --remote https://github.com/<you>/.ai-md.git
+
+# B) No remote yet → local skeleton only
 ai-md init
 
-# B) Existing private git repo
-ai-md setup --remote https://github.com/<you>/.ai-md.git
+# C) Optional auto-detect: if `gh` (or git github.user) identifies you
+#    AND github.com/<user>/.ai-md exists, init/setup use that remote.
+#    There is no hardcoded default remote.
 
 ai-md pull
 # edit shared/ or agents/<id>/ only

package/bin/ai-md.js

@@ -21,6 +21,7 @@ const {
   buildAndLink,
   runBuild,
   runRescue,
+  bootstrapContent,
   seedSkeleton,
   initRepo,
   harnessList,
@@ -253,9 +254,9 @@ Unique sync targets: cursor, claude, gemini, opencode, copilot
 Shared ~/.agents/skills: agents (canonical); codex is an alias
 
 Commands:
-  init               Scaffold skeleton into ~/.ai-md (no remote required)
+  init               Bootstrap ~/.ai-md (clone if remote known, else skeleton)
   seed-skeleton      Add missing recommended files only
-  setup              Persist config + install (+ optional --init / --script)
+  setup              Clone/sync if remote known; --init for skeleton; --script
   config             Show config; config set --remote/--dir/--link-mode
   status             Snapshot (default)
   doctor             Diagnose; --fix rebuilds + relinks (installed AIs only)
@@ -371,6 +372,7 @@ function main() {
               agents: cfg.agents,
               defaultLinkMode: defaultLinkMode(),
               sources: cfg.sources,
+              remoteDetection: cfg.remoteDetection,
             },
           },
           json: opts.json,
@@ -379,32 +381,30 @@ function main() {
         break;
       }
       case "init": {
-        const data = initRepo(cfg, {
+        const data = bootstrapContent(cfg, {
           noGit: opts.noGit,
           force: opts.force,
           dryRun: opts.dryRun,
+          forceLink: opts.forceLink,
+          agents: agentsOrDefault(opts, cfg),
         });
-        writeMachineConfig(
-          { dir: cfg.dir, agents: ["cursor"], linkMode: cfg.linkMode },
-          process.env,
-          { dryRun: opts.dryRun }
-        );
-        cfg = resolveConfig(process.env);
-        let bl = null;
-        if (!opts.dryRun) {
-          bl = buildAndLink(cfg, {
-            agents: ["cursor"],
-            force: true,
-            forceLink: opts.forceLink,
-          });
-        }
+        const help =
+          data.action === "cloned" ||
+          data.action === "synced" ||
+          data.action === "would_clone" ||
+          data.action === "would_replace_and_clone"
+            ? [
+                `Synced from ${data.remote || cfg.remote}`,
+                "Edit shared/ or agents/<id>/; then ai-md build && ai-md push -m \"…\"",
+              ]
+            : [
+                "Skeleton created (no remote).",
+                "Connect later: ai-md setup --remote https://github.com/<you>/.ai-md.git",
+              ];
         emit({
-          data: { init: data, buildLink: bl },
+          data: { init: data },
           json: opts.json,
-          help: [
-            "Edit shared/ or agents/<id>/",
-            "Later: ai-md config set --remote <url> && git -C ~/.ai-md push -u origin main",
-          ],
+          help,
         });
         break;
       }
@@ -517,54 +517,63 @@ function main() {
         break;
       }
       case "setup": {
-        if (opts.init && !opts.remote) {
-          const data = initRepo(cfg, {
+        const remoteCfg = resolveConfig(process.env, {
+          dir: opts.dir || undefined,
+          remote: opts.remote || undefined,
+        });
+        const remote = opts.remote || remoteCfg.remote || null;
+
+        // Explicit skeleton path only when no remote is known
+        if (opts.init && !remote) {
+          const data = bootstrapContent(remoteCfg, {
             noGit: opts.noGit,
             force: opts.force,
             dryRun: opts.dryRun,
+            forceLink: opts.forceLink,
+            agents: agentsOrDefault(opts, remoteCfg),
           });
-          writeMachineConfig(
-            { dir: cfg.dir, agents: ["cursor"], linkMode: cfg.linkMode },
-            process.env,
-            { dryRun: opts.dryRun }
-          );
-          cfg = resolveConfig(process.env);
-          const bl = opts.dryRun
-            ? null
-            : buildAndLink(cfg, {
-                agents: agentsOrDefault(opts, cfg),
-                force: true,
-                forceLink: opts.forceLink,
-              });
           emit({
-            data: { setup: "init", init: data, buildLink: bl },
+            data: { setup: "init", ...data },
             json: opts.json,
             help: [],
           });
           break;
         }
+
+        if (!remote) {
+          fail(
+            "setup needs a remote (or --init for local skeleton).\n" +
+              "  ai-md setup --remote https://github.com/<you>/.ai-md.git\n" +
+              "  ai-md init\n" +
+              "  (auto-detect: authenticate `gh` and create github.com/<user>/.ai-md)",
+            { exitCode: 2, json: opts.json }
+          );
+          process.exit(2);
+        }
+
+        // Remote known → clone/sync first; never seed skeleton before sync
         const saved = writeMachineConfig(
           {
-            dir: opts.dir || cfg.dir,
-            remote: opts.remote || cfg.remote,
-            agents: opts.agents || cfg.agents,
-            linkMode: opts.linkMode || cfg.linkMode,
+            dir: opts.dir || remoteCfg.dir,
+            remote,
+            agents: opts.agents || remoteCfg.agents,
+            linkMode: opts.linkMode || remoteCfg.linkMode,
           },
           process.env,
           { dryRun: opts.dryRun }
         );
         cfg = resolveConfig(process.env, {
           dir: opts.dir || undefined,
-          remote: opts.remote || undefined,
+          remote,
+          skipRemoteDetect: true,
         });
         applyEnvFromConfig(cfg);
-        const result = opts.dryRun
-          ? { build: null, link: null }
-          : runInstall(cfg, {
-              agents: agentsOrDefault(opts, cfg),
-              force: opts.force,
-              forceLink: opts.forceLink,
-            });
+        const result = bootstrapContent(cfg, {
+          force: opts.force,
+          dryRun: opts.dryRun,
+          forceLink: opts.forceLink,
+          agents: agentsOrDefault(opts, cfg),
+        });
         const scripts =
           opts.scripts.length === 0
             ? []
@@ -578,7 +587,7 @@ function main() {
           from: opts.from,
         });
         emit({
-          data: { setup: "ok", config: saved, ...result, scripts, ...data },
+          data: { setup: "ok", config: saved, result, scripts, ...data },
           json: opts.json,
           help: statusHelp(data),
         });

package/lib/commands.js

@@ -22,7 +22,7 @@ const {
   ensureAgentSourceDirs,
   isHarnessInstalled,
 } = require("./harnesses");
-const { seedSkeleton, initRepo, SKELETON_VERSION } = require("./skeleton");
+const { seedSkeleton, initRepo, SKELETON_VERSION, isEmptyDir } = require("./skeleton");
 
 function ensureGitignore(repoPath, { dryRun = false } = {}) {
   const gitignore = path.join(repoPath, ".gitignore");
@@ -259,16 +259,39 @@ function buildAndLink(cfg, opts = {}) {
 
 function runInstall(cfg, opts = {}) {
   const dir = cfg.dir;
-  if (!fs.existsSync(dir)) {
+  const empty = !fs.existsSync(dir) || isEmptyDir(dir);
+
+  if (empty) {
+    if (!cfg.remote) {
+      const err = new Error(
+        "No remote configured and content dir is empty.\n" +
+          "  ai-md init                 # skeleton only (no remote)\n" +
+          "  ai-md setup --remote <url> # clone existing github.com/<user>/.ai-md"
+      );
+      err.code = "EINVAL";
+      throw err;
+    }
+    if (fs.existsSync(dir) && isEmptyDir(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
     gitClone(cfg.remote, dir, { dryRun: opts.dryRun });
+    if (!opts.dryRun) {
+      seedSkeleton(cfg, { force: false });
+    }
   } else if (!fs.existsSync(path.join(dir, ".git"))) {
     const err = new Error(
-      `${dir} exists but is not a git repo. Use ai-md init or remove it.`
+      `${dir} exists but is not a git repo. Move it aside, then: ai-md setup --remote <url>`
     );
     err.code = "EEXIST";
     throw err;
+  } else if (cfg.remote && opts.pull !== false) {
+    try {
+      gitPull(cfg.dir, { dryRun: opts.dryRun });
+    } catch {
+      /* offline / no upstream — continue with local tree */
+    }
   }
-  // migrate hint: if legacy flat rules/ exist, status will note
+
   return buildAndLink(cfg, {
     agents: opts.agents,
     force: opts.force,
@@ -277,6 +300,111 @@ function runInstall(cfg, opts = {}) {
   });
 }
 
+/**
+ * Bootstrap: remote set → clone/sync first (never skeleton-first).
+ * No remote → seed skeleton only.
+ */
+function bootstrapContent(cfg, opts = {}) {
+  const {
+    noGit = false,
+    force = false,
+    dryRun = false,
+    forceLink = false,
+    agents = ["cursor"],
+  } = opts;
+
+  if (cfg.remote) {
+    const dir = cfg.dir;
+    const exists = fs.existsSync(dir);
+    const empty = !exists || isEmptyDir(dir);
+    const isGit = exists && fs.existsSync(path.join(dir, ".git"));
+
+    if (!empty && isGit) {
+      if (!dryRun) {
+        writeMachineConfig({
+          dir: cfg.dir,
+          remote: cfg.remote,
+          agents,
+          linkMode: cfg.linkMode,
+        });
+      }
+      return {
+        action: "synced",
+        remote: cfg.remote,
+        dir,
+        ...runInstall(cfg, {
+          agents,
+          force,
+          dryRun,
+          forceLink,
+          pull: true,
+        }),
+      };
+    }
+
+    if (!empty && !isGit) {
+      if (!force) {
+        const err = new Error(
+          `${dir} is not empty and has no .git.\n` +
+            `  mv ${dir} ${dir}.bak && ai-md setup --remote ${cfg.remote}\n` +
+            `  (refusing to seed skeleton before sync when a remote is set)`
+        );
+        err.code = "EEXIST";
+        throw err;
+      }
+      if (dryRun) {
+        return { action: "would_replace_and_clone", remote: cfg.remote, dir };
+      }
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+
+    if (dryRun) {
+      return { action: "would_clone", remote: cfg.remote, dir };
+    }
+    if (fs.existsSync(dir) && isEmptyDir(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+    gitClone(cfg.remote, dir, { dryRun: false });
+    // After clone only — fill gaps; never invent a tree instead of syncing
+    seedSkeleton(cfg, { force: false });
+    writeMachineConfig({
+      dir: cfg.dir,
+      remote: cfg.remote,
+      agents,
+      linkMode: cfg.linkMode,
+    });
+    const fresh = resolveConfig(process.env, {
+      dir: cfg.dir,
+      remote: cfg.remote,
+      skipRemoteDetect: true,
+    });
+    return {
+      action: "cloned",
+      remote: cfg.remote,
+      dir,
+      ...buildAndLink(fresh, { agents, force: true, forceLink }),
+    };
+  }
+
+  const data = initRepo(cfg, { noGit, force, dryRun });
+  if (!dryRun) {
+    writeMachineConfig({
+      dir: cfg.dir,
+      agents,
+      linkMode: cfg.linkMode,
+    });
+  }
+  const fresh = resolveConfig(process.env, {
+    dir: cfg.dir,
+    skipRemoteDetect: true,
+  });
+  let bl = null;
+  if (!dryRun) {
+    bl = buildAndLink(fresh, { agents, force: true, forceLink });
+  }
+  return { action: "initialized", init: data, buildLink: bl };
+}
+
 function runPull(cfg, opts = {}) {
   if (!fs.existsSync(path.join(cfg.dir, ".git"))) {
     const err = new Error(`${cfg.dir} is not a git repo; run ai-md install`);
@@ -443,6 +571,7 @@ module.exports = {
   runRescue,
   seedSkeleton,
   initRepo,
+  bootstrapContent,
   harnessList,
   harnessShow,
   harnessSet,

package/lib/config.js

@@ -4,8 +4,10 @@ const fs = require("fs");
 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 machineConfigPath(env = process.env) {
   if (env.AI_MD_CONFIG) return expandHome(env.AI_MD_CONFIG);
@@ -67,7 +69,24 @@ function resolveConfig(env = process.env, opts = {}) {
   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;
+
+  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
@@ -77,13 +96,7 @@ 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 || {};
@@ -98,6 +111,7 @@ function resolveConfig(env = process.env, opts = {}) {
     dir,
     remote,
     sources,
+    remoteDetection,
     agents,
     linkMode,
     machineConfigPath: stored.path,
@@ -118,9 +132,17 @@ function resolveConfig(env = process.env, opts = {}) {
 
 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") {
@@ -201,6 +223,13 @@ function migrateLegacyTemplate(cfg, { dryRun = false } = {}) {
 }
 
 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" });

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

@@ -184,8 +184,11 @@ function collectStatus(opts = {}) {
   return {
     generatedAt: new Date().toISOString(),
     dir: cfg.dir,
-    remote: remote || cfg.remote,
+    remote: remote || cfg.remote || null,
+    configuredRemote: cfg.remote || null,
+    gitRemote: remote,
     sources: cfg.sources,
+    remoteDetection: cfg.remoteDetection,
     linkMode: cfg.linkMode,
     wsl: isWsl(),
     machineConfigPath: cfg.machineConfigPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dujavi/ai-md",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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"

package/scripts/sync-config.sh

@@ -4,7 +4,7 @@
 set -euo pipefail
 
 REPO="${AI_MD_DIR:-${CURSOR_MD_DIR:-$HOME/.ai-md}}"
-REMOTE_URL="${AI_MD_REMOTE:-${CURSOR_MD_REMOTE:-https://github.com/dujavi/.ai-md.git}}"
+REMOTE_URL="${AI_MD_REMOTE:-${CURSOR_MD_REMOTE:-}}"
 DRY_RUN=0
 FORCE=0
 COMMIT_MSG="Update personal AI skills/rules"
@@ -32,10 +32,10 @@ Options:
 
 Environment:
   AI_MD_DIR     Private config path (default: ~/.ai-md)
-  AI_MD_REMOTE  Clone URL if repo missing (default: https://github.com/dujavi/.ai-md.git)
+  AI_MD_REMOTE  Clone URL if repo missing (required for install clone; no hardcoded default)
 
 Examples:
-  ai-md install
+  AI_MD_REMOTE=https://github.com/<you>/.ai-md.git ai-md install
   ai-md pull
   ai-md push -m "Add grafana rule"
   ai-md status
@@ -82,6 +82,13 @@ clone_if_missing() {
   fi
   if [[ -d "$REPO" ]] && [[ -n "$(ls -A "$REPO" 2>/dev/null || true)" ]]; then
     err "$REPO exists but is not a git repo (and is not empty)"
+    err "  Move it aside, then clone — do not seed a skeleton over an unsynced remote tree"
+    exit 1
+  fi
+  if [[ -z "$REMOTE_URL" ]]; then
+    err "No remote set and $REPO is missing/empty."
+    err "  export AI_MD_REMOTE=https://github.com/<you>/.ai-md.git"
+    err "  or: ai-md setup --remote <url>   /   ai-md init"
     exit 1
   fi
   log "Cloning $REMOTE_URL → $REPO"