@dalzoubi/dev-agents-sync 1.0.0

package/tests/range.test.mjs

@@ -0,0 +1,163 @@
+/**
+ * tests/range.test.mjs
+ *
+ * Tests for semver range resolution.
+ *
+ * The range resolver takes:
+ *   - a list of available version tags (strings like "v1.0.0", "v1.1.0")
+ *   - a semver range string (like "^1", "~1.0", ">=1.2.0")
+ *
+ * It returns the latest version satisfying the range, or throws/returns null
+ * with an actionable error message when nothing matches.
+ *
+ * Note: tags in the content repo include the "v" prefix but semver ranges do
+ * not. The resolver normalizes tag strings by stripping the leading "v".
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveRange } from '../src/range.mjs';
+
+// Available tags as they would come from the GitHub API
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+
+// ---------------------------------------------------------------------------
+// Caret range (^)
+// ---------------------------------------------------------------------------
+
+describe('resolveRange — caret range', () => {
+  it('picks the latest v1.x.x for range "^1"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '^1');
+    assert.equal(result, '1.2.0');
+  });
+
+  it('picks the latest v1.x.x for range "^1.0"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '^1.0');
+    assert.equal(result, '1.2.0');
+  });
+
+  it('picks the latest v2.x.x for range "^2"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '^2');
+    assert.equal(result, '2.0.0');
+  });
+
+  it('does NOT pick v2.0.0 for range "^1"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '^1');
+    assert.notEqual(result, '2.0.0');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tilde range (~)
+// ---------------------------------------------------------------------------
+
+describe('resolveRange — tilde range', () => {
+  it('picks v1.0.0 for range "~1.0" (no v1.0.x above v1.0.0)', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '~1.0');
+    assert.equal(result, '1.0.0');
+  });
+
+  it('picks v1.1.0 for range "~1.1"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '~1.1');
+    assert.equal(result, '1.1.0');
+  });
+
+  it('picks v1.2.0 for range "~1.2"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '~1.2');
+    assert.equal(result, '1.2.0');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Exact version
+// ---------------------------------------------------------------------------
+
+describe('resolveRange — exact version', () => {
+  it('returns exactly v1.1.0 when range is "1.1.0"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '1.1.0');
+    assert.equal(result, '1.1.0');
+  });
+
+  it('returns exactly v2.0.0 when range is "2.0.0"', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '2.0.0');
+    assert.equal(result, '2.0.0');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Range that matches nothing
+// ---------------------------------------------------------------------------
+
+describe('resolveRange — no match', () => {
+  it('throws (or returns null with error) when no tag satisfies the range', () => {
+    // v3 does not exist in the tag list
+    let threw = false;
+    let result = null;
+    try {
+      result = resolveRange(AVAILABLE_TAGS, '^3');
+    } catch (err) {
+      threw = true;
+      // Error message must be actionable
+      assert.ok(
+        err.message && (err.message.includes('range') || err.message.includes('^3')),
+        `expected actionable error, got: ${err.message}`,
+      );
+    }
+    if (!threw) {
+      // Alternative: returns null
+      assert.equal(result, null);
+    }
+  });
+
+  it('provides an actionable error message naming the unsatisfied range', () => {
+    let message = '';
+    try {
+      resolveRange(AVAILABLE_TAGS, '^99');
+    } catch (err) {
+      message = err.message;
+    }
+    // Must mention the range or provide guidance
+    assert.ok(
+      message.length > 0,
+      'error message must be non-empty when range is unsatisfied',
+    );
+  });
+
+  it('throws for an empty tag list', () => {
+    assert.throws(() => resolveRange([], '^1'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tag normalization (v prefix)
+// ---------------------------------------------------------------------------
+
+describe('resolveRange — tag normalization', () => {
+  it('handles tags with "v" prefix correctly', () => {
+    // GitHub tags come as "v1.0.0" — resolver must strip the v
+    const result = resolveRange(['v1.0.0', 'v1.1.0'], '^1');
+    assert.equal(result, '1.1.0');
+  });
+
+  it('handles tags without "v" prefix correctly', () => {
+    const result = resolveRange(['1.0.0', '1.1.0'], '^1');
+    assert.equal(result, '1.1.0');
+  });
+
+  it('handles a mixed list of prefixed and unprefixed tags', () => {
+    const result = resolveRange(['1.0.0', 'v1.1.0'], '^1');
+    assert.equal(result, '1.1.0');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Returned value is always a bare version (no "v" prefix)
+// ---------------------------------------------------------------------------
+
+describe('resolveRange — return value format', () => {
+  it('returned version string does NOT include a "v" prefix', () => {
+    const result = resolveRange(AVAILABLE_TAGS, '^1');
+    assert.ok(!result.startsWith('v'), `expected no v prefix, got: ${result}`);
+  });
+});

package/tests/status-check-diff.test.mjs

@@ -0,0 +1,489 @@
+/**
+ * tests/status-check-diff.test.mjs
+ *
+ * Tests for the `status`, `check`, and `diff` subcommands.
+ *
+ * status  — informational, always exit 0
+ * check   — CI-friendly; exit 0 (in sync), 1 (drift), 2 (tooling error)
+ * diff    — prints unified diff, no filesystem writes, always exit 0
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runStatus } from '../src/commands/status.mjs';
+import { runCheck } from '../src/commands/check.mjs';
+import { runDiff } from '../src/commands/diff.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+function buildFixtureFileMap() {
+  const map = {};
+  for (const target of ['claude', 'cursor']) {
+    const targetDir = path.join(FIXTURE_DIR, target);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, target);
+  }
+  return map;
+}
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+function makeFixtureFetcher() {
+  return async (_repo, _tag, _token) => buildFixtureFileMap();
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-scd-test-'));
+}
+
+function setupConsumerRepo(consumerDir, opts = {}) {
+  const {
+    targets = ['claude'],
+    resolvedVersion = '1.2.0',
+    range = '^1',
+    writeFiles = true,
+    driftFile = null, // { path, content } to simulate drift
+  } = opts;
+
+  writeLockfile(consumerDir, {
+    source: 'github:dalzoubi/dev-agents',
+    range,
+    resolvedVersion,
+    targets,
+    lastUpdated: '2026-04-01T00:00:00Z',
+  });
+
+  if (writeFiles && targets.includes('claude')) {
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+
+    // Write fixture files as if init already ran
+    const fixtureContent = readFileSync(
+      path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'),
+      'utf8',
+    );
+    const content = driftFile?.path?.includes('define')
+      ? driftFile.content
+      : fixtureContent;
+    writeFileSync(path.join(agentsDir, 'define.md'), content, 'utf8');
+
+    const testContent = readFileSync(
+      path.join(FIXTURE_DIR, 'claude', 'agents', 'test.md'),
+      'utf8',
+    );
+    writeFileSync(path.join(agentsDir, 'test.md'), testContent, 'utf8');
+
+    // Materialize remaining claude fixture files so check() — which now treats
+    // missing managed files as drift (M1) — sees a complete in-sync state.
+    const commandsDir = path.join(consumerDir, '.claude', 'commands');
+    mkdirSync(commandsDir, { recursive: true });
+    const preflightContent = readFileSync(
+      path.join(FIXTURE_DIR, 'claude', 'commands', 'preflight.md'),
+      'utf8',
+    );
+    writeFileSync(path.join(commandsDir, 'preflight.md'), preflightContent, 'utf8');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// status subcommand
+// ---------------------------------------------------------------------------
+
+describe('status', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    setupConsumerRepo(consumerDir);
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 0 and returns output object', async () => {
+    let exitCode = 0;
+    let result;
+
+    try {
+      result = await runStatus(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(exitCode, 0);
+    assert.ok(result, 'status must return a result object');
+  });
+
+  it('result includes range', async () => {
+    const result = await runStatus(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok('range' in result, 'result must include range');
+    assert.equal(result.range, '^1');
+  });
+
+  it('result includes resolvedVersion', async () => {
+    const result = await runStatus(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok('resolvedVersion' in result, 'result must include resolvedVersion');
+    assert.equal(result.resolvedVersion, '1.2.0');
+  });
+
+  it('result includes latest available version', async () => {
+    const result = await runStatus(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      'latestAvailable' in result || 'latest' in result,
+      'result must include latest available version',
+    );
+  });
+
+  it('result includes targets list', async () => {
+    const result = await runStatus(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok('targets' in result, 'result must include targets');
+    assert.deepEqual(result.targets, ['claude']);
+  });
+
+  it('result includes managed file counts per target', async () => {
+    const result = await runStatus(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      'fileCounts' in result || 'managedFiles' in result || 'counts' in result,
+      'result must include file counts',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// check subcommand — exit 0 (in sync)
+// ---------------------------------------------------------------------------
+
+describe('check — in sync (exit 0)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    setupConsumerRepo(consumerDir, { resolvedVersion: '1.2.0' });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 0 when local files match resolved version', async () => {
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 2;
+    }
+
+    assert.equal(exitCode, 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// check subcommand — exit 1 (drift)
+// ---------------------------------------------------------------------------
+
+describe('check — drift detected (exit 1)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 1 when managed file content has been locally modified', async () => {
+    // Set up repo but manually modify a managed file after init
+    setupConsumerRepo(consumerDir, { resolvedVersion: '1.2.0' });
+
+    // Tamper with a managed file (still has marker but content differs)
+    const defineFile = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    const original = readFileSync(defineFile, 'utf8');
+    writeFileSync(defineFile, original + '\n\n# Someone added this locally.', 'utf8');
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'expected exit code 1 for drifted managed file');
+  });
+
+  it('exits 1 when an expected managed file has been deleted locally', async () => {
+    // Init writes define.md and test.md. Delete one to simulate the canonical
+    // CI deletion-drift case: managed file removed between init and check.
+    setupConsumerRepo(consumerDir, { resolvedVersion: '1.2.0' });
+
+    const defineFile = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    rmSync(defineFile);
+
+    let exitCode;
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+      errorMessage = err.message;
+    }
+
+    assert.equal(exitCode, 1, 'expected exit code 1 for a missing managed file');
+    assert.ok(
+      errorMessage.includes('<missing>'),
+      `deletion-drift message must mark the file as missing, got: ${errorMessage}`,
+    );
+    assert.ok(
+      errorMessage.includes('define.md'),
+      `deletion-drift message must name the offending path, got: ${errorMessage}`,
+    );
+  });
+
+  it('drift error message names the offending file path', async () => {
+    setupConsumerRepo(consumerDir, { resolvedVersion: '1.2.0' });
+
+    const defineFile = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    writeFileSync(
+      defineFile,
+      readFileSync(defineFile, 'utf8') + '\nDrifted content.',
+      'utf8',
+    );
+
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      errorMessage = err.message;
+    }
+
+    assert.ok(
+      errorMessage.includes('define.md') || errorMessage.includes('.claude'),
+      `drift error must name the offending path, got: ${errorMessage}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// check subcommand — exit 2 (tooling error)
+// ---------------------------------------------------------------------------
+
+describe('check — tooling error (exit 2)', () => {
+  it('exits 2 when fetcher throws an auth error', async () => {
+    const consumerDir = makeTmpDir();
+    try {
+      setupConsumerRepo(consumerDir);
+
+      const authFailFetcher = async () => {
+        const err = new Error('Authentication failed: bad credentials');
+        err.type = 'auth';
+        throw err;
+      };
+
+      let exitCode;
+      try {
+        await runCheck(consumerDir, {
+          fetcher: authFailFetcher,
+          availableTags: ['v1.0.0', 'v1.2.0'],
+        });
+        exitCode = 0;
+      } catch (err) {
+        exitCode = err.exitCode;
+      }
+
+      assert.equal(exitCode, 2, 'auth failure must produce exit code 2');
+    } finally {
+      rmSync(consumerDir, { recursive: true, force: true });
+    }
+  });
+
+  it('exits 2 when fetcher throws a network error', async () => {
+    const consumerDir = makeTmpDir();
+    try {
+      setupConsumerRepo(consumerDir);
+
+      const networkFailFetcher = async () => {
+        const err = new Error('ECONNREFUSED: network error');
+        err.type = 'network';
+        throw err;
+      };
+
+      let exitCode;
+      try {
+        await runCheck(consumerDir, {
+          fetcher: networkFailFetcher,
+          availableTags: ['v1.0.0', 'v1.2.0'],
+        });
+        exitCode = 0;
+      } catch (err) {
+        exitCode = err.exitCode;
+      }
+
+      assert.equal(exitCode, 2, 'network failure must produce exit code 2');
+    } finally {
+      rmSync(consumerDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// diff subcommand
+// ---------------------------------------------------------------------------
+
+describe('diff', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    setupConsumerRepo(consumerDir, { resolvedVersion: '1.2.0' });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 0 even when diffs are present (informational only)', async () => {
+    // Tamper with a managed file to create a diff
+    const defineFile = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    writeFileSync(
+      defineFile,
+      readFileSync(defineFile, 'utf8') + '\nExtra line added locally.',
+      'utf8',
+    );
+
+    let exitCode = 0;
+    try {
+      await runDiff(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(exitCode, 0, 'diff must exit 0 even when diffs are present');
+  });
+
+  it('exits 0 when files are in sync (no diff)', async () => {
+    let exitCode = 0;
+    try {
+      await runDiff(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(exitCode, 0);
+  });
+
+  it('does not write any files to disk', async () => {
+    // Tamper with a file so there is actually a diff
+    const defineFile = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    const originalContent = readFileSync(defineFile, 'utf8');
+    writeFileSync(defineFile, originalContent + '\nLocal addition.', 'utf8');
+
+    await runDiff(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.2.0'],
+    });
+
+    // File must remain tampered — diff does not restore it
+    const afterDiff = readFileSync(defineFile, 'utf8');
+    assert.ok(
+      afterDiff.includes('Local addition.'),
+      'diff must not modify local files',
+    );
+  });
+
+  it('result contains diff output string', async () => {
+    const defineFile = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    writeFileSync(
+      defineFile,
+      readFileSync(defineFile, 'utf8') + '\nAdded line.',
+      'utf8',
+    );
+
+    const result = await runDiff(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.2.0'],
+    });
+
+    assert.ok(
+      typeof result === 'string' || typeof result?.diff === 'string',
+      'diff must return a string or an object with a diff string',
+    );
+  });
+});