isomorphic-jj 1.4.3 → 1.8.0

package/src/drivers/built-in-drivers.js

@@ -8,10 +8,10 @@
  * Deep merge for JSON objects
  * Recursively merges objects, with theirs taking precedence on conflicts
  *
- * @param {Object} base - Base object
- * @param {Object} ours - Our changes
- * @param {Object} theirs - Their changes
- * @returns {Object} Merged object
+ * @param {any} base - Base object
+ * @param {any} ours - Our changes
+ * @param {any} theirs - Their changes
+ * @returns {Record<string, any>|null} Merged object
  */
 function deepMergeJSON(base, ours, theirs) {
   // If all are identical, return any
@@ -30,7 +30,12 @@ function deepMergeJSON(base, ours, theirs) {
   }
 
   // Both sides changed - need smart merge
-  if (typeof ours !== 'object' || typeof theirs !== 'object' || Array.isArray(ours) || Array.isArray(theirs)) {
+  if (
+    typeof ours !== 'object' ||
+    typeof theirs !== 'object' ||
+    Array.isArray(ours) ||
+    Array.isArray(theirs)
+  ) {
     // Primitives or arrays - conflict
     return null;
   }
@@ -61,7 +66,12 @@ function deepMergeJSON(base, ours, theirs) {
       result[key] = oursVal;
     } else {
       // Both changed differently
-      if (typeof oursVal === 'object' && typeof theirsVal === 'object' && !Array.isArray(oursVal) && !Array.isArray(theirsVal)) {
+      if (
+        typeof oursVal === 'object' &&
+        typeof theirsVal === 'object' &&
+        !Array.isArray(oursVal) &&
+        !Array.isArray(theirsVal)
+      ) {
         // Recurse for nested objects
         const merged = deepMergeJSON(baseVal || {}, oursVal, theirsVal);
         if (merged === null) {
@@ -83,8 +93,10 @@ function deepMergeJSON(base, ours, theirs) {
  *
  * Attempts to merge JSON files intelligently by merging objects.
  * Falls back to conflict markers if merge isn't possible.
+ *
+ * @param {{ path?: string, content: { base?: string, ours?: string, theirs?: string } }} args
  */
-export async function jsonDriver({ path, content }) {
+export async function jsonDriver({ content }) {
   const { base, ours, theirs } = content;
 
   try {
@@ -106,10 +118,12 @@ export async function jsonDriver({ path, content }) {
       return {
         content: conflictContent,
         hasConflict: true,
-        conflicts: [{
-          type: 'json-merge-conflict',
-          message: 'Both sides modified the same field with different values',
-        }],
+        conflicts: [
+          {
+            type: 'json-merge-conflict',
+            message: 'Both sides modified the same field with different values',
+          },
+        ],
       };
     }
   } catch (error) {
@@ -118,10 +132,12 @@ export async function jsonDriver({ path, content }) {
     return {
       content: conflictContent,
       hasConflict: true,
-      conflicts: [{
-        type: 'json-parse-error',
-        message: `JSON parsing failed: ${error.message}`,
-      }],
+      conflicts: [
+        {
+          type: 'json-parse-error',
+          message: `JSON parsing failed: ${error.message}`,
+        },
+      ],
     };
   }
 }
@@ -133,8 +149,10 @@ export async function jsonDriver({ path, content }) {
  * - Union merge for dependencies/devDependencies
  * - Take theirs for version (semver conflicts are hard)
  * - Merge other fields intelligently
+ *
+ * @param {{ path?: string, content: { base?: string, ours?: string, theirs?: string } }} args
  */
-export async function packageJsonDriver({ path, content }) {
+export async function packageJsonDriver({ content }) {
   const { base, ours, theirs } = content;
 
   try {
@@ -147,12 +165,17 @@ export async function packageJsonDriver({ path, content }) {
 
     // Merge top-level fields
     for (const key of Object.keys({ ...oursObj, ...theirsObj })) {
-      if (key === 'dependencies' || key === 'devDependencies' || key === 'peerDependencies' || key === 'optionalDependencies') {
+      if (
+        key === 'dependencies' ||
+        key === 'devDependencies' ||
+        key === 'peerDependencies' ||
+        key === 'optionalDependencies'
+      ) {
         // Union merge dependencies
         merged[key] = {
           ...baseObj[key],
           ...oursObj[key],
-          ...theirsObj[key],  // theirs wins on conflicts
+          ...theirsObj[key], // theirs wins on conflicts
         };
       } else if (key === 'version') {
         // Version conflicts are tricky - take theirs
@@ -162,7 +185,7 @@ export async function packageJsonDriver({ path, content }) {
         merged[key] = {
           ...baseObj[key],
           ...oursObj[key],
-          ...theirsObj[key],  // theirs wins
+          ...theirsObj[key], // theirs wins
         };
       } else {
         // Other fields - use standard logic
@@ -198,10 +221,12 @@ export async function packageJsonDriver({ path, content }) {
     return {
       content: conflictContent,
       hasConflict: true,
-      conflicts: [{
-        type: 'parse-error',
-        message: `package.json parsing failed: ${error.message}`,
-      }],
+      conflicts: [
+        {
+          type: 'parse-error',
+          message: `package.json parsing failed: ${error.message}`,
+        },
+      ],
     };
   }
 }
@@ -211,8 +236,10 @@ export async function packageJsonDriver({ path, content }) {
  *
  * Note: This is a simple implementation. For production use, consider
  * using a proper YAML library like 'js-yaml'.
+ *
+ * @param {{ path?: string, content: { base?: string, ours?: string, theirs?: string } }} args
  */
-export async function yamlDriver({ path, content }) {
+export async function yamlDriver({ content }) {
   const { base, ours, theirs } = content;
 
   // Simple YAML merge - just do text-based for now
@@ -235,10 +262,12 @@ export async function yamlDriver({ path, content }) {
   return {
     content: conflictContent,
     hasConflict: true,
-    conflicts: [{
-      type: 'yaml-conflict',
-      message: 'YAML files modified on both sides',
-    }],
+    conflicts: [
+      {
+        type: 'yaml-conflict',
+        message: 'YAML files modified on both sides',
+      },
+    ],
   };
 }
 
@@ -247,8 +276,10 @@ export async function yamlDriver({ path, content }) {
  *
  * Attempts to merge markdown files by sections (headers).
  * Falls back to conflict markers for complex cases.
+ *
+ * @param {{ path?: string, content: { base?: string, ours?: string, theirs?: string } }} args
  */
-export async function markdownDriver({ path, content }) {
+export async function markdownDriver({ content }) {
   const { base, ours, theirs } = content;
 
   // Simple markdown merge - just text-based for now
@@ -272,10 +303,12 @@ export async function markdownDriver({ path, content }) {
   return {
     content: conflictContent,
     hasConflict: true,
-    conflicts: [{
-      type: 'markdown-conflict',
-      message: 'Markdown files modified on both sides',
-    }],
+    conflicts: [
+      {
+        type: 'markdown-conflict',
+        message: 'Markdown files modified on both sides',
+      },
+    ],
   };
 }
 

package/src/types.d.ts

@@ -294,6 +294,12 @@ export interface CreateJJOptions {
   backend?: string | any;
   /** Event hooks */
   hooks?: Hooks;
+  /**
+   * Automatically snapshot the working directory (disk-walk) before
+   * read/commit operations so out-of-band file changes are picked up.
+   * Defaults to `true`; set `false` to only track files written via jj.write().
+   */
+  autoSnapshot?: boolean;
 }
 
 /**
@@ -1042,6 +1048,13 @@ export interface JJ {
   edit(args: EditArgs): Promise<void>;
   status(): Promise<Status>;
   stats(): Promise<RepositoryStats>;
+  /**
+   * Snapshot the working directory (disk-walk), reconciling tracked file state
+   * and the working-copy change's content with what exists on disk (v1.6).
+   * Runs automatically before status/describe/diff/read/file.* unless the repo
+   * was created with `{ autoSnapshot: false }`.
+   */
+  snapshot(): Promise<{ added: string[]; modified: string[]; deleted: string[] }>;
 
   // History editing
   squash(args: SquashArgs): Promise<void>;
@@ -1051,6 +1064,39 @@ export interface JJ {
   unabandon(args: UnabandonArgs): Promise<void>;
   absorb(args?: AbsorbArgs): Promise<AbsorbResult>;
 
+  /**
+   * Create a change that reverses another change (matches `jj revert`, v1.5).
+   * Canonical replacement for the deprecated `backout()`.
+   */
+  revert(args: { revision?: ChangeID; change?: ChangeID; changeId?: ChangeID; target?: ChangeID; message?: string }): Promise<{
+    changeId: ChangeID;
+    description: string;
+    revertedFrom: ChangeID;
+    backedOut: ChangeID;
+    fileSnapshot: Record<string, string>;
+  }>;
+
+  /** @deprecated Use {@link JJ.revert}. Retained for backward compatibility. */
+  backout(args: { revision?: ChangeID; change?: ChangeID; changeId?: ChangeID; target?: ChangeID; message?: string }): Promise<{
+    changeId: ChangeID;
+    description: string;
+    backedOut: ChangeID;
+    fileSnapshot: Record<string, string>;
+  }>;
+
+  /** Sign a change, recording signature metadata (matches `jj sign`, v1.5). */
+  sign(args?: { revision?: ChangeID; change?: ChangeID; changeId?: ChangeID; backend?: string; key?: string }): Promise<{
+    changeId: ChangeID;
+    signed: true;
+    signature: { status: string; backend: string; key: string | null; timestamp: string };
+  }>;
+
+  /** Remove signature metadata from a change (matches `jj unsign`, v1.5). */
+  unsign(args?: { revision?: ChangeID; change?: ChangeID; changeId?: ChangeID }): Promise<{
+    changeId: ChangeID;
+    signed: false;
+  }>;
+
   // Queries
   log(opts?: LogOptions & { count?: false }): Promise<LogEntry[]>;
   log(opts: LogOptions & { count: true }): Promise<number>;
@@ -1059,6 +1105,11 @@ export interface JJ {
 
   // Operations
   undo(opts?: UndoOptions): Promise<UndoResult>;
+  /** Re-apply an operation previously reverted by {@link JJ.undo} (matches `jj redo`, v1.5). */
+  redo(): Promise<{
+    redoneOperation: { description: string; undoneOpId: OperationID };
+    restoredState: { workingCopy: ChangeID; heads: ChangeID[]; fileCount: number };
+  }>;
   operations: {
     list(opts?: { limit?: number }): Promise<Operation[]>;
     at(args: { operation: OperationID }): Promise<JJ>;
@@ -1116,6 +1167,8 @@ export interface JJ {
     set(args: BookmarkSetArgs): Promise<{ name: string; changeId: ChangeID }>;
     create(args: BookmarkCreateArgs): Promise<{ name: string; changeId: ChangeID }>;
     move(args: BookmarkMoveArgs): Promise<{ name: string; from: ChangeID; to: ChangeID }>;
+    /** Move a bookmark forward only; rejects non-descendant targets (matches `jj bookmark advance`, v1.5). */
+    advance(args: { name: string; to?: ChangeID; target?: ChangeID; changeId?: ChangeID; change?: ChangeID; revision?: ChangeID }): Promise<{ name: string; from: ChangeID; to: ChangeID }>;
     delete(args: BookmarkDeleteArgs): Promise<{ deleted: string }>;
     rename(args: BookmarkRenameArgs): Promise<{ oldName: string; newName: string; changeId: ChangeID }>;
     track(args: BookmarkTrackArgs): Promise<{ name: string; remote: string; tracking: boolean }>;
@@ -1152,6 +1205,8 @@ export interface JJ {
   file: {
     show(args: ReadArgs): Promise<string | Uint8Array>;
     list(args?: ListFilesArgs): Promise<string[]>;
+    /** Search tracked file contents (matches `jj file search`, v1.5). Regex by default. */
+    search(args: { pattern: string; changeId?: ChangeID; change?: ChangeID; kind?: 'regex' | 'substring'; path?: string }): Promise<Array<{ path: string; lineNumber: number; line: string }>>;
     write(args: WriteArgs): Promise<WriteResult>;
     move(args: MoveFileArgs): Promise<MoveResult>;
     remove(args: RemoveArgs): Promise<RemoveResult>;
@@ -1270,6 +1325,15 @@ export interface JJ {
     reset(): Promise<void>;
     clear(): Promise<void>;
   };
+
+  // Tags (immutable references; `set` is the v1.5 upsert)
+  tag: {
+    create(args: { name: string; changeId?: ChangeID }): Promise<{ name: string; changeId: ChangeID }>;
+    /** Create or move a tag (matches `jj tag set`, v1.5). */
+    set(args: { name: string; changeId?: ChangeID; change?: ChangeID; revision?: ChangeID }): Promise<{ name: string; changeId: ChangeID; updated: boolean }>;
+    list(args?: { pattern?: string }): Promise<Array<{ name: string; changeId: ChangeID }>>;
+    delete(args: { name: string }): Promise<{ deleted: string }>;
+  };
 }
 
 // ============================================================================
@@ -1290,6 +1354,8 @@ export function createJJ(options: CreateJJOptions): Promise<JJ>;
 export class JJError extends Error {
   code: string;
   suggestion?: string;
+  context: Record<string, any>;
+  details: Record<string, any>;
 
-  constructor(code: string, message: string, details?: { suggestion?: string });
+  constructor(code: string, message: string, context?: { suggestion?: string } & Record<string, any>);
 }

package/src/utils/atomic-write.js

@@ -0,0 +1,44 @@
+/**
+ * Shared atomic-write helper for filesystem writes.
+ *
+ * Writes content to a uniquely-named temp file, then renames it over the
+ * canonical path. A crash/error between those two steps leaves the
+ * canonical file untouched (never a truncated/partial write) — the temp
+ * file is best-effort cleaned up on failure.
+ *
+ * This mirrors the pattern `Storage.write()` (src/core/storage-manager.js)
+ * already uses for JSON stores, factored out so the protobuf-backed stores
+ * (JJOperationStore, JJViewStore, JJTreeState) can use it too instead of
+ * calling `writeFile()` directly on the canonical path — see issue #16.
+ */
+
+/**
+ * @param {any} fs - Filesystem implementation (Node fs, LightningFS, etc.)
+ * @param {string} targetPath - Canonical path to write to
+ * @param {string|Uint8Array} content - Content to write
+ */
+export async function atomicWriteFile(fs, targetPath, content) {
+  const tmpSuffix =
+    typeof crypto !== 'undefined' && crypto.randomUUID
+      ? crypto.randomUUID()
+      : `${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
+  const tmpPath = `${targetPath}.tmp.${Date.now()}.${tmpSuffix}`;
+
+  try {
+    const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+    if (dirPath) {
+      await fs.promises.mkdir(dirPath, { recursive: true });
+    }
+
+    await fs.promises.writeFile(tmpPath, content);
+    await fs.promises.rename(tmpPath, targetPath);
+  } catch (error) {
+    try {
+      await fs.promises.unlink(tmpPath);
+    } catch {
+      // Best-effort cleanup; ignore if the temp file was never created (or
+      // is already gone).
+    }
+    throw error;
+  }
+}

package/src/utils/errors.js

@@ -1,14 +1,14 @@
 /**
  * JJError - Custom error class for isomorphic-jj
- * 
+ *
  * Provides structured errors with error codes, context, and user-actionable suggestions.
  */
 export class JJError extends Error {
   /**
    * @param {string} code - Error code (e.g., 'CHANGE_NOT_FOUND')
    * @param {string} message - Human-readable error message
-   * @param {Object} [context={}] - Additional error context
-   * @param {string} [context.suggestion] - User-actionable suggestion
+   * @param {Object.<string, any>} [context] - Additional error context. May
+   *   include a `suggestion` string plus any other diagnostic fields.
    */
   constructor(code, message, context = {}) {
     super(message);

package/src/utils/id-generation.js

@@ -1,15 +1,15 @@
 /**
  * ID Generation utilities for isomorphic-jj
- * 
+ *
  * Generates stable change IDs and operation IDs using cryptographically secure random values.
  */
 
 /**
  * Generate a stable change ID
- * 
+ *
  * Uses 128-bit cryptographically random value encoded as 32-character hex string.
  * Collision probability is negligible (2^128 space).
- * 
+ *
  * @returns {string} 32-character lowercase hex string
  */
 export function generateChangeId() {
@@ -22,7 +22,7 @@ export function generateChangeId() {
  *
  * Uses SHA-256 hash of operation content for integrity verification.
  *
- * @param {Object} operation - Operation data
+ * @param {Object.<string, any>} operation - Operation data
  * @returns {Promise<string>} 64-character lowercase hex string (SHA-256)
  */
 export async function generateOperationId(operation) {

package/src/utils/mutex.js

@@ -0,0 +1,63 @@
+/**
+ * Small in-process locking utilities.
+ *
+ * These provide same-process concurrency safety only — they do not protect
+ * against races between separate OS processes sharing the same on-disk
+ * repository. Cross-process locking is a separate concern (e.g. a lockfile
+ * with retry/backoff) and is intentionally out of scope here.
+ */
+
+/**
+ * A simple FIFO async mutex: `run(fn)` queues `fn` to execute only once all
+ * previously-queued work on this mutex has settled, serializing access to
+ * whatever critical section `fn` represents.
+ */
+export class Mutex {
+  constructor() {
+    /** @type {Promise<any>} */
+    this._queue = Promise.resolve();
+  }
+
+  /**
+   * @template T
+   * @param {() => Promise<T>} fn
+   * @returns {Promise<T>}
+   */
+  run(fn) {
+    const result = this._queue.then(() => fn());
+    // Keep the queue moving even if `fn` rejects — a failed critical section
+    // must not permanently wedge the lock for subsequent callers.
+    this._queue = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}
+
+/**
+ * A registry of mutexes keyed by an arbitrary string (typically a file path),
+ * so unrelated paths don't contend with each other while operations on the
+ * *same* path are fully serialized.
+ */
+export class KeyedMutex {
+  constructor() {
+    /** @type {Map<string, Mutex>} */
+    this._mutexes = new Map();
+  }
+
+  /**
+   * @template T
+   * @param {string} key
+   * @param {() => Promise<T>} fn
+   * @returns {Promise<T>}
+   */
+  run(key, fn) {
+    let mutex = this._mutexes.get(key);
+    if (!mutex) {
+      mutex = new Mutex();
+      this._mutexes.set(key, mutex);
+    }
+    return mutex.run(fn);
+  }
+}

package/src/utils/validation.js

@@ -1,6 +1,6 @@
 /**
  * Validation utilities for isomorphic-jj
- * 
+ *
  * Provides validation functions for change IDs, paths, bookmark names, etc.
  */
 
@@ -8,7 +8,7 @@ import { JJError } from './errors.js';
 
 /**
  * Validate a change ID
- * 
+ *
  * @param {string} changeId - Change ID to validate
  * @throws {JJError} If change ID is invalid
  */
@@ -84,7 +84,7 @@ export function validatePath(path) {
 
 /**
  * Validate a bookmark name (follows Git ref name rules)
- * 
+ *
  * @param {string} name - Bookmark name to validate
  * @throws {JJError} If bookmark name is invalid
  */
@@ -115,13 +115,9 @@ export function validateBookmarkName(name) {
   }
 
   if (name.startsWith('.') || name.endsWith('.')) {
-    throw new JJError(
-      'INVALID_BOOKMARK_NAME',
-      'Bookmark name cannot start or end with "."',
-      {
-        name,
-      }
-    );
+    throw new JJError('INVALID_BOOKMARK_NAME', 'Bookmark name cannot start or end with "."', {
+      name,
+    });
   }
 
   if (name.endsWith('.lock')) {