shipwatch 0.1.0

package/src/client.js

@@ -0,0 +1,196 @@
+/** Local daemon client: private Unix socket requests and detached bootstrap.
+ * Exports paths/request/ensureDaemon. Supported CLI hosts: macOS and Linux (Windows via WSL).
+ */
+import net from 'node:net';
+import { validName } from './config.js';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, open, readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+
+/** SHIPWATCH_HOME isolates registries/logs for separate users and test runs. */
+export function paths() {
+  const home = path.resolve(process.env.SHIPWATCH_HOME || path.join(os.homedir(), '.shipwatch'));
+  return { home, socket: path.join(home, 'daemon.sock'), registry: path.join(home, 'tasks.json'), lock: path.join(home, 'daemon.lock'), logs: path.join(home, 'logs') };
+}
+
+/** Exactly one JSON response per connection, capped to avoid unbounded local IPC buffers. */
+export function request(action, params = {}, { timeoutMs } = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(paths().socket);
+    let response = '';
+    const fail = (error) => { socket.destroy(); reject(error); };
+    // Queries must fail promptly even when an older daemon queues them behind a stalled stop.
+    const query = ['ping', 'list', 'status'].includes(action);
+    socket.setTimeout(timeoutMs ?? (query ? 5000 : 120000), () => fail(Object.assign(new Error(query ? '后台进程 5 秒内未响应，可能正在阻塞；请检查后台日志并重启后台进程' : 'Daemon request timed out'), { code: 'ETIMEDOUT' })));
+    socket.on('error', fail);
+    socket.on('connect', () => socket.write(JSON.stringify({ action, ...params }) + '\n'));
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk) => {
+      response += chunk;
+      if (response.length > 16 * 1024 * 1024) return fail(new Error('Daemon response too large'));
+      if (response.includes('\n')) {
+        socket.end();
+        try {
+          const reply = JSON.parse(response.slice(0, response.indexOf('\n')));
+          if (reply.error) reject(new Error(reply.error)); else resolve(reply.result);
+        } catch (error) { reject(error); }
+      }
+    });
+    socket.on('end', () => { if (!response.includes('\n')) fail(Object.assign(new Error('Daemon closed without a response'), { code: 'ECONNRESET' })); });
+  });
+}
+
+/** Numeric targets are IDs; name:123 preserves access to existing numeric task names. */
+export function taskSelector(target) {
+  if (typeof target === 'string' && /^\d+$/.test(target)) {
+    const id = Number(target);
+    if (!Number.isSafeInteger(id)) throw new Error('无效的任务 ID');
+    return { id };
+  }
+  const name = typeof target === 'string' && target.startsWith('name:') ? target.slice(5) : target;
+  if (!validName(name)) throw new Error('A valid task name is required（请输入任务名称或 ID）');
+  return { name };
+}
+
+/** Guard resident older daemons rather than interpreting row indexes as task identities. */
+export async function requestTask(action, target, params = {}) {
+  const selector = taskSelector(target);
+  if (selector.id !== undefined && !(await request('ping')).capabilities?.includes('task-id')) throw new Error('当前后台进程不支持任务 ID，请重启后台进程后再试');
+  return request(action, { ...params, ...selector });
+}
+
+/** Clear all tasks, loading an offline registry without resuming deployments; wait for lock release. */
+export async function killDaemon() {
+  let result;
+  let daemon;
+  try { daemon = await request('ping'); }
+  catch (error) {
+    if (['ETIMEDOUT', 'ECONNRESET'].includes(error.code)) return recoverKill();
+    if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error;
+    // Use the daemon lock and persistence path even offline, without restarting saved tasks.
+    await ensureDaemon({ resume: false });
+    daemon = await request('ping');
+  }
+  if (!Number.isInteger(daemon.pid) || daemon.pid <= 0) throw new Error('Invalid daemon identity');
+  try {
+    if (Array.isArray(daemon.capabilities) && daemon.capabilities.includes('kill-clear')) result = await request('kill', {}, { timeoutMs: 30000 });
+    else {
+      // Updating files cannot update a resident process. Older daemons understand delete/shutdown,
+      // but route unknown kill requests through their required-name validation.
+      const tasks = await request('list');
+      for (const task of tasks) await request('delete', { name: task.name }, { timeoutMs: 30000 });
+      await request('shutdown', {}, { timeoutMs: 30000 });
+      result = { pid: daemon.pid, stoppedTasks: tasks.length, message: 'All tasks stopped and removed', legacyDaemon: true };
+    }
+  } catch (error) {
+    if (['ETIMEDOUT', 'ECONNRESET'].includes(error.code)) return recoverKill(daemon.pid);
+    throw error;
+  }
+  const deadline = Date.now() + 60000;
+  while (Date.now() < deadline) {
+    try {
+      const owner = JSON.parse(await readFile(paths().lock, 'utf8'));
+      if (owner.pid !== result.pid) return result;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      if (!daemon.capabilities?.includes('kill-reset-id')) await resetLegacyCounter();
+      return result;
+    }
+    await delay(50);
+  }
+  return recoverKill(daemon.pid);
+}
+
+/** Older daemons clear tasks but retain IDs; reserve their lock before resetting the empty registry's counter. */
+async function resetLegacyCounter() {
+  const locations = paths();
+  const lock = await open(locations.lock, 'wx', 0o600);
+  const counter = path.join(locations.home, 'next-task-id.json');
+  try {
+    await lock.writeFile(JSON.stringify({ pid: process.pid }));
+    const tasks = JSON.parse(await readFile(locations.registry, 'utf8'));
+    if (!Array.isArray(tasks) || tasks.length) throw new Error('任务列表未清空，不能重置 ID');
+    await writeFile(counter + '.tmp', '0', { mode: 0o600 });
+    await rename(counter + '.tmp', counter);
+  } finally { await lock.close(); await unlink(locations.lock); }
+}
+
+/** Read process ownership and parentage without matching or killing unrelated Node programs. */
+async function processTable() {
+  const { stdout } = await promisify(execFile)('ps', ['-axo', 'pid=,ppid=,uid=,stat=,command='], { timeout: 5000, maxBuffer: 16 * 1024 * 1024 });
+  return stdout.trim().split('\n').map((line) => {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+    return match && { pid: Number(match[1]), parent: Number(match[2]), uid: Number(match[3]), state: match[4], command: match[5] };
+  }).filter(Boolean);
+}
+
+/** Force only the lock-owning daemon and its descendants, then clear records without resuming tasks. */
+async function recoverKill(expectedPid) {
+  const owner = JSON.parse(await readFile(paths().lock, 'utf8'));
+  if (!Number.isSafeInteger(owner.pid) || owner.pid <= 1 || owner.pid === process.pid || (expectedPid !== undefined && expectedPid !== owner.pid)) throw new Error('后台进程身份已变化，已取消强制结束');
+  const daemonFile = fileURLToPath(new URL('./daemon.js', import.meta.url));
+  const rows = await processTable();
+  const root = rows.find((row) => row.pid === owner.pid);
+  if (root) {
+    if (root.uid !== process.getuid() || ![`${process.execPath} ${daemonFile}`, `${process.execPath} ${daemonFile} --no-resume`].includes(root.command)) throw new Error('无法确认后台进程身份，拒绝结束其它进程');
+    process.stderr.write('后台停止超时，正在结束全部监听进程并清空任务列表…\n');
+    const frozen = new Map();
+    try {
+      // Freeze parents before discovery so SSH children cannot be orphaned by killing the daemon first.
+      process.kill(root.pid, 'SIGSTOP'); frozen.set(root.pid, root);
+      for (let pass = 0; pass < 20; pass++) {
+        const current = await processTable();
+        const children = current.filter((row) => row.uid === root.uid && frozen.has(row.parent) && !frozen.has(row.pid));
+        if (!children.length) break;
+        for (const child of children) {
+          try { process.kill(child.pid, 'SIGSTOP'); frozen.set(child.pid, child); }
+          catch (error) { if (error.code !== 'ESRCH') throw error; }
+        }
+        if (pass === 19) throw new Error('后台子进程层级异常，取消强制结束');
+      }
+      if (JSON.parse(await readFile(paths().lock, 'utf8')).pid !== owner.pid) throw new Error('后台进程身份已变化');
+      const targets = [...frozen.values()].reverse();
+      for (const proc of targets) {
+        try { process.kill(proc.pid, 'SIGKILL'); }
+        catch (error) { if (error.code !== 'ESRCH') throw error; }
+        frozen.delete(proc.pid);
+      }
+      await delay(100);
+      const alive = (await processTable()).filter((row) => targets.some((target) => target.pid === row.pid && target.command === row.command) && !row.state.startsWith('Z'));
+      if (alive.length) throw new Error('后台进程尚未退出，任务记录保留');
+    } finally {
+      for (const proc of frozen.values()) {
+        try { process.kill(proc.pid, 'SIGCONT'); } catch (error) { if (error.code !== 'ESRCH') throw error; }
+      }
+    }
+  }
+  await ensureDaemon({ resume: false });
+  return { ...await killDaemon(), forced: true };
+}
+
+/** Start a detached daemon only when no responsive one exists; concurrent starts converge on its lock. */
+export async function ensureDaemon({ resume = true } = {}) {
+  try { await request('ping'); return; } catch (error) { if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error; }
+  const locations = paths();
+  if (Buffer.byteLength(locations.socket) > 100) throw new Error('SHIPWATCH_HOME is too long for a Unix socket; choose a shorter path');
+  await mkdir(locations.home, { recursive: true, mode: 0o700 });
+  const logfile = await open(path.join(locations.home, 'daemon.log'), 'a', 0o600);
+  const child = spawn(process.execPath, [fileURLToPath(new URL('./daemon.js', import.meta.url)), ...(resume ? [] : ['--no-resume'])], {
+    detached: true, stdio: ['ignore', logfile.fd, logfile.fd], env: process.env,
+  });
+  let spawnError;
+  child.on('error', (error) => { spawnError = error; });
+  child.unref();
+  await logfile.close();
+  for (let count = 0; count < 50; count++) {
+    if (spawnError) throw spawnError;
+    await delay(100);
+    try { await request('ping'); return; } catch (error) { if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error; }
+  }
+  const log = await readFile(path.join(locations.home, 'daemon.log'), 'utf8');
+  throw new Error(`Daemon failed to start: ${log.slice(-2000)}`);
+}

package/src/config-editor.js

@@ -0,0 +1,190 @@
+/** Interactive configuration editor: named files, validated fields, masked secrets and atomic saves.
+ * Exports editConfiguration/updateDeployMode/openPrompts/collectPasswords; uses readline and the shared validator.
+ */
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { readFile, writeFile, rename, unlink, lstat, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { defaultConfig, DEFAULT_CONFIG, validName, validateConfig, projectDefinitions, validateConfiguration } from './config.js';
+import { colorLevel, tint, gradient, notice } from './terminal.js';
+
+/** Named configs never alias the default file and cannot escape the current directory. */
+export function namedConfig(name) {
+  const stem = name?.endsWith('.shipwatch.config.json') ? name.slice(0, -'.shipwatch.config.json'.length) : name;
+  if (!validName(stem) || name === DEFAULT_CONFIG || stem === 'shipwatch') throw new Error('Use a distinct configuration name, e.g. shipwatch add production');
+  return { filename: path.resolve(`${stem}.shipwatch.config.json`), name: stem };
+}
+
+/** Queue readline input so pasted/piped answers are not lost; hide secret echoes on a TTY. */
+export function openPrompts(input = process.stdin, output = process.stdout) {
+  let muted = false;
+  const terminal = Boolean(input.isTTY);
+  const level = colorLevel(output);
+  const writer = new Writable({ write(chunk, encoding, done) { if (!muted) output.write(chunk, encoding); done(); } });
+  const reader = createInterface({ input, output: writer, terminal, historySize: 0 });
+  const answers = reader[Symbol.asyncIterator]();
+  reader.on('SIGINT', () => reader.close());
+  return {
+    async ask(label, { secret = false } = {}) {
+      muted = secret;
+      output.write(tint((level ? '❯ ' : '') + label, secret ? 'yellow' : 'cyan', level) + ': ');
+      const answer = await answers.next();
+      muted = false;
+      if (secret && terminal) output.write('\n');
+      if (answer.done) throw new Error('Input canceled or ended; configuration was not saved');
+      return answer.value;
+    },
+    section(message) { output.write(level ? '\n' + gradient(`◈ ${message}`, level) + '\n\n' : `  ${message}\n`); },
+    error(message) { output.write(`  ${notice(message, 'yellow', output)}\n`); },
+    close() { reader.close(); },
+  };
+}
+
+/** Required fields retry in place, and Enter retains a displayed valid default during editing. */
+async function field(prompts, label, previous, check) {
+  while (true) {
+    const value = (await prompts.ask(`${label}${previous !== undefined ? ` [${previous}]` : ''}`)).trim() || previous;
+    try {
+      if (value === undefined || value === '') throw new Error('此项必填');
+      await check?.(value);
+      return value;
+    } catch (error) { prompts.error(error.message); }
+  }
+}
+
+/** Configure new or existing servers without discarding retry, exclusion or other advanced settings. */
+export async function editConfiguration(filename, { name, editing = false, append = false, projectName, directory, prompts = openPrompts() } = {}) {
+  let original;
+  let raw;
+  let document;
+  let projects;
+  try {
+    if (editing || append) {
+      try {
+        const metadata = await lstat(filename);
+        if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error('Configuration must be a regular file');
+        original = await readFile(filename, 'utf8');
+      } catch (error) { if (!append || error.code !== 'ENOENT') throw error; }
+      if (original !== undefined) {
+        document = JSON.parse(original);
+        projects = projectDefinitions(document);
+      } else { document = { projects: [] }; projects = document.projects; }
+      if (append) {
+        if (projects.length >= 100) throw new Error('配置最多支持 100 个项目');
+        if (!Object.hasOwn(document, 'projects')) document = { projects: [document] };
+        projects = document.projects;
+        raw = defaultConfig(directory ?? '.');
+        projects.push(raw);
+      } else {
+        const selected = projectName ?? (projects.length === 1 ? projects[0].name : await field(prompts, `选择要编辑的项目（${projects.map((item) => item.name).join('、')}）`, undefined, (value) => {
+          if (!projects.some((item) => item.name === value)) throw new Error('请输入配置中的项目名称');
+        }));
+        raw = projects.find((item) => item.name === selected);
+        if (!raw) throw new Error(`配置中未找到项目 ${selected}`);
+        if (!Array.isArray(raw.servers) || !raw.servers.length) throw new Error('Invalid existing configuration');
+      }
+    } else {
+      try { await lstat(filename); throw new Error('Configuration already exists; use edit'); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      raw = defaultConfig(directory ?? '.'); raw.name = name ?? 'app';
+      document = raw; projects = [raw];
+    }
+    prompts.section?.('项目设置');
+    if (!editing && name === undefined) {
+      raw.name = await field(prompts, '任务名称 name（必填）', undefined, (value) => {
+        if (!validName(value)) throw new Error('名称需以字母或数字开头，仅含字母、数字、_、-，最多 64 字符');
+        if (projects.some((item) => item !== raw && item.name === value)) throw new Error('项目名称不能重复');
+      });
+    }
+    raw.directory = await field(prompts, '本地监听目录（必填，相对于配置文件）', raw.directory, async (value) => {
+      if (!(await stat(await realpath(path.resolve(path.dirname(filename), value)))).isDirectory()) throw new Error('请选择存在的目录');
+    });
+    for (let index = 0; index < raw.servers.length; index++) {
+      const server = raw.servers[index];
+      (prompts.section ?? prompts.error).call(prompts, `服务器 ${index + 1}: ${server.name}`);
+      server.host = await field(prompts, '服务器地址（必填）', server.host === 'CHANGE_ME' ? undefined : server.host, (value) => {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/.test(value) || value === 'CHANGE_ME') throw new Error('请输入有效主机名或 IPv4 地址');
+      });
+      server.user = await field(prompts, 'SSH 用户名（必填）', server.user, (value) => {
+        if (!/^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(value)) throw new Error('SSH 用户名格式无效');
+      });
+      server.port = Number(await field(prompts, 'SSH 端口（必填）', String(server.port ?? 22), (value) => {
+        if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 65535) throw new Error('端口必须为 1..65535 的整数');
+      }));
+      server.platform = await field(prompts, '服务器系统 linux/windows（必填）', server.platform ?? 'linux', (value) => {
+        if (!['linux', 'windows'].includes(value)) throw new Error('请输入 linux 或 windows');
+      });
+      // Reuse full target validation while isolating this server from other unfinished form entries.
+      server.path = await field(prompts, '服务器目标目录（必填）', editing ? server.path : undefined, async (value) => {
+        await validateConfig({ ...raw, servers: [{ ...server, path: value }] }, filename);
+      });
+      const password = await prompts.ask(`密码（可选${server.password ? '；留空保留已保存密码' : server.passwordPrompt ? '；留空保留启动时输入' : '；留空使用密钥/Agent'}；:prompt 启动时输入；:clear 清除；输入新密码会保存到配置）`, { secret: true });
+      if (password === ':clear') { delete server.password; delete server.passwordPrompt; }
+      else if (password === ':prompt') { delete server.password; server.passwordPrompt = true; }
+      else if (password) {
+        if (/[\r\n\0]/.test(password)) throw new Error('密码不能包含换行或空字符');
+        server.password = password; delete server.passwordPrompt;
+      }
+      const command = await prompts.ask(`更新成功后执行的服务命令（可选；留空${server.postDeployCommand ? `保留 ${server.postDeployCommand}` : '跳过'}；:clear 清除）`);
+      if (command === ':clear') delete server.postDeployCommand;
+      else if (command.trim()) server.postDeployCommand = command.trim();
+      if (index === raw.servers.length - 1) {
+        const more = await field(prompts, '继续添加服务器？y/n', 'n', (value) => { if (!['y', 'n'].includes(value.toLowerCase())) throw new Error('请输入 y 或 n'); });
+        if (more.toLowerCase() === 'y') {
+          const names = new Set(raw.servers.map((item) => item.name));
+          let next = raw.servers.length + 1;
+          while (names.has(`server-${next}`)) next++;
+          raw.servers.push({ name: `server-${next}`, host: 'CHANGE_ME', user: 'deploy', port: 22, platform: 'linux' });
+        }
+      }
+    }
+    await validateConfiguration(document, filename);
+    const content = JSON.stringify(document, null, 2) + '\n';
+    if (original === undefined) await writeFile(filename, content, { flag: 'wx', mode: 0o600 });
+    else {
+      if (await readFile(filename, 'utf8') !== original) throw new Error('Configuration changed while editing; reopen it');
+      const temporary = `${filename}.${randomBytes(8).toString('hex')}.tmp`;
+      await writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+      try { await rename(temporary, filename); }
+      finally { await unlink(temporary).catch((error) => { if (error.code !== 'ENOENT') throw error; }); }
+    }
+    return filename;
+  } finally { prompts.close(); }
+}
+
+/** Persist only the selected project's mode, preserving sibling projects and credentials. */
+export async function updateDeployMode(filename, projectName, mode) {
+  if (!['auto', 'manual'].includes(mode)) throw new Error('部署模式必须为 auto 或 manual');
+  const metadata = await lstat(filename);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error('Configuration must be a regular file');
+  const original = await readFile(filename, 'utf8');
+  const document = JSON.parse(original);
+  const project = projectDefinitions(document).find((item) => item.name === projectName);
+  if (!project) throw new Error(`配置中未找到项目 ${projectName}`);
+  project.deployMode = mode;
+  const temporary = `${filename}.${randomBytes(8).toString('hex')}.tmp`;
+  await writeFile(temporary, JSON.stringify(document, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  try {
+    if (await readFile(filename, 'utf8') !== original) throw new Error('Configuration changed while editing; reopen it');
+    await rename(temporary, filename);
+  } finally { await unlink(temporary).catch((error) => { if (error.code !== 'ENOENT') throw error; }); }
+}
+
+/** Runtime passwords stay in CLI/daemon memory and never enter the persistent task registry. */
+export async function collectPasswords(config, force = false, promptsFactory = openPrompts) {
+  const passwords = Object.create(null);
+  const servers = config.servers.filter((server) => force || server.passwordPrompt);
+  if (!servers.length) return passwords;
+  const prompts = promptsFactory();
+  try {
+    for (const server of servers) {
+      let password;
+      do { password = await prompts.ask(`${config.name} / ${server.name} (${server.user}@${server.host}) 密码`, { secret: true }); }
+      while (!password || /[\r\n\0]/.test(password));
+      passwords[server.name] = password;
+      server.password = password;
+    }
+  } finally { prompts.close(); }
+  return passwords;
+}

package/src/config.js

@@ -0,0 +1,118 @@
+/** Configuration boundary: parse JSON, normalize paths and reject unsafe deployment targets.
+ * Exports loadConfig/defaultConfig; depends only on Node filesystem/path APIs.
+ */
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+/** Defaults favor avoiding accidental secret publication; user exclusions are additive. */
+export const DEFAULT_CONFIG = 'shipwatch.config.json';
+export const DEFAULT_EXCLUDES = ['.git', 'node_modules', '.env', '.env.*', '*.pem', '*.key', '.shipwatch', 'shipwatch-snapshot-*', '.shipwatch-manifest.json', 'shipwatch.config.json', 'shipwatch.config', '*.shipwatch.config', '*.shipwatch.config.*', 'shipwatch.config.*'];
+export const validName = (name) => typeof name === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name);
+
+/** Create an editable template; host is deliberately invalid until the operator configures it. */
+export function defaultConfig(directory = '.') {
+  return { name: 'app', directory, deployMode: 'auto', intervalMs: 1000, debounceMs: 800, retry: { attempts: 3, delayMs: 1000 },
+    keepReleases: 5, timeoutMs: 120000, exclude: [],
+    servers: [{ name: 'production', host: 'CHANGE_ME', user: 'deploy', port: 22, platform: 'linux', path: '/srv/app' }] };
+}
+
+/** Integer settings are bounded so malformed config cannot create infinite retries or busy loops. */
+function integer(value, fallback, min, max, field) {
+  const result = value ?? fallback;
+  if (!Number.isInteger(result) || result < min || result > max) throw new Error(`${field} must be ${min}..${max}`);
+  return result;
+}
+
+/** Accept legacy single-project objects and explicit projects collections. */
+export function projectDefinitions(raw) {
+  const projects = raw && Object.hasOwn(raw, 'projects') ? raw.projects : [raw];
+  if (!Array.isArray(projects) || !projects.length || projects.length > 100) throw new Error('配置必须包含 1..100 个项目');
+  const names = new Set();
+  for (const project of projects) {
+    if (!validName(project?.name) || names.has(project.name)) throw new Error('项目名称必须有效且不能重复');
+    names.add(project.name);
+  }
+  return projects;
+}
+
+/** Validate the complete collection before any project can be started or a file saved. */
+export async function validateConfiguration(raw, configFile, directoryOverride) {
+  const projects = projectDefinitions(raw);
+  if (projects.length > 1 && directoryOverride !== undefined) throw new Error('多项目配置不能使用统一目录覆盖，请分别修改各项目 directory');
+  const configurations = [];
+  const sources = new Set();
+  for (const project of projects) {
+    const config = await validateConfig(project, configFile, directoryOverride);
+    const metadata = await stat(config.directory);
+    const identity = `${metadata.dev}:${metadata.ino}`;
+    if (sources.has(identity)) throw new Error('同一监听目录不能重复配置');
+    sources.add(identity); configurations.push(config);
+  }
+  return configurations;
+}
+
+/** Read one configuration file and normalize all of its projects. */
+export async function loadConfigs(filename, directoryOverride) {
+  const configFile = await realpath(filename);
+  return validateConfiguration(JSON.parse(await readFile(configFile, 'utf8')), configFile, directoryOverride);
+}
+
+/** Resolve a registered task by project name so sibling edits cannot switch its identity. */
+export async function loadConfig(filename, directoryOverride, projectName) {
+  const configFile = await realpath(filename);
+  const projects = projectDefinitions(JSON.parse(await readFile(configFile, 'utf8')));
+  if (projectName !== undefined) {
+    const project = projects.find((item) => item.name === projectName);
+    if (!project) throw new Error(`配置中未找到项目 ${projectName}`);
+    return validateConfig(project, configFile, directoryOverride);
+  }
+  if (projects.length !== 1) throw new Error('多项目配置需要指定项目名称');
+  return validateConfig(projects[0], configFile, directoryOverride);
+}
+
+/** Validate wizard drafts before writing them; the destination file need not exist yet. */
+export async function validateConfig(raw, configFile, directoryOverride) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Config must be an object');
+  if (!validName(raw.name)) throw new Error('Invalid task name (use letters, numbers, _ and -; max 64)');
+  if (typeof (raw.directory ?? '.') !== 'string') throw new Error('directory must be a string');
+  const directory = await realpath(directoryOverride ? path.resolve(directoryOverride) : path.resolve(path.dirname(configFile), raw.directory ?? '.'));
+  if (!(await stat(directory)).isDirectory()) throw new Error('Watch source must be a directory');
+  if (!Array.isArray(raw.servers) || raw.servers.length === 0 || raw.servers.length > 32) throw new Error('Configure 1..32 servers');
+  if (raw.exclude !== undefined && (!Array.isArray(raw.exclude) || raw.exclude.some((item) => typeof item !== 'string' || !item || item.includes('..') || item.includes('\\')))) throw new Error('exclude must contain relative glob strings');
+  if (raw.deployMode !== undefined && !['auto', 'manual'].includes(raw.deployMode)) throw new Error('deployMode 必须为 auto（自动）或 manual（手动）');
+  const names = new Set();
+  const targets = new Set();
+  const servers = raw.servers.map((server) => {
+    if (!server || !validName(server.name) || names.has(server.name)) throw new Error('Server names must be valid and unique');
+    names.add(server.name);
+    if (typeof server.host !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/.test(server.host) || server.host === 'CHANGE_ME') throw new Error(`Configure a valid SSH host for ${server.name}`);
+    if (typeof server.user !== 'string' || !/^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(server.user)) throw new Error(`Invalid SSH user for ${server.name}`);
+    const platform = server.platform ?? 'linux';
+    if (!['linux', 'windows'].includes(platform)) throw new Error('Server platform must be linux or windows');
+    if (typeof server.path !== 'string' || /[\x00-\x1f]/.test(server.path) || server.path.split(/[\\/]/).includes('..')) throw new Error('Invalid server path');
+    const paths = platform === 'windows' ? path.win32 : path.posix;
+    if (!paths.isAbsolute(server.path) || (platform === 'windows' && !/^[a-zA-Z]:[\\/]/.test(server.path))) throw new Error('Server path must be absolute (Windows requires a drive letter)');
+    const remotePath = paths.normalize(server.path);
+    if (remotePath.slice(paths.parse(remotePath).root.length).split(/[\\/]/).filter(Boolean).length < 2) throw new Error('Use an application subdirectory, e.g. /srv/app or C:\\apps\\web');
+    const port = integer(server.port, 22, 1, 65535, 'port');
+    const target = `${server.user}@${server.host}:${port}:${remotePath}`;
+    if (targets.has(target)) throw new Error('Duplicate server target');
+    targets.add(target);
+    if (server.identityFile !== undefined && typeof server.identityFile !== 'string') throw new Error('identityFile must be a string');
+    if (server.password !== undefined && (typeof server.password !== 'string' || /[\r\n\0]/.test(server.password))) throw new Error('password must be a single-line string');
+    if (server.passwordPrompt !== undefined && typeof server.passwordPrompt !== 'boolean') throw new Error('passwordPrompt must be boolean');
+    if (server.postDeployCommand !== undefined && (typeof server.postDeployCommand !== 'string' || /\0/.test(server.postDeployCommand) || server.postDeployCommand.length > 16384)) throw new Error('Invalid postDeployCommand');
+    return { name: server.name, host: server.host, user: server.user, path: remotePath, platform, port,
+      password: server.password || undefined, passwordPrompt: server.passwordPrompt ?? false,
+      postDeployCommand: server.postDeployCommand?.trim() || undefined,
+      identityFile: server.identityFile ? path.resolve(path.dirname(configFile), server.identityFile.replace(/^~\//, `${os.homedir()}/`)) : undefined };
+  });
+  return { name: raw.name, directory, configFile, servers, deployMode: raw.deployMode ?? 'auto',
+    exclude: [...DEFAULT_EXCLUDES, ...(raw.exclude ?? [])],
+    intervalMs: integer(raw.intervalMs, 1000, 100, 3600000, 'intervalMs'),
+    debounceMs: integer(raw.debounceMs, 800, 0, 60000, 'debounceMs'),
+    keepReleases: integer(raw.keepReleases, 5, 1, 1000, 'keepReleases'),
+    timeoutMs: integer(raw.timeoutMs, 120000, 100, 3600000, 'timeoutMs'),
+    retry: { attempts: integer(raw.retry?.attempts, 3, 1, 10, 'retry.attempts'), delayMs: integer(raw.retry?.delayMs, 1000, 10, 60000, 'retry.delayMs') } };
+}