synabun 2.0.0 → 2.0.5

package/neural-interface/lib/editor-config.js

@@ -0,0 +1,149 @@
+// ── The code editor's preferences (DATA_HOME/data/editor-config.json) ──
+// Word wrap, font size, indentation and the AI autocomplete settings of the
+// File Explorer's editor. The defaults and the normaliser are the client's own
+// (public/shared/editor/editor-prefs.js): one definition, so the file on disk
+// and the page can never disagree about what a valid configuration is. Unknown
+// keys are dropped and out-of-range values clamped on the way in and on the
+// way out.
+//
+// The endpoint API key of AI autocomplete is not kept here: it is
+// SYNABUN_EDITOR_AI_KEY in the environment, and only whether one is set
+// (`hasEndpointKey`) ever reaches the page.
+
+import { Router } from 'express';
+import { mkdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { replaceFileAtomic } from './confined-fs.js';
+import { defaultEditorConfig, mergeEditorConfig, normalizeEditorConfig } from '../public/shared/editor/editor-prefs.js';
+
+export { defaultEditorConfig, normalizeEditorConfig };
+export const EDITOR_CONFIG_SYNC_TYPE = 'editor:config-changed';
+/** What these routes add to the editor (GET /api/editor/capabilities). */
+export const EDITOR_CONFIG_CAPABILITIES = Object.freeze(['config']);
+
+/**
+ * The stored configuration. Read again when the file's modification time changes; written atomically.
+ * @param {{ path: string, log?: (tag: string, message: string) => void }} o
+ */
+export function createEditorConfigStore({ path, log = () => {} } = {}) {
+  if (!path) throw new Error('createEditorConfigStore requires path');
+  let cached = null; // { mtimeMs, config }
+
+  const mtime = () => { try { return statSync(path).mtimeMs; } catch { return 0; } };
+
+  /** The configuration in effect: the file's, normalised, or the defaults when there is no (readable) file. */
+  function read() {
+    const m = mtime();
+    if (cached && cached.mtimeMs === m) return cached.config;
+    let config = defaultEditorConfig();
+    if (m) {
+      try { config = normalizeEditorConfig(JSON.parse(readFileSync(path, 'utf8'))); }
+      catch (error) { log('editor-config:unreadable', error?.message || String(error)); }
+    }
+    cached = { mtimeMs: m, config };
+    return config;
+  }
+
+  /**
+   * Apply a partial change and save.
+   * @returns {{ config: object, changed: boolean }}
+   */
+  function update(partial) {
+    const current = read();
+    const config = mergeEditorConfig(current, partial);
+    const changed = JSON.stringify(config) !== JSON.stringify(current);
+    if (changed) {
+      mkdirSync(dirname(path), { recursive: true });
+      replaceFileAtomic(path, `${JSON.stringify(config, null, 2)}\n`);
+      cached = { mtimeMs: mtime(), config };
+    }
+    return { config, changed };
+  }
+
+  return { read, update, path };
+}
+
+export const ENDPOINT_KEY_NAME = 'SYNABUN_EDITOR_AI_KEY';
+// A bearer token as providers issue them. Nothing that could start a new line or a comment in a .env file.
+const ENDPOINT_KEY_FORMAT = /^[A-Za-z0-9._~+/=:@-]{1,500}$/;
+
+/**
+ * The API key of AI autocomplete's endpoint: SYNABUN_EDITOR_AI_KEY in the data home's .env, beside the other
+ * secrets, and in the environment of the running server. Written the way the TypeSafe key is (read the file,
+ * change one name, write the file).
+ * @param {object} deps
+ * @param {string} deps.envPath the .env file
+ * @param {(path: string) => object} deps.parseEnvFile server.js's reader
+ * @param {(path: string, vars: object) => void} deps.writeEnvFile server.js's writer
+ * @param {object} [deps.env] the running environment (process.env)
+ */
+export function createEndpointKeyStore({ envPath, parseEnvFile, writeEnvFile, env = process.env } = {}) {
+  if (!envPath || typeof parseEnvFile !== 'function' || typeof writeEnvFile !== 'function') {
+    throw new Error('createEndpointKeyStore requires envPath, parseEnvFile and writeEnvFile');
+  }
+  const get = () => String(env[ENDPOINT_KEY_NAME] || '').trim();
+  return {
+    get,
+    has: () => !!get(),
+    /** Store a key, or remove it with ''. Throws on a value that is not a key. */
+    set(value) {
+      if (typeof value !== 'string') throw new Error('The endpoint key must be text');
+      const key = value.trim();
+      if (key && !ENDPOINT_KEY_FORMAT.test(key)) throw new Error('The endpoint key has an unexpected format');
+      const vars = parseEnvFile(envPath);
+      if (key) { vars[ENDPOINT_KEY_NAME] = key; env[ENDPOINT_KEY_NAME] = key; }
+      else { delete vars[ENDPOINT_KEY_NAME]; delete env[ENDPOINT_KEY_NAME]; }
+      writeEnvFile(envPath, vars);
+      return !!key;
+    },
+  };
+}
+
+/**
+ * GET /  → { ok, config, hasEndpointKey }
+ * PUT /  (a partial configuration) → the same, after the change; other windows are told when it changed anything.
+ *        `endpointKey` in the body stores the endpoint's API key ('' removes it); it is never part of an answer.
+ * Mounted at /api/editor/config. The owner's only: `guard` refuses everybody else on the router itself.
+ * @param {object} deps
+ * @param {{ read: () => object, update: (partial: object) => { config: object, changed: boolean } }} deps.store
+ * @param {(message: object) => void} [deps.broadcastSync]
+ * @param {() => boolean} [deps.hasEndpointKey]
+ * @param {(key: string) => void} [deps.setEndpointKey] stores or removes the key; without it a key cannot be saved
+ * @param {(req: object, res: object, next: () => void) => void} [deps.guard] who may use these routes
+ *   (lib/http-guards.js ownerRouteGuard); without one, anybody who reaches them
+ */
+export function createEditorConfigRouter({ store, broadcastSync = () => {}, hasEndpointKey = () => false, setEndpointKey = null, guard = null } = {}) {
+  if (!store) throw new Error('createEditorConfigRouter requires a store');
+  const router = Router();
+  if (typeof guard === 'function') router.use(guard);
+  const view = (config) => ({ ok: true, config, hasEndpointKey: !!hasEndpointKey() });
+
+  router.get('/', (req, res) => {
+    try { res.json(view(store.read())); }
+    catch (error) { res.status(500).json({ ok: false, error: error.message }); }
+  });
+
+  router.put('/', (req, res) => {
+    if (!req.body || typeof req.body !== 'object' || Array.isArray(req.body)) {
+      return res.status(400).json({ ok: false, error: 'The body must be an object holding the preferences to change' });
+    }
+    const { endpointKey, ...partial } = req.body;
+    try {
+      let keyChanged = false;
+      if (endpointKey !== undefined) {
+        if (typeof setEndpointKey !== 'function') return res.status(400).json({ ok: false, error: 'Key storage is not wired in this server' });
+        const had = !!hasEndpointKey();
+        try { setEndpointKey(endpointKey); }
+        catch (error) { return res.status(400).json({ ok: false, error: error.message }); }
+        keyChanged = had !== !!hasEndpointKey();
+      }
+      const { config, changed } = store.update(partial);
+      if (changed || keyChanged) broadcastSync({ type: EDITOR_CONFIG_SYNC_TYPE, config, hasEndpointKey: !!hasEndpointKey() });
+      res.json(view(config));
+    } catch (error) {
+      res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  return router;
+}

package/neural-interface/lib/editor-files-api.js

@@ -0,0 +1,268 @@
+// ── The code editor's file routes ──
+// Reading, writing, creating and removing the files the File Explorer's editor
+// works on, plus what the editor asks the server before it uses anything newer
+// than read and write (GET /api/editor/capabilities).
+//
+// A path is allowed when it is inside one of the roots the server registers:
+// the data home, the registered projects, the plan folders, and one single
+// file, the user's OpenCode configuration. "Inside" is judged as written first
+// (403 "Path outside registered project roots"), then as the filesystem
+// resolves it: every read and write goes through lib/confined-fs.js, so a link
+// that leads out of its root is refused instead of followed.
+//
+// A read reports the file's version ({ mtimeMs, size }); a write that sends it
+// back as `expect` is refused with 409 when the file changed in between. A
+// write of a file that is expected not to be there (`expectAbsent`, with
+// `create`) is refused the same way when it is: it is created exclusively.
+//
+// Who may ask is each route's own business: the `guard` it is handed (server.js:
+// lib/http-guards.js ownerRouteGuard) refuses invite guests, a Host that is not
+// this server's and a write from another site's page, on the route itself.
+// Dependencies are injected: the router is tested without server.js.
+
+import { Router } from 'express';
+import { lstatSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { PathConfineError, realPathOf } from './path-confine.js';
+import { MAX_FILE_BYTES, canonicalInside, makeConfinedDir, readConfinedFile, removeConfinedEntry, writeConfinedFile } from './confined-fs.js';
+
+/** What these routes add to the editor: the version check on save, and POST /api/file-stat. */
+export const EDITOR_FILE_CAPABILITIES = Object.freeze(['file-version', 'file-stat']);
+export const MAX_STAT_PATHS = 50;
+/**
+ * The namespace of the UI blob store (lib/ui-blob-store.js, /api/ui-blobs) that holds the editor's copies of
+ * unsaved buffers. server.js allows it and keeps it for the owner; it announces `backups` when it does.
+ */
+export const EDITOR_BACKUP_NAMESPACE = 'editor-backups';
+export const EDITOR_BACKUP_CAPABILITIES = Object.freeze(['backups']);
+
+const OUTSIDE_ROOTS = 'Path outside registered project roots';
+const BINARY_PROBE_BYTES = 8192;
+const UTF8_BOM = [0xEF, 0xBB, 0xBF];
+
+const outsideRoots = () => new PathConfineError(403, OUTSIDE_ROOTS);
+const slashes = (path) => path.replace(/\\/g, '/');
+const versionOf = (st) => ({ mtimeMs: st.mtimeMs, size: st.size });
+
+/**
+ * The roots a path is inside, as written.
+ * @param {string} path any path a request sent
+ * @param {{ dirs?: string[], files?: string[] }} roots folders, and single files allowed by their exact path
+ * @returns {{ target: string, matches: { base: string, path: string, isBase: boolean }[] }} `target` is the path
+ *   resolved; each match is the folder to confine to and the path to use inside it. A single file is confined to
+ *   the folder it really is in: it is allowed by name, wherever a link takes it.
+ */
+export function matchFileRoots(path, roots = {}) {
+  const target = resolve(String(path));
+  const matches = [];
+  for (const dir of roots.dirs || []) {
+    const base = resolve(dir);
+    if (target === base) matches.push({ base, path: target, isBase: true });
+    else if (target.startsWith(base.endsWith(sep) ? base : base + sep)) matches.push({ base, path: target, isBase: false });
+  }
+  for (const file of roots.files || []) {
+    if (target !== resolve(file)) continue;
+    try {
+      const real = realPathOf(target);
+      matches.push({ base: dirname(real), path: real, isBase: false });
+    } catch { /* a link that cannot be resolved: not a file to open */ }
+  }
+  return { target, matches };
+}
+
+/**
+ * Run `use(match)` on the first root that really holds the path. A root the path leaves through a link is passed
+ * over; when every root is, the path is refused (403), as a path outside every root is.
+ * @param {string} path any path a request sent
+ * @param {{ dirs?: string[], files?: string[] }} roots
+ * @param {(match: { base: string, path: string, isBase: boolean, target: string }) => any} use
+ */
+export function useFileRoot(path, roots, use) {
+  const { target, matches } = matchFileRoots(path, roots);
+  if (!matches.length) throw outsideRoots();
+  let refused = null;
+  for (const match of matches) {
+    try { return use({ ...match, target }); }
+    catch (error) {
+      if (!(error instanceof PathConfineError) || error.status !== 403) throw error;
+      refused = error;
+    }
+  }
+  throw refused;
+}
+
+/**
+ * @param {object} deps
+ * @param {() => { dirs: string[], files: string[] }} deps.fileRoots the roots validateProjectPath() allows
+ * @param {() => string[]} [deps.capabilities] what other editor routes of this server add (GET /api/editor/capabilities)
+ * @param {number} [deps.maxBytes] the largest file that is read
+ * @param {(req: object, res: object, next: () => void) => void} [deps.guard] who may use these routes; without
+ *   one, anybody who reaches them
+ */
+export function createEditorFilesRouter({ fileRoots, capabilities = () => [], maxBytes = MAX_FILE_BYTES, guard = null } = {}) {
+  if (typeof fileRoots !== 'function') throw new Error('createEditorFilesRouter requires fileRoots');
+  const router = Router();
+  // On each route, not on the router: it is mounted at the root, where a check of its own would run for the
+  // paths of every route registered after it.
+  const owner = typeof guard === 'function' ? guard : (req, res, next) => next();
+
+  const fail = (res, error) => {
+    if (error instanceof PathConfineError) return res.status(error.status).json({ error: error.message });
+    return res.status(500).json({ error: error?.message || String(error) });
+  };
+
+  const inRoots = (path, use) => useFileRoot(path, fileRoots(), use);
+
+  // The canonical path of a match, and what is there (null when nothing is).
+  function locate(match) {
+    const real = canonicalInside(match.base, match.path, { allowBase: true });
+    let st = null;
+    try { st = statSync(real); } catch { st = null; }
+    return { real, st };
+  }
+
+  // GET /api/file-content — read one file for the editor
+  router.get('/api/file-content', owner, (req, res) => {
+    try {
+      const filePath = req.query.path;
+      if (!filePath || typeof filePath !== 'string') return res.status(400).json({ error: 'Missing path parameter' });
+      const found = inRoots(filePath, (match) => {
+        let { real, st } = locate(match);
+        if (!st || !st.isFile()) return { status: 400, body: { error: 'Not a valid file' } };
+        if (st.size > maxBytes) {
+          return { status: 413, body: { error: `File too large (the editor opens up to ${Math.round(maxBytes / (1024 * 1024))} MB)`, maxBytes } };
+        }
+        let buf = readConfinedFile(match.base, real, { maxBytes });
+        // The version must be the one of the bytes that were read: a write in between is read again.
+        let after = statSync(real);
+        if (after.mtimeMs !== st.mtimeMs || after.size !== st.size) {
+          buf = readConfinedFile(match.base, real, { maxBytes });
+          after = statSync(real);
+        }
+        st = after;
+        const probe = Math.min(BINARY_PROBE_BYTES, buf.length);
+        for (let i = 0; i < probe; i++) {
+          if (buf[i] === 0x00) return { status: 415, body: { error: 'Binary file', reason: 'binary' } };
+        }
+        const bom = buf.length >= 3 && UTF8_BOM.every((byte, i) => buf[i] === byte);
+        let content;
+        try { content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bom ? buf.subarray(3) : buf); }
+        catch { return { status: 415, body: { error: 'File is not valid UTF-8 text', reason: 'encoding' } }; }
+        return {
+          status: 200,
+          body: { ok: true, content, path: slashes(match.target), name: basename(match.target), size: st.size, version: versionOf(st), bom },
+        };
+      });
+      res.status(found.status).json(found.body);
+    } catch (error) { fail(res, error); }
+  });
+
+  // POST /api/file-content — write a file (an existing one, or a new one with `create: true`)
+  //   expect: { mtimeMs, size }   the version that was read: 409 { code: 'changed', current } when the file differs
+  //   expectAbsent: true          with `create`: the file is expected not to be there (the editor saving a tab whose
+  //                               file was deleted): 409 { code: 'changed', current } when it is
+  //   force: true                 write whatever is there ("Overwrite")
+  router.post('/api/file-content', owner, (req, res) => {
+    try {
+      const { path: filePath, content, create, expect, expectAbsent, force } = req.body || {};
+      if (!filePath || typeof filePath !== 'string' || typeof content !== 'string') {
+        return res.status(400).json({ error: 'Missing path or content' });
+      }
+      const checked = expect !== undefined && expect !== null;
+      if (checked && !(Number.isFinite(expect?.mtimeMs) && Number.isFinite(expect?.size))) {
+        return res.status(400).json({ error: 'expect must be the version a read returned: { mtimeMs, size }' });
+      }
+      const absent = expectAbsent === true && !force;
+      const changed = (st) => ({ status: 409, body: { error: 'The file changed on disk', code: 'changed', current: versionOf(st) } });
+      const done = inRoots(filePath, (match) => {
+        const { real, st } = locate(match);
+        if (st && !st.isFile()) return { status: 400, body: { error: create ? 'Not a valid file' : 'File does not exist' } };
+        if (!st && !create) return { status: 400, body: { error: 'File does not exist' } };
+        if (st && absent) return changed(st);
+        if (st && checked && !force && (st.mtimeMs !== expect.mtimeMs || st.size !== expect.size)) return changed(st);
+        // In place: an existing file keeps its mode and its inode, a link to it stays a link. A file that is
+        // expected to be absent is created exclusively: one that appeared since the look above is not written over.
+        try {
+          writeConfinedFile(match.base, real, content, { exclusive: absent });
+        } catch (error) {
+          if (!(absent && error instanceof PathConfineError && error.status === 409)) throw error;
+          let now = null;
+          try { now = statSync(real); } catch { now = null; }
+          if (now) return changed(now);
+          throw error;
+        }
+        return { status: 200, body: { ok: true, version: versionOf(statSync(real)) } };
+      });
+      res.status(done.status).json(done.body);
+    } catch (error) { fail(res, error); }
+  });
+
+  // POST /api/file-mkdir — create a directory
+  router.post('/api/file-mkdir', owner, (req, res) => {
+    try {
+      const { path: dirPath } = req.body || {};
+      if (!dirPath || typeof dirPath !== 'string') return res.status(400).json({ error: 'Missing path' });
+      inRoots(dirPath, (match) => {
+        if (match.isBase) mkdirSync(match.path, { recursive: true });
+        else makeConfinedDir(match.base, match.path);
+      });
+      res.json({ ok: true });
+    } catch (error) { fail(res, error); }
+  });
+
+  // DELETE /api/file-content — delete a file or an empty directory
+  router.delete('/api/file-content', owner, (req, res) => {
+    try {
+      const filePath = req.query.path;
+      if (!filePath || typeof filePath !== 'string') return res.status(400).json({ error: 'Missing path parameter' });
+      const done = inRoots(filePath, (match) => {
+        if (match.isBase) return { status: 403, body: { error: 'A registered folder is not deleted from here' } };
+        // The folder that holds the entry must really be in the root; the entry itself is removed as it is
+        // (a link is unlinked, never followed).
+        const parent = canonicalInside(match.base, dirname(match.path), { allowBase: true });
+        const entry = join(parent, basename(match.path));
+        let st;
+        try { st = lstatSync(entry); } catch { return { status: 404, body: { error: 'Path does not exist' } }; }
+        if (st.isDirectory()) {
+          if (readdirSync(entry).length > 0) return { status: 400, body: { error: 'Directory is not empty' } };
+          rmdirSync(entry);
+        } else {
+          removeConfinedEntry(match.base, entry);
+        }
+        return { status: 200, body: { ok: true } };
+      });
+      res.status(done.status).json(done.body);
+    } catch (error) { fail(res, error); }
+  });
+
+  // POST /api/file-stat — the versions of up to 50 files, to see which changed on disk
+  router.post('/api/file-stat', owner, (req, res) => {
+    try {
+      const paths = req.body?.paths;
+      if (!Array.isArray(paths) || paths.length > MAX_STAT_PATHS || paths.some((p) => typeof p !== 'string' || !p)) {
+        return res.status(400).json({ error: `paths must be an array of at most ${MAX_STAT_PATHS} file paths` });
+      }
+      const files = {};
+      for (const path of paths) {
+        let entry = { exists: false };
+        try {
+          entry = inRoots(path, (match) => {
+            const { st } = locate(match);
+            return st && st.isFile() ? { exists: true, version: versionOf(st) } : { exists: false };
+          });
+        } catch { /* outside the roots, or out of one through a link: not a file the editor has */ }
+        files[path] = entry;
+      }
+      res.json({ ok: true, files });
+    } catch (error) { fail(res, error); }
+  });
+
+  // GET /api/editor/capabilities — what this server offers the editor beyond reading and writing
+  router.get('/api/editor/capabilities', owner, (req, res) => {
+    let extra = [];
+    try { extra = (capabilities() || []).filter((name) => typeof name === 'string'); } catch { extra = []; }
+    res.json({ ok: true, capabilities: [...new Set([...EDITOR_FILE_CAPABILITIES, ...extra])] });
+  });
+
+  return router;
+}

package/neural-interface/lib/editor-git-api.js

@@ -0,0 +1,134 @@
+// ── The code editor's view of git: the committed version of a file ──
+// GET /api/file-head?path= answers with the text of a file as the last commit
+// has it (`git show HEAD:<path>`). The editor marks the lines that differ from
+// it and shows the two against each other.
+//
+// The path is checked like every other file path of the editor (inside a
+// registered root as written, and as the filesystem resolves it). git is run
+// with an argument array, never through a shell: a file name is a name,
+// whatever characters it holds. Only commands that read are run here:
+// `rev-parse --show-toplevel` to find the repository, `show` for the text.
+// Nothing in the repository, its index or its working tree is changed, and
+// nothing the repository's own configuration names is started: every call of
+// runGit() is a read as lib/git-read.js runs one (no file system monitor
+// program, no hook, no external diff or textconv, no fetch).
+//
+// A file git does not know, a folder that is not a repository and a machine
+// without git all answer `tracked: false`: for the editor that is "no markers",
+// not an error. Dependencies are injected: the router is tested without server.js.
+
+import { Router } from 'express';
+import { execFile } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, sep } from 'node:path';
+import { PathConfineError } from './path-confine.js';
+import { MAX_FILE_BYTES, canonicalInside } from './confined-fs.js';
+import { useFileRoot } from './editor-files-api.js';
+import { gitRead } from './git-read.js';
+
+/** What this route adds to the editor (GET /api/editor/capabilities). */
+export const EDITOR_GIT_CAPABILITIES = Object.freeze(['git-head']);
+export const GIT_TIMEOUT_MS = 5000;
+
+const UTF8_BOM = [0xEF, 0xBB, 0xBF];
+const BINARY_PROBE_BYTES = 8192;
+// Variables that would point git at another repository than the one the file is in.
+const REDIRECTING = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_NAMESPACE', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_CEILING_DIRECTORIES'];
+
+/**
+ * Run git for a read and collect what it prints. Never throws. The arguments are the command's own: what keeps a
+ * read from starting a program of the repository's is added here (lib/git-read.js).
+ * @param {string[]} args the command first
+ * @param {{ cwd: string, maxBuffer: number, timeoutMs?: number, binary?: string, env?: object }} o
+ * @returns {Promise<{ ok: boolean, stdout: Buffer, tooLarge: boolean }>} `tooLarge`: it printed more than `maxBuffer` bytes
+ */
+export function runGit(args, { cwd, maxBuffer, timeoutMs = GIT_TIMEOUT_MS, binary = 'git', env = process.env } = {}) {
+  const clean = { ...env };
+  for (const name of REDIRECTING) delete clean[name];
+  const failed = { ok: false, stdout: Buffer.alloc(0), tooLarge: false };
+  return gitRead(cwd, args, { binary, env: clean }).then((read) => new Promise((done) => {
+    try {
+      execFile(binary, read.args, { cwd, maxBuffer, timeout: timeoutMs, encoding: 'buffer', windowsHide: true, env: read.env, shell: false }, (error, stdout) => {
+        const out = Buffer.isBuffer(stdout) ? stdout : Buffer.alloc(0);
+        if (!error) done({ ok: true, stdout: out, tooLarge: false });
+        else done({ ok: false, stdout: out, tooLarge: error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' });
+      });
+    } catch {
+      done(failed);
+    }
+  })).catch(() => failed);
+}
+
+/**
+ * The committed text of one file.
+ * @param {string} real the file's canonical path (it may be gone from the disk)
+ * @param {{ maxBytes: number, git: (args: string[], o: object) => Promise<object> }} o
+ * @returns {Promise<{ tracked: boolean, content?: string, binary?: boolean, tooLarge?: boolean }>}
+ */
+export async function readHeadVersion(real, { maxBytes, git }) {
+  const folder = dirname(real);
+  const top = await git(['rev-parse', '--show-toplevel'], { cwd: folder, maxBuffer: 64 * 1024 });
+  if (!top.ok) return { tracked: false };
+  const root = top.stdout.toString('utf8').replace(/\r?\n$/, '');
+  if (!root || !isAbsolute(root)) return { tracked: false };
+  // The file's name inside the repository, as git writes it. Both paths are canonical: git prints its top level
+  // resolved, and `real` is.
+  const inside = relative(root, real);
+  if (!inside || inside.startsWith('..') || isAbsolute(inside)) return { tracked: false };
+  const name = sep === '/' ? inside : inside.split(sep).join('/');
+  const shown = await git(['show', `HEAD:${name}`], { cwd: root, maxBuffer: maxBytes });
+  if (shown.tooLarge) return { tracked: true, tooLarge: true };
+  if (!shown.ok) return { tracked: false };   // not in the last commit, or no commit yet
+  const buf = shown.stdout;
+  const probe = Math.min(BINARY_PROBE_BYTES, buf.length);
+  for (let i = 0; i < probe; i++) if (buf[i] === 0x00) return { tracked: true, binary: true };
+  const bom = buf.length >= 3 && UTF8_BOM.every((byte, i) => buf[i] === byte);
+  try { return { tracked: true, content: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bom ? buf.subarray(3) : buf) }; }
+  catch { return { tracked: true, binary: true }; }
+}
+
+/**
+ * GET /api/file-head?path=
+ *   200 { ok, tracked: false }                 git does not know the file, the folder is no repository, or there is no git
+ *   200 { ok, tracked: true, content }         the file as HEAD has it: its own line endings, a byte-order mark taken off
+ *   200 { ok, tracked: true, binary: true }    HEAD holds something that is not UTF-8 text
+ *   400 no path, or a folder · 403 outside the registered roots, or out of one through a link · 413 larger than `maxBytes`
+ * @param {object} deps
+ * @param {() => { dirs: string[], files: string[] }} deps.fileRoots the roots the editor's file routes allow
+ * @param {number} [deps.maxBytes]
+ * @param {(args: string[], o: object) => Promise<object>} [deps.git] runGit, or a stand-in
+ * @param {(req: object, res: object, next: () => void) => void} [deps.guard] who may use the route (the files
+ *   router's own: lib/http-guards.js ownerRouteGuard); on the route itself, as the router is mounted at the root
+ */
+export function createEditorGitRouter({ fileRoots, maxBytes = MAX_FILE_BYTES, git = runGit, guard = null } = {}) {
+  if (typeof fileRoots !== 'function') throw new Error('createEditorGitRouter requires fileRoots');
+  const router = Router();
+  const owner = typeof guard === 'function' ? guard : (req, res, next) => next();
+  const tooLarge = () => ({ status: 413, body: { error: `File too large (the editor opens up to ${Math.max(1, Math.round(maxBytes / (1024 * 1024)))} MB)`, maxBytes } });
+
+  router.get('/api/file-head', owner, async (req, res) => {
+    try {
+      const filePath = req.query.path;
+      if (!filePath || typeof filePath !== 'string') return res.status(400).json({ error: 'Missing path parameter' });
+      const found = useFileRoot(filePath, fileRoots(), (match) => {
+        const real = canonicalInside(match.base, match.path, { allowBase: true });
+        let st = null;
+        try { st = statSync(real); } catch { st = null; }
+        return { real, st };
+      });
+      // A file that is gone from the disk may still be in the last commit; a folder never is a file.
+      if (found.st && !found.st.isFile()) return res.status(400).json({ error: 'Not a valid file' });
+      if (found.st && found.st.size > maxBytes) { const refusal = tooLarge(); return res.status(refusal.status).json(refusal.body); }
+      const head = await readHeadVersion(found.real, { maxBytes, git });
+      if (head.tooLarge) { const refusal = tooLarge(); return res.status(refusal.status).json(refusal.body); }
+      if (!head.tracked) return res.json({ ok: true, tracked: false });
+      if (head.binary) return res.json({ ok: true, tracked: true, binary: true });
+      res.json({ ok: true, tracked: true, content: head.content });
+    } catch (error) {
+      if (error instanceof PathConfineError) return res.status(error.status).json({ error: error.message });
+      res.status(500).json({ error: error?.message || String(error) });
+    }
+  });
+
+  return router;
+}