@dalzoubi/dev-agents-sync 1.0.0

package/tests/lockfile.test.mjs

@@ -0,0 +1,202 @@
+/**
+ * tests/lockfile.test.mjs
+ *
+ * Tests for lockfile read/write/validation.
+ *
+ * The lockfile is `.dev-agents-sync.json` at the consumer repo root.
+ * Schema:
+ *   {
+ *     "$schema": "...",
+ *     "source": "github:dalzoubi/dev-agents",
+ *     "range": "^1",
+ *     "resolvedVersion": "1.0.0",
+ *     "targets": ["claude", "cursor"],
+ *     "lastUpdated": "2026-04-24T00:00:00Z"
+ *   }
+ *
+ * Privacy invariant: the lockfile MUST NOT contain auth tokens.
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+// The module under test — will not exist until implement runs.
+// Tests must fail on missing module, not on setup errors.
+import { readLockfile, writeLockfile, validateLockfile } from '../src/lockfile.mjs';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-lockfile-test-'));
+}
+
+const VALID_LOCKFILE = {
+  $schema: 'https://raw.githubusercontent.com/dalzoubi/dev-agents/v1/schema/lockfile.schema.json',
+  source: 'github:dalzoubi/dev-agents',
+  range: '^1',
+  resolvedVersion: '1.0.0',
+  targets: ['claude', 'cursor'],
+  lastUpdated: '2026-04-24T00:00:00Z',
+};
+
+// ---------------------------------------------------------------------------
+// validateLockfile — pure validation, no I/O
+// ---------------------------------------------------------------------------
+
+describe('validateLockfile', () => {
+  it('accepts a fully valid lockfile object', () => {
+    assert.doesNotThrow(() => validateLockfile(VALID_LOCKFILE));
+  });
+
+  it('rejects when range is missing', () => {
+    const bad = { ...VALID_LOCKFILE };
+    delete bad.range;
+    assert.throws(() => validateLockfile(bad), /range/i);
+  });
+
+  it('rejects when range is not a string', () => {
+    assert.throws(() => validateLockfile({ ...VALID_LOCKFILE, range: 1 }), /range/i);
+  });
+
+  it('rejects when targets is not an array', () => {
+    assert.throws(() => validateLockfile({ ...VALID_LOCKFILE, targets: 'claude' }), /targets/i);
+  });
+
+  it('rejects when targets contains an unknown value', () => {
+    assert.throws(
+      () => validateLockfile({ ...VALID_LOCKFILE, targets: ['claude', 'vscode'] }),
+      /targets/i,
+    );
+  });
+
+  it('rejects when targets is an empty array', () => {
+    assert.throws(() => validateLockfile({ ...VALID_LOCKFILE, targets: [] }), /targets/i);
+  });
+
+  it('accepts targets: ["claude"]', () => {
+    assert.doesNotThrow(() => validateLockfile({ ...VALID_LOCKFILE, targets: ['claude'] }));
+  });
+
+  it('accepts targets: ["cursor"]', () => {
+    assert.doesNotThrow(() => validateLockfile({ ...VALID_LOCKFILE, targets: ['cursor'] }));
+  });
+
+  it('rejects when source is missing', () => {
+    const bad = { ...VALID_LOCKFILE };
+    delete bad.source;
+    assert.throws(() => validateLockfile(bad), /source/i);
+  });
+
+  it('rejects when resolvedVersion is missing', () => {
+    const bad = { ...VALID_LOCKFILE };
+    delete bad.resolvedVersion;
+    assert.throws(() => validateLockfile(bad), /resolvedVersion/i);
+  });
+
+  it('rejects a completely wrong shape (empty object)', () => {
+    assert.throws(() => validateLockfile({}), /range|source|targets/i);
+  });
+
+  it('rejects null', () => {
+    assert.throws(() => validateLockfile(null));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// writeLockfile / readLockfile — I/O round-trip
+// ---------------------------------------------------------------------------
+
+describe('writeLockfile / readLockfile round-trip', () => {
+  let tmpDir;
+
+  before(() => {
+    tmpDir = makeTmpDir();
+  });
+
+  after(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('writes a valid lockfile and reads it back with identical shape', () => {
+    writeLockfile(tmpDir, VALID_LOCKFILE);
+    const lockfilePath = path.join(tmpDir, '.dev-agents-sync.json');
+    const raw = readFileSync(lockfilePath, 'utf8');
+    const parsed = JSON.parse(raw);
+
+    assert.equal(parsed.range, VALID_LOCKFILE.range);
+    assert.equal(parsed.resolvedVersion, VALID_LOCKFILE.resolvedVersion);
+    assert.deepEqual(parsed.targets, VALID_LOCKFILE.targets);
+    assert.equal(parsed.source, VALID_LOCKFILE.source);
+    assert.equal(parsed.lastUpdated, VALID_LOCKFILE.lastUpdated);
+  });
+
+  it('readLockfile returns an object equal to what was written', () => {
+    writeLockfile(tmpDir, VALID_LOCKFILE);
+    const back = readLockfile(tmpDir);
+    assert.equal(back.range, VALID_LOCKFILE.range);
+    assert.equal(back.resolvedVersion, VALID_LOCKFILE.resolvedVersion);
+    assert.deepEqual(back.targets, VALID_LOCKFILE.targets);
+  });
+
+  it('lockfile JSON is deterministic — same inputs produce byte-identical output', () => {
+    const dir1 = makeTmpDir();
+    const dir2 = makeTmpDir();
+    try {
+      writeLockfile(dir1, VALID_LOCKFILE);
+      writeLockfile(dir2, VALID_LOCKFILE);
+      const raw1 = readFileSync(path.join(dir1, '.dev-agents-sync.json'), 'utf8');
+      const raw2 = readFileSync(path.join(dir2, '.dev-agents-sync.json'), 'utf8');
+      assert.equal(raw1, raw2);
+    } finally {
+      rmSync(dir1, { recursive: true, force: true });
+      rmSync(dir2, { recursive: true, force: true });
+    }
+  });
+
+  it('lockfile does NOT contain the auth token', () => {
+    const secretToken = 'ghp_SUPERSECRETTOKEN12345';
+    // Even if a token was passed into context, writeLockfile should only persist the schema fields
+    writeLockfile(tmpDir, VALID_LOCKFILE, { token: secretToken });
+    const raw = readFileSync(path.join(tmpDir, '.dev-agents-sync.json'), 'utf8');
+    assert.ok(!raw.includes(secretToken), 'lockfile must not contain the auth token');
+  });
+
+  it('readLockfile throws a structured error when the file is missing', () => {
+    const emptyDir = makeTmpDir();
+    try {
+      assert.throws(() => readLockfile(emptyDir), /no lockfile|not found|ENOENT/i);
+    } finally {
+      rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  it('readLockfile throws a structured error when the file is invalid JSON', () => {
+    const corruptDir = makeTmpDir();
+    try {
+      writeFileSync(path.join(corruptDir, '.dev-agents-sync.json'), '{not: json}', 'utf8');
+      assert.throws(() => readLockfile(corruptDir), /invalid|parse|JSON/i);
+    } finally {
+      rmSync(corruptDir, { recursive: true, force: true });
+    }
+  });
+
+  it('readLockfile throws a structured validation error when schema is wrong', () => {
+    const badDir = makeTmpDir();
+    try {
+      writeFileSync(
+        path.join(badDir, '.dev-agents-sync.json'),
+        JSON.stringify({ source: 'github:dalzoubi/dev-agents' }),
+        'utf8',
+      );
+      // Missing required fields — should fail validation
+      assert.throws(() => readLockfile(badDir), /range|targets|invalid/i);
+    } finally {
+      rmSync(badDir, { recursive: true, force: true });
+    }
+  });
+});

package/tests/marker.test.mjs

@@ -0,0 +1,190 @@
+/**
+ * tests/marker.test.mjs
+ *
+ * Tests for managed-file marker detection.
+ *
+ * Marker format (from spec):
+ *   <!-- managed-by: dev-agents-sync vX.Y.Z -->
+ *
+ * Rules:
+ * - The marker is the first non-empty body line AFTER any YAML frontmatter.
+ * - Files with the marker are "managed" — safe to overwrite.
+ * - Files without the marker at the same path are "unmanaged" — refused without --force.
+ * - Detection works whether the file has frontmatter or not.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { hasMarker, buildMarker, extractMarkerVersion } from '../src/marker.mjs';
+
+// ---------------------------------------------------------------------------
+// buildMarker
+// ---------------------------------------------------------------------------
+
+describe('buildMarker', () => {
+  it('returns the correct marker string for a given version', () => {
+    assert.equal(buildMarker('1.0.0'), '<!-- managed-by: dev-agents-sync v1.0.0 -->');
+  });
+
+  it('includes the v prefix', () => {
+    const marker = buildMarker('2.3.4');
+    assert.ok(marker.includes('v2.3.4'), 'marker must include version with v prefix');
+  });
+
+  it('starts with <!-- and ends with -->', () => {
+    const marker = buildMarker('1.0.0');
+    assert.ok(marker.startsWith('<!--'));
+    assert.ok(marker.endsWith('-->'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hasMarker — file content with frontmatter
+// ---------------------------------------------------------------------------
+
+describe('hasMarker — files WITH YAML frontmatter', () => {
+  const version = '1.0.0';
+
+  it('detects marker as first body line after closing ---', () => {
+    const content = [
+      '---',
+      'name: "define"',
+      'description: "A test agent."',
+      '---',
+      '<!-- managed-by: dev-agents-sync v1.0.0 -->',
+      'Body text here.',
+    ].join('\n');
+    assert.ok(hasMarker(content));
+  });
+
+  it('detects marker after frontmatter with blank line between --- and marker', () => {
+    // The spec says "first non-empty body line" — blank lines between frontmatter and marker are OK
+    const content = [
+      '---',
+      'name: "define"',
+      '---',
+      '',
+      '<!-- managed-by: dev-agents-sync v1.0.0 -->',
+      'Body text here.',
+    ].join('\n');
+    assert.ok(hasMarker(content));
+  });
+
+  it('returns false when marker is absent (file has frontmatter but no marker)', () => {
+    const content = [
+      '---',
+      'name: "define"',
+      'description: "A test agent."',
+      '---',
+      'Body text without marker.',
+    ].join('\n');
+    assert.ok(!hasMarker(content));
+  });
+
+  it('returns false when a different comment appears first in the body', () => {
+    const content = [
+      '---',
+      'name: "define"',
+      '---',
+      '<!-- some other comment -->',
+      'Body text here.',
+    ].join('\n');
+    assert.ok(!hasMarker(content));
+  });
+
+  it('returns false when the marker appears AFTER other body content (not first body line)', () => {
+    const content = [
+      '---',
+      'name: "define"',
+      '---',
+      'Some text first.',
+      '<!-- managed-by: dev-agents-sync v1.0.0 -->',
+    ].join('\n');
+    assert.ok(!hasMarker(content));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hasMarker — file content WITHOUT frontmatter
+// ---------------------------------------------------------------------------
+
+describe('hasMarker — files WITHOUT YAML frontmatter', () => {
+  it('detects marker as first non-empty line when there is no frontmatter', () => {
+    const content = [
+      '<!-- managed-by: dev-agents-sync v1.0.0 -->',
+      'Body text here.',
+    ].join('\n');
+    assert.ok(hasMarker(content));
+  });
+
+  it('returns false when marker is absent and there is no frontmatter', () => {
+    const content = [
+      '# My Heading',
+      'Some body text.',
+    ].join('\n');
+    assert.ok(!hasMarker(content));
+  });
+
+  it('detects marker when there are leading blank lines (no frontmatter)', () => {
+    const content = [
+      '',
+      '<!-- managed-by: dev-agents-sync v1.0.0 -->',
+      'Body text here.',
+    ].join('\n');
+    assert.ok(hasMarker(content));
+  });
+
+  it('returns false for an empty file', () => {
+    assert.ok(!hasMarker(''));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hasMarker — different marker versions
+// ---------------------------------------------------------------------------
+
+describe('hasMarker — version in marker is informational only', () => {
+  it('returns true for marker with v0.9.0 (older version is still a valid marker)', () => {
+    const content = [
+      '---',
+      'name: "define"',
+      '---',
+      '<!-- managed-by: dev-agents-sync v0.9.0 -->',
+      'Body.',
+    ].join('\n');
+    assert.ok(hasMarker(content));
+  });
+
+  it('returns true for marker with v9.99.0', () => {
+    const content = '<!-- managed-by: dev-agents-sync v9.99.0 -->\nBody.';
+    assert.ok(hasMarker(content));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractMarkerVersion
+// ---------------------------------------------------------------------------
+
+describe('extractMarkerVersion', () => {
+  it('extracts version from a managed file with frontmatter', () => {
+    const content = [
+      '---',
+      'name: "define"',
+      '---',
+      '<!-- managed-by: dev-agents-sync v1.3.0 -->',
+      'Body.',
+    ].join('\n');
+    assert.equal(extractMarkerVersion(content), '1.3.0');
+  });
+
+  it('extracts version from a managed file without frontmatter', () => {
+    const content = '<!-- managed-by: dev-agents-sync v2.0.1 -->\nBody.';
+    assert.equal(extractMarkerVersion(content), '2.0.1');
+  });
+
+  it('returns null when no marker is present', () => {
+    const content = '# No marker here\nBody.';
+    assert.equal(extractMarkerVersion(content), null);
+  });
+});

package/tests/paths.test.mjs

@@ -0,0 +1,212 @@
+/**
+ * tests/paths.test.mjs
+ *
+ * Tests for cross-platform path handling.
+ *
+ * These tests ensure that on Windows (this machine) the CLI uses path.join /
+ * path-agnostic logic rather than hardcoded POSIX slashes when writing to the
+ * consumer repo filesystem.
+ *
+ * The FileMap keys from the content repo always use forward slashes (they come
+ * from the GitHub release's dist/ tree). The CLI must translate those into
+ * platform-appropriate paths before writing.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  existsSync,
+  readFileSync,
+  rmSync,
+  mkdirSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runInit } from '../src/commands/init.mjs';
+import { hasMarker } from '../src/marker.mjs';
+import { resolveConsumerPath } from '../src/writer.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 () => buildFixtureFileMap();
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-paths-test-'));
+}
+
+// ---------------------------------------------------------------------------
+// resolveConsumerPath — pure path translation unit
+// ---------------------------------------------------------------------------
+
+describe('resolveConsumerPath', () => {
+  it('translates "claude/agents/define.md" to .claude/agents/define.md', () => {
+    const consumerRoot = '/some/repo';
+    const result = resolveConsumerPath(consumerRoot, 'claude/agents/define.md');
+    // Must use path.join so it's platform-correct
+    const expected = path.join(consumerRoot, '.claude', 'agents', 'define.md');
+    assert.equal(result, expected);
+  });
+
+  it('translates "claude/commands/preflight.md" to .claude/commands/preflight.md', () => {
+    const consumerRoot = '/some/repo';
+    const result = resolveConsumerPath(consumerRoot, 'claude/commands/preflight.md');
+    const expected = path.join(consumerRoot, '.claude', 'commands', 'preflight.md');
+    assert.equal(result, expected);
+  });
+
+  it('translates "cursor/rules/define.mdc" to .cursor/rules/define.mdc', () => {
+    const consumerRoot = '/some/repo';
+    const result = resolveConsumerPath(consumerRoot, 'cursor/rules/define.mdc');
+    const expected = path.join(consumerRoot, '.cursor', 'rules', 'define.mdc');
+    assert.equal(result, expected);
+  });
+
+  it('works with a Windows-style absolute consumer root path', () => {
+    // Simulate a Windows-style path
+    const consumerRoot = 'C:\\Users\\developer\\projects\\my-app';
+    const result = resolveConsumerPath(consumerRoot, 'claude/agents/define.md');
+    // Must not throw and must produce a valid path
+    assert.ok(typeof result === 'string', 'must return a string');
+    assert.ok(result.length > 0);
+    // Must end with the correct filename
+    assert.ok(result.endsWith('define.md'), `expected path ending with define.md, got: ${result}`);
+  });
+
+  it('does not produce double-dot or traversal sequences', () => {
+    const consumerRoot = path.join(tmpdir(), 'consumer');
+    const result = resolveConsumerPath(consumerRoot, 'claude/agents/define.md');
+    assert.ok(!result.includes('..'), `path must not contain traversal, got: ${result}`);
+  });
+
+  it('does not allow path traversal from a malicious FileMap key', () => {
+    const consumerRoot = path.join(tmpdir(), 'consumer');
+    // Attempt path traversal via the FileMap key
+    assert.throws(
+      () => resolveConsumerPath(consumerRoot, '../../../etc/passwd'),
+      /traversal|invalid|outside/i,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// init writes files with platform-correct paths
+// ---------------------------------------------------------------------------
+
+describe('init — platform-correct file paths', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('writes .claude/agents/define.md using the OS path separator', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // The file must exist using the OS path (path.join does the right thing)
+    const expectedPath = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    assert.ok(
+      existsSync(expectedPath),
+      `file must exist at OS-correct path: ${expectedPath}`,
+    );
+  });
+
+  it('writes .cursor/rules/define.mdc using the OS path separator', async () => {
+    await runInit(consumerDir, {
+      targets: ['cursor'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const expectedPath = path.join(consumerDir, '.cursor', 'rules', 'define.mdc');
+    assert.ok(
+      existsSync(expectedPath),
+      `file must exist at OS-correct path: ${expectedPath}`,
+    );
+  });
+
+  it('written file content is readable via path.join on this platform', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const filePath = path.join(consumerDir, '.claude', 'agents', 'define.md');
+    let content;
+    assert.doesNotThrow(() => {
+      content = readFileSync(filePath, 'utf8');
+    });
+    assert.ok(hasMarker(content), 'written file must have the managed-by marker');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Lockfile path
+// ---------------------------------------------------------------------------
+
+describe('lockfile path — platform correct', () => {
+  it('lockfile is written at <consumerRoot>/.dev-agents-sync.json using path.join', async () => {
+    const consumerDir = makeTmpDir();
+    try {
+      await runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.2.0'],
+      });
+
+      const expectedLockfilePath = path.join(consumerDir, '.dev-agents-sync.json');
+      assert.ok(
+        existsSync(expectedLockfilePath),
+        `lockfile must exist at OS-correct path: ${expectedLockfilePath}`,
+      );
+    } finally {
+      rmSync(consumerDir, { recursive: true, force: true });
+    }
+  });
+});