pagan-artifact 0.3.2 → 0.3.3

package/setup/index.js

@@ -1,6 +1,8 @@
 /**
- * art - Modern version control.
- * Module: Setup (v0.3.2)
+ * Artifact - Modern version control.
+ * @author Benny Schmidt (https://github.com/bennyschmidt)
+ * @project https://github.com/bennyschmidt/artifact
+ * Module: Setup (v0.3.3)
  */
 
 const fs = require('fs');
@@ -8,15 +10,20 @@ const path = require('path');
 
 const pkg = require('../package.json');
 const shouldIgnore = require('../utils/shouldIgnore');
+const { MAX_PART_CHARS } = require('../utils/constants');
 
 const ARTIFACT_HOST = pkg.artConfig.host || 'http://localhost:1337';
-const MAX_PART_CHARS = 32000000;
 
 /**
  * Internal helper to create the .art directory tree.
+ * @param {string} artDirectory - The path to the .art folder.
  */
 
-function ensureDirStructure(artDirectory) {
+function ensureDirStructure (artDirectory) {
+  /**
+   * Define the core folder hierarchy required for local and remote tracking.
+   */
+
   const folders = [
     '',
     'root',
@@ -38,9 +45,15 @@ function ensureDirStructure(artDirectory) {
 
 /**
  * Initializes the local .art directory structure and indexes current files.
+ * @param {string} directoryPath - The root directory to initialize.
+ * @returns {string} Success message.
  */
 
 function init (directoryPath = process.cwd()) {
+  /**
+   * Check for an existing repository to prevent accidental overwrites.
+   */
+
   const artDirectory = path.join(directoryPath, '.art');
 
   if (fs.existsSync(artDirectory)) {
@@ -49,11 +62,15 @@ function init (directoryPath = process.cwd()) {
 
   ensureDirStructure(artDirectory);
 
+  /**
+   * Filter the working directory to find unignored files that are not internal.
+   */
+
   const files = fs.readdirSync(directoryPath, { recursive: true })
-    .filter(f => {
-      const isInternal = f === '.art' || f.startsWith('.art' + path.sep);
+    .filter(file => {
+      const isInternal = file === '.art' || file.startsWith('.art' + path.sep);
 
-      return !isInternal && !shouldIgnore(f);
+      return !isInternal && !shouldIgnore(file);
     });
 
   const rootMasterManifest = { parts: [] };
@@ -61,8 +78,14 @@ function init (directoryPath = process.cwd()) {
   let currentPartFiles = [];
   let currentPartChars = 0;
 
+  /**
+   * Internal helper to save indexed file snapshots into manifest parts.
+   */
+
   const saveManifestPart = () => {
-    if (currentPartFiles.length === 0) return;
+    if (currentPartFiles.length === 0) {
+      return;
+    }
 
     const partIndex = rootMasterManifest.parts.length;
     const partName = `manifest.part.${partIndex}.json`;
@@ -78,6 +101,10 @@ function init (directoryPath = process.cwd()) {
     currentPartChars = 0;
   };
 
+  /**
+   * Iterate through files and group their content into the root manifest.
+   */
+
   for (const file of files) {
     const fullPath = path.join(directoryPath, file);
 
@@ -99,6 +126,10 @@ function init (directoryPath = process.cwd()) {
 
   saveManifestPart();
 
+  /**
+   * Initialize manifest files for root and default branch histories.
+   */
+
   fs.writeFileSync(
     path.join(artDirectory, 'root/manifest.json'),
     JSON.stringify(rootMasterManifest, null, 2)
@@ -114,6 +145,10 @@ function init (directoryPath = process.cwd()) {
     JSON.stringify({ commits: [] }, null, 2)
   );
 
+  /**
+   * Create the primary art.json state file with default pointers.
+   */
+
   const artFile = {
     active: { branch: 'main', parent: null },
     remote: '',
@@ -130,11 +165,18 @@ function init (directoryPath = process.cwd()) {
 
 /**
  * Clone a repository and replay history.
+ * @param {string} repoSlug - The handle/repo identifier.
+ * @param {string} providedToken - Optional access token.
+ * @returns {Promise<string>} Success message.
  */
 
 async function clone (repoSlug, providedToken = null) {
+  /**
+   * Validate slug format and check destination availability.
+   */
+
   if (!repoSlug || !repoSlug.includes('/')) {
-    throw new Error('A valid slug is required (e.g., handle/repo).');
+    throw new Error('A valid slug is required (handle/repo).');
   }
 
   const [handle, repo] = repoSlug.split('/');
@@ -145,6 +187,10 @@ async function clone (repoSlug, providedToken = null) {
     throw new Error(`Destination path "${targetPath}" already exists.`);
   }
 
+  /**
+   * Prepare target directory and enter the workspace.
+   */
+
   fs.mkdirSync(targetPath, { recursive: true });
 
   const artPath = path.join(targetPath, '.art');
@@ -153,44 +199,77 @@ async function clone (repoSlug, providedToken = null) {
   process.chdir(targetPath);
 
   try {
+    /**
+     * Set up local art.json with remote tracking info.
+     */
+
     const artJsonPath = path.join(artPath, 'art.json');
 
     const artJson = {
       active: { branch: 'main', parent: null },
       remote: `${ARTIFACT_HOST}/${handle}/${repo}`,
-      configuration: { handle: '', personalAccessToken: providedToken || '' }
+      configuration: {
+        handle: '',
+        personalAccessToken: providedToken || ''
+      }
     };
 
     fs.writeFileSync(artJsonPath, JSON.stringify(artJson, null, 2));
 
     const token = artJson.configuration.personalAccessToken;
 
-    const rootRes = await fetch(`${ARTIFACT_HOST}/manifest`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        type: 'root',
-        handle,
-        repo,
-        branch: 'main',
-        ...(token && { personalAccessToken: token })
-      })
-    });
+    /**
+     * Fetch the root manifest to reconstruct the project's base state.
+     */
+
+    const rootRes = await fetch(
+      `${ARTIFACT_HOST}/manifest`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          type: 'root',
+          handle,
+          repo,
+          branch: 'main',
+
+          ...(token && { personalAccessToken: token })
+        })
+      }
+    );
 
     const masterManifest = await rootRes.json();
 
-    fs.writeFileSync(path.join(artPath, 'root/manifest.json'), JSON.stringify(masterManifest, null, 2));
+    fs.writeFileSync(
+      path.join(artPath, 'root/manifest.json'),
+      JSON.stringify(masterManifest, null, 2)
+    );
+
+    /**
+     * Download root parts and write files to the working directory.
+     */
 
     for (const partName of masterManifest.parts) {
-      const partRes = await fetch(`${ARTIFACT_HOST}/part`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ handle, repo, partName, ...(token && { personalAccessToken: token }) })
-      });
+      const partRes = await fetch(
+        `${ARTIFACT_HOST}/part`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            handle,
+            repo,
+            partName,
+            ...(token && { personalAccessToken: token })
+          })
+        }
+      );
 
       const partData = await partRes.json();
 
-      fs.writeFileSync(path.join(artPath, 'root', partName), JSON.stringify(partData, null, 2));
+      fs.writeFileSync(
+        path.join(artPath, 'root', partName),
+        JSON.stringify(partData, null, 2)
+      );
 
       for (const file of partData.files) {
         const workingPath = path.join(targetPath, file.path);
@@ -200,44 +279,79 @@ async function clone (repoSlug, providedToken = null) {
       }
     }
 
-    const historyRes = await fetch(`${ARTIFACT_HOST}/manifest`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ type: 'history', handle, repo, branch: 'main', ...(token && { personalAccessToken: token }) })
-    });
-
-    const historyManifest = await historyRes.json();
-    const localHistoryDir = path.join(artPath, 'history/local/main');
-    const remoteHistoryDir = path.join(artPath, 'history/remote/main');
+    /**
+     * Retrieve the full history manifest for the main branch.
+     */
 
-    for (const commitHash of historyManifest.commits) {
-      const commitRes = await fetch(`${ARTIFACT_HOST}/commit`, {
+    const historyRes = await fetch(
+      `${ARTIFACT_HOST}/manifest`,
+      {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
+          type: 'history',
           handle,
           repo,
           branch: 'main',
-          hash: commitHash,
+          ...(token && { personalAccessToken: token })
+        })
+      }
+    );
+
+    const historyManifest = await historyRes.json();
+    const localHistoryDir = path.join(artPath, 'history/local/main');
+    const remoteHistoryDir = path.join(artPath, 'history/remote/main');
+
+    /**
+     * Replay every commit in chronological order to sync local state with
+     * remote history.
+     */
 
-          ...(token && { personalAccessToken: token
+    for (const commitHash of historyManifest.commits) {
+      const commitRes = await fetch(
+        `${ARTIFACT_HOST}/commit`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            handle,
+            repo,
+            branch: 'main',
+            hash: commitHash,
+            ...(token && { personalAccessToken: token })
           })
-        })
-      });
+        }
+      );
 
       const commitMaster = await commitRes.json();
 
       let fullChanges = {};
 
+      /**
+       * Fetch and merge paginated changes if the commit is split into parts.
+       */
+
       if (commitMaster.parts && commitMaster.parts.length > 0) {
         for (const partName of commitMaster.parts) {
-          const partRes = await fetch(`${ARTIFACT_HOST}/commit/part`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ handle, repo, branch: 'main', partName, ...(token && { personalAccessToken: token }) })
-          });
+          const partRes = await fetch(
+            `${ARTIFACT_HOST}/part`,
+            {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                type: 'history',
+                handle,
+                repo,
+                branch: 'main',
+                partName,
+                
+                ...(token && { personalAccessToken: token })
+              })
+            }
+          );
 
           const partData = await partRes.json();
+
           fs.writeFileSync(path.join(localHistoryDir, partName), JSON.stringify(partData, null, 2));
           fs.writeFileSync(path.join(remoteHistoryDir, partName), JSON.stringify(partData, null, 2));
 
@@ -252,18 +366,24 @@ async function clone (repoSlug, providedToken = null) {
       fs.writeFileSync(path.join(localHistoryDir, `${commitHash}.json`), masterContent);
       fs.writeFileSync(path.join(remoteHistoryDir, `${commitHash}.json`), masterContent);
 
+      /**
+       * Apply individual file operations (insert, delete, create) to the working tree.
+       */
+
       for (const [filePath, changeSet] of Object.entries(fullChanges)) {
         const fullPath = path.join(targetPath, filePath);
 
         if (Array.isArray(changeSet)) {
           let content = fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : '';
-          for (const op of changeSet) {
-            if (op.type === 'insert') {
-              content = content.slice(0, op.position) + op.content + content.slice(op.position);
-            } else if (op.type === 'delete') {
-              content = content.slice(0, op.position) + content.slice(op.position + op.length);
+
+          for (const operation of changeSet) {
+            if (operation.type === 'insert') {
+              content = content.slice(0, operation.position) + operation.content + content.slice(operation.position);
+            } else if (operation.type === 'delete') {
+              content = content.slice(0, operation.position) + content.slice(operation.position + operation.length);
             }
           }
+
           fs.writeFileSync(fullPath, content);
         } else if (changeSet.type === 'createFile') {
           fs.mkdirSync(path.dirname(fullPath), { recursive: true });
@@ -274,6 +394,10 @@ async function clone (repoSlug, providedToken = null) {
       }
     }
 
+    /**
+     * Finalize the manifests and set the active parent pointer to the latest commit.
+     */
+
     const manifestJson = JSON.stringify({ commits: historyManifest.commits }, null, 2);
 
     fs.writeFileSync(path.join(localHistoryDir, 'manifest.json'), manifestJson);
@@ -294,18 +418,29 @@ async function clone (repoSlug, providedToken = null) {
 
 /**
  * Updates the configuration in art.json.
+ * @param {string} key - Configuration key.
+ * @param {any} value - Configuration value.
+ * @returns {Object} Updated configuration object.
  */
-function config(key, value) {
+
+function config (key, value) {
+  /**
+   * Verify repo existence and update specific configuration fields.
+   */
+
   const manifestPath = path.join(process.cwd(), '.art', 'art.json');
 
   if (!fs.existsSync(manifestPath)) {
     throw new Error('No art repository found.');
   }
 
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const manifest = JSON.parse(
+    fs.readFileSync(manifestPath, 'utf8')
+  );
 
   if (key && value !== undefined) {
     manifest.configuration[key] = value;
+
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
   }
 

package/utils/constants.js

@@ -0,0 +1,15 @@
+/**
+ * Console colors.
+ * ANSI colors for both dark and light theme terminals.
+ */
+
+export const RED = '\x1b[31m';
+export const GREEN = '\x1b[32m';
+export const RESET = '\x1b[0m';
+export const GRAY = '\x1b[90m';
+
+/**
+ * Artifact configuration
+ */
+
+export const MAX_PART_SIZE = 32000000;

package/utils/getStateByHash/index.js

@@ -1,87 +1,144 @@
 /**
- * art - Modern version control.
- * Module: Utils (v0.3.2)
+ * Artifact - Modern version control.
+ * @author Benny Schmidt (https://github.com/bennyschmidt)
+ * @project https://github.com/bennyschmidt/artifact
+ * Module: Utils / getStateByHash (v0.3.3)
  */
 
 const fs = require('fs');
 const path = require('path');
 
 /**
- * Helper to reconstruct file states at a specific commit hash.
+ * Reconstructs the full file state of a branch at a specific point in time by replaying commits.
+ * @param {string} branchName - The branch to read history from.
+ * @param {string} targetHash - The commit hash representing the desired state.
+ * @returns {Object} A map of file paths to their full string content.
  */
 
- module.exports = (branchName, targetHash) => {
-   const artPath = path.join(process.cwd(), '.art');
-   const rootPath = path.join(artPath, 'root/manifest.json');
-
-   if (!fs.existsSync(rootPath)) return {};
-
-   const rootMaster = JSON.parse(fs.readFileSync(rootPath, 'utf8'));
-   const branchPath = path.join(artPath, 'history/local', branchName);
-   const manifestPath = path.join(branchPath, 'manifest.json');
-
-   if (!fs.existsSync(manifestPath)) return {};
-
-   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-
-   let state = {};
-
-   for (const partName of rootMaster.parts) {
-     const partPath = path.join(artPath, 'root', partName);
-     const partData = JSON.parse(fs.readFileSync(partPath, 'utf8'));
-
-     for (const file of partData.files) {
-       state[file.path] = file.content;
-     }
-   }
-
-   if (!targetHash) return state;
-
-   for (const hash of manifest.commits) {
-     const commitPath = path.join(branchPath, `${hash}.json`);
-
-     if (!fs.existsSync(commitPath)) continue;
-
-     const commitMaster = JSON.parse(fs.readFileSync(commitPath, 'utf8'));
-
-     let fullChanges = {};
-
-     if (commitMaster.parts && Array.isArray(commitMaster.parts)) {
-       for (const partName of commitMaster.parts) {
-         const partPath = path.join(branchPath, partName);
-         if (fs.existsSync(partPath)) {
-           const partData = JSON.parse(fs.readFileSync(partPath, 'utf8'));
-           Object.assign(fullChanges, partData.changes);
-         }
-       }
-     } else if (commitMaster.changes) {
-       fullChanges = commitMaster.changes;
-     }
-
-     for (const [filePath, changeSet] of Object.entries(fullChanges)) {
-       if (Array.isArray(changeSet)) {
-         let currentContent = state[filePath] || '';
-
-         for (const operation of changeSet) {
-           if (operation.type === 'insert') {
-             currentContent = `${currentContent.slice(0, operation.position)}${operation.content}${currentContent.slice(operation.position)}`;
-           } else if (operation.type === 'delete') {
-             currentContent = `${currentContent.slice(0, operation.position)}${currentContent.slice(operation.position + operation.length)}`;
-           }
-         }
-
-         state[filePath] = currentContent;
-       } else {
-         if (changeSet.type === 'createFile') {
-           state[filePath] = changeSet.content;
-         } else if (changeSet.type === 'deleteFile') {
-           delete state[filePath];
-         }
-       }
-     }
-
-     if (hash === targetHash) break;
-   }
-
-   return state;
- };
+function getStateByHash (branchName, targetHash) {
+  /**
+   * Initialize repository paths and verify the existence of the root manifest.
+   */
+
+  const artifactPath = path.join(process.cwd(), '.art');
+  const rootPath = path.join(artifactPath, 'root/manifest.json');
+
+  if (!fs.existsSync(rootPath)) {
+    return {};
+  }
+
+  /**
+   * Load the initial "root" state which serves as the base
+   * for all subsequent deltas.
+   */
+
+  const rootMaster = JSON.parse(
+    fs.readFileSync(rootPath, 'utf8')
+  );
+  const branchPath = path.join(artifactPath, 'history/local', branchName);
+  const manifestPath = path.join(branchPath, 'manifest.json');
+
+  if (!fs.existsSync(manifestPath)) {
+    return {};
+  }
+
+  const manifest = JSON.parse(
+    fs.readFileSync(manifestPath, 'utf8')
+  );
+
+  let state = {};
+
+  /**
+   * Populate the state object with the original snapshots
+   * from the assembled root manifest parts.
+   */
+
+  for (const partName of rootMaster.parts) {
+    const partPath = path.join(artifactPath, 'root', partName);
+    const partData = JSON.parse(
+      fs.readFileSync(partPath, 'utf8')
+    );
+
+    for (const file of partData.files) {
+      state[file.path] = file.content;
+    }
+  }
+
+  if (!targetHash) {
+    return state;
+  }
+
+  /**
+   * Replay the history of the branch chronologically,
+   * applying changes until the target hash is reached.
+   */
+
+  for (const hash of manifest.commits) {
+    const commitPath = path.join(branchPath, `${hash}.json`);
+
+    if (!fs.existsSync(commitPath)) {
+      continue;
+    }
+
+    const commitMaster = JSON.parse(
+      fs.readFileSync(commitPath, 'utf8')
+    );
+
+    let fullChanges = {};
+
+    /**
+     * Consolidate changes from commit parts or the master commit file.
+     */
+
+    if (commitMaster.parts && Array.isArray(commitMaster.parts)) {
+      for (const partName of commitMaster.parts) {
+        const partPath = path.join(branchPath, partName);
+
+        if (fs.existsSync(partPath)) {
+          const partData = JSON.parse(
+            fs.readFileSync(partPath, 'utf8')
+          );
+
+          Object.assign(fullChanges, partData.changes);
+        }
+      }
+    } else if (commitMaster.changes) {
+      fullChanges = commitMaster.changes;
+    }
+
+    /**
+     * Apply line-based operations (insert/delete)
+     * or file-level operations to the current state.
+     */
+
+    for (const [filePath, changeSet] of Object.entries(fullChanges)) {
+      if (Array.isArray(changeSet)) {
+        let currentContent = state[filePath] || '';
+
+        for (const operation of changeSet) {
+          if (operation.type === 'insert') {
+            currentContent = `${currentContent.slice(0, operation.position)}${operation.content}${currentContent.slice(operation.position)}`;
+          } else if (operation.type === 'delete') {
+            currentContent = `${currentContent.slice(0, operation.position)}${currentContent.slice(operation.position + operation.length)}`;
+          }
+        }
+
+        state[filePath] = currentContent;
+      } else {
+        if (changeSet.type === 'createFile') {
+          state[filePath] = changeSet.content;
+        } else if (changeSet.type === 'deleteFile') {
+          delete state[filePath];
+        }
+      }
+    }
+
+    if (hash === targetHash) {
+      break;
+    }
+  }
+
+  return state;
+}
+
+module.exports = getStateByHash;