@dalzoubi/dev-agents-sync 1.0.0

package/src/commands/update.mjs

@@ -0,0 +1,103 @@
+/**
+ * `update` subcommand.
+ *
+ * Reads the lockfile, resolves latest matching tag, fetches that tag's dist,
+ * and rewrites managed files for the recorded targets.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { readLockfile, writeLockfile } from '../lockfile.mjs';
+import { resolveRange } from '../range.mjs';
+import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
+import { hasMarker } from '../marker.mjs';
+
+function filterFileMapByTargets(fileMap, targets) {
+  const out = {};
+  for (const [key, content] of Object.entries(fileMap)) {
+    const prefix = key.split('/')[0];
+    if (targets.includes(prefix)) {
+      out[key] = content;
+    }
+  }
+  return out;
+}
+
+export async function runUpdate(consumerCwd, opts = {}) {
+  const { force = false, dryRun = false, token, fetcher, availableTags, repo = 'dalzoubi/dev-agents' } = opts;
+
+  if (typeof fetcher !== 'function') {
+    const err = new Error('runUpdate requires an injected fetcher');
+    err.exitCode = 2;
+    throw err;
+  }
+  if (!Array.isArray(availableTags)) {
+    const err = new Error('runUpdate requires availableTags');
+    err.exitCode = 2;
+    throw err;
+  }
+
+  const lock = readLockfile(consumerCwd);
+
+  const targetVersion = resolveRange(availableTags, lock.range);
+
+  if (targetVersion === lock.resolvedVersion) {
+    return {
+      upToDate: true,
+      resolvedVersion: lock.resolvedVersion,
+      message: `already up to date at v${lock.resolvedVersion}`,
+    };
+  }
+
+  const fileMap = await fetcher(repo, `v${targetVersion}`, token);
+  const normalized = normalizeFileMap(fileMap);
+  const scoped = filterFileMapByTargets(normalized, lock.targets);
+
+  const plannedWrites = [];
+  for (const [relKey, content] of Object.entries(scoped)) {
+    const absPath = resolveConsumerPath(consumerCwd, relKey);
+    plannedWrites.push({ relKey, absPath, content });
+  }
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      resolvedVersion: targetVersion,
+      previousVersion: lock.resolvedVersion,
+      files: plannedWrites.map(({ relKey }) => relKey),
+    };
+  }
+
+  // Collision check
+  for (const { absPath, relKey } of plannedWrites) {
+    if (existsSync(absPath) && !force) {
+      const existing = readFileSync(absPath, 'utf8');
+      if (!hasMarker(existing)) {
+        const err = new Error(
+          `refusing to overwrite unmanaged file at ${relKey} ` +
+            `(${absPath}). The marker is missing — pass --force to overwrite.`,
+        );
+        err.exitCode = 1;
+        throw err;
+      }
+    }
+  }
+
+  for (const { absPath, relKey, content } of plannedWrites) {
+    writeManagedFile({ absPath, relKey, content, force: true });
+  }
+
+  writeLockfile(consumerCwd, {
+    source: lock.source,
+    range: lock.range,
+    resolvedVersion: targetVersion,
+    targets: lock.targets,
+    lastUpdated: new Date().toISOString(),
+  });
+
+  return {
+    resolvedVersion: targetVersion,
+    previousVersion: lock.resolvedVersion,
+    files: plannedWrites.map(({ relKey }) => relKey),
+  };
+}

package/src/fetcher.mjs

@@ -0,0 +1,356 @@
+/**
+ * Fetcher abstraction.
+ *
+ * A fetcher is an async function:
+ *   async (repo, tag, token) => FileMap
+ *
+ * where FileMap is { [relativePath: string]: string content }.
+ * Relative paths use forward slashes and start with the target prefix
+ * ("claude/..." or "cursor/...").
+ *
+ * Both `defaultGithubFetcher` and `defaultGithubTagLister` accept an optional
+ * trailing options object `{ httpClient, tarExtractor }` purely as a test
+ * injection seam. Production callers do not need to pass it; sane defaults
+ * (`globalThis.fetch`, a `tar`-package extractor) are used.
+ */
+
+import { createHash } from 'node:crypto';
+import semver from 'semver';
+
+export const DEFAULT_REPO = 'dalzoubi/dev-agents';
+
+/**
+ * Error code attached to errors thrown by the stub default fetcher/tag-lister
+ * placeholder. Real network errors thrown by the implementations below MUST
+ * NOT use this code — it is reserved for genuinely-unimplemented stubs.
+ */
+export const STUB_NOT_IMPLEMENTED = 'STUB_NOT_IMPLEMENTED';
+
+const GITHUB_API = 'https://api.github.com';
+const STRICT_SEMVER_TAG = /^v\d+\.\d+\.\d+$/;
+
+const AUTH_HINT =
+  'set GITHUB_TOKEN or run `gh auth login`';
+
+/**
+ * Builds a generic, actionable error with `exitCode = 2`.
+ * Never embeds the token or raw upstream body.
+ */
+function makeError(message) {
+  const err = new Error(message);
+  err.exitCode = 2;
+  return err;
+}
+
+function authError(status) {
+  return makeError(
+    `authentication failed (HTTP ${status}) — ${AUTH_HINT}`,
+  );
+}
+
+function notFoundError(repo, tag) {
+  return makeError(`release v${tag} not found in ${repo}`);
+}
+
+function genericHttpError(status, context) {
+  return makeError(
+    `GitHub API request failed (HTTP ${status}) while ${context}`,
+  );
+}
+
+/**
+ * Builds the standard request init object for GitHub API JSON endpoints.
+ */
+function jsonInit(token) {
+  const headers = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return { headers };
+}
+
+/**
+ * Builds the standard request init object for asset binary downloads.
+ */
+function assetInit(token) {
+  const headers = {
+    Accept: 'application/octet-stream',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return { headers };
+}
+
+/**
+ * Builds the request init for the second hop after a redirect from the GitHub
+ * asset endpoint. The Location target is typically a pre-signed S3 URL with
+ * its own query-string auth; forwarding GitHub's Bearer token causes S3 to
+ * reject the request, so we strip Authorization entirely.
+ */
+function redirectInit() {
+  return {
+    headers: {
+      Accept: 'application/octet-stream',
+    },
+  };
+}
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 5;
+
+/**
+ * Downloads a release asset, manually following redirects without forwarding
+ * the Authorization header to the redirect target. Returns a successful
+ * response (`ok === true`); throws a generic CLI error otherwise.
+ */
+async function downloadAsset(httpClient, url, token, context) {
+  // First hop: GitHub asset URL with Bearer token, manual redirect.
+  const init = assetInit(token);
+  init.redirect = 'manual';
+  let res = await httpClient(url, init);
+
+  let hops = 0;
+  while (REDIRECT_STATUSES.has(res.status)) {
+    if (hops >= MAX_REDIRECTS) {
+      throw makeError(`too many redirects while ${context}`);
+    }
+    const location = res.headers?.get?.('location') ?? null;
+    if (!location) {
+      throw makeError(`redirect missing Location header while ${context}`);
+    }
+    // Subsequent hops: NO Authorization header.
+    const nextInit = redirectInit();
+    nextInit.redirect = 'manual';
+    res = await httpClient(location, nextInit);
+    hops += 1;
+  }
+
+  if (!res.ok) {
+    if (res.status === 401 || res.status === 403) {
+      throw authError(res.status);
+    }
+    throw genericHttpError(res.status, context);
+  }
+  return res;
+}
+
+/**
+ * Default httpClient: thin wrapper over `globalThis.fetch`.
+ * Network/transport failures are translated into generic CLI errors with
+ * `exitCode = 2` and no token leakage.
+ */
+async function defaultHttpClient(url, init) {
+  if (typeof globalThis.fetch !== 'function') {
+    throw makeError(
+      'global fetch is unavailable — Node.js 20 or newer is required',
+    );
+  }
+  try {
+    return await globalThis.fetch(url, init);
+  } catch (_cause) {
+    throw makeError('network request to GitHub failed');
+  }
+}
+
+/**
+ * Default tarExtractor: gunzips a tarball ArrayBuffer and returns a FileMap
+ * `{ [path]: utf8Content }`. Directory entries are skipped.
+ *
+ * Uses the `tar` npm package (added as a runtime dep). Imported lazily so the
+ * module loads even if `tar` isn't installed in environments that always
+ * inject their own extractor (e.g. tests).
+ */
+export async function defaultTarExtractor(buffer) {
+  let tar;
+  try {
+    tar = await import('tar');
+  } catch (_cause) {
+    throw makeError(
+      'tar extraction is unavailable — install the `tar` npm package',
+    );
+  }
+
+  const buf = Buffer.from(buffer);
+  const entries = {};
+
+  await new Promise((resolve, reject) => {
+    const parser = new tar.Parser({ gzip: true });
+    parser.on('entry', (entry) => {
+      // Skip directories.
+      if (entry.type === 'Directory' || entry.path.endsWith('/')) {
+        entry.resume();
+        return;
+      }
+      const chunks = [];
+      entry.on('data', (chunk) => chunks.push(chunk));
+      entry.on('end', () => {
+        entries[entry.path] = Buffer.concat(chunks).toString('utf8');
+      });
+      entry.on('error', reject);
+    });
+    parser.on('end', resolve);
+    parser.on('error', reject);
+    parser.end(buf);
+  });
+
+  return entries;
+}
+
+/**
+ * Lists release tags from a GitHub repo. Returns bare semver strings
+ * (no leading "v"), filtered to strict `MAJOR.MINOR.PATCH` form, with
+ * drafts and prereleases excluded, sorted descending by semver.
+ *
+ * @param {string} repo  "owner/name"
+ * @param {string} token GitHub token (Bearer auth)
+ * @param {{ httpClient?: Function }} [opts]
+ * @returns {Promise<string[]>}
+ */
+export async function defaultGithubTagLister(repo, token, opts = {}) {
+  const httpClient = opts.httpClient ?? defaultHttpClient;
+  const url = `${GITHUB_API}/repos/${repo}/releases`;
+
+  const res = await httpClient(url, jsonInit(token));
+
+  if (!res.ok) {
+    if (res.status === 401 || res.status === 403) {
+      throw authError(res.status);
+    }
+    throw genericHttpError(res.status, `listing releases for ${repo}`);
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch (_cause) {
+    throw makeError(
+      `failed to parse GitHub releases response for ${repo}`,
+    );
+  }
+
+  if (!Array.isArray(body)) {
+    return [];
+  }
+
+  const bare = body
+    .filter((r) => r && !r.draft && !r.prerelease)
+    .map((r) => r.tag_name)
+    .filter((t) => typeof t === 'string' && STRICT_SEMVER_TAG.test(t))
+    .map((t) => t.slice(1));
+
+  bare.sort((a, b) => semver.rcompare(a, b));
+  return bare;
+}
+
+/**
+ * Fetches a release's `dist-v<tag>.tar.gz` asset, optionally verifies the
+ * sidecar sha256, extracts it, strips the `dist/` prefix, and returns a
+ * FileMap.
+ *
+ * @param {string} repo   "owner/name"
+ * @param {string} tag    bare semver e.g. "1.0.0"
+ * @param {string} token  GitHub token
+ * @param {{ httpClient?: Function, tarExtractor?: Function }} [opts]
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function defaultGithubFetcher(repo, tag, token, opts = {}) {
+  const httpClient = opts.httpClient ?? defaultHttpClient;
+  const tarExtractor = opts.tarExtractor ?? defaultTarExtractor;
+
+  const releaseUrl = `${GITHUB_API}/repos/${repo}/releases/tags/v${tag}`;
+  const releaseRes = await httpClient(releaseUrl, jsonInit(token));
+
+  if (!releaseRes.ok) {
+    if (releaseRes.status === 401 || releaseRes.status === 403) {
+      throw authError(releaseRes.status);
+    }
+    if (releaseRes.status === 404) {
+      throw notFoundError(repo, tag);
+    }
+    throw genericHttpError(
+      releaseRes.status,
+      `fetching release v${tag} from ${repo}`,
+    );
+  }
+
+  let release;
+  try {
+    release = await releaseRes.json();
+  } catch (_cause) {
+    throw makeError(
+      `failed to parse release metadata for v${tag} in ${repo}`,
+    );
+  }
+
+  const assets = Array.isArray(release?.assets) ? release.assets : [];
+  const tarballName = `dist-v${tag}.tar.gz`;
+  const sidecarName = `${tarballName}.sha256`;
+
+  const tarballAsset = assets.find((a) => a && a.name === tarballName);
+  if (!tarballAsset) {
+    throw makeError(
+      `asset '${tarballName}' not found on release v${tag}`,
+    );
+  }
+  const sidecarAsset = assets.find((a) => a && a.name === sidecarName);
+
+  // Download the tarball (manual redirect to avoid forwarding the GitHub
+  // Authorization header to S3 — S3 rejects it and has its own signed query auth).
+  const tarRes = await downloadAsset(
+    httpClient,
+    tarballAsset.url,
+    token,
+    `downloading asset '${tarballName}'`,
+  );
+  const tarBuffer = await tarRes.arrayBuffer();
+
+  // If a sidecar is present, verify the sha256.
+  if (sidecarAsset) {
+    const sidecarRes = await downloadAsset(
+      httpClient,
+      sidecarAsset.url,
+      token,
+      `downloading sha256 sidecar '${sidecarName}'`,
+    );
+    const sidecarBuf = await sidecarRes.arrayBuffer();
+    const sidecarText = Buffer.from(sidecarBuf).toString('utf8').trim();
+    // sha256sum format: "<hex>  <filename>" — take the leading hex token.
+    const expectedHash = sidecarText.split(/\s+/)[0]?.toLowerCase() ?? '';
+
+    const actualHash = createHash('sha256')
+      .update(Buffer.from(tarBuffer))
+      .digest('hex')
+      .toLowerCase();
+
+    if (!expectedHash || expectedHash !== actualHash) {
+      throw makeError(`sha256 mismatch for ${tarballName}`);
+    }
+  }
+
+  // Extract and rewrite paths.
+  let entries;
+  try {
+    entries = await tarExtractor(tarBuffer);
+  } catch (_cause) {
+    throw makeError(
+      `failed to extract '${tarballName}'`,
+    );
+  }
+
+  const fileMap = {};
+  for (const [path, content] of Object.entries(entries ?? {})) {
+    if (typeof path !== 'string') continue;
+    if (path.endsWith('/')) continue; // directory entry
+    if (!path.startsWith('dist/')) continue;
+    const rewritten = path.slice('dist/'.length);
+    if (!rewritten) continue; // would be the bare "dist/" entry
+    fileMap[rewritten] = content;
+  }
+
+  return fileMap;
+}

package/src/index.mjs

@@ -0,0 +1,14 @@
+/**
+ * Public programmatic entry point for @dalzoubi/dev-agents-sync.
+ */
+
+export { readLockfile, writeLockfile, validateLockfile } from './lockfile.mjs';
+export { hasMarker, buildMarker, extractMarkerVersion } from './marker.mjs';
+export { resolveRange } from './range.mjs';
+export { resolveToken } from './auth.mjs';
+export { resolveConsumerPath } from './writer.mjs';
+export { runInit } from './commands/init.mjs';
+export { runUpdate } from './commands/update.mjs';
+export { runStatus } from './commands/status.mjs';
+export { runCheck } from './commands/check.mjs';
+export { runDiff } from './commands/diff.mjs';

package/src/lockfile.mjs

@@ -0,0 +1,147 @@
+/**
+ * Lockfile read/write/validate.
+ *
+ * The lockfile lives at <consumerCwd>/.dev-agents-sync.json.
+ * Output is byte-deterministic given the same inputs.
+ * The auth token is NEVER persisted into the lockfile.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const LOCKFILE_NAME = '.dev-agents-sync.json';
+export const DEFAULT_SOURCE = 'github:dalzoubi/dev-agents';
+export const SCHEMA_URL =
+  'https://raw.githubusercontent.com/dalzoubi/dev-agents/v1/schema/lockfile.schema.json';
+
+const VALID_TARGETS = new Set(['claude', 'cursor']);
+
+// Field order is load-bearing for determinism.
+const FIELD_ORDER = [
+  '$schema',
+  'source',
+  'range',
+  'resolvedVersion',
+  'targets',
+  'lastUpdated',
+];
+
+export function lockfilePath(consumerCwd) {
+  return path.join(consumerCwd, LOCKFILE_NAME);
+}
+
+class LockfileError extends Error {
+  constructor(message, { exitCode = 1, cause } = {}) {
+    super(message);
+    this.name = 'LockfileError';
+    this.exitCode = exitCode;
+    if (cause) this.cause = cause;
+  }
+}
+
+export function validateLockfile(lock) {
+  if (lock === null || lock === undefined || typeof lock !== 'object') {
+    throw new LockfileError('invalid lockfile: expected an object');
+  }
+
+  if (typeof lock.source !== 'string' || lock.source.length === 0) {
+    throw new LockfileError('invalid lockfile: missing or invalid `source`');
+  }
+  if (typeof lock.range !== 'string' || lock.range.length === 0) {
+    throw new LockfileError('invalid lockfile: missing or invalid `range`');
+  }
+  if (typeof lock.resolvedVersion !== 'string' || lock.resolvedVersion.length === 0) {
+    throw new LockfileError(
+      'invalid lockfile: missing or invalid `resolvedVersion`',
+    );
+  }
+  if (!Array.isArray(lock.targets)) {
+    throw new LockfileError('invalid lockfile: `targets` must be an array');
+  }
+  if (lock.targets.length === 0) {
+    throw new LockfileError('invalid lockfile: `targets` must not be empty');
+  }
+  for (const t of lock.targets) {
+    if (!VALID_TARGETS.has(t)) {
+      throw new LockfileError(
+        `invalid lockfile: unknown value in \`targets\`: ${JSON.stringify(t)} ` +
+          `(allowed: ${[...VALID_TARGETS].join(', ')})`,
+      );
+    }
+  }
+  return true;
+}
+
+/**
+ * Returns the canonical, deterministic JSON serialization of a lockfile.
+ * Fields are emitted in a stable order; targets are sorted; trailing newline appended.
+ */
+export function serializeLockfile(lock) {
+  const out = {};
+  // Always include $schema first (default if missing)
+  if (lock.$schema || lock.$schema === undefined) {
+    out.$schema = lock.$schema || SCHEMA_URL;
+  }
+  for (const key of FIELD_ORDER) {
+    if (key === '$schema') continue;
+    if (lock[key] === undefined) continue;
+    if (key === 'targets') {
+      out.targets = [...lock.targets].sort();
+    } else {
+      out[key] = lock[key];
+    }
+  }
+  return JSON.stringify(out, null, 2) + '\n';
+}
+
+/**
+ * Writes a lockfile to <consumerCwd>/.dev-agents-sync.json.
+ * The optional `_options` arg is accepted but never persisted (privacy invariant:
+ * tokens or other extra context must not land on disk).
+ */
+export function writeLockfile(consumerCwd, lock, _options) {
+  const normalized = {
+    $schema: lock.$schema || SCHEMA_URL,
+    source: lock.source ?? DEFAULT_SOURCE,
+    range: lock.range,
+    resolvedVersion: lock.resolvedVersion,
+    targets: lock.targets,
+    lastUpdated: lock.lastUpdated,
+  };
+  validateLockfile(normalized);
+  const json = serializeLockfile(normalized);
+  writeFileSync(lockfilePath(consumerCwd), json, 'utf8');
+  return normalized;
+}
+
+export function readLockfile(consumerCwd) {
+  const file = lockfilePath(consumerCwd);
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      throw new LockfileError(
+        `no lockfile found at ${file} — run \`dev-agents-sync init\` first`,
+        { exitCode: 1, cause: err },
+      );
+    }
+    throw new LockfileError(`could not read lockfile at ${file}`, {
+      exitCode: 2,
+      cause: err,
+    });
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new LockfileError(
+      `invalid JSON in lockfile at ${file}: could not parse`,
+      { exitCode: 1, cause: err },
+    );
+  }
+
+  validateLockfile(parsed);
+  return parsed;
+}

package/src/marker.mjs

@@ -0,0 +1,61 @@
+/**
+ * Managed-file marker.
+ *
+ * Format: <!-- managed-by: dev-agents-sync vX.Y.Z -->
+ *
+ * Detection: the marker is the first non-empty body line, where "body" means
+ *   - the entire file when there is no YAML frontmatter
+ *   - the content after the closing `---` of the frontmatter, otherwise
+ */
+
+const MARKER_RE = /^<!--\s*managed-by:\s*dev-agents-sync\s+v([0-9]+\.[0-9]+\.[0-9]+(?:[-+][\w.-]+)?)\s*-->\s*$/;
+
+export function buildMarker(version) {
+  return `<!-- managed-by: dev-agents-sync v${version} -->`;
+}
+
+/**
+ * Returns the body of the file with frontmatter stripped (if any).
+ * If the file starts with `---` on its first line and a closing `---` is
+ * found later, everything between (inclusive) is removed.
+ */
+function stripFrontmatter(content) {
+  if (!content) return '';
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== '---') {
+    return content;
+  }
+  // Find closing `---`
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      return lines.slice(i + 1).join('\n');
+    }
+  }
+  // Unterminated frontmatter — treat the whole thing as body
+  return content;
+}
+
+function firstNonEmptyLine(text) {
+  const lines = text.split(/\r?\n/);
+  for (const line of lines) {
+    if (line.trim().length > 0) return line;
+  }
+  return null;
+}
+
+export function hasMarker(content) {
+  if (!content) return false;
+  const body = stripFrontmatter(content);
+  const first = firstNonEmptyLine(body);
+  if (first === null) return false;
+  return MARKER_RE.test(first);
+}
+
+export function extractMarkerVersion(content) {
+  if (!content) return null;
+  const body = stripFrontmatter(content);
+  const first = firstNonEmptyLine(body);
+  if (first === null) return null;
+  const m = first.match(MARKER_RE);
+  return m ? m[1] : null;
+}