@dalzoubi/dev-agents-sync 1.0.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dalzoubi/dev-agents-sync",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
+  "bin": {
+    "dev-agents-sync": "./src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./lockfile": "./src/lockfile.mjs",
+    "./marker": "./src/marker.mjs",
+    "./range": "./src/range.mjs",
+    "./fetcher": "./src/fetcher.mjs",
+    "./writer": "./src/writer.mjs",
+    "./auth": "./src/auth.mjs",
+    "./commands/init": "./src/commands/init.mjs",
+    "./commands/update": "./src/commands/update.mjs",
+    "./commands/status": "./src/commands/status.mjs",
+    "./commands/check": "./src/commands/check.mjs",
+    "./commands/diff": "./src/commands/diff.mjs"
+  },
+  "scripts": {
+    "dev": "node --watch src/cli.mjs",
+    "build": "echo 'No build step for v1 (pure ESM)'",
+    "test": "node --test tests/*.test.mjs",
+    "test:e2e": "node --test tests/e2e/*.test.mjs",
+    "lint": "npx eslint ."
+  },
+  "dependencies": {
+    "semver": "^7.6.0",
+    "tar": "^7.4.0"
+  },
+  "devDependencies": {
+    "node": ">=20.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,95 @@
+/**
+ * Auth chain.
+ *
+ *   1. explicit `--token` flag (passed via { tokenFlag })
+ *   2. GITHUB_TOKEN env var
+ *   3. `gh auth token` shellout (injectable for tests)
+ *
+ * On failure, throw an actionable error with exitCode = 2 that names BOTH
+ * fallbacks (`GITHUB_TOKEN` and `gh auth login`). The token value is never
+ * embedded in error messages or logged.
+ */
+
+import { spawn } from 'node:child_process';
+
+class AuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AuthError';
+    this.exitCode = 2;
+  }
+}
+
+/** Default `gh auth token` shellout. Returns the trimmed token or null. */
+async function defaultGhAuthToken() {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn('gh', ['auth', 'token'], { shell: false });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (err) => reject(err));
+    child.on('close', (code) => {
+      if (code === 0) {
+        const token = stdout.trim();
+        resolve(token.length > 0 ? token : null);
+      } else {
+        // Do NOT include stderr verbatim — it's unlikely to leak a token,
+        // but be conservative.
+        reject(new Error(`gh auth token exited with code ${code}`));
+      }
+    });
+  });
+}
+
+/**
+ * Resolves an auth token following the documented chain.
+ *
+ * Options:
+ *   tokenFlag    — explicit token from --token flag (highest priority)
+ *   env          — process.env-like object (default: process.env)
+ *   ghAuthToken  — async function returning a token or null/empty (injectable)
+ */
+export async function resolveToken({ tokenFlag, env, ghAuthToken } = {}) {
+  if (tokenFlag && typeof tokenFlag === 'string' && tokenFlag.length > 0) {
+    return tokenFlag;
+  }
+
+  const envSource = env ?? process.env;
+  const envToken = envSource && envSource.GITHUB_TOKEN;
+  if (typeof envToken === 'string' && envToken.length > 0) {
+    return envToken;
+  }
+
+  const shellout = ghAuthToken ?? defaultGhAuthToken;
+  let ghToken = null;
+  let ghErr = null;
+  try {
+    ghToken = await shellout();
+  } catch (err) {
+    ghErr = err;
+  }
+
+  if (typeof ghToken === 'string' && ghToken.length > 0) {
+    return ghToken;
+  }
+
+  // Both fallbacks failed. Throw an actionable error. Do not echo any
+  // upstream value (which might have been a token-shaped string).
+  throw new AuthError(
+    'authentication required: no token found.\n' +
+      '  Set the GITHUB_TOKEN environment variable, or run `gh auth login` ' +
+      'to authenticate the GitHub CLI.',
+  );
+}

package/src/cli.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * dev-agents-sync — CLI entry point.
+ *
+ * This is intentionally minimal in v1: tests drive the runX() functions
+ * directly. The CLI binary parses flags and dispatches.
+ */
+
+import process from 'node:process';
+
+import { runInit } from './commands/init.mjs';
+import { runUpdate } from './commands/update.mjs';
+import { runStatus } from './commands/status.mjs';
+import { runCheck } from './commands/check.mjs';
+import { runDiff } from './commands/diff.mjs';
+import {
+  defaultGithubFetcher,
+  defaultGithubTagLister,
+  STUB_NOT_IMPLEMENTED,
+} from './fetcher.mjs';
+import { resolveToken } from './auth.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      let key, value;
+      if (eq >= 0) {
+        key = a.slice(2, eq);
+        value = a.slice(eq + 1);
+      } else {
+        key = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+          value = next;
+          i += 1;
+        } else {
+          value = true;
+        }
+      }
+      args.flags[key] = value;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function fail(message, code = 2) {
+  process.stderr.write(`error: ${message}\n`);
+  process.exit(code);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { _: positional, flags } = parseArgs(argv);
+  const sub = positional[0];
+
+  if (!sub || sub === 'help' || flags.help) {
+    process.stdout.write(
+      'Usage: dev-agents-sync <init|update|status|check|diff> [flags]\n',
+    );
+    process.exit(0);
+  }
+
+  const cwd = process.cwd();
+
+  let token;
+  try {
+    token = await resolveToken({
+      tokenFlag: typeof flags.token === 'string' ? flags.token : undefined,
+      env: process.env,
+    });
+  } catch (err) {
+    // For status/check/diff/init/update we need a token — bail early.
+    fail(err.message, err.exitCode ?? 2);
+  }
+
+  const fetcher = async (repo, tag) => defaultGithubFetcher(repo, tag, token);
+  let availableTags;
+  try {
+    availableTags = await defaultGithubTagLister('dalzoubi/dev-agents', token);
+  } catch (err) {
+    // Only swallow the stub's specific "not implemented" sentinel. Real
+    // network/auth/parse failures must surface to the user with exit 2.
+    if (err && err.code === STUB_NOT_IMPLEMENTED) {
+      availableTags = [];
+    } else {
+      fail(err.message ?? String(err), err?.exitCode ?? 2);
+    }
+  }
+
+  const targetsFlag = (() => {
+    if (flags.targets === undefined) return undefined;
+    if (flags.targets === 'auto') return 'auto';
+    if (typeof flags.targets === 'string') {
+      return flags.targets.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    return undefined;
+  })();
+
+  const commonOpts = {
+    fetcher,
+    availableTags,
+    token,
+    targets: targetsFlag,
+    range: typeof flags.range === 'string' ? flags.range : undefined,
+    force: Boolean(flags.force),
+    dryRun: Boolean(flags['dry-run']),
+  };
+
+  try {
+    switch (sub) {
+      case 'init': {
+        const r = await runInit(cwd, commonOpts);
+        process.stdout.write(`init complete: v${r.resolvedVersion}\n`);
+        process.exit(0);
+        break;
+      }
+      case 'update': {
+        const r = await runUpdate(cwd, commonOpts);
+        if (r.upToDate) process.stdout.write(`already up to date at v${r.resolvedVersion}\n`);
+        else process.stdout.write(`updated to v${r.resolvedVersion}\n`);
+        process.exit(0);
+        break;
+      }
+      case 'status': {
+        const r = await runStatus(cwd, commonOpts);
+        process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+        process.exit(0);
+        break;
+      }
+      case 'check': {
+        await runCheck(cwd, commonOpts);
+        process.stdout.write('in sync\n');
+        process.exit(0);
+        break;
+      }
+      case 'diff': {
+        const r = await runDiff(cwd, commonOpts);
+        if (r && r.diff) process.stdout.write(r.diff);
+        process.exit(0);
+        break;
+      }
+      default:
+        fail(`unknown subcommand: ${sub}`, 2);
+    }
+  } catch (err) {
+    fail(err.message, err.exitCode ?? 2);
+  }
+}
+
+main().catch((err) => {
+  fail(err.message ?? String(err), 2);
+});

package/src/commands/check.mjs

@@ -0,0 +1,77 @@
+/**
+ * `check` subcommand.
+ *
+ * Exit 0 — local managed files match expected emission for the resolved version.
+ * Exit 1 — drift detected.
+ * Exit 2 — tooling error (auth, network, etc.).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { readLockfile } from '../lockfile.mjs';
+import { resolveConsumerPath, normalizeFileMap } from '../writer.mjs';
+
+function filterFileMapByTargets(fileMap, targets) {
+  const out = {};
+  for (const [key, content] of Object.entries(fileMap)) {
+    const prefix = key.split('/')[0];
+    if (targets.includes(prefix)) {
+      out[key] = content;
+    }
+  }
+  return out;
+}
+
+export async function runCheck(consumerCwd, opts = {}) {
+  const { fetcher, token, repo = 'dalzoubi/dev-agents' } = opts;
+
+  if (typeof fetcher !== 'function') {
+    const err = new Error('runCheck requires an injected fetcher');
+    err.exitCode = 2;
+    throw err;
+  }
+
+  const lock = readLockfile(consumerCwd);
+
+  let fileMap;
+  try {
+    fileMap = await fetcher(repo, `v${lock.resolvedVersion}`, token);
+  } catch (err) {
+    const wrapped = new Error(
+      `tooling error while fetching v${lock.resolvedVersion}: ${err.message}`,
+    );
+    wrapped.exitCode = 2;
+    wrapped.cause = err;
+    throw wrapped;
+  }
+
+  const scoped = filterFileMapByTargets(normalizeFileMap(fileMap), lock.targets);
+
+  const drifted = [];
+
+  for (const [relKey, expected] of Object.entries(scoped)) {
+    const absPath = resolveConsumerPath(consumerCwd, relKey);
+    if (!existsSync(absPath)) {
+      // Missing-locally is the canonical CI drift case: an expected managed
+      // file was deleted (or never written). Mark it explicitly so consumers
+      // can tell deletion drift from content drift in the message.
+      drifted.push(`<missing> ${relKey}`);
+      continue;
+    }
+    const actual = readFileSync(absPath, 'utf8');
+    if (actual !== expected) {
+      drifted.push(relKey);
+    }
+  }
+
+  if (drifted.length === 0) {
+    return { inSync: true, resolvedVersion: lock.resolvedVersion };
+  }
+
+  const err = new Error(
+    `drift detected for v${lock.resolvedVersion} — drifted: ${drifted.join(', ')}`,
+  );
+  err.exitCode = 1;
+  err.drifted = drifted;
+  throw err;
+}

package/src/commands/diff.mjs

@@ -0,0 +1,68 @@
+/**
+ * `diff` subcommand. Prints unified diff between local managed files and
+ * what the resolved version would emit. Always exits 0 (informational).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { readLockfile } from '../lockfile.mjs';
+import { resolveConsumerPath, normalizeFileMap } from '../writer.mjs';
+
+function filterFileMapByTargets(fileMap, targets) {
+  const out = {};
+  for (const [key, content] of Object.entries(fileMap)) {
+    const prefix = key.split('/')[0];
+    if (targets.includes(prefix)) {
+      out[key] = content;
+    }
+  }
+  return out;
+}
+
+/** Naive line-based unified diff. Sufficient for this tool's purposes. */
+function unifiedDiff(relKey, actual, expected) {
+  if (actual === expected) return '';
+  const aLines = actual.split('\n');
+  const bLines = expected.split('\n');
+  const out = [
+    `--- a/${relKey}`,
+    `+++ b/${relKey}`,
+  ];
+  const max = Math.max(aLines.length, bLines.length);
+  for (let i = 0; i < max; i++) {
+    const a = aLines[i];
+    const b = bLines[i];
+    if (a === b) continue;
+    if (a !== undefined) out.push(`-${a}`);
+    if (b !== undefined) out.push(`+${b}`);
+  }
+  return out.join('\n') + '\n';
+}
+
+export async function runDiff(consumerCwd, opts = {}) {
+  const { fetcher, token, repo = 'dalzoubi/dev-agents' } = opts;
+
+  if (typeof fetcher !== 'function') {
+    const err = new Error('runDiff requires an injected fetcher');
+    err.exitCode = 2;
+    throw err;
+  }
+
+  const lock = readLockfile(consumerCwd);
+
+  const fileMap = await fetcher(repo, `v${lock.resolvedVersion}`, token);
+  const scoped = filterFileMapByTargets(normalizeFileMap(fileMap), lock.targets);
+
+  let combined = '';
+  const perFile = {};
+
+  for (const [relKey, expected] of Object.entries(scoped)) {
+    const absPath = resolveConsumerPath(consumerCwd, relKey);
+    const actual = existsSync(absPath) ? readFileSync(absPath, 'utf8') : '';
+    const d = unifiedDiff(relKey, actual, expected);
+    perFile[relKey] = d;
+    combined += d;
+  }
+
+  return { diff: combined, perFile };
+}

package/src/commands/init.mjs

@@ -0,0 +1,159 @@
+/**
+ * `init` subcommand.
+ *
+ * Creates the lockfile and writes managed files for the chosen targets.
+ * Refuses to overwrite unmanaged collisions without --force.
+ * Supports --dry-run (no writes).
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { writeLockfile, DEFAULT_SOURCE } from '../lockfile.mjs';
+import { resolveRange } from '../range.mjs';
+import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
+import { hasMarker } from '../marker.mjs';
+
+const DEFAULT_RANGE = '^1';
+const ALL_TARGETS = ['claude', 'cursor'];
+
+function autoDetectTargets(consumerCwd) {
+  const claudeExists = existsSync(path.join(consumerCwd, '.claude'));
+  const cursorExists = existsSync(path.join(consumerCwd, '.cursor'));
+  if (!claudeExists && !cursorExists) return [...ALL_TARGETS];
+  const out = [];
+  if (claudeExists) out.push('claude');
+  if (cursorExists) out.push('cursor');
+  return out;
+}
+
+function normalizeTargets(targetsOpt, consumerCwd) {
+  if (targetsOpt === undefined || targetsOpt === null || targetsOpt === 'auto') {
+    return autoDetectTargets(consumerCwd);
+  }
+  if (Array.isArray(targetsOpt)) {
+    if (targetsOpt.length === 0) return autoDetectTargets(consumerCwd);
+    return [...targetsOpt];
+  }
+  if (typeof targetsOpt === 'string') {
+    return targetsOpt.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  throw new Error(`invalid --targets value: ${JSON.stringify(targetsOpt)}`);
+}
+
+function filterFileMapByTargets(fileMap, targets) {
+  const out = {};
+  for (const [key, content] of Object.entries(fileMap)) {
+    const prefix = key.split('/')[0];
+    if (targets.includes(prefix)) {
+      out[key] = content;
+    }
+  }
+  return out;
+}
+
+/**
+ * runInit — programmatic entry point for the init subcommand.
+ *
+ * Options:
+ *   targets        — array | "auto" | undefined  (default: auto-detect)
+ *   range          — semver range (default: "^1")
+ *   force          — overwrite unmanaged collisions
+ *   dryRun         — print plan, no writes
+ *   token          — auth token (passed to fetcher; never persisted)
+ *   fetcher        — async (repo, tag, token) => FileMap   (injectable)
+ *   availableTags  — array of tag strings (injectable; in production this
+ *                    will be supplied by a tag lister)
+ *   source         — defaults to "github:dalzoubi/dev-agents"
+ *   repo           — defaults to "dalzoubi/dev-agents"
+ *   log            — { info, warn, error } sink (default: stderr)
+ */
+export async function runInit(consumerCwd, opts = {}) {
+  const {
+    targets,
+    range = DEFAULT_RANGE,
+    force = false,
+    dryRun = false,
+    token,
+    fetcher,
+    availableTags,
+    source = DEFAULT_SOURCE,
+    repo = 'dalzoubi/dev-agents',
+  } = opts;
+
+  if (typeof fetcher !== 'function') {
+    const err = new Error('runInit requires an injected fetcher');
+    err.exitCode = 2;
+    throw err;
+  }
+  if (!Array.isArray(availableTags)) {
+    const err = new Error('runInit requires availableTags');
+    err.exitCode = 2;
+    throw err;
+  }
+
+  const resolvedTargets = normalizeTargets(targets, consumerCwd);
+  if (resolvedTargets.length === 0) {
+    const err = new Error('no targets selected; specify --targets or run in a repo with .claude/ or .cursor/');
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const resolvedVersion = resolveRange(availableTags, range);
+
+  const fileMap = await fetcher(repo, `v${resolvedVersion}`, token);
+  const normalized = normalizeFileMap(fileMap);
+  const scoped = filterFileMapByTargets(normalized, resolvedTargets);
+
+  // Plan writes
+  const plannedWrites = [];
+  for (const [relKey, content] of Object.entries(scoped)) {
+    const absPath = resolveConsumerPath(consumerCwd, relKey);
+    plannedWrites.push({ relKey, absPath, content });
+  }
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      resolvedVersion,
+      targets: resolvedTargets,
+      plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
+      files: plannedWrites.map(({ relKey }) => relKey),
+    };
+  }
+
+  // Pre-flight collision check (so we fail before any writes)
+  for (const { absPath, relKey } of plannedWrites) {
+    if (existsSync(absPath) && !force) {
+      const fs = await import('node:fs');
+      const existing = fs.readFileSync(absPath, 'utf8');
+      if (!hasMarker(existing)) {
+        const err = new Error(
+          `refusing to overwrite unmanaged file at ${relKey} ` +
+            `(${absPath}). Delete/rename it or pass --force to overwrite.`,
+        );
+        err.exitCode = 1;
+        throw err;
+      }
+    }
+  }
+
+  for (const { absPath, relKey, content } of plannedWrites) {
+    writeManagedFile({ absPath, relKey, content, force: true });
+  }
+
+  writeLockfile(consumerCwd, {
+    source,
+    range,
+    resolvedVersion,
+    targets: [...resolvedTargets].sort(),
+    lastUpdated: new Date().toISOString(),
+  });
+
+  return {
+    resolvedVersion,
+    targets: [...resolvedTargets].sort(),
+    plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
+    files: plannedWrites.map(({ relKey }) => relKey),
+  };
+}

package/src/commands/status.mjs

@@ -0,0 +1,71 @@
+/**
+ * `status` subcommand. Informational, exit 0.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { readLockfile } from '../lockfile.mjs';
+import { resolveRange } from '../range.mjs';
+
+const TARGET_DIRS = {
+  claude: ['.claude', 'agents'],
+  cursor: ['.cursor', 'rules'],
+};
+
+function countTargetFiles(consumerCwd, target) {
+  const segs = TARGET_DIRS[target];
+  if (!segs) return 0;
+  // Count files recursively under <target-root>/
+  const root = path.join(consumerCwd, segs[0]);
+  if (!existsSync(root)) return 0;
+  let n = 0;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) n += 1;
+    }
+  }
+  return n;
+}
+
+export async function runStatus(consumerCwd, opts = {}) {
+  const { availableTags } = opts;
+
+  const lock = readLockfile(consumerCwd);
+
+  let latestAvailable = null;
+  if (Array.isArray(availableTags) && availableTags.length > 0) {
+    try {
+      latestAvailable = resolveRange(availableTags, lock.range);
+    } catch {
+      latestAvailable = null;
+    }
+  }
+
+  const fileCounts = {};
+  for (const t of lock.targets) {
+    fileCounts[t] = countTargetFiles(consumerCwd, t);
+  }
+
+  return {
+    range: lock.range,
+    resolvedVersion: lock.resolvedVersion,
+    latestAvailable,
+    latest: latestAvailable,
+    targets: lock.targets,
+    source: lock.source,
+    fileCounts,
+    managedFiles: fileCounts,
+    counts: fileCounts,
+  };
+}