@dujavi/ai-md 0.1.0 → 0.3.0

package/README.md

@@ -1,53 +1,49 @@
 # ai-md
 
-Public CLI for syncing a **private** personal AI config directory (`~/.ai-md`) and installing agent CLIs.
+Public **AXI-shaped** CLI for a **private** personal AI config directory (`~/.ai-md`).
 
-| Layer | What | Where |
-|-------|------|--------|
-| **Public** | This package (`ai-md`) — sync/link/ensure-tools scripts only | npm + [github.com/dujavi/ai-md](https://github.com/dujavi/ai-md) |
-| **Private** | Your skills, rules, projects | `~/.ai-md` git repo (e.g. `github.com/<you>/.ai-md`) |
+| Layer | Path | Purpose |
+|-------|------|---------|
+| **System** | `skills/`, `rules/` | Global base — linked to `~/.cursor/{skills,rules}` |
+| **Templates** | `templates/<type>/` | Project-type starters (`base`, later `forms`, …) |
+| **Projects** | `projects/<name>/` | Per-app overlays (repo `.cursor` → here) |
 
-No personal rules or skills ship in this package.
+No personal content ships in this package. Reads default to TOON + `help[]` (`--json` available).
 
 ## Install
 
 ```bash
 npm i -g @dujavi/ai-md
-# or one-shot:
-npx @dujavi/ai-md --help
 ```
 
-## New machine
-
-```bash
-npm i -g @dujavi/ai-md
-export AI_MD_REMOTE=https://github.com/<you>/.ai-md.git   # your private content repo
-ai-md install
-ai-md ensure-tools   # grok + quota-axi
+## Layout idea
+
+```text
+~/.ai-md/
+  skills/                 # system — all agents see these
+  rules/
+  templates/
+    base/                 # default project starter (customizable stubs only)
+    # forms/ …            # other use cases
+  projects/
+    presenter/
+    sendfolio/
 ```
 
-Defaults (override with env):
-
-- `AI_MD_DIR` → `~/.ai-md`
-- `AI_MD_REMOTE` → `https://github.com/dujavi/.ai-md.git`
+Put shared agentic skills/rules in **system** folders. Put only type-specific or per-project starters under **templates/**.
 
 ## Commands
 
 ```bash
-ai-md install
-ai-md pull
-ai-md push -m "why"
-ai-md status
-ai-md doctor --fix
-ai-md ensure-tools          # alias: tools
-ai-md link-project --repo ~/my-app
+ai-md                                      # status
+ai-md init-project --repo ~/app --from base
+ai-md apply-template --project app --from base
+ai-md doctor --fix --agents cursor,claude
+ai-md pull | push -m "why"
+ai-md ensure-tools
 ```
 
-`install` / `pull` / `doctor` keep:
-
-- `~/.cursor/skills` → `$AI_MD_DIR/skills`
-- `~/.cursor/rules` → `$AI_MD_DIR/rules`
+## Environment
 
-## Agent-friendly
-
-Non-interactive flags only (`--dry-run`, `--force`, `--fix`, `-m`). No prompts. Prefer `npx -y @dujavi/ai-md <cmd>` when not installed globally.
+- `AI_MD_DIR` → `~/.ai-md`
+- `AI_MD_REMOTE` → private content git URL

package/bin/ai-md.js

@@ -2,98 +2,329 @@
 "use strict";
 
 const { spawnSync } = require("child_process");
-const os = require("os");
 const path = require("path");
+const { resolveConfig } = require("../lib/config");
+const { emit, fail } = require("../lib/output");
+const { collectStatus, statusHelp } = require("../lib/status");
+const {
+  initProject,
+  applyTemplate,
+  linkProject,
+  runDoctor,
+  ensureCursorLinks,
+  ensureAgentSkillLinks,
+} = require("../lib/commands");
 
 const scriptsDir = path.join(__dirname, "..", "scripts");
-const home = os.homedir();
+const cfg = resolveConfig();
 
-const env = {
-  ...process.env,
-  AI_MD_DIR:
-    process.env.AI_MD_DIR ||
-    process.env.CURSOR_MD_DIR ||
-    path.join(home, ".ai-md"),
-  AI_MD_REMOTE:
-    process.env.AI_MD_REMOTE ||
-    process.env.CURSOR_MD_REMOTE ||
-    "https://github.com/dujavi/.ai-md.git",
-};
+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;
 
-// Keep legacy env names in sync for older wrappers.
-env.CURSOR_MD_DIR = env.AI_MD_DIR;
-env.CURSOR_MD_REMOTE = env.AI_MD_REMOTE;
-
-const COMMANDS = {
-  install: { script: "sync-config.sh", prefix: ["install"] },
-  pull: { script: "sync-config.sh", prefix: ["pull"] },
-  push: { script: "sync-config.sh", prefix: ["push"] },
-  status: { script: "sync-config.sh", prefix: ["status"] },
-  doctor: { script: "sync-config.sh", prefix: ["doctor"] },
-  "ensure-tools": { script: "ensure-agent-tools.sh", prefix: [] },
-  tools: { script: "ensure-agent-tools.sh", prefix: [] },
-  "link-project": { script: "link-project.sh", prefix: [] },
-  link: { script: "link-project.sh", prefix: [] },
-};
+function parseArgs(argv) {
+  const out = {
+    cmd: null,
+    json: false,
+    full: false,
+    force: false,
+    dryRun: false,
+    fix: false,
+    message: null,
+    repo: null,
+    name: null,
+    project: null,
+    from: "base",
+    agents: ["cursor"],
+    rest: [],
+  };
+  const args = [...argv];
+  if (args.length === 0) {
+    out.cmd = "status";
+    return out;
+  }
+  const first = args[0];
+  if (first === "-h" || first === "--help" || first === "help") {
+    out.cmd = "help";
+    return out;
+  }
+  if (first.startsWith("-")) {
+    // flags before command → treat as status with flags
+    out.cmd = "status";
+  } else {
+    out.cmd = args.shift();
+  }
+  while (args.length) {
+    const a = args.shift();
+    switch (a) {
+      case "--json":
+        out.json = true;
+        break;
+      case "--full":
+        out.full = true;
+        break;
+      case "--force":
+        out.force = true;
+        break;
+      case "--dry-run":
+        out.dryRun = true;
+        break;
+      case "--fix":
+        out.fix = true;
+        out.force = true;
+        break;
+      case "-m":
+      case "--message":
+        out.message = args.shift();
+        break;
+      case "--repo":
+        out.repo = args.shift();
+        break;
+      case "--name":
+        out.name = args.shift();
+        break;
+      case "--project":
+        out.project = args.shift();
+        break;
+      case "--from":
+        out.from = args.shift();
+        break;
+      case "--agents":
+        out.agents = String(args.shift() || "cursor")
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+        break;
+      case "-h":
+      case "--help":
+        out.cmdHelp = true;
+        break;
+      default:
+        if (a.startsWith("-")) {
+          fail(`unknown flag: ${a}`, {
+            exitCode: 2,
+            json: out.json,
+            help: ["Run `ai-md --help`"],
+          });
+          process.exit(2);
+        }
+        out.rest.push(a);
+        break;
+    }
+  }
+  return out;
+}
 
 function printHelp() {
-  console.log(`ai-md — sync private ~/.ai-md skills/rules; install agent CLIs
+  process.stdout.write(`ai-md — private ~/.ai-md: system skills/rules + templates/ + projects/ (AXI-shaped)
 
 Usage:
-  ai-md <command> [options]
-  npx @dujavi/ai-md <command> [options]
+  ai-md [command] [options]
+  npx -y @dujavi/ai-md [command] [options]
+
+Layout:
+  ~/.ai-md/skills, rules     System (global) base — linked to ~/.cursor
+  ~/.ai-md/templates/<type>  Project-type starters (default: base)
+  ~/.ai-md/projects/<name>   Per-app overlays (repo .cursor → here)
 
 Commands:
-  install          Clone AI_MD_REMOTE → ~/.ai-md (if needed); link ~/.cursor/{skills,rules}
-  pull             git pull private config; refresh symlinks
-  push             commit + push private config (-m/--message)
-  status           repo + symlink health
-  doctor           diagnose; --fix repairs symlinks
-  ensure-tools     install/update grok + quota-axi (alias: tools)
-  link-project     link a repo .cursor/ → ~/.ai-md/projects/<name>/
-  help             show this help
+  status             Snapshot (default when no command) [AXI]
+  doctor             Diagnose links/projects; --fix repairs
+  install            Clone remote if needed; link ~/.cursor + optional agents
+  pull | push        Sync private git repo
+  ensure-tools       Install/update grok + quota-axi (alias: tools)
+  init-project       Seed projects/<name> from templates/<from> + link .cursor/
+  apply-template     Merge missing files from a template into a project
+  link-project       Link repo .cursor/ without seeding (alias: link)
+  help               Show this help
 
-Environment:
-  AI_MD_DIR        Private config dir (default: ~/.ai-md)
-  AI_MD_REMOTE     Git remote if clone needed (default: https://github.com/dujavi/.ai-md.git)
+Options:
+  --json             JSON instead of TOON (status/doctor/init/…)
+  --full             Include paths and drift details
+  --agents <list>    Skill link targets: cursor,claude,agents (default: cursor)
+  --repo <path>      App repository root
+  --name <id>        Project id under projects/ (default: basename)
+  --project <id>     Target project for apply-template
+  --from <id>        Template under templates/ (default: base)
+  --force            Replace non-symlink .cursor / re-merge
+  --dry-run          Preview without writing
+  --fix             doctor: repair symlinks
+  -m, --message      push commit message
 
 Examples:
-  npm i -g @dujavi/ai-md
-  ai-md install
-  ai-md ensure-tools
-  ai-md pull
-  ai-md push -m "Add routing rule"
-  ai-md link-project --repo ~/presenter
-  ai-md doctor --fix
-
-Private skills/rules live in each person's AI_MD_DIR repo.
-This package ships tooling only — no personal content.
+  ai-md
+  ai-md status --json
+  ai-md init-project --repo ~/presenter --from base
+  ai-md apply-template --project presenter --from base
+  ai-md doctor --fix --agents cursor,claude
 `);
 }
 
-const [cmd, ...args] = process.argv.slice(2);
-
-if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
-  printHelp();
-  process.exit(0);
+function runBash(script, args) {
+  const result = spawnSync("bash", [path.join(scriptsDir, script), ...args], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.error) {
+    fail(result.error.message, { exitCode: 1 });
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
 }
 
-const mapped = COMMANDS[cmd];
-if (!mapped) {
-  console.error(`error: unknown command: ${cmd}`);
-  console.error(`  ai-md --help`);
-  process.exit(2);
-}
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
 
-const scriptPath = path.join(scriptsDir, mapped.script);
-const result = spawnSync("bash", [scriptPath, ...mapped.prefix, ...args], {
-  stdio: "inherit",
-  env,
-});
+  if (opts.cmd === "help" || opts.cmdHelp) {
+    printHelp();
+    return;
+  }
 
-if (result.error) {
-  console.error(`error: failed to run ${mapped.script}: ${result.error.message}`);
-  process.exit(1);
+  try {
+    switch (opts.cmd) {
+      case "status": {
+        const data = collectStatus({
+          full: opts.full,
+          agents: opts.agents,
+          from: opts.from,
+        });
+        emit({ data, json: opts.json, help: statusHelp(data) });
+        process.exitCode = data.counts.problems > 0 ? 1 : 0;
+        break;
+      }
+      case "doctor": {
+        const data = runDoctor({
+          fix: opts.fix,
+          force: opts.force,
+          agents: opts.agents,
+          dryRun: opts.dryRun,
+        });
+        emit({
+          data,
+          json: opts.json,
+          help: data.help,
+        });
+        process.exitCode = data.after.problems.length > 0 ? 1 : 0;
+        break;
+      }
+      case "init-project": {
+        const data = initProject({
+          repo: opts.repo,
+          name: opts.name,
+          from: opts.from,
+          force: opts.force,
+          dryRun: opts.dryRun,
+        });
+        emit({
+          data,
+          json: opts.json,
+          help: [
+            "Customize rules/agentic-workflow.mdc for this project",
+            'Run `ai-md push -m "Init <project>"` after reviewing the private repo diff',
+          ],
+        });
+        break;
+      }
+      case "apply-template": {
+        const data = applyTemplate({
+          project: opts.project || opts.name,
+          from: opts.from,
+          dryRun: opts.dryRun,
+        });
+        emit({
+          data,
+          json: opts.json,
+          help: [
+            "Review added files under ~/.ai-md/projects/<name>/",
+            'Run `ai-md push -m "Apply template to <project>"` when ready',
+          ],
+        });
+        break;
+      }
+      case "link-project":
+      case "link": {
+        const data = linkProject({
+          repo: opts.repo,
+          name: opts.name,
+          force: opts.force,
+          dryRun: opts.dryRun,
+        });
+        emit({
+          data,
+          json: opts.json,
+          help: [
+            "Prefer `ai-md init-project --repo <path>` to seed from template first",
+          ],
+        });
+        break;
+      }
+      case "install": {
+        // clone/pull via bash, then Node links (incl. agents)
+        const bashArgs = ["install"];
+        if (opts.force) bashArgs.push("--force");
+        if (opts.dryRun) bashArgs.push("--dry-run");
+        const result = spawnSync(
+          "bash",
+          [path.join(scriptsDir, "sync-config.sh"), ...bashArgs],
+          { stdio: "inherit", env: process.env }
+        );
+        if (result.status !== 0) {
+          process.exit(result.status === null ? 1 : result.status);
+        }
+        const links = [
+          ...ensureCursorLinks(cfg, { force: opts.force, dryRun: opts.dryRun }),
+          ...ensureAgentSkillLinks(cfg, opts.agents, {
+            force: opts.force,
+            dryRun: opts.dryRun,
+          }),
+        ];
+        const data = collectStatus({ full: opts.full, agents: opts.agents });
+        emit({
+          data: { install: "ok", links, ...data },
+          json: opts.json,
+          help: [
+            "Run `ai-md ensure-tools` to install grok + quota-axi",
+            "Run `ai-md init-project --repo <path>` for a new app",
+          ],
+        });
+        break;
+      }
+      case "pull":
+        runBash("sync-config.sh", [
+          "pull",
+          ...(opts.dryRun ? ["--dry-run"] : []),
+        ]);
+        break;
+      case "push": {
+        const args = ["push"];
+        if (opts.message) args.push("-m", opts.message);
+        if (opts.dryRun) args.push("--dry-run");
+        runBash("sync-config.sh", args);
+        break;
+      }
+      case "ensure-tools":
+      case "tools":
+        runBash("ensure-agent-tools.sh", [
+          ...(opts.dryRun ? ["--dry-run"] : []),
+        ]);
+        break;
+      default:
+        fail(`unknown command: ${opts.cmd}`, {
+          exitCode: 2,
+          json: opts.json,
+          help: ["Run `ai-md --help`"],
+        });
+        process.exit(2);
+    }
+  } catch (err) {
+    fail(err.message || String(err), {
+      exitCode: err.code === "EINVAL" ? 2 : 1,
+      json: opts.json,
+      help: ["Run `ai-md --help`"],
+    });
+    process.exit(process.exitCode || 1);
+  }
 }
 
-process.exit(result.status === null ? 1 : result.status);
+main();

package/lib/commands.js

@@ -0,0 +1,262 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  resolveConfig,
+  templatePath,
+  symlinkState,
+  agentSkillTargets,
+} = require("./config");
+const { collectStatus, statusHelp, collectProjects } = require("./status");
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function linkPath(target, link, { force = false, dryRun = false } = {}) {
+  ensureDir(path.dirname(link));
+  ensureDir(target);
+  const state = symlinkState(link, target);
+  if (state.state === "ok") {
+    return { path: link, action: "ok", target };
+  }
+  if (state.state === "not_symlink" && !force) {
+    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 };
+  }
+  if (fs.existsSync(link) || state.state !== "missing") {
+    try {
+      fs.lstatSync(link);
+      fs.rmSync(link, { recursive: true, force: true });
+    } catch {
+      /* missing */
+    }
+  }
+  fs.symlinkSync(target, link);
+  return {
+    path: link,
+    action: state.state === "missing" ? "linked" : "repaired",
+    target,
+  };
+}
+
+function ensureCursorLinks(cfg, opts = {}) {
+  return [
+    linkPath(cfg.skillsDir, cfg.cursorSkills, opts),
+    linkPath(cfg.rulesDir, cfg.cursorRules, opts),
+  ];
+}
+
+function ensureAgentSkillLinks(cfg, agents, opts = {}) {
+  return agentSkillTargets(cfg.home, agents)
+    .filter((t) => t.name !== "cursor") // cursor handled via ensureCursorLinks
+    .map((t) => linkPath(cfg.skillsDir, t.path, opts));
+}
+
+function ensureGitignore(repoPath, { dryRun = false } = {}) {
+  const gitignore = path.join(repoPath, ".gitignore");
+  if (!fs.existsSync(gitignore)) {
+    return { path: gitignore, action: "missing_gitignore" };
+  }
+  const text = fs.readFileSync(gitignore, "utf8");
+  const lines = text.split(/\r?\n/);
+  if (lines.some((l) => l.trim() === ".cursor/")) {
+    return { path: gitignore, action: "ok" };
+  }
+  if (dryRun) return { path: gitignore, action: "would_append" };
+  const suffix =
+    (text.endsWith("\n") || text.length === 0 ? "" : "\n") +
+    "\n# Personal Cursor config (symlink to ~/.ai-md)\n.cursor/\n";
+  fs.appendFileSync(gitignore, suffix);
+  return { path: gitignore, action: "appended" };
+}
+
+function copyDir(src, dest, { dryRun = false } = {}) {
+  if (dryRun) return { action: "would_copy", from: src, to: dest };
+  fs.cpSync(src, dest, { recursive: true, force: false, errorOnExist: false });
+  return { action: "copied", from: src, to: dest };
+}
+
+function initProject({
+  repo,
+  name,
+  from = "base",
+  force = false,
+  dryRun = false,
+} = {}) {
+  const cfg = resolveConfig();
+  if (!fs.existsSync(path.join(cfg.dir, ".git"))) {
+    const err = new Error(`${cfg.dir} is not a git repo; run ai-md install first`);
+    err.code = "ENOENT";
+    throw err;
+  }
+  if (!repo || !fs.existsSync(repo) || !fs.statSync(repo).isDirectory()) {
+    const err = new Error(`missing or invalid --repo <path>`);
+    err.code = "EINVAL";
+    throw err;
+  }
+  const absRepo = fs.realpathSync(repo);
+  const projectName = name || path.basename(absRepo);
+  const tmplDir = templatePath(cfg, from);
+  const projectDir = path.join(cfg.projectsDir, projectName);
+
+  if (!fs.existsSync(tmplDir)) {
+    const err = new Error(
+      `template not found: ${tmplDir} (available under ${cfg.templatesDir}/)`
+    );
+    err.code = "ENOENT";
+    throw err;
+  }
+
+  const actions = [];
+  if (fs.existsSync(projectDir)) {
+    const hasContent =
+      countEntries(path.join(projectDir, "rules")) +
+        countEntries(path.join(projectDir, "skills")) >
+      0;
+    if (hasContent && !force) {
+      actions.push({ action: "exists", path: projectDir });
+    } else {
+      actions.push(...mergeTemplate(tmplDir, projectDir, { dryRun }));
+    }
+  } else {
+    actions.push(copyDir(tmplDir, projectDir, { dryRun }));
+  }
+
+  const link = path.join(absRepo, ".cursor");
+  actions.push(linkPath(projectDir, link, { force, dryRun }));
+  actions.push(ensureGitignore(absRepo, { dryRun }));
+
+  return {
+    project: projectName,
+    projectDir,
+    repo: absRepo,
+    from,
+    templateDir: tmplDir,
+    actions,
+  };
+}
+
+function countEntries(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  return fs.readdirSync(dir).filter((n) => !n.startsWith(".")).length;
+}
+
+function mergeTemplate(templateDir, projectDir, { dryRun = false } = {}) {
+  const actions = [];
+  for (const kind of ["rules", "skills"]) {
+    const srcRoot = path.join(templateDir, kind);
+    const destRoot = path.join(projectDir, kind);
+    if (!fs.existsSync(srcRoot)) continue;
+    ensureDir(destRoot);
+    for (const name of fs.readdirSync(srcRoot)) {
+      if (name.startsWith(".")) continue;
+      const src = path.join(srcRoot, name);
+      const dest = path.join(destRoot, name);
+      if (fs.existsSync(dest)) {
+        actions.push({ action: "keep", path: dest });
+        continue;
+      }
+      if (dryRun) {
+        actions.push({ action: "would_add", path: dest, from: src });
+      } else {
+        fs.cpSync(src, dest, { recursive: true });
+        actions.push({ action: "added", path: dest, from: src });
+      }
+    }
+  }
+  return actions;
+}
+
+function applyTemplate({ project, from = "base", dryRun = false } = {}) {
+  const cfg = resolveConfig();
+  if (!project) {
+    const err = new Error("missing --project <name>");
+    err.code = "EINVAL";
+    throw err;
+  }
+  const projectDir = path.join(cfg.projectsDir, project);
+  if (!fs.existsSync(projectDir)) {
+    const err = new Error(`project not found: ${projectDir}`);
+    err.code = "ENOENT";
+    throw err;
+  }
+  const tmplDir = templatePath(cfg, from);
+  if (!fs.existsSync(tmplDir)) {
+    const err = new Error(`template not found: ${tmplDir}`);
+    err.code = "ENOENT";
+    throw err;
+  }
+  const actions = mergeTemplate(tmplDir, projectDir, { dryRun });
+  return { project, projectDir, from, templateDir: tmplDir, actions };
+}
+
+function linkProject({ repo, name, force = false, dryRun = false } = {}) {
+  const cfg = resolveConfig();
+  if (!fs.existsSync(path.join(cfg.dir, ".git"))) {
+    const err = new Error(`${cfg.dir} is not a git repo; run ai-md install first`);
+    err.code = "ENOENT";
+    throw err;
+  }
+  if (!repo || !fs.existsSync(repo)) {
+    const err = new Error("missing or invalid --repo <path>");
+    err.code = "EINVAL";
+    throw err;
+  }
+  const absRepo = fs.realpathSync(repo);
+  const projectName = name || path.basename(absRepo);
+  const projectDir = path.join(cfg.projectsDir, projectName);
+  if (!dryRun) {
+    ensureDir(path.join(projectDir, "rules"));
+    ensureDir(path.join(projectDir, "skills"));
+  }
+  const actions = [
+    linkPath(projectDir, path.join(absRepo, ".cursor"), { force, dryRun }),
+    ensureGitignore(absRepo, { dryRun }),
+  ];
+  return { project: projectName, projectDir, repo: absRepo, actions };
+}
+
+function runDoctor({ fix = false, force = false, agents = ["cursor"], dryRun = false } = {}) {
+  const cfg = resolveConfig();
+  const status = collectStatus({ full: true, agents });
+  const repairs = [];
+  if (fix || force) {
+    repairs.push(...ensureCursorLinks(cfg, { force: true, dryRun }));
+    repairs.push(...ensureAgentSkillLinks(cfg, agents, { force: true, dryRun }));
+  }
+  const after = fix || force ? collectStatus({ full: true, agents }) : status;
+  return {
+    before: {
+      problems: status.problems,
+      counts: status.counts,
+    },
+    repairs,
+    after: {
+      problems: after.problems,
+      counts: after.counts,
+      links: after.links,
+      projects: after.projects,
+    },
+    help: statusHelp(after),
+  };
+}
+
+module.exports = {
+  ensureCursorLinks,
+  ensureAgentSkillLinks,
+  ensureGitignore,
+  initProject,
+  applyTemplate,
+  linkProject,
+  runDoctor,
+  linkPath,
+  collectProjects,
+};

package/lib/config.js

@@ -0,0 +1,131 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function resolveConfig(env = process.env) {
+  const home = os.homedir();
+  const dir =
+    env.AI_MD_DIR || env.CURSOR_MD_DIR || path.join(home, ".ai-md");
+  const remote =
+    env.AI_MD_REMOTE ||
+    env.CURSOR_MD_REMOTE ||
+    "https://github.com/dujavi/.ai-md.git";
+  const templatesDir = path.join(dir, "templates");
+  return {
+    home,
+    dir,
+    remote,
+    cursorSkills: path.join(home, ".cursor", "skills"),
+    cursorRules: path.join(home, ".cursor", "rules"),
+    projectsDir: path.join(dir, "projects"),
+    templatesDir,
+    /** @deprecated use templatePath(cfg, name) */
+    templateDir: path.join(templatesDir, "base"),
+    skillsDir: path.join(dir, "skills"),
+    rulesDir: path.join(dir, "rules"),
+  };
+}
+
+function templatePath(cfg, name = "base") {
+  return path.join(cfg.templatesDir, name);
+}
+
+function listTemplates(cfg) {
+  if (!fs.existsSync(cfg.templatesDir)) return [];
+  return fs
+    .readdirSync(cfg.templatesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name)
+    .sort();
+}
+
+function countRules(rulesDir) {
+  if (!fs.existsSync(rulesDir)) return 0;
+  return fs
+    .readdirSync(rulesDir)
+    .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;
+}
+
+function listSkillNames(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name)
+    .sort();
+}
+
+function listRuleNames(rulesDir) {
+  if (!fs.existsSync(rulesDir)) return [];
+  return fs
+    .readdirSync(rulesDir)
+    .filter((f) => f.endsWith(".mdc") || f.endsWith(".md"))
+    .sort();
+}
+
+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 };
+}
+
+function agentSkillTargets(home, agents) {
+  const map = {
+    cursor: path.join(home, ".cursor", "skills"),
+    claude: path.join(home, ".claude", "skills"),
+    agents: path.join(home, ".agents", "skills"),
+  };
+  return (agents || [])
+    .map((a) => String(a).trim().toLowerCase())
+    .filter(Boolean)
+    .filter((name) => map[name])
+    .map((name) => ({ name, path: map[name] }));
+}
+
+/** One-time: projects/template → templates/base */
+function migrateLegacyTemplate(cfg, { dryRun = false } = {}) {
+  const legacy = path.join(cfg.projectsDir, "template");
+  const dest = templatePath(cfg, "base");
+  if (!fs.existsSync(legacy) || fs.existsSync(dest)) {
+    return { action: "skip" };
+  }
+  if (dryRun) return { action: "would_migrate", from: legacy, to: dest };
+  fs.mkdirSync(cfg.templatesDir, { recursive: true });
+  fs.renameSync(legacy, dest);
+  return { action: "migrated", from: legacy, to: dest };
+}
+
+module.exports = {
+  resolveConfig,
+  templatePath,
+  listTemplates,
+  migrateLegacyTemplate,
+  countRules,
+  countSkills,
+  listSkillNames,
+  listRuleNames,
+  symlinkState,
+  agentSkillTargets,
+};

package/lib/output.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const { encode } = require("@toon-format/toon");
+
+function emit({ data, json = false, help = [] }) {
+  if (json) {
+    const payload = help.length ? { ...data, help } : data;
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`${encode(data)}\n`);
+  if (help.length) {
+    process.stdout.write(`help[${help.length}]:\n`);
+    for (const line of help) {
+      process.stdout.write(`  ${JSON.stringify(line)}\n`);
+    }
+  }
+}
+
+function fail(message, { exitCode = 1, help = [], json = false } = {}) {
+  const data = {
+    error: message,
+    ...(help.length ? { help } : {}),
+  };
+  if (json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${encode(data)}\n`);
+    if (help.length) {
+      process.stdout.write(`help[${help.length}]:\n`);
+      for (const line of help) {
+        process.stdout.write(`  ${JSON.stringify(line)}\n`);
+      }
+    }
+  }
+  process.exitCode = exitCode;
+}
+
+module.exports = { emit, fail, encode };

package/lib/status.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const {
+  resolveConfig,
+  templatePath,
+  listTemplates,
+  migrateLegacyTemplate,
+  countRules,
+  countSkills,
+  listSkillNames,
+  listRuleNames,
+  symlinkState,
+  agentSkillTargets,
+} = require("./config");
+
+function git(repo, args) {
+  try {
+    return execFileSync("git", ["-C", repo, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function templateDrift(projectDir, tmplDir) {
+  if (!fs.existsSync(tmplDir)) {
+    return { missingRules: [], missingSkills: [], extraRules: [], extraSkills: [] };
+  }
+  const tRules = new Set(listRuleNames(path.join(tmplDir, "rules")));
+  const tSkills = new Set(listSkillNames(path.join(tmplDir, "skills")));
+  const pRules = new Set(listRuleNames(path.join(projectDir, "rules")));
+  const pSkills = new Set(listSkillNames(path.join(projectDir, "skills")));
+  return {
+    missingRules: [...tRules].filter((r) => !pRules.has(r)),
+    missingSkills: [...tSkills].filter((s) => !pSkills.has(s)),
+    extraRules: [...pRules].filter((r) => !tRules.has(r)),
+    extraSkills: [...pSkills].filter((s) => !tSkills.has(s)),
+  };
+}
+
+function collectTemplates(cfg, { full = false } = {}) {
+  return listTemplates(cfg).map((name) => {
+    const dir = templatePath(cfg, name);
+    return {
+      name,
+      rules: countRules(path.join(dir, "rules")),
+      skills: countSkills(path.join(dir, "skills")),
+      ...(full ? { path: dir } : {}),
+    };
+  });
+}
+
+function collectProjects(cfg, { full = false, from = "base" } = {}) {
+  const projects = [];
+  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;
+    const projectDir = path.join(cfg.projectsDir, name);
+    if (!fs.statSync(projectDir).isDirectory()) continue;
+    const drift = templateDrift(projectDir, tmplDir);
+    projects.push({
+      name,
+      kind: "project",
+      from,
+      rules: countRules(path.join(projectDir, "rules")),
+      skills: countSkills(path.join(projectDir, "skills")),
+      missingRules: drift.missingRules.length,
+      missingSkills: drift.missingSkills.length,
+      ...(full ? { path: projectDir, drift } : {}),
+    });
+  }
+  return projects;
+}
+
+function collectStatus(opts = {}) {
+  const cfg = resolveConfig();
+  const full = Boolean(opts.full);
+  const agents = opts.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 links = [
+    symlinkState(cfg.cursorSkills, cfg.skillsDir),
+    symlinkState(cfg.cursorRules, cfg.rulesDir),
+  ];
+
+  const agentLinks = agentSkillTargets(cfg.home, agents)
+    .filter((t) => t.name !== "cursor")
+    .map((t) => ({
+      agent: t.name,
+      ...symlinkState(t.path, cfg.skillsDir),
+    }));
+
+  const templates = collectTemplates(cfg, { full });
+  const projects = collectProjects(cfg, { full, from });
+  const drifting = projects.filter(
+    (p) => p.missingRules > 0 || p.missingSkills > 0
+  );
+
+  let branch = null;
+  let remote = null;
+  let dirty = false;
+  let aheadBehind = null;
+  if (isGit) {
+    branch = git(cfg.dir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    remote = git(cfg.dir, ["remote", "get-url", "origin"]);
+    const porcelain = git(cfg.dir, ["status", "--porcelain"]);
+    dirty = Boolean(porcelain && porcelain.length);
+    aheadBehind = git(cfg.dir, ["status", "-sb"]) || null;
+  }
+
+  const problems = [];
+  if (!exists) problems.push("ai_md_missing");
+  else if (!isGit) problems.push("ai_md_not_git");
+  for (const l of links) {
+    if (l.state !== "ok") problems.push(`cursor_${path.basename(l.path)}_${l.state}`);
+  }
+  if (!fs.existsSync(templatePath(cfg, "base")) && templates.length === 0) {
+    problems.push("templates_missing");
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    dir: cfg.dir,
+    remote: remote || cfg.remote,
+    branch,
+    dirty,
+    statusLine: aheadBehind,
+    layout: {
+      system: { rules: cfg.rulesDir, skills: cfg.skillsDir },
+      templates: cfg.templatesDir,
+      projects: cfg.projectsDir,
+    },
+    migration,
+    counts: {
+      rules: countRules(cfg.rulesDir),
+      skills: countSkills(cfg.skillsDir),
+      templates: templates.length,
+      projects: projects.length,
+      drifting: drifting.length,
+      problems: problems.length,
+    },
+    links: links.map((l) => ({
+      path: l.path,
+      state: l.state,
+      ...(full ? { target: l.target, expected: l.expected } : {}),
+    })),
+    agentLinks: agentLinks.map((l) => ({
+      agent: l.agent,
+      path: l.path,
+      state: l.state,
+      ...(full ? { target: l.target, expected: l.expected } : {}),
+    })),
+    templates,
+    projects,
+    driftFrom: from,
+    problems,
+  };
+}
+
+function statusHelp(data) {
+  const help = [];
+  if (data.problems.includes("ai_md_missing") || data.problems.includes("ai_md_not_git")) {
+    help.push("Run `ai-md install` to clone AI_MD_REMOTE → ~/.ai-md and link ~/.cursor/{skills,rules}");
+  }
+  if (data.links.some((l) => l.state !== "ok")) {
+    help.push("Run `ai-md doctor --fix` to repair ~/.cursor skills/rules symlinks");
+  }
+  if (data.problems.includes("templates_missing")) {
+    help.push("Create ~/.ai-md/templates/base with project starters (system skills/rules stay in skills/ and rules/)");
+  }
+  if (data.counts.drifting > 0) {
+    help.push(
+      `Run \`ai-md apply-template --project <name> --from ${data.driftFrom || "base"}\` to merge missing template files`
+    );
+  }
+  if (data.dirty) {
+    help.push('Run `ai-md push -m "<why>"` to commit and push private config');
+  } else {
+    help.push("Edit system skills/rules under ~/.ai-md/{skills,rules}; project overlays under projects/");
+  }
+  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;
+}
+
+module.exports = {
+  collectStatus,
+  collectProjects,
+  collectTemplates,
+  templateDrift,
+  statusHelp,
+  git,
+};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dujavi/ai-md",
-  "version": "0.1.0",
-  "description": "CLI to sync private ~/.ai-md Cursor skills/rules and install agent tools (grok, quota-axi)",
+  "version": "0.3.0",
+  "description": "AXI-shaped CLI for ~/.ai-md system skills/rules, templates/, and projects/",
   "bin": {
     "ai-md": "bin/ai-md.js"
   },
   "files": [
     "bin/",
+    "lib/",
     "scripts/",
     "README.md",
     "LICENSE"
@@ -15,7 +16,10 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node bin/ai-md.js --help"
+    "test": "node bin/ai-md.js --help && node bin/ai-md.js status --json >/dev/null"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^2.3.1"
   },
   "keywords": [
     "cursor",