@sayansr26/agent-os 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -40,6 +40,18 @@ among several rather than the whole product.
 - Documentation is generic throughout; examples are invented.
 
 ### Fixed
+- **`init` scaffolded over projects that already had rules.** It wrote a
+  placeholder `AGENTS.md` and an `example.md` rule regardless of what was
+  there, and the next `sync` compiled the placeholder on top of the project's
+  real `AGENTS.md`. `init` now adopts what it finds — the existing `AGENTS.md`
+  and the first rules directory it recognises, `.cursor/rules/*.mdc` converted
+  back to `paths:` — and seeds `example.md` only when there was nothing to
+  adopt. A tool for stopping rule drift must not cause it.
+- **`sync` now refuses to overwrite a file it did not generate.** Generated
+  files carry a banner; anything else at a generated path is the user's own
+  work. `sync` names those files, leaves them alone and exits non-zero, with
+  `--force` as the explicit opt-out. `AGENTS.md` carries the banner too — it
+  previously did not, which is why nothing could tell it apart.
 - `check` reported every skill file as drifted immediately after a `sync`. Skill
   files are read as buffers so a skill can ship a binary asset, rule files are
   generated as strings, and the two were compared with `!==`. Comparison is now

package/README.md

@@ -76,6 +76,13 @@ Every command below is `npx @sayansr26/agent-os <command>`. Install it once —
 
 `--root <dir>` to target another directory, `--dry-run` to preview.
 
+**On an existing project, `init` adopts rather than scaffolds.** It takes your
+current `AGENTS.md` and the first rules directory it recognises as the source,
+so the first `sync` regenerates what you already had. **`sync` never overwrites
+a file it did not generate** — generated files carry a banner, anything else at
+that path is yours. It names those files, leaves them alone and exits 1; pass
+`--force` if you really mean to replace them.
+
 Generated files carry a banner. Edit `.agent-os/`, run `sync`, never edit the output.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayansr26/agent-os",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "One source of truth for AI coding agent config. Write your rules once; compile them to Claude Code, Cursor, Cline, Windsurf, Antigravity, Gemini CLI, OpenCode and Kilo.",
   "keywords": [
     "ai",
@@ -46,4 +46,4 @@
     "test": "node scripts/validate-plugin.mjs && node src/selftest.mjs",
     "prepublishOnly": "npm test"
   }
-}
+}

package/src/adopt.mjs

@@ -0,0 +1,80 @@
+/**
+ * Adopt what a project already has, instead of scaffolding over it.
+ *
+ * `init` used to write a placeholder `AGENTS.md` and an `example.md` rule into
+ * every project, including projects that already had a real AGENTS.md and a
+ * directory of real rules. The next `sync` then compiled the placeholder over
+ * the real file. A tool whose whole purpose is to stop rule files drifting must
+ * not destroy the rules it finds, so `init` now imports them as the source.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { BANNER } from "./source.mjs";
+
+const isGenerated = (text) => text.includes(BANNER);
+
+const readDirMd = (dir, ext) => {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(ext))
+    .map((f) => ({ name: basename(f, ext), text: readFileSync(join(dir, f), "utf8") }))
+    .filter((r) => !isGenerated(r.text));
+};
+
+/** `.cursor/rules/*.mdc` back into the canonical `paths:` / `always:` shape. */
+function fromCursor({ name, text }) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return { name, text };
+  const fields = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  const globs = (fields.globs || "").split(",").map((g) => g.trim()).filter(Boolean);
+  const always = String(fields.alwaysApply) === "true";
+  const fm = ["---"];
+  if (fields.description) fm.push(`description: ${fields.description}`);
+  if (always || globs.length === 0) fm.push("always: true");
+  else { fm.push("paths:"); for (const g of globs) fm.push(`  - "${g}"`); }
+  fm.push("---", "");
+  return { name, text: `${fm.join("\n")}\n${m[2].trim()}\n` };
+}
+
+/**
+ * What this project already has that should become the source.
+ * Returns `{ agents, rules, from, paths }`; `from` is what to tell the user,
+ * `paths` the files it consumed — safe for `init` to regenerate in place.
+ */
+export function adopt(root) {
+  const from = [];
+  const paths = new Set();
+  let agents = null;
+
+  const agentsPath = join(root, "AGENTS.md");
+  if (existsSync(agentsPath)) {
+    const text = readFileSync(agentsPath, "utf8");
+    if (!isGenerated(text)) { agents = text; from.push("AGENTS.md"); paths.add("AGENTS.md"); }
+  }
+
+  // In precedence order — the first store that has anything wins, because these
+  // are copies of each other in a project that was keeping them in sync by hand.
+  const sources = [
+    [".claude/rules", ".md", (r) => r],
+    [".clinerules", ".md", (r) => r],
+    [".agents/rules", ".md", (r) => r],
+    [".cursor/rules", ".mdc", fromCursor],
+    [".windsurf/rules", ".md", (r) => r],
+  ];
+
+  let rules = [];
+  for (const [dir, ext, convert] of sources) {
+    const found = readDirMd(join(root, dir), ext);
+    if (!found.length) continue;
+    rules = found.map(convert);
+    from.push(`${dir}/ (${rules.length} rule${rules.length === 1 ? "" : "s"})`);
+    for (const r of found) paths.add(`${dir}/${r.name}${ext}`);
+    break;
+  }
+
+  return { agents, rules, from, paths };
+}

package/src/cli.mjs

@@ -1,9 +1,10 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
 import { detect, summarise, TOOLS } from "./detect.mjs";
-import { load, write, readIfExists, matches, DIR } from "./source.mjs";
+import { load, write, readIfExists, matches, BANNER, DIR } from "./source.mjs";
+import { adopt } from "./adopt.mjs";
 import { compile, TARGETS } from "./targets.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -25,6 +26,7 @@ ${bold("agent-os")} — one source of truth for AI coding agent config
 Options
   --root <dir>   project directory (default: cwd)
   --dry-run      print what would change, write nothing
+  --force        overwrite files agent-os did not generate (it refuses by default)
 `;
 
 function scaffold(root, found) {
@@ -32,6 +34,17 @@ function scaffold(root, found) {
   mkdirSync(join(root, DIR, "rules"), { recursive: true });
   if (!existsSync(join(root, DIR, "config.json")))
     write(root, `${DIR}/config.json`, JSON.stringify({ targets: present.length ? present : ["claude-code"] }, null, 2) + "\n");
+
+  // Take what the project already has as the source. Writing a placeholder over
+  // a real AGENTS.md, then compiling the placeholder back on top of it, is the
+  // exact drift this tool exists to prevent.
+  const taken = adopt(root);
+  if (taken.agents && !existsSync(join(root, DIR, "AGENTS.md")))
+    write(root, `${DIR}/AGENTS.md`, taken.agents);
+  for (const r of taken.rules)
+    if (!existsSync(join(root, DIR, "rules", `${r.name}.md`)))
+      write(root, `${DIR}/rules/${r.name}.md`, r.text);
+
   if (!existsSync(join(root, DIR, "AGENTS.md")))
     write(root, `${DIR}/AGENTS.md`, `# Project instructions
 
@@ -42,7 +55,11 @@ Keep it short. Anything that only matters for part of the tree belongs in
 \`.agent-os/rules/\` instead, where it can be scoped to the files it applies to.
 `);
   mkdirSync(join(root, DIR, "skills"), { recursive: true });
-  if (!existsSync(join(root, DIR, "rules", "example.md")))
+
+  // Only seed the placeholder when there was nothing to adopt. A project with
+  // real rules does not need an `example.md` compiled into every tool it uses.
+  const anyRule = readdirSync(join(root, DIR, "rules")).some((f) => f.endsWith(".md"));
+  if (!anyRule)
     write(root, `${DIR}/rules/example.md`, `---
 description: Conventions for the API layer
 paths:
@@ -55,7 +72,7 @@ A rule with \`paths:\` is loaded only when the agent touches a matching file, in
 every tool that supports conditional loading. Tools that do not support it get
 these as a referenced list instead of always-on text.
 `);
-  return present;
+  return { present, taken };
 }
 
 export async function main(argv) {
@@ -101,11 +118,19 @@ export async function main(argv) {
     return;
   }
 
+  let adopted = new Set();
+
   if (cmd === "init") {
     console.log(`\n${bold("agent-os init")}  ${root}\n`);
     console.log(summarise(found));
-    const present = scaffold(root, found);
-    console.log(`\n  created ${DIR}/ ${dim("(config.json, AGENTS.md, rules/example.md)")}`);
+    const { present, taken } = scaffold(root, found);
+    adopted = taken.paths;
+    if (taken.from.length) {
+      console.log(`\n  adopted into ${DIR}/ ${dim("— your existing files are now the source")}`);
+      for (const f of taken.from) console.log(`    ${f}`);
+    } else {
+      console.log(`\n  created ${DIR}/ ${dim("(config.json, AGENTS.md, rules/example.md)")}`);
+    }
     if (!present.length) console.log(`  ${dim("no tools detected — defaulting to claude-code; edit .agent-os/config.json")}`);
   }
 
@@ -142,13 +167,42 @@ export async function main(argv) {
       }
       return TARGETS[t]?.label || t;
     };
+    // Never overwrite a file this tool did not write. A generated file carries
+    // the banner; anything else at that path is the user's own work, and
+    // silently compiling over it is worse than doing nothing.
+    const force = argv.includes("--force");
+    const isOurs = (f) => {
+      const cur = readIfExists(root, f.path);
+      if (cur === null) return true;                       // nothing there yet
+      if (cur.includes(BANNER)) return true;               // we wrote it
+      if (TARGETS[f.target]?.merge) return true;           // merged in place, nothing lost
+      if (adopted.has(f.path)) return true;                // init just took this as the source
+      if (matches(root, f.path, f.content) === true) return true; // already identical
+      return false;
+    };
+
+    const blocked = [];
     for (const [t, fs_] of Object.entries(byTarget)) {
       console.log(`  ${labelFor(t).padEnd(38)} ${fs_.length} file(s)`);
       for (const f of fs_) {
+        if (!force && !isOurs(f)) { blocked.push(f.path); console.log(`    ${f.path}  ${dim("SKIPPED — not generated by agent-os")}`); continue; }
         if (!dry) write(root, f.path, f.content);
         console.log(`    ${f.path}`);
       }
     }
+
+    if (blocked.length) {
+      console.log(`\n${bold(`${blocked.length} file(s) left alone`)} because agent-os did not write them:\n`);
+      for (const b of blocked) console.log(`  ${b}`);
+      console.log(`
+Pick one:
+  · move the content into ${DIR}/ so it becomes the source, then re-run
+  · ${dim("--force")} to overwrite (the current content is lost — commit first)
+`);
+      process.exitCode = 1;
+      return;
+    }
+
     console.log(`\n${dim("Generated files carry a banner. Edit .agent-os/ and re-run sync; never edit them directly.")}\n`);
     return;
   }

package/src/selftest.mjs

@@ -53,11 +53,56 @@ try {
 
   console.log("\n  drift");
   ok(cli(["check"], root).status === 0, "check passes when in sync");
-  writeFileSync(join(root, ".cursor/rules/api.mdc"), "hand edited\n");
+  // Realistic drift: someone edits the body of a generated file and leaves the
+  // banner in place. sync owns that file and must put it back.
+  writeFileSync(join(root, ".cursor/rules/api.mdc"),
+    read(".cursor/rules/api.mdc").replace("Validate at the boundary.", "hand edited"));
   const d = cli(["check"], root);
   ok(d.status === 1, "check exits 1 on drift");
   ok(d.stdout.includes("DRIFTED"), "check names the drifted file");
   ok(cli(["sync"], root).status === 0 && cli(["check"], root).status === 0, "sync repairs drift");
+  // Banner stripped: now indistinguishable from a hand-written file, so sync
+  // refuses rather than guessing.
+  writeFileSync(join(root, ".cursor/rules/api.mdc"), "mine now\n");
+  ok(cli(["sync"], root).status === 1, "sync refuses once the banner is gone");
+  ok(read(".cursor/rules/api.mdc") === "mine now\n", "and leaves that file untouched");
+  cli(["sync", "--force"], root);
+
+  console.log("\n  never clobbers what it did not write");
+  {
+    const r2 = mkdtempSync(join(tmpdir(), "agent-os-adopt-"));
+    mkdirSync(join(r2, ".claude/rules"), { recursive: true });
+    const realAgents = "# Real AGENTS.md\n\nCLAUDE.md is the source of truth.\n";
+    writeFileSync(join(r2, "AGENTS.md"), realAgents);
+    writeFileSync(join(r2, ".claude/rules/theming.md"),
+      '---\ndescription: Theming\npaths:\n  - "src/**/*.tsx"\n---\n\nUse the token set.\n');
+
+    const i = cli(["init"], r2);
+    ok(i.status === 0, "init exits 0 on a project that already has rules");
+    ok(readFileSync(join(r2, "AGENTS.md"), "utf8") === realAgents ||
+       readFileSync(join(r2, ".agent-os/AGENTS.md"), "utf8") === realAgents,
+       "existing AGENTS.md becomes the source rather than being replaced");
+    ok(existsSync(join(r2, ".agent-os/rules/theming.md")), "existing .claude/rules/ are adopted");
+    ok(!existsSync(join(r2, ".agent-os/rules/example.md")), "no example.md when real rules were adopted");
+    ok(!existsSync(join(r2, ".claude/rules/example.md")), "no example.md compiled into the project");
+
+    // A hand-written file at a generated path must survive a sync.
+    const r3 = mkdtempSync(join(tmpdir(), "agent-os-guard-"));
+    mkdirSync(join(r3, ".agent-os/rules"), { recursive: true });
+    writeFileSync(join(r3, ".agent-os/config.json"), JSON.stringify({ targets: ["claude-code"] }));
+    writeFileSync(join(r3, ".agent-os/AGENTS.md"), "# Compiled\n");
+    writeFileSync(join(r3, ".agent-os/rules/x.md"), '---\npaths:\n  - "a/**"\n---\n\nBody.\n');
+    const mine = "# Mine, by hand\n";
+    writeFileSync(join(r3, "AGENTS.md"), mine);
+    const g = cli(["sync"], r3);
+    ok(g.status === 1, "sync exits 1 rather than clobbering");
+    ok(readFileSync(join(r3, "AGENTS.md"), "utf8") === mine, "hand-written AGENTS.md survives sync");
+    ok(g.stdout.includes("SKIPPED"), "sync says which file it left alone");
+    const fg = cli(["sync", "--force"], r3);
+    ok(fg.status === 0 && readFileSync(join(r3, "AGENTS.md"), "utf8") !== mine, "--force overwrites when asked");
+    rmSync(r2, { recursive: true, force: true });
+    rmSync(r3, { recursive: true, force: true });
+  }
 
   console.log("\n  merge, not overwrite");
   writeFileSync(join(root, "opencode.json"), JSON.stringify({ model: "anthropic/x", instructions: ["KEEP.md"] }, null, 2));

package/src/targets.mjs

@@ -28,7 +28,9 @@ function agentsMd(src) {
       s.map((r) => `- \`${r.paths.join("`, `")}\` — ${r.description || r.name}`).join("\n")
     );
   }
-  return parts.filter(Boolean).join("\n\n") + "\n";
+  // The banner is what lets `sync` tell its own output from the user's file.
+  // Without it AGENTS.md is indistinguishable from hand-written work.
+  return mdHeader + parts.filter(Boolean).join("\n\n") + "\n";
 }
 
 export const TARGETS = {