dsh-webdav-sync 0.0.0-stage → 1.0.1

package/lib/state.js

@@ -0,0 +1,253 @@
+/**
+ * The plugin's own files, all of them inside the profile's `.dsh-webdav-sync`:
+ * the configuration (which holds the server password and the passphrase, so it is
+ * written 0600), the sync state, and a cached copy of what the server held when
+ * it was last read.
+ *
+ * The cache exists for one reason. A sync that finds the server unchanged still
+ * has to merge, and merging is three-way: it needs the version of each part as
+ * the server last held it. That is in the state, but the parts themselves are
+ * needed to compute what a part *became* on the server. Keeping the last body
+ * means a sync that only changed something here never downloads the file it is
+ * about to write over.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { AUTO_CHOICES, AUTO_MANUAL, BACKUP_EXT, } from './wire.js';
+import { sum } from './crypto.js';
+import { isMissing, message, writeAtomic } from './store.js';
+/** Name of the configuration file inside the state directory. */
+export const CONFIG_NAME = 'sync.json';
+/** Name of the sync state file. */
+export const STATE_NAME = 'sync-state.json';
+/** Name of the cached copy of the server's file. */
+export const CACHE_NAME = `sync-server${BACKUP_EXT}`;
+/** Name of the directory holding copies the sync replaced. */
+export const KEPT_DIR = 'sync';
+/** Mode for anything holding a secret, and for the directory around it. */
+const SECRET_MODE = 0o600;
+const DIR_MODE = 0o700;
+/** The configuration as first written, before anything is known. */
+export function defaultConfig() {
+    return {
+        url: '',
+        user: '',
+        password: '',
+        passphrase: '',
+        autoEvery: AUTO_MANUAL,
+        models: true,
+        defaults: true,
+        plugins: true,
+        patch: true,
+        rememberPassword: true,
+    };
+}
+/** The configuration file's path. */
+export function configFile(paths) {
+    return join(paths.stateDir, CONFIG_NAME);
+}
+/** The sync state file's path. */
+export function stateFile(paths) {
+    return join(paths.stateDir, STATE_NAME);
+}
+/** The cached server copy's path. */
+export function cacheFile(paths) {
+    return join(paths.stateDir, CACHE_NAME);
+}
+/** The folder replaced copies are kept in. */
+export function keptDir(paths) {
+    return join(paths.stateDir, KEPT_DIR);
+}
+/**
+ * Passwords that are in use but deliberately not written down.
+ *
+ * "Remember the password" off means it must not reach `sync.json`; it does not
+ * mean it should stop working. Every route rebuilds its engine from that file,
+ * so a password emptied there is one no request can carry and sync could not
+ * sign in at all until the host restarted. It is held here for as long as the
+ * host runs — keyed by state directory, so two profiles keep their own — and
+ * handed back whenever the stored configuration is read.
+ */
+const held = new Map();
+/** Keep a password in memory only, for the profile it was given for. */
+export function holdPassword(paths, password) {
+    if (password === '')
+        held.delete(paths.stateDir);
+    else
+        held.set(paths.stateDir, password);
+}
+/** Forget the in-memory password for a profile, on turning sync off or remembering again. */
+export function releasePassword(paths) {
+    held.delete(paths.stateDir);
+}
+/** The in-memory password for a profile, if one is being held. */
+export function heldPassword(paths) {
+    return held.get(paths.stateDir);
+}
+/**
+ * Read the configuration, with anything unset filled in from the defaults, so a
+ * file written by an older build never reads as a missing field.
+ */
+export async function loadConfig(paths) {
+    const raw = await readJson(configFile(paths));
+    if (raw === undefined)
+        return { config: defaultConfig(), found: false };
+    return { config: normaliseConfig(raw), found: true };
+}
+/** Read the sync state; an empty one only when there is none. */
+export async function loadState(paths) {
+    const raw = await readJson(stateFile(paths));
+    if (raw === undefined)
+        return {};
+    return raw;
+}
+/** Write the configuration, 0600 because it holds two secrets. */
+export async function saveConfig(paths, config) {
+    await writeAtomic(configFile(paths), `${JSON.stringify(config, null, 2)}\n`, SECRET_MODE);
+}
+/** Write the state. It holds no secret, but it does name a folder, so it is 0600 too. */
+export async function saveState(paths, state) {
+    await writeAtomic(stateFile(paths), `${JSON.stringify(state, null, 2)}\n`, SECRET_MODE);
+}
+/** Write the state directory itself, 0700, before anything goes in it. */
+export async function ensureStateDir(paths) {
+    await writeAtomicStateDir(paths);
+}
+async function writeAtomicStateDir(paths) {
+    const { mkdir, chmod } = await import('node:fs/promises');
+    await mkdir(paths.stateDir, { recursive: true, mode: DIR_MODE });
+    await chmod(paths.stateDir, DIR_MODE).catch(() => undefined);
+}
+/** Keep the body just read or written, so the next sync can merge without it. */
+export async function remember(paths, data) {
+    await writeAtomic(cacheFile(paths), data, SECRET_MODE);
+}
+/**
+ * The cached body, but only when it hashes to what is expected. A cache that
+ * does not match is not the version the state describes, so it is not one the
+ * merge may stand in for.
+ */
+export async function cached(paths, want) {
+    if (want === undefined || want === '')
+        return undefined;
+    let data;
+    try {
+        data = await readFile(cacheFile(paths));
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return undefined;
+        throw cause;
+    }
+    return sum(data) === want ? new Uint8Array(data) : undefined;
+}
+/**
+ * Identifies the thing a state describes: one server, one account, one
+ * passphrase. A change to any of them resets the state, because the hashes in it
+ * are about a file that is no longer the one being synced.
+ *
+ * The password is deliberately not here: it opens the same file rather than
+ * pointing at a different one, and dropping a usable baseline whenever someone
+ * rotates a password would make this computer adopt the server wholesale on the
+ * next sync. See `docs/decisions/0026-password-not-in-state-key.md`.
+ */
+export function stateKey(config) {
+    return createHash('sha256')
+        .update([config.url.trim().replace(/\/+$/, ''), '\u0000', config.user, '\u0000', config.passphrase].join(''))
+        .digest('hex');
+}
+/**
+ * Whether two configurations point at the same account. A password is only ever
+ * reused for the server and user it was given for: keeping one across an address
+ * change is how a password for one service gets sent to another.
+ */
+export function sameAccount(a, b) {
+    return normaliseUrl(a.url) === normaliseUrl(b.url) && a.user.trim() === b.user.trim();
+}
+/** An address with its trailing slashes gone, for comparing two of them. */
+export function normaliseUrl(url) {
+    return url.trim().replace(/\/+$/, '');
+}
+/**
+ * Whether the configuration is complete enough to reach a server. The
+ * passphrase is trimmed for the same reason `seal` refuses a blank one: a
+ * passphrase of spaces would seal nothing, so a timer must not treat it as
+ * ready and start syncs that can only fail.
+ */
+export function usable(config) {
+    return normaliseUrl(config.url) !== '' && config.passphrase.trim() !== '';
+}
+/** Whether a part travels with this configuration. */
+export function syncsPart(config, part) {
+    switch (part) {
+        case 'models':
+            return config.models;
+        case 'defaults':
+            return config.defaults;
+        case 'plugins':
+            return config.plugins;
+        case 'patch':
+            return config.patch;
+    }
+}
+/** Fill in defaults and coerce the several fields that come from a browser. */
+export function normaliseConfig(raw) {
+    const base = defaultConfig();
+    const text = (key) => {
+        const value = raw[key];
+        return typeof value === 'string' ? value : base[key];
+    };
+    const flag = (key) => {
+        const value = raw[key];
+        return typeof value === 'boolean' ? value : base[key];
+    };
+    const auto = raw.autoEvery;
+    const autoEvery = typeof auto === 'number' && Number.isInteger(auto) && AUTO_CHOICES.includes(auto) ? auto : AUTO_MANUAL;
+    return {
+        url: text('url'),
+        user: text('user'),
+        password: text('password'),
+        passphrase: text('passphrase'),
+        autoEvery,
+        models: flag('models'),
+        defaults: flag('defaults'),
+        plugins: flag('plugins'),
+        patch: flag('patch'),
+        rememberPassword: flag('rememberPassword'),
+    };
+}
+/**
+ * Read a JSON object out of one of the plugin's own files.
+ *
+ * Only a file that is *not there* reads as nothing. A file that is there but
+ * unreadable is a different thing and used to be treated as the same one: the
+ * configuration fell back to defaults, so the address and passphrase silently
+ * became empty, and the state read as a fresh one, so every part looked like a
+ * part the server had changed and the server's copy came over the top of this
+ * computer's work. Both files here are written whole by `writeAtomic`, so one
+ * that cannot be parsed was damaged from outside — worth saying so, with its
+ * name, rather than pretending it was never written.
+ */
+async function readJson(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return undefined;
+        throw cause;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error(`${file} 不是可读的 JSON：${message(cause)}`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${file} 里不是 JSON 对象`);
+    }
+    return value;
+}

package/lib/store.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Reading and writing a DSH profile.
+ *
+ * Two files matter. `cordis.patch.yml` is the profile's own patch layer — a
+ * top-level YAML array of loader rows, each either an id-targeted override or an
+ * `insert:` block that pushes new rows in. The model catalog is one of those rows
+ * (`llm-pi-ai`), the default model is another (`agent-default-model`), and
+ * everything else — MCP servers, permission presets, UI settings, inserts — is
+ * the rest of them. `package.json` names the installed plugins.
+ *
+ * Writes go through the `yaml` Document API rather than a stringify of a parsed
+ * object, so the file's own comments and layout survive a sync that only meant to
+ * change one provider.
+ */
+import type { Document } from 'yaml';
+import { type DefaultsPart, type ModelsPart, type PatchEntry, type PatchPart, type PluginsPart } from './wire.js';
+import type { ResolvedPaths } from './paths.js';
+/** The profile patch row holding the model catalog. */
+export declare const MODELS_ID = "llm-pi-ai";
+/** The profile patch row holding the default model. */
+export declare const DEFAULTS_ID = "agent-default-model";
+/** Package whose patch row the plugin adds for itself; never carried as a part. */
+export declare const SELF_ID = "dsh-webdav-sync";
+/** One row of the profile patch, as it is carried between computers. */
+export interface PatchRow {
+    /** Stable identity: `id:<id>` for a row, `insert:<inner ids>` for an insert block. */
+    key: string;
+    /** The row as plain JSON. */
+    value: PatchEntry;
+}
+/** A profile patch, parsed and kept as a document so a write preserves the file. */
+export interface PatchFile {
+    document: Document;
+    rows: PatchRow[];
+    /** The bytes read, for the changed-since check and for keeping a copy. */
+    text: string;
+    /** The file's modification time, used as the merge's tie-breaker. */
+    mtimeMs: number;
+}
+/** The profile manifest, kept as plain JSON with its original key order. */
+export interface ManifestFile {
+    value: Record<string, unknown>;
+    text: string;
+    mtimeMs: number;
+}
+/** Read and parse the profile patch. A missing file reads as an empty patch. */
+export declare function readPatch(paths: ResolvedPaths): Promise<PatchFile>;
+/** Read the profile manifest. A missing file reads as an empty manifest. */
+export declare function readManifest(paths: ResolvedPaths): Promise<ManifestFile>;
+/** Every part of a profile this plugin can carry, as collected from disk. */
+export interface Collected {
+    models?: ModelsPart;
+    defaults?: DefaultsPart;
+    plugins?: PluginsPart;
+    patch?: PatchPart;
+}
+/**
+ * Gather the parts from one profile.
+ *
+ * A part is left out entirely when the profile holds nothing for it, so a
+ * computer that has never configured models never claims the model part — which
+ * is what lets the other computer's catalog come in untouched on a first sync.
+ */
+export declare function collect(patch: PatchFile, manifest: ManifestFile): Collected;
+/** `dsh.profile.bundles` from a manifest, as strings. */
+export declare function readBundles(manifest: Record<string, unknown>): string[];
+/**
+ * The plugins a manifest declares that a set of installed package names does not
+ * have. Built-in shell packages are skipped: they ship with DSH, not with the
+ * profile.
+ */
+export declare function missingPlugins(plugins: PluginsPart | undefined, installed: readonly string[]): string[];
+/**
+ * Rewrite the profile patch so it holds the merged parts.
+ *
+ * Model and default rows are replaced in place when they exist and appended when
+ * they do not; the remaining rows are replaced wholesale by the merged list, with
+ * the model rows kept where they were. A no-op merge leaves the bytes untouched,
+ * so a sync that changed nothing does not rewrite the file.
+ */
+export declare function applyPatch(patch: PatchFile, parts: {
+    models?: ModelsPart | null;
+    defaults?: DefaultsPart | null;
+    patch?: PatchPart;
+}): string;
+/**
+ * Rewrite the profile manifest with merged plugin declarations, two-space
+ * indented.
+ *
+ * The declaration is mirrored rather than merged: a plugin another computer
+ * removed goes from here too, or the two manifests never converge and every sync
+ * would push again. Nothing is uninstalled — `node_modules` is not synced — so
+ * what leaves is a line in a file, not a package.
+ */
+export declare function applyManifest(manifest: ManifestFile, plugins: PluginsPart): string;
+/** Write bytes only when they differ from what is already there. */
+export declare function writeIfChanged(file: string, data: string | Uint8Array): Promise<boolean>;
+/**
+ * Write a file by writing a sibling and renaming it over the target, so a crash
+ * or a power cut leaves either the old file or the new one and never half of
+ * either. The temporary file is removed when the write fails.
+ */
+export declare function writeAtomic(file: string, data: string | Uint8Array, mode?: number): Promise<void>;
+/**
+ * Keep a copy of something the plugin is about to replace, in `sync/` beside its
+ * own state. The newest `keep` files matching the tag survive.
+ */
+export declare function keepAside(dir: string, tag: string, data: string | Uint8Array, keep?: number): Promise<string>;
+/**
+ * A patch row's stable key.
+ *
+ * An `insert:` block is keyed by the ids of the rows it inserts, which is what
+ * makes it the same block on two computers that wrote it separately. An
+ * insert block whose rows carry no ids has no such name, and keying it by its
+ * position of `?`s would give every such block the one key `insert:?` — two
+ * different blocks would be read as one row, and a merge would write one
+ * block's contents into the other. Those are keyed by their own content
+ * instead, exactly like any other row that has neither id nor usable insert.
+ */
+export declare function keyOf(entry: PatchEntry): string;
+/** `true` for a value that is a plain object rather than an array or null. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether two values from a YAML document hold the same data.
+ *
+ * A node read back out of a Document is not a plain object, so this normalises
+ * through JSON before comparing. It is what lets a sync tell "the merge decided
+ * the same thing" from "the merge decided something new", and therefore skip a
+ * write that would only reformat the file.
+ */
+export declare function sameJson(a: unknown, b: unknown): boolean;
+/** An object's keys in sorted order, so a rewritten manifest is stable. */
+export declare function sortKeys(value: Record<string, unknown>): Record<string, unknown>;
+/** A filesystem error meaning "there is nothing there". */
+export declare function isMissing(cause: unknown): boolean;
+/**
+ * An error's message, said in one line, with whatever it was caused by.
+ *
+ * A wrapper's own message is the vaguest part of it — "fetch failed" and
+ * "reading dsh-profile.dshsync" name the attempt, while the cause underneath
+ * says `ECONNREFUSED` or the parse error, and that is what a reader needs. The
+ * chain is followed rather than only read at the top, since the ends that were
+ * wrapped twice on the way up are the ones with the reason in them. The walk is
+ * bounded and watches for repeats, because a cause pointing back at itself would
+ * otherwise turn one sentence into a hang.
+ */
+export declare function message(cause: unknown): string;