@wildwinter/simple-vc-lib 0.0.2

package/dist/simpleVcLib.js

@@ -0,0 +1,731 @@
+import { join, dirname, resolve } from 'path';
+import { existsSync, readFileSync, statSync, unlinkSync, rmSync, accessSync, constants, chmodSync, writeFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+
+const VALID_SYSTEMS = ['git', 'perforce', 'plastic', 'svn', 'filesystem'];
+
+/**
+ * Load explicit VC configuration, if any.
+ * Checks the SIMPLE_VC environment variable first, then walks up from
+ * startDir looking for a .vcconfig JSON file.
+ *
+ * .vcconfig format: { "system": "git" | "perforce" | "plastic" | "svn" | "filesystem" }
+ *
+ * @param {string} startDir - Directory to begin walking upward from.
+ * @returns {{ system: string } | null}
+ */
+function loadConfig(startDir) {
+  const envSystem = process.env.SIMPLE_VC?.toLowerCase();
+  if (envSystem && VALID_SYSTEMS.includes(envSystem)) {
+    return { system: envSystem };
+  }
+
+  let dir = startDir;
+  while (true) {
+    const configPath = join(dir, '.vcconfig');
+    if (existsSync(configPath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+        const system = parsed?.system?.toLowerCase();
+        if (system && VALID_SYSTEMS.includes(system)) {
+          return { system };
+        }
+      } catch {
+        // Malformed .vcconfig — ignore and fall through to auto-detection.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Run a CLI command synchronously.
+ * Arguments are passed as an array to avoid shell-injection and handle spaces in paths.
+ */
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    timeout: options.timeout ?? 10000,
+    cwd: options.cwd,
+    windowsHide: true,
+  });
+
+  return {
+    exitCode: result.status ?? -1,
+    output: (result.stdout ?? '').trim(),
+    error: (result.stderr ?? '').trim(),
+    timedOut: result.signal === 'SIGTERM' || result.signal === 'SIGKILL',
+  };
+}
+
+// Maps a VCS root directory to its system name.
+// Populated on first detection; avoids repeated directory walks for the same repo.
+const _rootCache = new Map();
+
+/** Clear the detection cache. Called when the provider override is cleared. */
+function clearDetectorCache() {
+  _rootCache.clear();
+}
+
+/**
+ * Auto-detect the active version control system for a given file path.
+ * Walks up the directory tree looking for VC markers, then checks for Perforce.
+ * Falls back to 'filesystem' if nothing is found.
+ *
+ * @param {string} absPath - Absolute path of the file (may not exist yet).
+ * @returns {'git' | 'plastic' | 'svn' | 'perforce' | 'filesystem'}
+ */
+function detectProvider(absPath) {
+  let dir;
+  try {
+    dir = statSync(absPath).isDirectory() ? absPath : dirname(absPath);
+  } catch {
+    // Path doesn't exist yet — use its parent directory.
+    dir = dirname(absPath);
+  }
+
+  // Check whether any ancestor is a known VCS root before doing any I/O.
+  let current = dir;
+  while (true) {
+    if (_rootCache.has(current)) return _rootCache.get(current);
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  // Walk up looking for VC marker directories/files.
+  current = dir;
+  while (true) {
+    if (existsSync(join(current, '.git'))) {
+      _rootCache.set(current, 'git');
+      return 'git';
+    }
+    if (existsSync(join(current, '.plastic'))) {
+      _rootCache.set(current, 'plastic');
+      return 'plastic';
+    }
+    if (existsSync(join(current, '.svn'))) {
+      _rootCache.set(current, 'svn');
+      return 'svn';
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  // Perforce has no marker directory; detect by running `p4 info`.
+  const p4 = runCommand('p4', ['info'], { timeout: 3000 });
+  if (p4.exitCode === 0 && p4.output.includes('Client name:')) return 'perforce';
+
+  return 'filesystem';
+}
+
+/**
+ * @typedef {'ok' | 'locked' | 'outOfDate' | 'error'} VCStatus
+ * @typedef {{ success: boolean, status: VCStatus, message: string }} VCResult
+ */
+
+/** @returns {VCResult} */
+function okResult(message = '') {
+  return { success: true, status: 'ok', message };
+}
+
+/** @returns {VCResult} */
+function errorResult(status, message) {
+  return { success: false, status, message };
+}
+
+function isWritable$1(filePath) {
+  try {
+    accessSync(filePath, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function makeWritable$1(filePath) {
+  try {
+    const mode = statSync(filePath).mode;
+    chmodSync(filePath, mode | 0o200);
+    return isWritable$1(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function git(args, cwd) {
+  return runCommand('git', args, { cwd });
+}
+
+/**
+ * Returns true if the file is tracked by git (exists in the index).
+ */
+function isTracked$2(filePath) {
+  const result = git(['ls-files', '--error-unmatch', filePath], dirname(filePath));
+  return result.exitCode === 0;
+}
+
+/**
+ * Git provider.
+ *
+ * Git does not use file locking, so prepareToWrite only needs to ensure the
+ * file is writable at the OS level. finishedWrite stages new files with git add.
+ */
+class GitProvider {
+  get name() { return 'git'; }
+
+  prepareToWrite(filePath) {
+    if (!existsSync(filePath)) return okResult();
+    if (isWritable$1(filePath)) return okResult();
+    if (makeWritable$1(filePath)) return okResult('File made writable');
+    return errorResult('error', `Cannot make file writable: ${filePath}`);
+  }
+
+  finishedWrite(filePath) {
+    if (!existsSync(filePath))
+      return errorResult('error', `'${filePath}' does not exist after write`);
+
+    if (isTracked$2(filePath)) return okResult();
+
+    const result = git(['add', filePath], dirname(filePath));
+    if (result.exitCode === 0) return okResult('File added to git');
+    return errorResult('error', `Cannot add '${filePath}' to git: ${result.error || result.output}`);
+  }
+
+  deleteFile(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    if (isTracked$2(filePath)) {
+      const result = git(['rm', '--force', filePath], dirname(filePath));
+      if (result.exitCode === 0) return okResult();
+      return errorResult('error', `Cannot delete '${filePath}' from git: ${result.error || result.output}`);
+    }
+
+    try {
+      unlinkSync(filePath);
+      return okResult();
+    } catch (e) {
+      return errorResult('error', `Failed to delete file: ${e.message}`);
+    }
+  }
+
+  deleteFolder(folderPath) {
+    if (!existsSync(folderPath)) return okResult();
+
+    const listResult = git(['ls-files', folderPath], folderPath);
+    if (listResult.exitCode === 0 && listResult.output.length > 0) {
+      const rmResult = git(['rm', '-r', '--force', folderPath], folderPath);
+      if (rmResult.exitCode !== 0) {
+        return errorResult('error', `Cannot delete folder '${folderPath}' from git: ${rmResult.error || rmResult.output}`);
+      }
+    }
+
+    // Delete any remaining untracked files git rm left behind.
+    if (existsSync(folderPath)) {
+      try {
+        rmSync(folderPath, { recursive: true, force: true });
+      } catch (e) {
+        return errorResult('error', `Cannot delete folder '${folderPath}': ${e.message}`);
+      }
+    }
+
+    return okResult();
+  }
+}
+
+function isWritable(filePath) {
+  try {
+    accessSync(filePath, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function makeWritable(filePath) {
+  try {
+    const mode = statSync(filePath).mode;
+    chmodSync(filePath, mode | 0o200); // Adds owner-write bit.
+    return isWritable(filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Plain-filesystem provider: no VC system, just file-system operations.
+ * Used as the fallback when no VC is detected.
+ */
+class FilesystemProvider {
+  get name() { return 'filesystem'; }
+
+  prepareToWrite(filePath) {
+    if (!existsSync(filePath)) return okResult();
+    if (isWritable(filePath)) return okResult();
+    if (makeWritable(filePath)) return okResult('File made writable');
+    return errorResult('error', `Cannot make '${filePath}' writable`);
+  }
+
+  finishedWrite(filePath) {
+    if (!existsSync(filePath))
+      return errorResult('error', `'${filePath}' does not exist after write`);
+    return okResult();
+  }
+
+  deleteFile(filePath) {
+    if (!existsSync(filePath)) return okResult();
+    try {
+      unlinkSync(filePath);
+      return okResult();
+    } catch (e) {
+      return errorResult('error', `Cannot delete '${filePath}': ${e.message}`);
+    }
+  }
+
+  deleteFolder(folderPath) {
+    if (!existsSync(folderPath)) return okResult();
+    try {
+      rmSync(folderPath, { recursive: true, force: true });
+      return okResult();
+    } catch (e) {
+      return errorResult('error', `Cannot delete folder '${folderPath}': ${e.message}`);
+    }
+  }
+}
+
+const fs$2 = new FilesystemProvider();
+
+function p4(args) {
+  return runCommand('p4', args);
+}
+
+/**
+ * Returns p4 fstat info for a file, or null if the file is not in the depot.
+ */
+function fstat(filePath) {
+  const result = p4(['fstat', filePath]);
+  if (result.exitCode !== 0) return null;
+  return result.output;
+}
+
+function isInDepot(filePath) {
+  return fstat(filePath) !== null;
+}
+
+/**
+ * Perforce (Helix Core) provider.
+ *
+ * Uses the `p4` CLI. Assumes the workspace is already configured in the
+ * environment (P4PORT, P4USER, P4CLIENT, or via p4 config/tickets).
+ */
+class PerforceProvider {
+  get name() { return 'perforce'; }
+
+  prepareToWrite(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    if (!isInDepot(filePath)) {
+      return fs$2.prepareToWrite(filePath);
+    }
+
+    const result = p4(['edit', filePath]);
+    if (result.exitCode === 0) return okResult();
+
+    const combined = (result.output + ' ' + result.error).toLowerCase();
+    if (combined.includes('locked by')) {
+      return errorResult('locked', `'${filePath}' is locked by another user`);
+    }
+    if (combined.includes('out of date')) {
+      return errorResult('outOfDate', `'${filePath}' is out of date — sync before editing`);
+    }
+    return errorResult('error', `Cannot open '${filePath}' for editing: ${result.error || result.output}`);
+  }
+
+  finishedWrite(filePath) {
+    if (!existsSync(filePath))
+      return errorResult('error', `'${filePath}' does not exist after write`);
+
+    const info = fstat(filePath);
+    if (info !== null) return okResult();
+
+    const result = p4(['add', filePath]);
+    if (result.exitCode === 0) return okResult('File opened for add in Perforce');
+    return errorResult('error', `Cannot add '${filePath}' to Perforce: ${result.error || result.output}`);
+  }
+
+  deleteFile(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    if (isInDepot(filePath)) {
+      const result = p4(['delete', filePath]);
+      if (result.exitCode === 0) return okResult();
+      return errorResult('error', `Cannot delete '${filePath}' from Perforce: ${result.error || result.output}`);
+    }
+
+    try {
+      unlinkSync(filePath);
+      return okResult();
+    } catch (e) {
+      return errorResult('error', `Cannot delete '${filePath}': ${e.message}`);
+    }
+  }
+
+  deleteFolder(folderPath) {
+    if (!existsSync(folderPath)) return okResult();
+
+    // The /... wildcard schedules the entire depot subtree for deletion.
+    const depotPath = folderPath.replace(/\\/g, '/') + '/...';
+    const result = p4(['delete', depotPath]);
+
+    if (existsSync(folderPath)) {
+      try {
+        rmSync(folderPath, { recursive: true, force: true });
+      } catch (e) {
+        return errorResult('error', `Cannot delete folder '${folderPath}': ${e.message}`);
+      }
+    }
+
+    // p4 delete of untracked path exits non-zero, but we still succeeded locally.
+    if (result.exitCode !== 0 && result.error && !result.error.includes('no such file')) {
+      return errorResult('error', `Cannot delete folder '${folderPath}' from Perforce: ${result.error || result.output}`);
+    }
+
+    return okResult();
+  }
+}
+
+const fs$1 = new FilesystemProvider();
+
+function cm(args) {
+  return runCommand('cm', args);
+}
+
+/**
+ * Returns true if the file is tracked by Plastic SCM (Unity Version Control).
+ */
+function isTracked$1(filePath) {
+  const result = cm(['status', '--short', filePath]);
+  if (result.exitCode !== 0) return false;
+  // Untracked files are reported with a '?' prefix.
+  const lines = result.output.split('\n').filter(l => l.trim());
+  return lines.length > 0 && !lines[0].startsWith('?');
+}
+
+/**
+ * Plastic SCM / Unity Version Control provider.
+ *
+ * Uses the `cm` CLI (Plastic SCM command-line client).
+ * Files under Plastic SCM are read-only until checked out.
+ */
+class PlasticProvider {
+  get name() { return 'plastic'; }
+
+  prepareToWrite(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    if (!isTracked$1(filePath)) {
+      return fs$1.prepareToWrite(filePath);
+    }
+
+    const result = cm(['co', filePath]);
+    if (result.exitCode === 0) return okResult();
+
+    const combined = (result.output + ' ' + result.error).toLowerCase();
+    if (combined.includes('locked') || combined.includes('exclusive')) {
+      return errorResult('locked', `'${filePath}' is locked`);
+    }
+    if (combined.includes('out of date') || combined.includes('not latest')) {
+      return errorResult('outOfDate', `'${filePath}' is out of date — update before editing`);
+    }
+    return errorResult('error', `Cannot check out '${filePath}': ${result.error || result.output}`);
+  }
+
+  finishedWrite(filePath) {
+    if (!existsSync(filePath))
+      return errorResult('error', `'${filePath}' does not exist after write`);
+
+    if (isTracked$1(filePath)) return okResult();
+
+    const result = cm(['add', filePath]);
+    if (result.exitCode === 0) return okResult('File added to Plastic SCM');
+    return errorResult('error', `Cannot add '${filePath}' to Plastic SCM: ${result.error || result.output}`);
+  }
+
+  deleteFile(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    if (isTracked$1(filePath)) {
+      const result = cm(['remove', filePath]);
+      if (result.exitCode === 0) return okResult();
+      return errorResult('error', `Cannot delete '${filePath}' from Plastic SCM: ${result.error || result.output}`);
+    }
+
+    try {
+      unlinkSync(filePath);
+      return okResult();
+    } catch (e) {
+      return errorResult('error', `Cannot delete '${filePath}': ${e.message}`);
+    }
+  }
+
+  deleteFolder(folderPath) {
+    if (!existsSync(folderPath)) return okResult();
+
+    if (isTracked$1(folderPath)) {
+      // cm remove is recursive for directories.
+      const result = cm(['remove', folderPath]);
+      if (result.exitCode !== 0) {
+        return errorResult('error', `Cannot delete folder '${folderPath}' from Plastic SCM: ${result.error || result.output}`);
+      }
+    }
+
+    if (existsSync(folderPath)) {
+      try {
+        rmSync(folderPath, { recursive: true, force: true });
+      } catch (e) {
+        return errorResult('error', `Cannot delete folder '${folderPath}': ${e.message}`);
+      }
+    }
+
+    return okResult();
+  }
+}
+
+const fs = new FilesystemProvider();
+
+function svn(args) {
+  return runCommand('svn', args);
+}
+
+/**
+ * Returns true if the file is tracked by SVN.
+ */
+function isTracked(filePath) {
+  const result = svn(['info', filePath]);
+  return result.exitCode === 0;
+}
+
+/**
+ * Subversion (SVN) provider.
+ *
+ * SVN files are normally writable. The exception is files with the
+ * svn:needs-lock property, which are read-only until locked.
+ * prepareToWrite handles this by calling `svn lock`.
+ */
+class SvnProvider {
+  get name() { return 'svn'; }
+
+  prepareToWrite(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    const fsResult = fs.prepareToWrite(filePath);
+    if (fsResult.success) return okResult();
+
+    // File is read-only — only expected for files with svn:needs-lock set.
+    if (!isTracked(filePath)) {
+      return errorResult('error', `Cannot make '${filePath}' writable`);
+    }
+
+    const result = svn(['lock', filePath]);
+    if (result.exitCode === 0) return okResult('File locked in SVN');
+
+    const combined = (result.output + ' ' + result.error).toLowerCase();
+    if (combined.includes('locked by') || combined.includes('steal lock')) {
+      return errorResult('locked', `'${filePath}' is locked by another user`);
+    }
+    if (combined.includes('out of date')) {
+      return errorResult('outOfDate', `'${filePath}' is out of date — update before locking`);
+    }
+    return errorResult('error', `Cannot lock '${filePath}' in SVN: ${result.error || result.output}`);
+  }
+
+  finishedWrite(filePath) {
+    if (!existsSync(filePath))
+      return errorResult('error', `'${filePath}' does not exist after write`);
+
+    if (isTracked(filePath)) return okResult();
+
+    const result = svn(['add', filePath]);
+    if (result.exitCode === 0) return okResult('File added to SVN');
+    return errorResult('error', `Cannot add '${filePath}' to SVN: ${result.error || result.output}`);
+  }
+
+  deleteFile(filePath) {
+    if (!existsSync(filePath)) return okResult();
+
+    if (isTracked(filePath)) {
+      const result = svn(['delete', '--force', filePath]);
+      if (result.exitCode === 0) return okResult();
+      return errorResult('error', `Cannot delete '${filePath}' from SVN: ${result.error || result.output}`);
+    }
+
+    try {
+      unlinkSync(filePath);
+      return okResult();
+    } catch (e) {
+      return errorResult('error', `Failed to delete file: ${e.message}`);
+    }
+  }
+
+  deleteFolder(folderPath) {
+    if (!existsSync(folderPath)) return okResult();
+
+    if (isTracked(folderPath)) {
+      const result = svn(['delete', '--force', folderPath]);
+      if (result.exitCode !== 0) {
+        return errorResult('error', `Cannot delete folder '${folderPath}' from SVN: ${result.error || result.output}`);
+      }
+    } else {
+      try {
+        rmSync(folderPath, { recursive: true, force: true });
+      } catch (e) {
+        return errorResult('error', `Failed to delete folder: ${e.message}`);
+      }
+    }
+
+    return okResult();
+  }
+}
+
+const PROVIDER_MAP = {
+  git: () => new GitProvider(),
+  perforce: () => new PerforceProvider(),
+  plastic: () => new PlasticProvider(),
+  svn: () => new SvnProvider(),
+  filesystem: () => new FilesystemProvider(),
+};
+
+/** @type {object | null} An explicitly set provider that bypasses auto-detection. */
+let _overrideProvider = null;
+
+/**
+ * Override the provider used for all operations.
+ * Useful for testing or in environments where auto-detection is unreliable.
+ * Pass a provider instance, or null to clear the override.
+ *
+ * @param {object | null} provider
+ */
+function setProvider(provider) {
+  _overrideProvider = provider;
+}
+
+/** Clear any previously set provider override, restoring auto-detection. */
+function clearProvider() {
+  _overrideProvider = null;
+  clearDetectorCache();
+}
+
+function dirOf(p) {
+  const abs = resolve(p);
+  try {
+    return statSync(abs).isDirectory() ? abs : dirname(abs);
+  } catch {
+    return dirname(abs);
+  }
+}
+
+function resolveProvider(filePath) {
+  if (_overrideProvider) return _overrideProvider;
+
+  const dir = dirOf(filePath);
+  const config = loadConfig(dir);
+  if (config) {
+    const factory = PROVIDER_MAP[config.system];
+    if (factory) return factory();
+  }
+
+  const detected = detectProvider(resolve(filePath));
+  return (PROVIDER_MAP[detected] ?? PROVIDER_MAP.filesystem)();
+}
+
+/**
+ * Prepare a file path for writing.
+ * Checks out or unlocks the file in VC if it is read-only.
+ * No-op if the file does not yet exist.
+ *
+ * On failure, `status` may be 'locked', 'outOfDate', or 'error'.
+ *
+ * @param {string} filePath
+ */
+function prepareToWrite(filePath) {
+  return resolveProvider(filePath).prepareToWrite(filePath);
+}
+
+/**
+ * Notify the library that a file has been written.
+ * Adds the file to VC if it is not yet tracked. No-op for existing tracked files.
+ *
+ * @param {string} filePath
+ */
+function finishedWrite(filePath) {
+  return resolveProvider(filePath).finishedWrite(filePath);
+}
+
+/**
+ * Delete a file, marking it for deletion in VC if tracked.
+ *
+ * @param {string} filePath
+ */
+function deleteFile(filePath) {
+  return resolveProvider(filePath).deleteFile(filePath);
+}
+
+/**
+ * Delete a folder and all its contents, marking tracked files for deletion in VC.
+ *
+ * @param {string} folderPath
+ */
+function deleteFolder(folderPath) {
+  return resolveProvider(folderPath).deleteFolder(folderPath);
+}
+
+/**
+ * Write text to a file, handling VC checkout and registration automatically.
+ * Calls `prepareToWrite`, writes the file, then calls `finishedWrite`.
+ * Works whether or not the file already exists.
+ *
+ * On failure, returns the result from whichever step failed.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @param {BufferEncoding} [encoding='utf8']
+ */
+function writeTextFile(filePath, content, encoding = 'utf8') {
+  const prep = resolveProvider(filePath).prepareToWrite(filePath);
+  if (!prep.success) return prep;
+  try {
+    writeFileSync(filePath, content, { encoding });
+  } catch (e) {
+    return { success: false, status: 'error', message: e.message };
+  }
+  return resolveProvider(filePath).finishedWrite(filePath);
+}
+
+/**
+ * Write binary data to a file, handling VC checkout and registration automatically.
+ * Calls `prepareToWrite`, writes the file, then calls `finishedWrite`.
+ * Works whether or not the file already exists.
+ *
+ * On failure, returns the result from whichever step failed.
+ *
+ * @param {string} filePath
+ * @param {Buffer | Uint8Array} data
+ */
+function writeBinaryFile(filePath, data) {
+  const prep = resolveProvider(filePath).prepareToWrite(filePath);
+  if (!prep.success) return prep;
+  try {
+    writeFileSync(filePath, data);
+  } catch (e) {
+    return { success: false, status: 'error', message: e.message };
+  }
+  return resolveProvider(filePath).finishedWrite(filePath);
+}
+
+export { FilesystemProvider, GitProvider, PerforceProvider, PlasticProvider, SvnProvider, clearProvider, deleteFile, deleteFolder, finishedWrite, prepareToWrite, setProvider, writeBinaryFile, writeTextFile };
+//# sourceMappingURL=simpleVcLib.js.map