@dalzoubi/dev-agents-sync 2.0.6 → 2.0.8

package/tests/codex-target.test.mjs

@@ -0,0 +1,375 @@
+/**
+ * tests/codex-target.test.mjs
+ *
+ * RED tests (slice: codex-writer-and-lockfile) — pin the codex target contract
+ * BEFORE implementation so that implement cannot accidentally skip a case.
+ *
+ * Contract:
+ *  - TARGET_PREFIX.codex = '' (repo root — same strategy as "root" target).
+ *  - FileMap keys carry the full repo-root-relative path: "codex/..." prefix.
+ *  - resolveConsumerPath(root, 'codex/.agents/skills/define/SKILL.md')
+ *      → <root>/.agents/skills/define/SKILL.md
+ *  - resolveConsumerPath(root, 'codex/AGENTS.md') → <root>/AGENTS.md
+ *  - normalizeFileMap PRESERVES 'codex/...' keys (currently drops them).
+ *  - validateLockfile ACCEPTS targets containing 'codex' (currently rejects).
+ *  - Backward-compat: legacy lockfiles (no codex) still validate + serialize
+ *    byte-identically.
+ *  - serializeLockfile sorts targets including 'codex'.
+ *  - Schema: lockfile.schema.json does NOT exist locally; test documents this.
+ *
+ * Status markers per assertion (pre-implement):
+ *   RED  — expected to fail against current source until implement runs.
+ *   GREEN — expected to pass against current source (backward compat / safety).
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { resolveConsumerPath, normalizeFileMap } from '../src/writer.mjs';
+import {
+  validateLockfile,
+  serializeLockfile,
+  SCHEMA_URL,
+} from '../src/lockfile.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Shared fixture — a minimal valid legacy lockfile (no codex)
+// ---------------------------------------------------------------------------
+
+const LEGACY_LOCKFILE = {
+  $schema: SCHEMA_URL,
+  source: 'github:dalzoubi/dev-agents',
+  range: '^1',
+  resolvedVersion: '1.0.0',
+  targets: ['claude', 'cursor'],
+  lastUpdated: '2026-04-24T00:00:00Z',
+};
+
+// ---------------------------------------------------------------------------
+// 1–2. resolveConsumerPath — codex target path translation
+// ---------------------------------------------------------------------------
+
+describe('resolveConsumerPath — codex target', () => {
+  const root = '/some/consumer';
+
+  // RED: 'codex' is not in TARGET_PREFIX — currently throws "unknown target prefix"
+  it('translates codex/.agents/skills/define/SKILL.md to <root>/.agents/skills/define/SKILL.md', () => {
+    const result = resolveConsumerPath(root, 'codex/.agents/skills/define/SKILL.md');
+    const expected = path.join(root, '.agents', 'skills', 'define', 'SKILL.md');
+    assert.equal(result, expected);
+  });
+
+  // RED: same root, different agent slug
+  it('translates codex/.agents/skills/implement/SKILL.md to <root>/.agents/skills/implement/SKILL.md', () => {
+    const result = resolveConsumerPath(root, 'codex/.agents/skills/implement/SKILL.md');
+    const expected = path.join(root, '.agents', 'skills', 'implement', 'SKILL.md');
+    assert.equal(result, expected);
+  });
+
+  // RED: third representative agent
+  it('translates codex/.agents/skills/test/SKILL.md to <root>/.agents/skills/test/SKILL.md', () => {
+    const result = resolveConsumerPath(root, 'codex/.agents/skills/test/SKILL.md');
+    const expected = path.join(root, '.agents', 'skills', 'test', 'SKILL.md');
+    assert.equal(result, expected);
+  });
+
+  // RED: repo-root file — codex/AGENTS.md → <root>/AGENTS.md (not nested under a subdir)
+  it('translates codex/AGENTS.md to <root>/AGENTS.md (repo root, not nested)', () => {
+    const result = resolveConsumerPath(root, 'codex/AGENTS.md');
+    const expected = path.join(root, 'AGENTS.md');
+    assert.equal(result, expected);
+    // Must NOT include any extra directory segment between root and AGENTS.md
+    const relative = path.relative(root, result);
+    assert.equal(relative, 'AGENTS.md', 'AGENTS.md must resolve directly under consumer root');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. normalizeFileMap — codex keys must be preserved, not dropped
+// ---------------------------------------------------------------------------
+
+describe('normalizeFileMap — codex/ keys', () => {
+  // RED: 'codex' is not in the recognized-prefix allow-list — currently dropped
+  it('preserves codex/.agents/skills/define/SKILL.md in normalized output', () => {
+    const out = normalizeFileMap({
+      'codex/.agents/skills/define/SKILL.md': 'skill-content',
+    });
+    assert.equal(
+      out['codex/.agents/skills/define/SKILL.md'],
+      'skill-content',
+      'codex key must not be dropped by normalizeFileMap',
+    );
+  });
+
+  // RED: preserves codex/AGENTS.md too
+  it('preserves codex/AGENTS.md in normalized output', () => {
+    const out = normalizeFileMap({
+      'codex/AGENTS.md': 'agents-content',
+    });
+    assert.equal(
+      out['codex/AGENTS.md'],
+      'agents-content',
+      'codex/AGENTS.md must not be dropped by normalizeFileMap',
+    );
+  });
+
+  // RED: does not warn for codex/ keys (parallel to root-target behavior)
+  it('does not emit a stderr warning for codex/ 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({
+        'codex/.agents/skills/define/SKILL.md': 'A',
+        'codex/AGENTS.md': 'B',
+      });
+      assert.equal(
+        captured,
+        '',
+        `expected no stderr warning for recognized codex/ keys, got: ${JSON.stringify(captured)}`,
+      );
+    } finally {
+      process.stderr.write = origWrite;
+    }
+  });
+
+  // GREEN: an unrecognized prefix still gets dropped (the allow-list stays conservative)
+  it('still drops a genuinely unrecognized prefix (bogus/x.md)', () => {
+    const origWrite = process.stderr.write.bind(process.stderr);
+    let captured = '';
+    process.stderr.write = (chunk) => {
+      captured += typeof chunk === 'string' ? chunk : chunk.toString();
+      return true;
+    };
+    try {
+      const out = normalizeFileMap({
+        'bogus/x.md': 'should-be-dropped',
+        'codex/.agents/skills/define/SKILL.md': 'should-be-kept',
+      });
+      assert.equal(out['bogus/x.md'], undefined, 'bogus prefix must still be dropped');
+      assert.ok(captured.includes('warn:'), `expected stderr warn for bogus key, got: ${captured}`);
+      assert.ok(captured.includes("'bogus/x.md'"), `warn must name the dropped key, got: ${captured}`);
+    } finally {
+      process.stderr.write = origWrite;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Path traversal — codex target must still enforce traversal safety
+// ---------------------------------------------------------------------------
+
+describe('resolveConsumerPath — traversal safety with codex prefix', () => {
+  const root = '/some/consumer';
+
+  // GREEN: traversal within any prefix must be rejected regardless of the prefix name
+  // (This should already pass once codex is in TARGET_PREFIX, because the
+  //  traversal check runs before the TARGET_PREFIX lookup. We assert it here
+  //  so the impl can never regress on this.)
+  it('throws on path traversal via codex/../../etc/passwd', () => {
+    assert.throws(
+      () => resolveConsumerPath(root, 'codex/../../etc/passwd'),
+      /traversal|invalid|outside/i,
+      'traversal via codex prefix must be rejected',
+    );
+  });
+
+  it('throws on path traversal via codex/../../../etc/passwd', () => {
+    assert.throws(
+      () => resolveConsumerPath(root, 'codex/../../../etc/passwd'),
+      /traversal|invalid|outside/i,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. validateLockfile — accepts targets containing 'codex'
+// ---------------------------------------------------------------------------
+
+describe('validateLockfile — codex in targets', () => {
+  // RED: VALID_TARGETS does not include 'codex' — currently throws
+  it('accepts targets: ["codex"]', () => {
+    assert.doesNotThrow(
+      () =>
+        validateLockfile({
+          ...LEGACY_LOCKFILE,
+          targets: ['codex'],
+        }),
+      'validateLockfile must accept a codex-only targets array',
+    );
+  });
+
+  // RED: mixed targets including codex
+  it('accepts targets: ["claude", "codex"]', () => {
+    assert.doesNotThrow(
+      () =>
+        validateLockfile({
+          ...LEGACY_LOCKFILE,
+          targets: ['claude', 'codex'],
+        }),
+      'validateLockfile must accept ["claude", "codex"]',
+    );
+  });
+
+  // RED: all known targets including codex
+  it('accepts targets: ["claude", "codex", "copilot", "cursor"]', () => {
+    assert.doesNotThrow(
+      () =>
+        validateLockfile({
+          ...LEGACY_LOCKFILE,
+          targets: ['claude', 'codex', 'copilot', 'cursor'],
+        }),
+      'validateLockfile must accept the full set of valid targets',
+    );
+  });
+
+  // GREEN: genuinely unknown targets still rejected (conservative allow-list)
+  it('still rejects an unknown target value (e.g. "vscode")', () => {
+    assert.throws(
+      () =>
+        validateLockfile({
+          ...LEGACY_LOCKFILE,
+          targets: ['claude', 'vscode'],
+        }),
+      /targets/i,
+      'non-codex unknown targets must still be rejected',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Backward-compat: legacy lockfile (no codex) still validates and serializes
+//    byte-identically — no new fields introduced, field order unchanged.
+// ---------------------------------------------------------------------------
+
+describe('backward-compat — legacy lockfile round-trip', () => {
+  // GREEN: existing consumers not using codex must be unaffected
+  it('validateLockfile still accepts a legacy lockfile with targets: ["claude"]', () => {
+    assert.doesNotThrow(
+      () =>
+        validateLockfile({
+          ...LEGACY_LOCKFILE,
+          targets: ['claude'],
+        }),
+    );
+  });
+
+  // GREEN: serialization of a legacy lockfile must be byte-identical before and after
+  // the codex change — FIELD_ORDER must not gain new entries, no manifest key added.
+  it('serializeLockfile of a legacy lockfile matches exact expected JSON (FIELD_ORDER lock)', () => {
+    const expected =
+      '{\n' +
+      `  "$schema": "${SCHEMA_URL}",\n` +
+      '  "source": "github:dalzoubi/dev-agents",\n' +
+      '  "range": "^1",\n' +
+      '  "resolvedVersion": "1.0.0",\n' +
+      '  "targets": [\n' +
+      '    "claude",\n' +
+      '    "cursor"\n' +
+      '  ],\n' +
+      '  "lastUpdated": "2026-04-24T00:00:00Z"\n' +
+      '}\n';
+
+    const actual = serializeLockfile(LEGACY_LOCKFILE);
+    assert.equal(
+      actual,
+      expected,
+      'serialized legacy lockfile must be byte-identical to expected (field order + no extra fields)',
+    );
+  });
+
+  // GREEN: no new top-level keys appear in the serialized output
+  it('serialized legacy lockfile does not contain a "codex" key at any level', () => {
+    const serialized = serializeLockfile(LEGACY_LOCKFILE);
+    const parsed = JSON.parse(serialized);
+    assert.ok(
+      !Object.keys(parsed).includes('codex'),
+      'serialized lockfile must not have a top-level "codex" key',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. serializeLockfile — sorts targets including 'codex'
+// ---------------------------------------------------------------------------
+
+describe('serializeLockfile — target sorting with codex', () => {
+  // RED: if validateLockfile rejects codex, serializeLockfile would never be
+  // reached. Once implement adds codex to VALID_TARGETS, these assertions
+  // confirm the sort order is correct.
+  it('sorts ["codex","claude"] → ["claude","codex"] in serialized output', () => {
+    const lock = { ...LEGACY_LOCKFILE, targets: ['codex', 'claude'] };
+    // Bypass validateLockfile — we're testing serializeLockfile's sort in isolation.
+    // serializeLockfile does not call validateLockfile internally.
+    const serialized = serializeLockfile(lock);
+    const parsed = JSON.parse(serialized);
+    assert.deepEqual(
+      parsed.targets,
+      ['claude', 'codex'],
+      'targets must be sorted alphabetically',
+    );
+  });
+
+  it('sorts ["cursor","codex","claude"] → ["claude","codex","cursor"]', () => {
+    const lock = { ...LEGACY_LOCKFILE, targets: ['cursor', 'codex', 'claude'] };
+    const serialized = serializeLockfile(lock);
+    const parsed = JSON.parse(serialized);
+    assert.deepEqual(parsed.targets, ['claude', 'codex', 'cursor']);
+  });
+
+  // GREEN: existing sort behavior for targets without codex is unchanged
+  it('sorts ["cursor","claude"] → ["claude","cursor"] (regression — no codex)', () => {
+    const lock = { ...LEGACY_LOCKFILE, targets: ['cursor', 'claude'] };
+    const serialized = serializeLockfile(lock);
+    const parsed = JSON.parse(serialized);
+    assert.deepEqual(parsed.targets, ['claude', 'cursor']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. Schema: lockfile.schema.json local presence + enum check
+// ---------------------------------------------------------------------------
+
+describe('lockfile schema — local file presence and enum constraint', () => {
+  // This test documents the schema state so the implementer knows whether a
+  // schema edit is required as part of the codex slice.
+  //
+  // Current finding: schema/lockfile.schema.json does NOT exist in this repo.
+  // The SCHEMA_URL in lockfile.mjs points to a remote file at the published
+  // GitHub raw URL. No local enum validation is enforced by the CLI's own code.
+  // The implementer does NOT need to create/update a local schema file for the
+  // codex target change (VALID_TARGETS in lockfile.mjs is the authoritative
+  // allow-list). If a local schema file is introduced in the future, it must
+  // include 'codex' in the targets enum.
+
+  it('schema/lockfile.schema.json does NOT exist locally (remote schema only)', () => {
+    const schemaPath = path.join(__dirname, '..', '..', '..', 'schema', 'lockfile.schema.json');
+    assert.equal(
+      existsSync(schemaPath),
+      false,
+      [
+        'schema/lockfile.schema.json must not exist locally.',
+        'If it does exist, add "codex" to its targets enum.',
+        `Checked path: ${schemaPath}`,
+      ].join(' '),
+    );
+  });
+
+  // GREEN (informational): the SCHEMA_URL constant points to a versioned remote URL.
+  // It must not be empty, and must reference the known repo path.
+  it('SCHEMA_URL is a non-empty string referencing the dalzoubi/dev-agents repo', () => {
+    assert.ok(typeof SCHEMA_URL === 'string' && SCHEMA_URL.length > 0, 'SCHEMA_URL must be a non-empty string');
+    assert.ok(
+      SCHEMA_URL.includes('dalzoubi/dev-agents'),
+      `SCHEMA_URL must reference the dalzoubi/dev-agents repo, got: ${SCHEMA_URL}`,
+    );
+  });
+});