@dalzoubi/dev-agents-sync 1.0.0

package/tests/fixtures/release-v1.0.0/claude/agents/define.md

@@ -0,0 +1,18 @@
+---
+name: "define"
+description: "Planning and analysis agent for spec-driven development."
+model: "opus"
+tools: [Read, Grep, Glob, WebFetch, WebSearch, Agent, TodoWrite, Write]
+---
+<!-- managed-by: dev-agents-sync v1.0.0 -->
+You are the **Define** agent: planning and analysis for spec-driven development.
+
+## Your posture
+
+Senior product-minded engineer. You do not write code. You produce a spec that is concrete enough for the Implement agent to execute.
+
+## Hard rules
+
+- **Read-only on source code.** You may only write the final spec markdown.
+- **One question at a time.** Never ask multi-part questions.
+- Honor the project's `CLAUDE.md` at the repo root.

package/tests/fixtures/release-v1.0.0/claude/agents/test.md

@@ -0,0 +1,17 @@
+---
+name: "test"
+description: "Test and quality agent. Creates unit, integration, and regression tests."
+model: "sonnet"
+tools: [Read, Edit, Write, Grep, Glob, Bash, TodoWrite, Agent]
+---
+<!-- managed-by: dev-agents-sync v1.0.0 -->
+You are the **Test** agent: test creation and bug reproduction.
+
+## Your posture
+
+Quality-minded engineer. You write tests that fail for the right reason, pass for the right reason.
+
+## Hard rules
+
+- **Edit test files only.**
+- Do not fix production code — that is the Implement agent's job.

package/tests/fixtures/release-v1.0.0/claude/commands/preflight.md

@@ -0,0 +1,7 @@
+---
+name: "preflight"
+description: "Pre-task orientation command. Run at the start of any session."
+tools: [Read, Grep, Glob]
+---
+<!-- managed-by: dev-agents-sync v1.0.0 -->
+Read CLAUDE.md and any AGENTS.md files. Orient yourself to the codebase before taking any action.

package/tests/fixtures/release-v1.0.0/cursor/rules/define.mdc

@@ -0,0 +1,16 @@
+---
+description: "Planning and analysis agent for spec-driven development."
+globs: []
+alwaysApply: false
+---
+<!-- managed-by: dev-agents-sync v1.0.0 -->
+You are the **Define** agent: planning and analysis for spec-driven development.
+
+## Your posture
+
+Senior product-minded engineer. You do not write code.
+
+## Hard rules
+
+- **Read-only on source code.**
+- **One question at a time.**

package/tests/fixtures/release-v1.0.0/cursor/rules/test.mdc

@@ -0,0 +1,15 @@
+---
+description: "Test and quality agent. Creates unit, integration, and regression tests."
+globs: []
+alwaysApply: false
+---
+<!-- managed-by: dev-agents-sync v1.0.0 -->
+You are the **Test** agent: test creation and bug reproduction.
+
+## Your posture
+
+Quality-minded engineer. You write tests that fail for the right reason.
+
+## Hard rules
+
+- **Edit test files only.**

package/tests/init.test.mjs

@@ -0,0 +1,514 @@
+/**
+ * tests/init.test.mjs
+ *
+ * Tests for the `init` subcommand.
+ *
+ * Strategy: inject a fixture-backed fetcher that returns the files from
+ * tests/fixtures/release-v1.0.0/ so no real GitHub calls are made.
+ *
+ * The fixture fetcher is a function:
+ *   async (repo, tag, token) => FileMap
+ *
+ * where FileMap is:  { [relativePath: string]: string (file content) }
+ *
+ * All tests use isolated tmp dirs so they never touch the real repo.
+ */
+
+import { describe, it, before, after, 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 { runInit } from '../src/commands/init.mjs';
+import { hasMarker } from '../src/marker.mjs';
+import { readLockfile } from '../src/lockfile.mjs';
+
+// ---------------------------------------------------------------------------
+// Fixture fetcher
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+/**
+ * Builds a FileMap from the fixture directory for a specific set of targets.
+ * Returns an object keyed by paths relative to the fixture root.
+ */
+function buildFixtureFileMap(targets = ['claude', 'cursor']) {
+  const map = {};
+  for (const target of targets) {
+    const targetDir = path.join(FIXTURE_DIR, target);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map);
+  }
+  return map;
+}
+
+function collectFiles(baseDir, currentDir, map) {
+  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);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[rel] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+/** Creates an injectable fixture fetcher for specific targets. */
+function makeFixtureFetcher(availableTags = ['v1.0.0', 'v1.1.0', 'v1.2.0']) {
+  return async (repo, tag) => {
+    // Simulate returning the fixture dist contents as a FileMap
+    // The target directories are returned regardless of which tag was requested
+    // (fixture is our stand-in for all tags).
+    return buildFixtureFileMap(['claude', 'cursor']);
+  };
+}
+
+/** Available tags list for resolving ranges in tests. */
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-init-test-'));
+}
+
+// ---------------------------------------------------------------------------
+// Clean repo — basic init
+// ---------------------------------------------------------------------------
+
+describe('init — clean repo', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('creates .dev-agents-sync.json with default range "^1"', async () => {
+    await runInit(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.equal(lockfile.range, '^1');
+  });
+
+  it('creates .dev-agents-sync.json with resolved version', async () => {
+    await runInit(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    // resolvedVersion must be the highest matching ^1 tag (1.2.0)
+    assert.equal(lockfile.resolvedVersion, '1.2.0');
+  });
+
+  it('creates .dev-agents-sync.json with source field', async () => {
+    await runInit(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.ok(lockfile.source, 'source field must be present');
+  });
+
+  it('writes managed files to .claude/ when targets includes claude', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(existsSync(path.join(consumerDir, '.claude')));
+  });
+
+  it('all written .claude files have the managed-by marker', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    if (existsSync(agentsDir)) {
+      const files = readdirSync(agentsDir);
+      for (const file of files) {
+        const content = readFileSync(path.join(agentsDir, file), 'utf8');
+        assert.ok(hasMarker(content), `file ${file} missing managed-by marker`);
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// --targets flag
+// ---------------------------------------------------------------------------
+
+describe('init — --targets flag', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('--targets claude writes only .claude/, no .cursor/', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(existsSync(path.join(consumerDir, '.claude')));
+    assert.ok(!existsSync(path.join(consumerDir, '.cursor')));
+  });
+
+  it('--targets claude records targets: ["claude"] in lockfile', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.deepEqual(lockfile.targets, ['claude']);
+  });
+
+  it('--targets cursor writes only .cursor/rules/, no .claude/', async () => {
+    await runInit(consumerDir, {
+      targets: ['cursor'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(existsSync(path.join(consumerDir, '.cursor')));
+    assert.ok(!existsSync(path.join(consumerDir, '.claude')));
+  });
+
+  it('--targets cursor records targets: ["cursor"] in lockfile', async () => {
+    await runInit(consumerDir, {
+      targets: ['cursor'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.deepEqual(lockfile.targets, ['cursor']);
+  });
+
+  it('--targets claude,cursor writes both directories', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude', 'cursor'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(existsSync(path.join(consumerDir, '.claude')));
+    assert.ok(existsSync(path.join(consumerDir, '.cursor')));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Auto-target detection
+// ---------------------------------------------------------------------------
+
+describe('init — auto-target detection', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('auto: picks claude only when .claude/ exists and .cursor/ does not', async () => {
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+
+    await runInit(consumerDir, {
+      targets: 'auto',
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.deepEqual(lockfile.targets, ['claude']);
+    assert.ok(!existsSync(path.join(consumerDir, '.cursor', 'rules')));
+  });
+
+  it('auto: picks cursor only when .cursor/ exists and .claude/ does not', async () => {
+    mkdirSync(path.join(consumerDir, '.cursor'), { recursive: true });
+
+    await runInit(consumerDir, {
+      targets: 'auto',
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.deepEqual(lockfile.targets, ['cursor']);
+    assert.ok(!existsSync(path.join(consumerDir, '.claude', 'agents')));
+  });
+
+  it('auto: picks both when neither .claude/ nor .cursor/ exists yet', async () => {
+    // No pre-existing directories
+    await runInit(consumerDir, {
+      targets: 'auto',
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    // Both should be recorded (the spec says "install both if neither directory exists")
+    assert.ok(
+      lockfile.targets.includes('claude') && lockfile.targets.includes('cursor'),
+      `expected both targets, got: ${JSON.stringify(lockfile.targets)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// --dry-run
+// ---------------------------------------------------------------------------
+
+describe('init — --dry-run', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('does not write any files to disk in dry-run mode', async () => {
+    const output = await runInit(consumerDir, {
+      targets: ['claude', 'cursor'],
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // Lockfile should NOT be created
+    assert.ok(
+      !existsSync(path.join(consumerDir, '.dev-agents-sync.json')),
+      'lockfile must not be created in dry-run mode',
+    );
+    // No .claude/ or .cursor/ should be created
+    assert.ok(!existsSync(path.join(consumerDir, '.claude')));
+    assert.ok(!existsSync(path.join(consumerDir, '.cursor')));
+  });
+
+  it('returns planned writes in dry-run mode', async () => {
+    const result = await runInit(consumerDir, {
+      targets: ['claude'],
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // The result should describe what would be written
+    assert.ok(result, 'dry-run must return a result object');
+    assert.ok(
+      result.plannedWrites !== undefined || result.files !== undefined || Array.isArray(result),
+      'dry-run result must include planned file list',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Unmanaged collision
+// ---------------------------------------------------------------------------
+
+describe('init — unmanaged collision', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('refuses to overwrite an unmanaged file (no marker), exit 1', async () => {
+    // Pre-create a file at a path that init would write
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    writeFileSync(path.join(agentsDir, 'define.md'), '# My custom define\nNo marker here.', 'utf8');
+
+    let exitCode;
+    try {
+      await runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFixtureFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'expected exit code 1 for unmanaged collision');
+  });
+
+  it('collision error message names the conflicting path', async () => {
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    writeFileSync(path.join(agentsDir, 'define.md'), '# Custom content', 'utf8');
+
+    let errorMessage = '';
+    try {
+      await runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFixtureFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      errorMessage = err.message;
+    }
+
+    assert.ok(
+      errorMessage.includes('define.md') || errorMessage.includes('.claude'),
+      `error message must name the conflicting path, got: ${errorMessage}`,
+    );
+  });
+
+  it('--force overwrites the unmanaged file', async () => {
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    const originalContent = '# My custom define\nNo marker here.';
+    writeFileSync(path.join(agentsDir, 'define.md'), originalContent, 'utf8');
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      force: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // File should now have the marker
+    const written = readFileSync(path.join(agentsDir, 'define.md'), 'utf8');
+    assert.ok(hasMarker(written), 'file should now have the managed-by marker after --force');
+  });
+
+  it('overwrites a file that already has the marker (managed file, no --force needed)', async () => {
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    // Pre-create a managed file (with marker)
+    writeFileSync(
+      path.join(agentsDir, 'define.md'),
+      '---\nname: "define"\n---\n<!-- managed-by: dev-agents-sync v0.9.0 -->\nOld content.',
+      'utf8',
+    );
+
+    // Should not throw — managed files are safe to overwrite
+    await assert.doesNotReject(
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFixtureFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Non-interactive by default
+// ---------------------------------------------------------------------------
+
+describe('init — non-interactive default', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('completes without prompting when called programmatically (--yes implicit)', async () => {
+    // If init tries to prompt interactively this would hang — it must not.
+    // We set a short timeout to detect hangs.
+    await assert.doesNotReject(
+      Promise.race([
+        runInit(consumerDir, {
+          targets: ['claude'],
+          fetcher: makeFixtureFetcher(),
+          availableTags: AVAILABLE_TAGS,
+        }),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('init timed out — likely prompting interactively')), 3000),
+        ),
+      ]),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Custom range
+// ---------------------------------------------------------------------------
+
+describe('init — custom --range', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('records the custom range in the lockfile', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      range: '~1.1',
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.equal(lockfile.range, '~1.1');
+  });
+
+  it('resolves to the latest patch for a tilde range', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      range: '~1.0',
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfile = readLockfile(consumerDir);
+    assert.equal(lockfile.resolvedVersion, '1.0.0');
+  });
+});