artifacty 0.13.1 → 0.15.0

package/src/lib/sample-content.js

@@ -30,7 +30,7 @@ Open http://127.0.0.1:8787. The server binds to localhost by default. To start a
 5. Inspect the version history.
 6. Compare the versions with a diff.
 7. Add tags.
-8. Use search, filters, or saved views to find the artifact again.
+8. Use search to find the artifact again. Open **Advanced filters** or **Saved views** in the main dashboard when needed. These sections start collapsed; closing them preserves your filters.
 9. Add a comment.
 10. Request a review.
 11. As the owner or administrator, record an approved or changes-requested status.
@@ -42,7 +42,7 @@ Open http://127.0.0.1:8787. The server binds to localhost by default. To start a
 
 ## Choose your access model
 
-Before accounts exist, Artifacty operates as a local single-user store. Once accounts exist, use personal accounts and tokens. Create the initial administrator at **/login**. Administrators manage accounts at **/admin/users**. The Access page links to that page. Administrators manage teams, access mode, and network rules at **/admin/access**. In private mode, use personal authentication for ordinary artifact reads and creation. Server-wide tokens do not authorize those operations. Local CLI operations remain trusted store administration.
+Before accounts exist, Artifacty operates as a local single-user store. Once accounts exist, use personal accounts and tokens. Create the initial administrator at **/login**. In the desktop navigation rail, open **Administration**. On narrower screens, open **Menu** first. Use **Users** (**/admin/users**) for accounts. Use **Access** (**/admin/access**) for teams, access mode, and network rules. Administration also contains Backup, Retention, Webhooks, and Server update. In private mode, use personal authentication for ordinary artifact reads and creation. Server-wide tokens do not authorize those operations. Local CLI operations remain trusted store administration.
 
 A share link is a separate read-only capability with an expiry time. It does not grant account membership. Default expiry is seven days. Owners can share the latest version or pin one version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, an owner can link a private-visibility artifact without that site toggle. When you no longer need a link, revoke it. An owner change invalidates existing links.
 
@@ -70,10 +70,10 @@ If the current store is corrupt, preserve it and copy the selected snapshot to a
 <header><p>ARTIFACTY / REFERENCE</p><h1>From an agent output to a shared record</h1><p>Use this inventory to choose the right publishing, review, access, and maintenance workflow. Use Node.js 22.12.0 or newer. The current store schema is 10. Mermaid 12.1.0 keeps the classic look, dagre layout, and default theme. Use an ES2024-capable browser, such as Safari 17.4 or newer. The optional Babel 8 React renderer requires Node ^22.18.0 or &gt;=24.11.0.</p></header>
 <nav aria-label="Guide sections"><a href="#formats">Formats</a> · <a href="#history">History and discovery</a> · <a href="#collaboration">Collaboration</a> · <a href="#access">Access</a> · <a href="#operations">Operations</a></nav>
 <section id="formats"><h2>Formats and imports</h2><p>The 13 formats are HTML, Markdown, text, JSON, code, SVG, Mermaid, React, SARIF, CSV, image, video, and notebook. Choose an artifact type separately: a document, handoff, code review, test report, dashboard, diagram, component, table, or another supported type.</p><p>Bundles group multiple files under one artifact. Supported binary bundle assets include PDF, DOCX, XLSX, and ZIP. Importers normalize outputs from Claude, Codex, Gemini, GitHub Copilot, Cursor, and generic inputs. Use the browser import screen or <code>artifacty import --agent codex --file handoff.md</code>.</p><p>Artifact content is untrusted. Browser previews use constrained rendering. A public HTML share preview is static. It blocks scripts and external resource loading. Share links show other active formats as source. Do not expect those previews to preserve interactive application behavior.</p></section>
-<section id="history"><h2>Versions, discovery, and retrieval</h2><ul><li>Updates create versions with immutable content files. You can read a historical version and compare versions with a diff. To avoid overwriting a concurrent edit, use an expected-version check.</li><li>Archive and restore artifacts instead of losing their history. Integrity checks verify stored files, hashes, and orphaned files.</li><li>Search by keyword and filter by tags, source agent, artifact type, publisher, dates, review status, relationships, and archive state. Pagination and grouping help you use large lists. To reuse a set of filters, save it as a view.</li><li>When available, SQLite FTS5 accelerates keyword search. Otherwise, search uses metadata. Optional embeddings enable semantic and hybrid search. Without a configured provider, those modes use keyword search. Rebuild search or embedding indexes after configuration changes.</li></ul></section>
+<section id="history"><h2>Versions, discovery, and retrieval</h2><ul><li>Updates create versions with immutable content files. You can read a historical version and compare versions with a diff. To avoid overwriting a concurrent edit, use an expected-version check.</li><li>Archive and restore artifacts instead of losing their history. Integrity checks verify stored files, hashes, and orphaned files.</li><li>Search by keyword and filter by tags, source agent, artifact type, publisher, dates, review status, relationships, and archive state. Pagination and grouping help you use large lists. To reuse a set of filters, save it as a view. Search stays visible in the main dashboard. Open Advanced filters or Saved views when needed. Both sections start collapsed; closing them preserves selected filters.</li><li>When available, SQLite FTS5 accelerates keyword search. Otherwise, search uses metadata. Optional embeddings enable semantic and hybrid search. Without a configured provider, those modes use keyword search. Rebuild search or embedding indexes after configuration changes.</li></ul></section>
 <section id="collaboration"><h2>Relationships, comments, review, and notifications</h2><p>Connect artifacts using derived-from, supersedes, reviews, references, or part-of relations. Comments support threads and anchors. After you address a thread, resolve it. Review status progresses among none, pending, changes-requested, and approved.</p><p>The inbox at <code>/inbox</code> collects relevant shares, comments, review activity, and new versions. Notifications depend on the user and current artifact access. You can mark items read individually or together. A notification does not grant access.</p><p>Audit records support investigation. Event polling and server-sent events expose authorized activity streams. Webhooks deliver configured events to validated destinations. Use event filters, replay cursors, and webhook administration for integrations.</p></section>
-<section id="access"><h2>Accounts, permissions, share links, and network rules</h2><p>Create the initial administrator at <code>/login</code>. Administrators manage accounts at <code>/admin/users</code>. The Access page links to that page. Administrators manage teams, access mode, and network rules at <code>/admin/access</code>. The artifact <strong>Sharing</strong> panel shows effective access and its sources. Direct-user and team grants support read, comment, and edit. Where grants overlap, the strongest permission wins. Ownership and administrator management are separate from grants. Token scopes limit token actions. They do not grant artifact access.</p><p>Private mode requires an active personal account. Server-wide tokens do not authorize ordinary artifact reads or creation in private mode. Administrator APIs have their own authorization rules. Personal tokens remain constrained by both their scopes and the user's artifact permissions. Trusted local CLI operations can administer the local store directly.</p><p>Read-only share links default to seven days and can target the latest version or a pinned version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, owners may link private-visibility artifacts without that site toggle. Links can be revoked, and owner changes invalidate them. A valid capability permits only its read-only shared surface.</p><p>Network allow rules accept IP addresses and CIDRs. First, stage a change. Next, verify access from the intended peer. Then confirm the change within 120 seconds or roll it back. Pending state survives a restart. Before the next access, the server checks for expiry. If the change has expired, the server restores the previous rules. Rules use the socket peer address, not forwarded proxy headers.</p></section>
-<section id="operations"><h2>Interfaces and maintenance</h2><ul><li>The browser supports creation, import, viewing, editing, discovery, review, inbox, and administration.</li><li>The CLI supports serve/start/stop/status, publish/import/update/read/list, history and diff, relations/comments/review, saved views, event watching, account import, backup, retention, indexes, integrity, and diagnostics. Run <code>artifacty help</code> for exact flags.</li><li>The JSON API exposes artifacts and operational endpoints under <code>/api/</code>. MCP exposes agent tools through stdio and optional HTTP transport. Use <code>artifacty install claude --dry-run</code> to inspect integration configuration and <code>artifacty check</code> to verify tool discovery.</li><li>Export and import JSON backups to move a store. Upgrade snapshots separately preserve raw SQLite, referenced versions, and any legacy index. Schema migrations always require a verified snapshot. Set <code>ARTIFACTY_BACKUP_ON_UPDATE=true</code> for application-version snapshots, including an unknown-version baseline. <code>ARTIFACTY_UPGRADE_BACKUP_KEEP</code> defaults to 3 and accepts 1–1000.</li><li>Use <code>artifacty backups list</code>, <code>artifacty backups verify &lt;id&gt;</code>, and <code>artifacty backups restore &lt;id&gt; --confirm restore-store</code>. Stop every server and MCP process first. Restore saves a recovery snapshot and rolls back credentials and security state. Revoked sessions, tokens, or links can become valid again. For a corrupt store, copy the snapshot to a new empty home and restore there. Preserve interrupted <code>.restore-*</code> directories and use their <code>restore.json</code> recoveryBackupId. See <code>docs/upgrade-backups.md</code>.</li><li>Retention supports archive rules, archived-item purge, audit/event history limits, and protected tags. Before an intentional purge, inspect a dry run.</li><li><code>artifacty samples install</code> installs these manuals idempotently. <code>artifacty samples remove</code> archives only managed samples in the current scope. Reinstallation restores existing versions and user edits.</li></ul><p>Keep ARTIFACTY_HOME private. Older builds refuse schema-10 stores. Before changing builds, preserve a backup. Consult repository integration documentation for concrete agent and API examples.</p></section>
+<section id="access"><h2>Accounts, permissions, share links, and network rules</h2><p>Create the initial administrator at <code>/login</code>. In the navigation, administrators open <strong>Administration</strong>. Use Users at <code>/admin/users</code> for accounts. Use Access at <code>/admin/access</code> for teams, access mode, and network rules. Backup, Retention, Webhooks, and Server update are in the same group. The artifact <strong>Sharing</strong> panel shows effective access and its sources. Direct-user and team grants support read, comment, and edit. Where grants overlap, the strongest permission wins. Ownership and administrator management are separate from grants. Token scopes limit token actions. They do not grant artifact access.</p><p>Private mode requires an active personal account. Server-wide tokens do not authorize ordinary artifact reads or creation in private mode. Administrator APIs have their own authorization rules. Personal tokens remain constrained by both their scopes and the user's artifact permissions. Trusted local CLI operations can administer the local store directly.</p><p>Read-only share links default to seven days and can target the latest version or a pinned version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, owners may link private-visibility artifacts without that site toggle. Links can be revoked, and owner changes invalidate them. A valid capability permits only its read-only shared surface.</p><p>Network allow rules accept IP addresses and CIDRs. First, stage a change. Next, verify access from the intended peer. Then confirm the change within 120 seconds or roll it back. Pending state survives a restart. Before the next access, the server checks for expiry. If the change has expired, the server restores the previous rules. Rules use the socket peer address, not forwarded proxy headers.</p></section>
+<section id="operations"><h2>Interfaces and maintenance</h2><ul><li>The browser supports creation, import, viewing, editing, discovery, review, inbox, and administration. On desktop, use the navigation rail. On narrower screens, open Menu. Artifacts and Inbox lead to your work; New and Import add content. Account contains Account &amp; API tokens, password changes, and sign-out. API docs and language selection are also in the navigation. Administrators can open Server update at /admin/update. Checking the latest release does not install it. For a supported non-root Linux systemd user service, confirm the displayed version and backup/restart before starting. Keep the page open to reconnect and read the result.</li><li>The CLI supports serve/start/stop/status, publish/import/update/read/list, history and diff, relations/comments/review, saved views, event watching, account import, backup, retention, indexes, integrity, and diagnostics. Run <code>artifacty help</code> for exact flags.</li><li>The JSON API exposes artifacts and operational endpoints under <code>/api/</code>. MCP exposes agent tools through stdio and optional HTTP transport. Use <code>artifacty install claude --dry-run</code> to inspect integration configuration and <code>artifacty check</code> to verify tool discovery.</li><li>Export and import JSON backups to move a store. Upgrade snapshots separately preserve raw SQLite, referenced versions, and any legacy index. Schema migrations always require a verified snapshot. Set <code>ARTIFACTY_BACKUP_ON_UPDATE=true</code> for application-version snapshots, including an unknown-version baseline. <code>ARTIFACTY_UPGRADE_BACKUP_KEEP</code> defaults to 3 and accepts 1–1000.</li><li>Use <code>artifacty backups list</code>, <code>artifacty backups verify &lt;id&gt;</code>, and <code>artifacty backups restore &lt;id&gt; --confirm restore-store</code>. Stop every server and MCP process first. Restore saves a recovery snapshot and rolls back credentials and security state. Revoked sessions, tokens, or links can become valid again. For a corrupt store, copy the snapshot to a new empty home and restore there. Preserve interrupted <code>.restore-*</code> directories and use their <code>restore.json</code> recoveryBackupId. See <code>docs/upgrade-backups.md</code>.</li><li>Retention supports archive rules, archived-item purge, audit/event history limits, and protected tags. Before an intentional purge, inspect a dry run.</li><li><code>artifacty samples install</code> installs these manuals idempotently. <code>artifacty samples remove</code> archives only managed samples in the current scope. Reinstallation restores existing versions and user edits.</li></ul><p>Keep ARTIFACTY_HOME private. Older builds refuse schema-10 stores. Before changing builds, preserve a backup. Consult repository integration documentation for concrete agent and API examples.</p></section>
 <footer><p>This guide is a managed sample artifact. Editing it creates your own version. Reinstalling samples preserves that work.</p></footer>
 </main></body></html>`
   },
@@ -171,7 +171,7 @@ The four sample manuals are installed. You can open the browser dashboard. To pr
 
 ## Administration practice
 
-As an administrator, open **/admin/access** to inspect access mode and network rules. You can switch access mode or stage a network change.
+As an administrator, open **Administration → Access** (**/admin/access**) to inspect access mode and network rules. On narrower screens, open **Menu** first. You can switch access mode or stage a network change.
 
 1. Before you stage a network change, keep your actual socket peer address in the allowed rules.
 2. Stage the change.

package/src/lib/self-update.js

@@ -0,0 +1,351 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { access, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { createUpgradeBackup, verifyUpgradeBackup, restoreUpgradeBackup } from "./upgrade-backup.js";
+
+const execute = promisify(execFile);
+const UNIT = "com.artifacty.server.service";
+const LAUNCHER_MARK = "// artifacty-managed-launcher";
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const failure = (message, code = "SELF_UPDATE_FAILED") => Object.assign(new Error(message), { code });
+
+function compareVersions(left, right) {
+  const parse = (value) => { const [core, ...pre] = value.split("+")[0].split("-"); return { core: core.split(".").map(Number), pre: pre.join("-") }; };
+  const a = parse(left); const b = parse(right);
+  for (let index = 0; index < 3; index++) if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1;
+  if (!a.pre || !b.pre) return a.pre === b.pre ? 0 : !a.pre ? 1 : -1;
+  const ap = a.pre.split("."); const bp = b.pre.split(".");
+  for (let index = 0; index < Math.max(ap.length, bp.length); index++) {
+    if (ap[index] === bp[index]) continue;
+    if (ap[index] === undefined) return -1;
+    if (bp[index] === undefined) return 1;
+    const an = /^\d+$/.test(ap[index]); const bn = /^\d+$/.test(bp[index]);
+    if (an && bn) return Number(ap[index]) > Number(bp[index]) ? 1 : -1;
+    if (an !== bn) return an ? -1 : 1;
+    return ap[index] > bp[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+async function readOptional(file) {
+  try { return await readFile(file, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+function quoteUnit(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+
+// Accept the simple ExecStart form produced by Artifacty's service installer.
+// Reject specifiers, environment expansion, and ambiguous quoting before stopping it.
+function unitArguments(text) {
+  const commands = [];
+  for (const line of text.replace(/\\\n\s*/g, " ").split("\n")) {
+    if (!line.startsWith("ExecStart=")) continue;
+    const command = line.slice(10).trim();
+    if (!command) commands.length = 0;
+    else commands.push(command);
+  }
+  if (commands.length !== 1 || /[$%\r\n]/.test(commands[0])) throw failure("Unsupported service ExecStart. No changes were made.", "UNSUPPORTED_SERVICE");
+  const args = [];
+  const expression = /\s*(?:"((?:[^"\\]|\\["\\])*)"|'([^']*)'|([^\s"'\\]+))/gy;
+  let offset = 0;
+  while (offset < commands[0].length) {
+    expression.lastIndex = offset;
+    const match = expression.exec(commands[0]);
+    if (!match) throw failure("Unsupported service argument quoting", "UNSUPPORTED_SERVICE");
+    args.push(match[1] !== undefined ? match[1].replace(/\\(["\\])/g, "$1") : match[2] ?? match[3]);
+    offset = expression.lastIndex;
+  }
+  if (args.length < 2 || !path.isAbsolute(args[0]) || !path.isAbsolute(args[1]) || !args[1].endsWith("/src/server.js")) {
+    throw failure("The user service does not run an identifiable Artifacty server", "UNSUPPORTED_SERVICE");
+  }
+  return args;
+}
+
+async function packageAt(root) {
+  const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  if (manifest.name !== "artifacty" || !VERSION.test(manifest.version)) throw failure("Invalid Artifacty package metadata");
+  return manifest;
+}
+
+async function discoverService(run, home) {
+  const result = await run("systemctl", ["--user", "show", UNIT, "--no-pager", "--property=LoadState,ActiveState,MainPID"]);
+  const properties = Object.fromEntries(result.stdout.trim().split("\n").map((line) => {
+    const index = line.indexOf("="); return [line.slice(0, index), line.slice(index + 1)];
+  }));
+  if (properties.LoadState !== "loaded" || !["active", "inactive", "failed"].includes(properties.ActiveState)) {
+    throw failure("Install a stable Artifacty systemd user service before automatic updates", "UNSUPPORTED_SERVICE");
+  }
+  const text = (await run("systemctl", ["--user", "cat", UNIT, "--no-pager"])).stdout;
+  const args = unitArguments(text);
+  if (args.filter((arg) => arg === "--home").length !== 1) throw failure("The service must have exactly one --home argument", "SERVICE_HOME_MISMATCH");
+  const homeIndex = args.indexOf("--home");
+  if (homeIndex < 0 || !args[homeIndex + 1] || path.resolve(args[homeIndex + 1]) !== home) {
+    throw failure("The service must explicitly use the selected --home directory", "SERVICE_HOME_MISMATCH");
+  }
+  const packageRoot = path.dirname(path.dirname(args[1]));
+  const manifest = await packageAt(packageRoot);
+  const pid = Number(properties.MainPID);
+  if (properties.ActiveState === "active" && (!Number.isInteger(pid) || pid <= 0)) throw failure("Cannot identify the running service process");
+  return { args, text, packageRoot, version: manifest.version, pid, active: properties.ActiveState === "active" };
+}
+
+async function assertNoOtherWriters({ home, allowedPid, ownPid = process.pid, processRoot = "/proc" }) {
+  const canonicalHome = await realpath(home);
+  for (const entry of await readdir(processRoot)) {
+    if (!/^\d+$/.test(entry) || Number(entry) === ownPid || Number(entry) === allowedPid) continue;
+    const directory = path.join(processRoot, entry);
+    let args;
+    try {
+      const owner = await lstat(directory);
+      if (process.getuid && owner.uid !== process.getuid()) continue;
+      args = (await readFile(`${directory}/cmdline`, "utf8")).split("\0").filter(Boolean);
+    } catch (error) {
+      if (["ENOENT", "ESRCH"].includes(error.code)) continue;
+      throw failure("Cannot inspect another user process; stop other clients before updating", "UNMANAGED_WRITER");
+    }
+    for (const argument of args.slice(1)) {
+      if (!/(?:server\.js|cli\.js|artifacty(?:-mcp)?)$/.test(argument)) continue;
+      let source;
+      let cwd;
+      try { cwd = await realpath(`${directory}/cwd`); source = await realpath(path.resolve(cwd, argument)); }
+      catch { continue; }
+      if (!/\/src\/(?:mcp-server|server|cli)\.js$/.test(source)) continue;
+      try { await packageAt(path.dirname(path.dirname(source))); } catch { continue; }
+      const indices = args.flatMap((arg, index) => arg === "--home" ? [index] : []);
+      if (indices.length > 1) throw failure("Stop Artifacty clients with ambiguous --home arguments", "UNMANAGED_WRITER");
+      let processHome = indices.length ? args[indices[0] + 1] : null;
+      if (!processHome) {
+        let environment;
+        try { environment = (await readFile(`${directory}/environ`, "utf8")).split("\0"); }
+        catch { throw failure("Cannot inspect another Artifacty process; stop it before updating", "UNMANAGED_WRITER"); }
+        processHome = environment.find((item) => item.startsWith("ARTIFACTY_HOME="))?.slice(15);
+        const userHome = environment.find((item) => item.startsWith("HOME="))?.slice(5);
+        processHome ||= userHome && path.join(userHome, ".artifacty");
+      }
+      let resolved;
+      try { resolved = processHome && await realpath(path.resolve(cwd, processHome)); } catch { /* Unknown homes fail closed. */ }
+      if (!resolved || resolved === canonicalHome) throw failure(`Stop the unmanaged Artifacty process (pid ${entry}) before updating`, "UNMANAGED_WRITER");
+    }
+  }
+}
+
+async function writableDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw failure(`Expected a real directory: ${directory}`);
+  await access(directory, constants.W_OK);
+}
+
+async function originalFile(file, managedMark) {
+  const info = await lstat(file).catch((error) => { if (error.code === "ENOENT") return null; throw error; });
+  if (!info) return null;
+  if (!info.isFile() || info.isSymbolicLink()) throw failure(`Refusing to replace an unmanaged file: ${file}`, "UNMANAGED_FILE");
+  const content = await readFile(file, "utf8");
+  if (managedMark && !content.includes(managedMark)) throw failure(`Refusing to replace an unmanaged file: ${file}`, "UNMANAGED_FILE");
+  await access(file, constants.W_OK);
+  return { content, mode: info.mode & 0o777 };
+}
+
+async function replaceFile(file, content, mode = 0o600) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { mode, flag: "wx" });
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+function launcher(node, entry) {
+  return `#!/usr/bin/env node\n${LAUNCHER_MARK}\nconst { spawnSync } = require("node:child_process");\nconst result = spawnSync(${JSON.stringify(node)}, [${JSON.stringify(entry)}, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });\nif (result.error) { console.error(result.error.message); process.exitCode = 1; } else { process.exitCode = result.status ?? 1; }\n`;
+}
+
+function validHealthUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" && !url.username && !url.password && !url.search && !url.hash && url.pathname === "/" && Boolean(url.port);
+  } catch { return false; }
+}
+
+async function verifyServiceIdentity(pid, args) {
+  const executable = await realpath(`/proc/${pid}/exe`);
+  const expected = await realpath(args[0]);
+  const command = (await readFile(`/proc/${pid}/cmdline`, "utf8")).split("\0").filter(Boolean);
+  if (executable !== expected || JSON.stringify(command.slice(1)) !== JSON.stringify(args.slice(1))) {
+    throw failure("The service PID does not match its configured Node process", "SERVICE_IDENTITY_MISMATCH");
+  }
+}
+
+async function waitHealthy(run, home, health, sleep, identity, args) {
+  for (let attempt = 0; attempt < 30; attempt++) {
+    let state;
+    try { state = JSON.parse(await readOptional(path.join(home, "server.json")) || "null"); } catch { /* Server state may be mid-write. */ }
+    const result = await run("systemctl", ["--user", "show", UNIT, "--property=MainPID", "--value"]);
+    const pid = Number(result.stdout.trim());
+    if (pid > 0 && state?.pid === pid && validHealthUrl(state.url)) {
+      await identity(pid, args);
+      if (await health(state.url)) return pid;
+    }
+    await sleep(1000);
+  }
+  throw failure("The updated service did not pass its PID and HTTP health checks", "UPDATE_HEALTH_FAILED");
+}
+
+/** Verify that a web administrator is operating the managed service itself. */
+export async function inspectWebUpdateService({ home, pid = process.pid }, injected = {}) {
+  if ((injected.platform || process.platform) !== "linux" || (injected.uid ?? process.geteuid?.()) === 0) {
+    throw failure("Web updates require a non-root Linux systemd user service", "UNSUPPORTED_SERVICE");
+  }
+  const run = injected.run || ((command, args) => execute(command, args, { timeout: 10000, maxBuffer: 1024 * 1024 }));
+  const service = await discoverService(run, path.resolve(home));
+  if (!service.active || service.pid !== pid) throw failure("This server is not the managed Artifacty service", "SERVICE_IDENTITY_MISMATCH");
+  await (injected.verifyServiceIdentity || verifyServiceIdentity)(pid, service.args);
+  return { currentVersion: service.version };
+}
+
+/** Update the managed Linux user service. Dependencies are injectable for offline tests. */
+export async function updateApplication(options = {}, injected = {}) {
+  const env = injected.env || process.env;
+  const platform = injected.platform || process.platform;
+  const userHome = injected.userHome || homedir();
+  const home = path.resolve(options.home || env.ARTIFACTY_HOME || path.join(userHome, ".artifacty"));
+  const run = injected.run || ((command, args) => execute(command, args, { env, timeout: 180000, maxBuffer: 2 * 1024 * 1024 }));
+  const sleep = injected.sleep || pause;
+  const identity = injected.verifyServiceIdentity || verifyServiceIdentity;
+  const writers = injected.assertNoOtherWriters || ((context) => assertNoOtherWriters({ ...context, processRoot: injected.processRoot }));
+  const progress = (message) => { try { options.onProgress?.(message); } catch { /* Reporting cannot interrupt recovery. */ } };
+  const health = injected.health || (async (url) => {
+    try {
+      const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(2000), redirect: "error" });
+      const body = await response.json();
+      return response.ok && body.ok === true && body.name === "artifacty" && path.resolve(body.store) === home;
+    } catch { return false; }
+  });
+  const backups = injected.backups || { create: createUpgradeBackup, verify: verifyUpgradeBackup, restore: restoreUpgradeBackup };
+  const requested = options.targetVersion || "latest";
+  if (requested !== "latest" && !VERSION.test(requested)) throw failure("--target-version must be latest or an exact version", "INVALID_UPDATE_VERSION");
+  let service;
+  let unsupported;
+  if (platform === "linux") {
+    try { service = await discoverService(run, home); } catch (error) { unsupported = error.message; }
+  } else unsupported = "Automatic updates currently require a Linux systemd user service";
+  const current = service?.version || (await packageAt(options.packageRoot || path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url)))))).version;
+  const targetVersion = JSON.parse((await run("npm", ["view", `artifacty@${requested}`, "version", "--json"])).stdout);
+  if (typeof targetVersion !== "string" || !VERSION.test(targetVersion)) throw failure("npm did not resolve one exact Artifacty version");
+  const summary = { currentVersion: current, targetVersion, supported: Boolean(service), service: service ? UNIT : null };
+  if (options.check) return { ...summary, check: true, updateAvailable: compareVersions(current, targetVersion) < 0, ...(unsupported ? { reason: unsupported } : {}) };
+  if (!service) throw failure(unsupported, "UNSUPPORTED_SERVICE");
+  if ((injected.uid ?? process.geteuid?.()) === 0) throw failure("Run updates as the service user, without sudo", "ROOT_UPDATE_REFUSED");
+  if (/[\r\n$%]/.test(home + userHome)) throw failure("Store and user paths containing $, %, or newlines are unsupported", "UNSUPPORTED_PATH");
+  if (compareVersions(current, targetVersion) > 0) {
+    if (requested !== "latest") throw failure("Automatic package downgrades are not supported", "UPDATE_DOWNGRADE_REFUSED");
+    return { ...summary, updated: false, reason: "already-newer" };
+  }
+  if (current === targetVersion) return { ...summary, updated: false, reason: "already-current" };
+  if (service.active) {
+    await identity(service.pid, service.args);
+    let state;
+    try { state = JSON.parse(await readOptional(path.join(home, "server.json")) || "null"); } catch { /* Fail before stopping an uncheckable service. */ }
+    if (state?.pid !== service.pid || !validHealthUrl(state.url) || !await health(state.url)) {
+      throw failure("The current service cannot pass its HTTP health check. Check its bind address and IP policy before updating.", "UPDATE_PREFLIGHT_HEALTH");
+    }
+  }
+  await writers({ home, allowedPid: service.pid });
+
+  const stateRoot = path.join(userHome, ".local", "share", "artifacty");
+  const releases = path.join(stateRoot, "releases");
+  const bin = path.join(userHome, ".local", "bin");
+  const dropinDirectory = path.join(userHome, ".config", "systemd", "user", `${UNIT}.d`);
+  for (const directory of [stateRoot, releases, bin, dropinDirectory]) await writableDirectory(directory);
+  const dropin = path.join(dropinDirectory, "zz-artifacty-self-update.conf");
+  const destinations = [dropin, path.join(bin, "artifacty"), path.join(bin, "artifacty-mcp")];
+  const originals = await Promise.all(destinations.map((file, index) => originalFile(file, index ? LAUNCHER_MARK : "# artifacty-managed-update")));
+  const lockPath = path.join(stateRoot, "update.lock");
+  let lock;
+  try { lock = await open(lockPath, "wx", 0o600); }
+  catch (error) { if (error.code === "EEXIST") throw failure(`Another update or an interrupted update holds ${lockPath}`, "UPDATE_LOCKED"); throw error; }
+  const stage = path.join(releases, `${targetVersion}-${randomUUID()}`);
+  let snapshot;
+  let stopped = false;
+  let switched = false;
+  let succeeded = false;
+  try {
+    await lock.writeFile(JSON.stringify({ pid: process.pid, targetVersion }));
+    progress(`Staging Artifacty ${targetVersion} before stopping the service.`);
+    await run("npm", ["install", "--prefix", stage, "--ignore-scripts", "--omit=dev", "--no-audit", "--no-fund", "--package-lock=false", "--save-exact", `artifacty@${targetVersion}`]);
+    const stagedRoot = path.join(stage, "node_modules", "artifacty");
+    if ((await packageAt(stagedRoot)).version !== targetVersion) throw failure("Staged package version does not match the resolved version");
+    for (const entry of ["cli.js", "server.js", "mcp-server.js"]) await run(service.args[0], ["--check", path.join(stagedRoot, "src", entry)]);
+    const version = (await run(service.args[0], [path.join(stagedRoot, "src", "cli.js"), "--version"])).stdout.trim();
+    if (version !== targetVersion) throw failure("Staged CLI version check failed");
+    const refreshed = await discoverService(run, home);
+    if (refreshed.text !== service.text || refreshed.pid !== service.pid) throw failure("Service configuration changed while staging; retry the update");
+    await writers({ home, allowedPid: service.pid });
+    progress("Stopping the user service and verifying a recovery snapshot.");
+    stopped = true;
+    await run("systemctl", ["--user", "stop", UNIT]);
+    await writers({ home, allowedPid: 0 });
+    snapshot = await backups.create({ home }, { reason: "manual", targetAppVersion: targetVersion });
+    await backups.verify({ home }, snapshot.id);
+    const args = [service.args[0], path.join(stagedRoot, "src", "server.js"), ...service.args.slice(2)];
+    progress("Switching the user service to the staged release.");
+    switched = true;
+    await replaceFile(dropin, `# artifacty-managed-update\n[Service]\nExecStart=\nExecStart=${args.map(quoteUnit).join(" ")}\n`);
+    await replaceFile(destinations[1], launcher(service.args[0], path.join(stagedRoot, "src", "cli.js")), 0o755);
+    await replaceFile(destinations[2], launcher(service.args[0], path.join(stagedRoot, "src", "mcp-server.js")), 0o755);
+    await run("systemctl", ["--user", "daemon-reload"]);
+    const configured = await discoverService(run, home);
+    if (configured.args[1] !== args[1] || JSON.stringify(configured.args.slice(2)) !== JSON.stringify(args.slice(2))) throw failure("A service override prevented the staged package from becoming active");
+    if (service.active) {
+      await run("systemctl", ["--user", "start", UNIT]);
+      progress("Waiting for service health and process identity.");
+      await waitHealthy(run, home, health, sleep, identity, args);
+    }
+    succeeded = true;
+    let firstExecutable;
+    for (const directory of (env.PATH || "").split(path.delimiter)) {
+      const candidate = path.resolve(directory, "artifacty");
+      try { await access(candidate, constants.X_OK); firstExecutable = await realpath(candidate); break; } catch { /* Try the next PATH entry. */ }
+    }
+    const pathWarning = firstExecutable !== await realpath(destinations[1]) ? `Use ${destinations[1]} until ${bin} precedes other Artifacty installations in PATH.` : undefined;
+    const commandPath = /^[\w/.-]+$/.test(destinations[1]) ? destinations[1] : `'${destinations[1].replaceAll("'", "'\\''")}'`;
+    return { ...summary, updated: true, backupId: snapshot.id, backupPath: snapshot.path, packageRoot: stagedRoot, restarted: service.active, launcher: destinations[1], nextCommand: `${commandPath} update`, ...(pathWarning ? { pathWarning } : {}) };
+  } catch (cause) {
+    progress("Update failed. Restoring the previous service and store where safe.");
+    const recoveryErrors = [];
+    if (switched) {
+      try { await run("systemctl", ["--user", "stop", UNIT]); } catch { recoveryErrors.push("could not stop the updated service"); }
+      if (!recoveryErrors.length) {
+        try {
+          for (let index = 0; index < destinations.length; index++) {
+            const original = originals[index];
+            if (original) await replaceFile(destinations[index], original.content, original.mode);
+            else await rm(destinations[index], { force: true });
+          }
+          await run("systemctl", ["--user", "daemon-reload"]);
+          await writers({ home, allowedPid: 0 });
+          await backups.restore({ home }, snapshot.id, { confirm: "restore-store" });
+        } catch (error) { recoveryErrors.push(`could not restore the previous configuration and store (${/^[A-Z_]+$/.test(error.code || "") ? error.code : "restore failed"})`); }
+      }
+    }
+    if (stopped && service.active && !recoveryErrors.length) {
+      try { await run("systemctl", ["--user", "start", UNIT]); await waitHealthy(run, home, health, sleep, identity, service.args); }
+      catch { recoveryErrors.push("the previous service did not restart cleanly"); }
+    }
+    const error = failure(`Update failed: ${cause.code || "operation failed"}. ${recoveryErrors.length ? `Recovery incomplete: ${recoveryErrors.join("; ")}.` : stopped ? "The previous service configuration was restored." : "The running service was not changed."}${snapshot ? ` Backup: ${snapshot.id}.` : ""}`, recoveryErrors.length ? "UPDATE_RECOVERY_INCOMPLETE" : "SELF_UPDATE_FAILED");
+    error.backupId = snapshot?.id;
+    error.backupPath = snapshot?.path;
+    error.cause = cause;
+    throw error;
+  } finally {
+    await lock.close();
+    await rm(lockPath, { force: true });
+    if (!succeeded && !switched) await rm(stage, { recursive: true, force: true });
+  }
+}

package/src/lib/web-update.js

@@ -0,0 +1,177 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, open, rm, lstat, realpath } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import path from "node:path";
+import { updateApplication, inspectWebUpdateService } from "./self-update.js";
+
+const execute = promisify(execFile);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const ACTIVE = new Set(["queued", "running"]);
+const needsRecovery = (run) => run?.state === "interrupted" || run?.errorCode === "UPDATE_RECOVERY_INCOMPLETE";
+const fail = (message, code, statusCode = 409) => Object.assign(new Error(message), { code, statusCode });
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const unitName = (id) => `artifacty-update-${id}.service`;
+const runnerStateRoot = (userHome) => path.join(userHome, ".local", "share", "artifacty", "update-jobs");
+
+async function readJson(file) {
+  try { return JSON.parse(await readFile(file, "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+async function writeJson(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(value), { flag: "wx", mode: 0o600 });
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+async function privateDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink() || (process.getuid && info.uid !== process.getuid()) || (process.platform !== "win32" && (info.mode & 0o077))) {
+    throw fail("Update state directory must be private and owned by the service user", "UNSAFE_UPDATE_STATE");
+  }
+}
+
+/** The controller does no work on construction. Read-only pages never contact npm. */
+export function createWebUpdater({ home, packageRoot }, injected = {}) {
+  home = path.resolve(home);
+  const root = runnerStateRoot(injected.userHome || homedir());
+  const stateInsideStore = root === home || root.startsWith(`${home}${path.sep}`);
+  const directory = path.join(root, hash(home));
+  const file = path.join(directory, "status.json");
+  const now = injected.now || Date.now;
+  const run = injected.run || ((command, args) => execute(command, args, { timeout: 15000, maxBuffer: 1024 * 1024 }));
+  const inspect = injected.inspect || ((options) => inspectWebUpdateService(options));
+  const update = injected.update || updateApplication;
+  const read = async () => await readJson(file) || {};
+  const currentVersion = async () => JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")).version;
+  const publicState = async (state, session) => ({
+    currentVersion: await currentVersion(),
+    check: state.check ? { ...state.check, confirmationId: state.sessionHash === hash(session || "") ? state.check.confirmationId : null } : null,
+    run: state.run || null
+  });
+  async function locked(action) {
+    if (stateInsideStore) throw fail("Update status must be outside the artifact store", "UNSAFE_UPDATE_STATE");
+    await privateDirectory(root);
+    const [resolvedRoot, resolvedHome] = await Promise.all([realpath(root), realpath(home)]);
+    if (resolvedRoot === resolvedHome || resolvedRoot.startsWith(`${resolvedHome}${path.sep}`)) throw fail("Update status must be outside the artifact store", "UNSAFE_UPDATE_STATE");
+    await privateDirectory(directory);
+    const lockPath = path.join(directory, "dispatch.lock");
+    let lock;
+    try { lock = await open(lockPath, "wx", 0o600); }
+    catch (error) { if (error.code === "EEXIST") throw fail("Another update request is in progress", "UPDATE_BUSY"); throw error; }
+    try { await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date(now()).toISOString() })); return await action(); }
+    finally { await lock.close(); await rm(lockPath, { force: true }); }
+  }
+  async function status(session) {
+    if (stateInsideStore) return { currentVersion: await currentVersion(), supported: false, reason: "Update state must be outside the artifact store.", check: null, run: null };
+    const state = await read();
+    // An unfinished job is never inferred successful. Keep uncertain jobs locked.
+    if (ACTIVE.has(state.run?.state) && now() - Date.parse(state.run.startedAt) > 30000) {
+      try {
+        const result = await run("systemctl", ["--user", "show", unitName(state.run.id), "--property=ActiveState", "--value"]).catch((error) => {
+          // systemctl may exit nonzero for a collected unit while still
+          // returning its authoritative inactive state. Bus failures do not.
+          if (["inactive", "failed"].includes(error.stdout?.trim())) return { stdout: error.stdout };
+          throw error;
+        });
+        if (["inactive", "failed"].includes(result.stdout.trim())) {
+          return await locked(async () => {
+            const latest = await read();
+            if (latest.run?.id === state.run.id && ACTIVE.has(latest.run.state)) {
+              latest.run = { ...latest.run, state: "interrupted", finishedAt: new Date(now()).toISOString(), errorCode: "UPDATE_INTERRUPTED", error: "The update worker stopped without a final result. Inspect the retained update backup and service before retrying." };
+              await writeJson(file, latest);
+            }
+            return publicState(latest, session);
+          });
+        }
+      } catch { /* Unavailable user manager is not evidence that a job has stopped. */ }
+    }
+    return publicState(state, session);
+  }
+  async function check(session) {
+    return locked(async () => {
+      const state = await read();
+      if (ACTIVE.has(state.run?.state) || needsRecovery(state.run)) throw fail("Resolve the existing update before checking again", "UPDATE_BUSY");
+      let eligible = false;
+      try { await inspect({ home, pid: process.pid }); eligible = true; } catch { /* Read-only version checks also support unmanaged installations. */ }
+      let result;
+      try {
+        const checked = await update({ home, packageRoot, check: true });
+        result = { currentVersion: await currentVersion(), targetVersion: checked.targetVersion, supported: eligible && checked.supported, updateAvailable: checked.updateAvailable };
+        if (!result.supported) result.reason = "Web updates require this server to be the non-root Linux systemd user service.";
+      } catch (error) {
+        result = { currentVersion: await currentVersion(), supported: eligible, updateAvailable: false, reason: "The latest release could not be checked. Try again later.", errorCode: "UPDATE_CHECK_FAILED" };
+      }
+      state.check = { ...result, check: undefined, confirmationId: randomUUID(), checkedAt: new Date(now()).toISOString(), expiresAt: new Date(now() + 10 * 60 * 1000).toISOString() };
+      state.sessionHash = hash(session);
+      await writeJson(file, state);
+      return publicState(state, session);
+    });
+  }
+  async function start({ session, confirmationId, targetVersion, confirmUpdate }) {
+    return locked(async () => {
+      const state = await read();
+      if (ACTIVE.has(state.run?.state) || needsRecovery(state.run)) throw fail("An update is already running or needs recovery", "UPDATE_BUSY");
+      const checked = state.check;
+      if (confirmUpdate !== "true" || !checked?.supported || !checked.updateAvailable || checked.confirmationId !== confirmationId || state.sessionHash !== hash(session) || checked.targetVersion !== targetVersion || Date.parse(checked.expiresAt) <= now()) {
+        throw fail("Check for updates again and confirm the displayed version", "UPDATE_CONFIRMATION_REQUIRED", 400);
+      }
+      await inspect({ home, pid: process.pid });
+      if (checked.currentVersion !== await currentVersion()) throw fail("The installed version changed; check again", "UPDATE_CONFIRMATION_REQUIRED", 400);
+      const id = randomUUID();
+      const requestFile = path.join(root, `${id}.json`);
+      await writeJson(requestFile, { id, home, packageRoot, targetVersion, statusFile: file });
+      state.check.confirmationId = null;
+      state.run = { id, state: "queued", targetVersion, startedAt: new Date(now()).toISOString(), phase: "Starting an independent update worker." };
+      await writeJson(file, state);
+      try {
+        await run("systemd-run", ["--user", `--unit=${unitName(id)}`, "--collect", "--property=Type=exec", "--", process.execPath, path.join(packageRoot, "src", "update-runner.js"), id]);
+      } catch {
+        // A timeout can occur after systemd accepted the unit. Preserve the job
+        // and its request; polling will resolve a stopped worker as interrupted.
+        // Never overwrite progress or completion written by that worker.
+        return publicState(await read(), session);
+      }
+      return publicState(state, session);
+    });
+  }
+  return { status, check, start };
+}
+
+/** Invoked only by the fixed systemd transient service, never the web server. */
+export async function runWebUpdate(id, injected = {}) {
+  if (!UUID.test(id || "")) throw fail("Invalid update job", "INVALID_UPDATE_JOB", 400);
+  const root = runnerStateRoot(injected.userHome || homedir());
+  await privateDirectory(root);
+  const requestFile = path.join(root, `${id}.json`);
+  const info = await lstat(requestFile);
+  if (!info.isFile() || info.isSymbolicLink() || (process.platform !== "win32" && (info.mode & 0o077)) || (process.getuid && info.uid !== process.getuid())) throw fail("Unsafe update request", "UNSAFE_UPDATE_STATE");
+  const request = await readJson(requestFile);
+  const expectedFile = path.join(root, hash(path.resolve(request.home)), "status.json");
+  if (request.id !== id || request.statusFile !== expectedFile || !path.isAbsolute(request.packageRoot)) throw fail("Invalid update request", "INVALID_UPDATE_JOB");
+  const sourceRoot = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+  if (await realpath(request.packageRoot) !== await realpath(injected.packageRoot || sourceRoot) || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(request.targetVersion)) throw fail("Update package identity does not match the worker", "INVALID_UPDATE_JOB");
+  await privateDirectory(path.dirname(expectedFile));
+  // A durable claim makes replays fail closed, including after a worker crash.
+  const claim = await open(path.join(root, `${id}.claimed`), "wx", 0o600);
+  await claim.close();
+  const state = await readJson(expectedFile);
+  if (state?.run?.id !== id || state.run.state !== "queued") throw fail("Update job was already consumed", "INVALID_UPDATE_JOB");
+  const save = async (changes) => { state.run = { ...state.run, ...changes }; await writeJson(expectedFile, state); };
+  await save({ state: "running", phase: "Preparing update." });
+  let progressQueue = Promise.resolve();
+  try {
+    const result = await (injected.update || updateApplication)({ home: request.home, packageRoot: request.packageRoot, targetVersion: request.targetVersion,
+      onProgress: (phase) => { progressQueue = progressQueue.then(() => save({ phase })); }
+    });
+    await progressQueue;
+    await save({ state: "succeeded", phase: "Update completed.", finishedAt: new Date().toISOString(), result });
+  } catch (error) {
+    await progressQueue.catch(() => {});
+    await save({ state: "failed", finishedAt: new Date().toISOString(), errorCode: /^[A-Z_]+$/.test(error.code || "") ? error.code : "SELF_UPDATE_FAILED", error: "Update failed. Inspect the service and retained recovery backup before retrying.", result: { backupId: error.backupId, backupPath: error.backupPath } });
+  } finally { await rm(requestFile, { force: true }); }
+}