@dujavi/ai-md 0.4.0 → 0.6.0

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,67 @@ 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,
     sources: cfg.sources,
+    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 +222,8 @@ function collectStatus(opts = {}) {
     templates,
     projects,
     driftFrom: from,
+    skeletonVersion,
+    packageSkeletonVersion: SKELETON_VERSION,
     problems,
   };
 }
@@ -177,7 +232,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 +245,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.4.0",
-  "description": "AXI-shaped CLI for ~/.ai-md with persisted dir/remote machine config, templates/, and projects/",
+  "version": "0.6.0",
+  "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,8 @@
     "bin/",
     "lib/",
     "scripts/",
+    "skeleton/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],
@@ -16,20 +18,22 @@
     "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"
   },
   "keywords": [
+    "axi",
     "cursor",
-    "ai",
+    "claude",
+    "agents",
     "skills",
     "rules",
-    "quota-axi",
-    "grok",
+    "personal-config",
     "cli",
-    "axi"
+    "toon",
+    "ai-md"
   ],
   "author": "dujavi",
   "license": "MIT",

package/scripts/sync-config.sh

@@ -22,7 +22,7 @@ Commands:
   status    Show repo state, symlink health, and rule/skill counts
   doctor    Diagnose problems; with --fix, repair symlinks
 
-Also: ai-md ensure-tools  (grok + quota-axi)
+Private scripts: ai-md script <name>  (from ~/.ai-md/scripts/)
 
 Options:
   -m, --message <msg>  Commit message for push (default: generic update)
@@ -146,7 +146,7 @@ cmd_install() {
   log "Install complete."
   log "  rules:  $(count_rules)"
   log "  skills: $(count_skills)"
-  log "Next: ai-md ensure-tools  # grok + quota-axi"
+  log "Next: ai-md script <name>  # private ~/.ai-md/scripts/"
 }
 
 cmd_pull() {

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.

package/scripts/ensure-agent-tools.sh

@@ -1,114 +0,0 @@
-#!/usr/bin/env bash
-# Ensure Grok Build CLI + quota-axi are installed on this machine.
-# Safe to re-run (idempotent). Does not print secrets.
-set -euo pipefail
-
-DRY_RUN=0
-
-usage() {
-  cat <<'EOF'
-Usage: ensure-agent-tools.sh [--dry-run]
-
-Installs or updates:
-  - grok   (Grok Build CLI) via https://x.ai/cli/install.sh
-  - quota-axi via volta (if present) or npm -g
-
-Then prints version + auth/quota smoke checks (no secrets).
-EOF
-}
-
-log() { printf '%s\n' "$*"; }
-err() { printf 'error: %s\n' "$*" >&2; }
-run() {
-  if [[ "$DRY_RUN" -eq 1 ]]; then
-    log "dry-run: $*"
-  else
-    "$@"
-  fi
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --dry-run) DRY_RUN=1; shift ;;
-    -h|--help|help) usage; exit 0 ;;
-    *) err "unknown argument: $1"; usage; exit 1 ;;
-  esac
-done
-
-ensure_path_hint() {
-  local need=0
-  case ":$PATH:" in
-    *":$HOME/.local/bin:"*) ;;
-    *) need=1; log "note: add \$HOME/.local/bin to PATH" ;;
-  esac
-  case ":$PATH:" in
-    *":$HOME/.grok/bin:"*) ;;
-    *) need=1; log "note: add \$HOME/.grok/bin to PATH (grok installer usually does)" ;;
-  esac
-  return 0
-}
-
-install_grok() {
-  if command -v grok >/dev/null 2>&1; then
-    log "grok present: $(grok --version 2>/dev/null || echo unknown)"
-    log "Updating grok via official installer…"
-  else
-    log "Installing grok via official installer…"
-  fi
-  if [[ "$DRY_RUN" -eq 1 ]]; then
-    log "dry-run: curl -fsSL https://x.ai/cli/install.sh | bash"
-    return 0
-  fi
-  curl -fsSL https://x.ai/cli/install.sh | bash
-}
-
-install_quota_axi() {
-  if command -v quota-axi >/dev/null 2>&1; then
-    log "quota-axi present: $(quota-axi --version 2>/dev/null || echo unknown)"
-  else
-    log "Installing quota-axi…"
-  fi
-  if command -v volta >/dev/null 2>&1; then
-    run volta install quota-axi
-  elif command -v npm >/dev/null 2>&1; then
-    run npm install -g quota-axi
-  else
-    err "Need volta or npm to install quota-axi"
-    return 1
-  fi
-}
-
-smoke() {
-  log ""
-  log "=== smoke checks ==="
-  if command -v grok >/dev/null 2>&1; then
-    log "grok: $(command -v grok)"
-    grok --version 2>&1 || true
-    if [[ -f "$HOME/.grok/auth.json" ]]; then
-      log "grok auth: ~/.grok/auth.json present"
-    else
-      log "grok auth: missing — run \`grok\` (browser) or set XAI_API_KEY"
-    fi
-  else
-    err "grok not on PATH after install"
-  fi
-
-  if command -v quota-axi >/dev/null 2>&1; then
-    log "quota-axi: $(command -v quota-axi)"
-    quota-axi auth 2>&1 || true
-    quota-axi --provider grok 2>&1 || true
-  else
-    err "quota-axi not on PATH after install"
-  fi
-
-  if ! command -v sqlite3 >/dev/null 2>&1; then
-    log "note: sqlite3 not found — Cursor quota via quota-axi may fail (install sqlite3)"
-  fi
-}
-
-ensure_path_hint
-install_grok
-install_quota_axi
-smoke
-log ""
-log "Done. Re-run anytime; pair with: ai-md install"