@dalzoubi/dev-agents-sync 1.0.0

package/src/range.mjs

@@ -0,0 +1,50 @@
+/**
+ * Semver range resolution.
+ *
+ * resolveRange(availableTags, range) → highest matching version (no v prefix).
+ * Tags can be supplied with or without the leading `v`.
+ *
+ * Throws an actionable Error on no-match (so callers can map to exit code 1).
+ */
+
+import semver from 'semver';
+
+class RangeError extends Error {
+  constructor(message, { exitCode = 1 } = {}) {
+    super(message);
+    this.name = 'RangeError';
+    this.exitCode = exitCode;
+  }
+}
+
+function normalize(tag) {
+  if (typeof tag !== 'string') return null;
+  const stripped = tag.startsWith('v') ? tag.slice(1) : tag;
+  return semver.valid(stripped);
+}
+
+export function resolveRange(availableTags, range) {
+  if (!Array.isArray(availableTags) || availableTags.length === 0) {
+    throw new RangeError(
+      `no available tags to resolve range \`${range}\` against`,
+    );
+  }
+  const versions = availableTags
+    .map(normalize)
+    .filter((v) => v !== null);
+
+  if (versions.length === 0) {
+    throw new RangeError(
+      `no valid semver tags found to resolve range \`${range}\``,
+    );
+  }
+
+  const max = semver.maxSatisfying(versions, range);
+  if (!max) {
+    throw new RangeError(
+      `no version in available tags satisfies range \`${range}\` ` +
+        `(available: ${versions.join(', ')})`,
+    );
+  }
+  return max;
+}

package/src/writer.mjs

@@ -0,0 +1,132 @@
+/**
+ * Filesystem writer + path translation.
+ *
+ * `resolveConsumerPath(consumerRoot, relPath)` maps a forward-slash key
+ * from a release FileMap (e.g. "claude/agents/define.md") to an OS-correct
+ * absolute path inside the consumer repo (e.g. "<root>/.claude/agents/define.md").
+ *
+ * Rejects path traversal (`..`).
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { hasMarker } from './marker.mjs';
+
+const TARGET_PREFIX = {
+  claude: '.claude',
+  cursor: '.cursor',
+};
+
+// Subdirectories that uniquely identify a target. Used to normalize
+// un-prefixed FileMap keys into target-prefixed form.
+const SUBDIR_TO_TARGET = {
+  agents: 'claude',
+  commands: 'claude',
+  rules: 'cursor',
+};
+
+/**
+ * Normalizes a FileMap so every key starts with a target prefix
+ * ("claude/..." or "cursor/..."). Accepts both:
+ *   - already-prefixed keys (left untouched)
+ *   - un-prefixed keys whose first segment is one of the well-known
+ *     target subdirs (agents, commands, rules)
+ *
+ * Unrecognized keys are dropped (with no error) to keep behavior conservative.
+ */
+export function normalizeFileMap(fileMap) {
+  const out = {};
+  for (const [key, content] of Object.entries(fileMap)) {
+    const norm = key.replace(/\\/g, '/');
+    const first = norm.split('/')[0];
+    if (first === 'claude' || first === 'cursor') {
+      out[norm] = content;
+      continue;
+    }
+    const inferred = SUBDIR_TO_TARGET[first];
+    if (inferred) {
+      out[`${inferred}/${norm}`] = content;
+      continue;
+    }
+    // Unrecognized: dropping is preserved for backward compatibility,
+    // but emit a stderr warning so silent content-loss is visible.
+    // (Slice 4 will pin the fetcher to prefixed shape and remove tolerance.)
+    if (typeof process !== 'undefined' && process.stderr && typeof process.stderr.write === 'function') {
+      process.stderr.write(
+        `warn: dev-agents-sync: dropped unrecognized FileMap key '${key}' (no recognized prefix or subdir)\n`,
+      );
+    }
+  }
+  return out;
+}
+
+class PathError extends Error {
+  constructor(message, { exitCode = 1 } = {}) {
+    super(message);
+    this.name = 'PathError';
+    this.exitCode = exitCode;
+  }
+}
+
+export function resolveConsumerPath(consumerRoot, relPath) {
+  if (typeof relPath !== 'string' || relPath.length === 0) {
+    throw new PathError(`invalid path: ${JSON.stringify(relPath)}`);
+  }
+
+  // Normalize to forward slashes for inspection
+  const normalized = relPath.replace(/\\/g, '/');
+  const parts = normalized.split('/').filter((p) => p.length > 0);
+
+  if (parts.length === 0) {
+    throw new PathError(`invalid path (empty): ${JSON.stringify(relPath)}`);
+  }
+  for (const part of parts) {
+    if (part === '..' || part === '.') {
+      throw new PathError(
+        `invalid path traversal in ${JSON.stringify(relPath)} (refusing to write outside consumer root)`,
+      );
+    }
+  }
+
+  const [target, ...rest] = parts;
+  const prefix = TARGET_PREFIX[target];
+  if (!prefix) {
+    throw new PathError(
+      `invalid path: unknown target prefix in ${JSON.stringify(relPath)} ` +
+        `(allowed: ${Object.keys(TARGET_PREFIX).join(', ')})`,
+    );
+  }
+  if (rest.length === 0) {
+    throw new PathError(`invalid path (target only): ${JSON.stringify(relPath)}`);
+  }
+
+  return path.join(consumerRoot, prefix, ...rest);
+}
+
+/**
+ * Writes a single managed file to the consumer repo.
+ * Throws with exitCode 1 if the existing file is unmanaged and `force` is not set.
+ */
+export function writeManagedFile({ absPath, relKey, content, force }) {
+  if (existsSync(absPath) && !force) {
+    const existing = readFileSync(absPath, 'utf8');
+    if (!hasMarker(existing)) {
+      const err = new Error(
+        `refusing to overwrite unmanaged file at ${relKey}: ` +
+          `${absPath} has no managed-by marker. ` +
+          `Delete or rename the file, or pass --force to overwrite.`,
+      );
+      err.exitCode = 1;
+      throw err;
+    }
+  }
+  mkdirSync(path.dirname(absPath), { recursive: true });
+  writeFileSync(absPath, content, 'utf8');
+}
+
+/** Returns true if the path under <root>/.claude or <root>/.cursor exists with content matching `expected`. */
+export function fileMatchesExpected(absPath, expected) {
+  if (!existsSync(absPath)) return false;
+  const actual = readFileSync(absPath, 'utf8');
+  return actual === expected;
+}

package/tests/auth.test.mjs

@@ -0,0 +1,290 @@
+/**
+ * tests/auth.test.mjs
+ *
+ * Tests for the auth chain:
+ *   1. GITHUB_TOKEN env var → use it
+ *   2. GITHUB_TOKEN absent, `gh auth token` shellout succeeds → use that
+ *   3. Both fail → exit 2 with actionable message naming both fallbacks
+ *
+ * Privacy invariants (from spec):
+ *   - Token is NEVER written to disk (lockfile after run must not contain the token).
+ *   - Token is NEVER logged (stderr/stdout must not contain the token string).
+ *
+ * These tests drive the auth module in isolation so the full CLI is not needed.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { resolveToken } from '../src/auth.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-auth-test-'));
+}
+
+/**
+ * Runs resolveToken with specific env and gh-shellout overrides.
+ * The production module accepts an injectable `ghAuthToken` function so tests
+ * can avoid real `gh` calls.
+ */
+async function resolveTokenWith({ envToken, ghTokenResult, ghTokenError } = {}) {
+  const env = envToken ? { GITHUB_TOKEN: envToken } : {};
+
+  const ghAuthToken = ghTokenError
+    ? async () => { throw ghTokenError; }
+    : async () => ghTokenResult ?? null;
+
+  return resolveToken({ env, ghAuthToken });
+}
+
+// ---------------------------------------------------------------------------
+// Token resolution — GITHUB_TOKEN env var
+// ---------------------------------------------------------------------------
+
+describe('resolveToken — GITHUB_TOKEN env var', () => {
+  it('returns the token from GITHUB_TOKEN when set', async () => {
+    const token = 'ghp_ENVTOKEN123456';
+    const result = await resolveTokenWith({ envToken: token });
+    assert.equal(result, token);
+  });
+
+  it('does not call ghAuthToken shellout when GITHUB_TOKEN is present', async () => {
+    let ghCalled = false;
+    const env = { GITHUB_TOKEN: 'ghp_TEST' };
+
+    await resolveToken({
+      env,
+      ghAuthToken: async () => {
+        ghCalled = true;
+        return 'should-not-be-returned';
+      },
+    });
+
+    assert.ok(!ghCalled, 'ghAuthToken must not be called when GITHUB_TOKEN is set');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Token resolution — gh auth token fallback
+// ---------------------------------------------------------------------------
+
+describe('resolveToken — gh auth token fallback', () => {
+  it('returns token from gh shellout when GITHUB_TOKEN is absent', async () => {
+    const ghToken = 'ghp_GHTOKEN789012';
+    const result = await resolveTokenWith({ ghTokenResult: ghToken });
+    assert.equal(result, ghToken);
+  });
+
+  it('returns null-or-throws when GITHUB_TOKEN is absent and gh returns empty', async () => {
+    let threw = false;
+    let result = null;
+
+    try {
+      result = await resolveTokenWith({ ghTokenResult: '' });
+    } catch {
+      threw = true;
+    }
+
+    // Both behaviors are acceptable: throw or return null/undefined
+    // What is NOT acceptable is returning a truthy empty string
+    if (!threw) {
+      assert.ok(
+        result === null || result === undefined,
+        `expected null/undefined when gh returns empty, got: ${JSON.stringify(result)}`,
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Token resolution — both fail → actionable error
+// ---------------------------------------------------------------------------
+
+describe('resolveToken — both fail', () => {
+  it('throws an error when both GITHUB_TOKEN and gh auth token are unavailable', async () => {
+    await assert.rejects(
+      resolveTokenWith({
+        ghTokenError: new Error('gh: not logged in'),
+      }),
+    );
+  });
+
+  it('error message mentions GITHUB_TOKEN', async () => {
+    let message = '';
+    try {
+      await resolveTokenWith({ ghTokenError: new Error('not logged in') });
+    } catch (err) {
+      message = err.message;
+    }
+    assert.ok(
+      message.includes('GITHUB_TOKEN'),
+      `error must mention GITHUB_TOKEN, got: ${message}`,
+    );
+  });
+
+  it('error message mentions `gh auth login` as a fallback', async () => {
+    let message = '';
+    try {
+      await resolveTokenWith({ ghTokenError: new Error('not logged in') });
+    } catch (err) {
+      message = err.message;
+    }
+    assert.ok(
+      message.includes('gh auth login'),
+      `error must mention 'gh auth login', got: ${message}`,
+    );
+  });
+
+  it('error produces exit code 2', async () => {
+    let exitCode = null;
+    try {
+      await resolveTokenWith({ ghTokenError: new Error('not logged in') });
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+    assert.equal(exitCode, 2, 'auth failure must produce exit code 2');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Privacy: token never written to disk
+// ---------------------------------------------------------------------------
+
+describe('auth — token never written to disk', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('lockfile does not contain the token after writeLockfile', () => {
+    const SECRET_TOKEN = 'ghp_SUPERSECRET_SHOULD_NEVER_APPEAR';
+
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-25T00:00:00Z',
+    });
+
+    const lockfileContent = readFileSync(
+      path.join(consumerDir, '.dev-agents-sync.json'),
+      'utf8',
+    );
+
+    assert.ok(
+      !lockfileContent.includes(SECRET_TOKEN),
+      'lockfile must never contain the auth token',
+    );
+  });
+
+  it('lockfile does not contain any string that looks like a GitHub token', () => {
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-25T00:00:00Z',
+    });
+
+    const lockfileContent = readFileSync(
+      path.join(consumerDir, '.dev-agents-sync.json'),
+      'utf8',
+    );
+
+    // GitHub token patterns: ghp_, gho_, github_pat_, etc.
+    const ghTokenPattern = /gh[pos]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+/;
+    assert.ok(
+      !ghTokenPattern.test(lockfileContent),
+      'lockfile must not contain any GitHub token pattern',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Privacy: token never logged
+// ---------------------------------------------------------------------------
+
+describe('auth — token never in logs', () => {
+  it('resolveToken does not emit the token to stdout', async () => {
+    const token = 'ghp_NEVERLOG987654';
+    const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+    let stdoutCapture = '';
+
+    process.stdout.write = (chunk, ...args) => {
+      stdoutCapture += chunk.toString();
+      return originalStdoutWrite(chunk, ...args);
+    };
+
+    try {
+      await resolveTokenWith({ envToken: token });
+    } finally {
+      process.stdout.write = originalStdoutWrite;
+    }
+
+    assert.ok(
+      !stdoutCapture.includes(token),
+      `token must not appear in stdout, captured: ${stdoutCapture.substring(0, 200)}`,
+    );
+  });
+
+  it('resolveToken does not emit the token to stderr', async () => {
+    const token = 'ghp_NEVERLOGERR987654';
+    const originalStderrWrite = process.stderr.write.bind(process.stderr);
+    let stderrCapture = '';
+
+    process.stderr.write = (chunk, ...args) => {
+      stderrCapture += chunk.toString();
+      return originalStderrWrite(chunk, ...args);
+    };
+
+    try {
+      await resolveTokenWith({ envToken: token });
+    } finally {
+      process.stderr.write = originalStderrWrite;
+    }
+
+    assert.ok(
+      !stderrCapture.includes(token),
+      `token must not appear in stderr, captured: ${stderrCapture.substring(0, 200)}`,
+    );
+  });
+
+  it('error message from auth failure does not contain any token value', async () => {
+    // Even a partial token must not appear in the error message
+    let errorMessage = '';
+    const fakeToken = 'ghp_LEAKED_TOKEN';
+
+    try {
+      // Simulate gh returning a token but then failing in a way that might leak it
+      await resolveToken({
+        env: {},
+        ghAuthToken: async () => {
+          const err = new Error(`Error: token ${fakeToken} is invalid`);
+          err.exitCode = 2;
+          throw err;
+        },
+      });
+    } catch (err) {
+      errorMessage = err.message;
+    }
+
+    assert.ok(
+      !errorMessage.includes(fakeToken),
+      `error message must not contain leaked token, got: ${errorMessage}`,
+    );
+  });
+});