artifacty 0.6.0 → 0.8.0

package/README.md

@@ -46,7 +46,7 @@ artifacty stop
 ```
 
 `artifacty start` and `artifacty serve --detach` use the same lifecycle path as `artifacty serve`. Logs are written under `~/.artifacty/logs/`.
-These lifecycle commands use Node's detached process support and work on macOS, Linux, and Windows. `artifacty stop` uses Windows `taskkill` on Windows and process-group signals on macOS/Linux.
+These lifecycle commands use Node's detached process support and work on macOS, Linux, and Windows. `artifacty stop` uses process-group signals on macOS/Linux and Windows `taskkill`, falling back to `/F` when Windows requires forceful termination.
 
 For foreground debugging, keep the process attached:
 
@@ -82,6 +82,13 @@ artifacty install all
 artifacty check
 ```
 
+Run diagnostics for the local runtime, store, server, service definitions, and MCP discovery:
+
+```bash
+artifacty doctor
+artifacty doctor --skip-mcp
+```
+
 Use `artifacty install codex --timeout 30000` or
 `artifacty install gemini --timeout 30000` to tune supported MCP client timeouts.
 
@@ -190,6 +197,7 @@ Operational commands:
 
 ```bash
 artifacty audit --limit 20
+artifacty doctor
 artifacty index rebuild
 artifacty integrity
 artifacty backup
@@ -199,6 +207,8 @@ artifacty start
 artifacty status
 artifacty stop
 artifacty service install --dry-run
+artifacty service unit --dry-run
+artifacty service task --dry-run
 ```
 
 When working from a source checkout without global installation, replace `artifacty` with `node src/cli.js` and `artifacty-mcp` with `node src/mcp-server.js`.

package/docs/integrations.md

@@ -34,10 +34,19 @@ node src/cli.js stop
 The lifecycle commands are intended to be cross-platform:
 
 - macOS and Linux: `stop` signals the detached process group first, then falls back to the server process id.
-- Windows: `start` hides the child console window, and `stop` uses `taskkill /PID <pid> /T`; `--force` adds `/F`.
+- Windows: `start` hides the child console window, and `stop` uses `taskkill /PID <pid> /T`, falling back to `/F` when Windows requires forceful termination. `--force` uses `/F` immediately.
 - All platforms: `status` combines the managed pid file with the HTTP `/health` endpoint, so a stale pid alone is not reported as healthy.
 
-For login/startup persistence, use the operating system's service manager. Artifacty's `service` command currently generates a macOS LaunchAgent plist; Linux systemd user units and Windows Task Scheduler/Service wrappers should be configured explicitly until first-class installers are added.
+Run diagnostics when setup behaves unexpectedly:
+
+```bash
+node src/cli.js doctor
+node src/cli.js doctor --skip-mcp
+```
+
+`doctor` checks Node version support, local exposure settings, store integrity, managed server health, service definition rendering, and MCP discovery. A stopped server is reported as a warning, not a failure.
+
+For login/startup persistence, use the operating system's service manager. Artifacty's `service` command can generate macOS LaunchAgent, Linux systemd user-unit, and Windows Task Scheduler definitions.
 
 Create artifacts directly in the browser at `http://127.0.0.1:8787/new`.
 
@@ -85,6 +94,7 @@ node src/cli.js check
 - `--dry-run` returns the generated config without writing it.
 - `--timeout <ms>` adjusts Codex `startup_timeout_sec` and Gemini `timeout`. It does not change Claude Code startup behavior; set `MCP_TIMEOUT` before launching Claude Code if you need a larger value there.
 - `check` starts the local MCP server and verifies required tools, resources, and prompts through MCP discovery methods.
+- `doctor` combines MCP discovery with runtime, storage, server, and service diagnostics.
 
 ## Client Compatibility Matrix
 
@@ -299,17 +309,33 @@ Renderer notes:
 
 ## Background Service
 
-Generate or install a macOS LaunchAgent plist:
+Generate platform-specific service definitions:
+
+```bash
+node src/cli.js service plist --dry-run
+node src/cli.js service unit --dry-run
+node src/cli.js service task --dry-run
+```
+
+Install the definition for the current OS:
 
 ```bash
-node src/cli.js service plist
 node src/cli.js service install --dry-run
 node src/cli.js service install
+node src/cli.js service uninstall --dry-run
 ```
 
-The generated service runs `src/server.js` with explicit `--host` and `--home` arguments. It includes `--port` only when you configure a port, which keeps the default port fallback available. Load or unload it manually with the `launchctl` commands returned by `service install`.
+Use `--platform macos|linux|windows` when preparing a definition for another host. Use `--path` to choose the output path, or the platform-specific aliases `--plist`, `--unit`, and `--script`.
+
+The generated service runs `src/server.js` with explicit `--host` and `--home` arguments. It includes `--port` only when you configure a port, which keeps the default port fallback available. `--api-token`, `--share-mode`, and `--allow-secrets` are preserved in the generated definition when explicitly provided.
+
+Activation is still delegated to the OS service manager:
+
+- macOS: `launchctl load ~/Library/LaunchAgents/com.artifacty.server.plist`
+- Linux: `systemctl --user enable --now com.artifacty.server.service`
+- Windows: run the generated PowerShell script, which registers and starts the `ArtifactyServer` scheduled task.
 
-For background services, prefer a stable `ARTIFACTY_API_TOKEN` in the service environment. `serve --generate-token` is intended for temporary interactive sessions; the parent CLI returns the generated token in JSON.
+For background services, prefer a stable `ARTIFACTY_API_TOKEN` or `--api-token` value. `serve --generate-token` is intended for temporary interactive sessions; the parent CLI returns the generated token in JSON.
 
 ## Backup and Audit
 

package/docs/release-checklist.md

@@ -10,6 +10,12 @@ npm run release:check
 
 This runs syntax checks, the full Node test suite, and a local smoke test that starts the HTTP server with token auth enabled, creates an artifact, verifies secret blocking, reads audit logs, writes a backup, and checks MCP tool/resource/prompt discovery.
 
+Run the local diagnostics pass:
+
+```bash
+artifacty doctor
+```
+
 ## Packaging
 
 - Confirm `package.json` `version` and `files` are intentional.
@@ -25,6 +31,7 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
 - Require `ARTIFACTY_API_TOKEN` and `ARTIFACTY_SHARE_MODE=lan` or `team` before binding to `0.0.0.0`.
 - Confirm non-loopback startup output includes the LAN/team warning.
 - Confirm `artifacty serve` starts a managed background server and returns prompt-friendly JSON; use `artifacty serve --foreground` for attached log checks.
+- Confirm `artifacty service plist|unit|task --dry-run` renders macOS, Linux, and Windows service definitions.
 - Prefer `x-artifacty-token` or `Authorization: Bearer <token>` over query tokens in scripts.
 - Review secret-scan bypasses. `--allow-secrets` and `ARTIFACTY_ALLOW_SECRETS=true` should be deliberate and temporary.
 - Review [../SECURITY.md](../SECURITY.md) and [threat-model.md](threat-model.md) when changing auth, rendering, MCP, or network-sharing behavior.
@@ -46,4 +53,5 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
 
 - Export a backup before upgrades: `artifacty backup`.
 - Confirm `artifacty audit --limit 20` shows recent create/update/read/archive events.
-- For macOS background service installs, dry-run first: `artifacty service install --dry-run`.
+- Confirm `artifacty doctor` reports no failures. A stopped server warning is acceptable when intentionally checking an offline store.
+- For background service installs, dry-run first: `artifacty service install --dry-run`. Use `--platform macos|linux|windows` to review another OS definition.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -28,7 +28,7 @@
     "start": "node src/server.js",
     "mcp": "node src/mcp-server.js",
     "test": "node --test",
-    "lint": "node --check src/*.js src/lib/*.js src/client/*.js test/*.test.js",
+    "lint": "node scripts/lint.mjs",
     "smoke": "bash scripts/smoke.sh",
     "release:check": "npm run lint && npm test && npm run smoke"
   },
@@ -42,6 +42,7 @@
     "docs/release-checklist.md",
     "docs/sarif-csv-artifact-plan.md",
     "docs/threat-model.md",
+    "scripts/lint.mjs",
     "scripts/smoke.sh",
     "README.md",
     "LICENSE",

package/scripts/lint.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+const targets = [
+  { dir: "src", pattern: /\.js$/ },
+  { dir: path.join("src", "lib"), pattern: /\.js$/ },
+  { dir: path.join("src", "client"), pattern: /\.js$/ },
+  { dir: "test", pattern: /\.test\.js$/ }
+];
+
+const files = [];
+
+for (const target of targets) {
+  const entries = await readdir(target.dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isFile() && target.pattern.test(entry.name)) {
+      files.push(path.join(target.dir, entry.name));
+    }
+  }
+}
+
+files.sort();
+
+for (const file of files) {
+  const result = spawnSync(process.execPath, ["--check", file], {
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}

package/src/cli.js

@@ -22,6 +22,7 @@ import { serviceCommand } from "./lib/service.js";
 import { backgroundStatus, startBackgroundServer, stopBackgroundServer } from "./lib/background.js";
 import { resolvePublicBaseUrl } from "./lib/server-state.js";
 import { generateToken } from "./lib/token.js";
+import { runDoctor } from "./lib/doctor.js";
 import { startServer } from "./server.js";
 
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
@@ -105,6 +106,27 @@ async function main() {
     return;
   }
 
+  if (command === "doctor") {
+    const result = await runDoctor({
+      packageRoot: PACKAGE_ROOT,
+      serverPath: options.serverPath,
+      url: options.url,
+      home: options.home,
+      host: options.host,
+      port: options.port,
+      apiToken: options.apiToken,
+      shareMode: options.shareMode,
+      allowSecrets: options.allowSecrets,
+      timeout: options.timeout,
+      skipMcp: options.skipMcp
+    });
+    printJson(result);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (command === "publish") {
     const content = await readContent(options);
     const artifact = await createArtifact(store, {
@@ -280,6 +302,13 @@ async function main() {
       projectDir: options.projectDir || PACKAGE_ROOT,
       serverPath: options.serverPath,
       plistPath: options.plist,
+      unitPath: options.unit,
+      scriptPath: options.script,
+      servicePath: options.path,
+      platform: options.platform,
+      apiToken: options.apiToken,
+      shareMode: options.shareMode,
+      allowSecrets: options.allowSecrets,
       host: options.host,
       port: options.port,
       home: options.home,
@@ -317,7 +346,7 @@ function parseArgs(args) {
     }
 
     const key = arg.slice(2);
-    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force") {
+    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force" || key === "skip-mcp") {
       options[toCamelCase(key)] = true;
       continue;
     }
@@ -405,6 +434,7 @@ Usage:
   artifacty start [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--timeout 30000]
   artifacty status [--home ~/.artifacty]
   artifacty stop [--home ~/.artifacty] [--timeout 30000] [--force]
+  artifacty doctor [--home ~/.artifacty] [--skip-mcp] [--timeout 5000]
   artifacty publish --title <title> (--file <path> | --content <text>) [--format html|markdown|text|json|code|svg|mermaid|react] [--source agent] [--tag tag]
   artifacty import --agent claude|codex|gemini|copilot|cursor|auto (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react] [--tag tag]
   artifacty install claude|codex|gemini|copilot|cursor|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--timeout 30000]
@@ -418,7 +448,7 @@ Usage:
   artifacty export --file <path>
   artifacty backup [--file <path>]
   artifacty import-store --file <path>
-  artifacty service plist|install|uninstall [--dry-run] [--plist <path>]
+  artifacty service plist|unit|task|install|uninstall [--platform macos|linux|windows] [--dry-run] [--path <path>]
   artifacty list [--query text] [--tag tag] [--source agent] [--limit 50] [--offset 0] [--include-archived]
   artifacty show <id> [--version n] [--raw]
 

package/src/lib/background.js

@@ -248,10 +248,20 @@ function buildServerEnv(options) {
 async function terminatePid(pid, options = {}) {
   const command = stopCommandForPlatform(pid, options);
   if (command) {
-    await execFileQuiet(command.command, command.args).catch((error) => {
+    await execFileQuiet(command.command, command.args).catch(async (error) => {
       if (!isPidRunning(pid)) {
         return;
       }
+      if (!options.force) {
+        const forced = stopCommandForPlatform(pid, { force: true });
+        await execFileQuiet(forced.command, forced.args).catch((forcedError) => {
+          if (!isPidRunning(pid)) {
+            return;
+          }
+          throw new Error(`Failed to stop Windows process ${pid}: ${forcedError.stderr || forcedError.message}`);
+        });
+        return;
+      }
       throw new Error(`Failed to stop Windows process ${pid}: ${error.stderr || error.message}`);
     });
     return;

package/src/lib/doctor.js

@@ -0,0 +1,214 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { arch, platform } from "node:os";
+import { backgroundStatus } from "./background.js";
+import { checkMcpTools } from "./check.js";
+import { securityConfig, validateServerExposure, exposureWarning } from "./security.js";
+import { serviceCommand } from "./service.js";
+import { checkStoreIntegrity, createStore } from "./storage.js";
+
+const MIN_NODE_VERSION = "22.5.0";
+
+export async function runDoctor(options = {}) {
+  const packageRoot = path.resolve(options.packageRoot || process.cwd());
+  const store = createStore({ home: options.home });
+  const checks = [];
+
+  await collect(checks, "runtime", () => runtimeCheck(packageRoot));
+  await collect(checks, "security", () => securityCheck(options));
+  await collect(checks, "storage", () => storageCheck(store));
+  await collect(checks, "server", () => serverCheck(store));
+  await collect(checks, "service", () => serviceCheck(options));
+  if (options.skipMcp) {
+    checks.push({
+      name: "mcp",
+      status: "skip",
+      message: "MCP discovery skipped by --skip-mcp"
+    });
+  } else {
+    await collect(checks, "mcp", () => mcpCheck(packageRoot, options));
+  }
+
+  const failures = checks.filter((check) => check.status === "fail");
+  const warnings = checks.filter((check) => check.status === "warn");
+
+  return {
+    ok: failures.length === 0,
+    checkedAt: new Date().toISOString(),
+    version: await packageVersion(packageRoot),
+    home: store.home,
+    platform: process.platform,
+    checks,
+    failures: failures.map(({ name, message }) => ({ name, message })),
+    warnings: warnings.map(({ name, message }) => ({ name, message }))
+  };
+}
+
+async function collect(checks, name, fn) {
+  try {
+    checks.push({ name, ...(await fn()) });
+  } catch (error) {
+    checks.push({
+      name,
+      status: "fail",
+      message: error.message,
+      error: {
+        name: error.name,
+        code: error.code
+      }
+    });
+  }
+}
+
+async function runtimeCheck(packageRoot) {
+  const version = await packageVersion(packageRoot);
+  const supported = compareVersions(process.versions.node, MIN_NODE_VERSION) >= 0;
+  return {
+    status: supported ? "pass" : "fail",
+    message: supported
+      ? `Node ${process.versions.node} satisfies >=${MIN_NODE_VERSION}`
+      : `Node ${process.versions.node} is below required >=${MIN_NODE_VERSION}`,
+    data: {
+      artifactyVersion: version,
+      nodeVersion: process.versions.node,
+      requiredNodeVersion: `>=${MIN_NODE_VERSION}`,
+      platform: platform(),
+      arch: arch()
+    }
+  };
+}
+
+function securityCheck(options = {}) {
+  const host = options.host || process.env.ARTIFACTY_HOST || "127.0.0.1";
+  const config = securityConfig(options);
+  validateServerExposure({ host, config });
+  const warning = exposureWarning({ host, config });
+  if (warning) {
+    return {
+      status: "warn",
+      message: warning,
+      data: {
+        host,
+        shareMode: config.shareMode,
+        hasApiToken: Boolean(config.apiToken)
+      }
+    };
+  }
+  return {
+    status: "pass",
+    message: "Server exposure settings are local-first",
+    data: {
+      host,
+      shareMode: config.shareMode,
+      hasApiToken: Boolean(config.apiToken)
+    }
+  };
+}
+
+async function storageCheck(store) {
+  const integrity = await checkStoreIntegrity(store);
+  return {
+    status: integrity.ok ? "pass" : "fail",
+    message: integrity.ok
+      ? `Store is consistent with ${integrity.artifactCount} artifacts and ${integrity.versionCount} versions`
+      : "Store integrity check found missing, changed, orphaned, or inconsistent files",
+    data: integrity
+  };
+}
+
+async function serverCheck(store) {
+  const status = await backgroundStatus({ home: store.home });
+  if (status.running) {
+    return {
+      status: "pass",
+      message: `Managed server is healthy at ${status.url}`,
+      data: status
+    };
+  }
+  if (status.processRunning || status.pidFileExists) {
+    return {
+      status: "fail",
+      message: "Recorded server process or pid file exists but health check is not passing",
+      data: status
+    };
+  }
+  return {
+    status: "warn",
+    message: "No managed Artifacty server is currently running",
+    data: status
+  };
+}
+
+async function serviceCheck(options = {}) {
+  const definitions = [];
+  for (const action of ["plist", "unit", "task"]) {
+    const result = await serviceCommand(action, {
+      projectDir: options.packageRoot || process.cwd(),
+      serverPath: options.serverPath,
+      host: options.host,
+      port: options.port,
+      home: options.home,
+      apiToken: options.apiToken,
+      shareMode: options.shareMode,
+      allowSecrets: options.allowSecrets,
+      dryRun: true
+    });
+    definitions.push({
+      action,
+      platform: result.platform,
+      path: result.path,
+      contentBytes: Buffer.byteLength(result.content || "", "utf8")
+    });
+  }
+  return {
+    status: "pass",
+    message: "Service definitions render for macOS, Linux, and Windows",
+    data: { definitions }
+  };
+}
+
+async function mcpCheck(packageRoot, options = {}) {
+  const result = await checkMcpTools({
+    projectDir: packageRoot,
+    serverPath: options.serverPath,
+    url: options.url,
+    home: options.home,
+    timeout: options.timeout
+  });
+  return {
+    status: result.ok ? "pass" : "fail",
+    message: result.ok
+      ? `MCP discovery found ${result.toolCount} tools, ${result.resourceCount} resources, and ${result.promptCount} prompts`
+      : "MCP discovery is missing required tools, resources, or prompts",
+    data: result
+  };
+}
+
+async function packageVersion(packageRoot) {
+  const file = path.join(packageRoot, "package.json");
+  const parsed = JSON.parse(await readFile(file, "utf8"));
+  return parsed.version;
+}
+
+function compareVersions(left, right) {
+  const leftParts = versionParts(left);
+  const rightParts = versionParts(right);
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    const leftPart = leftParts[index] || 0;
+    const rightPart = rightParts[index] || 0;
+    if (leftPart > rightPart) {
+      return 1;
+    }
+    if (leftPart < rightPart) {
+      return -1;
+    }
+  }
+  return 0;
+}
+
+function versionParts(value) {
+  return String(value)
+    .split(".")
+    .map((part) => Number.parseInt(part, 10))
+    .filter((part) => Number.isFinite(part));
+}

package/src/lib/service.js

@@ -1,67 +1,70 @@
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, platform as osPlatform } from "node:os";
 import path from "node:path";
 
 const DEFAULT_LABEL = "com.artifacty.server";
+const DEFAULT_TASK_NAME = "ArtifactyServer";
 
 export async function serviceCommand(action, options = {}) {
-  const plistPath = path.resolve(options.plistPath || path.join(homedir(), "Library", "LaunchAgents", `${DEFAULT_LABEL}.plist`));
-  const plist = createLaunchAgentPlist(options);
+  const definition = serviceDefinition(action, options);
 
-  if (action === "plist") {
-    return { action, path: plistPath, content: plist, dryRun: true };
+  if (definition.renderOnly) {
+    return {
+      action,
+      platform: definition.platform,
+      path: definition.path,
+      content: definition.content,
+      dryRun: true,
+      nextSteps: definition.nextSteps
+    };
   }
 
   if (action === "install") {
-    const existing = await readFile(plistPath, "utf8").catch(() => "");
-    const changed = existing !== plist;
+    const existing = await readFile(definition.path, "utf8").catch(() => "");
+    const changed = existing !== definition.content;
     if (!options.dryRun) {
-      await mkdir(path.dirname(plistPath), { recursive: true });
-      await writeFile(plistPath, plist, "utf8");
+      await mkdir(path.dirname(definition.path), { recursive: true });
+      await writeFile(definition.path, definition.content, "utf8");
     }
     return {
       action,
-      path: plistPath,
+      platform: definition.platform,
+      path: definition.path,
       changed,
       dryRun: Boolean(options.dryRun),
-      content: options.dryRun ? plist : undefined,
-      nextSteps: [
-        `launchctl load ${plistPath}`,
-        `launchctl unload ${plistPath}`
-      ]
+      content: options.dryRun ? definition.content : undefined,
+      nextSteps: definition.nextSteps
     };
   }
 
   if (action === "uninstall") {
-    const existed = existsSync(plistPath);
+    const existed = existsSync(definition.path);
     if (!options.dryRun) {
-      await rm(plistPath, { force: true });
+      await rm(definition.path, { force: true });
     }
     return {
       action,
-      path: plistPath,
+      platform: definition.platform,
+      path: definition.path,
       changed: existed,
-      dryRun: Boolean(options.dryRun)
+      dryRun: Boolean(options.dryRun),
+      nextSteps: definition.uninstallSteps
     };
   }
 
-  throw new Error("service requires action: plist, install, or uninstall");
+  throw new Error("service requires action: plist, unit, task, install, or uninstall");
 }
 
 export function createLaunchAgentPlist(options = {}) {
-  const projectDir = path.resolve(options.projectDir || process.cwd());
-  const nodePath = process.execPath;
-  const serverPath = path.resolve(options.serverPath || path.join(projectDir, "src", "server.js"));
-  const host = options.host || process.env.ARTIFACTY_HOST || "127.0.0.1";
-  const port = options.port || process.env.ARTIFACTY_PORT;
-  const home = path.resolve(options.home || process.env.ARTIFACTY_HOME || path.join(homedir(), ".artifacty"));
-  const logDir = path.join(home, "logs");
-  const portArguments = port
-    ? `    <string>--port</string>
-    <string>${escapeXml(port)}</string>
-`
-    : "";
+  const config = serviceConfig(options);
+  const programArguments = [config.nodePath, ...serverArgs(config)]
+    .map((argument) => `    <string>${escapeXml(argument)}</string>`)
+    .join("\n");
+  const environment = environmentEntries(config)
+    .map(([key, value]) => `    <key>${escapeXml(key)}</key>
+    <string>${escapeXml(value)}</string>`)
+    .join("\n");
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -71,31 +74,227 @@ export function createLaunchAgentPlist(options = {}) {
   <string>${DEFAULT_LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${escapeXml(nodePath)}</string>
-    <string>${escapeXml(serverPath)}</string>
-    <string>--host</string>
-    <string>${escapeXml(host)}</string>
-${portArguments}    <string>--home</string>
-    <string>${escapeXml(home)}</string>
+${programArguments}
   </array>
   <key>EnvironmentVariables</key>
   <dict>
-    <key>ARTIFACTY_HOME</key>
-    <string>${escapeXml(home)}</string>
+${environment}
   </dict>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
   <true/>
   <key>StandardOutPath</key>
-  <string>${escapeXml(path.join(logDir, "server.out.log"))}</string>
+  <string>${escapeXml(path.join(config.logDir, "server.out.log"))}</string>
   <key>StandardErrorPath</key>
-  <string>${escapeXml(path.join(logDir, "server.err.log"))}</string>
+  <string>${escapeXml(path.join(config.logDir, "server.err.log"))}</string>
 </dict>
 </plist>
 `;
 }
 
+export function createSystemdUserUnit(options = {}) {
+  const config = serviceConfig(options);
+  const environment = environmentEntries(config)
+    .map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`)
+    .join("\n");
+  const execStart = [config.nodePath, ...serverArgs(config)]
+    .map(systemdQuote)
+    .join(" ");
+
+  return `[Unit]
+Description=Artifacty local artifact server
+After=network.target
+
+[Service]
+Type=simple
+${environment}
+ExecStart=${execStart}
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function createWindowsTaskScript(options = {}) {
+  const config = serviceConfig(options);
+  const argumentsLine = serverArgs(config, { includeApiTokenArg: true })
+    .map(quoteWindowsArg)
+    .join(" ");
+
+  return `$ErrorActionPreference = 'Stop'
+
+$taskName = ${powershellString(config.taskName)}
+$node = ${powershellString(config.nodePath)}
+$arguments = ${powershellString(argumentsLine)}
+$description = 'Artifacty local artifact server'
+
+$action = New-ScheduledTaskAction -Execute $node -Argument $arguments
+$trigger = New-ScheduledTaskTrigger -AtLogOn
+$settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
+
+Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Settings $settings -Description $description -Force | Out-Null
+Start-ScheduledTask -TaskName $taskName
+
+Write-Host "Installed and started scheduled task '$taskName'."
+Write-Host "Stop: schtasks /End /TN $taskName"
+Write-Host "Remove: schtasks /Delete /TN $taskName /F"
+`;
+}
+
+function serviceDefinition(action, options = {}) {
+  if (action === "plist") {
+    return definitionForPlatform("macos", options, true);
+  }
+  if (action === "unit") {
+    return definitionForPlatform("linux", options, true);
+  }
+  if (action === "task") {
+    return definitionForPlatform("windows", options, true);
+  }
+  if (action === "install" || action === "uninstall") {
+    return definitionForPlatform(normalizePlatform(options.platform), options, false);
+  }
+  throw new Error("service requires action: plist, unit, task, install, or uninstall");
+}
+
+function definitionForPlatform(platform, options = {}, renderOnly) {
+  const config = serviceConfig({ ...options, platform });
+  if (platform === "macos") {
+    return {
+      platform,
+      renderOnly,
+      path: servicePath(platform, options),
+      content: createLaunchAgentPlist(options),
+      nextSteps: [
+        `launchctl load ${shellQuote(servicePath(platform, options))}`,
+        `launchctl unload ${shellQuote(servicePath(platform, options))}`
+      ],
+      uninstallSteps: [
+        `launchctl unload ${shellQuote(servicePath(platform, options))}`
+      ]
+    };
+  }
+  if (platform === "linux") {
+    return {
+      platform,
+      renderOnly,
+      path: servicePath(platform, options),
+      content: createSystemdUserUnit(options),
+      nextSteps: [
+        "systemctl --user daemon-reload",
+        `systemctl --user enable --now ${path.basename(servicePath(platform, options))}`,
+        `systemctl --user status ${path.basename(servicePath(platform, options))}`,
+        `journalctl --user -u ${path.basename(servicePath(platform, options))} -f`,
+        `systemctl --user disable --now ${path.basename(servicePath(platform, options))}`
+      ],
+      uninstallSteps: [
+        "systemctl --user daemon-reload",
+        `systemctl --user disable --now ${path.basename(servicePath(platform, options))}`
+      ]
+    };
+  }
+  if (platform === "windows") {
+    return {
+      platform,
+      renderOnly,
+      path: servicePath(platform, options),
+      content: createWindowsTaskScript(options),
+      nextSteps: [
+        `powershell -ExecutionPolicy Bypass -File ${quoteWindowsArg(servicePath(platform, options))}`,
+        `schtasks /Query /TN ${config.taskName}`,
+        `schtasks /End /TN ${config.taskName}`,
+        `schtasks /Delete /TN ${config.taskName} /F`
+      ],
+      uninstallSteps: [
+        `schtasks /Delete /TN ${config.taskName} /F`
+      ]
+    };
+  }
+  throw new Error(`Unsupported service platform: ${platform}`);
+}
+
+function serviceConfig(options = {}) {
+  const projectDir = path.resolve(options.projectDir || process.cwd());
+  const home = path.resolve(options.home || process.env.ARTIFACTY_HOME || path.join(homedir(), ".artifacty"));
+  return {
+    projectDir,
+    nodePath: path.resolve(options.nodePath || process.execPath),
+    serverPath: path.resolve(options.serverPath || path.join(projectDir, "src", "server.js")),
+    host: options.host || process.env.ARTIFACTY_HOST || "127.0.0.1",
+    port: options.port !== undefined && options.port !== null ? String(options.port) : process.env.ARTIFACTY_PORT || "",
+    home,
+    logDir: path.join(home, "logs"),
+    apiToken: options.apiToken || "",
+    shareMode: options.shareMode || "",
+    allowSecrets: Boolean(options.allowSecrets),
+    taskName: options.taskName || DEFAULT_TASK_NAME
+  };
+}
+
+function serverArgs(config, options = {}) {
+  const args = [
+    config.serverPath,
+    "--host",
+    config.host,
+    "--home",
+    config.home
+  ];
+  if (config.port) {
+    args.push("--port", String(config.port));
+  }
+  if (config.shareMode) {
+    args.push("--share-mode", config.shareMode);
+  }
+  if (config.allowSecrets) {
+    args.push("--allow-secrets");
+  }
+  if (options.includeApiTokenArg && config.apiToken) {
+    args.push("--api-token", config.apiToken);
+  }
+  return args;
+}
+
+function environmentEntries(config) {
+  const entries = [["ARTIFACTY_HOME", config.home]];
+  if (config.apiToken) {
+    entries.push(["ARTIFACTY_API_TOKEN", config.apiToken]);
+  }
+  return entries;
+}
+
+function servicePath(platform, options = {}) {
+  if (options.servicePath || options.path) {
+    return path.resolve(options.servicePath || options.path);
+  }
+  if (platform === "macos") {
+    return path.resolve(options.plistPath || path.join(homedir(), "Library", "LaunchAgents", `${DEFAULT_LABEL}.plist`));
+  }
+  if (platform === "linux") {
+    return path.resolve(options.unitPath || path.join(homedir(), ".config", "systemd", "user", `${DEFAULT_LABEL}.service`));
+  }
+  if (platform === "windows") {
+    const localAppData = process.env.LOCALAPPDATA || path.join(homedir(), "AppData", "Local");
+    return path.resolve(options.scriptPath || path.join(localAppData, "Artifacty", "install-artifacty-server-task.ps1"));
+  }
+  throw new Error(`Unsupported service platform: ${platform}`);
+}
+
+function normalizePlatform(value = osPlatform()) {
+  if (value === "darwin" || value === "mac" || value === "macos") {
+    return "macos";
+  }
+  if (value === "win32" || value === "windows" || value === "win") {
+    return "windows";
+  }
+  if (value === "linux") {
+    return "linux";
+  }
+  throw new Error("service platform must be macos, linux, or windows");
+}
+
 function escapeXml(value) {
   return String(value)
     .replaceAll("&", "&amp;")
@@ -103,3 +302,23 @@ function escapeXml(value) {
     .replaceAll(">", "&gt;")
     .replaceAll('"', "&quot;");
 }
+
+function systemdQuote(value) {
+  return `"${String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function powershellString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function quoteWindowsArg(value) {
+  const text = String(value);
+  if (!/[\s"]/.test(text)) {
+    return text;
+  }
+  return `"${text.replaceAll('"', '\\"')}"`;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}