dsh-webdav-sync 0.0.0-stage → 1.0.0

package/lib/install.js

@@ -0,0 +1,269 @@
+/**
+ * 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 { spawn } from 'node:child_process';
+import { mkdtemp, open, readFile, rm, stat, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installedPackages } from './engine.js';
+import { missingPlugins } from './store.js';
+/** How long an install may run before it is given up on. */
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+/** How much of the child's output the card is given. */
+const TAIL_CHARS = 4000;
+/**
+ * Where pnpm is, most authoritative first.
+ *
+ * dsh ships its own pnpm under `resources/runtime/pnpm`, and that is the version
+ * the profile's lockfile was written by. `DSH_PNPM` lets a caller name one
+ * outright; PATH is the last resort, since a machine with no global pnpm is
+ * exactly the case this exists for.
+ */
+function pnpmCandidates(env) {
+    const out = [];
+    const named = env.DSH_PNPM;
+    if (named !== undefined && named.trim() !== '')
+        out.push(named.trim());
+    const resources = env.DSH_RESOURCES_DIR;
+    if (resources !== undefined && resources.trim() !== '') {
+        out.push(join(resources.trim(), 'runtime', 'pnpm', 'bin', 'pnpm.cjs'));
+    }
+    if (process.platform === 'win32')
+        out.push('pnpm.cmd');
+    else
+        out.push('pnpm');
+    return out;
+}
+/** Whether a path names something that exists. */
+async function exists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a path names something this computer can actually run.
+ *
+ * `exists` is not enough: a directory exists too, and so does a text file with no
+ * interpreter. Spawning either one fails with an errno that differs by platform
+ * and by kind of file — a directory is `EACCES` on Linux and `ENOENT` on Windows,
+ * a text file is `EFTYPE` on Windows — and quoting that back would describe a
+ * file the user never named instead of saying there is no pnpm here. So the
+ * candidate is judged before it is spawned, and the answer is the same on every
+ * computer.
+ */
+async function runnable(file, env) {
+    try {
+        if (!(await stat(file)).isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    if (process.platform === 'win32') {
+        // Windows starts a program by its extension; anything else is opened by an
+        // application, which is not what `spawn` does.
+        const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter((part) => part.trim() !== '');
+        return extensions.some((extension) => file.toLowerCase().endsWith(extension.trim().toLowerCase()));
+    }
+    try {
+        // A file this computer is not allowed to execute is not a pnpm either. The
+        // bundled `pnpm.cjs` dsh ships is executable, so it still qualifies.
+        await access(file, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a failed spawn means "this computer cannot start that", rather than
+ * something that went wrong while running it.
+ *
+ * The errno differs by platform and by what the path turned out to be: `ENOENT`
+ * for a target that is not there (and for a directory on Windows), `EACCES` for
+ * one that exists without the right to execute it (a directory on Linux),
+ * `ENOEXEC` for a file whose interpreter cannot be started, `EFTYPE` for a file
+ * Windows refuses to start, `ENOTDIR` for a path with a non-directory in the
+ * middle. Every one of them means the same thing to the user — there is no pnpm
+ * here — and none of them is worth quoting.
+ */
+const NOT_A_COMMAND = new Set(['ENOENT', 'EACCES', 'ENOEXEC', 'EFTYPE', 'ENOTDIR']);
+/**
+ * Whether a bare command name is one this computer can run.
+ *
+ * A name with no separator in it is handed to the shell, and a shell that
+ * cannot find it still starts and still answers — with its own complaint, in
+ * its own words ("'pnpm.cmd' is not recognized…"). Searching PATH here first
+ * keeps that from happening, so "there is no pnpm" arrives as the sentence
+ * written for it rather than as whatever the shell says.
+ */
+async function onPath(name, env) {
+    const path = env.PATH ?? env.Path ?? '';
+    const windows = process.platform === 'win32';
+    const base = windows ? name.replace(/\.(cmd|exe|bat|com)$/i, '') : name;
+    const extensions = windows
+        ? ['', ...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter((part) => part.trim() !== '')]
+        : [''];
+    for (const directory of path.split(windows ? ';' : ':')) {
+        if (directory.trim() === '')
+            continue;
+        for (const extension of extensions) {
+            if (await exists(join(directory, base + extension)))
+                return true;
+            if (await exists(join(directory, name)))
+                return true;
+        }
+    }
+    return false;
+}
+/** Whether a failed spawn means the command could not be started at all. */
+function missingCommand(cause) {
+    const code = typeof cause === 'object' && cause !== null ? cause.code : undefined;
+    return typeof code === 'string' && NOT_A_COMMAND.has(code);
+}
+/** The last `chars` characters of a text, with a marker when it was cut. */
+function tail(text, chars) {
+    const trimmed = text.trim();
+    if (trimmed.length <= chars)
+        return trimmed;
+    return `…${trimmed.slice(trimmed.length - chars)}`;
+}
+/**
+ * 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 async function installPlugins(paths) {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-webdav-install-'));
+    const logFile = join(dir, 'pnpm.log');
+    const env = { ...process.env, CI: '1' };
+    delete env.npm_config_prefix;
+    let output = '';
+    let code = null;
+    let started = false;
+    let lastCause;
+    try {
+        for (const candidate of pnpmCandidates(process.env)) {
+            if (candidate.includes('\\') || candidate.includes('/')) {
+                if (!(await runnable(candidate, process.env)))
+                    continue;
+            }
+            else if (!(await onPath(candidate, process.env))) {
+                continue;
+            }
+            try {
+                code = await run(candidate, ['install', '--reporter', 'append-only'], paths.profileDir, env, logFile);
+                started = true;
+                lastCause = undefined;
+                break;
+            }
+            catch (cause) {
+                // A command that is not there is not a failure worth quoting back: the
+                // shell's own words for it name a file the user never asked for. Let it
+                // fall through to the sentence below, which says what to do about it.
+                // The candidate check above is what normally keeps this from happening;
+                // this is the second line of defence for a file that exists and still
+                // cannot be started (a broken interpreter, a path that changed underneath
+                // us).
+                if (!missingCommand(cause))
+                    lastCause = cause;
+            }
+        }
+        output = tail(await readFile(logFile, 'utf8').catch(() => ''), TAIL_CHARS);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    if (!started) {
+        if (lastCause !== undefined) {
+            const why = lastCause instanceof Error ? lastCause.message : String(lastCause);
+            throw new Error(`在 ${paths.profileDir} 里运行 pnpm 失败：${why}`);
+        }
+        throw new Error('这台电脑上没有 pnpm，同步带过来的插件就装不上：请先安装 pnpm，或者把 DSH_PNPM 指向 pnpm 可执行文件');
+    }
+    const still = await stillMissing(paths);
+    if (code !== 0 && still.length > 0) {
+        return { ok: false, output: output === '' ? `pnpm 的退出码是 ${code}` : output };
+    }
+    if (still.length > 0) {
+        return { ok: false, output: `pnpm 跑完了，但这些仍然没有装上：${still.join('、')}` };
+    }
+    return { ok: true, output: output === '' ? 'pnpm 跑完了，没有输出' : output };
+}
+/** The plugins the profile declares that are still not in `node_modules`. */
+async function stillMissing(paths) {
+    const raw = await readFile(paths.packageFile, 'utf8').catch(() => '{}');
+    let manifest = {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === 'object')
+            manifest = parsed;
+    }
+    catch {
+        // An unreadable manifest is not this function's to report: the declaring
+        // side already reads it, and an empty declaration simply says "nothing".
+    }
+    const deps = manifest.dependencies;
+    const profile = manifest.dsh?.profile;
+    const bundles = profile?.bundles;
+    const declared = {
+        dependencies: deps !== null && typeof deps === 'object' ? deps : {},
+        bundles: Array.isArray(bundles) ? bundles.filter((item) => typeof item === 'string') : [],
+    };
+    return missingPlugins(declared, await installedPackages(paths));
+}
+/** Spawn one command with its output going to a file, and answer its exit code. */
+async function run(command, args, cwd, env, logFile) {
+    const handle = await open(logFile, 'a');
+    try {
+        return await new Promise((resolvePromise, rejectPromise) => {
+            const child = spawn(command, args, {
+                cwd,
+                env,
+                // The output goes to an open file descriptor rather than a pipe: a pipe
+                // is refused inside dsh's file sandbox, and there is nothing here that
+                // needs it — the tail of the file is what is shown.
+                stdio: ['ignore', handle.fd, handle.fd],
+                windowsHide: true,
+                shell: command.endsWith('.cmd'),
+            });
+            const timer = setTimeout(() => {
+                child.kill();
+                rejectPromise(new Error(`pnpm 在 ${INSTALL_TIMEOUT_MS / 60000} 分钟内没有跑完`));
+            }, INSTALL_TIMEOUT_MS);
+            child.on('error', cause => {
+                clearTimeout(timer);
+                rejectPromise(cause);
+            });
+            child.on('close', exitCode => {
+                clearTimeout(timer);
+                resolvePromise(exitCode ?? 1);
+            });
+        });
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}

package/lib/paths.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Where this plugin's files live. A DSH installation has exactly one active
+ * profile directory at a time — the profile whose `cordis.patch.yml` holds the
+ * model catalog and whose `package.json` lists the installed plugins — so the
+ * profile directory is resolved once, from the composition's own environment,
+ * and everything else is derived from it.
+ *
+ * Resolution order mirrors `dsh-git-branch/src/settings.ts`: an explicit value
+ * wins, then `$DSH_HOME`, then `~/.dsh`. A blank string counts as unset.
+ */
+/** Every path this plugin resolves, computed once per call site. */
+export interface ResolvedPaths {
+    /** The active profile directory, or the best guess at one. */
+    profileDir: string;
+    /** Where this plugin keeps its configuration and sync state. */
+    stateDir: string;
+    /** The profile patch holding the model catalog and the other patch rows. */
+    patchFile: string;
+    /** The profile manifest holding the installed-plugin list. */
+    packageFile: string;
+    /** Legacy composition file, read only to seed a first sync when the patch is empty. */
+    baseFile: string;
+}
+/** The environment variable DSH sets to the running profile's directory. */
+export declare const ENV_PROFILE_DIR = "DSH_PROFILE_DIR";
+/** The environment variable DSH sets to its home directory. */
+export declare const ENV_HOME = "DSH_HOME";
+/** The environment variable DSH sets to the running profile's name. */
+export declare const ENV_PROFILE = "DSH_PROFILE";
+/** Directory name this plugin owns inside the profile directory. */
+export declare const STATE_DIR_NAME = ".dsh-webdav-sync";
+/**
+ * `true` when a candidate would be read as unset: absent, not a string, or
+ * nothing but whitespace.
+ */
+export declare function blank(value: string | undefined | null): boolean;
+/**
+ * The profile directory in force.
+ *
+ * `DSH_PROFILE_DIR` is authoritative when the composition set it. Without it,
+ * `$DSH_HOME/profiles/<DSH_PROFILE>` is used; without that, `~/.dsh/profiles/desktop`.
+ */
+export declare function resolveProfileDir(configured: string | undefined, env?: NodeJS.ProcessEnv): string;
+/**
+ * The DSH home directory: `$DSH_HOME` when it names an absolute path, `~/.dsh`
+ * otherwise. A blank value counts as unset.
+ */
+export declare function resolveHome(env?: NodeJS.ProcessEnv): string;
+/** Every path derived from one profile directory. */
+export declare function resolvePaths(profileDir: string): ResolvedPaths;
+/** Resolve everything from the environment in one call. */
+export declare function resolveFromEnv(configured: string | undefined, env?: NodeJS.ProcessEnv): ResolvedPaths;
+/**
+ * Reject a profile directory the plugin cannot work in, with the reason, so a
+ * misconfiguration is reported where it is set rather than at the first sync.
+ */
+export declare function validateProfileDir(profileDir: string): void;

package/lib/paths.js

@@ -0,0 +1,79 @@
+/**
+ * Where this plugin's files live. A DSH installation has exactly one active
+ * profile directory at a time — the profile whose `cordis.patch.yml` holds the
+ * model catalog and whose `package.json` lists the installed plugins — so the
+ * profile directory is resolved once, from the composition's own environment,
+ * and everything else is derived from it.
+ *
+ * Resolution order mirrors `dsh-git-branch/src/settings.ts`: an explicit value
+ * wins, then `$DSH_HOME`, then `~/.dsh`. A blank string counts as unset.
+ */
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+/** The environment variable DSH sets to the running profile's directory. */
+export const ENV_PROFILE_DIR = 'DSH_PROFILE_DIR';
+/** The environment variable DSH sets to its home directory. */
+export const ENV_HOME = 'DSH_HOME';
+/** The environment variable DSH sets to the running profile's name. */
+export const ENV_PROFILE = 'DSH_PROFILE';
+/** Directory name this plugin owns inside the profile directory. */
+export const STATE_DIR_NAME = '.dsh-webdav-sync';
+/**
+ * `true` when a candidate would be read as unset: absent, not a string, or
+ * nothing but whitespace.
+ */
+export function blank(value) {
+    return typeof value !== 'string' || value.trim() === '';
+}
+/**
+ * The profile directory in force.
+ *
+ * `DSH_PROFILE_DIR` is authoritative when the composition set it. Without it,
+ * `$DSH_HOME/profiles/<DSH_PROFILE>` is used; without that, `~/.dsh/profiles/desktop`.
+ */
+export function resolveProfileDir(configured, env = process.env) {
+    if (!blank(configured) && isAbsolute(configured.trim()))
+        return resolve(configured.trim());
+    const named = env[ENV_PROFILE_DIR];
+    if (!blank(named) && isAbsolute(named.trim()))
+        return resolve(named.trim());
+    const home = resolveHome(env);
+    const profile = blank(env[ENV_PROFILE]) ? 'desktop' : env[ENV_PROFILE].trim();
+    return join(home, 'profiles', profile);
+}
+/**
+ * The DSH home directory: `$DSH_HOME` when it names an absolute path, `~/.dsh`
+ * otherwise. A blank value counts as unset.
+ */
+export function resolveHome(env = process.env) {
+    const home = env[ENV_HOME];
+    if (!blank(home) && isAbsolute(home.trim()))
+        return resolve(home.trim());
+    return join(homedir(), '.dsh');
+}
+/** Every path derived from one profile directory. */
+export function resolvePaths(profileDir) {
+    const dir = resolve(profileDir);
+    return {
+        profileDir: dir,
+        stateDir: join(dir, STATE_DIR_NAME),
+        patchFile: join(dir, 'cordis.patch.yml'),
+        packageFile: join(dir, 'package.json'),
+        baseFile: join(dir, 'cordis.yml'),
+    };
+}
+/** Resolve everything from the environment in one call. */
+export function resolveFromEnv(configured, env = process.env) {
+    return resolvePaths(resolveProfileDir(configured, env));
+}
+/**
+ * Reject a profile directory the plugin cannot work in, with the reason, so a
+ * misconfiguration is reported where it is set rather than at the first sync.
+ */
+export function validateProfileDir(profileDir) {
+    if (blank(profileDir))
+        throw new Error('WebdavSyncConfig：「profileDir」必须是非空字符串');
+    if (!isAbsolute(profileDir.trim())) {
+        throw new Error(`WebdavSyncConfig：「profileDir」必须是绝对路径，收到的是「${profileDir}」`);
+    }
+}

package/lib/state.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 { type Part, type StoredState, type SyncConfig } from './wire.js';
+import type { ResolvedPaths } from './paths.js';
+/** Name of the configuration file inside the state directory. */
+export declare const CONFIG_NAME = "sync.json";
+/** Name of the sync state file. */
+export declare const STATE_NAME = "sync-state.json";
+/** Name of the cached copy of the server's file. */
+export declare const CACHE_NAME = "sync-server.dshsync";
+/** Name of the directory holding copies the sync replaced. */
+export declare const KEPT_DIR = "sync";
+/** The configuration as first written, before anything is known. */
+export declare function defaultConfig(): SyncConfig;
+/** The configuration file's path. */
+export declare function configFile(paths: ResolvedPaths): string;
+/** The sync state file's path. */
+export declare function stateFile(paths: ResolvedPaths): string;
+/** The cached server copy's path. */
+export declare function cacheFile(paths: ResolvedPaths): string;
+/** The folder replaced copies are kept in. */
+export declare function keptDir(paths: ResolvedPaths): string;
+/** Keep a password in memory only, for the profile it was given for. */
+export declare function holdPassword(paths: ResolvedPaths, password: string): void;
+/** Forget the in-memory password for a profile, on turning sync off or remembering again. */
+export declare function releasePassword(paths: ResolvedPaths): void;
+/** The in-memory password for a profile, if one is being held. */
+export declare function heldPassword(paths: ResolvedPaths): string | undefined;
+/**
+ * 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 declare function loadConfig(paths: ResolvedPaths): Promise<{
+    config: SyncConfig;
+    found: boolean;
+}>;
+/** Read the sync state; an empty one only when there is none. */
+export declare function loadState(paths: ResolvedPaths): Promise<StoredState>;
+/** Write the configuration, 0600 because it holds two secrets. */
+export declare function saveConfig(paths: ResolvedPaths, config: SyncConfig): Promise<void>;
+/** Write the state. It holds no secret, but it does name a folder, so it is 0600 too. */
+export declare function saveState(paths: ResolvedPaths, state: StoredState): Promise<void>;
+/** Write the state directory itself, 0700, before anything goes in it. */
+export declare function ensureStateDir(paths: ResolvedPaths): Promise<void>;
+/** Keep the body just read or written, so the next sync can merge without it. */
+export declare function remember(paths: ResolvedPaths, data: Uint8Array): Promise<void>;
+/**
+ * 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 declare function cached(paths: ResolvedPaths, want: string | undefined): Promise<Uint8Array | 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 declare function stateKey(config: SyncConfig): string;
+/**
+ * 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 declare function sameAccount(a: SyncConfig, b: SyncConfig): boolean;
+/** An address with its trailing slashes gone, for comparing two of them. */
+export declare function normaliseUrl(url: string): string;
+/**
+ * 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 declare function usable(config: SyncConfig): boolean;
+/** Whether a part travels with this configuration. */
+export declare function syncsPart(config: SyncConfig, part: Part): boolean;
+/** Fill in defaults and coerce the several fields that come from a browser. */
+export declare function normaliseConfig(raw: Record<string, unknown>): SyncConfig;