@dalzoubi/dev-agents-sync 2.0.16 → 2.0.17

package/tests/steering-seed.test.mjs

@@ -0,0 +1,645 @@
+/**
+ * tests/steering-seed.test.mjs
+ *
+ * Behavior tests for S1 — Steering scaffold + CLI seed.
+ *
+ * What these tests prove (one named test per criterion — §7):
+ *
+ *  B1. init writes three blank steering scaffold files when .claude/steering/ is absent.
+ *  B2. update writes three blank steering scaffold files when .claude/steering/ is absent.
+ *  B3. update leaves an already-edited steering/decisions.md byte-identical (seed-if-absent).
+ *  B4. update leaves an already-edited steering/glossary.md byte-identical (seed-if-absent).
+ *  B5. update leaves an already-edited steering/architecture.md byte-identical (seed-if-absent).
+ *  B6. Seeded steering files do NOT contain the managed-by marker (consumer-owned).
+ *  B7. After seeding, the lockfile contains no entry for any steering/* path.
+ *  B8. build.mjs copies .agents/steering/*.md → .claude/steering/*.md WITHOUT prepending
+ *      the marker and WITHOUT mangling frontmatter.
+ *
+ * All tests use isolated tmp dirs (mkdtempSync) and never touch the real repo.
+ * They are intentionally FAILING until the implement agent wires up the behavior.
+ */
+
+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 { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runInit } from '../src/commands/init.mjs';
+import { runUpdate } from '../src/commands/update.mjs';
+import { writeLockfile, readLockfile } from '../src/lockfile.mjs';
+import { hasMarker } from '../src/marker.mjs';
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const REPO_ROOT = path.resolve(PACKAGE_ROOT, '..', '..');
+const BUILD_SCRIPT = path.join(REPO_ROOT, 'scripts', 'build.mjs');
+
+// ---------------------------------------------------------------------------
+// Fixture helpers (mirrors the pattern in init.test.mjs / update.test.mjs)
+// ---------------------------------------------------------------------------
+
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+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 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, target);
+  }
+  return map;
+}
+
+function makeFixtureFetcher() {
+  return async (_repo, _tag, _token) => buildFixtureFileMap(['claude', 'cursor']);
+}
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-steering-test-'));
+}
+
+/** Sets up a minimal already-initialized consumer repo (lockfile + one managed file). */
+async function setupInitializedRepo(consumerDir, opts = {}) {
+  const {
+    targets = ['claude'],
+    resolvedVersion = '1.0.0',
+    range = '^1',
+  } = opts;
+
+  writeLockfile(consumerDir, {
+    source: 'github:dalzoubi/dev-agents',
+    range,
+    resolvedVersion,
+    targets,
+    lastUpdated: '2026-06-16T00:00:00Z',
+  });
+
+  // Write at least one managed file so update can find something to work with.
+  const agentsDir = path.join(consumerDir, '.claude', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  const fixtureContent = readFileSync(
+    path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'),
+    'utf8',
+  );
+  writeFileSync(path.join(agentsDir, 'define.md'), fixtureContent, 'utf8');
+}
+
+/** The three steering file names the spec requires. */
+const STEERING_FILES = ['decisions.md', 'glossary.md', 'architecture.md'];
+
+// ---------------------------------------------------------------------------
+// B1 — init seeds steering when absent
+// ---------------------------------------------------------------------------
+
+describe('S1 steering seed — init', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('B1: init creates .claude/steering/ with three scaffold files when absent', async () => {
+    // No steering/ pre-exists. init must create all three.
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    assert.ok(
+      existsSync(steeringDir),
+      `.claude/steering/ must be created by init when absent`,
+    );
+
+    for (const file of STEERING_FILES) {
+      const absPath = path.join(steeringDir, file);
+      assert.ok(
+        existsSync(absPath),
+        `init must write .claude/steering/${file} when absent`,
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// B2 — update seeds steering when absent
+// ---------------------------------------------------------------------------
+
+describe('S1 steering seed — update', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('B2: update creates .claude/steering/ with three scaffold files when absent', async () => {
+    await setupInitializedRepo(consumerDir);
+    // The lockfile resolvedVersion is 1.0.0, but we supply 1.2.0 as the latest
+    // tag so update will run (not short-circuit as up-to-date).
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    assert.ok(
+      existsSync(steeringDir),
+      `.claude/steering/ must be created by update when absent`,
+    );
+
+    for (const file of STEERING_FILES) {
+      const absPath = path.join(steeringDir, file);
+      assert.ok(
+        existsSync(absPath),
+        `update must write .claude/steering/${file} when absent`,
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// B3–B5 — update never clobbers existing steering content
+// ---------------------------------------------------------------------------
+
+describe('S1 steering seed — never-clobber (update)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('B3: update leaves edited steering/decisions.md byte-identical', async () => {
+    await setupInitializedRepo(consumerDir);
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    mkdirSync(steeringDir, { recursive: true });
+    const original = '# Decisions\n\n2026-06-16 — chose X: because of Y\n';
+    writeFileSync(path.join(steeringDir, 'decisions.md'), original, 'utf8');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const after = readFileSync(path.join(steeringDir, 'decisions.md'), 'utf8');
+    assert.equal(
+      after,
+      original,
+      'update must leave edited steering/decisions.md byte-identical (seed-if-absent)',
+    );
+  });
+
+  it('B4: update leaves edited steering/glossary.md byte-identical', async () => {
+    await setupInitializedRepo(consumerDir);
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    mkdirSync(steeringDir, { recursive: true });
+    const original = '# Glossary\n\n**Managed file**: a file bearing the `managed-by` marker.\n';
+    writeFileSync(path.join(steeringDir, 'glossary.md'), original, 'utf8');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const after = readFileSync(path.join(steeringDir, 'glossary.md'), 'utf8');
+    assert.equal(
+      after,
+      original,
+      'update must leave edited steering/glossary.md byte-identical (seed-if-absent)',
+    );
+  });
+
+  it('B5: update leaves edited steering/architecture.md byte-identical', async () => {
+    await setupInitializedRepo(consumerDir);
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    mkdirSync(steeringDir, { recursive: true });
+    const original = '# Architecture\n\nCore pattern: CLI → lockfile → fetcher → writer.\n';
+    writeFileSync(path.join(steeringDir, 'architecture.md'), original, 'utf8');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const after = readFileSync(path.join(steeringDir, 'architecture.md'), 'utf8');
+    assert.equal(
+      after,
+      original,
+      'update must leave edited steering/architecture.md byte-identical (seed-if-absent)',
+    );
+  });
+
+  it('B3 variant: init also leaves edited steering/decisions.md byte-identical', async () => {
+    // .claude/steering/ already exists with content before init is called on a second run.
+    // Simulating a re-init (the consumer already ran init before and edited steering).
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    mkdirSync(steeringDir, { recursive: true });
+    const original = '# Decisions\n\nPre-existing consumer content.\n';
+    writeFileSync(path.join(steeringDir, 'decisions.md'), original, 'utf8');
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const after = readFileSync(path.join(steeringDir, 'decisions.md'), 'utf8');
+    assert.equal(
+      after,
+      original,
+      'init must leave existing steering/decisions.md byte-identical (seed-if-absent)',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// B6 — seeded steering files carry no managed-by marker
+// ---------------------------------------------------------------------------
+
+describe('S1 steering seed — no marker on seeded files', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('B6a: steering/decisions.md seeded by init has no managed-by marker', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const content = readFileSync(
+      path.join(consumerDir, '.claude', 'steering', 'decisions.md'),
+      'utf8',
+    );
+    assert.ok(
+      !hasMarker(content),
+      'seeded steering/decisions.md must NOT contain the managed-by marker (consumer-owned)',
+    );
+  });
+
+  it('B6b: steering/glossary.md seeded by init has no managed-by marker', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const content = readFileSync(
+      path.join(consumerDir, '.claude', 'steering', 'glossary.md'),
+      'utf8',
+    );
+    assert.ok(
+      !hasMarker(content),
+      'seeded steering/glossary.md must NOT contain the managed-by marker (consumer-owned)',
+    );
+  });
+
+  it('B6c: steering/architecture.md seeded by init has no managed-by marker', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const content = readFileSync(
+      path.join(consumerDir, '.claude', 'steering', 'architecture.md'),
+      'utf8',
+    );
+    assert.ok(
+      !hasMarker(content),
+      'seeded steering/architecture.md must NOT contain the managed-by marker (consumer-owned)',
+    );
+  });
+
+  it('B6d: steering/decisions.md seeded by update has no managed-by marker', async () => {
+    await setupInitializedRepo(consumerDir);
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const content = readFileSync(
+      path.join(consumerDir, '.claude', 'steering', 'decisions.md'),
+      'utf8',
+    );
+    assert.ok(
+      !hasMarker(content),
+      'seeded steering/decisions.md must NOT contain the managed-by marker (consumer-owned)',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// B7 — lockfile does not track steering/* paths
+// ---------------------------------------------------------------------------
+
+describe('S1 steering seed — lockfile does not track steering paths', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('B7a: after init, lockfile contains no entry for steering/decisions.md', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // Read raw lockfile JSON so we catch any form of steering path tracking,
+    // regardless of the field name used (files, managedFiles, tracked, etc.).
+    const raw = readFileSync(
+      path.join(consumerDir, '.dev-agents-sync.json'),
+      'utf8',
+    );
+    assert.ok(
+      !raw.includes('steering/'),
+      `lockfile must not reference any steering/ path after init, got:\n${raw}`,
+    );
+  });
+
+  it('B7b: after update, lockfile contains no entry for any steering/* path', async () => {
+    await setupInitializedRepo(consumerDir);
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const raw = readFileSync(
+      path.join(consumerDir, '.dev-agents-sync.json'),
+      'utf8',
+    );
+    assert.ok(
+      !raw.includes('steering/'),
+      `lockfile must not reference any steering/ path after update, got:\n${raw}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// B8 — build.mjs emits steering files to .claude/steering/ without marker
+// ---------------------------------------------------------------------------
+
+/**
+ * Helper: run build.mjs with a temporary .agents/ dir that contains both
+ * a minimal valid agent (so the build doesn't fail with "nothing to emit")
+ * and a steering/ subdirectory with test content.
+ *
+ * Returns { exitCode, stdout, stderr, mirrorRoot }.
+ */
+function runBuildWithSteering(agentsDir, steeringContent, mirrorRoot) {
+  const promptsDir = path.dirname(agentsDir); // e.g. <tmp>/.agents
+  const distDir = path.join(path.dirname(promptsDir), 'dist');
+
+  // Write minimal valid agent so build doesn't bail out.
+  const agentsSubdir = path.join(agentsDir, 'agents');
+  mkdirSync(agentsSubdir, { recursive: true });
+  writeFileSync(
+    path.join(agentsSubdir, 'dummy.md'),
+    `---\nname: dummy\ndescription: "Dummy agent for build test."\n---\n\n# Dummy\n\nBody text.\n`,
+    'utf8',
+  );
+
+  // Write steering source files.
+  const steeringDir = path.join(agentsDir, 'steering');
+  mkdirSync(steeringDir, { recursive: true });
+  for (const [filename, content] of Object.entries(steeringContent)) {
+    writeFileSync(path.join(steeringDir, filename), content, 'utf8');
+  }
+
+  try {
+    const stdout = execFileSync(
+      process.execPath,
+      [
+        BUILD_SCRIPT,
+        '--prompts-dir', agentsDir,
+        '--dist-dir', distDir,
+        '--no-mirror-root',
+        '--mirror-claude', mirrorRoot,
+      ],
+      { encoding: 'utf8', env: { ...process.env } },
+    );
+    return { exitCode: 0, stdout, stderr: '', distDir, mirrorRoot };
+  } catch (err) {
+    return {
+      exitCode: err.status ?? 1,
+      stdout: err.stdout ?? '',
+      stderr: err.stderr ?? '',
+      distDir,
+      mirrorRoot,
+    };
+  }
+}
+
+describe('S1 steering seed — build.mjs emits steering to mirror without marker', () => {
+  let tmpRoot;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(path.join(tmpdir(), 'das-steering-build-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('B8a: build --mirror-claude copies .agents/steering/decisions.md to .claude/steering/decisions.md', () => {
+    const agentsDir = path.join(tmpRoot, '.agents');
+    const mirrorRoot = path.join(tmpRoot, 'mirror');
+    mkdirSync(mirrorRoot, { recursive: true });
+
+    const { exitCode, stderr } = runBuildWithSteering(
+      agentsDir,
+      {
+        'decisions.md': '# Decisions\n\nConsumer-written content.\n',
+        'glossary.md': '# Glossary\n',
+        'architecture.md': '# Architecture\n',
+      },
+      mirrorRoot,
+    );
+
+    assert.equal(exitCode, 0, `Build must succeed. stderr:\n${stderr}`);
+
+    const dest = path.join(mirrorRoot, '.claude', 'steering', 'decisions.md');
+    assert.ok(
+      existsSync(dest),
+      `.claude/steering/decisions.md must be written by build --mirror-claude`,
+    );
+  });
+
+  it('B8b: build emits all three steering files to .claude/steering/', () => {
+    const agentsDir = path.join(tmpRoot, '.agents');
+    const mirrorRoot = path.join(tmpRoot, 'mirror');
+    mkdirSync(mirrorRoot, { recursive: true });
+
+    const { exitCode, stderr } = runBuildWithSteering(
+      agentsDir,
+      {
+        'decisions.md': '# Decisions\n',
+        'glossary.md': '# Glossary\n',
+        'architecture.md': '# Architecture\n',
+      },
+      mirrorRoot,
+    );
+
+    assert.equal(exitCode, 0, `Build must succeed. stderr:\n${stderr}`);
+
+    for (const file of STEERING_FILES) {
+      const dest = path.join(mirrorRoot, '.claude', 'steering', file);
+      assert.ok(
+        existsSync(dest),
+        `build must emit .claude/steering/${file} (all three steering files)`,
+      );
+    }
+  });
+
+  it('B8c: build-emitted steering file does NOT start with the managed-by marker', () => {
+    const agentsDir = path.join(tmpRoot, '.agents');
+    const mirrorRoot = path.join(tmpRoot, 'mirror');
+    mkdirSync(mirrorRoot, { recursive: true });
+
+    const sourceContent = '# Decisions\n\nThis is consumer steering content.\n';
+
+    const { exitCode, stderr } = runBuildWithSteering(
+      agentsDir,
+      {
+        'decisions.md': sourceContent,
+        'glossary.md': '# Glossary\n',
+        'architecture.md': '# Architecture\n',
+      },
+      mirrorRoot,
+    );
+
+    assert.equal(exitCode, 0, `Build must succeed. stderr:\n${stderr}`);
+
+    const dest = path.join(mirrorRoot, '.claude', 'steering', 'decisions.md');
+    const emitted = readFileSync(dest, 'utf8');
+
+    assert.ok(
+      !hasMarker(emitted),
+      `build-emitted steering/decisions.md must NOT contain the managed-by marker. Content:\n${emitted}`,
+    );
+  });
+
+  it('B8d: build-emitted steering file preserves source content verbatim (no frontmatter mangling)', () => {
+    const agentsDir = path.join(tmpRoot, '.agents');
+    const mirrorRoot = path.join(tmpRoot, 'mirror');
+    mkdirSync(mirrorRoot, { recursive: true });
+
+    const sourceContent = '# Decisions\n\n2026-06-16 — chose ESM modules: tree-shaking benefits.\n';
+
+    const { exitCode, stderr } = runBuildWithSteering(
+      agentsDir,
+      {
+        'decisions.md': sourceContent,
+        'glossary.md': '# Glossary\n',
+        'architecture.md': '# Architecture\n',
+      },
+      mirrorRoot,
+    );
+
+    assert.equal(exitCode, 0, `Build must succeed. stderr:\n${stderr}`);
+
+    const dest = path.join(mirrorRoot, '.claude', 'steering', 'decisions.md');
+    const emitted = readFileSync(dest, 'utf8');
+
+    // Normalize line endings in case the writer converts to LF.
+    const normalize = (s) => s.replace(/\r\n/g, '\n');
+    assert.equal(
+      normalize(emitted),
+      normalize(sourceContent),
+      'build must copy steering file verbatim without prepending a marker or modifying content',
+    );
+  });
+
+  it('B8e: build-emitted steering file first line is NOT the managed-by marker', () => {
+    // Strictly verifies the physical first line — catches cases where the marker
+    // lands before rather than after the content.
+    const agentsDir = path.join(tmpRoot, '.agents');
+    const mirrorRoot = path.join(tmpRoot, 'mirror');
+    mkdirSync(mirrorRoot, { recursive: true });
+
+    const { exitCode, stderr } = runBuildWithSteering(
+      agentsDir,
+      {
+        'decisions.md': '# Decisions\n',
+        'glossary.md': '# Glossary\n',
+        'architecture.md': '# Architecture\n',
+      },
+      mirrorRoot,
+    );
+
+    assert.equal(exitCode, 0, `Build must succeed. stderr:\n${stderr}`);
+
+    const dest = path.join(mirrorRoot, '.claude', 'steering', 'decisions.md');
+    const emitted = readFileSync(dest, 'utf8');
+    const firstLine = emitted.split('\n')[0];
+
+    assert.ok(
+      !/<!--\s*managed-by/.test(firstLine),
+      `First line of emitted steering file must NOT be the marker. Got: ${JSON.stringify(firstLine)}`,
+    );
+  });
+});