@thegitai/cli 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/src/api/chat.js

@@ -2,6 +2,7 @@ import { createPromptCheckpoint, sanitizeSessionSafetyForServer, } from '../sess
 import { applySessionSnapshot, snapshotFromSession, } from '../session-store.js';
 import { executeLocalToolCall } from '../tool-executor.js';
 import { createTraceContext, normalizeServerUrl, readErrorResponse, } from './http.js';
+import { collectClientEnvironment } from '../client-environment.js';
 export class TurnCancelledError extends Error {
     name = 'TurnCancelledError';
     constructor(message = 'Turn cancelled.') {
@@ -288,6 +289,7 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
         modelId: session.modelId,
         session: snapshotForServer(session),
         input,
+        clientEnvironment: collectClientEnvironment({ env: session.env }),
         imageAttachments,
         maxToolSteps: session.maxToolSteps,
         autoYes: session.autoYes,

package/dist/src/artifact-policy.js

@@ -37,6 +37,15 @@ export const BINARY_ARTIFACT_EXTENSIONS = createArtifactNameSet([
     '.bz2',
     '.7z',
     '.pdf',
+    '.doc',
+    '.docx',
+    '.docm',
+    '.dot',
+    '.dotx',
+    '.dotm',
+    '.xls',
+    '.xlsx',
+    '.xlsm',
     '.exe',
     '.dll',
     '.so',

package/dist/src/client-environment.js

@@ -0,0 +1,127 @@
+import { accessSync, constants, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const PACKAGE_MANAGER_CANDIDATES = [
+    'apt',
+    'apt-get',
+    'dnf',
+    'yum',
+    'pacman',
+    'zypper',
+    'apk',
+    'brew',
+    'nix',
+    'snap',
+    'flatpak',
+    'winget',
+    'choco',
+    'scoop',
+];
+function detectShell(platform, env) {
+    if (platform === 'win32') {
+        const comspec = env.COMSPEC;
+        return comspec ? path.win32.basename(comspec) : 'unknown';
+    }
+    const shell = env.SHELL;
+    return shell ? path.basename(shell) : 'unknown';
+}
+function unquoteOsReleaseValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 2)
+        return trimmed;
+    const quote = trimmed[0];
+    if ((quote !== '"' && quote !== "'") || trimmed.at(-1) !== quote) {
+        return trimmed;
+    }
+    return trimmed
+        .slice(1, -1)
+        .replace(/\\(["'`$\\])/g, '$1')
+        .trim();
+}
+export function parseLinuxOsRelease(text) {
+    const values = {};
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const index = trimmed.indexOf('=');
+        if (index <= 0)
+            continue;
+        const key = trimmed.slice(0, index);
+        const value = unquoteOsReleaseValue(trimmed.slice(index + 1));
+        values[key] = value;
+    }
+    return {
+        distroId: values.ID,
+        distroName: values.PRETTY_NAME ?? values.NAME,
+        distroVersion: values.VERSION_ID ?? values.VERSION,
+    };
+}
+function readLinuxOsReleaseText(options) {
+    if ('osReleaseText' in options) {
+        return options.osReleaseText ?? '';
+    }
+    try {
+        return readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function pathEnv(env) {
+    return env.PATH ?? env.Path ?? env.path ?? '';
+}
+function windowsExecutableNames(command, env) {
+    if (path.extname(command))
+        return [command];
+    const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map((extension) => extension.trim())
+        .filter(Boolean);
+    return [command, ...extensions.map((extension) => `${command}${extension}`)];
+}
+function defaultExecutableExists(command, env, platform) {
+    const searchPath = pathEnv(env);
+    if (!searchPath)
+        return false;
+    const names = platform === 'win32' ? windowsExecutableNames(command, env) : [command];
+    for (const dir of searchPath.split(path.delimiter)) {
+        if (!dir.trim())
+            continue;
+        for (const name of names) {
+            try {
+                accessSync(path.join(dir, name), constants.X_OK);
+                return true;
+            }
+            catch {
+                try {
+                    accessSync(path.join(dir, name));
+                    return platform === 'win32';
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+    return false;
+}
+function detectPackageManagers(env, platform, executableExists) {
+    return PACKAGE_MANAGER_CANDIDATES.filter((command) => executableExists(command, env, platform));
+}
+export function collectClientEnvironment(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const executableExists = options.executableExists ?? defaultExecutableExists;
+    const linuxDistro = platform === 'linux'
+        ? parseLinuxOsRelease(readLinuxOsReleaseText(options))
+        : {};
+    return {
+        platform,
+        arch: options.arch ?? process.arch,
+        release: options.release ?? os.release(),
+        shell: detectShell(platform, env),
+        ...linuxDistro,
+        packageManagers: detectPackageManagers(env, platform, executableExists),
+    };
+}

package/dist/src/edit-journal.js

@@ -1,33 +1,64 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { BINARY_ARTIFACT_EXTENSIONS } from './artifact-policy.js';
 import { resolveProjectPath } from './patcher.js';
 export const MAX_EDIT_JOURNAL_RECORDS = 50;
-const MAX_STORED_CONTENT_CHARS = 1_000_000;
-export function hashContent(content) {
+const MAX_STORED_CONTENT_CHARS = 8_000_000;
+export function hashBytes(content) {
     return `sha256:${createHash('sha256').update(content).digest('hex')}`;
 }
+export function hashContent(content) {
+    return hashBytes(Buffer.from(content, 'utf8'));
+}
+export function hashStoredContent(content, encoding = 'utf8') {
+    return encoding === 'base64'
+        ? hashBytes(Buffer.from(content, 'base64'))
+        : hashContent(content);
+}
+export function storedContentBuffer(content, encoding = 'utf8') {
+    return encoding === 'base64'
+        ? Buffer.from(content, 'base64')
+        : Buffer.from(content, 'utf8');
+}
+function snapshotEncoding(filePath, content) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (BINARY_ARTIFACT_EXTENSIONS.has(ext))
+        return 'base64';
+    if (content.includes(0))
+        return 'base64';
+    return 'utf8';
+}
 export function readFileEditSnapshot(rootDir, filePath) {
     try {
         const absPath = resolveProjectPath(rootDir, filePath);
         if (!existsSync(absPath)) {
-            return { exists: false, content: null, hash: null };
+            return { exists: false, content: null, contentEncoding: 'utf8', hash: null };
         }
         if (lstatSync(absPath).isSymbolicLink()) {
             return {
                 exists: true,
                 content: null,
+                contentEncoding: 'utf8',
                 hash: null,
                 error: `Refusing to snapshot symbolic link: ${filePath}`,
             };
         }
-        const content = readFileSync(absPath, 'utf-8');
-        return { exists: true, content, hash: hashContent(content) };
+        const content = readFileSync(absPath);
+        const encoding = snapshotEncoding(filePath, content);
+        return {
+            exists: true,
+            content: encoding === 'base64' ? content.toString('base64') : content.toString('utf8'),
+            contentEncoding: encoding,
+            hash: hashBytes(content),
+        };
     }
     catch (err) {
         return {
             exists: false,
             content: null,
+            contentEncoding: 'utf8',
             hash: null,
             error: err?.message ? String(err.message) : String(err),
         };
@@ -46,7 +77,8 @@ export function isEditToolName(toolName) {
     return (toolName === 'write_file' ||
         toolName === 'patch_file' ||
         toolName === 'str_replace' ||
-        toolName === 'delete_file');
+        toolName === 'delete_file' ||
+        toolName === 'replace_document_text');
 }
 export function operationFromSnapshots(before, after) {
     if (before.hash === after.hash)
@@ -102,6 +134,7 @@ export function normalizeAssistantEditJournal(value) {
                 ? entry.afterHash
                 : null,
             beforeContent: typeof entry.beforeContent === 'string' ? entry.beforeContent : null,
+            beforeContentEncoding: entry.beforeContentEncoding === 'base64' ? 'base64' : 'utf8',
             createdAt: typeof entry.createdAt === 'string' && entry.createdAt
                 ? entry.createdAt
                 : new Date().toISOString(),

package/dist/src/patcher.js

@@ -169,6 +169,23 @@ export function writeProjectFile(rootDir, filePath, content) {
     writeFileSync(absPath, content, 'utf-8');
     return { absPath, changed: true };
 }
+export function writeProjectFileBuffer(rootDir, filePath, content) {
+    const absPath = resolveProjectPath(rootDir, filePath);
+    if (existsSync(absPath)) {
+        try {
+            const existingContent = readFileSync(absPath);
+            if (existingContent.equals(content)) {
+                return { absPath, changed: false };
+            }
+        }
+        catch {
+            // If we can't read it for some reason, proceed with write
+        }
+    }
+    mkdirSync(path.dirname(absPath), { recursive: true });
+    writeFileSync(absPath, content);
+    return { absPath, changed: true };
+}
 export function deleteProjectFile(rootDir, filePath) {
     const absPath = resolveProjectPath(rootDir, filePath);
     if (!existsSync(absPath)) {

package/dist/src/scanner.js

@@ -16,13 +16,16 @@ const TARGET_CHUNK_CHARS = 1800;
 const MAX_CHUNK_CHARS = 2800;
 const FALLBACK_OVERLAP_LINES = 10;
 const MAX_STRUCTURE_DEPTH = 2;
+function parseGitLsFilesOutput(output) {
+    return String(output)
+        .split('\0')
+        .filter(Boolean)
+        .filter((filePath) => !shouldIgnorePath(filePath));
+}
 function getFiles(rootDir, { limit = Infinity } = {}) {
     try {
-        const output = execSync('git ls-files --cached --others --exclude-standard', { cwd: rootDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-        const files = output
-            .split('\n')
-            .filter(Boolean)
-            .filter((filePath) => !shouldIgnorePath(filePath));
+        const output = execSync('git ls-files -z --cached --others --exclude-standard', { cwd: rootDir, stdio: ['pipe', 'pipe', 'pipe'] });
+        const files = parseGitLsFilesOutput(output);
         return Number.isFinite(limit) ? files.slice(0, limit) : files;
     }
     catch {

package/dist/src/session-safety.js

@@ -2,14 +2,14 @@ import { execFileSync } from 'node:child_process';
 import { lstatSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { ARTIFACT_IGNORE_DIRS, normalizeProjectRelativePath, shouldIgnoreArtifactPath, } from './artifact-policy.js';
-import { hashContent, readFileEditSnapshot } from './edit-journal.js';
-import { deleteProjectFile, resolveProjectPath, writeProjectFile } from './patcher.js';
+import { hashBytes, readFileEditSnapshot, storedContentBuffer, } from './edit-journal.js';
+import { deleteProjectFile, resolveProjectPath, writeProjectFile, writeProjectFileBuffer, } from './patcher.js';
 import { removeIndexFile, upsertIndexFile } from './project-index.js';
 const MAX_CHECKPOINTS = 20;
 const MAX_SESSION_EDITS = 500;
 const MAX_READ_RECORDS = 200;
 const MAX_REDACTION_TOKENS = 500;
-const MAX_SNAPSHOT_CONTENT_CHARS = 1_000_000;
+const MAX_SNAPSHOT_CONTENT_CHARS = 8_000_000;
 const MAX_MUTATION_SCAN_FILES = 2000;
 const MAX_BASELINE_CONTENT_BYTES = 50 * 1024 * 1024;
 export function createSessionSafetyState() {
@@ -34,6 +34,14 @@ function normalizeEditOperation(value) {
         ? text
         : null;
 }
+function normalizeStoredContentEncoding(value) {
+    return value === 'base64' ? 'base64' : 'utf8';
+}
+function writeStoredProjectFile(rootDir, filePath, content, encoding) {
+    return encoding === 'base64'
+        ? writeProjectFileBuffer(rootDir, filePath, storedContentBuffer(content, encoding))
+        : writeProjectFile(rootDir, filePath, content);
+}
 export function normalizeSessionSafetyState(value) {
     const raw = value && typeof value === 'object' ? value : {};
     const safety = createSessionSafetyState();
@@ -57,6 +65,7 @@ export function normalizeSessionSafetyState(value) {
                         exists: file.exists === true,
                         hash: typeof file.hash === 'string' ? file.hash : null,
                         content: typeof file.content === 'string' ? file.content : null,
+                        contentEncoding: normalizeStoredContentEncoding(file.contentEncoding),
                         skipped: typeof file.skipped === 'string' && file.skipped.trim()
                             ? file.skipped.trim()
                             : undefined,
@@ -143,6 +152,7 @@ export function normalizeSessionSafetyState(value) {
                 beforeHash: typeof item.beforeHash === 'string' ? item.beforeHash : null,
                 afterHash: typeof item.afterHash === 'string' ? item.afterHash : null,
                 beforeContent: typeof item.beforeContent === 'string' ? item.beforeContent : null,
+                beforeContentEncoding: normalizeStoredContentEncoding(item.beforeContentEncoding),
                 createdAt: typeof item.createdAt === 'string' && item.createdAt
                     ? item.createdAt
                     : new Date().toISOString(),
@@ -242,7 +252,10 @@ export function mergeLocalSessionSafetyState(local, incoming) {
         for (const file of checkpoint.files) {
             if (file.content == null)
                 continue;
-            localCheckpointContent.set(`${checkpoint.id}\0${file.filePath}\0${file.hash ?? ''}`, file.content);
+            localCheckpointContent.set(`${checkpoint.id}\0${file.filePath}\0${file.hash ?? ''}`, {
+                content: file.content,
+                contentEncoding: file.contentEncoding,
+            });
         }
     }
     next.checkpoints = next.checkpoints.map((checkpoint) => ({
@@ -251,17 +264,35 @@ export function mergeLocalSessionSafetyState(local, incoming) {
             if (file.content != null)
                 return file;
             const content = localCheckpointContent.get(`${checkpoint.id}\0${file.filePath}\0${file.hash ?? ''}`);
-            return content == null ? file : { ...file, content };
+            return content == null
+                ? file
+                : {
+                    ...file,
+                    content: content.content,
+                    contentEncoding: content.contentEncoding,
+                };
         }),
     }));
     const localBeforeContent = new Map(localState.sessionEdits
         .filter((edit) => edit.beforeContent != null)
-        .map((edit) => [edit.id, edit.beforeContent]));
+        .map((edit) => [
+        edit.id,
+        {
+            beforeContent: edit.beforeContent,
+            beforeContentEncoding: edit.beforeContentEncoding,
+        },
+    ]));
     next.sessionEdits = next.sessionEdits.map((edit) => {
         if (edit.beforeContent != null)
             return edit;
         const beforeContent = localBeforeContent.get(edit.id);
-        return beforeContent == null ? edit : { ...edit, beforeContent };
+        return beforeContent == null
+            ? edit
+            : {
+                ...edit,
+                beforeContent: beforeContent.beforeContent,
+                beforeContentEncoding: beforeContent.beforeContentEncoding,
+            };
     });
     return next;
 }
@@ -279,6 +310,7 @@ function readCheckpointSnapshot(rootDir, filePath) {
             exists: false,
             hash: null,
             content: null,
+            contentEncoding: 'utf8',
             skipped: `Refusing to checkpoint ignored or out-of-project path: ${filePath}`,
         };
     }
@@ -289,6 +321,7 @@ function readCheckpointSnapshot(rootDir, filePath) {
             exists: snapshot.exists,
             hash: snapshot.hash,
             content: null,
+            contentEncoding: snapshot.contentEncoding,
             skipped: snapshot.error,
         };
     }
@@ -298,6 +331,7 @@ function readCheckpointSnapshot(rootDir, filePath) {
             exists: snapshot.exists,
             hash: snapshot.hash,
             content: null,
+            contentEncoding: snapshot.contentEncoding,
             skipped: `File is too large to checkpoint (${snapshot.content.length} chars).`,
         };
     }
@@ -306,6 +340,7 @@ function readCheckpointSnapshot(rootDir, filePath) {
         exists: snapshot.exists,
         hash: snapshot.hash,
         content: snapshot.content,
+        contentEncoding: snapshot.contentEncoding,
     };
 }
 export function createPromptCheckpoint(state, label, turnId) {
@@ -661,7 +696,7 @@ export async function restoreCheckpointFiles(args) {
         const before = readFileEditSnapshot(args.rootDir, snapshot.filePath);
         try {
             if (snapshot.exists) {
-                const result = writeProjectFile(args.rootDir, snapshot.filePath, snapshot.content ?? '');
+                const result = writeStoredProjectFile(args.rootDir, snapshot.filePath, snapshot.content ?? '', snapshot.contentEncoding);
                 if (result.changed)
                     changed = true;
                 if (syncPolicy)
@@ -693,7 +728,7 @@ export async function restoreCheckpointFiles(args) {
                         if (item.before.content == null) {
                             throw new Error('previous file content is unavailable');
                         }
-                        writeProjectFile(args.rootDir, item.snapshot.filePath, item.before.content);
+                        writeStoredProjectFile(args.rootDir, item.snapshot.filePath, item.before.content, item.before.contentEncoding);
                         if (syncPolicy) {
                             await upsertIndexFile(args.projectIndex, item.snapshot.filePath);
                         }
@@ -749,6 +784,7 @@ export async function restoreCheckpointFiles(args) {
             beforeHash: item.before.hash,
             afterHash: item.after.hash,
             beforeContent: item.before.content,
+            beforeContentEncoding: item.before.contentEncoding,
             checkpointId: checkpoint.id,
         });
         restored.push({
@@ -777,6 +813,18 @@ function git(args, cwd) {
         return null;
     }
 }
+function gitBuffer(args, cwd) {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10_000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
 export function findGitRoot(startDir) {
     const root = git(['rev-parse', '--show-toplevel'], startDir);
     return root ? path.resolve(root) : null;
@@ -897,14 +945,15 @@ function readGitHeadSnapshot(rootDir, filePath) {
         return null;
     const abs = resolveProjectPath(rootDir, filePath);
     const relToGit = path.relative(gitRoot, abs).split(path.sep).join('/');
-    const content = git(['show', `HEAD:${relToGit}`], gitRoot);
+    const content = gitBuffer(['show', `HEAD:${relToGit}`], gitRoot);
     if (content == null)
         return null;
     return {
         filePath,
         exists: true,
-        hash: hashContent(content),
-        content,
+        hash: hashBytes(content),
+        content: content.toString('base64'),
+        contentEncoding: 'base64',
     };
 }
 export function captureMutationBaseline(rootDir, options) {
@@ -932,6 +981,7 @@ export function captureMutationBaseline(rootDir, options) {
                 exists: true,
                 hash: null,
                 content: null,
+                contentEncoding: 'utf8',
                 skipped: `Pre-command snapshot skipped: project baseline content budget exceeded (${contentBudget} bytes). Restore for this file is not available.`,
             });
             continue;
@@ -978,6 +1028,7 @@ export function collectCommandMutations(args) {
                 exists: false,
                 hash: null,
                 content: null,
+                contentEncoding: 'utf8',
             };
         if (before.hash === after.hash && !before.skipped)
             continue;
@@ -1000,6 +1051,7 @@ export function collectCommandMutations(args) {
             beforeHash: before.hash,
             afterHash: after.hash,
             beforeContent: before.content,
+            beforeContentEncoding: before.contentEncoding,
             checkpointId: args.checkpointId,
         });
         records.push(record);

package/dist/src/tool-executor.js

@@ -32,6 +32,12 @@ export function formatToolCallForStatus(call) {
 }
 function getEditToolFilePath(call) {
     const args = call.args && typeof call.args === 'object' ? call.args : {};
+    if (call.name === 'replace_document_text') {
+        const outputPath = args.outputPath ?? args.output_path;
+        if (typeof outputPath === 'string' && outputPath.trim()) {
+            return outputPath.trim();
+        }
+    }
     for (const key of EDIT_FILE_PATH_ARG_ALIASES) {
         const value = args[key];
         if (typeof value === 'string' && value.trim())
@@ -79,6 +85,7 @@ function recordAssistantEdit(session, call, result, before) {
         beforeHash: before.hash,
         afterHash: after.hash,
         beforeContent: operation === 'create' ? null : before.content,
+        beforeContentEncoding: before.contentEncoding,
         createdAt: new Date().toISOString(),
         revertedAt: null,
         revertedByToolCallId: null,
@@ -98,6 +105,7 @@ function recordAssistantEdit(session, call, result, before) {
         beforeHash: before.hash,
         afterHash: after.hash,
         beforeContent: operation === 'create' ? null : before.content,
+        beforeContentEncoding: before.contentEncoding,
         checkpointId: checkpoint.id,
     });
     clearEditFailure(session.clientState.safety, filePath);

package/dist/src/tools/index.js

@@ -11,6 +11,7 @@ import { listSymbols } from './list-symbols.js';
 import { patchFile } from './patch-file.js';
 import { readDocument } from './read-document.js';
 import { readFile } from './read-file.js';
+import { replaceDocumentText } from './replace-document-text.js';
 import { runShellCommand } from './run-command.js';
 import { runNodeScript } from './run-node-script.js';
 import { restoreFilesToCheckpoint, restoreToCheckpoint, } from './restore-checkpoint.js';
@@ -25,6 +26,7 @@ export const TOOL_MAP = {
     list_directories: (context, args) => listDirectories(context, args),
     read_file: (context, args) => readFile(context, args),
     read_document: (context, args) => readDocument(context.rootDir, args, context.env),
+    replace_document_text: replaceDocumentText,
     grep_code: (context, args) => grepCode(context.rootDir, args),
     find_symbol: (context, args) => findSymbol(context, args),
     list_symbols: (context, args) => listSymbols(context, args),

package/dist/src/tools/patch-file.js

@@ -1,10 +1,12 @@
 import chalk from 'chalk';
+import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
 import { applyUnifiedPatch, readProjectFile, renderDiffPreview, writeProjectFile, } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { getCurrentFileHash, resolveRedactionTokens } from '../session-safety.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
+const DOCUMENT_EXTENSIONS = new Set(['.pdf', '.xlsx', '.docx']);
 export async function patchFile(context, args) {
     const { rootDir, projectIndex, autoYes, confirmPatch } = context;
     const filePath = String(args.filePath ?? '').trim();
@@ -15,6 +17,17 @@ export async function patchFile(context, args) {
     if (!patch.trim()) {
         return { ok: false, error: 'patch is required' };
     }
+    const ext = path.extname(filePath).toLowerCase();
+    if (DOCUMENT_EXTENSIONS.has(ext)) {
+        return {
+            ok: false,
+            filePath,
+            error: ext === '.docx'
+                ? 'Use replace_document_text for .docx files.'
+                : `Use read_document for ${ext} files; patching is not supported.`,
+            failureCategory: 'invalid_argument',
+        };
+    }
     let originalContent;
     try {
         originalContent = readProjectFile(rootDir, filePath);

package/dist/src/tools/path-suggest.js

@@ -0,0 +1,66 @@
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { isSensitiveProjectPath } from '../artifact-policy.js';
+// "File not found" recovery hint: when a model mistypes a filename (most
+// often Unicode punctuation — a straight ' for a curly ’ — or a small typo),
+// suggest the closest real file from the same directory.
+function foldName(name) {
+    return name
+        .normalize('NFC')
+        .replace(/[‘’ʼ]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/ /g, ' ')
+        .toLowerCase();
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i++) {
+        const current = [i, ...new Array(cols - 1).fill(0)];
+        for (let j = 1; j < cols; j++) {
+            current[j] = Math.min(prev[j] + 1, current[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = current;
+    }
+    return prev[cols - 1];
+}
+export function suggestClosestPath(rootDir, missingPath) {
+    const resolved = path.isAbsolute(missingPath)
+        ? missingPath
+        : path.resolve(rootDir, missingPath);
+    const directory = path.dirname(resolved);
+    const wantedBase = foldName(path.basename(resolved));
+    if (!wantedBase)
+        return null;
+    let candidates;
+    try {
+        candidates = readdirSync(directory);
+    }
+    catch {
+        return null;
+    }
+    const threshold = Math.max(2, Math.floor(wantedBase.length * 0.25));
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        // Never suggest a file the caller would refuse to read/write directly:
+        // probing a near-miss like `.enx` or `credential.docx` must not leak the
+        // existence of `.env`/credentials through the recovery hint.
+        const candidateRelative = path.relative(rootDir, path.join(directory, candidate));
+        if (isSensitiveProjectPath(candidateRelative))
+            continue;
+        const distance = levenshtein(wantedBase, foldName(candidate));
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    if (!best || bestDistance > threshold)
+        return null;
+    const suggested = path.join(directory, best);
+    const relative = path.relative(rootDir, suggested);
+    return relative && !relative.startsWith('..') ? relative : suggested;
+}

package/dist/src/tools/read-document.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { isSensitiveProjectPath, normalizeProjectRelativePath, } from '../artifact-policy.js';
+import { suggestClosestPath } from './path-suggest.js';
 import { readCliAuthConfig } from '../api/auth.js';
 export function normalizeDocumentText(raw) {
     const text = String(raw ?? '').replace(/\r\n?/g, '\n');
@@ -36,6 +37,7 @@ export function normalizeDocumentText(raw) {
 }
 async function parseDocumentOnServer(config, fileName, fileData, ext, args) {
     const includePageArgs = ext === '.pdf';
+    const includeParagraphArgs = ext === '.docx';
     const response = await globalThis.fetch(`${config.serverUrl.replace(/\/+$/, '')}/v1/document/parse`, {
         method: 'POST',
         headers: {
@@ -51,6 +53,12 @@ async function parseDocumentOnServer(config, fileName, fileData, ext, args) {
             ...(includePageArgs && args.lastPage !== undefined
                 ? { lastPage: args.lastPage }
                 : {}),
+            ...(includeParagraphArgs && args.firstParagraph !== undefined
+                ? { firstParagraph: args.firstParagraph }
+                : {}),
+            ...(includeParagraphArgs && args.lastParagraph !== undefined
+                ? { lastParagraph: args.lastParagraph }
+                : {}),
         }),
     });
     const data = await response.json().catch(() => null);
@@ -76,17 +84,20 @@ export async function readDocument(rootDir, args, env) {
         };
     }
     if (!existsSync(resolvedPath)) {
+        const suggestion = suggestClosestPath(rootDir, resolvedPath);
         return {
             ok: false,
-            error: `File not found: ${resolvedPath}`,
+            error: suggestion
+                ? `File not found: ${resolvedPath}. Did you mean "${suggestion}"? Note the exact punctuation (e.g. curly apostrophe ’ vs straight ').`
+                : `File not found: ${resolvedPath}`,
             failureCategory: 'not_found',
         };
     }
     const ext = path.extname(resolvedPath).toLowerCase();
-    if (ext !== '.pdf' && ext !== '.xlsx') {
+    if (ext !== '.pdf' && ext !== '.xlsx' && ext !== '.docx') {
         return {
             ok: false,
-            error: `Unsupported file type: "${ext}". read_document only supports .pdf and .xlsx.`,
+            error: `Unsupported file type: "${ext}". read_document only supports .pdf, .xlsx, and .docx.`,
         };
     }
     const authConfig = readCliAuthConfig(env);

package/dist/src/tools/read-file.js

@@ -6,6 +6,7 @@ import { readProjectFile } from '../patcher.js';
 import { dotenvFitsRedactionBudget, getCurrentFileHash, recordReadCoverage, redactContentWithStableTokens, redactDotenvWithStableTokens, } from '../session-safety.js';
 import { readFileRange, truncate } from '../utils.js';
 const MAX_FILE_READ_CHARS = 12000;
+const DOCUMENT_EXTENSIONS = new Set(['.pdf', '.xlsx', '.docx']);
 export async function readFile(context, args) {
     const rootDir = typeof context === 'string' ? context : context.rootDir;
     const safety = typeof context === 'string' ? undefined : context.safety;
@@ -26,6 +27,14 @@ export async function readFile(context, args) {
             error: 'This path is not permitted.',
         };
     }
+    const documentExt = path.extname(projectPath ?? filePath).toLowerCase();
+    if (DOCUMENT_EXTENSIONS.has(documentExt)) {
+        return {
+            ok: false,
+            error: `Use read_document for ${documentExt} files.`,
+            failureCategory: 'invalid_argument',
+        };
+    }
     let content;
     if (projectPath) {
         try {

package/dist/src/tools/replace-document-text.js

@@ -0,0 +1,242 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { isSensitiveProjectPath, normalizeProjectRelativePath, } from '../artifact-policy.js';
+import { readCliAuthConfig } from '../api/auth.js';
+import { resolveProjectPath, writeProjectFileBuffer } from '../patcher.js';
+import { suggestClosestPath } from './path-suggest.js';
+import { isTuiMode } from '../runtime-mode.js';
+function normalizeReplacements(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => {
+        if (!item || typeof item !== 'object')
+            return null;
+        const entry = item;
+        const oldText = String(entry.oldText ?? entry.old_text ?? '');
+        const newText = String(entry.newText ?? entry.new_text ?? '');
+        if (!oldText)
+            return null;
+        return { oldText, newText };
+    })
+        .filter(Boolean);
+}
+function relativeEditablePath(rootDir, rawPath) {
+    const resolvedPath = path.isAbsolute(rawPath)
+        ? rawPath
+        : path.resolve(rootDir, rawPath);
+    const projectPath = normalizeProjectRelativePath(rootDir, resolvedPath);
+    if (!projectPath || isSensitiveProjectPath(projectPath))
+        return null;
+    return projectPath.split(path.sep).join('/');
+}
+function renderPreview(filePath, preview) {
+    if (isTuiMode())
+        return;
+    console.log(chalk.bold(`\n  Document text replacement preview for ${filePath}:`));
+    for (const line of preview.split('\n')) {
+        if (line.startsWith('+')) {
+            console.log(chalk.green(line));
+        }
+        else if (line.startsWith('-')) {
+            console.log(chalk.red(line));
+        }
+        else if (line.startsWith('@@')) {
+            console.log(chalk.cyan(line));
+        }
+        else {
+            console.log(chalk.dim(line));
+        }
+    }
+    console.log();
+}
+async function replaceDocumentTextOnServer(config, fileName, fileData, replacements, replaceAll, validate) {
+    const response = await globalThis.fetch(`${config.serverUrl.replace(/\/+$/, '')}/v1/document/replace-text`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            fileName,
+            fileData: fileData.toString('base64'),
+            replacements,
+            replaceAll,
+            validate,
+        }),
+    });
+    const data = await response.json().catch(() => null);
+    if (!response.ok) {
+        return {
+            ok: false,
+            error: `Server document edit failed: ${data?.error?.message ?? response.status}`,
+        };
+    }
+    return data;
+}
+export async function replaceDocumentText(context, args) {
+    const sourceRaw = String(args.filePath ?? args.file_path ?? '').trim();
+    if (!sourceRaw) {
+        return { ok: false, error: 'filePath is required' };
+    }
+    const sourcePath = relativeEditablePath(context.rootDir, sourceRaw);
+    if (!sourcePath) {
+        return {
+            ok: false,
+            error: 'replace_document_text can only edit permitted files inside the project root.',
+            failureCategory: 'permission_denied',
+        };
+    }
+    if (path.extname(sourcePath).toLowerCase() !== '.docx') {
+        return {
+            ok: false,
+            error: 'replace_document_text only supports .docx files.',
+            failureCategory: 'invalid_argument',
+        };
+    }
+    const outputRaw = String(args.outputPath ?? args.output_path ?? '').trim();
+    const targetPath = outputRaw
+        ? relativeEditablePath(context.rootDir, outputRaw)
+        : sourcePath;
+    if (!targetPath) {
+        return {
+            ok: false,
+            error: 'outputPath must be inside the project root.',
+            failureCategory: 'permission_denied',
+        };
+    }
+    if (path.extname(targetPath).toLowerCase() !== '.docx') {
+        return {
+            ok: false,
+            error: 'outputPath must end with .docx.',
+            failureCategory: 'invalid_argument',
+        };
+    }
+    const replacements = normalizeReplacements(args.replacements);
+    if (!replacements.length) {
+        return {
+            ok: false,
+            error: 'replacements must include at least one { oldText, newText } item.',
+            failureCategory: 'missing_required_argument',
+        };
+    }
+    const authConfig = readCliAuthConfig(context.env);
+    if (!authConfig) {
+        return {
+            ok: false,
+            error: 'Document editing requires a server connection. Please log in first.',
+        };
+    }
+    const sourceAbsPath = resolveProjectPath(context.rootDir, sourcePath);
+    if (!existsSync(sourceAbsPath)) {
+        const suggestion = suggestClosestPath(context.rootDir, sourceAbsPath);
+        return {
+            ok: false,
+            filePath: sourcePath,
+            error: suggestion
+                ? `File does not exist: ${sourcePath}. Did you mean "${suggestion}"? Note the exact punctuation (e.g. curly apostrophe ’ vs straight ').`
+                : `File does not exist: ${sourcePath}`,
+            failureCategory: 'not_found',
+        };
+    }
+    const validateOnly = args.validate === true || args.dryRun === true;
+    const serverResult = await replaceDocumentTextOnServer(authConfig, path.basename(sourcePath), readFileSync(sourceAbsPath), replacements, args.replaceAll === true || args.replace_all === true, validateOnly);
+    if (!serverResult.ok) {
+        return {
+            ...serverResult,
+            filePath: sourcePath,
+            failureCategory: serverResult.failureCategory ?? 'external_service',
+        };
+    }
+    // Validate-only: report per-replacement match info without touching the file.
+    // changed:false marks it non-mutating so the agent loop does not count a
+    // dry-run as an applied edit.
+    if (validateOnly) {
+        return {
+            ok: true,
+            validate: true,
+            changed: false,
+            filePath: sourcePath,
+            operation: 'replace_document_text',
+            results: serverResult.results,
+        };
+    }
+    // No replacement matched: nothing was written. Surface per-item reasons so
+    // the model can correct and resend only the failing entries.
+    const replacementCount = Number(serverResult.replacementCount ?? 0);
+    if (replacementCount === 0) {
+        const failures = Array.isArray(serverResult.replacements)
+            ? serverResult.replacements
+                .filter((item) => item && item.ok === false)
+                .map((item) => `- ${item.error ?? 'no match'}`)
+            : [];
+        return {
+            ok: false,
+            filePath: sourcePath,
+            operation: 'replace_document_text',
+            failureCategory: 'conflict',
+            error: `0 of ${serverResult.requestedCount ?? replacements.length} replacements applied; file unchanged.` +
+                (failures.length ? `\n${failures.join('\n')}` : ''),
+            replacements: serverResult.replacements,
+        };
+    }
+    const preview = String(serverResult.preview ?? '');
+    renderPreview(targetPath, preview);
+    if (!context.autoYes && context.confirmPatch) {
+        const confirmed = await context.confirmPatch(targetPath, preview);
+        if (!confirmed) {
+            if (!isTuiMode()) {
+                console.log(chalk.dim(`  replace_document_text skipped: ${targetPath}`));
+            }
+            return {
+                ok: false,
+                skipped: true,
+                filePath: targetPath,
+                error: 'User declined replace_document_text',
+            };
+        }
+    }
+    const fileData = String(serverResult.fileData ?? '');
+    const nextData = Buffer.from(fileData, 'base64');
+    const write = writeProjectFileBuffer(context.rootDir, targetPath, nextData);
+    const failedCount = Number(serverResult.failedCount ?? 0);
+    const appliedCount = Number(serverResult.appliedCount ?? replacementCount);
+    const requestedCount = Number(serverResult.requestedCount ?? replacements.length);
+    const partialFailures = Array.isArray(serverResult.replacements)
+        ? serverResult.replacements
+            .filter((item) => item && item.ok === false)
+            .map((item) => `- ${item.error ?? 'no match'}`)
+        : [];
+    return {
+        ok: true,
+        filePath: targetPath,
+        sourceFilePath: sourcePath,
+        changed: write.changed,
+        operation: 'replace_document_text',
+        replacementCount: serverResult.replacementCount,
+        requestedCount: serverResult.requestedCount,
+        appliedCount: serverResult.appliedCount,
+        failedCount: serverResult.failedCount,
+        replacements: serverResult.replacements,
+        bytesWritten: nextData.length,
+        // A partial batch still wrote the matched entries (changed:true above), but
+        // the loop must reflect and repair the missed entries — needsRepair forces
+        // that without losing credit for the applied edits.
+        ...(failedCount > 0
+            ? {
+                needsRepair: true,
+                failureCategory: 'conflict',
+                error: `${appliedCount} of ${requestedCount} replacements applied; ` +
+                    `${failedCount} missed and still need to be fixed:\n` +
+                    partialFailures.join('\n'),
+                failureDetails: {
+                    category: 'conflict',
+                    tool: 'replace_document_text',
+                    action: 'Re-issue replace_document_text for the missed entries only, with corrected oldText. ' +
+                        'Copy the exact text from read_document (mind curly vs straight quotes), or pass validate:true to test a match first.',
+                },
+            }
+            : {}),
+    };
+}

package/dist/src/tools/str-replace.js

@@ -1,10 +1,12 @@
 import chalk from 'chalk';
+import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
 import { readProjectFile, writeProjectFile } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { getCurrentFileHash, resolveRedactionTokens } from '../session-safety.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
+const DOCUMENT_EXTENSIONS = new Set(['.pdf', '.xlsx', '.docx']);
 function countOccurrences(haystack, needle) {
     if (needle.length === 0)
         return 0;
@@ -92,6 +94,17 @@ export async function strReplace(context, args) {
     if (oldString.length === 0) {
         return { ok: false, error: 'old_string is required and must be non-empty' };
     }
+    const ext = path.extname(filePath).toLowerCase();
+    if (DOCUMENT_EXTENSIONS.has(ext)) {
+        return {
+            ok: false,
+            filePath,
+            error: ext === '.docx'
+                ? 'Use replace_document_text for .docx files.'
+                : `Use read_document for ${ext} files; text replacement is not supported.`,
+            failureCategory: 'invalid_argument',
+        };
+    }
     let originalContent;
     try {
         originalContent = readProjectFile(rootDir, filePath);

package/dist/src/tools/undo-edit.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
-import { hashContent, readFileEditSnapshot, } from '../edit-journal.js';
-import { deleteProjectFile, writeProjectFile, } from '../patcher.js';
+import { hashStoredContent, readFileEditSnapshot, storedContentBuffer, } from '../edit-journal.js';
+import { deleteProjectFile, writeProjectFile, writeProjectFileBuffer, } from '../patcher.js';
 import { removeIndexFile, upsertIndexFile, } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
@@ -84,7 +84,7 @@ function validateUndoPlan(rootDir, records) {
                     currentHash,
                 };
             }
-            const beforeContentHash = hashContent(record.beforeContent);
+            const beforeContentHash = hashStoredContent(record.beforeContent, record.beforeContentEncoding);
             if (beforeContentHash !== record.beforeHash) {
                 return {
                     ok: false,
@@ -110,7 +110,9 @@ async function applyUndo(context, record) {
     if (record.beforeContent === null) {
         throw new Error(`Cannot undo ${record.id}: the stored pre-edit snapshot is incomplete.`);
     }
-    const { changed } = writeProjectFile(rootDir, record.filePath, record.beforeContent);
+    const { changed } = record.beforeContentEncoding === 'base64'
+        ? writeProjectFileBuffer(rootDir, record.filePath, storedContentBuffer(record.beforeContent, record.beforeContentEncoding))
+        : writeProjectFile(rootDir, record.filePath, record.beforeContent);
     if (changed) {
         await upsertIndexFile(projectIndex, record.filePath);
     }

package/dist/src/tools/write-file.js

@@ -1,10 +1,12 @@
 import chalk from 'chalk';
+import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
 import { writeProjectFile } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { getCurrentFileHash, hasFreshFullReadCoverage, resolveRedactionTokens, } from '../session-safety.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
+const DOCUMENT_EXTENSIONS = new Set(['.pdf', '.xlsx', '.docx']);
 export async function writeFile(context, args) {
     const { rootDir, projectIndex } = context;
     const filePath = String(args.filePath ?? '').trim();
@@ -12,6 +14,17 @@ export async function writeFile(context, args) {
     if (!filePath) {
         return { ok: false, error: 'filePath is required' };
     }
+    const ext = path.extname(filePath).toLowerCase();
+    if (DOCUMENT_EXTENSIONS.has(ext)) {
+        return {
+            ok: false,
+            filePath,
+            error: ext === '.docx'
+                ? 'Use replace_document_text for .docx files.'
+                : `Use read_document for ${ext} files; write_file is not supported.`,
+            failureCategory: 'invalid_argument',
+        };
+    }
     const coveragePath = normalizeProjectRelativePath(rootDir, filePath) ?? filePath;
     const currentHash = getCurrentFileHash(rootDir, filePath);
     if (currentHash !== null &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thegitai/cli",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "description": "TheGitAI CLI client (source-visible, proprietary)",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://thegit.ai",
@@ -27,10 +27,10 @@
     "web-tree-sitter": "^0.26.6"
   },
   "optionalDependencies": {
-    "@thegitai/tui-darwin-arm64": "1.0.0-beta.6",
-    "@thegitai/tui-darwin-x64": "1.0.0-beta.6",
-    "@thegitai/tui-linux-x64": "1.0.0-beta.6",
-    "@thegitai/tui-win32-x64": "1.0.0-beta.6"
+    "@thegitai/tui-darwin-arm64": "1.0.0-beta.8",
+    "@thegitai/tui-darwin-x64": "1.0.0-beta.8",
+    "@thegitai/tui-linux-x64": "1.0.0-beta.8",
+    "@thegitai/tui-win32-x64": "1.0.0-beta.8"
   },
   "publishConfig": {
     "access": "public"