@dujavi/ai-md 0.5.0 → 0.6.1

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,70 @@ 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,
+    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,
     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 +225,8 @@ function collectStatus(opts = {}) {
     templates,
     projects,
     driftFrom: from,
+    skeletonVersion,
+    packageSkeletonVersion: SKELETON_VERSION,
     problems,
   };
 }
@@ -177,7 +235,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 +248,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.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"
   },
@@ -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"

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"

package/skeleton/README.md

@@ -0,0 +1,3 @@
+# Your private AI config
+
+Edit `shared/` and `agents/<id>/` only. Run `ai-md build` after changes.

package/skeleton/shared/rules/edit-source-not-dist.mdc

@@ -0,0 +1,23 @@
+---
+description: Edit ~/.ai-md shared/ and agents/ only — never live harness dirs or dist/
+alwaysApply: true
+---
+
+# Edit source, not dist or live harness paths
+
+`~/.ai-md` is the source of truth. Live tool dirs (`~/.cursor`, `~/.claude`, `~/.agents`, …) and `~/.ai-md/dist/` are **build outputs**.
+
+## Do
+
+- Edit `~/.ai-md/shared/` for rules/skills that apply to all harnesses.
+- Edit `~/.ai-md/agents/<harness>/` for harness-specific rules/skills.
+- After edits: `ai-md build` (or `ai-md pull` / `install`, which rebuild).
+
+## Do not
+
+- Edit `~/.cursor/{rules,skills}`, `~/.claude/…`, `~/.agents/…`, or any other live harness path.
+- Edit `~/.ai-md/dist/` directly.
+
+## If you already edited a live path
+
+Stop. Run `ai-md rescue --agents <harness>` to promote dirty files into `agents/<harness>/`, then review and `ai-md build`. Do not keep iterating under dist or live dirs.

package/skeleton/shared/rules/personal-config.mdc

@@ -0,0 +1,49 @@
+---
+description: Sync global personal skills and rules via ~/.ai-md and the ai-md CLI (build → dist → link)
+alwaysApply: true
+---
+
+# Personal skills and rules — ai-md
+
+**`~/.ai-md`** is the private source of truth. Use **`ai-md`** (`@dujavi/ai-md`) — not Cursor Sync / Gist.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `shared/rules`, `shared/skills` | System base for all harnesses |
+| `agents/<id>/` | Harness-specific overlays |
+| `dist/<id>/` | Build output (gitignored) — do not edit |
+| `templates/<type>/` | Project-type starters |
+| `projects/<name>/` | Per-app overlays |
+| `scripts/` | Private machine scripts |
+
+See also `edit-source-not-dist.mdc` and skill `ai-md-config`.
+
+## Sync
+
+```bash
+ai-md pull
+# edit shared/ or agents/<id>/
+ai-md build
+ai-md push -m "why"
+```
+
+`install` / `pull` / `doctor --fix` rebuild and link **only for installed AIs** (detect `~/.cursor`, `claude` on PATH, etc.). Use `--force-link` to override.
+
+## Where to edit
+
+| What | Edit here |
+|------|-----------|
+| Cross-harness rules/skills | `~/.ai-md/shared/` |
+| Cursor-only (e.g. Grok CLI policy) | `~/.ai-md/agents/cursor/` |
+| Project starters | `~/.ai-md/templates/<type>/` |
+| App overlays | `~/.ai-md/projects/<repo>/` |
+
+Never edit `~/.cursor/skills-cursor/`, live harness dirs, or `dist/`.
+
+## Agent behavior
+
+- Global changes → `shared/` or `agents/<id>/`; remind `ai-md build` then `push`.
+- Symlink / dist issues → `ai-md doctor --fix` or `ai-md rescue`.
+- New harness → `ai-md harness set …` then content under `agents/<id>/`.

package/skeleton/shared/skills/ai-md-config/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ai-md-config
+description: >-
+  Manage personal AI config in ~/.ai-md: shared vs agents layers, build/dist,
+  harness registration, rescue dirty dist. Use when adding rules/skills, fixing
+  links, or supporting a new AI tool.
+---
+
+# ai-md config playbook
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `shared/rules`, `shared/skills` | All harnesses |
+| `agents/<id>/rules`, `agents/<id>/skills` | One harness (overlay wins on name conflict) |
+| `dist/<id>/` | Generated — never edit |
+| `projects/<name>/` | Per-repo overlays (`.cursor` → here) |
+
+## Commands
+
+```bash
+ai-md pull / push -m "why"
+ai-md build [--agents cursor,claude] [--force]
+ai-md rescue --agents cursor
+ai-md harness list | show <id>
+ai-md harness set <id> --skills ~/path [--rules ~/path] [--format mdc|md|skills-only]
+ai-md harness enable|disable <id>
+ai-md init | seed-skeleton
+ai-md doctor --fix
+```
+
+## Add a rule or skill
+
+1. Choose layer: `shared/` (all tools) vs `agents/<id>/` (one tool).
+2. Write the file under that path (never under `dist/` or `~/.cursor/…`).
+3. `ai-md build`
+4. `ai-md push -m "…"` when ready.
+
+## New harness
+
+```bash
+ai-md harness set my-tool --skills ~/.my-tool/skills --rules ~/.my-tool/rules --format md
+# put tool-specific content in agents/my-tool/
+ai-md build --agents my-tool
+```
+
+## Unique vs shared `.agents`
+
+- Unique live roots: `cursor`, `claude`, `gemini`, `opencode`, `copilot`
+- Shared `~/.agents/skills`: `agents` (canonical writer); `codex` is an alias (no second emit)

package/skeleton/templates/base/rules/project-context.mdc

@@ -0,0 +1,8 @@
+---
+description: Project-specific context — customize after init-project
+alwaysApply: true
+---
+
+# Project context
+
+Replace this stub with stack, phase gates, and doc index for this app.