@dalzoubi/dev-agents-sync 1.0.14 → 1.0.16

package/tests/root-target.test.mjs

@@ -0,0 +1,440 @@
+/**
+ * tests/root-target.test.mjs
+ *
+ * Tests for the `root` target prefix:
+ * - resolveConsumerPath maps root/ keys to the consumer repo root
+ * - normalizeFileMap preserves root/ keys without warning or dropping
+ * - init/update emit root-targeted files unconditionally (regardless of lockfile targets)
+ * - check evaluates root-targeted files unconditionally
+ * - writeManagedFile refuses to overwrite a root-targeted file whose marker is not on the first line
+ * - existing .claude/.cursor/.github first-time creations remain silent (no regression)
+ */
+
+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 { resolveConsumerPath, normalizeFileMap, writeManagedFile } from '../src/writer.mjs';
+import { hasMarkerOnFirstLine } from '../src/marker.mjs';
+import { runInit } from '../src/commands/init.mjs';
+import { runUpdate } from '../src/commands/update.mjs';
+import { runCheck } from '../src/commands/check.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');
+
+const CONSTITUTION_FIXTURE = readFileSync(
+  path.join(FIXTURE_DIR, 'root', 'CONSTITUTION.md'),
+  'utf8',
+);
+
+function buildFixtureFileMap(targets = ['claude', 'cursor', 'root']) {
+  const map = {};
+  for (const t of targets) {
+    const targetDir = path.join(FIXTURE_DIR, t);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, t);
+  }
+  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 makeFullFetcher() {
+  return async () => buildFixtureFileMap(['claude', 'cursor', 'root']);
+}
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-root-test-'));
+}
+
+// ---------------------------------------------------------------------------
+// resolveConsumerPath — root target
+// ---------------------------------------------------------------------------
+
+describe('resolveConsumerPath — root target', () => {
+  it('maps root/CONSTITUTION.md to <consumerRoot>/CONSTITUTION.md', () => {
+    const root = '/some/consumer';
+    const result = resolveConsumerPath(root, 'root/CONSTITUTION.md');
+    assert.equal(result, path.join(root, 'CONSTITUTION.md'));
+  });
+
+  it('maps root/NESTED/FILE.md to <consumerRoot>/NESTED/FILE.md', () => {
+    const root = '/some/consumer';
+    const result = resolveConsumerPath(root, 'root/NESTED/FILE.md');
+    assert.equal(result, path.join(root, 'NESTED', 'FILE.md'));
+  });
+
+  it('still rejects path traversal in root-targeted paths', () => {
+    assert.throws(
+      () => resolveConsumerPath('/consumer', 'root/../etc/passwd'),
+      /traversal/i,
+    );
+  });
+
+  it('still rejects target-only root path (no file segment)', () => {
+    assert.throws(
+      () => resolveConsumerPath('/consumer', 'root'),
+      /target only/i,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeFileMap — root keys
+// ---------------------------------------------------------------------------
+
+describe('normalizeFileMap — root/ keys are preserved without warning', () => {
+  it('passes through root/CONSTITUTION.md untouched', () => {
+    const out = normalizeFileMap({ 'root/CONSTITUTION.md': 'content' });
+    assert.equal(out['root/CONSTITUTION.md'], 'content');
+  });
+
+  it('does not warn when processing root/ keys', () => {
+    const origWrite = process.stderr.write.bind(process.stderr);
+    let captured = '';
+    process.stderr.write = (chunk) => {
+      captured += typeof chunk === 'string' ? chunk : chunk.toString();
+      return true;
+    };
+    try {
+      normalizeFileMap({ 'root/CONSTITUTION.md': 'content', 'claude/agents/define.md': 'A' });
+      assert.equal(captured, '', `expected no stderr for root/ keys, got: ${captured}`);
+    } finally {
+      process.stderr.write = origWrite;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// writeManagedFile — root target marker enforcement
+// ---------------------------------------------------------------------------
+
+describe('writeManagedFile — root target first-line marker enforcement', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('refuses to overwrite a root-targeted file that has no marker', () => {
+    const absPath = path.join(tmpDir, 'CONSTITUTION.md');
+    writeFileSync(absPath, '# My Constitution\nNo marker here.\n', 'utf8');
+
+    assert.throws(
+      () => writeManagedFile({ absPath, relKey: 'root/CONSTITUTION.md', content: 'new', force: false }),
+      /unmanaged|marker|force/i,
+    );
+  });
+
+  it('refuses to overwrite a root-targeted file whose marker is not the first physical line', () => {
+    const absPath = path.join(tmpDir, 'CONSTITUTION.md');
+    // Marker exists but buried after a blank line
+    writeFileSync(
+      absPath,
+      '\n<!-- managed-by: dev-agents-sync v1.0.0 -->\n# Constitution\n',
+      'utf8',
+    );
+
+    assert.throws(
+      () => writeManagedFile({ absPath, relKey: 'root/CONSTITUTION.md', content: 'new', force: false }),
+      /unmanaged|marker|force/i,
+    );
+  });
+
+  it('allows overwriting a root-targeted file when marker is the literal first line', () => {
+    const absPath = path.join(tmpDir, 'CONSTITUTION.md');
+    writeFileSync(
+      absPath,
+      '<!-- managed-by: dev-agents-sync v1.0.0 -->\n# Constitution\nConstitution version: v1\n',
+      'utf8',
+    );
+
+    assert.doesNotThrow(() =>
+      writeManagedFile({
+        absPath,
+        relKey: 'root/CONSTITUTION.md',
+        content: '<!-- managed-by: dev-agents-sync v1.1.0 -->\n# Constitution\nConstitution version: v2\n',
+        force: false,
+      }),
+    );
+
+    const written = readFileSync(absPath, 'utf8');
+    assert.ok(written.includes('v1.1.0'));
+  });
+
+  it('--force overwrites even when root-targeted file has no marker', () => {
+    const absPath = path.join(tmpDir, 'CONSTITUTION.md');
+    writeFileSync(absPath, '# No marker\n', 'utf8');
+
+    assert.doesNotThrow(() =>
+      writeManagedFile({
+        absPath,
+        relKey: 'root/CONSTITUTION.md',
+        content: '<!-- managed-by: dev-agents-sync v1.0.0 -->\n# Constitution\n',
+        force: true,
+      }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// init — unconditional root emission
+// ---------------------------------------------------------------------------
+
+describe('init — root-targeted files emitted unconditionally', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('emits CONSTITUTION.md at consumer root even when targets is ["cursor"]', async () => {
+    await runInit(consumerDir, {
+      targets: ['cursor'],
+      fetcher: makeFullFetcher(),
+      availableTags: ['v1.0.0'],
+    });
+
+    const constitutionPath = path.join(consumerDir, 'CONSTITUTION.md');
+    assert.ok(existsSync(constitutionPath), 'CONSTITUTION.md must exist at consumer root');
+
+    const content = readFileSync(constitutionPath, 'utf8');
+    assert.ok(hasMarkerOnFirstLine(content), 'marker must be the first physical line');
+    assert.ok(content.includes('Constitution version: v1'), 'body version line must be present');
+  });
+
+  it('emits CONSTITUTION.md even when targets is ["claude"]', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFullFetcher(),
+      availableTags: ['v1.0.0'],
+    });
+
+    assert.ok(
+      existsSync(path.join(consumerDir, 'CONSTITUTION.md')),
+      'CONSTITUTION.md must exist regardless of claude-only targets',
+    );
+  });
+
+  it('still writes claude/ files when targets includes claude (no regression)', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFullFetcher(),
+      availableTags: ['v1.0.0'],
+    });
+
+    assert.ok(
+      existsSync(path.join(consumerDir, '.claude', 'agents', 'define.md')),
+      '.claude/agents/define.md must still be written',
+    );
+  });
+
+  it('refuses to overwrite an unmanaged CONSTITUTION.md without --force', async () => {
+    writeFileSync(path.join(consumerDir, 'CONSTITUTION.md'), '# My custom\n', 'utf8');
+
+    await assert.rejects(
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+      }),
+      /unmanaged|marker|force/i,
+    );
+  });
+
+  it('refuses to overwrite a CONSTITUTION.md whose marker is buried after a blank line (H1 regression)', async () => {
+    // Marker exists but is NOT the first physical line — should be treated as unmanaged
+    writeFileSync(
+      path.join(consumerDir, 'CONSTITUTION.md'),
+      '\n<!-- managed-by: dev-agents-sync v1.0.0 -->\n# Constitution\n',
+      'utf8',
+    );
+
+    await assert.rejects(
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+      }),
+      /unmanaged|marker|force/i,
+    );
+  });
+
+  it('lockfile targets array does not contain "root" after init', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFullFetcher(),
+      availableTags: ['v1.0.0'],
+    });
+
+    const lockRaw = readFileSync(
+      path.join(consumerDir, '.dev-agents-sync.json'),
+      'utf8',
+    );
+    const lock = JSON.parse(lockRaw);
+    assert.ok(!lock.targets.includes('root'), 'lockfile targets must not include "root"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// update — unconditional root emission
+// ---------------------------------------------------------------------------
+
+describe('update — root-targeted files emitted unconditionally', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('emits CONSTITUTION.md when lockfile targets is ["cursor"] only', async () => {
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['cursor'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+    // pre-write a cursor file so update has something to compare
+    const rulesDir = path.join(consumerDir, '.cursor', 'rules');
+    mkdirSync(rulesDir, { recursive: true });
+    writeFileSync(
+      path.join(rulesDir, 'define.mdc'),
+      readFileSync(path.join(FIXTURE_DIR, 'cursor', 'rules', 'define.mdc'), 'utf8'),
+      'utf8',
+    );
+
+    // Update with a fetcher that simulates v1.1.0 (updated marker only)
+    const v110Fetcher = async () => {
+      const base = buildFixtureFileMap(['claude', 'cursor', 'root']);
+      const updated = {};
+      for (const [key, content] of Object.entries(base)) {
+        updated[key] = content.replace('v1.0.0', 'v1.1.0');
+      }
+      return updated;
+    };
+
+    await runUpdate(consumerDir, {
+      fetcher: v110Fetcher,
+      availableTags: ['v1.0.0', 'v1.1.0'],
+    });
+
+    const constitutionPath = path.join(consumerDir, 'CONSTITUTION.md');
+    assert.ok(existsSync(constitutionPath), 'CONSTITUTION.md must be emitted on update');
+    const content = readFileSync(constitutionPath, 'utf8');
+    assert.ok(hasMarkerOnFirstLine(content), 'marker must be first line after update');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// check — unconditional root evaluation
+// ---------------------------------------------------------------------------
+
+describe('check — root-targeted files checked unconditionally', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('exits 1 (drift) when CONSTITUTION.md is missing even with cursor-only targets', async () => {
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['cursor'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+    // CONSTITUTION.md intentionally not written
+
+    await assert.rejects(
+      runCheck(consumerDir, { fetcher: makeFullFetcher() }),
+      /drift/i,
+    );
+  });
+
+  it('exits 1 (drift) when CONSTITUTION.md content differs from expected (version line edited)', async () => {
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    // Write a tampered CONSTITUTION.md (changed version line)
+    const tampered = CONSTITUTION_FIXTURE.replace(
+      'Constitution version: v1',
+      'Constitution version: v2',
+    );
+    writeFileSync(path.join(consumerDir, 'CONSTITUTION.md'), tampered, 'utf8');
+
+    // Also write the claude agent so that target isn't missing
+    mkdirSync(path.join(consumerDir, '.claude', 'agents'), { recursive: true });
+    writeFileSync(
+      path.join(consumerDir, '.claude', 'agents', 'define.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'), 'utf8'),
+      'utf8',
+    );
+
+    await assert.rejects(
+      runCheck(consumerDir, { fetcher: makeFullFetcher() }),
+      /drift/i,
+    );
+  });
+
+  it('exits 0 when CONSTITUTION.md matches expected exactly', async () => {
+    // Use a fetcher that returns only root + one claude file to keep the
+    // test setup minimal and deterministic.
+    const minimalFetcher = async () => ({
+      'root/CONSTITUTION.md': CONSTITUTION_FIXTURE,
+      'claude/agents/define.md': readFileSync(
+        path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'),
+        'utf8',
+      ),
+    });
+
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    writeFileSync(path.join(consumerDir, 'CONSTITUTION.md'), CONSTITUTION_FIXTURE, 'utf8');
+
+    mkdirSync(path.join(consumerDir, '.claude', 'agents'), { recursive: true });
+    writeFileSync(
+      path.join(consumerDir, '.claude', 'agents', 'define.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'), 'utf8'),
+      'utf8',
+    );
+
+    await assert.doesNotReject(runCheck(consumerDir, { fetcher: minimalFetcher }));
+  });
+});