@dalzoubi/dev-agents-sync 2.0.7 → 2.0.8

package/tests/e2e/codex-readme.test.mjs

@@ -0,0 +1,335 @@
+/**
+ * tests/e2e/codex-readme.test.mjs
+ *
+ * Asserts that the consumer-facing README documents the Codex adoption flow.
+ *
+ * These tests are RED until the implement step writes the Codex section into
+ * packages/dev-agents-sync/README.md.
+ *
+ * The README (packages/dev-agents-sync/README.md) must:
+ *
+ *   1. Mention the `codex` target and `--targets codex` so consumers know the
+ *      flag to run.
+ *
+ *   2. Document the output file shape: `.agents/skills/<agent>/SKILL.md` (the
+ *      directory-per-skill layout that Codex discovers at runtime) AND the thin
+ *      root `AGENTS.md`.
+ *
+ *   3. Explain that Codex skills are MODEL-INVOKED (not literal `/define` slash
+ *      commands). Users invoke them via `/skills`, `$<name>`, or implicit
+ *      selection — not by typing `/define`. The README must carry a phrase that
+ *      captures this distinction (e.g. "model-invoked", "invoked by the model",
+ *      "/skills", "$name" mention, or "not slash commands"/"not a slash
+ *      command").
+ *
+ *   4. Document that Codex is OPT-IN ONLY — no auto-detection. The README must
+ *      state (or clearly imply) that Codex is not auto-selected; the user must
+ *      explicitly pass `--targets codex`.
+ *
+ *   5. Document MANUAL REMOVAL — there is no uninstall command. The consumer
+ *      removes codex files manually (consistent with all targets). The README
+ *      must mention manual removal or the absence of an uninstall command.
+ *
+ *   6. Document the TWO FILE SHAPES distinction: in this authoring repo the
+ *      canonical `.agents/skills/*.md` are flat single files (source), while
+ *      the codex output uses directory-per-skill `SKILL.md` (dist shape). This
+ *      prevents a maintainer from confusing the two.
+ *
+ * Implement agent must update `packages/dev-agents-sync/README.md` before
+ * these tests go green.
+ *
+ * Proximity strategy: for multi-section assertions we look for key terms within
+ * a 600-character window of the `codex` mention(s) — tight enough to prove
+ * co-location without being brittle to minor rewording.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// The consumer-facing README is in the CLI package (confirmed: readme-coverage.test.mjs
+// uses the same path and the existing tests verify it documents init/update/check).
+const README_PATH = path.join(__dirname, '..', '..', 'README.md');
+
+function readReadme() {
+  assert.ok(
+    existsSync(README_PATH),
+    `README.md must exist at ${README_PATH}`,
+  );
+  return readFileSync(README_PATH, 'utf8');
+}
+
+/**
+ * Returns true if `needle` appears within `windowSize` characters of any
+ * occurrence of `anchor` in `haystack`.
+ */
+function appearsNear(haystack, anchor, needle, windowSize = 600) {
+  let searchFrom = 0;
+  while (true) {
+    const idx = haystack.indexOf(anchor, searchFrom);
+    if (idx === -1) return false;
+    const windowStart = Math.max(0, idx - windowSize / 2);
+    const windowEnd = Math.min(haystack.length, idx + windowSize / 2);
+    if (haystack.slice(windowStart, windowEnd).includes(needle)) return true;
+    searchFrom = idx + 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Criterion 1 — README mentions the codex target and --targets codex
+// ---------------------------------------------------------------------------
+
+describe('README (codex): mentions the codex target', () => {
+  it('README.md contains the string "codex"', () => {
+    const content = readReadme();
+    assert.ok(
+      content.includes('codex'),
+      'README.md must mention "codex" to document the Codex target.\n' +
+      'The Codex adoption flow (init --targets codex) must be documented so\n' +
+      'consumers know how to adopt the toolkit with OpenAI Codex.',
+    );
+  });
+
+  it('README.md contains "--targets codex" (the flag consumers must pass)', () => {
+    const content = readReadme();
+    assert.ok(
+      content.includes('--targets codex'),
+      'README.md must include "--targets codex" to document the opt-in invocation.\n' +
+      'Codex is not auto-detected; consumers must pass --targets codex explicitly.',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 2 — README documents the output file shape
+// ---------------------------------------------------------------------------
+
+describe('README (codex): documents the output file shape', () => {
+  it('README.md mentions SKILL.md (the per-agent codex output file)', () => {
+    const content = readReadme();
+    assert.ok(
+      content.includes('SKILL.md'),
+      'README.md must mention "SKILL.md" to document the codex output shape.\n' +
+      'Each agent produces .agents/skills/<agent>/SKILL.md — Codex\'s discovery path.',
+    );
+  });
+
+  it('README.md mentions the .agents/skills/ directory (codex discovery path)', () => {
+    const content = readReadme();
+    // Accept either the full path fragment or individual components near "codex".
+    const hasSkillsPath =
+      content.includes('.agents/skills') ||
+      appearsNear(content, 'codex', 'skills', 800);
+    assert.ok(
+      hasSkillsPath,
+      'README.md must document the .agents/skills/ output directory.\n' +
+      'Codex discovers skills at .agents/skills/<agent>/SKILL.md (cwd → repo root scan).',
+    );
+  });
+
+  it('README.md mentions AGENTS.md (the thin root index file)', () => {
+    const content = readReadme();
+    // AGENTS.md is already in the README (for non-codex references), but we
+    // specifically need it documented in the context of the codex section.
+    // We assert it appears near "codex" (within 1000 chars) OR as a standalone
+    // mention near SKILL.md — either signals codex output shape coverage.
+    const nearCodex = appearsNear(content, 'codex', 'AGENTS.md', 1000);
+    const nearSkillMd = appearsNear(content, 'SKILL.md', 'AGENTS.md', 800);
+    assert.ok(
+      nearCodex || nearSkillMd,
+      'README.md must document the AGENTS.md thin root index in the codex section.\n' +
+      'The codex target emits both .agents/skills/<agent>/SKILL.md (six files) and\n' +
+      'a thin root AGENTS.md — both must be mentioned.',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 3 — README explains model-invoked (not slash commands)
+// ---------------------------------------------------------------------------
+
+describe('README (codex): explains model-invoked UX (not slash commands)', () => {
+  it('README.md contains a phrase explaining that Codex skills are model-invoked', () => {
+    const content = readReadme();
+    // Accept any of several phrasings that capture the model-invoked nature.
+    const phrases = [
+      'model-invoked',
+      'invoked by the model',
+      'model invoked',
+      '/skills',
+      '$name',
+      'not slash command',
+      'not a slash command',
+      'not literal',
+      'implicitly selected',
+      'implicit selection',
+    ];
+    const lc = content.toLowerCase();
+    const found = phrases.some(
+      (p) => lc.includes(p.toLowerCase()),
+    );
+    assert.ok(
+      found,
+      'README.md must explain that Codex skills are model-invoked, not literal\n' +
+      'slash commands. Accepted phrases: ' + phrases.join(', ') + '.\n' +
+      'Codex users trigger an agent via /skills, $<name> mention, or implicit\n' +
+      'selection — NOT by typing /define. This distinction must be documented.',
+    );
+  });
+
+  it('README.md mentions the model-invoked UX in proximity to "codex"', () => {
+    const content = readReadme();
+    const phrases = [
+      'model-invoked',
+      'invoked by the model',
+      '/skills',
+      '$name',
+      'not slash',
+      'implicit',
+    ];
+    const foundNear = phrases.some((p) =>
+      appearsNear(content, 'codex', p, 1200),
+    );
+    assert.ok(
+      foundNear,
+      'README.md must describe the model-invoked UX near the "codex" section.\n' +
+      'The distinction between Codex skills (model-invoked) and slash commands\n' +
+      '(/define, /test, etc.) must appear in the codex documentation context.',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 4 — README documents opt-in only / no auto-detect
+// ---------------------------------------------------------------------------
+
+describe('README (codex): documents opt-in only — no auto-detect', () => {
+  it('README.md states codex is opt-in (not auto-detected)', () => {
+    const content = readReadme();
+    // Accept any phrasing that communicates opt-in / no auto-detect.
+    const phrases = [
+      'opt-in',
+      'opt in',
+      'not auto',
+      'no auto',
+      'must pass --targets',
+      'must be passed',
+      'explicit',
+    ];
+    const lc = content.toLowerCase();
+    // The phrase must appear near "codex" to be meaningful.
+    const foundNear = phrases.some((p) =>
+      appearsNear(lc, 'codex', p.toLowerCase(), 1200),
+    );
+    assert.ok(
+      foundNear,
+      'README.md must state that the codex target is opt-in only (no auto-detection).\n' +
+      'Codex has no filesystem signal (no .codex/ dir); users must pass --targets codex\n' +
+      'explicitly. Accepted phrases near "codex": ' + phrases.join(', '),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 5 — README documents manual removal (no uninstall command)
+// ---------------------------------------------------------------------------
+
+describe('README (codex): documents manual removal — no uninstall command', () => {
+  it('README.md mentions manual removal or absence of an uninstall command', () => {
+    const content = readReadme();
+    // Accept any phrasing that captures the no-cleanup contract.
+    const phrases = [
+      'manual',
+      'manually',
+      'no uninstall',
+      'no cleanup',
+      'remove manually',
+      'removed manually',
+      'does not delete',
+      'does not remove',
+      'uninstall',
+    ];
+    const lc = content.toLowerCase();
+    const foundNear = phrases.some((p) =>
+      appearsNear(lc, 'codex', p.toLowerCase(), 1500),
+    );
+    assert.ok(
+      foundNear,
+      'README.md must document that codex files are removed manually (no uninstall).\n' +
+      'The CLI has no cleanup/uninstall for any target: dropping codex from targets\n' +
+      'stops future writes; file removal is manual and must be documented.\n' +
+      'Accepted phrases near "codex": ' + phrases.join(', '),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 6 — README documents the two-file-shape distinction
+// ---------------------------------------------------------------------------
+
+describe('README (codex): documents the two file shapes (canonical flat vs codex output)', () => {
+  it('README.md distinguishes canonical flat .agents/skills/*.md from codex directory-per-skill output', () => {
+    const content = readReadme();
+    // The key distinction: canonical sources in THIS repo are flat single files
+    // (.agents/skills/<name>.md). The codex TARGET OUTPUT is directory-per-skill
+    // (.agents/skills/<agent>/SKILL.md). Both shapes share the .agents/skills/ path
+    // prefix, so the distinction is load-bearing for maintainers.
+    //
+    // We assert the README mentions at least one of these distinguishing phrases:
+    //   - "flat" (contrasting the flat canonical vs dir-per-skill shape)
+    //   - "directory-per-skill" or "dir-per-skill"
+    //   - "canonical source" in proximity to "skill" (documenting the authoring shape)
+    //   - "output only" or "output shape" (the dir shape is output, not authoring)
+    //   - "authoring" near "skill" (the flat files are for authoring)
+    //   - both "SKILL.md" AND ".md" near each other with a distinction word
+    //
+    // Accept any phrasing that conveys the two shapes.
+    const phrases = [
+      'flat',
+      'directory-per-skill',
+      'dir-per-skill',
+      'output only',
+      'output shape',
+      'authoring',
+      'canonical source',
+      'single file',
+    ];
+    const lc = content.toLowerCase();
+    const foundNear = phrases.some((p) =>
+      // Search near "skill" broadly since the shape discussion may not be next to "codex"
+      appearsNear(lc, 'skill', p.toLowerCase(), 1500) ||
+      appearsNear(lc, 'codex', p.toLowerCase(), 1500),
+    );
+    assert.ok(
+      foundNear,
+      'README.md must document the two file shapes:\n' +
+      '  - Canonical authoring: .agents/skills/*.md (flat single files in this repo)\n' +
+      '  - Codex output:        .agents/skills/<agent>/SKILL.md (directory-per-skill)\n' +
+      'Without this distinction, a maintainer may confuse the two.\n' +
+      'Accepted phrases near "skill" or "codex": ' + phrases.join(', '),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 7 — Codex section is near existing init/update/check documentation
+//               (confirms Codex adoption is integrated into the Quick Start flow)
+// ---------------------------------------------------------------------------
+
+describe('README (codex): codex adoption is documented near the Quick Start / init section', () => {
+  it('"codex" appears within 3000 characters of the "init" section documentation', () => {
+    const content = readReadme();
+    // The init → update → check flow is the consumer Quick Start. The codex
+    // adoption path must be discoverable from the same section.
+    const foundNear = appearsNear(content, 'init', 'codex', 3000);
+    assert.ok(
+      foundNear,
+      'README.md must document the codex target near the init section.\n' +
+      'Consumers reading the Quick Start (init → update → check) must see\n' +
+      '"codex" within the same broad section — not buried far from the flow.',
+    );
+  });
+});