agents-sync 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,2 +1,10 @@
 #!/usr/bin/env node
-import "./index.js";
+const args = process.argv.slice(2);
+if (args.includes("init")) {
+    const { runInit } = await import("./init.js");
+    await runInit({ cwd: process.cwd() });
+}
+else {
+    await import("./index.js");
+}
+export {};

package/dist/index.js

@@ -1,129 +1,35 @@
 import chokidar from "chokidar";
-import path from "node:path";
-import fs from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { loadConfig, resolveTargetAgentsDir } from "./config.js";
-import { parseAgentsMarkdown, inferKindFromPath } from "./schema.js";
-import { translators } from "./translation/index.js";
-const CWD = process.cwd();
-const CONFIG_PATH = path.join(CWD, "agents.config.json");
-const ensureDir = async (dirPath) => {
-    await fs.mkdir(dirPath, { recursive: true });
-};
-const writeIfChanged = async (filePath, content) => {
-    let existing = null;
-    try {
-        existing = await fs.readFile(filePath, "utf8");
-    }
-    catch {
-        existing = null;
-    }
-    if (existing === content)
-        return;
-    await ensureDir(path.dirname(filePath));
-    await fs.writeFile(filePath, content, "utf8");
-};
-const walkFiles = async (dirPath) => {
-    const entries = await fs.readdir(dirPath, { withFileTypes: true });
-    const files = [];
-    for (const entry of entries) {
-        const full = path.join(dirPath, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...(await walkFiles(full)));
-        }
-        else if (entry.isFile()) {
-            files.push(full);
-        }
-    }
-    return files;
-};
+import { createSyncContext, ensureTargetDirs, walkFiles, syncSourceFile, removeSourceFile, syncRootDoc } from "./sync.js";
 const main = async () => {
-    const config = await loadConfig(CONFIG_PATH);
-    const sourceDir = path.resolve(CWD, config.sourceDir);
-    const rootDoc = path.resolve(CWD, config.rootDoc);
-    const targetEntries = Object.entries(config.targets);
-    for (const [, target] of targetEntries) {
-        await ensureDir(resolveTargetAgentsDir(CWD, target, config.agentsSubdir));
-    }
-    const syncSourceFile = async (filePath) => {
-        const rel = path.relative(sourceDir, filePath);
-        const kind = inferKindFromPath(rel);
-        if (!kind)
-            return;
-        const id = path.basename(rel, path.extname(rel));
-        const content = await fs.readFile(filePath, "utf8");
-        const doc = parseAgentsMarkdown(content, { kind, id });
-        await Promise.all(targetEntries.map(async ([targetKey, target]) => {
-            const translator = translators[targetKey];
-            if (!translator)
-                return;
-            const baseDir = resolveTargetAgentsDir(CWD, target, config.agentsSubdir);
-            const subdir = translator.subdir(doc, target);
-            const ext = translator.fileExtension(doc, target);
-            const outPath = path.join(baseDir, subdir, `${doc.id}${ext}`);
-            const translated = translator.renderDoc(doc, target);
-            await writeIfChanged(outPath, translated);
-        }));
-    };
-    const removeSourceFile = async (filePath) => {
-        const rel = path.relative(sourceDir, filePath);
-        const kind = inferKindFromPath(rel);
-        if (!kind)
-            return;
-        const id = path.basename(rel, path.extname(rel));
-        const doc = parseAgentsMarkdown("", { kind, id });
-        await Promise.all(targetEntries.map(async ([targetKey, target]) => {
-            const translator = translators[targetKey];
-            if (!translator)
-                return;
-            const baseDir = resolveTargetAgentsDir(CWD, target, config.agentsSubdir);
-            const subdir = translator.subdir(doc, target);
-            const ext = translator.fileExtension(doc, target);
-            const outPath = path.join(baseDir, subdir, `${id}${ext}`);
-            await fs.rm(outPath, { force: true });
-        }));
-    };
-    const syncRootDoc = async () => {
-        if (!existsSync(rootDoc))
-            return;
-        const content = await fs.readFile(rootDoc, "utf8");
-        const doc = parseAgentsMarkdown(content, { kind: "config", id: "root" });
-        const rootTargets = config.rootTargets;
-        await Promise.all(Object.entries(rootTargets).map(async ([targetKey, outName]) => {
-            const translator = translators[targetKey];
-            if (!translator)
-                return;
-            const outPath = path.resolve(CWD, outName);
-            const translated = translator.renderDoc(doc, config.targets[targetKey]);
-            await writeIfChanged(outPath, translated);
-        }));
-    };
-    if (existsSync(sourceDir)) {
-        const files = await walkFiles(sourceDir);
+    const ctx = await createSyncContext(process.cwd());
+    await ensureTargetDirs(ctx);
+    if (existsSync(ctx.sourceDir)) {
+        const files = await walkFiles(ctx.sourceDir);
         for (const filePath of files) {
-            await syncSourceFile(filePath);
+            await syncSourceFile(ctx, filePath);
         }
     }
-    await syncRootDoc();
-    const agentsWatcher = chokidar.watch(sourceDir, {
+    await syncRootDoc(ctx);
+    const agentsWatcher = chokidar.watch(ctx.sourceDir, {
         ignoreInitial: true,
         awaitWriteFinish: {
             stabilityThreshold: 150,
             pollInterval: 50
         }
     });
-    agentsWatcher.on("add", syncSourceFile);
-    agentsWatcher.on("change", syncSourceFile);
-    agentsWatcher.on("unlink", removeSourceFile);
-    const rootWatcher = chokidar.watch(rootDoc, {
+    agentsWatcher.on("add", (filePath) => syncSourceFile(ctx, filePath));
+    agentsWatcher.on("change", (filePath) => syncSourceFile(ctx, filePath));
+    agentsWatcher.on("unlink", (filePath) => removeSourceFile(ctx, filePath));
+    const rootWatcher = chokidar.watch(ctx.rootDoc, {
         ignoreInitial: true,
         awaitWriteFinish: {
             stabilityThreshold: 150,
             pollInterval: 50
         }
     });
-    rootWatcher.on("add", syncRootDoc);
-    rootWatcher.on("change", syncRootDoc);
+    rootWatcher.on("add", () => syncRootDoc(ctx));
+    rootWatcher.on("change", () => syncRootDoc(ctx));
     process.stdout.write("agents-sync watching .agents and AGENTS.MD\n");
 };
 main().catch((err) => {

package/dist/init.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { ensureDir, syncOnce } from "./sync.js";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_CONFIG_PATH = path.join(PACKAGE_ROOT, "agents.config.json");
+const DEFAULT_SCHEMA_PATH = path.join(PACKAGE_ROOT, "SCHEMA.MD");
+const DEFAULT_SCHEMA_COMMAND = `\`\`\`agents
+id: schema
+type: command
+title: Schema Guide
+description: How to write and update the canonical agents schema.
+aliases: agents-schema
+\`\`\`
+
+Use \`.agents/SCHEMA.MD\` as the source of truth for the canonical schema.
+
+When you create or update commands, hooks, or skills, follow the format
+defined in \`.agents/SCHEMA.MD\`. If you need to extend or change the schema,
+update \`.agents/SCHEMA.MD\` and keep examples consistent.`;
+const writeIfMissing = async (filePath, content) => {
+    if (existsSync(filePath))
+        return false;
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, "utf8");
+    return true;
+};
+const copyIfMissing = async (fromPath, toPath) => {
+    if (existsSync(toPath))
+        return false;
+    const content = await fs.readFile(fromPath, "utf8");
+    await ensureDir(path.dirname(toPath));
+    await fs.writeFile(toPath, content, "utf8");
+    return true;
+};
+export const runInit = async ({ cwd, quiet }) => {
+    const created = [];
+    if (await copyIfMissing(DEFAULT_CONFIG_PATH, path.join(cwd, "agents.config.json"))) {
+        created.push("agents.config.json");
+    }
+    const agentsDir = path.join(cwd, ".agents");
+    await ensureDir(agentsDir);
+    await ensureDir(path.join(agentsDir, "commands"));
+    await ensureDir(path.join(agentsDir, "hooks"));
+    await ensureDir(path.join(agentsDir, "skills"));
+    if (await copyIfMissing(DEFAULT_SCHEMA_PATH, path.join(agentsDir, "SCHEMA.MD"))) {
+        created.push(".agents/SCHEMA.MD");
+    }
+    if (await writeIfMissing(path.join(agentsDir, "commands", "schema.md"), DEFAULT_SCHEMA_COMMAND)) {
+        created.push(".agents/commands/schema.md");
+    }
+    await syncOnce(cwd);
+    if (!quiet) {
+        if (created.length) {
+            console.log(`agents-sync init created: ${created.join(", ")}`);
+        }
+        else {
+            console.log("agents-sync init: nothing to do");
+        }
+    }
+};

package/dist/postinstall.js

@@ -0,0 +1,36 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { runInit } from "./init.js";
+const shouldSkip = async () => {
+    if (process.env.AGENTS_SYNC_SKIP_INIT === "1")
+        return true;
+    if (process.env.npm_config_global === "true")
+        return true;
+    const initCwd = process.env.INIT_CWD;
+    if (!initCwd)
+        return true;
+    const pkgPath = path.join(initCwd, "package.json");
+    if (!existsSync(pkgPath))
+        return true;
+    try {
+        const raw = await fs.readFile(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (!deps["agents-sync"])
+            return true;
+    }
+    catch {
+        return true;
+    }
+    return false;
+};
+const main = async () => {
+    if (await shouldSkip())
+        return;
+    const cwd = process.env.INIT_CWD ?? process.cwd();
+    await runInit({ cwd, quiet: true });
+};
+main().catch((err) => {
+    console.warn("[agents-sync] init skipped:", err?.message ?? err);
+});

package/dist/sync.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { loadConfig, resolveTargetAgentsDir } from "./config.js";
+import { parseAgentsMarkdown, inferKindFromPath } from "./schema.js";
+import { translators } from "./translation/index.js";
+export const ensureDir = async (dirPath) => {
+    await fs.mkdir(dirPath, { recursive: true });
+};
+export const writeIfChanged = async (filePath, content) => {
+    let existing = null;
+    try {
+        existing = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        existing = null;
+    }
+    if (existing === content)
+        return;
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, "utf8");
+};
+export const walkFiles = async (dirPath) => {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walkFiles(full)));
+        }
+        else if (entry.isFile()) {
+            files.push(full);
+        }
+    }
+    return files;
+};
+export const createSyncContext = async (cwd, configPath = path.join(cwd, "agents.config.json")) => {
+    const config = await loadConfig(configPath);
+    const sourceDir = path.resolve(cwd, config.sourceDir);
+    const rootDoc = path.resolve(cwd, config.rootDoc);
+    const targetEntries = Object.entries(config.targets);
+    return { cwd, config, sourceDir, rootDoc, targetEntries };
+};
+export const ensureTargetDirs = async (ctx) => {
+    for (const [, target] of ctx.targetEntries) {
+        await ensureDir(resolveTargetAgentsDir(ctx.cwd, target, ctx.config.agentsSubdir));
+    }
+};
+export const syncSourceFile = async (ctx, filePath) => {
+    const rel = path.relative(ctx.sourceDir, filePath);
+    const kind = inferKindFromPath(rel);
+    if (!kind)
+        return;
+    const id = path.basename(rel, path.extname(rel));
+    const content = await fs.readFile(filePath, "utf8");
+    const doc = parseAgentsMarkdown(content, { kind, id });
+    await Promise.all(ctx.targetEntries.map(async ([targetKey, target]) => {
+        const translator = translators[targetKey];
+        if (!translator)
+            return;
+        const baseDir = resolveTargetAgentsDir(ctx.cwd, target, ctx.config.agentsSubdir);
+        const subdir = translator.subdir(doc, target);
+        const ext = translator.fileExtension(doc, target);
+        const outPath = path.join(baseDir, subdir, `${doc.id}${ext}`);
+        const translated = translator.renderDoc(doc, target);
+        await writeIfChanged(outPath, translated);
+    }));
+};
+export const removeSourceFile = async (ctx, filePath) => {
+    const rel = path.relative(ctx.sourceDir, filePath);
+    const kind = inferKindFromPath(rel);
+    if (!kind)
+        return;
+    const id = path.basename(rel, path.extname(rel));
+    const doc = parseAgentsMarkdown("", { kind, id });
+    await Promise.all(ctx.targetEntries.map(async ([targetKey, target]) => {
+        const translator = translators[targetKey];
+        if (!translator)
+            return;
+        const baseDir = resolveTargetAgentsDir(ctx.cwd, target, ctx.config.agentsSubdir);
+        const subdir = translator.subdir(doc, target);
+        const ext = translator.fileExtension(doc, target);
+        const outPath = path.join(baseDir, subdir, `${id}${ext}`);
+        await fs.rm(outPath, { force: true });
+    }));
+};
+export const syncRootDoc = async (ctx) => {
+    if (!existsSync(ctx.rootDoc))
+        return;
+    const content = await fs.readFile(ctx.rootDoc, "utf8");
+    const doc = parseAgentsMarkdown(content, { kind: "config", id: "root" });
+    const rootTargets = ctx.config.rootTargets;
+    await Promise.all(Object.entries(rootTargets).map(async ([targetKey, outName]) => {
+        const translator = translators[targetKey];
+        if (!translator)
+            return;
+        const outPath = path.resolve(ctx.cwd, outName);
+        const translated = translator.renderDoc(doc, ctx.config.targets[targetKey]);
+        await writeIfChanged(outPath, translated);
+    }));
+};
+export const syncOnce = async (cwd, configPath = path.join(cwd, "agents.config.json")) => {
+    const ctx = await createSyncContext(cwd, configPath);
+    await ensureTargetDirs(ctx);
+    if (existsSync(ctx.sourceDir)) {
+        const files = await walkFiles(ctx.sourceDir);
+        for (const filePath of files) {
+            await syncSourceFile(ctx, filePath);
+        }
+    }
+    await syncRootDoc(ctx);
+    return ctx;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-sync",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -16,7 +16,8 @@
     "build": "tsc -p tsconfig.json",
     "postbuild": "node scripts/add-shebang.mjs",
     "start": "node dist/index.js",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "postinstall": "node dist/postinstall.js"
   },
   "dependencies": {
     "chokidar": "^3.6.0"

package/readme.md

@@ -26,6 +26,30 @@ npm i -D agents-sync
 npx agents-sync
 ```
 
+### Auto Init On Install
+
+When installed as a direct dependency, `agents-sync` will scaffold:
+
+- `agents.config.json`
+- `.agents/SCHEMA.MD`
+- `.agents/commands/schema.md`
+- `.agents/commands`, `.agents/hooks`, `.agents/skills`
+
+It then runs a one-time sync to create the target folders and the `schema`
+command in each tool folder.
+
+Skip this behavior with:
+
+```bash
+AGENTS_SYNC_SKIP_INIT=1 npm i -D agents-sync
+```
+
+You can also run it manually:
+
+```bash
+npx agents-sync init
+```
+
 ## Canonical Schema
 
 The canonical format is Markdown with an optional `agents` metadata fence. See `SCHEMA.MD` for the full schema and translation rules.