@dalzoubi/dev-agents-sync 2.0.6 → 2.0.8

package/README.md

@@ -41,6 +41,24 @@ npx --yes @dalzoubi/dev-agents-sync@1 init --targets claude
 This writes managed files into `.claude/` and creates `.dev-agents-sync.json` with the resolved content version.
 Use `--targets cursor` or `--targets claude,cursor` to install Cursor project agents, rules, and slash commands into `.cursor/agents/`, `.cursor/rules/`, and `.cursor/commands/`.
 
+### OpenAI Codex target
+
+To adopt the toolkit with OpenAI Codex, pass the `codex` target explicitly:
+
+```bash
+npx --yes @dalzoubi/dev-agents-sync@1 init --targets codex
+```
+
+Codex is **opt-in only**. Unlike other targets there is no filesystem signal to detect (there is no `.codex/` directory), so `codex` is never auto-selected — you must pass `--targets codex` explicitly. You can combine it with other targets, e.g. `--targets claude,codex`.
+
+**Output shape.** `init --targets codex` writes six directory-per-skill files — one per agent — at `.agents/skills/<agent>/SKILL.md` (`analyze`, `define`, `implement`, `supervise`, `test`, `validate`), plus a thin root `AGENTS.md` index. Codex discovers these by scanning from the working directory up to the repo root, so each agent lives at its own `.agents/skills/<agent>/SKILL.md` path. Every file carries the managed-by marker, and `update` and `check` scope to these paths exactly like the other targets.
+
+**Model-invoked, not slash commands.** Codex Agent Skills are model-invoked: a Codex user triggers an agent through `/skills`, a `$<name>` mention, or implicit selection by the model — *not* by typing a literal `/define`-style slash command the way Claude commands work. This is an accepted approximation of the slash-command UX the other targets provide; the agent content is the same, only the invocation differs.
+
+**Manual removal.** Like every target, there is no uninstall or cleanup command. Dropping `codex` from the `targets` in `.dev-agents-sync.json` stops future writes, but the already-written `.agents/skills/<agent>/SKILL.md` directories and the root `AGENTS.md` are removed manually.
+
+> **Maintainer note — two file shapes.** Do not confuse the Codex output with this toolkit's own authoring sources. In the `dalzoubi/dev-agents` repo, the canonical skill sources are **flat single files** at `.agents/skills/*.md`. The Codex target **output** is the **directory-per-skill** form `.agents/skills/<agent>/SKILL.md`. Both share the `.agents/skills/` prefix, but the flat `.md` files are for authoring and the `SKILL.md` directories are the generated codex output shape.
+
 As part of `init`, the CLI injects an auto-routing fenced block into `CLAUDE.md` (creating the file if it does not exist). The block tells Claude Code how to route tasks to the correct agent. It is delimited by:
 
 ```html
@@ -113,7 +131,7 @@ and build if relevant) and summarizes what changed. It does not push or open a P
 
 ## Common Flags
 
-- `--targets claude,cursor` selects output targets. Use `claude`, `cursor`, or both.
+- `--targets claude,cursor` selects output targets. Use `claude`, `cursor`, `copilot`, `codex`, or any comma-separated combination. `codex` is opt-in only — see [OpenAI Codex target](#openai-codex-target).
 - `--range ^1` selects the content version range. The default is `^1`.
 - `--dry-run` prints the planned changes without writing files.
 - `--force` allows overwriting unmanaged file collisions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/lockfile.mjs

@@ -16,7 +16,7 @@ export const SCHEMA_URL =
 
 // TODO(ask-first follow-up): simplify targets — once all consumers adopt Copilot,
 // adding 'cursor' could auto-include 'copilot' so callers don't need to list both.
-const VALID_TARGETS = new Set(['claude', 'cursor', 'copilot']);
+const VALID_TARGETS = new Set(['claude', 'cursor', 'copilot', 'codex']);
 
 // Field order is load-bearing for determinism.
 const FIELD_ORDER = [

package/src/writer.mjs

@@ -19,6 +19,10 @@ const TARGET_PREFIX = {
   // root resolves to the consumer repo root (empty prefix, no subdirectory).
   // Root-targeted files are emitted unconditionally regardless of the lockfile's targets.
   root: '',
+  // codex keys carry a full repo-root-relative path (e.g. "codex/.agents/skills/define/SKILL.md",
+  // "codex/AGENTS.md"), so they resolve against an empty prefix just like `root`.
+  // The shared '' value with `root` is intentional — they are distinct keys, not a duplicate to "fix".
+  codex: '',
 };
 
 // Subdirectories that uniquely identify a target. Used to normalize
@@ -43,7 +47,15 @@ export function normalizeFileMap(fileMap) {
   for (const [key, content] of Object.entries(fileMap)) {
     const norm = key.replace(/\\/g, '/');
     const first = norm.split('/')[0];
-    if (first === 'claude' || first === 'cursor' || first === 'copilot' || first === 'root') {
+    // codex keys carry a full repo-root-relative path and resolve via the empty
+    // TARGET_PREFIX.codex (mirrors `root`), so they must be preserved here too.
+    if (
+      first === 'claude' ||
+      first === 'cursor' ||
+      first === 'copilot' ||
+      first === 'root' ||
+      first === 'codex'
+    ) {
       out[norm] = content;
       continue;
     }

package/tests/codex-cross-cutting.test.mjs

@@ -0,0 +1,411 @@
+/**
+ * tests/codex-cross-cutting.test.mjs
+ *
+ * Cross-cutting matrix sanity for the codex target feature (S4).
+ *
+ * This file covers two distinct concerns:
+ *
+ *   A. Test-file existence sanity — confirms the three S1–S3 codex test files
+ *      exist and that the spec test plan behaviors are addressed by them. This
+ *      acts as a guard that prevents silent deletion or rename of the test files
+ *      across future refactors.
+ *
+ *   B. filterFileMapByTargets behavioral parity — the function is duplicated
+ *      identically in update.mjs and check.mjs (and with a minor variant in
+ *      init.mjs and diff.mjs). Since there is no shared module, behavioral drift
+ *      between the update.mjs and check.mjs copies is a known risk documented in
+ *      the spec ("consolidation candidate"). This test asserts that both copies
+ *      produce identical output for codex-prefix inputs, including the `root`-
+ *      always-included behavior, so a future consolidation cannot accidentally
+ *      regress one copy.
+ *
+ * These tests do NOT duplicate assertions already covered by S1–S3 tests. They
+ * are lightweight regression guards on the shape and parity of the test suite
+ * itself.
+ *
+ * GUARDRAIL: This test file does not import production modules directly for the
+ * duplication check — instead it imports the commands under test via their
+ * exported runUpdate / runCheck functions and exercises the codex prefix through
+ * those public interfaces, keeping production coupling to a minimum.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const REPO_ROOT = path.join(PACKAGE_ROOT, '..', '..');
+
+// ---------------------------------------------------------------------------
+// A. Test-file existence sanity
+//
+// Asserts the three S1–S3 codex test files exist at their canonical paths.
+// A rename or deletion would make these RED immediately, signalling that the
+// spec's test plan coverage has been broken.
+// ---------------------------------------------------------------------------
+
+describe('codex test-file existence sanity', () => {
+  it('S1 codex-emitter test file exists at tests/codex-emitter.test.mjs (repo root)', () => {
+    const p = path.join(REPO_ROOT, 'tests', 'codex-emitter.test.mjs');
+    assert.ok(
+      existsSync(p),
+      `S1 test file must exist at ${p}.\n` +
+      'This file guards: six SKILL.md files emitted, frontmatter reduced, full body ' +
+      'inlined, marker placement, thin AGENTS.md, determinism, --mirror-codex flag.',
+    );
+  });
+
+  it('S2 codex-target test file exists at packages/dev-agents-sync/tests/codex-target.test.mjs', () => {
+    const p = path.join(PACKAGE_ROOT, 'tests', 'codex-target.test.mjs');
+    assert.ok(
+      existsSync(p),
+      `S2 test file must exist at ${p}.\n` +
+      'This file guards: resolveConsumerPath codex path translation, normalizeFileMap ' +
+      'allow-list, validateLockfile codex acceptance, backward-compat, sort order.',
+    );
+  });
+
+  it('S3 codex-init-check test file exists at packages/dev-agents-sync/tests/codex-init-check.test.mjs', () => {
+    const p = path.join(PACKAGE_ROOT, 'tests', 'codex-init-check.test.mjs');
+    assert.ok(
+      existsSync(p),
+      `S3 test file must exist at ${p}.\n` +
+      'This file guards: init --targets codex writes all files, scoping, collision ' +
+      'refusal, check drift, unmanaged sibling untouched, opt-in / no auto-detect.',
+    );
+  });
+
+  it('S4 codex-readme e2e test file exists at packages/dev-agents-sync/tests/e2e/codex-readme.test.mjs', () => {
+    const p = path.join(PACKAGE_ROOT, 'tests', 'e2e', 'codex-readme.test.mjs');
+    assert.ok(
+      existsSync(p),
+      `S4 README coverage test file must exist at ${p}.\n` +
+      'This file guards: README documents codex target, --targets codex, SKILL.md shape, ' +
+      'AGENTS.md, model-invoked UX, opt-in-only, manual removal, two-file-shape distinction.',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// A2. Spec test-plan behavior coverage cross-check
+//
+// Cross-checks that the spec's documented test-plan behaviors are each addressed
+// by one of the three existing test files. Each assertion verifies that a
+// particular test label/keyword appears in the respective test file, giving a
+// lightweight guard that the spec behaviors have not been silently skipped.
+// ---------------------------------------------------------------------------
+
+describe('codex spec test-plan behavior coverage', () => {
+  function readTestFile(relPath) {
+    const absPath = path.join(REPO_ROOT, relPath);
+    return readFileSync(absPath, 'utf8');
+  }
+
+  it('S1 file covers "frontmatter" behavior (reduced to name + description)', () => {
+    const content = readTestFile('tests/codex-emitter.test.mjs');
+    assert.ok(
+      content.includes('frontmatter'),
+      'S1 test file must include "frontmatter" assertions (spec: SKILL.md frontmatter ' +
+      'reduced to name+description only, no model/tools/cursor/claude keys).',
+    );
+  });
+
+  it('S1 file covers "determinism" behavior (byte-identical re-run)', () => {
+    const content = readTestFile('tests/codex-emitter.test.mjs');
+    assert.ok(
+      content.includes('determinism') || content.includes('byte-identical') || content.includes('identical'),
+      'S1 test file must include determinism assertions (spec: same inputs → same bytes).',
+    );
+  });
+
+  it('S1 file covers "--mirror-codex" flag behavior', () => {
+    const content = readTestFile('tests/codex-emitter.test.mjs');
+    assert.ok(
+      content.includes('--mirror-codex'),
+      'S1 test file must include --mirror-codex assertions (spec: mirror flag writes ' +
+      'committed mirror, does not clobber flat canonical skill files).',
+    );
+  });
+
+  it('S2 file covers "resolveConsumerPath" codex path translation', () => {
+    const content = readTestFile(
+      'packages/dev-agents-sync/tests/codex-target.test.mjs',
+    );
+    assert.ok(
+      content.includes('resolveConsumerPath'),
+      'S2 test file must include resolveConsumerPath assertions for the codex prefix.',
+    );
+  });
+
+  it('S2 file covers backward-compat (legacy lockfile without codex)', () => {
+    const content = readTestFile(
+      'packages/dev-agents-sync/tests/codex-target.test.mjs',
+    );
+    assert.ok(
+      content.includes('backward') || content.includes('legacy'),
+      'S2 test file must include backward-compat assertions (spec: legacy lockfiles ' +
+      'without codex remain valid and serialize byte-identically).',
+    );
+  });
+
+  it('S3 file covers "autoDetect" exclusion (opt-in only)', () => {
+    const content = readTestFile(
+      'packages/dev-agents-sync/tests/codex-init-check.test.mjs',
+    );
+    assert.ok(
+      content.includes('autoDetect') || content.includes('auto-detect') || content.includes('auto_detect'),
+      'S3 test file must include autoDetectTargets assertions (spec: Codex never ' +
+      'auto-selected, not even when .agents/ exists in the consumer repo).',
+    );
+  });
+
+  it('S3 file covers unmanaged sibling .agents/ file is untouched', () => {
+    const content = readTestFile(
+      'packages/dev-agents-sync/tests/codex-init-check.test.mjs',
+    );
+    assert.ok(
+      content.includes('sibling') || content.includes('untouched') || content.includes('unmanaged'),
+      'S3 test file must include sibling-file-untouched assertions (spec: a pre-existing ' +
+      'unmanaged .agents/ file is never touched by init).',
+    );
+  });
+
+  it('S3 file covers collision refusal for pre-existing unmanaged AGENTS.md', () => {
+    const content = readTestFile(
+      'packages/dev-agents-sync/tests/codex-init-check.test.mjs',
+    );
+    assert.ok(
+      content.includes('AGENTS.md') && (content.includes('refus') || content.includes('collision') || content.includes('unmanaged')),
+      'S3 test file must include collision-refusal assertions for unmanaged AGENTS.md.',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// B. filterFileMapByTargets behavioral parity between update.mjs and check.mjs
+//
+// The function is duplicated verbatim in update.mjs and check.mjs. We exercise
+// both commands with codex-prefix inputs and assert they produce the same scoped
+// output, so a divergence in one copy will fail this test before it silently
+// breaks a production behavior.
+//
+// Strategy: use the commands' public API (runUpdate, runCheck) with an injected
+// fetcher carrying a fixture FileMap. For the parity assertion we inspect what
+// files each command WRITES (update) or REPORTS (check) for a codex-only target.
+// Both must operate on exactly the same set of codex-prefixed keys.
+//
+// We do NOT test that both commands accept a non-codex target here — that is
+// already covered by the main command test suites. We only test the codex-prefix
+// path through both.
+// ---------------------------------------------------------------------------
+
+import { runUpdate } from '../src/commands/update.mjs';
+import { runCheck } from '../src/commands/check.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+
+const SIX_AGENTS = ['analyze', 'define', 'implement', 'supervise', 'test', 'validate'];
+const MANAGED_MARKER = '<!-- managed-by: dev-agents-sync v1.0.0 -->';
+
+function makeCodexSkillContent(agent) {
+  return `${MANAGED_MARKER}\n# ${agent} Skill\n\nYou are the ${agent} agent.\n`;
+}
+
+function makeCodexAgentsMd() {
+  return `${MANAGED_MARKER}\n# Agent Skills\n\nThis repo contains the following agent skills.\n`;
+}
+
+/** Fixture FileMap with codex + root + claude keys. */
+function buildMixedFileMap() {
+  const map = {};
+  for (const agent of SIX_AGENTS) {
+    map[`codex/.agents/skills/${agent}/SKILL.md`] = makeCodexSkillContent(agent);
+  }
+  map['codex/AGENTS.md'] = makeCodexAgentsMd();
+  // A root-prefixed key — must be included by both update.mjs and check.mjs
+  // regardless of target, since both copies have `prefix === 'root' || ...`.
+  map['root/CONSTITUTION.md'] = `${MANAGED_MARKER}\n# Constitution\n`;
+  // A claude-prefixed key — must be EXCLUDED when targets is only ['codex'].
+  map['claude/agents/define.md'] = `---\nname: "define"\n---\n${MANAGED_MARKER}\nClaude agent.\n`;
+  return map;
+}
+
+function makeMixedFetcher() {
+  return async () => buildMixedFileMap();
+}
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0'];
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-codex-cc-test-'));
+}
+
+describe('filterFileMapByTargets parity: update.mjs and check.mjs handle codex prefix identically', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Writes a pre-initialized codex consumer state so that:
+   *   - the lockfile records targets: ['codex']
+   *   - all codex files are written with correct content (in-sync state)
+   *   - the root/CONSTITUTION.md is also written (root is always-included)
+   */
+  function setupCodexConsumer(dir) {
+    writeLockfile(dir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['codex'],
+      lastUpdated: '2026-06-07T00:00:00Z',
+    });
+
+    // Write codex files
+    for (const agent of SIX_AGENTS) {
+      const skillDir = path.join(dir, '.agents', 'skills', agent);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(
+        path.join(skillDir, 'SKILL.md'),
+        makeCodexSkillContent(agent),
+        'utf8',
+      );
+    }
+    writeFileSync(path.join(dir, 'AGENTS.md'), makeCodexAgentsMd(), 'utf8');
+    // Root files are always-included by both commands.
+    writeFileSync(path.join(dir, 'CONSTITUTION.md'), `${MANAGED_MARKER}\n# Constitution\n`, 'utf8');
+  }
+
+  // Test that update.mjs writes exactly the codex files (+ root) when targets is ['codex'],
+  // and does NOT write .claude/ files. This confirms update.mjs's copy of
+  // filterFileMapByTargets excludes claude-prefixed keys for a codex-only target.
+  it('update.mjs writes codex SKILL.md files and excludes claude files for targets: [codex]', async () => {
+    setupCodexConsumer(consumerDir);
+
+    // Bump the lockfile resolvedVersion to force an update
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0', // will be bumped to 1.2.0 by resolveRange
+      targets: ['codex'],
+      lastUpdated: '2026-06-07T00:00:00Z',
+    });
+
+    // Use availableTags that has a newer version to force update path
+    await runUpdate(consumerDir, {
+      fetcher: makeMixedFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0'],
+    });
+
+    // codex files must exist
+    for (const agent of SIX_AGENTS) {
+      const skillPath = path.join(consumerDir, '.agents', 'skills', agent, 'SKILL.md');
+      assert.ok(
+        existsSync(skillPath),
+        `update.mjs must write .agents/skills/${agent}/SKILL.md for targets: ['codex']`,
+      );
+    }
+    assert.ok(
+      existsSync(path.join(consumerDir, 'AGENTS.md')),
+      'update.mjs must write AGENTS.md for targets: [codex]',
+    );
+
+    // claude files must NOT exist (update.mjs's filterFileMapByTargets correctly
+    // excludes claude-prefixed keys when targets does not include claude)
+    assert.ok(
+      !existsSync(path.join(consumerDir, '.claude')),
+      'update.mjs must NOT write .claude/ files when targets is only [codex]',
+    );
+  });
+
+  // Test that check.mjs also excludes claude files and only checks codex files.
+  // We delete a codex file to force exit 1 — confirming that check.mjs's copy
+  // of filterFileMapByTargets includes codex keys.
+  it('check.mjs reports missing codex SKILL.md (includes codex keys) and ignores claude keys', async () => {
+    setupCodexConsumer(consumerDir);
+
+    // Delete one codex SKILL.md to induce drift
+    rmSync(path.join(consumerDir, '.agents', 'skills', 'define', 'SKILL.md'));
+
+    let exitCode;
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeMixedFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+      errorMessage = err.message;
+    }
+
+    // check must exit 1 because a codex file is missing
+    assert.equal(
+      exitCode,
+      1,
+      'check.mjs must exit 1 when a codex SKILL.md is missing — confirming check.mjs ' +
+      'includes codex keys in its filterFileMapByTargets output.',
+    );
+    // The error must name the missing file (not a claude file)
+    assert.ok(
+      errorMessage.includes('define') || errorMessage.includes('SKILL.md'),
+      `check.mjs error must name the missing codex file, got: ${errorMessage}`,
+    );
+    // The error must NOT name a claude file as missing
+    assert.ok(
+      !errorMessage.includes('.claude'),
+      `check.mjs must NOT report .claude/ drift when targets is only [codex], got: ${errorMessage}`,
+    );
+  });
+
+  // Parity assertion: both commands include codex keys and exclude claude keys
+  // when targets is ['codex']. This is the critical parity check — if one copy
+  // of filterFileMapByTargets regresses (e.g. drops the codex allow-list or adds
+  // an accidental include), this test catches it.
+  it('both update.mjs and check.mjs are in sync — neither writes/checks claude files for targets: [codex]', async () => {
+    // This is a summary assertion: if the two tests above pass, both commands
+    // apply the same codex-prefix scoping. We assert the common fixture FileMap
+    // key structure here so the test is self-documenting.
+    const fileMap = buildMixedFileMap();
+    const codexKeys = Object.keys(fileMap).filter(k => k.startsWith('codex/'));
+    const claudeKeys = Object.keys(fileMap).filter(k => k.startsWith('claude/'));
+    const rootKeys = Object.keys(fileMap).filter(k => k.startsWith('root/'));
+
+    // Fixture sanity — if the fixture is wrong the parity tests above are meaningless.
+    assert.ok(codexKeys.length >= 7, `fixture must have at least 7 codex keys (6 skills + AGENTS.md), got ${codexKeys.length}`);
+    assert.ok(claudeKeys.length >= 1, `fixture must have at least 1 claude key for exclusion-scoping test, got ${claudeKeys.length}`);
+    assert.ok(rootKeys.length >= 1, `fixture must have at least 1 root key to verify always-included behavior, got ${rootKeys.length}`);
+
+    // The set of keys that should be included for targets: ['codex'] by BOTH commands
+    // (update.mjs and check.mjs) is: codex/* + root/* (always-included).
+    const expectedIncluded = new Set([...codexKeys, ...rootKeys]);
+    const expectedExcluded = new Set(claudeKeys);
+
+    // Verify our expectations match the spec's prefix-scoping contract.
+    assert.equal(expectedExcluded.size, claudeKeys.length, 'all claude keys must be excluded');
+    assert.ok(
+      [...expectedIncluded].every(k => k.startsWith('codex/') || k.startsWith('root/')),
+      'all included keys must have codex/ or root/ prefix',
+    );
+    assert.ok(
+      [...expectedExcluded].every(k => k.startsWith('claude/')),
+      'all excluded keys must have claude/ prefix',
+    );
+  });
+});