tosijs-ui 1.16.24 → 1.16.25

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 1.16.25
+
+### Dev server
+
+- **`editableData`: folders an editor on the dev page may save to** (#3365). A level or
+  scene editor running on a dev-server page can list, read and save the project's data files
+  through `/__docstore/data`, behind the same gate as source: this machine, an edit session
+  over the tunnel, or the LAN under `trustLan`. Share links stay read-only.
+  `editableData: ['static/levels']`, or `{ dirs, extensions, commit }`. Only data formats may
+  be allowed (`.json` by default; also `.jsonc` `.json5` `.ndjson` `.txt` `.csv` `.tsv`
+  `.yaml` `.yml` `.toml`), so nothing saved there runs or renders. Dot-files and symlinks are
+  never written, nor are common configuration names (`package.json`, `tsconfig.json`,
+  `firebase.json`, `*.config.*`), though the folders you name are the real boundary. A `.json`
+  save must parse, and a save replaces the file whole. A folder outside the project, the
+  project itself, one in or around `.git` or `node_modules`, or one overlapping the build
+  output stops the server at launch. `tosijs-ui/site` exports the `EditableDataOptions` type
+  and the `DATA_EXTENSIONS` list.
+- **`commit: true` makes every save a version.** Each save is its own commit
+  (`data: save <file>`, naming who saved it), and other staged work is left alone. The
+  repository's hooks run, and each git step gets 20 seconds. Nothing is committed while the
+  repository is mid-rebase, mid-merge, cherry-picking, reverting, bisecting or on a detached
+  HEAD. `?history=<file>` lists a file's latest 100 versions and `?file=<file>&at=<commit>` reads
+  one back. A save that wrote the file but did not commit answers with `commitError` instead of
+  reporting a clean save. Each committed save waits for git, so it suits an explicit Save, not
+  autosave.
+- **`tosijs-ui/doc-system/data-client`** wraps the endpoint for an editor: `listData`,
+  `readData` (text, or `{ json: true }`, or `{ at }`), `saveData` (a string as is, anything
+  else as formatted JSON) and `dataHistory`. A refusal rejects with a `DataStoreError` carrying
+  the status, and so does a page answering for the endpoint (a static host's catch-all), so
+  `listData()` tells an editor whether to offer saving.
+- **`trustLan` can name your network**, so a committed setting trusts nobody on anyone else's:
+  `trustLan: '192.168.1.0/24'` or a list, IPv4 or IPv6. Only private addresses inside it are
+  trusted. **`TOSIJS_TRUST_LAN`** sets it for one run and wins over the config either way: `1`,
+  a network, or `0` to turn a committed setting off. A network that cannot be parsed stops the
+  server at launch, and the launch warning names who is trusted and where the setting came from.
+  A refused device outside the named networks is told so in the log, and the messages readers
+  see when the LAN is refused now suggest these forms rather than `trustLan: true`.
+- **The SPA fallback shows the page the URL names.** Was: a path with no file of its own got
+  the root page, which then asked for its assets relative to that path, got 404s and never
+  hydrated; with `home` set, a reader saw the home doc. Now the dev server serves the root page
+  with its relative URLs made root-relative (in-page `#` links still stay on the page), and
+  hydration adopts a pre-rendered article only when it is the doc being shown. Generated pages
+  stamp the article with `data-doc` for that. The asset fix is the dev server's; a static host's
+  own catch-all rewrite is unchanged.
+
 ## 1.16.24
 
 `dist/iife.js` grows by about 0.2 kB gzip.

package/dist/doc-browser.js

@@ -111,6 +111,7 @@ import { tosiLocalized } from './localize.js';
 import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
+import { LAN_REFUSAL_ADVICE } from './live-example/source-access.js';
 /*
 Does this doc contain a REAL ` ```test ` block, as opposed to mentioning one?
 
@@ -954,8 +955,18 @@ export function createDocBrowser(options) {
     };
     let adoptInitialContent = contentElement !== undefined && !memoryRouting;
     const showDoc = (doc) => {
-        if (adoptInitialContent) {
-            adoptInitialContent = false; // leave the pre-rendered HTML untouched
+        /*
+        Adopt the pre-render only if it IS this doc. The dev server's SPA fallback serves the root
+        page for a path with no file of its own, so `/guide/` can arrive holding the home page's
+        article (#3346). The generator stamps `data-doc`; a page without it predates the stamp
+        and is adopted as before.
+        */
+        const prerendered = contentElement?.dataset.doc;
+        const adopt = adoptInitialContent &&
+            (prerendered === undefined || prerendered === doc.filename);
+        adoptInitialContent = false;
+        if (adopt) {
+            // leave the pre-rendered HTML untouched
         }
         else {
             // Pass the doc's build-time tjs bakes so this client-rendered page embeds the
@@ -1291,7 +1302,7 @@ export function createDocBrowser(options) {
             window.alert('This workspace needs an invite link before it can save.\n\n' +
                 'Run `tosijs-tunnel --link` on the machine hosting it, open the link once, ' +
                 'then try again. Your edit is still here.\n\n' +
-                'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.');
+                LAN_REFUSAL_ADVICE);
         }
         else {
             // Genuinely no write endpoint (a deployed static site) — hand the file back.
@@ -1306,7 +1317,7 @@ export function createDocBrowser(options) {
             window.alert(sourceUnauthorized
                 ? 'This workspace needs an invite link before you can edit.\n\n' +
                     'Run `tosijs-tunnel --link` on the machine hosting it and open the link once.\n\n' +
-                    'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.'
+                    LAN_REFUSAL_ADVICE
                 : `Could not load source for ${doc.path}`);
             return;
         }

package/dist/doc-system/data-client.d.ts

@@ -0,0 +1,35 @@
+export declare class DataStoreError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/** Every editable file, project-relative, newest first. */
+export declare function listData(): Promise<{
+    files: {
+        file: string;
+        size: number;
+        modified: string;
+    }[];
+}>;
+/** A file's text, or parsed JSON with `json: true`; `at` reads it as of a commit. */
+export declare function readData(file: string, options: {
+    at?: string;
+    json: true;
+}): Promise<any>;
+export declare function readData(file: string, options?: {
+    at?: string;
+    json?: false;
+}): Promise<string>;
+/** Save a file: a string as it is, anything else as formatted JSON. */
+export declare function saveData(file: string, content: unknown): Promise<{
+    ok: true;
+    file: string;
+    commit?: string | null;
+    commitError?: string;
+}>;
+/** A file's committed versions, newest first. */
+export declare function dataHistory(file: string): Promise<{
+    commit: string;
+    date: string;
+    author: string;
+    subject: string;
+}[]>;

package/dist/doc-system/data-client.js

@@ -0,0 +1,105 @@
+/*{ "parent": "Documentation System", "order": 85 }*/
+/*#
+# data client
+
+For an editor running on a dev-server page (a level editor, a scene editor) to open and save
+the project's data files through `/__docstore/data`. Turn it on by naming the folders in the
+site config; [`editableData`](/doc-site-system/) in the doc-site system reference has the
+rules.
+
+```typescript
+// tosijs-site.config.ts
+editableData: { dirs: ['static/levels'], commit: true }
+```
+
+```typescript
+import { listData, readData, saveData, dataHistory } from 'tosijs-ui/doc-system/data-client'
+
+const { files } = await listData()
+const level = await readData('static/levels/ocean.json', { json: true })
+level.spawn = [0, 2, 0]
+const { commit } = await saveData('static/levels/ocean.json', level)
+const versions = await dataHistory('static/levels/ocean.json')
+if (versions.length > 1) {
+  const before = await readData('static/levels/ocean.json', { at: versions[1].commit })
+}
+```
+
+`saveData` writes an object as JSON (two-space indent, trailing newline) and a string as it
+is. With `commit: true` in the config each save is its own commit, and `commit` in the result
+is its hash (`null` when the save changed nothing). A save that wrote but could not commit
+(a failing hook, or a repository mid-rebase) resolves with `commitError` set rather than
+rejecting, because the file was saved. Each committed save runs git and the repository's
+hooks before it answers, so it suits an explicit Save, not autosave.
+
+**Dev server only.** Everything else rejects with a `DataStoreError` whose `status` says why:
+`501` when the server has no `editableData`, `403` when this page may not edit files here or
+the file is not editable, `400` for content it refuses (JSON that does not parse). A response
+that is not the endpoint's (a deployed site's catch-all answering with a page) rejects too, so
+`listData()` is the probe for whether to offer saving at all.
+
+File names may use letters, digits, `-`, `_`, `.`, `/` and spaces. `dataHistory` returns the
+latest 100 versions.
+*/
+const ENDPOINT = '/__docstore/data';
+export class DataStoreError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'DataStoreError';
+    }
+}
+async function ask(query, init) {
+    const response = await fetch(`${ENDPOINT}${query}`, {
+        credentials: 'same-origin',
+        ...init,
+    });
+    /*
+    The endpoint answers JSON or the file's text, never a page. An HTML answer is something
+    else's: a static host's catch-all serving its index for every path.
+    */
+    const type = response.headers.get('content-type') ?? '';
+    if (response.ok && type.includes('text/html')) {
+        throw new DataStoreError(`${init?.method ?? 'GET'} ${ENDPOINT}${query}: answered with a page, not the data endpoint (no dev server here?)`, response.status);
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch {
+            // plain text
+        }
+        throw new DataStoreError(`${init?.method ?? 'GET'} ${ENDPOINT}${query}: ${response.status} ${message}`, response.status);
+    }
+    return response;
+}
+const q = (params) => '?' + new URLSearchParams(params).toString();
+/** Every editable file, project-relative, newest first. */
+export async function listData() {
+    return (await ask('?list')).json();
+}
+export async function readData(file, options = {}) {
+    const params = { file };
+    if (options.at)
+        params.at = options.at;
+    const text = await (await ask(q(params))).text();
+    return options.json ? JSON.parse(text) : text;
+}
+/** Save a file: a string as it is, anything else as formatted JSON. */
+export async function saveData(file, content) {
+    const text = typeof content === 'string'
+        ? content
+        : JSON.stringify(content, null, 2) + '\n';
+    return (await ask('', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file, content: text }),
+    })).json();
+}
+/** A file's committed versions, newest first. */
+export async function dataHistory(file) {
+    return (await (await ask(q({ history: file }))).json()).versions;
+}

package/dist/doc-system/site/data-store.d.ts

@@ -0,0 +1,71 @@
+/** Formats a data folder may hold. Text only: the endpoint takes and returns strings. */
+export declare const DATA_EXTENSIONS: readonly [".json", ".jsonc", ".json5", ".ndjson", ".txt", ".csv", ".tsv", ".yaml", ".yml", ".toml"];
+/** The largest save accepted, in bytes. A level is kilobytes; this stops a runaway client. */
+export declare const MAX_DATA_BYTES: number;
+export interface EditableDataOptions {
+    /** Folders, relative to the project root. */
+    dirs: string[];
+    /** Extensions to allow, from DATA_EXTENSIONS. Default `['.json']`. */
+    extensions?: string[];
+    /** Commit each save to git, so every save is a version. Default false. */
+    commit?: boolean;
+}
+export interface DataStore {
+    root: string;
+    /** Real paths of the folders, and the names they were configured as. */
+    dirs: {
+        real: string;
+        name: string;
+    }[];
+    extensions: string[];
+    commit: boolean;
+}
+/** The folder setting, checked and resolved, or null when the project has none. Throws. */
+export declare function resolveDataStore(setting: string[] | EditableDataOptions | undefined, root: string, 
+/** The site's build output, which every build deletes and rewrites. */
+outputDir?: string): DataStore | null;
+/**
+ * The absolute path a client's file name may be read or written at, or the reason it may not.
+ * `file` is project-relative (`static/levels/ocean.json`).
+ */
+export declare function resolveDataFile(store: DataStore, file: unknown): {
+    path: string;
+    rel: string;
+} | {
+    refused: string;
+};
+/** Why `content` may not be saved as `rel`, or null. JSON must parse: a half-edit is not a level. */
+export declare function dataContentProblem(rel: string, content: unknown): string | null;
+/** Write through a temporary file and a rename, so a reader never sees half a file. */
+export declare function writeDataFile(target: string, content: string): void;
+/** Every editable file in the named folders, project-relative, newest first. */
+export declare function listDataFiles(store: DataStore): {
+    file: string;
+    size: number;
+    modified: string;
+}[];
+/** Whether `root` is in a git work tree, for `commit: true` to be checked at launch. */
+export declare function isGitWorkTree(root: string): boolean;
+/**
+ * Save a file. With `commit` on, also commit it, alone, leaving other staged work as it was:
+ * `commit` is the hash, or null when the save changed nothing. A save that wrote the file but
+ * could not commit it resolves with `commitError`, because the file WAS saved. The repository's
+ * hooks run, as for any commit; a repository mid-rebase, mid-merge, bisecting or on a detached
+ * HEAD is not committed to, since that commit would land somewhere the developer did not choose.
+ */
+export declare function saveDataFile(store: DataStore, target: {
+    path: string;
+    rel: string;
+}, content: string, savedBy: string): Promise<{
+    commit?: string | null;
+    commitError?: string;
+}>;
+/** One file's committed versions, newest first. */
+export declare function dataHistory(store: DataStore, rel: string, limit?: number): Promise<{
+    commit: string;
+    date: string;
+    author: string;
+    subject: string;
+}[]>;
+/** A file as it was at `commit`, or null if the commit is not a hash or lacks the file. */
+export declare function readDataAt(store: DataStore, rel: string, commit: string): Promise<string | null>;

package/dist/doc-system/site/data-store.js

@@ -0,0 +1,352 @@
+/*
+WHICH files `editableData` may touch, and how a save becomes a version (#3365).
+
+`/__docstore/source` writes only scraped doc sources (#128), so an editor running on the dev
+page (a level editor, say) could not save the JSON it edits. This is the sibling for data: a
+list of folders the project names, behind the same gate (`sourceRequestAdmission`).
+
+An allow-list at every level, as #128 argues for source:
+
+- Folders: inside the project, never the project itself, never inside or containing `.git` or
+  `node_modules`. Resolved through symlinks, at launch.
+- Extensions: data formats only, from DATA_EXTENSIONS. Nothing a browser or a tool executes or
+  renders (`.js`, `.html`, `.svg`, `.md`, whose fences run as live examples). A config naming
+  anything else stops the server rather than being trimmed quietly.
+- Names: no dot-files and no names tools read as configuration (`package.json`,
+  `tsconfig.json`, `*.config.*`), so a folder that happens to hold one cannot be used to write it.
+- Paths: plain characters only, no `..`, and the real path (symlinks resolved) must still be
+  inside a named folder. An existing symlink is never written through.
+
+FAILS CLOSED: anything unexpected is a refusal with a reason, never a best effort.
+*/
+import * as fs from 'fs';
+import * as path from 'path';
+/** Formats a data folder may hold. Text only: the endpoint takes and returns strings. */
+export const DATA_EXTENSIONS = [
+    '.json',
+    '.jsonc',
+    '.json5',
+    '.ndjson',
+    '.txt',
+    '.csv',
+    '.tsv',
+    '.yaml',
+    '.yml',
+    '.toml',
+];
+/** The largest save accepted, in bytes. A level is kilobytes; this stops a runaway client. */
+export const MAX_DATA_BYTES = 16 * 1024 * 1024;
+/*
+Names tools read as configuration, some of which run commands. A backstop, not the boundary:
+no list of every tool's file can be complete, so the folders a project names are what keep
+writes away from configuration, and the docs say so.
+*/
+const CONFIG_NAMES = [
+    /^package(-lock)?\.json$/,
+    /^[tj]sconfig(\..*)?\.json$/,
+    /^bunfig\.toml$/,
+    /^deno\.jsonc?$/,
+    /\.config\.[^.]+$/,
+    /^(project|turbo|nx|lerna|composer|firebase|vercel|now)\.json$/,
+    /^(Cargo|pyproject|netlify|wrangler|fly|Pipfile)\.toml$/i,
+];
+/** The folder setting, checked and resolved, or null when the project has none. Throws. */
+export function resolveDataStore(setting, root, 
+/** The site's build output, which every build deletes and rewrites. */
+outputDir) {
+    if (setting == null)
+        return null;
+    const options = Array.isArray(setting)
+        ? { dirs: setting }
+        : setting;
+    const fail = (why) => {
+        throw new Error(`editableData: ${why}`);
+    };
+    if (!Array.isArray(options.dirs) || options.dirs.length === 0)
+        fail('name at least one folder, e.g. editableData: ["static/levels"]');
+    const extensions = (options.extensions ?? ['.json']).map((e) => (e.startsWith('.') ? e : '.' + e).toLowerCase());
+    for (const ext of extensions) {
+        if (!DATA_EXTENSIONS.includes(ext))
+            fail(`${JSON.stringify(ext)} is not a data format this endpoint will write. ` +
+                `Allowed: ${DATA_EXTENSIONS.join(' ')}`);
+    }
+    const realRoot = fs.realpathSync(root);
+    const output = outputDir ? path.resolve(realRoot, outputDir) : null;
+    const dirs = options.dirs.map((name) => {
+        if (typeof name !== 'string' || path.isAbsolute(name))
+            fail(`${JSON.stringify(name)} must be a folder relative to the project`);
+        let real;
+        try {
+            real = fs.realpathSync(path.resolve(realRoot, name));
+        }
+        catch {
+            return fail(`${JSON.stringify(name)} does not exist`);
+        }
+        if (!fs.statSync(real).isDirectory())
+            fail(`${JSON.stringify(name)} is not a folder`);
+        if (!real.startsWith(realRoot + path.sep))
+            fail(`${JSON.stringify(name)} must be inside the project, and not the project itself`);
+        const parts = path.relative(realRoot, real).split(path.sep);
+        if (parts.some((p) => p === '.git' || p === 'node_modules'))
+            fail(`${JSON.stringify(name)} is inside .git or node_modules`);
+        for (const inner of ['.git', 'node_modules'])
+            if (fs.existsSync(path.join(real, inner)))
+                fail(`${JSON.stringify(name)} contains ${inner}`);
+        if (output &&
+            (real === output ||
+                real.startsWith(output + path.sep) ||
+                output.startsWith(real + path.sep)))
+            fail(`${JSON.stringify(name)} overlaps the build output (${path.relative(realRoot, output)}), which every build deletes`);
+        return { real, name: name.replace(/\/+$/, '') };
+    });
+    return {
+        root: realRoot,
+        dirs,
+        extensions,
+        commit: options.commit === true,
+    };
+}
+/**
+ * The absolute path a client's file name may be read or written at, or the reason it may not.
+ * `file` is project-relative (`static/levels/ocean.json`).
+ */
+export function resolveDataFile(store, file) {
+    if (typeof file !== 'string' || file === '')
+        return { refused: 'name a file' };
+    const rel = file.replace(/^\.?\/+/, '');
+    if (!/^[\w\- ./]+$/.test(rel))
+        return { refused: 'file names may use letters, digits, - _ . / and spaces' };
+    const parts = rel.split('/');
+    if (parts.some((p) => p === '' || p === '.' || p === '..'))
+        return { refused: 'no empty, . or .. path segments' };
+    if (parts.some((p) => p.startsWith('.')))
+        return { refused: 'no dot-files or dot-folders' };
+    const base = parts[parts.length - 1];
+    if (CONFIG_NAMES.some((re) => re.test(base)))
+        return { refused: `${base} is a name tools read as configuration` };
+    if (!store.extensions.includes(path.extname(base).toLowerCase()))
+        return {
+            refused: `only ${store.extensions.join(' ')} files are editable here`,
+        };
+    const target = path.resolve(store.root, rel);
+    let realParent;
+    try {
+        realParent = fs.realpathSync(path.dirname(target));
+    }
+    catch {
+        return { refused: 'that folder does not exist' };
+    }
+    const dir = store.dirs.find((d) => realParent === d.real || realParent.startsWith(d.real + path.sep));
+    if (!dir)
+        return { refused: 'not inside an editableData folder' };
+    const real = path.join(realParent, base);
+    try {
+        if (fs.lstatSync(real).isSymbolicLink())
+            return { refused: 'a symlink is never written through' };
+    }
+    catch {
+        // Does not exist yet: a new file in a named folder.
+    }
+    return { path: real, rel: path.relative(store.root, real) };
+}
+/** Why `content` may not be saved as `rel`, or null. JSON must parse: a half-edit is not a level. */
+export function dataContentProblem(rel, content) {
+    if (typeof content !== 'string')
+        return 'content must be a string';
+    if (Buffer.byteLength(content) > MAX_DATA_BYTES)
+        return `content is over ${MAX_DATA_BYTES / 1024 / 1024} MB`;
+    if (path.extname(rel).toLowerCase() === '.json') {
+        try {
+            JSON.parse(content);
+        }
+        catch (e) {
+            return `not valid JSON: ${e.message}`;
+        }
+    }
+    return null;
+}
+/** Write through a temporary file and a rename, so a reader never sees half a file. */
+export function writeDataFile(target, content) {
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(temp, content);
+    try {
+        fs.renameSync(temp, target);
+    }
+    catch (e) {
+        fs.rmSync(temp, { force: true });
+        throw e;
+    }
+}
+/** Every editable file in the named folders, project-relative, newest first. */
+export function listDataFiles(store) {
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || entry.isSymbolicLink())
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile()) {
+                const rel = path.relative(store.root, full).split(path.sep).join('/');
+                if ('path' in resolveDataFile(store, rel)) {
+                    const stat = fs.statSync(full);
+                    found.push({
+                        file: rel,
+                        size: stat.size,
+                        modified: stat.mtime.toISOString(),
+                        ms: stat.mtimeMs,
+                    });
+                }
+            }
+        }
+    };
+    for (const dir of store.dirs)
+        walk(dir.real);
+    return found.sort((a, b) => b.ms - a.ms).map(({ ms: _ms, ...f }) => f);
+}
+/** Run git in the project and return stdout, or throw with its stderr. Bounded in time. */
+async function git(root, args, timeoutMs = 20_000) {
+    const proc = Bun.spawn(['git', ...args], {
+        cwd: root,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        stdin: 'ignore',
+        // A signing prompt or an editor must fail, not wait for a terminal nobody is watching.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_EDITOR: 'false' },
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill();
+    }, timeoutMs);
+    const [out, err, code] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    clearTimeout(timer);
+    if (timedOut)
+        throw new Error(`git ${args[0]} took over ${timeoutMs / 1000}s (a slow hook, or a prompt) and was stopped`);
+    if (code !== 0)
+        throw new Error((err.trim() || out.trim() || `git ${args[0]} exited ${code}`).slice(0, 500));
+    return out;
+}
+/** Whether `root` is in a git work tree, for `commit: true` to be checked at launch. */
+export function isGitWorkTree(root) {
+    const result = Bun.spawnSync(['git', 'rev-parse', '--is-inside-work-tree'], {
+        cwd: root,
+        stdout: 'pipe',
+        stderr: 'pipe',
+    });
+    return result.exitCode === 0 && result.stdout.toString().trim() === 'true';
+}
+/** Why the repository is in no state to take a commit, or null. */
+async function repositoryBusy(root) {
+    const states = [
+        ['rebase-merge', 'in the middle of a rebase'],
+        ['rebase-apply', 'in the middle of a rebase'],
+        ['MERGE_HEAD', 'in the middle of a merge'],
+        ['CHERRY_PICK_HEAD', 'in the middle of a cherry-pick'],
+        ['REVERT_HEAD', 'in the middle of a revert'],
+        ['BISECT_LOG', 'in the middle of a bisect'],
+    ];
+    for (const [name, state] of states) {
+        const where = (await git(root, ['rev-parse', '--git-path', name])).trim();
+        if (fs.existsSync(path.resolve(root, where)))
+            return state;
+    }
+    try {
+        await git(root, ['symbolic-ref', '-q', 'HEAD']);
+    }
+    catch {
+        return 'on a detached HEAD';
+    }
+    return null;
+}
+async function commitFile(store, rel, savedBy) {
+    await git(store.root, ['add', '--', rel]);
+    const changed = await git(store.root, [
+        'diff',
+        '--cached',
+        '--name-only',
+        '--',
+        rel,
+    ]);
+    if (!changed.trim())
+        return null;
+    await git(store.root, [
+        'commit',
+        '-m',
+        `data: save ${rel}`,
+        '-m',
+        `Saved through the dev server by ${savedBy}.`,
+        '--',
+        rel,
+    ]);
+    return (await git(store.root, ['rev-parse', 'HEAD'])).trim();
+}
+// With `commit` on, saves run one at a time, each writing and then committing: two commits
+// fight over .git/index.lock, and a write that lands between another save's write and its
+// `git add` would put one save's content under the other's name (1.16.25 review).
+let saveQueue = Promise.resolve();
+/**
+ * Save a file. With `commit` on, also commit it, alone, leaving other staged work as it was:
+ * `commit` is the hash, or null when the save changed nothing. A save that wrote the file but
+ * could not commit it resolves with `commitError`, because the file WAS saved. The repository's
+ * hooks run, as for any commit; a repository mid-rebase, mid-merge, bisecting or on a detached
+ * HEAD is not committed to, since that commit would land somewhere the developer did not choose.
+ */
+export function saveDataFile(store, target, content, savedBy) {
+    if (!store.commit) {
+        writeDataFile(target.path, content);
+        return Promise.resolve({});
+    }
+    const run = async () => {
+        writeDataFile(target.path, content);
+        try {
+            const busy = await repositoryBusy(store.root);
+            if (busy)
+                return {
+                    commit: null,
+                    commitError: `not committed: the repository is ${busy}`,
+                };
+            return { commit: await commitFile(store, target.rel, savedBy) };
+        }
+        catch (e) {
+            return { commit: null, commitError: e.message };
+        }
+    };
+    const result = saveQueue.then(run, run);
+    saveQueue = result.catch(() => undefined);
+    return result;
+}
+/** One file's committed versions, newest first. */
+export async function dataHistory(store, rel, limit = 100) {
+    const out = await git(store.root, [
+        'log',
+        `-n${limit}`,
+        '--format=%H%x1f%aI%x1f%an%x1f%s',
+        '--',
+        rel,
+    ]);
+    return out
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+        const [commit, date, author, subject] = line.split('\x1f');
+        return { commit, date, author, subject };
+    });
+}
+/** A file as it was at `commit`, or null if the commit is not a hash or lacks the file. */
+export async function readDataAt(store, rel, commit) {
+    if (!/^[0-9a-f]{4,40}$/i.test(commit))
+        return null;
+    try {
+        // `./` makes the path relative to the project, which need not be the repository's root.
+        return await git(store.root, ['show', `${commit}:./${rel}`]);
+    }
+    catch {
+        return null;
+    }
+}