dsh-webdav-sync 0.0.0-stage → 1.0.0

package/lib/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * dsh-webdav-sync host half.
+ *
+ * The plugin's whole job is done by two halves that never both run in the same
+ * process: this one, inside the DSH host, reads and writes the profile's own
+ * files (`cordis.patch.yml` for the model catalog and the other rows,
+ * `package.json` for the installed plugins), talks to the WebDAV server, and
+ * serves the routes the browser half fetches; the browser half is a settings
+ * card that shows what is where and asks for a sync.
+ *
+ * Nothing about the WebDAV account is stored in the composition: the profile
+ * patch is itself one of the things that travels, so a password put there would
+ * be uploaded by the next sync. It lives in the profile's
+ * `.dsh-webdav-sync/sync.json`, mode 0600, beside the state and the cache.
+ */
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type ConfigureBody } from './wire.js';
+import { sameAccount, usable, type Engine } from './engine.js';
+import { defaultConfig, normaliseConfig } from './state.js';
+export declare const name = "dsh-webdav-sync";
+export declare const inject: never[];
+/** The settings namespace this plugin serves; its browser card spells the same string. */
+export declare const WEBDAV_SYNC_NS = "dsh-webdav-sync";
+export interface Config {
+    /** Profile directory to sync; absent selects the running profile. */
+    profileDir?: Volatile<string | undefined> | string;
+    /** How often the host syncs on its own, in minutes; `-1` (the default) is only when asked. */
+    autoEvery?: Volatile<number> | number;
+}
+/**
+ * Cordis resolves the composition entry's config through this schema before
+ * `apply` runs. In dsh 0.1.7+, fields marked with `.volatile()` are projected
+ * by the settings service into live configuration forms.
+ */
+export declare const Config: z;
+/** Reject stale or misspelled config keys before defaults can hide them. */
+export declare function validateConfig(config: Config): void;
+/** The settings-facing subset of the config. */
+export interface SectionConfig {
+    profileDir?: string;
+    autoEvery: number;
+}
+/** The section-shaped view of a config: absent keys stay absent. */
+export declare function sectionOf(config: Config): SectionConfig;
+/**
+ * Apply one configuration change from the card.
+ *
+ * A blank secret leaves the stored one alone rather than clearing it: the card
+ * is given only whether a secret is set, so it can never send back what it was
+ * never shown, and a form submitted without touching the password field must not
+ * wipe it. The way to clear a stored password is to turn sync off.
+ *
+ * The passphrase is refused when it is the WebDAV password: the server is sent
+ * the password, so a file sealed with it could be opened by whoever runs the
+ * server, which is the opposite of what sealing it is for.
+ */
+export declare function configure(engine: Engine, body: ConfigureBody): Promise<void>;
+/**
+ * Plugin apply: mount the settings presentation policy, the HTTP routes and the
+ * auto-sync timer on any webServer that comes and goes.
+ */
+/**
+ * Passwords that are in use but deliberately not on disk.
+ *
+ * "Remember the password" off means it must not be written to `sync.json`, and
+ * it does not mean it should stop working: every route rebuilds its engine from
+ * that file, so a password emptied there would be one no request could carry and
+ * sync would be unable to sign in until the process restarted. It is held for as
+ * long as the host runs, keyed by the state directory so two profiles do not
+ * share one, and put back into the configuration each time it is read.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+export { defaultConfig, normaliseConfig, sameAccount, usable };

package/lib/index.js

@@ -0,0 +1,329 @@
+/**
+ * dsh-webdav-sync host half.
+ *
+ * The plugin's whole job is done by two halves that never both run in the same
+ * process: this one, inside the DSH host, reads and writes the profile's own
+ * files (`cordis.patch.yml` for the model catalog and the other rows,
+ * `package.json` for the installed plugins), talks to the WebDAV server, and
+ * serves the routes the browser half fetches; the browser half is a settings
+ * card that shows what is where and asks for a sync.
+ *
+ * Nothing about the WebDAV account is stored in the composition: the profile
+ * patch is itself one of the things that travels, so a password put there would
+ * be uploaded by the next sync. It lives in the profile's
+ * `.dsh-webdav-sync/sync.json`, mode 0600, beside the state and the cache.
+ */
+import z from '@deepseek-ai/schemastery';
+import { AUTO_CHOICES, ROUTE_CHECK, ROUTE_CONFIG, ROUTE_DISMISS, ROUTE_INSTALL, ROUTE_OFF, ROUTE_PREVIEW, ROUTE_RESTORE, ROUTE_STATUS, ROUTE_SYNC, ROUTE_UNDO, ROUTE_UPLOAD, } from './wire.js';
+import { validateProfileDir, resolveFromEnv } from './paths.js';
+import { check, dismiss, engineFor, loadConfig, preview, restore, sameAccount, saveConfig, status, sync, turnOff, undo, upload, usable, } from './engine.js';
+import { installPlugins } from './install.js';
+import { sameSecret } from './crypto.js';
+import { defaultConfig, normaliseConfig, heldPassword, holdPassword, releasePassword } from './state.js';
+export const name = 'dsh-webdav-sync';
+export const inject = [];
+/** Largest accepted request body (bytes) — these payloads are a few strings. */
+const BODY_LIMIT = 64 * 1024;
+/** The settings namespace this plugin serves; its browser card spells the same string. */
+export const WEBDAV_SYNC_NS = 'dsh-webdav-sync';
+/** How long the auto-sync timer waits before its first attempt. */
+const FIRST_DELAY_MS = 20_000;
+function readVolatile(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'object' && value !== null && 'get' in value && typeof value.get === 'function') {
+        return value.get();
+    }
+    return value;
+}
+/**
+ * Cordis resolves the composition entry's config through this schema before
+ * `apply` runs. In dsh 0.1.7+, fields marked with `.volatile()` are projected
+ * by the settings service into live configuration forms.
+ */
+export const Config = z.object({
+    profileDir: z.string().volatile(),
+    autoEvery: z.number().default(-1).volatile(),
+});
+/** Reject stale or misspelled config keys before defaults can hide them. */
+export function validateConfig(config) {
+    const unknown = Object.keys(config).find(key => key !== 'profileDir' && key !== 'autoEvery');
+    if (unknown !== undefined) {
+        throw new Error(`WebdavSyncConfig：不认识的配置项「${unknown}」`);
+    }
+    const dir = readVolatile(config.profileDir);
+    if (dir !== undefined && dir !== '')
+        validateProfileDir(dir);
+    const auto = readVolatile(config.autoEvery);
+    if (auto !== undefined && !AUTO_CHOICES.includes(auto)) {
+        throw new Error(`WebdavSyncConfig：「autoEvery」只能是 ${AUTO_CHOICES.join('、')} 之一`);
+    }
+}
+/** The section-shaped view of a config: absent keys stay absent. */
+export function sectionOf(config) {
+    const profileDir = readVolatile(config.profileDir);
+    const autoEvery = readVolatile(config.autoEvery);
+    return {
+        ...(profileDir === undefined || profileDir === '' ? {} : { profileDir }),
+        autoEvery: autoEvery ?? -1,
+    };
+}
+/**
+ * Apply one configuration change from the card.
+ *
+ * A blank secret leaves the stored one alone rather than clearing it: the card
+ * is given only whether a secret is set, so it can never send back what it was
+ * never shown, and a form submitted without touching the password field must not
+ * wipe it. The way to clear a stored password is to turn sync off.
+ *
+ * The passphrase is refused when it is the WebDAV password: the server is sent
+ * the password, so a file sealed with it could be opened by whoever runs the
+ * server, which is the opposite of what sealing it is for.
+ */
+export async function configure(engine, body) {
+    const next = { ...engine.config };
+    const gavePassword = typeof body.password === 'string' && body.password !== '';
+    if (typeof body.url === 'string')
+        next.url = body.url.trim().replace(/\/+$/, '');
+    if (typeof body.user === 'string')
+        next.user = body.user.trim();
+    if (gavePassword)
+        next.password = body.password;
+    if (typeof body.passphrase === 'string' && body.passphrase !== '')
+        next.passphrase = body.passphrase;
+    if (typeof body.models === 'boolean')
+        next.models = body.models;
+    if (typeof body.defaults === 'boolean')
+        next.defaults = body.defaults;
+    if (typeof body.plugins === 'boolean')
+        next.plugins = body.plugins;
+    if (typeof body.patch === 'boolean')
+        next.patch = body.patch;
+    if (typeof body.rememberPassword === 'boolean')
+        next.rememberPassword = body.rememberPassword;
+    if (typeof body.autoEvery === 'number' && AUTO_CHOICES.includes(body.autoEvery)) {
+        next.autoEvery = body.autoEvery;
+    }
+    // The password this computer would actually send: one typed into this submit, or
+    // the one already in hand for this account. What is written down is only part of
+    // that — a password the user chose not to remember is held in memory for the run
+    // — and this refusal is about the file on the server being openable by whoever
+    // runs it, which is just as true of the one that would be sent. A changed
+    // account has no password in hand at all: the carried one is dropped below, so
+    // it cannot be what seals a file this submit is about to write.
+    const inHand = gavePassword || sameAccount(engine.config, next);
+    const sent = inHand ? (next.password !== '' ? next.password : (heldPassword(engine.paths) ?? '')) : '';
+    if (next.passphrase !== '' && sent !== '' && sameSecret(next.passphrase, sent)) {
+        throw new Error('口令不能和 WebDAV 密码相同：密码是要发给服务器的，服务器可以拿它打开文件。请另设一个口令');
+    }
+    // A blank password field means "keep the stored one", which is only a faithful
+    // reading while the stored one belongs to the same account. Pointing this
+    // computer at another server or user while carrying the old password along
+    // would send a credential for one service to another, so the carried-over one
+    // is dropped rather than reused. A password typed in this same submit is kept:
+    // it was given for the address being saved. The card reads "a password is set"
+    // from the stored value, so it stops saying so once this takes effect.
+    if (!gavePassword && !sameAccount(engine.config, next))
+        next.password = '';
+    // Turning remembering off is about the file, not about this run: the card says
+    // the password "is used for this run only", and a password emptied here would
+    // be one no request could ever carry, leaving sync unable to sign in until the
+    // process restarts and the user retypes it. It stays in the engine — which is
+    // what the running half talks to the server with — and is left out of what is
+    // written down.
+    if (next.rememberPassword) {
+        await saveConfig(engine.paths, next);
+        releasePassword(engine.paths);
+    }
+    else {
+        await saveConfig(engine.paths, { ...next, password: '' });
+        holdPassword(engine.paths, next.password);
+    }
+    engine.config = next;
+}
+/**
+ * Plugin apply: mount the settings presentation policy, the HTTP routes and the
+ * auto-sync timer on any webServer that comes and goes.
+ */
+/**
+ * Passwords that are in use but deliberately not on disk.
+ *
+ * "Remember the password" off means it must not be written to `sync.json`, and
+ * it does not mean it should stop working: every route rebuilds its engine from
+ * that file, so a password emptied there would be one no request could carry and
+ * sync would be unable to sign in until the process restarted. It is held for as
+ * long as the host runs, keyed by the state directory so two profiles do not
+ * share one, and put back into the configuration each time it is read.
+ */
+export function apply(ctx, config = {}) {
+    validateConfig(config);
+    const currentConfig = () => ctx.fiber?.config ?? config;
+    /** Resolve the profile and read the stored sync configuration, always afresh. */
+    const engine = async () => {
+        const paths = resolveFromEnv(readVolatile(currentConfig().profileDir));
+        const { config: stored } = await loadConfig(paths);
+        const secret = stored.rememberPassword ? undefined : heldPassword(paths);
+        return engineFor(paths, secret === undefined || secret === '' ? stored : { ...stored, password: secret });
+    };
+    // In dsh 0.1.7+, the settings service projects volatile Config fields into
+    // forms. auto: false tells the host this plugin ships its own card, which the
+    // browser half registers as `plugins.bundle.config`.
+    ctx.inject(['settings'], (settingsCtx) => {
+        settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber), 'webdav-sync: settings presentation policy');
+    });
+    ctx.inject(['webServer'], (webCtx) => {
+        const send = (res, status, body) => {
+            res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+            res.end(JSON.stringify(body));
+        };
+        const readJson = (req) => new Promise((resolvePromise, rejectPromise) => {
+            const chunks = [];
+            let size = 0;
+            req.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > BODY_LIMIT) {
+                    req.destroy();
+                    rejectPromise(new Error('请求内容过大'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            req.on('end', () => {
+                if (chunks.length === 0) {
+                    resolvePromise({});
+                    return;
+                }
+                try {
+                    resolvePromise(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                }
+                catch (error) {
+                    rejectPromise(new Error(`请求内容不是合法的 JSON：${error instanceof Error ? error.message : String(error)}`));
+                }
+            });
+            req.on('error', rejectPromise);
+        });
+        /**
+         * One exact route. A failure answers 400 with its own message, which is what
+         * the card shows: the messages this plugin raises are written to be read by
+         * a person ("服务器上没有目录 … 请先在那边建好"), not to be mapped
+         * onto status codes.
+         */
+        const route = (path, label, handle) => {
+            webCtx.effect(() => webCtx.webServer.register({
+                kind: 'exact',
+                path,
+                handler: async (req, res) => {
+                    try {
+                        await handle(req, res, req.method === 'GET' ? {} : await readJson(req));
+                    }
+                    catch (error) {
+                        const text = error instanceof Error ? error.message : String(error);
+                        send(res, 400, { error: text });
+                    }
+                },
+            }), `webdav-sync: ${label} route`);
+        };
+        route(ROUTE_STATUS, 'status', async (_req, res) => {
+            const result = await status(await engine());
+            send(res, 200, result);
+        });
+        route(ROUTE_CONFIG, 'config', async (_req, res, body) => {
+            const current = await engine();
+            await configure(current, (body ?? {}));
+            await saveStateIfUsable(current);
+            send(res, 200, { message: '已保存' });
+        });
+        route(ROUTE_CHECK, 'check', async (_req, res) => {
+            const current = await engine();
+            if (!usable(current.config) && current.config.url.trim() === '') {
+                throw new Error('请先填写同步地址');
+            }
+            send(res, 200, await check(current));
+        });
+        route(ROUTE_SYNC, 'sync', async (req, res, body) => {
+            const current = await engine();
+            const force = body?.force === true || new URL(req.url ?? '/', 'http://x').searchParams.get('force') === '1';
+            send(res, 200, await sync(current, { force }));
+        });
+        route(ROUTE_PREVIEW, 'preview', async (_req, res) => {
+            send(res, 200, await preview(await engine()));
+        });
+        route(ROUTE_RESTORE, 'restore', async (_req, res) => {
+            send(res, 200, await restore(await engine()));
+        });
+        route(ROUTE_UNDO, 'undo', async (_req, res) => {
+            send(res, 200, await undo(await engine()));
+        });
+        route(ROUTE_UPLOAD, 'upload', async (_req, res) => {
+            send(res, 200, await upload(await engine()));
+        });
+        route(ROUTE_DISMISS, 'dismiss', async (_req, res) => {
+            await dismiss(await engine());
+            send(res, 200, { message: '已关闭提示' });
+        });
+        route(ROUTE_OFF, 'off', async (_req, res) => {
+            await turnOff(await engine());
+            send(res, 200, { message: '已关闭 WebDAV 同步；服务器上的文件保持原样' });
+        });
+        route(ROUTE_INSTALL, 'install', async (_req, res) => {
+            const current = await engine();
+            send(res, 200, await installPlugins(current.paths));
+        });
+    });
+    startTimer(ctx, currentConfig);
+}
+/** Write a state file that records the new configuration's key, if it can be written. */
+async function saveStateIfUsable(engine) {
+    try {
+        const { ensureStateDir } = await import('./state.js');
+        await ensureStateDir(engine.paths);
+    }
+    catch {
+        // Not being able to make the directory is reported by the first sync, which
+        // needs it far more than a configuration change does.
+    }
+}
+/**
+ * Sync on a timer, when the stored configuration asks for it.
+ *
+ * The interval is read from the stored configuration before every attempt rather
+ * than captured once, so changing it in the card takes effect without a reload.
+ * A failure is recorded in the state by `sync` itself and changes nothing here:
+ * the next tick tries again, which is the whole point of a timer.
+ */
+function startTimer(ctx, currentConfig) {
+    let timer;
+    let stopped = false;
+    const tick = async () => {
+        if (stopped)
+            return;
+        let wait = 0;
+        try {
+            const paths = resolveFromEnv(readVolatile(currentConfig().profileDir));
+            const { config: stored } = await loadConfig(paths);
+            const minutes = stored.autoEvery;
+            if (usable(stored) && minutes > 0) {
+                await sync(engineFor(paths, stored)).catch(() => undefined);
+                wait = minutes * 60_000;
+            }
+        }
+        catch {
+            // A configuration that cannot be read yet is not an error worth logging on
+            // every tick: the card is where it gets set.
+        }
+        if (stopped)
+            return;
+        // Nothing to do is polled for slowly instead of not at all, so turning sync
+        // on in the card starts it without a reload.
+        timer = setTimeout(() => void tick(), wait === 0 ? 60_000 : wait);
+        timer.unref?.();
+    };
+    timer = setTimeout(() => void tick(), FIRST_DELAY_MS);
+    timer.unref?.();
+    ctx.effect(() => () => {
+        stopped = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }, 'webdav-sync: auto-sync timer');
+}
+export { defaultConfig, normaliseConfig, sameAccount, usable };

package/lib/install.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Installing the plugins a synced profile declares.
+ *
+ * A sync can bring in a `package.json` naming plugins this computer has never
+ * installed. The profile's `node_modules` is not synced — it is a build product,
+ * tens of megabytes of it — so the declaration travels and the packages are
+ * fetched here instead.
+ *
+ * The command is `pnpm install` in the profile, which is what dsh's own plugin
+ * manager runs; the packages come from the same registries, so nothing about
+ * supply-chain rules changes because this plugin asked for them.
+ *
+ * The child's output goes to an open file, never a pipe. A pipe is a restricted
+ * operation inside dsh's file sandbox, and this code runs wherever the harness
+ * put the plugin: a file descriptor always works, and the tail of the file is
+ * what the card shows anyway.
+ */
+import type { InstallResult } from './wire.js';
+import type { ResolvedPaths } from './paths.js';
+/**
+ * Run `pnpm install` in the profile directory.
+ *
+ * A nonzero exit is not a thrown error: the card shows what pnpm said, which is
+ * the only thing that tells a user whether a package name was wrong or the
+ * network was down. A pnpm that cannot be started at all is the one case that
+ * throws, because there is nothing to show.
+ */
+export declare function installPlugins(paths: ResolvedPaths): Promise<InstallResult>;