draftgo-cli 1.0.4

package/src/releaseInstall.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { PACKAGE_ROOT } = require('./paths');
+
+const MARKER = '.draftgo-install.json';
+const REPO = process.env.DRAFTGO_REPO || 'draftgo/draftgo-cli';
+const BASE_URL = process.env.DRAFTGO_INSTALL_BASE_URL || 'https://draftgo.cn/draftgo-cli';
+const MIRROR = process.env.DRAFTGO_GITHUB_MIRROR || `https://ghproxy.net/https://github.com/${REPO}/releases/download`;
+
+function readInstallMarker() {
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, MARKER), 'utf8'));
+    if (!marker.installRoot || !marker.binDir) return null;
+    return { installRoot: path.resolve(marker.installRoot), binDir: path.resolve(marker.binDir) };
+  } catch { return null; }
+}
+
+function download(url, output, timeoutMs = 15000, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) return reject(new Error('Too many download redirects.'));
+    const parsed = new URL(url);
+    const transport = parsed.protocol === 'http:' ? http : https;
+    const req = transport.get(parsed, { timeout: timeoutMs, headers: { 'user-agent': 'draftgo-cli' } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return resolve(download(new URL(res.headers.location, parsed).toString(), output, timeoutMs, redirects + 1));
+      }
+      if (res.statusCode !== 200) { res.resume(); return reject(new Error(`HTTP ${res.statusCode}`)); }
+      const stream = fs.createWriteStream(output, { flags: 'wx' });
+      stream.on('error', reject);
+      res.on('error', reject);
+      stream.on('finish', () => stream.close(() => resolve(url)));
+      res.pipe(stream);
+    });
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('Download timed out.')));
+  });
+}
+
+async function downloadFirst(urls, output) {
+  const errors = [];
+  for (const url of urls) {
+    try { return { url: await download(url, output), output }; }
+    catch (error) { errors.push(`${url}: ${error.message}`); try { fs.rmSync(output, { force: true }); } catch {} }
+  }
+  throw new Error(`Unable to download DraftGo release.\n${errors.join('\n')}`);
+}
+
+function hashFile(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function writeLauncher(binDir, packageDir) {
+  fs.mkdirSync(binDir, { recursive: true });
+  if (process.platform === 'win32') {
+    const launcher = path.join(binDir, 'draftgo.cmd');
+    fs.writeFileSync(launcher, `@echo off\r\nnode "${path.join(packageDir, 'bin', 'draftgo.js')}" %*\r\n`, 'ascii');
+    return launcher;
+  }
+  const launcher = path.join(binDir, 'draftgo');
+  fs.writeFileSync(launcher, `#!/usr/bin/env sh\nexec node "${path.join(packageDir, 'bin', 'draftgo.js')}" "$@"\n`, { mode: 0o755 });
+  fs.chmodSync(launcher, 0o755);
+  return launcher;
+}
+
+async function installRelease(version, expectedSha, marker = readInstallMarker()) {
+  if (!marker) return null;
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(version))) throw new Error('Invalid release version.');
+  fs.mkdirSync(marker.installRoot, { recursive: true });
+  const tempDir = fs.mkdtempSync(path.join(marker.installRoot, '.update-'));
+  const archive = path.join(tempDir, `draftgo-cli-${version}.tgz`);
+  const asset = path.basename(archive);
+  const urls = [`${BASE_URL}/${asset}`, `${MIRROR}/v${version}/${asset}`, `https://github.com/${REPO}/releases/download/v${version}/${asset}`];
+  try {
+    const downloaded = await downloadFirst(urls, archive);
+    let checksum = expectedSha;
+    if (!checksum) {
+      const checksumFile = path.join(tempDir, `${asset}.sha256`);
+      await download(`${downloaded.url}.sha256`, checksumFile);
+      checksum = fs.readFileSync(checksumFile, 'utf8').trim().split(/\s+/)[0];
+    }
+    if (!/^[0-9a-f]{64}$/i.test(String(checksum)) || hashFile(archive).toLowerCase() !== checksum.toLowerCase()) {
+      throw new Error('DraftGo archive checksum mismatch.');
+    }
+    const staged = path.join(tempDir, 'package');
+    fs.mkdirSync(staged);
+    const extract = spawnSync('tar', ['-xzf', archive, '-C', staged, '--strip-components=1'], { encoding: 'utf8', shell: false });
+    if (extract.error || extract.status !== 0) throw new Error(extract.error ? extract.error.message : (extract.stderr || 'Unable to extract DraftGo release.'));
+    const installedVersion = JSON.parse(fs.readFileSync(path.join(staged, 'package.json'), 'utf8')).version;
+    if (installedVersion !== version) throw new Error(`Release version mismatch: expected ${version}, received ${installedVersion}.`);
+    fs.writeFileSync(path.join(staged, MARKER), JSON.stringify(marker, null, 2) + '\n');
+    const destination = path.join(marker.installRoot, version);
+    if (fs.existsSync(destination)) fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(staged, destination);
+    return { launcher: writeLauncher(marker.binDir, destination), destination };
+  } finally { fs.rmSync(tempDir, { recursive: true, force: true }); }
+}
+
+module.exports = { MARKER, readInstallMarker, installRelease, hashFile, writeLauncher };

package/src/runtimeFiles.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = 1;
+const RETRYABLE_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+function draftgoRoot(projectDir) { return path.resolve(projectDir, '.draftgo'); }
+function manifestPath(projectDir) { return path.join(draftgoRoot(projectDir), 'runtime-manifest.json'); }
+function inside(root, target) { const relation = path.relative(path.resolve(root), path.resolve(target)); return relation && !relation.startsWith('..') && !path.isAbsolute(relation); }
+function load(projectDir) {
+  const file = manifestPath(projectDir);
+  if (!fs.existsSync(file)) return { schema_version: SCHEMA_VERSION, entries: [] };
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!value || value.schema_version !== SCHEMA_VERSION || !Array.isArray(value.entries)) throw new Error('Invalid .draftgo/runtime-manifest.json.');
+  return value;
+}
+function replaceFile(temporary, file, rename = fs.renameSync, wait = (ms) => Atomics.wait(sleepBuffer, 0, 0, ms)) {
+  for (let attempt = 0; ; attempt += 1) {
+    try { rename(temporary, file); return; } catch (error) {
+      if (!RETRYABLE_RENAME_CODES.has(error.code) || attempt >= 5) throw error;
+      wait(20 * (attempt + 1));
+    }
+  }
+}
+function save(projectDir, value) {
+  const file = manifestPath(projectDir); fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+  try { replaceFile(temporary, file); } catch (error) {
+    try { fs.rmSync(temporary, { force: true }); } catch { /* retain the original rename error */ }
+    throw error;
+  }
+}
+function register(projectDir, file, type, command, options = {}) {
+  const root = draftgoRoot(projectDir); const absolute = path.resolve(file);
+  if (!inside(root, absolute)) throw new Error('Managed runtime files must stay inside .draftgo.');
+  if (fs.existsSync(absolute) && !inside(fs.realpathSync(root), fs.realpathSync(absolute))) throw new Error('Managed runtime file escapes .draftgo.');
+  const relative = path.relative(root, absolute).replace(/\\/g, '/'); const value = load(projectDir);
+  const entry = { path: relative, type: String(type), command: String(command), created_at: new Date().toISOString(), cleanable: options.cleanable !== false };
+  value.entries = value.entries.filter((item) => item.path !== relative); value.entries.push(entry); save(projectDir, value); return entry;
+}
+function managedPath(projectDir, ...parts) { const file = path.join(draftgoRoot(projectDir), ...parts); if (!inside(draftgoRoot(projectDir), file)) throw new Error('Managed path escapes .draftgo.'); return file; }
+module.exports = { SCHEMA_VERSION, draftgoRoot, manifestPath, load, save, register, managedPath, inside, replaceFile };

package/src/skill.js

@@ -0,0 +1,295 @@
+'use strict';
+
+// Per-platform skill renderer.
+//
+// Every AI-tool target receives the complete Skill and its domain references
+// in that target's own project directory.
+//
+// Templating in .md files:
+//   {{SKILL_DIR}}     → platform's project-relative skill dir (forward slashes)
+//   {{SKILL_SCRIPTS}} → {{SKILL_DIR}}/scripts
+
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('fs');
+const { RESOURCES_DIR } = require('./paths');
+const paths = require('./paths');
+const {
+  exists, ensureDir, readText, writeText, copyFile, removePath,
+  appendGitignoreLine,
+} = require('./fsx');
+
+const SKILL_SOURCE_DIR = path.join(RESOURCES_DIR, 'skill');
+const MAX_VERSION_FILE_BYTES = 128;
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+function getPackageVersion() {
+  try {
+    return require(path.join(paths.PACKAGE_ROOT, 'package.json')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function readInstalledVersion(projectDir) {
+  const file = paths.versionFile(projectDir);
+  let linkStat;
+  try {
+    linkStat = fs.lstatSync(file);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (linkStat.isSymbolicLink() || !linkStat.isFile()) {
+    throw new Error('Invalid .draftgo/.version: expected a regular file.');
+  }
+
+  let descriptor;
+  let raw;
+  try {
+    const noFollow = Number.isInteger(fs.constants.O_NOFOLLOW) ? fs.constants.O_NOFOLLOW : 0;
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > MAX_VERSION_FILE_BYTES) {
+      throw new Error('Invalid .draftgo/.version: file is too large or not regular.');
+    }
+    const buffer = Buffer.alloc(MAX_VERSION_FILE_BYTES + 1);
+    const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+    if (bytes > MAX_VERSION_FILE_BYTES) {
+      throw new Error('Invalid .draftgo/.version: file exceeds 128 bytes.');
+    }
+    raw = buffer.subarray(0, bytes).toString('utf8');
+  } catch (error) {
+    if (error && error.code === 'ELOOP') {
+      throw new Error('Invalid .draftgo/.version: symbolic links are not allowed.');
+    }
+    throw error;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+
+  const version = raw.trim();
+  const validLineEnding = raw === version || raw === `${version}\n` || raw === `${version}\r\n`;
+  if (!validLineEnding || !VERSION_PATTERN.test(version)) {
+    throw new Error('Invalid .draftgo/.version: expected one semantic version.');
+  }
+  return version;
+}
+
+function writeInstalledVersion(projectDir) {
+  const file = paths.versionFile(projectDir);
+  ensureDir(path.dirname(file));
+  const temporary = path.join(
+    path.dirname(file),
+    `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`,
+  );
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, 'wx', 0o600);
+    fs.writeFileSync(descriptor, getPackageVersion() + '\n', 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(temporary, file);
+  } finally {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch { /* Preserve the original failure. */ }
+    }
+    try { fs.rmSync(temporary, { force: true }); } catch { /* Best-effort cleanup. */ }
+  }
+}
+
+function renderFrontmatter(fm) {
+  if (!fm) return '';
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm)) {
+    const s = String(v);
+    if (/[:#"\n]/.test(s)) {
+      lines.push(`${k}: "${s.replace(/"/g, '\\"')}"`);
+    } else {
+      lines.push(`${k}: ${s}`);
+    }
+  }
+  lines.push('---', '');
+  return lines.join('\n');
+}
+
+function splitFrontmatter(text) {
+  const normalized = String(text || '').replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) return { frontmatter: {}, body: normalized };
+  const end = normalized.indexOf('\n---\n', 4);
+  if (end < 0) return { frontmatter: {}, body: normalized };
+  const frontmatter = {};
+  for (const line of normalized.slice(4, end).split('\n')) {
+    const colon = line.indexOf(':');
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body: normalized.slice(end + 5) };
+}
+
+function substitute(text, platform) {
+  const skillDir = platform.skillDir;
+  const scriptsDir = `${skillDir}/scripts`;
+  return text
+    .replace(/\{\{SKILL_DIR\}\}/g, skillDir)
+    .replace(/\{\{SKILL_SCRIPTS\}\}/g, scriptsDir);
+}
+
+function walk(root, onFile) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.name === '__pycache__') continue;
+    const abs = path.join(root, entry.name);
+    if (entry.isDirectory()) walk(abs, onFile);
+    else if (entry.isFile()) onFile(abs);
+  }
+}
+
+function renderInto(destDir, platform) {
+  ensureDir(destDir);
+  const srcRoot = SKILL_SOURCE_DIR;
+  walk(srcRoot, (absSrc) => {
+    const rel = path.relative(srcRoot, absSrc);
+    const absDst = path.join(destDir, rel);
+    ensureDir(path.dirname(absDst));
+    if (absSrc.endsWith('.md')) {
+      let body = readText(absSrc);
+      if (rel === 'SKILL.md') {
+        const parsed = splitFrontmatter(body);
+        body = renderFrontmatter({ ...(platform.frontmatter || {}), ...parsed.frontmatter }) + parsed.body;
+      }
+      body = substitute(body, platform);
+      writeText(absDst, body);
+    } else {
+      copyFile(absSrc, absDst);
+    }
+  });
+
+}
+
+function validateRenderedSkill(assetDir) {
+  const main = path.join(assetDir, 'SKILL.md');
+  if (!exists(main)) throw new Error('渲染结果缺少 SKILL.md');
+  const text = readText(main);
+  const firstEnd = text.indexOf('\n---\n', 4);
+  const body = firstEnd >= 0 ? text.slice(firstEnd + 5) : '';
+  if (!text.startsWith('---\n') || firstEnd < 0 || body.startsWith('---\n')) {
+    throw new Error('SKILL.md frontmatter 必须且只能有一个');
+  }
+  if (/\{\{(?:SKILL_DIR|SKILL_SCRIPTS)\}\}/.test(text)) {
+    throw new Error('SKILL.md 仍包含未替换占位符');
+  }
+}
+
+function ensureRuntime(projectDir) {
+  appendGitignoreLine(projectDir, '.draftgo/config.json');
+  appendGitignoreLine(projectDir, '.draftgo/token');
+  appendGitignoreLine(projectDir, '.draftgo/worktree/');
+  appendGitignoreLine(projectDir, '.draftgo/conflicts/');
+}
+
+function installPlatform(projectDir, platform, opts = {}) {
+  if (!exists(SKILL_SOURCE_DIR)) {
+    throw new Error(
+      `Skill source missing: ${SKILL_SOURCE_DIR}. The CLI package may be broken.`
+    );
+  }
+  const destAsset = path.join(projectDir, platform.assetDir);
+  const destMain  = path.join(projectDir, platform.mainFile);
+  const mainOutsideAsset = path.relative(destAsset, destMain).startsWith('..');
+  if ((exists(destAsset) || exists(destMain)) && !opts.force) {
+    return { path: platform.mainFile, skipped: true };
+  }
+
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const stageAsset = `${destAsset}.tmp-${token}`;
+  const backupAsset = `${destAsset}.bak-${token}`;
+  const stageMain = mainOutsideAsset ? `${destMain}.tmp-${token}` : null;
+  const backupMain = mainOutsideAsset ? `${destMain}.bak-${token}` : null;
+  let assetBackedUp = false;
+  let mainBackedUp = false;
+  let assetInstalled = false;
+  let mainInstalled = false;
+
+  try {
+    renderInto(stageAsset, platform);
+    validateRenderedSkill(stageAsset);
+    if (mainOutsideAsset) copyFile(path.join(stageAsset, 'SKILL.md'), stageMain);
+
+    ensureDir(path.dirname(destAsset));
+    if (exists(destAsset)) {
+      fs.renameSync(destAsset, backupAsset);
+      assetBackedUp = true;
+    }
+    if (mainOutsideAsset && exists(destMain)) {
+      ensureDir(path.dirname(destMain));
+      fs.renameSync(destMain, backupMain);
+      mainBackedUp = true;
+    }
+
+    fs.renameSync(stageAsset, destAsset);
+    assetInstalled = true;
+    if (mainOutsideAsset) {
+      fs.renameSync(stageMain, destMain);
+      mainInstalled = true;
+    }
+  } catch (err) {
+    if (mainInstalled && exists(destMain)) removePath(destMain);
+    if (assetInstalled && exists(destAsset)) removePath(destAsset);
+    if (mainBackedUp && exists(backupMain)) fs.renameSync(backupMain, destMain);
+    if (assetBackedUp && exists(backupAsset)) fs.renameSync(backupAsset, destAsset);
+    throw err;
+  } finally {
+    if (exists(stageAsset)) removePath(stageAsset);
+    if (stageMain && exists(stageMain)) removePath(stageMain);
+  }
+
+  if (exists(backupAsset)) removePath(backupAsset);
+  if (backupMain && exists(backupMain)) removePath(backupMain);
+  if (!exists(destMain)) throw new Error(`安装后缺少入口文件：${platform.mainFile}`);
+
+  return { path: platform.mainFile };
+}
+
+function uninstallPlatform(projectDir, platform) {
+  const destAsset = path.join(projectDir, platform.assetDir);
+  const destMain  = path.join(projectDir, platform.mainFile);
+  let removed = false;
+  if (exists(destAsset)) { removePath(destAsset); removed = true; }
+  if (path.relative(destAsset, destMain).startsWith('..') && exists(destMain)) {
+    removePath(destMain); removed = true;
+  }
+  return removed;
+}
+
+function statusPlatform(projectDir, platform) {
+  return { installed: exists(path.join(projectDir, platform.mainFile)) };
+}
+
+function installAll(projectDir, platforms, opts = {}) {
+  ensureRuntime(projectDir);
+  const results = [];
+  for (const p of platforms) {
+    results.push({ platform: p, result: installPlatform(projectDir, p, opts) });
+  }
+  if (results.every((item) => !item.result.skipped)) writeInstalledVersion(projectDir);
+  return results;
+}
+
+module.exports = {
+  SKILL_SOURCE_DIR,
+  getPackageVersion,
+  readInstalledVersion,
+  writeInstalledVersion,
+  installPlatform,
+  uninstallPlatform,
+  statusPlatform,
+  installAll,
+  ensureRuntime,
+  splitFrontmatter,
+};

package/src/targets.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// Public Skill target registry backed by shared platform descriptors.
+
+const { platforms } = require('./platforms');
+const skill = require('./skill');
+
+function makeInstaller(p) {
+  return {
+    name: p.name,
+    displayName: p.displayName,
+    mainFile: p.mainFile,
+    assetDir: p.assetDir,
+    install(projectDir, opts) {
+      return skill.installPlatform(projectDir, p, opts || {});
+    },
+    uninstall(projectDir) {
+      return skill.uninstallPlatform(projectDir, p);
+    },
+    status(projectDir) {
+      return skill.statusPlatform(projectDir, p);
+    },
+  };
+}
+
+const all = platforms.map(makeInstaller);
+const byName = Object.fromEntries(all.map((i) => [i.name, i]));
+
+function resolveTargets(input) {
+  if (!input) return { resolved: [], unknown: [] };
+  if (input === 'all') return { resolved: all.slice(), unknown: [] };
+  const list = Array.isArray(input) ? input : [input];
+  if (list.includes('all')) return { resolved: all.slice(), unknown: [] };
+  const resolved = [];
+  const unknown = [];
+  for (const name of list) {
+    if (byName[name]) resolved.push(byName[name]);
+    else unknown.push(name);
+  }
+  return { resolved, unknown };
+}
+
+module.exports = { all, byName, resolveTargets };

package/src/timeout.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+function parseTimeout(value) {
+  if (value == null) return undefined;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) {
+    throw new TypeError('--timeout must be a positive integer in milliseconds.');
+  }
+  const timeoutMs = Number(text);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
+    throw new TypeError(`--timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`);
+  }
+  return timeoutMs;
+}
+
+module.exports = { MAX_TIMEOUT_MS, parseTimeout };

package/src/updateCheck.js

@@ -0,0 +1,100 @@
+'use strict';
+
+// Fetch the latest draftgo-cli version from the DraftGo release endpoint.
+// Results are cached for 24 hours so update stays fast and deterministic.
+
+const http = require('http');
+const https = require('https');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const REPO = process.env.DRAFTGO_REPO || 'draftgo/draftgo-cli';
+const RELEASE_BASE_URL = process.env.DRAFTGO_INSTALL_BASE_URL || 'https://draftgo.cn/draftgo-cli';
+const RELEASE_URLS = [
+  `${RELEASE_BASE_URL}/latest.json`,
+  `https://api.github.com/repos/${REPO}/releases/latest`,
+];
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_FILE = path.join(os.homedir(), '.draftgo-cli', 'update-check.json');
+
+function readCache() {
+  try {
+    const cached = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (!cached.version || !cached.checkedAt) return null;
+    if (Date.now() - Number(cached.checkedAt) > CACHE_TTL_MS) return null;
+    return String(cached.version);
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(version) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({ version, checkedAt: Date.now() }) + '\n', 'utf8');
+  } catch {
+    // Cache failures must never block CLI work.
+  }
+}
+
+function requestVersion(url, timeoutMs, redirects = 0) {
+  return new Promise((resolve) => {
+    if (redirects > 5) return resolve(null);
+    let parsed;
+    try { parsed = new URL(url); } catch { return resolve(null); }
+    const transport = parsed.protocol === 'http:' ? http : https;
+    let req;
+    try {
+      req = transport.get(parsed, {
+        timeout: timeoutMs,
+        headers: { accept: 'application/json', 'user-agent': 'draftgo-cli' },
+      }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          return resolve(requestVersion(new URL(res.headers.location, parsed).toString(), timeoutMs, redirects + 1));
+        }
+        if (res.statusCode !== 200) { res.resume(); return resolve(null); }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+          if (body.length > 64 * 1024) req.destroy();
+        });
+        res.on('end', () => {
+          try {
+            const payload = JSON.parse(body);
+            resolve(payload.version || String(payload.tag_name || '').replace(/^v/, '') || null);
+          } catch { resolve(null); }
+        });
+      });
+    } catch { return resolve(null); }
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function fetchLatestVersion(timeoutMs = 3000, opts = {}) {
+  if (!opts.force) {
+    const cached = readCache();
+    if (cached) return Promise.resolve(cached);
+  }
+  for (const url of RELEASE_URLS) {
+    const version = await requestVersion(url, timeoutMs);
+    if (version) { writeCache(version); return version; }
+  }
+  return null;
+}
+
+// Compare 'a.b.c' ignoring prerelease tags. Returns 1 / 0 / -1.
+function cmpSemver(a, b) {
+  const pa = String(a).split('-')[0].split('.').map((x) => Number(x) || 0);
+  const pb = String(b).split('-')[0].split('.').map((x) => Number(x) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+module.exports = { fetchLatestVersion, cmpSemver, readCache, requestVersion, CACHE_TTL_MS };