shipwatch 0.1.0

package/src/progress.js

@@ -0,0 +1,108 @@
+/** Live deployment display: poll the queued round, render bounded terminal lines, then show its report.
+ * Exports followDeployment/renderProgress; uses daemon requests and the existing report formatter.
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { request } from './client.js';
+import { formatReport } from './presentation.js';
+import { fitLine } from './task-list.js';
+import { colorLevel, tint, gradient, stateTone } from './terminal.js';
+
+const phases = { queued: '等待发布', snapshot: '制作快照', connecting: '连接服务器', preparing: '比较文件', uploading: '传输文件', verifying: '校验文件', activating: '同步目标目录', command: '执行服务命令', pruning: '整理版本', cleanup: '清理', retrying: '等待重试', success: '成功', failed: '失败', canceled: '已取消' };
+
+/** Percent describes files passed to SSH, never a fabricated percentage of the whole release. */
+export function renderProgress(progress, columns = 80) {
+  const servers = Object.values(progress?.servers ?? {});
+  const known = servers.length && servers.every((server) => Number.isInteger(server.totalFiles));
+  const total = servers.reduce((sum, server) => sum + (server.totalFiles ?? 0), 0);
+  const sent = servers.reduce((sum, server) => sum + (server.transferredFiles ?? 0), 0);
+  const ratio = known ? total ? Math.min(1, sent / total) : 1 : 0;
+  const fill = Math.floor(ratio * 10);
+  const bar = '[' + '#'.repeat(fill) + '-'.repeat(10 - fill) + ']';
+  const phase = progress?.phase === 'deploying' ? [...new Set(servers.map((server) => phases[server.phase] ?? server.phase))].join('/') : phases[progress?.phase] ?? '等待发布';
+  const value = `${phase} ${bar} ${known ? `${sent}/${total}` : '?/?'} 文件`;
+  // A conservative two-cell budget handles CJK in narrow terminals without wrapping cursor updates.
+  const limit = Math.max(1, Math.floor(((columns || 80) - 1) / 2));
+  const chars = Array.from(value);
+  return chars.length > limit ? chars.slice(0, Math.max(0, limit - 1)).join('') + '…' : value;
+}
+
+/** Render the approved per-server view within the terminal's dimensions; no invented overall percentage. */
+export function renderDeploymentFrame(task, ticket, { columns = 80, rows = 24, elapsed = 0, now = Date.now(), tick = 0, level = colorLevel() } = {}) {
+  const progress = task.deploySequence < ticket.sequence ? { phase: 'queued' } : task.progress;
+  const limit = Math.max(1, rows - 2);
+  if (columns < 40 || limit < 10) return [tint(fitLine(renderProgress(progress, columns), columns), 'cyan', level)];
+  const servers = Object.values(progress?.servers ?? {});
+  const order = { connecting: 0, preparing: 0, uploading: 1, verifying: 2, activating: 3, command: 3, pruning: 3, cleanup: 3, retrying: 1, failed: 3, canceled: 3, success: 4 };
+  const step = progress?.phase === 'deploying' && servers.length ? Math.min(...servers.map((server) => order[server.phase] ?? 0)) : progress?.phase === 'cleanup' ? 3 : 0;
+  const spin = Array.from('⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏')[tick % 10];
+  const lines = [gradient('SHIPWATCH', level) + tint('  v0.1.0', 'muted', level), '', tint(fitLine(`🚀 ${ticket.name} #${ticket.id} · ${servers.length || '…'} 台服务器`, columns), 'cyan', level, true)];
+  const steps = ['准备', '传输', '校验', '发布', '完成'];
+  const stageLine = steps.map((label, index) => `${index < step ? '✓ ' : ''}${label}`);
+  lines.push(columns < 60 ? tint(fitLine(stageLine.join(' › '), columns), 'cyan', level) : stageLine.map((label, index) => tint(label, index < step ? 'green' : index === step ? 'cyan' : 'muted', level)).join(tint(' › ', 'border', level)));
+  lines.push(tint(fitLine(`已用 ${elapsed.toFixed(1)} 秒${task.summary?.totalFiles !== undefined ? ` · ${task.summary.totalFiles} 个项目文件` : ''}`, columns), 'muted', level), '');
+  const visible = servers.slice(0, Math.max(1, Math.floor((limit - 9) / 3)));
+  for (const server of visible) {
+    const known = Number.isInteger(server.totalFiles);
+    const count = known ? `${server.transferredFiles ?? 0}/${server.totalFiles}` : '?/?';
+    const retry = server.phase === 'retrying' && Number.isFinite(server.retryAt) ? ` · ${Math.max(0, Math.ceil((server.retryAt - now) / 1000))} 秒后重试` : '';
+    const attempt = server.attempt > 1 || server.phase === 'retrying' ? ` · 尝试 ${server.attempt}/${server.attempts ?? '?'}` : '';
+    const tone = ['success', 'failed', 'canceled'].includes(server.phase) ? stateTone(server.phase) : server.phase === 'retrying' ? 'yellow' : 'cyan';
+    lines.push(tint(fitLine(`${server.phase === 'success' ? '✓' : server.phase === 'failed' ? '×' : spin} ${server.server} · ${phases[server.phase] ?? server.phase}${attempt}${retry}`, columns), tone, level));
+    const size = Math.max(4, Math.min(32, columns - count.length - 15));
+    const ratio = known ? server.totalFiles ? Math.min(1, (server.transferredFiles ?? 0) / server.totalFiles) : 1 : 0;
+    const filled = Math.floor(ratio * size);
+    lines.push('  ' + gradient('█'.repeat(filled), level) + tint('░'.repeat(size - filled), 'border', level) + `  ${count} 文件`, '');
+  }
+  if (!servers.length) lines.push(tint(`${spin} ${phases[progress?.phase] ?? '等待发布'}`, 'cyan', level), '');
+  if (visible.length < servers.length && lines.length + 2 <= limit) lines.push(tint(fitLine(`另有 ${servers.length - visible.length} 台服务器，完整结果将在结束后显示`, columns), 'muted', level));
+  lines.push(tint(fitLine('Ctrl+C 退出查看 · 后台继续发布', columns), 'muted', level));
+  return lines.slice(0, limit);
+}
+
+/** Ctrl+C detaches the display; it does not cancel a deployment owned by the background daemon. */
+export async function followDeployment(ticket, { json = false } = {}) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  const level = colorLevel();
+  const animated = level > 0 && !json;
+  const started = performance.now();
+  let tick = 0;
+  let screen = false;
+  // Alternate screen avoids damaging shell history on resize; always restore it before the final report.
+  const leaveScreen = () => {
+    if (screen) { process.stdout.write('\u001b[?25h\u001b[?1049l'); screen = false; }
+  };
+  let previous;
+  try {
+    while (!controller.signal.aborted) {
+      const task = await request('status', { id: ticket.id });
+      if (task.instanceId !== ticket.instanceId) throw new Error('任务已重启或替换，已退出进度查看');
+      const completed = task.completedReports?.find((item) => item.sequence === ticket.sequence);
+      if (completed) {
+        leaveScreen();
+        process.stdout.write(json ? JSON.stringify(completed.report, null, 2) + '\n' : formatReport(completed.report, process.stdout.columns));
+        if (completed.report.status !== 'success') process.exitCode = 1;
+        return;
+      }
+      if (!task.running) throw new Error('任务已停止，发布未完成');
+      if (task.deploySequence > ticket.sequence) throw new Error('该轮发布记录已过期，请查看项目日志');
+      const line = renderProgress(task.deploySequence < ticket.sequence ? { phase: 'queued' } : task.progress, process.stdout.columns);
+      if (animated) {
+        if (!screen) { process.stdout.write('\u001b[?1049h\u001b[?25l'); screen = true; }
+        const frame = renderDeploymentFrame(task, ticket, { columns: process.stdout.columns || 80, rows: process.stdout.rows || 24, elapsed: (performance.now() - started) / 1000, tick: tick++, level });
+        process.stdout.write('\u001b[H\u001b[2J' + frame.join('\n'));
+      } else if (!json && line !== previous) process.stdout.write(line + '\n');
+      previous = line;
+      await delay(250, undefined, { signal: controller.signal });
+    }
+  } catch (error) { if (!controller.signal.aborted) throw error; }
+  finally {
+    process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop);
+    leaveScreen();
+    if (controller.signal.aborted) {
+      if (!json) process.stdout.write('已退出进度查看，后台发布继续运行。\n');
+      process.exitCode = 130;
+    }
+  }
+}

package/src/remote-agent.cjs

@@ -0,0 +1,341 @@
+/** Remote agent for Linux and Windows: stage incremental files, SHA-256 verify, activate and prune.
+ * Entry: node agent.cjs ACTION BASE64_JSON. Requires Node >=22 and only builtin modules.
+ * This script is installed by content hash over SSH; all user data travels as JSON, never shell code.
+ */
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { createReadStream } = require('node:fs');
+const readline = require('node:readline');
+const { spawn } = require('node:child_process');
+
+/** Only Shipwatch-generated version names can address or delete releases. */
+const VERSION = /^\d{13}-[a-f0-9]{16}$/;
+
+/** Stream hash validation independently of the uploaded manifest's claims. */
+async function digest(filename) {
+  const hash = crypto.createHash('sha256');
+  for await (const chunk of createReadStream(filename)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+/** Missing files are expected for first deployments; other filesystem errors remain visible. */
+async function exists(filename) {
+  try { await fs.lstat(filename); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+/** Retention owns release directories and may remove read-only build artifacts without following links. */
+async function removeRelease(directory) {
+  if (!(await exists(directory))) return;
+  async function unlock(root) {
+    const metadata = await fs.lstat(root);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) return;
+    await fs.chmod(root, 0o700);
+    for (const name of await fs.readdir(root)) await unlock(path.join(root, name));
+  }
+  await unlock(directory);
+  await fs.rm(directory, { recursive: true, force: true });
+}
+
+/** Reject traversal and Windows reserved/ambiguous names on every platform. */
+function safeKey(key) {
+  if (typeof key !== 'string' || !key || key.split('/').some((part) => !part || part === '.' || part === '..' || /[\\:\x00-\x1f<>"|?*]/.test(part) || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) throw new Error(`Unsafe cross-platform filename: ${key}`);
+  return key;
+}
+
+/** Validate manifest schema before it can influence filesystem paths. */
+function validateManifest(manifest) {
+  if (manifest?.version !== 1 || !manifest.entries || typeof manifest.entries !== 'object' || Array.isArray(manifest.entries)) throw new Error('Invalid manifest');
+  const folded = new Set();
+  for (const [key, entry] of Object.entries(manifest.entries)) {
+    safeKey(key);
+    if (/^(?:current|releases)$/i.test(key.split('/')[0]) || /^\.(?:shipwatch-|next-|previous-|verified-|hook-started-)/i.test(key.split('/')[0])) throw new Error(`Reserved deployment filename: ${key}`);
+    const normalized = process.platform === 'win32' ? key.toLowerCase() : key;
+    if (folded.has(normalized)) throw new Error(`Case-colliding path: ${key}`);
+    folded.add(normalized);
+    if (!entry || !['file', 'directory'].includes(entry.type) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 511 || (entry.type === 'file' && !/^[a-f0-9]{64}$/.test(entry.sha256))) throw new Error(`Invalid manifest entry: ${key}`);
+  }
+}
+
+/** Materialize verified files in the configured directory, preserving files not managed by Shipwatch.
+ * Each file is replaced from a verified temporary copy. A whole multi-file update is not atomic.
+ */
+async function syncTarget(root, release, manifest, version) {
+  // A prior interrupted directory-to-file replacement can leave old child paths beneath a file.
+  const targetExists = async (filename) => {
+    try { return await exists(filename); } catch (error) { if (error.code === 'ENOTDIR') return false; throw error; }
+  };
+  const stateFile = path.join(root, '.shipwatch-live.json');
+  const previous = await exists(stateFile) ? JSON.parse(await fs.readFile(stateFile, 'utf8')) : { version: 1, entries: {} };
+  validateManifest(previous);
+  const allKeys = [...new Set([...Object.keys(previous.entries), ...Object.keys(manifest.entries)])];
+  // Reject links before making changes; an existing junction must never redirect writes outside root.
+  for (const key of allKeys) {
+    const parts = key.split('/');
+    for (let count = 1; count <= parts.length; count++) {
+      const filename = path.join(root, ...parts.slice(0, count));
+      if (!(await targetExists(filename))) break;
+      const metadata = await fs.lstat(filename);
+      if (metadata.isSymbolicLink() || (!metadata.isFile() && !metadata.isDirectory())) throw new Error(`Unsafe target entry: ${key}`);
+      if (!metadata.isDirectory()) break;
+    }
+  }
+  const depth = (key) => key.split('/').length;
+  // Temporarily unlock managed build directories so read-only artifacts can be updated or removed.
+  const originalModes = new Map();
+  try {
+    for (const key of allKeys.sort((a, b) => depth(a) - depth(b))) {
+      const filename = path.join(root, key);
+      let metadata;
+      try { metadata = await fs.lstat(filename); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) continue; throw error; }
+      if (metadata.isDirectory() && process.platform !== 'win32') {
+        originalModes.set(key, metadata.mode & 0o777);
+        await fs.chmod(filename, (metadata.mode & 0o777) | 0o700);
+      }
+    }
+    for (const key of Object.keys(previous.entries).sort((a, b) => depth(b) - depth(a))) {
+      if (manifest.entries[key]?.type === previous.entries[key].type) continue;
+      const filename = path.join(root, key);
+      if (!(await targetExists(filename))) continue;
+      const metadata = await fs.lstat(filename);
+      const actualType = metadata.isDirectory() ? 'directory' : 'file';
+      if (manifest.entries[key]?.type === actualType) continue;
+      if (metadata.isDirectory()) {
+        try { await fs.rmdir(filename); }
+        catch (error) { if (!manifest.entries[key] && ['ENOTEMPTY', 'EEXIST'].includes(error.code)) continue; throw error; }
+      } else await fs.unlink(filename);
+    }
+    for (const key of Object.keys(manifest.entries).sort((a, b) => depth(a) - depth(b))) {
+      const entry = manifest.entries[key];
+      const filename = path.join(root, key);
+      if (entry.type === 'directory') { await fs.mkdir(filename, { recursive: true }); continue; }
+      await fs.mkdir(path.dirname(filename), { recursive: true });
+      if (await targetExists(filename) && !(await fs.lstat(filename)).isFile()) throw new Error(`Target type conflict: ${key}`);
+      if (!(await targetExists(filename)) || await digest(filename) !== entry.sha256) {
+        const temporary = path.join(root, `.shipwatch-sync-${version}`);
+        try {
+          await fs.copyFile(path.join(release, key), temporary, fs.constants.COPYFILE_EXCL);
+          if (await digest(temporary) !== entry.sha256) throw new Error(`Target SHA-256 mismatch: ${key}`);
+          if (process.platform !== 'win32') await fs.chmod(temporary, entry.mode);
+          await fs.rename(temporary, filename);
+        } finally { await fs.rm(temporary, { force: true }); }
+      } else if (process.platform !== 'win32') await fs.chmod(filename, entry.mode);
+    }
+    const temporaryState = path.join(root, `.shipwatch-live-${version}`);
+    try {
+      await fs.writeFile(temporaryState, JSON.stringify(manifest), { flag: 'wx', mode: 0o600 });
+      await fs.rename(temporaryState, stateFile);
+    } finally { await fs.rm(temporaryState, { force: true }); }
+  } finally {
+    // Apply directory modes last: a read-only parent must not prevent copying its children.
+    if (process.platform !== 'win32') {
+      const directories = new Set([...originalModes.keys(), ...Object.keys(manifest.entries).filter((key) => manifest.entries[key].type === 'directory')]);
+      for (const key of [...directories].sort((a, b) => depth(b) - depth(a))) {
+        const filename = path.join(root, key);
+        let metadata;
+        try { metadata = await fs.lstat(filename); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) continue; throw error; }
+        if (metadata.isDirectory()) await fs.chmod(filename, manifest.entries[key]?.mode ?? originalModes.get(key));
+      }
+    }
+  }
+  process.stdout.write(`Synchronized target directory ${root}\n`);
+}
+
+/** Main operation; the lock token is a version id so one publisher cannot release another's lock. */
+async function main(action, options) {
+  const { root: requestedRoot, version, keep, platform } = options;
+  if (!VERSION.test(version) || !path.isAbsolute(requestedRoot) || path.resolve(requestedRoot) === path.parse(requestedRoot).root) throw new Error('Unsafe release location');
+  if ((process.platform === 'win32') !== (platform === 'windows')) throw new Error('Server platform does not match configuration');
+  if (action === 'prepare') await fs.mkdir(requestedRoot, { recursive: true });
+  if ((await fs.lstat(requestedRoot)).isSymbolicLink()) throw new Error('Deployment root cannot be a symlink');
+  // Canonicalize ancestors too: aliases such as /var -> /private/var must compare identically.
+  const root = await fs.realpath(requestedRoot);
+  const releases = path.join(path.dirname(root), `${path.basename(root)}-releases`);
+  const previousSibling = path.join(path.dirname(root), `${path.basename(root)}releases`);
+  const legacyReleases = path.join(root, 'releases');
+  // A sibling directory needs its own ownership claim; the old root marker cannot authorize it.
+  const releasesMarker = path.join(root, '.shipwatch-releases');
+  const ownsReleases = async () => await exists(releasesMarker) && await fs.readFile(releasesMarker, 'utf8') === releases;
+  const release = path.join(releases, version);
+  const current = path.join(root, 'current');
+  const lock = path.join(root, '.shipwatch-lock');
+  const marker = path.join(root, '.shipwatch-owned');
+  const manifestPath = path.join(release, '.shipwatch-manifest.json');
+  const assertLock = async () => {
+    if ((await fs.readFile(lock, 'utf8')) !== version) throw new Error('Release lock ownership mismatch');
+  };
+  const readManifest = async () => {
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    validateManifest(manifest);
+    return manifest;
+  };
+  if (action === 'prepare') {
+    let contents = '';
+    for await (const chunk of process.stdin) contents += chunk;
+    const manifest = JSON.parse(contents);
+    validateManifest(manifest);
+    await fs.mkdir(root, { recursive: true });
+    if ((await fs.lstat(root)).isSymbolicLink()) throw new Error('Deployment root cannot be a symlink');
+    await fs.writeFile(lock, version, { flag: 'wx', mode: 0o600 });
+    // Do not adopt an existing releases/current tree without an ownership marker.
+    if (!(await exists(marker))) {
+      if (await exists(releases) || await exists(legacyReleases) || await exists(current)) throw new Error('Unmanaged releases/current exists at target');
+      await fs.writeFile(marker, 'shipwatch-v1\n', { flag: 'wx' });
+    }
+    if ((await fs.readFile(marker, 'utf8')) !== 'shipwatch-v1\n') throw new Error('Invalid target ownership marker');
+    if (!(await ownsReleases())) {
+      if (await exists(releases)) throw new Error('Unmanaged sibling releases exists at target');
+      if (await exists(releasesMarker) && await fs.readFile(releasesMarker, 'utf8') !== previousSibling) throw new Error('Invalid releases ownership marker');
+      await fs.mkdir(releases);
+      await fs.writeFile(releasesMarker, releases);
+    } else await fs.mkdir(releases, { recursive: true });
+    if ((await fs.lstat(releases)).isSymbolicLink()) throw new Error('Releases directory cannot be a symlink');
+    await fs.mkdir(release);
+    let previous = {};
+    let previousRoot;
+    if (await exists(current)) {
+      if (!(await fs.lstat(current)).isSymbolicLink()) throw new Error('current must be a managed link');
+      previousRoot = await fs.realpath(current);
+      // Existing sites keep serving the old tree until the verified new release is activated.
+      const legacyParent = await exists(legacyReleases) && !(await fs.lstat(legacyReleases)).isSymbolicLink()
+        ? await fs.realpath(legacyReleases) : undefined;
+      if (![await fs.realpath(releases), legacyParent, previousSibling].includes(path.dirname(previousRoot)) || !VERSION.test(path.basename(previousRoot))) throw new Error('current points outside managed releases');
+      previous = JSON.parse(await fs.readFile(path.join(previousRoot, '.shipwatch-manifest.json'), 'utf8')).entries;
+    }
+    const wanted = [];
+    for (const [key, entry] of Object.entries(manifest.entries)) {
+      const target = path.join(release, key);
+      if (entry.type === 'directory') await fs.mkdir(target, { recursive: true });
+      else {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        if (previousRoot && previous[key]?.type === 'file' && previous[key].sha256 === entry.sha256) {
+          // Copy rather than hardlink: chmod or external writes cannot mutate retained releases.
+          const previousFile = path.join(previousRoot, key);
+          if (!(await fs.lstat(previousFile)).isFile()) throw new Error('Previous release contains a non-file');
+          await fs.copyFile(previousFile, target);
+          if (process.platform !== 'win32') await fs.chmod(target, entry.mode);
+        } else wanted.push(key);
+      }
+    }
+    await fs.writeFile(manifestPath, JSON.stringify(manifest));
+    process.stdout.write(JSON.stringify({ wanted, deletedFiles: Object.keys(previous).filter((key) => previous[key].type === 'file' && !manifest.entries[key]).length }));
+    return;
+  }
+  await assertLock();
+  if ((await fs.lstat(root)).isSymbolicLink()) throw new Error('Deployment root cannot be a symlink');
+  if (await exists(releases) && (await fs.lstat(releases)).isSymbolicLink()) throw new Error('Releases directory cannot be a symlink');
+  if (action !== 'cleanup' && !(await ownsReleases())) throw new Error('Unmanaged sibling releases exists at target');
+  if (action === 'upload') {
+    const manifest = await readManifest();
+    let handle;
+    let key;
+    try {
+      for await (const line of readline.createInterface({ input: process.stdin, crlfDelay: Infinity })) {
+        const packet = JSON.parse(line);
+        if (packet.begin !== undefined) {
+          if (handle) throw new Error('Unclosed upload');
+          key = safeKey(packet.begin);
+          if (manifest.entries[key]?.type !== 'file') throw new Error('Unexpected upload path');
+          handle = await fs.open(path.join(release, key), 'w', 0o600);
+        } else if (packet.chunk !== undefined) {
+          if (!handle || typeof packet.chunk !== 'string' || packet.chunk.length > 100000) throw new Error('Invalid upload chunk');
+          await handle.writeFile(Buffer.from(packet.chunk, 'base64'));
+        } else if (packet.end === true) {
+          if (!handle) throw new Error('Unexpected upload end');
+          if (process.platform !== 'win32') await handle.chmod(manifest.entries[key].mode);
+          await handle.close(); handle = undefined;
+          process.stdout.write(`Uploaded ${key}\n`);
+        } else throw new Error('Invalid upload packet');
+      }
+      if (handle) throw new Error('Truncated upload stream');
+    } finally { if (handle) await handle.close(); }
+  } else if (action === 'verify') {
+    const manifest = await readManifest();
+    const found = new Set();
+    async function walk(relative = '') {
+      for (const name of await fs.readdir(path.join(release, relative))) {
+        const key = relative ? `${relative}/${name}` : name;
+        if (key === '.shipwatch-manifest.json') continue;
+        const entry = manifest.entries[key];
+        const filename = path.join(release, key);
+        const metadata = await fs.lstat(filename);
+        if (!entry || metadata.isSymbolicLink() || (entry.type === 'directory' ? !metadata.isDirectory() : !metadata.isFile())) throw new Error(`Unexpected file/type: ${key}`);
+        found.add(key);
+        if (entry.type === 'directory') await walk(key);
+        else if (await digest(filename) !== entry.sha256) throw new Error(`SHA-256 mismatch: ${key}`);
+        if (process.platform !== 'win32') {
+          if (entry.type === 'directory') await fs.chmod(filename, entry.mode);
+          if (((await fs.stat(filename)).mode & 0o777) !== entry.mode) throw new Error(`Mode mismatch: ${key}`);
+        }
+      }
+    }
+    await walk();
+    if (found.size !== Object.keys(manifest.entries).length) throw new Error('Missing release files');
+    await fs.writeFile(path.join(root, `.verified-${version}`), version);
+    process.stdout.write('SHA-256 verification passed\n');
+  } else if (action === 'activate') {
+    if ((await fs.readFile(path.join(root, `.verified-${version}`), 'utf8')) !== version) throw new Error('Release not verified');
+    await syncTarget(root, release, await readManifest(), version);
+    const next = path.join(root, `.next-${version}`);
+    const backup = path.join(root, `.previous-${version}`);
+    await fs.symlink(release, next, process.platform === 'win32' ? 'junction' : 'dir');
+    if (process.platform === 'win32' && await exists(current)) {
+      // Windows cannot replace an existing junction atomically. Restore old current if step two fails.
+      await fs.rename(current, backup);
+      try { await fs.rename(next, current); } catch (error) { await fs.rename(backup, current); throw error; }
+      await fs.unlink(backup);
+    } else await fs.rename(next, current);
+    process.stdout.write(`Activated ${version}\n`);
+  } else if (action === 'hook') {
+    if (await fs.realpath(current) !== release) throw new Error('Service command requires the active release');
+    let payload = '';
+    for await (const chunk of process.stdin) payload += chunk;
+    const { command, timeoutMs } = JSON.parse(payload);
+    if (typeof command !== 'string' || !command.trim() || command.length > 16384 || command.includes('\0') || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 3600000) throw new Error('Invalid service command');
+    // Claim before executing: a lost SSH response must not cause the same command to run twice.
+    await fs.writeFile(path.join(root, `.hook-started-${version}`), version, { flag: 'wx' });
+    await new Promise((resolve, reject) => {
+      const child = spawn(command, { shell: true, cwd: root, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+      child.stdout.pipe(process.stdout); child.stderr.pipe(process.stderr);
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        if (process.platform === 'win32') {
+          const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+          killer.on('error', () => child.kill());
+        } else {
+          try { process.kill(-child.pid, 'SIGKILL'); } catch (error) { if (error.code !== 'ESRCH') child.kill('SIGKILL'); }
+        }
+      }, timeoutMs);
+      child.on('error', (error) => { clearTimeout(timer); reject(error); });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        if (timedOut) reject(new Error('Service command timed out'));
+        else if (code !== 0) reject(new Error(`Service command exited ${code}`));
+        else resolve();
+      });
+    });
+    process.stdout.write('Service command completed\n');
+  } else if (action === 'prune') {
+    if (!Number.isInteger(keep) || keep < 1) throw new Error('Invalid retention');
+    const active = path.basename(await fs.realpath(current));
+    const versions = (await fs.readdir(releases)).filter((name) => VERSION.test(name)).sort().reverse();
+    const retained = new Set([active, ...versions.filter((name) => name !== active).slice(0, keep - 1)]);
+    for (const name of versions) if (!retained.has(name)) {
+      await removeRelease(path.join(releases, name));
+      process.stdout.write(`Pruned ${name}\n`);
+    }
+  } else if (action === 'cleanup') {
+    const active = await exists(current) ? await fs.realpath(current) : undefined;
+    if (active !== release && await ownsReleases()) await removeRelease(release);
+    for (const filename of [`.next-${version}`, `.verified-${version}`, `.hook-started-${version}`]) {
+      if (await exists(path.join(root, filename))) await fs.unlink(path.join(root, filename));
+    }
+    await fs.unlink(lock);
+  } else throw new Error(`Unknown remote operation: ${action}`);
+}
+
+main(process.argv[2], JSON.parse(Buffer.from(process.argv[3] || '', 'base64').toString())).catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/src/snapshot.js

@@ -0,0 +1,88 @@
+/** Snapshot service: hash source trees and create immutable, verified staging copies.
+ * Exports scan/snapshot; Node crypto/fs only; rejects links and special files.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readdir, lstat, mkdir, copyFile, chmod, mkdtemp, writeFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+/** Match * within a path segment and ** across segments; bare patterns match any basename. */
+function matcher(pattern) {
+  const normalized = pattern.replace(/^\//, '').replace(/\/$/, '');
+  let source = '';
+  for (let index = 0; index < normalized.length; index++) {
+    const char = normalized[index];
+    if (char === '*' && normalized[index + 1] === '*') {
+      index++;
+      if (normalized[index + 1] === '/') { index++; source += '(?:.*/)?'; } else source += '.*';
+    } else if (char === '*') source += '[^/]*';
+    else if (char === '?') source += '[^/]';
+    else source += char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp((normalized.includes('/') ? '^' : '(^|/)') + source + '$');
+}
+
+/** Stream hashes to keep memory bounded for large artifacts. */
+async function hashFile(filename) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(filename)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+/** Restore owner write access before deleting snapshots containing read-only source directories. */
+async function removeSnapshot(directory) {
+  async function unlock(root) {
+    await chmod(root, 0o700);
+    for (const name of await readdir(root)) {
+      const child = path.join(root, name);
+      if ((await lstat(child)).isDirectory()) await unlock(child);
+    }
+  }
+  await unlock(directory);
+  await rm(directory, { recursive: true, force: true });
+}
+
+/** Include directory entries and modes so empty directories and chmod changes trigger publication. */
+export async function scan(config, root = config.directory) {
+  const patterns = config.exclude.map(matcher);
+  const entries = Object.create(null);
+  const configRelative = path.relative(root, config.configFile).split(path.sep).join('/');
+  async function walk(relative = '') {
+    for (const name of (await readdir(path.join(root, relative))).sort()) {
+      const key = relative ? `${relative}/${name}` : name;
+      if (key === configRelative || patterns.some((pattern) => pattern.test(key))) continue;
+      const filename = path.join(root, key);
+      const metadata = await lstat(filename);
+      if (metadata.isSymbolicLink() || (!metadata.isDirectory() && !metadata.isFile())) throw new Error(`Unsupported symlink or special file: ${key}`);
+      const mode = metadata.mode & 0o777;
+      entries[key] = metadata.isDirectory() ? { type: 'directory', mode } : { type: 'file', mode, sha256: await hashFile(filename) };
+      if (metadata.isDirectory()) await walk(key);
+    }
+  }
+  await walk();
+  return { entries, digest: createHash('sha256').update(JSON.stringify(entries)).digest('hex') };
+}
+
+/** Compare before/copy/after hashes; never publish a tree that changed during capture. */
+export async function snapshot(config) {
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'shipwatch-snapshot-'));
+  try {
+    const before = await scan(config);
+    for (const [key, entry] of Object.entries(before.entries)) {
+      const target = path.join(directory, key);
+      if (entry.type === 'directory') await mkdir(target, { recursive: true });
+      else { await copyFile(path.join(config.directory, key), target); await chmod(target, entry.mode); }
+    }
+    // Apply directory modes last so read-only source directories can still be assembled.
+    for (const [key, entry] of Object.entries(before.entries).reverse()) if (entry.type === 'directory') await chmod(path.join(directory, key), entry.mode);
+    const copied = await scan(config, directory);
+    const after = await scan(config);
+    if (before.digest !== copied.digest || before.digest !== after.digest) throw new Error('Source changed during snapshot; retrying on next stable scan');
+    await writeFile(path.join(directory, '.shipwatch-manifest.json'), JSON.stringify({ version: 1, entries: before.entries }));
+    return { directory, digest: before.digest, totalFiles: Object.values(before.entries).filter((entry) => entry.type === 'file').length, cleanup: () => removeSnapshot(directory) };
+  } catch (error) {
+    await removeSnapshot(directory);
+    throw error;
+  }
+}