@chrysb/alphaclaw 0.3.5-beta.1 → 0.4.1-beta.0

package/lib/server/google-state.js

@@ -0,0 +1,317 @@
+const crypto = require("crypto");
+
+const kGoogleStateVersion = 2;
+const kDefaultGoogleClient = "default";
+const kDefaultGoogleScopes = [
+  "gmail:read",
+  "calendar:read",
+  "calendar:write",
+  "drive:read",
+  "sheets:read",
+  "docs:read",
+];
+
+const createEmptyGoogleState = () => ({
+  version: kGoogleStateVersion,
+  accounts: [],
+  gmailPush: {
+    token: "",
+    topics: {},
+  },
+});
+
+const createGoogleAccountId = () => crypto.randomBytes(4).toString("hex");
+
+const normalizeScopes = (services) => {
+  if (!Array.isArray(services)) return [...kDefaultGoogleScopes];
+  const deduped = Array.from(
+    new Set(
+      services
+        .map((scope) => String(scope || "").trim())
+        .filter(Boolean),
+    ),
+  );
+  return deduped.length ? deduped : [...kDefaultGoogleScopes];
+};
+
+const normalizePositiveInt = (value, fallbackValue = null) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return fallbackValue;
+};
+
+const normalizeTimestamp = (value) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return null;
+};
+
+const normalizeGmailWatch = (gmailWatch = {}) => {
+  const enabled = Boolean(gmailWatch?.enabled);
+  return {
+    enabled,
+    port: enabled ? normalizePositiveInt(gmailWatch?.port) : null,
+    expiration: normalizeTimestamp(gmailWatch?.expiration),
+    lastPushAt: normalizeTimestamp(gmailWatch?.lastPushAt),
+    pid: enabled ? normalizePositiveInt(gmailWatch?.pid) : null,
+  };
+};
+
+const normalizeGmailPush = (gmailPush = {}) => {
+  const rawTopics = gmailPush?.topics;
+  const topics = Object.fromEntries(
+    Object.entries(rawTopics && typeof rawTopics === "object" ? rawTopics : {})
+      .map(([client, topic]) => [
+        String(client || "").trim(),
+        String(topic || "").trim(),
+      ])
+      .filter(([client, topic]) => client && topic),
+  );
+  return {
+    token: String(gmailPush?.token || "").trim(),
+    topics,
+  };
+};
+
+const isLikelyPersonalEmail = (email = "") => {
+  const normalized = String(email || "").trim().toLowerCase();
+  return normalized.endsWith("@gmail.com") || normalized.endsWith("@googlemail.com");
+};
+
+const normalizePersonalFlag = ({ account = {}, client = kDefaultGoogleClient }) => {
+  if (typeof account.personal === "boolean") return account.personal;
+  if (client === "personal") return true;
+  return isLikelyPersonalEmail(account.email);
+};
+
+const normalizeGoogleAccount = (account = {}) => ({
+  // Backward-compatible migration path for older state entries that predate
+  // explicit personal flags or were saved before the personal marker existed.
+  ...(() => {
+    const client =
+      String(account.client || kDefaultGoogleClient).trim() || kDefaultGoogleClient;
+    return {
+      id: String(account.id || createGoogleAccountId()),
+      email: String(account.email || "").trim(),
+      client,
+      personal: normalizePersonalFlag({ account, client }),
+      services: normalizeScopes(account.services),
+      authenticated: Boolean(account.authenticated),
+      gmailWatch: normalizeGmailWatch(account.gmailWatch),
+    };
+  })(),
+});
+
+const normalizeGoogleStateV2 = (state = {}) => {
+  const accounts = Array.isArray(state.accounts)
+    ? state.accounts.map((account) => normalizeGoogleAccount(account))
+    : [];
+  return {
+    version: kGoogleStateVersion,
+    accounts,
+    gmailPush: normalizeGmailPush(state.gmailPush),
+  };
+};
+
+const hasPersonalGoogleAccount = (state = {}) =>
+  (state.accounts || []).some((account) => account.personal);
+
+const writeGoogleState = ({ fs, statePath, state }) => {
+  const normalized = normalizeGoogleStateV2(state);
+  fs.writeFileSync(statePath, JSON.stringify(normalized, null, 2));
+  return normalized;
+};
+
+const migrateGoogleStateV1 = ({ fs, statePath, rawState = {} }) => {
+  const email = String(rawState.email || "").trim();
+  const accounts = email
+    ? [
+        normalizeGoogleAccount({
+          id: createGoogleAccountId(),
+          email,
+          services: rawState.services,
+          authenticated: Boolean(rawState.authenticated),
+          client: kDefaultGoogleClient,
+          personal: false,
+        }),
+      ]
+    : [];
+  const migrated = {
+    version: kGoogleStateVersion,
+    accounts,
+    gmailPush: normalizeGmailPush({}),
+  };
+  fs.writeFileSync(statePath, JSON.stringify(migrated, null, 2));
+  return migrated;
+};
+
+const readGoogleState = ({ fs, statePath }) => {
+  if (!fs.existsSync(statePath)) return createEmptyGoogleState();
+  try {
+    const raw = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    if (raw && raw.version === kGoogleStateVersion && Array.isArray(raw.accounts)) {
+      const normalized = normalizeGoogleStateV2(raw);
+      if (JSON.stringify(raw) !== JSON.stringify(normalized)) {
+        fs.writeFileSync(statePath, JSON.stringify(normalized, null, 2));
+      }
+      return normalized;
+    }
+    return migrateGoogleStateV1({ fs, statePath, rawState: raw || {} });
+  } catch {
+    return createEmptyGoogleState();
+  }
+};
+
+const listGoogleAccounts = (state = {}) => [...(state.accounts || [])];
+
+const getGoogleAccountById = (state = {}, accountId = "") =>
+  (state.accounts || []).find((account) => account.id === accountId) || null;
+
+const getGoogleAccountByEmailAndClient = (
+  state = {},
+  email = "",
+  client = kDefaultGoogleClient,
+) =>
+  (state.accounts || []).find(
+    (account) => account.email === email && account.client === client,
+  ) || null;
+
+const getGoogleAccountByEmail = (state = {}, email = "") => {
+  const normalizedEmail = String(email || "").trim().toLowerCase();
+  if (!normalizedEmail) return null;
+  return (
+    (state.accounts || []).find(
+      (account) =>
+        String(account.email || "").trim().toLowerCase() === normalizedEmail,
+    ) || null
+  );
+};
+
+const getGmailPushConfig = (state = {}) => normalizeGmailPush(state.gmailPush);
+
+const setGmailPushConfig = ({ state = {}, config = {} }) => {
+  const nextState = normalizeGoogleStateV2(state);
+  nextState.gmailPush = normalizeGmailPush({
+    ...nextState.gmailPush,
+    ...config,
+    topics: {
+      ...(nextState.gmailPush?.topics || {}),
+      ...((config?.topics && typeof config.topics === "object")
+        ? config.topics
+        : {}),
+    },
+  });
+  return { state: nextState, gmailPush: nextState.gmailPush };
+};
+
+const getAccountGmailWatch = (account = {}) =>
+  normalizeGmailWatch(account?.gmailWatch);
+
+const setAccountGmailWatch = ({ state = {}, accountId = "", watch = {} }) => {
+  const nextState = normalizeGoogleStateV2(state);
+  const targetId = String(accountId || "").trim();
+  if (!targetId) return { state: nextState, account: null };
+  const accountIndex = nextState.accounts.findIndex(
+    (account) => account.id === targetId,
+  );
+  if (accountIndex === -1) return { state: nextState, account: null };
+  const account = nextState.accounts[accountIndex];
+  const mergedWatch = normalizeGmailWatch({
+    ...(account.gmailWatch || {}),
+    ...watch,
+  });
+  const nextAccount = {
+    ...account,
+    gmailWatch: mergedWatch,
+  };
+  nextState.accounts[accountIndex] = nextAccount;
+  return { state: nextState, account: nextAccount };
+};
+
+const listWatchEnabledAccounts = (state = {}) =>
+  (state.accounts || []).filter((account) =>
+    Boolean(normalizeGmailWatch(account.gmailWatch).enabled),
+  );
+
+const generatePushToken = () => crypto.randomBytes(24).toString("base64url");
+
+const allocateServePort = ({
+  state = {},
+  basePort = 18801,
+  maxAccounts = 5,
+}) => {
+  const usedPorts = new Set(
+    (state.accounts || [])
+      .map((account) => normalizePositiveInt(account?.gmailWatch?.port))
+      .filter(Boolean),
+  );
+  for (let offset = 0; offset < maxAccounts; offset += 1) {
+    const candidate = basePort + offset;
+    if (!usedPorts.has(candidate)) return candidate;
+  }
+  return null;
+};
+
+const upsertGoogleAccount = ({
+  state,
+  account,
+  maxAccounts = 5,
+}) => {
+  const nextState = normalizeGoogleStateV2(state);
+  const normalized = normalizeGoogleAccount(account);
+  if (!normalized.email) throw new Error("Account email is required");
+  const existingIdx = nextState.accounts.findIndex((item) => item.id === normalized.id);
+
+  if (normalized.personal) {
+    const personalExists = nextState.accounts.some(
+      (item, idx) => item.personal && idx !== existingIdx,
+    );
+    if (personalExists) {
+      throw new Error("Only one personal account is allowed");
+    }
+  }
+
+  if (existingIdx >= 0) {
+    nextState.accounts[existingIdx] = normalized;
+    return { state: nextState, account: normalized };
+  }
+
+  if (nextState.accounts.length >= maxAccounts) {
+    throw new Error(`Maximum ${maxAccounts} Google accounts allowed`);
+  }
+
+  nextState.accounts.push(normalized);
+  return { state: nextState, account: normalized };
+};
+
+const removeGoogleAccount = ({ state, accountId }) => {
+  const nextState = normalizeGoogleStateV2(state);
+  const removed = getGoogleAccountById(nextState, accountId);
+  if (!removed) return { state: nextState, account: null };
+  nextState.accounts = nextState.accounts.filter((account) => account.id !== accountId);
+  return { state: nextState, account: removed };
+};
+
+module.exports = {
+  kGoogleStateVersion,
+  kDefaultGoogleClient,
+  kDefaultGoogleScopes,
+  createGoogleAccountId,
+  createEmptyGoogleState,
+  readGoogleState,
+  writeGoogleState,
+  listGoogleAccounts,
+  getGoogleAccountById,
+  getGoogleAccountByEmailAndClient,
+  getGoogleAccountByEmail,
+  upsertGoogleAccount,
+  removeGoogleAccount,
+  hasPersonalGoogleAccount,
+  getGmailPushConfig,
+  setGmailPushConfig,
+  getAccountGmailWatch,
+  setAccountGmailWatch,
+  listWatchEnabledAccounts,
+  generatePushToken,
+  allocateServePort,
+};

package/lib/server/helpers.js

@@ -3,7 +3,7 @@ const crypto = require("crypto");
 const {
   CODEX_JWT_CLAIM_PATH,
   kOnboardingModelProviders,
-  GOG_CREDENTIALS_PATH,
+  gogClientCredentialsPath,
 } = require("./constants");
 
 const normalizeOpenclawVersion = (rawVersion) => {
@@ -170,20 +170,26 @@ const getApiEnableUrl = (svc, projectId) => {
   return `https://console.developers.google.com/apis/api/${api}/overview${project}`;
 };
 
-const readGoogleCredentials = () => {
+const readGoogleCredentials = (clientName = "default") => {
   try {
-    const c = JSON.parse(fs.readFileSync(GOG_CREDENTIALS_PATH, "utf8"));
+    const credentialsPath = gogClientCredentialsPath(clientName);
+    const c = JSON.parse(fs.readFileSync(credentialsPath, "utf8"));
+    const webCredentials = c.web || c.installed || c;
     return {
-      clientId:
-        c.web?.client_id || c.installed?.client_id || c.client_id || null,
-      clientSecret:
-        c.web?.client_secret ||
-        c.installed?.client_secret ||
-        c.client_secret ||
-        null,
+      clientId: webCredentials?.client_id || null,
+      clientSecret: webCredentials?.client_secret || null,
+      projectId: webCredentials?.project_id || null,
+      path: credentialsPath,
+      client: clientName,
     };
   } catch {
-    return { clientId: null, clientSecret: null };
+    return {
+      clientId: null,
+      clientSecret: null,
+      projectId: null,
+      path: gogClientCredentialsPath(clientName),
+      client: clientName,
+    };
   }
 };
 

package/lib/server/internal-files-migration.js

@@ -3,6 +3,11 @@ const path = require("path");
 const kInternalDirName = ".alphaclaw";
 const kHourlyGitSyncFileName = "hourly-git-sync.sh";
 const kCliDeviceAutoApprovedFileName = ".cli-device-auto-approved";
+const kOpenclawGitignoreHookEntries = [
+  "!hooks/",
+  "!hooks/transforms/",
+  "!hooks/transforms/**",
+];
 
 const buildManagedPaths = ({ openclawDir, pathModule = path }) => {
   const internalDir = pathModule.join(openclawDir, kInternalDirName);
@@ -13,7 +18,10 @@ const buildManagedPaths = ({ openclawDir, pathModule = path }) => {
       internalDir,
       kCliDeviceAutoApprovedFileName,
     ),
-    legacyHourlyGitSyncPath: pathModule.join(openclawDir, kHourlyGitSyncFileName),
+    legacyHourlyGitSyncPath: pathModule.join(
+      openclawDir,
+      kHourlyGitSyncFileName,
+    ),
     legacyCliDeviceAutoApprovedPath: pathModule.join(
       openclawDir,
       kCliDeviceAutoApprovedFileName,
@@ -45,7 +53,9 @@ const migrateManagedInternalFiles = ({
   fs.mkdirSync(managedPaths.internalDir, { recursive: true });
 
   const migrateOne = ({ sourcePaths, targetPath }) => {
-    const existingSourcePath = sourcePaths.find((sourcePath) => fs.existsSync(sourcePath));
+    const existingSourcePath = sourcePaths.find((sourcePath) =>
+      fs.existsSync(sourcePath),
+    );
     if (fs.existsSync(targetPath)) {
       sourcePaths.forEach((sourcePath) => {
         if (sourcePath !== targetPath && fs.existsSync(sourcePath)) {
@@ -63,13 +73,31 @@ const migrateManagedInternalFiles = ({
       mode: sourceStats.mode,
     });
     sourcePaths.forEach((sourcePath) => {
-      if (sourcePath !== existingSourcePath && sourcePath !== targetPath && fs.existsSync(sourcePath)) {
+      if (
+        sourcePath !== existingSourcePath &&
+        sourcePath !== targetPath &&
+        fs.existsSync(sourcePath)
+      ) {
         fs.rmSync(sourcePath, { force: true });
       }
     });
   };
 
   try {
+    const gitignorePath = pathModule.join(openclawDir, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+      const raw = String(fs.readFileSync(gitignorePath, "utf8") || "");
+      const existingLines = raw.split(/\r?\n/);
+      const existingSet = new Set(existingLines.map((line) => line.trim()));
+      const missing = kOpenclawGitignoreHookEntries.filter(
+        (line) => !existingSet.has(line),
+      );
+      if (missing.length) {
+        const separator = raw.endsWith("\n") || !raw.length ? "" : "\n";
+        const next = `${raw}${separator}${missing.join("\n")}\n`;
+        fs.writeFileSync(gitignorePath, next);
+      }
+    }
     migrateOne({
       sourcePaths: [managedPaths.legacyHourlyGitSyncPath],
       targetPath: managedPaths.hourlyGitSyncPath,

package/lib/server/onboarding/github.js

@@ -64,13 +64,28 @@ const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
       headers: ghHeaders,
     });
     if (checkRes.status === 404) {
-      return { ok: true };
+      return { ok: true, repoExists: false, repoIsEmpty: false };
     }
     if (checkRes.ok) {
+      const commitsRes = await fetch(
+        `https://api.github.com/repos/${repoUrl}/commits?per_page=1`,
+        { headers: ghHeaders },
+      );
+      if (commitsRes.status === 409) {
+        return { ok: true, repoExists: true, repoIsEmpty: true };
+      }
+      if (commitsRes.ok) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Repository "${repoUrl}" already exists and is not empty.`,
+        };
+      }
+      const commitCheckDetails = await parseGithubErrorMessage(commitsRes);
       return {
         ok: false,
         status: 400,
-        error: `Repository "${repoUrl}" already exists.`,
+        error: `Cannot verify whether repo "${repoUrl}" is empty: ${commitCheckDetails}`,
       };
     }
 
@@ -100,6 +115,10 @@ const ensureGithubRepoAccessible = async ({
     githubToken,
   });
   if (!verification.ok) return verification;
+  if (verification.repoExists && verification.repoIsEmpty) {
+    console.log(`[onboard] Using existing empty repo ${repoUrl}`);
+    return { ok: true };
+  }
 
   try {
     console.log(`[onboard] Creating repo ${repoUrl}...`);

package/lib/server/onboarding/index.js

@@ -17,9 +17,7 @@ const {
   installHourlyGitSyncScript,
   installHourlyGitSyncCron,
 } = require("./cron");
-const {
-  migrateManagedInternalFiles,
-} = require("../internal-files-migration");
+const { migrateManagedInternalFiles } = require("../internal-files-migration");
 
 const createOnboardingService = ({
   fs,

package/lib/server/onboarding/openclaw.js

@@ -8,6 +8,7 @@ const kUsageTrackerPluginPath = path.resolve(
   "plugin",
   "usage-tracker",
 );
+const kDefaultToolsProfile = "full";
 
 const buildOnboardArgs = ({
   varMap,
@@ -134,10 +135,12 @@ const writeSanitizedOpenclawConfig = ({ fs, openclawDir, varMap }) => {
   if (!Array.isArray(cfg.plugins.load.paths)) cfg.plugins.load.paths = [];
   if (!cfg.plugins.entries) cfg.plugins.entries = {};
   if (!cfg.commands) cfg.commands = {};
+  if (!cfg.tools) cfg.tools = {};
   if (!cfg.hooks) cfg.hooks = {};
   if (!cfg.hooks.internal) cfg.hooks.internal = {};
   if (!cfg.hooks.internal.entries) cfg.hooks.internal.entries = {};
   cfg.commands.restart = true;
+  cfg.tools.profile = kDefaultToolsProfile;
   cfg.hooks.internal.enabled = true;
   cfg.hooks.internal.entries["bootstrap-extra-files"] = {
     ...(cfg.hooks.internal.entries["bootstrap-extra-files"] || {}),

package/lib/server/onboarding/workspace.js

@@ -1,6 +1,7 @@
 const path = require("path");
 const { kSetupDir, OPENCLAW_DIR } = require("../constants");
 const { renderTopicRegistryMarkdown } = require("../topic-registry");
+const { readGoogleState } = require("../google-state");
 
 const resolveSetupUiUrl = (baseUrl) => {
   const normalizedBaseUrl = String(baseUrl || "").trim().replace(/\/+$/, "");
@@ -32,6 +33,41 @@ const isTelegramWorkspaceEnabled = (fs) => {
   }
 };
 
+const renderGoogleAccountsMarkdown = (fs) => {
+  try {
+    const googleStatePath = `${OPENCLAW_DIR}/gogcli/state.json`;
+    const state = readGoogleState({ fs, statePath: googleStatePath });
+    const accounts = Array.isArray(state.accounts) ? state.accounts : [];
+    let section = "\n\n## Available Google Accounts\n\n";
+    if (!accounts.length) {
+      section += "No Google accounts are currently configured.\n";
+      return section;
+    }
+    section +=
+      "Configured in AlphaClaw (use `--client <client> --account <email>` for gog commands):\n\n";
+    section += accounts
+      .map((account) => {
+        const email = String(account.email || "").trim() || "(unknown email)";
+        const client = String(account.client || "default").trim() || "default";
+        const personal = account.personal ? "personal" : "company";
+        const auth = account.authenticated ? "authenticated" : "awaiting sign-in";
+        const services = Array.isArray(account.services) ? account.services.join(", ") : "";
+        const metaParts = [
+          `type: ${personal}`,
+          `client: ${client}`,
+          `status: ${auth}`,
+          services ? `services: ${services}` : null,
+        ].filter(Boolean);
+        return `- ${email} (${metaParts.join("; ")})`;
+      })
+      .join("\n");
+    section += "\n";
+    return section;
+  } catch {
+    return "";
+  }
+};
+
 const syncBootstrapPromptFiles = ({ fs, workspaceDir, baseUrl }) => {
   try {
     const setupUiUrl = resolveSetupUiUrl(baseUrl);
@@ -51,6 +87,10 @@ const syncBootstrapPromptFiles = ({ fs, workspaceDir, baseUrl }) => {
     if (topicSection) {
       toolsContent += topicSection;
     }
+    const googleAccountsSection = renderGoogleAccountsMarkdown(fs);
+    if (googleAccountsSection) {
+      toolsContent += googleAccountsSection;
+    }
 
     fs.writeFileSync(`${bootstrapDir}/TOOLS.md`, toolsContent);
     console.log("[onboard] Bootstrap prompt files synced");

package/lib/server/routes/browse/index.js

@@ -1,5 +1,5 @@
 const path = require("path");
-const { kLockedBrowsePaths } = require("../../constants");
+const { kLockedBrowsePaths, kProtectedBrowsePaths } = require("../../constants");
 const {
   kDefaultTreeDepth,
   kIgnoredDirectoryNames,
@@ -30,7 +30,6 @@ const registerBrowseRoutes = ({ app, fs, kRootDir }) => {
   const kRootResolved = path.resolve(kRootDir);
   const kRootWithSep = `${kRootResolved}${path.sep}`;
   const kRootDisplayName = "kRootDir/.openclaw";
-
   if (!fs.existsSync(kRootResolved)) {
     fs.mkdirSync(kRootResolved, { recursive: true });
   }
@@ -369,7 +368,14 @@ const registerBrowseRoutes = ({ app, fs, kRootDir }) => {
         .split("\n")
         .map((line) => line.trim())
         .filter(Boolean);
+      const rawStatus = statusLines[0]?.slice(0, 2) || "";
       const isUntracked = statusLines.some((line) => line.startsWith("??"));
+      const statusKind =
+        rawStatus === "??" || rawStatus.includes("A")
+          ? "U"
+          : rawStatus.includes("D")
+            ? "D"
+            : "M";
 
       const diffResult = isUntracked
         ? await runGitCommandWithExitCode(
@@ -397,6 +403,8 @@ const registerBrowseRoutes = ({ app, fs, kRootDir }) => {
         ok: true,
         path: relativePath,
         content,
+        statusKind,
+        isDeleted: statusKind === "D",
       });
     } catch (error) {
       return res.status(500).json({
@@ -567,6 +575,86 @@ const registerBrowseRoutes = ({ app, fs, kRootDir }) => {
         .json({ ok: false, error: error.message || "Could not save file" });
     }
   });
+
+  app.delete("/api/browse/delete", (req, res) => {
+    const targetPath = String(req.body?.path || "").trim();
+    const resolvedPath = resolveSafePath(
+      targetPath,
+      kRootResolved,
+      kRootWithSep,
+      kRootDisplayName,
+    );
+    if (!resolvedPath.ok) {
+      return res.status(400).json({ ok: false, error: resolvedPath.error });
+    }
+    const normalizedPolicyPath = normalizePolicyPath(resolvedPath.relativePath);
+    if (
+      matchesPolicyPath(kLockedBrowsePaths, normalizedPolicyPath) ||
+      matchesPolicyPath(kProtectedBrowsePaths, normalizedPolicyPath)
+    ) {
+      return res.status(403).json({
+        ok: false,
+        error: "This file cannot be deleted from the explorer.",
+      });
+    }
+    try {
+      if (!fs.existsSync(resolvedPath.absolutePath)) {
+        return res.status(404).json({ ok: false, error: "File does not exist" });
+      }
+      const stats = fs.statSync(resolvedPath.absolutePath);
+      if (!stats.isFile()) {
+        return res.status(400).json({ ok: false, error: "Path is not a file" });
+      }
+      fs.rmSync(resolvedPath.absolutePath, { force: true });
+      return res.json({
+        ok: true,
+        path: resolvedPath.relativePath,
+      });
+    } catch (error) {
+      return res.status(500).json({
+        ok: false,
+        error: error.message || "Could not delete file",
+      });
+    }
+  });
+
+  app.post("/api/browse/restore", async (req, res) => {
+    const { path: targetPath } = req.body || {};
+    const resolvedPath = resolveSafePath(
+      targetPath,
+      kRootResolved,
+      kRootWithSep,
+      kRootDisplayName,
+    );
+    if (!resolvedPath.ok) {
+      return res.status(400).json({ ok: false, error: resolvedPath.error });
+    }
+    const relativePath = String(resolvedPath.relativePath || "").trim();
+    if (!relativePath) {
+      return res.status(400).json({ ok: false, error: "path is required" });
+    }
+    const restoreResult = await runGitCommand(
+      ["restore", "--staged", "--worktree", "--", relativePath],
+      kRootResolved,
+    );
+    const fallbackResult = !restoreResult.ok
+      ? await runGitCommand(["checkout", "--", relativePath], kRootResolved)
+      : { ok: true };
+    if (!restoreResult.ok && !fallbackResult.ok) {
+      return res.status(500).json({
+        ok: false,
+        error:
+          restoreResult.error ||
+          fallbackResult.error ||
+          "Could not restore file from git",
+      });
+    }
+    return res.json({
+      ok: true,
+      path: relativePath,
+      restored: fs.existsSync(resolvedPath.absolutePath),
+    });
+  });
 };
 
 module.exports = { registerBrowseRoutes };