dsh-gitbar-lite 0.0.0-stage → 0.1.0

package/lib/host/store.js

@@ -0,0 +1,360 @@
+/**
+ * Durable state: workspace→repository bindings, UI preferences, and the plugin's
+ * own trash.
+ *
+ * Where it lives
+ * --------------
+ * `<DSH_HOME>/dsh-gitbar-lite/`, falling back to `~/.dsh` exactly the way
+ * `@deepseek-ai/dsh-home-paths` does. Do not read `$DSH_HOME` alone: the Host
+ * process usually does *not* have it set (the variable is injected into the
+ * shell the Harness spawns), so a state file written under a bare
+ * `process.env.DSH_HOME` would silently land somewhere else or nowhere. This is
+ * the same trap `dsh-tailscale-remote` documents in its own state-file code.
+ *
+ * Why not the settings service or a storage domain
+ * -----------------------------------------------
+ * A binding is keyed by an arbitrary absolute workspace path, and a storage
+ * domain's per-record keys are restricted to `^[a-zA-Z0-9_-]+$` because they
+ * become path segments — `C:\Users\...\<folder with spaces>` cannot be one
+ * without hashing it, at which point the "native" option is doing less for us
+ * than the twelve lines below. A settings `Config` would put a growing map of
+ * machine paths into the user-visible settings form, which is worse. So this is
+ * a plain JSON file the plugin owns, written through a temp file and a rename
+ * so a crash mid-write cannot truncate it.
+ *
+ * @module dsh-gitbar-lite/host/store
+ */
+
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+import { STATE_DIR_NAME, STATE_FILES } from '../shared.js'
+
+/** Schema version of every file this module writes. */
+const STATE_VERSION = 1
+
+/**
+ * Resolve the DSH home directory, matching `resolveDshHome` from
+ * `@deepseek-ai/dsh-home-paths`: explicit config wins, then a non-blank
+ * `$DSH_HOME`, then `~/.dsh`.
+ *
+ * @param {string} configured
+ * @returns {string}
+ */
+export function resolveDshHome(configured) {
+  if (typeof configured === 'string' && configured.trim() !== '') return configured.trim()
+  const fromEnv = process.env.DSH_HOME
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv.trim()
+  return join(homedir(), '.dsh')
+}
+
+/**
+ * Canonicalize a path so two spellings of one directory share a record: resolve
+ * relatives, drop a trailing separator, and (best effort) follow junctions and
+ * symlinks to their real target. Falls back to the lexical form when the path
+ * does not exist yet.
+ *
+ * @param {string} input
+ * @returns {string}
+ */
+export function canonicalize(input) {
+  let absolute
+  try {
+    absolute = resolve(input)
+  } catch {
+    return String(input)
+  }
+  try {
+    return realpathSync.native(absolute)
+  } catch {
+    return absolute
+  }
+}
+
+/**
+ * The binding key for a workspace path: canonical, separator-normalized, and
+ * case-folded on Windows, where `C:\Foo` and `c:\foo` are one directory.
+ *
+ * @param {string} workspacePath
+ */
+export function workspaceKey(workspacePath) {
+  const canonical = canonicalize(workspacePath).replace(/[\\/]+$/, '')
+  return process.platform === 'win32' ? canonical.toLowerCase() : canonical
+}
+
+/** A filesystem-safe, roughly sortable id for a trash entry. */
+export function trashId(now = Date.now(), random = Math.random) {
+  const suffix = Math.floor(random() * 0xffffffff)
+    .toString(36)
+    .padStart(7, '0')
+  return `${now.toString(36)}-${suffix}`
+}
+
+/**
+ * Build the store bound to one plugin instance.
+ *
+ * @param {object} ctx host context (for `logger` only)
+ * @param {object} config resolved plugin config
+ */
+export function createStore(ctx, config) {
+  const warn = (message) => {
+    try {
+      ctx.logger?.warn?.(message)
+    } catch {
+      // Logging must never be the thing that breaks a request.
+    }
+  }
+
+  const baseDir = () =>
+    typeof config.stateDir === 'string' && config.stateDir.trim() !== ''
+      ? config.stateDir.trim()
+      : join(resolveDshHome(process.env.DSH_HOME), STATE_DIR_NAME)
+
+  const bindingsPath = () => join(baseDir(), STATE_FILES.BINDINGS)
+  const prefsPath = () => join(baseDir(), STATE_FILES.PREFS)
+  const trashIndexPath = () => join(baseDir(), STATE_FILES.TRASH_INDEX)
+  const trashDir = () => join(baseDir(), 'trash')
+
+  /**
+   * Serialize writes per file.
+   *
+   * Two tabs (or the panel and its trash tab) can issue overlapping mutations,
+   * and a read-modify-write that interleaves loses one of them. Chaining per
+   * path is enough: every writer goes through `mutateJson`.
+   */
+  const queues = new Map()
+  function serialize(path, work) {
+    const previous = queues.get(path) ?? Promise.resolve()
+    const next = previous.then(work, work)
+    queues.set(
+      path,
+      next.then(
+        () => undefined,
+        () => undefined,
+      ),
+    )
+    return next
+  }
+
+  /** Read JSON, returning `fallback` for anything missing or malformed. */
+  async function readJson(path, fallback) {
+    try {
+      const parsed = JSON.parse(await readFile(path, 'utf8'))
+      if (parsed === null || typeof parsed !== 'object') return fallback
+      return parsed
+    } catch (error) {
+      if (error?.code !== 'ENOENT') warn(`dsh-gitbar-lite: ignoring unreadable ${path}: ${String(error?.message ?? error)}`)
+      return fallback
+    }
+  }
+
+  /** Write JSON through a temp file plus rename, so a crash cannot truncate it. */
+  async function writeJson(path, value) {
+    const temporary = `${path}.tmp`
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+    await rename(temporary, path)
+  }
+
+  /** Read-modify-write under the per-path queue. */
+  function mutateJson(path, fallback, mutate) {
+    return serialize(path, async () => {
+      const current = await readJson(path, fallback)
+      const next = await mutate(current)
+      await writeJson(path, next)
+      return next
+    })
+  }
+
+  return {
+    baseDir,
+    trashDir,
+    bindingsPath,
+    prefsPath,
+    trashIndexPath,
+    readJson,
+    writeJson,
+
+    // ---------------------------------------------------------------- bindings
+
+    /** Every binding, keyed by `workspaceKey`. */
+    async readBindings() {
+      const document = await readJson(bindingsPath(), { version: STATE_VERSION, bindings: {} })
+      const bindings = document?.bindings
+      return bindings !== null && typeof bindings === 'object' ? bindings : {}
+    },
+
+    /** The repository bound to one workspace path, or `undefined`. */
+    async readBinding(workspacePath) {
+      const bindings = await this.readBindings()
+      const record = bindings[workspaceKey(workspacePath)]
+      return typeof record?.repoRoot === 'string' && record.repoRoot !== '' ? record.repoRoot : undefined
+    },
+
+    /**
+     * Bind (or, with `undefined`, unbind) one workspace path.
+     *
+     * @returns {Promise<string | undefined>} the repository now bound
+     */
+    async writeBinding(workspacePath, repoRoot) {
+      const key = workspaceKey(workspacePath)
+      const canonicalWorkspace = canonicalize(workspacePath)
+      let result
+      await mutateJson(bindingsPath(), { version: STATE_VERSION, bindings: {} }, (document) => {
+        const bindings = document?.bindings !== null && typeof document?.bindings === 'object' ? { ...document.bindings } : {}
+        if (repoRoot === undefined) {
+          delete bindings[key]
+          result = undefined
+        } else {
+          bindings[key] = {
+            repoRoot: canonicalize(repoRoot),
+            workspacePath: canonicalWorkspace,
+            updatedAt: new Date().toISOString(),
+          }
+          result = bindings[key].repoRoot
+        }
+        return { version: STATE_VERSION, bindings }
+      })
+      return result
+    },
+
+    // ------------------------------------------------------------------- prefs
+
+    /** Preferences, with defaults applied. */
+    async readPrefs() {
+      const document = await readJson(prefsPath(), { version: STATE_VERSION })
+      return {
+        /**
+         * Whether the discard confirmation starts with "delete for good" ticked.
+         * Default false: the safe answer is the one that keeps a copy.
+         */
+        trashHardDelete: document?.trashHardDelete === true,
+        /** Whether the trash lists entries from every repository, not just the bound one. */
+        trashShowAllRepos: document?.trashShowAllRepos === true,
+      }
+    },
+
+    /** Merge a preferences patch. */
+    async writePrefs(patch) {
+      let result
+      await mutateJson(prefsPath(), { version: STATE_VERSION }, (document) => {
+        result = {
+          version: STATE_VERSION,
+          trashHardDelete: (patch?.trashHardDelete ?? document?.trashHardDelete) === true,
+          trashShowAllRepos: (patch?.trashShowAllRepos ?? document?.trashShowAllRepos) === true,
+        }
+        return result
+      })
+      return result
+    },
+
+    // ------------------------------------------------------------------- trash
+
+    /**
+     * The trash index: metadata for every archived discard, newest first.
+     *
+     * Entries whose blob is missing are still listed — the metadata (which
+     * repository, which base commit, which files) is worth keeping even if
+     * someone deleted the `.diff` by hand.
+     */
+    async readTrash() {
+      const document = await readJson(trashIndexPath(), { version: STATE_VERSION, entries: [] })
+      const entries = Array.isArray(document?.entries) ? document.entries : []
+      return entries.filter((entry) => entry !== null && typeof entry?.id === 'string')
+    },
+
+    /**
+     * Append one entry, trimming the index to `config.trashLimit` and deleting
+     * the blobs of whatever falls off the end.
+     *
+     * @param {object} entry
+     * @param {string} diffText
+     */
+    async appendTrash(entry, diffText) {
+      const blobName = `${entry.id}.diff`
+      await mkdir(trashDir(), { recursive: true })
+      await writeFile(join(trashDir(), blobName), diffText, 'utf8')
+
+      let dropped = []
+      await mutateJson(trashIndexPath(), { version: STATE_VERSION, entries: [] }, (document) => {
+        const existing = Array.isArray(document?.entries) ? document.entries : []
+        const limit = Number.isFinite(config.trashLimit) && config.trashLimit > 0 ? config.trashLimit : 200
+        const combined = [{ ...entry, blob: blobName }, ...existing]
+        dropped = combined.slice(limit)
+        return { version: STATE_VERSION, entries: combined.slice(0, limit) }
+      })
+
+      for (const stale of dropped) {
+        if (typeof stale?.blob === 'string') await this.removeTrashBlob(stale.blob)
+      }
+      return entry
+    },
+
+    /** One entry's metadata, or `undefined`. */
+    async readTrashEntry(id) {
+      const entries = await this.readTrash()
+      return entries.find((entry) => entry.id === id)
+    },
+
+    /** One entry's archived diff text, or `undefined` when the blob is gone. */
+    async readTrashDiff(entry) {
+      const blob = typeof entry?.blob === 'string' && entry.blob !== '' ? entry.blob : `${entry?.id}.diff`
+      try {
+        return await readFile(join(trashDir(), blob), 'utf8')
+      } catch (error) {
+        if (error?.code !== 'ENOENT') warn(`dsh-gitbar-lite: reading trash blob failed: ${String(error?.message ?? error)}`)
+        return undefined
+      }
+    },
+
+    /** Delete one blob, tolerating its absence. */
+    async removeTrashBlob(blob) {
+      const name = String(blob).replace(/[\\/]/g, '')
+      if (name === '' || name.includes('..')) return
+      try {
+        await rm(join(trashDir(), name), { force: true })
+      } catch (error) {
+        warn(`dsh-gitbar-lite: removing trash blob failed: ${String(error?.message ?? error)}`)
+      }
+    },
+
+    /**
+     * Drop one entry and its blob.
+     *
+     * @returns {Promise<boolean>} whether an entry was actually removed
+     */
+    async removeTrash(id) {
+      const entry = await this.readTrashEntry(id)
+      if (entry === undefined) return false
+      await mutateJson(trashIndexPath(), { version: STATE_VERSION, entries: [] }, (document) => {
+        const existing = Array.isArray(document?.entries) ? document.entries : []
+        return { version: STATE_VERSION, entries: existing.filter((candidate) => candidate.id !== id) }
+      })
+      if (typeof entry.blob === 'string') await this.removeTrashBlob(entry.blob)
+      return true
+    },
+
+    /**
+     * Empty the trash.
+     *
+     * The blobs are swept by directory listing rather than by index, so a blob
+     * orphaned by an interrupted write goes too.
+     *
+     * @returns {Promise<number>} how many entries were removed
+     */
+    async clearTrash() {
+      const entries = await this.readTrash()
+      await writeJson(trashIndexPath(), { version: STATE_VERSION, entries: [] })
+      try {
+        for (const name of await readdir(trashDir())) {
+          if (name.endsWith('.diff')) await this.removeTrashBlob(name)
+        }
+      } catch (error) {
+        if (error?.code !== 'ENOENT') warn(`dsh-gitbar-lite: sweeping trash failed: ${String(error?.message ?? error)}`)
+      }
+      return entries.length
+    },
+  }
+}

package/lib/host/workspace.js

@@ -0,0 +1,84 @@
+/**
+ * Which directory is this session's workspace?
+ *
+ * The answer is taken from the same place the shipped
+ * `@deepseek-ai/dsh-api-workspace-files` takes it: the session header's `cwd`,
+ * falling back to the sandbox policy's `workspaceRoot`. That is the authoritative
+ * answer — a workspace record's `sessionIds` is *not*, because the registry only
+ * indexes sessions that existed when the Host booted, so a session created a
+ * minute ago is filtered out of its own workspace's list.
+ *
+ * Every value here is optional-chained: a plugin must not turn a missing
+ * optional service into a thrown error that blanks a panel.
+ *
+ * @module dsh-gitbar-lite/host/workspace
+ */
+
+import { ERROR_CODES } from '../shared.js'
+import { RepoError } from './repo.js'
+
+/**
+ * The header of one session, live when possible and persisted otherwise.
+ *
+ * @param {object} ctx host context
+ * @param {string} sessionId
+ * @returns {Promise<object | undefined>}
+ */
+async function headerOf(ctx, sessionId) {
+  const live = ctx.sessions?.get?.(sessionId)?.header
+  if (live !== undefined && live !== null) return live
+  const persistence = ctx.get?.('sessionPersistence', false)
+  if (persistence === undefined || typeof persistence.stat !== 'function') return undefined
+  try {
+    return (await persistence.stat(sessionId))?.header
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The workspace directory a session works in.
+ *
+ * @param {object} ctx host context
+ * @param {string} sessionId
+ * @returns {Promise<{ sessionId: string, cwd: string, workspaceTitle: string | null } | undefined>}
+ */
+export async function workspaceOf(ctx, sessionId) {
+  const header = await headerOf(ctx, sessionId)
+  if (header === undefined) return undefined
+
+  const fromPolicy = ctx.get?.('sandboxPolicy', false)?.workspaceRoot
+  const cwd = typeof header.cwd === 'string' && header.cwd !== '' ? header.cwd : typeof fromPolicy === 'string' ? fromPolicy : ''
+  if (cwd === '') return undefined
+
+  let workspaceTitle = null
+  const registry = ctx.get?.('workspaceRegistry', false)
+  if (registry !== undefined && typeof registry.resolveByPath === 'function') {
+    try {
+      workspaceTitle = (await registry.resolveByPath(cwd))?.title ?? null
+    } catch {
+      // `resolveByPath` realpaths and therefore rejects for a missing directory;
+      // the cwd we already have is still the right answer.
+      workspaceTitle = null
+    }
+  }
+
+  return { sessionId, cwd, workspaceTitle }
+}
+
+/**
+ * `workspaceOf`, or a `RepoError` carrying the user-facing reason.
+ *
+ * @param {object} ctx host context
+ * @param {string} sessionId
+ */
+export async function requireWorkspace(ctx, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId === '') {
+    throw new RepoError(ERROR_CODES.BAD_REQUEST, '缺少 sessionId。')
+  }
+  const workspace = await workspaceOf(ctx, sessionId)
+  if (workspace === undefined) {
+    throw new RepoError(ERROR_CODES.NO_WORKSPACE, '拿不到这个会话的工作区目录，无法定位仓库。')
+  }
+  return workspace
+}

package/lib/index.js

@@ -0,0 +1,160 @@
+/**
+ * dsh-gitbar-lite — host half.
+ *
+ * A GitHub Desktop-shaped Git panel for the built-in right sidebar. The host
+ * half owns everything that touches the disk or the repository:
+ *
+ *   - `createGit`       runs git through `ctx.subprocess` (resolved executable,
+ *                       containment, a bounded output buffer, a scrubbed env);
+ *   - `createRepo`      the operations themselves — status, stage, commit,
+ *                       push, fetch, per-file diff, discard;
+ *   - `createStore`     the workspace→repository bindings, the UI preferences,
+ *                       and the plugin's own trash under `<DSH_HOME>`;
+ *   - `createHandlers`  the RPC actions the browser half calls;
+ *   - `createRoute`     one exact Fetch route on `connection.fetch`.
+ *
+ * The browser half lives in `lib/client.js` and speaks to this one only over
+ * that route, so it inherits the harness Host/Origin fence and the browser
+ * cookie check for free.
+ *
+ * @module dsh-gitbar-lite
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+import { createGit } from './host/git.js'
+import { createRepo } from './host/repo.js'
+import { createHandlers, createRoute } from './host/routes.js'
+import { createStore } from './host/store.js'
+import { PLUGIN_ID } from './shared.js'
+
+/** Stable Loader identity; also the settings namespace and the client bundle id. */
+export const name = PLUGIN_ID
+
+/**
+ * Only what the plugin cannot work without.
+ *
+ * `connection` is deliberately NOT here: declaring it would park the whole
+ * plugin when the Web bundle is absent, and the plugin is still perfectly able
+ * to run headless. It is acquired opportunistically instead (see `apply`).
+ */
+export const inject = ['subprocess', 'sessions']
+
+/** Guard for a schemastery build without `volatile()`. */
+const vol = (schema) => (typeof schema?.volatile === 'function' ? schema.volatile() : schema)
+
+/**
+ * Plugin configuration.
+ *
+ * Every field is volatile, which is what lets the user change them from the
+ * settings page without a restart — and is why `cordis.patch.yml` deliberately
+ * carries no `config` block: values written into the profile's own patch layer
+ * must not be shadowed by this package on the next upgrade.
+ */
+export const Config = vol(
+  z.object({
+    /** Explicit git executable; empty means "whatever is on PATH". */
+    gitPath: z.string().default(''),
+    /** Override the plugin's state directory; empty means `<DSH_HOME>/dsh-gitbar-lite`. */
+    stateDir: z.string().default(''),
+    /** Per-command timeout. A push to a slow remote may need more. */
+    timeoutMs: z.number().default(30000),
+    /** Ceiling on one archived diff, in bytes. */
+    maxDiffBytes: z.number().default(512 * 1024),
+    /** Files larger than this are listed but their content is not archived or diffed. */
+    maxFileBytes: z.number().default(2 * 1024 * 1024),
+    /** How many trash entries to keep before the oldest are dropped. */
+    trashLimit: z.number().default(200),
+    /** Directory depth the repository picker scans below the workspace root. */
+    scanDepth: z.number().default(3),
+  }),
+)
+
+/** Defaults, read from the schema rather than restated. */
+const DEFAULTS = new Config({}).get()
+
+/**
+ * Resolve the live config.
+ *
+ * A volatile schemastery root is a frozenset whose values are read through
+ * `get()`; a plain one is the object itself. Both shapes have to work, because
+ * whether the schema is volatile is not something this module controls.
+ *
+ * @param {unknown} rawConfig
+ * @returns {typeof DEFAULTS}
+ */
+export function readConfig(rawConfig) {
+  const source = typeof rawConfig?.get === 'function' ? rawConfig.get() : rawConfig
+  const record = source !== null && typeof source === 'object' ? source : {}
+  const resolved = { ...DEFAULTS }
+  for (const key of Object.keys(DEFAULTS)) {
+    const value = record[key]
+    if (value !== undefined && value !== null) resolved[key] = value
+  }
+  return resolved
+}
+
+/**
+ * Install the host half.
+ *
+ * @param {object} ctx host context
+ * @param {unknown} rawConfig the Loader's config for this row
+ */
+export function apply(ctx, rawConfig) {
+  const config = readConfig(rawConfig)
+  const git = createGit(ctx, config)
+  const store = createStore(ctx, config)
+  const repo = createRepo(git, config)
+  const handlers = createHandlers({ ctx, git, repo, store })
+  const route = createRoute({ handlers, logger: ctx.logger })
+
+  /**
+   * Register the route on the preferred carrier, exactly once.
+   *
+   * The guard is load-bearing, not defensive: `connection` may already be
+   * present when this plugin loads, in which case `ctx.inject` fires its
+   * callback immediately *as well as* the direct attempt below running — and
+   * `connection.fetch.register` rejects a second registration of the same path.
+   * Without the flag the plugin would either throw at load or, worse, race
+   * itself depending on service order.
+   *
+   * `connection.fetch` is the only acceptable carrier. An exact `webServer`
+   * route on the same path resolves *before* the harness's `/api` prefix route,
+   * which is where the Host/Origin fence and the browser-cookie check live — so
+   * using one would turn this into an unauthenticated git endpoint reachable by
+   * any page that can guess the path.
+   */
+  let registered = false
+  const install = (scope) => {
+    if (registered) return
+    const connection = scope.get('connection', false)
+    if (connection?.fetch?.register === undefined) return
+    // Own the lifetime explicitly rather than relying on the service proxy's
+    // call-site binding: the disposer is the registration's, so unloading the
+    // plugin always unregisters the route. Assign `registered` only after the
+    // effect has actually run, so a throw here leaves the plugin retryable.
+    scope.effect(() => connection.fetch.register(route), 'dsh-gitbar-lite: rpc route')
+    registered = true
+  }
+
+  install(ctx)
+  // Services load in no guaranteed order, so wait for `connection` the public
+  // way. It fires when the service arrives and stays silent if it never does.
+  ctx.inject(['connection'], (scope) => install(scope))
+}
+
+/**
+ * Internals exposed for the test suite.
+ *
+ * The suite drives real registrations against a fake context rather than
+ * re-implementing the plugin, so it needs the same factories `apply` uses.
+ */
+export const internals = {
+  readConfig,
+  DEFAULTS,
+  createGit,
+  createRepo,
+  createStore,
+  createHandlers,
+  createRoute,
+}