artifacty 0.1.1 → 0.1.2

package/README.md

@@ -38,6 +38,17 @@ artifacty serve
 
 Open the URL printed by the server. Artifacty prefers `http://127.0.0.1:8787`; if that default port is busy and no explicit port was configured, it starts on the next available local port and records the actual URL for CLI and MCP responses.
 
+Run it in the background and return to your prompt:
+
+```bash
+artifacty start
+artifacty status
+artifacty stop
+```
+
+`artifacty serve --detach` is equivalent to `artifacty start`. 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.
+
 Generate an API token at startup when you want to protect HTTP API and browser write routes:
 
 ```bash
@@ -50,7 +61,7 @@ The server prints the generated token plus `/new?token=...` and `/import?token=.
 
 ```bash
 artifacty token
-ARTIFACTY_API_TOKEN="$(artifacty token --raw)" artifacty serve
+artifacty start --api-token "$(artifacty token --raw)"
 ```
 
 Install MCP configuration for local agents:
@@ -166,6 +177,9 @@ artifacty audit --limit 20
 artifacty backup
 artifacty export --file ./artifacty-backup.json
 artifacty import-store --file ./artifacty-backup.json
+artifacty start
+artifacty status
+artifacty stop
 artifacty service install --dry-run
 ```
 

package/docs/integrations.md

@@ -20,6 +20,24 @@ npm start -- --generate-token
 
 The generated token is printed with ready-to-open create and import URLs.
 
+For prompt-friendly local background runs, use the lifecycle commands:
+
+```bash
+node src/cli.js start --port 8787
+node src/cli.js status
+node src/cli.js stop
+```
+
+`serve --detach` uses the same detached-process path as `start`. It writes `server.pid`, `server.json`, and logs under `ARTIFACTY_HOME` (default `~/.artifacty`). Prefer `start --api-token "$(node src/cli.js token --raw)"` when a background server needs API protection, because generated startup tokens are only visible in the server log.
+
+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`.
+- 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.
+
 Create artifacts directly in the browser at `http://127.0.0.1:8787/new`.
 
 For LAN or VPN sharing, keep the default local binding unless you intentionally need another machine to reach the server. See [network-sharing.md](network-sharing.md) before using `--host 0.0.0.0`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [

package/src/cli.js

@@ -17,6 +17,7 @@ import { convertAgentArtifact } from "./lib/converters.js";
 import { checkMcpTools } from "./lib/check.js";
 import { installAgent } from "./lib/installer.js";
 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 { startServer } from "./server.js";
@@ -44,6 +45,13 @@ async function main() {
   }
 
   if (command === "serve") {
+    if (options.detach) {
+      printJson(await startBackgroundServer({
+        ...serverOptions(options),
+        serverPath: path.join(PACKAGE_ROOT, "src", "server.js")
+      }));
+      return;
+    }
     if (options.generateToken && options.apiToken) {
       throw new Error("Use either --api-token or --generate-token, not both");
     }
@@ -67,6 +75,28 @@ async function main() {
     return;
   }
 
+  if (command === "start") {
+    printJson(await startBackgroundServer({
+      ...serverOptions(options),
+      serverPath: path.join(PACKAGE_ROOT, "src", "server.js")
+    }));
+    return;
+  }
+
+  if (command === "stop") {
+    printJson(await stopBackgroundServer({
+      home: options.home,
+      timeout: options.timeout,
+      force: options.force
+    }));
+    return;
+  }
+
+  if (command === "status") {
+    printJson(await backgroundStatus({ home: options.home }));
+    return;
+  }
+
   if (command === "publish") {
     const content = await readContent(options);
     const artifact = await createArtifact(store, {
@@ -256,7 +286,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") {
+    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "force") {
       options[toCamelCase(key)] = true;
       continue;
     }
@@ -314,7 +344,10 @@ function printHelp() {
 
 Usage:
   artifacty token [--bytes 32] [--raw]
-  artifacty serve [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--generate-token] [--bytes 32]
+  artifacty serve [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--bytes 32] [--detach]
+  artifacty start [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--timeout 5000]
+  artifacty status [--home ~/.artifacty]
+  artifacty stop [--home ~/.artifacty] [--timeout 5000] [--force]
   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|auto (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react] [--tag tag]
   artifacty install claude|codex|gemini|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--timeout 30000]
@@ -353,6 +386,20 @@ function stripInstallContentUnlessDryRun(result) {
   return rest;
 }
 
+function serverOptions(options) {
+  return {
+    host: options.host,
+    port: options.port,
+    home: options.home,
+    apiToken: options.apiToken,
+    shareMode: options.shareMode,
+    allowSecrets: options.allowSecrets,
+    generateToken: options.generateToken,
+    bytes: options.bytes,
+    timeout: options.timeout
+  };
+}
+
 function toCamelCase(value) {
   return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }

package/src/lib/background.js

@@ -0,0 +1,344 @@
+import { execFile, spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createStore } from "./storage.js";
+import { readServerState, serverStatePath } from "./server-state.js";
+
+const DEFAULT_READY_TIMEOUT_MS = 5000;
+
+export async function startBackgroundServer(options = {}) {
+  if (options.generateToken && options.apiToken) {
+    throw new Error("Use either --api-token or --generate-token, not both");
+  }
+
+  const store = createStore({ home: options.home });
+  const paths = backgroundPaths(store);
+  const current = await backgroundStatus({ home: store.home });
+  if (current.running) {
+    throw new Error(`Artifacty server is already running on ${current.url || "unknown URL"} (pid ${current.pid})`);
+  }
+
+  mkdirSync(paths.logDir, { recursive: true });
+  mkdirSync(store.home, { recursive: true });
+
+  const child = spawnDetachedServer(options, store, paths);
+
+  writeFileSync(paths.pidFile, `${child.pid}\n`, "utf8");
+
+  try {
+    const ready = await waitForReady({
+      store,
+      pid: child.pid,
+      timeoutMs: Number(options.timeout || DEFAULT_READY_TIMEOUT_MS)
+    });
+    child.unref();
+    return {
+      action: "start",
+      running: true,
+      pid: child.pid,
+      url: ready.url,
+      home: store.home,
+      logs: {
+        stdout: paths.stdoutLog,
+        stderr: paths.stderrLog
+      },
+      statePath: serverStatePath(store)
+    };
+  } catch (error) {
+    try {
+      await terminatePid(child.pid);
+    } catch {
+      // Process may already have exited during startup.
+    }
+    rmSync(paths.pidFile, { force: true });
+    const logTail = await tailFile(paths.stderrLog);
+    const message = logTail ? `${error.message}\n${logTail}` : error.message;
+    throw new Error(message);
+  }
+}
+
+export async function stopBackgroundServer(options = {}) {
+  const store = createStore({ home: options.home });
+  const paths = backgroundPaths(store);
+  const status = await backgroundStatus({ home: store.home });
+
+  if (!status.pid || !status.pidFileExists) {
+    return {
+      action: "stop",
+      stopped: false,
+      running: status.running,
+      reason: status.pid ? "server was not started by artifacty start" : "server is not running",
+      pid: status.pid || null,
+      home: store.home
+    };
+  }
+
+  if (!status.processRunning) {
+    rmSync(paths.pidFile, { force: true });
+    return {
+      action: "stop",
+      stopped: false,
+      running: false,
+      reason: "removed stale pid file",
+      pid: status.pid,
+      home: store.home
+    };
+  }
+
+  if (!options.force && !status.stateMatchesPid && !status.healthy) {
+    return {
+      action: "stop",
+      stopped: false,
+      running: status.running,
+      reason: "pid file does not match a healthy Artifacty server; retry with --force to stop the recorded pid",
+      pid: status.pid,
+      home: store.home
+    };
+  }
+
+  await terminatePid(status.pid);
+  let stopped = await waitForStop(status.pid, Number(options.timeout || DEFAULT_READY_TIMEOUT_MS));
+  if (!stopped && options.force) {
+    await terminatePid(status.pid, { force: true });
+    stopped = await waitForStop(status.pid, 1000);
+  }
+  if (!stopped) {
+    return {
+      action: "stop",
+      stopped: false,
+      running: true,
+      reason: "server did not stop before timeout; retry with --force",
+      pid: status.pid,
+      home: store.home
+    };
+  }
+  rmSync(paths.pidFile, { force: true });
+
+  return {
+    action: "stop",
+    stopped: true,
+    running: false,
+    pid: status.pid,
+    home: store.home
+  };
+}
+
+export async function backgroundStatus(options = {}) {
+  const store = createStore({ home: options.home });
+  const paths = backgroundPaths(store);
+  const state = await readServerState(store);
+  const pidFromFile = readPidFile(paths.pidFile);
+  const pid = pidFromFile || state?.pid || null;
+  const processRunning = pid ? isPidRunning(pid) : false;
+  const health = state?.url ? await fetchHealth(state.url) : { ok: false };
+  const stateMatchesPid = Boolean(pid && state?.pid === pid);
+
+  return {
+    action: "status",
+    running: Boolean(processRunning && health.ok),
+    processRunning,
+    healthy: Boolean(health.ok),
+    platform: process.platform,
+    pid,
+    statePid: state?.pid || null,
+    stateMatchesPid,
+    pidFileExists: existsSync(paths.pidFile),
+    managed: Boolean(pidFromFile),
+    url: state?.url || null,
+    home: store.home,
+    logs: {
+      stdout: paths.stdoutLog,
+      stderr: paths.stderrLog
+    },
+    statePath: serverStatePath(store)
+  };
+}
+
+export function backgroundPaths(store) {
+  const logDir = path.join(store.home, "logs");
+  return {
+    logDir,
+    pidFile: path.join(store.home, "server.pid"),
+    stdoutLog: path.join(logDir, "server.out.log"),
+    stderrLog: path.join(logDir, "server.err.log")
+  };
+}
+
+export function stopCommandForPlatform(pid, options = {}, platform = process.platform) {
+  if (platform !== "win32") {
+    return null;
+  }
+  const args = ["/PID", String(pid), "/T"];
+  if (options.force) {
+    args.push("/F");
+  }
+  return { command: "taskkill", args };
+}
+
+function spawnDetachedServer(options, store, paths) {
+  let stdoutFd;
+  let stderrFd;
+  try {
+    stdoutFd = openSync(paths.stdoutLog, "a");
+    stderrFd = openSync(paths.stderrLog, "a");
+    return spawn(process.execPath, buildServerArgs(options, store), {
+      detached: true,
+      env: buildServerEnv(options),
+      stdio: ["ignore", stdoutFd, stderrFd],
+      windowsHide: true
+    });
+  } finally {
+    closeFd(stdoutFd);
+    closeFd(stderrFd);
+  }
+}
+
+export function buildServerArgs(options, store) {
+  const args = [options.serverPath];
+  addValueArg(args, "--host", options.host);
+  addValueArg(args, "--port", options.port);
+  addValueArg(args, "--home", store.home);
+  addValueArg(args, "--share-mode", options.shareMode);
+  addValueArg(args, "--bytes", options.bytes);
+  if (options.generateToken) {
+    args.push("--generate-token");
+  }
+  if (options.allowSecrets) {
+    args.push("--allow-secrets");
+  }
+  return args;
+}
+
+function buildServerEnv(options) {
+  return {
+    ...process.env,
+    ...(options.apiToken ? { ARTIFACTY_API_TOKEN: options.apiToken } : {})
+  };
+}
+
+async function terminatePid(pid, options = {}) {
+  const command = stopCommandForPlatform(pid, options);
+  if (command) {
+    await execFileQuiet(command.command, command.args).catch((error) => {
+      if (!isPidRunning(pid)) {
+        return;
+      }
+      throw new Error(`Failed to stop Windows process ${pid}: ${error.stderr || error.message}`);
+    });
+    return;
+  }
+
+  const signal = options.force ? "SIGKILL" : "SIGTERM";
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch (error) {
+      if (error.code !== "ESRCH") {
+        throw error;
+      }
+    }
+  }
+}
+
+function execFileQuiet(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { windowsHide: true }, (error, stdout, stderr) => {
+      if (error) {
+        reject(Object.assign(error, { stdout, stderr }));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+function addValueArg(args, name, value) {
+  if (value !== undefined && value !== null && value !== "") {
+    args.push(name, String(value));
+  }
+}
+
+async function waitForReady({ store, pid, timeoutMs }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidRunning(pid)) {
+      throw new Error("Artifacty server exited before it became ready");
+    }
+    const state = await readServerState(store);
+    if (state?.pid === pid && state.url) {
+      const health = await fetchHealth(state.url);
+      if (health.ok) {
+        return state;
+      }
+    }
+    await delay(100);
+  }
+  throw new Error(`Timed out waiting for Artifacty server to become ready after ${timeoutMs}ms`);
+}
+
+async function waitForStop(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidRunning(pid)) {
+      return true;
+    }
+    await delay(100);
+  }
+  return !isPidRunning(pid);
+}
+
+function readPidFile(pidFile) {
+  try {
+    const pid = Number(readFileSync(pidFile, "utf8").trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPidRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+async function fetchHealth(url) {
+  try {
+    const response = await fetch(`${url}/health`, {
+      signal: AbortSignal.timeout(500)
+    });
+    return { ok: response.ok, status: response.status };
+  } catch {
+    return { ok: false };
+  }
+}
+
+async function tailFile(file, maxBytes = 2000) {
+  try {
+    const content = await readFile(file, "utf8");
+    return content.slice(-maxBytes).trim();
+  } catch {
+    return "";
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function closeFd(fd) {
+  if (typeof fd !== "number") {
+    return;
+  }
+  try {
+    closeSync(fd);
+  } catch {
+    // The child inherited the descriptor; parent cleanup is best effort.
+  }
+}