@hermespilot/link 0.1.2 → 0.1.4

package/README.md

@@ -22,11 +22,17 @@ hermeslink --version
 hermeslink status
 hermeslink pair
 hermeslink start
+hermeslink stop
+hermeslink autostart on
+hermeslink autostart off
 hermeslink doctor
+hermeslink logs
 ```
 
 `hermeslink pair` requires HermesPilot Server and Relay to be available. The terminal side does not ask for a HermesPilot account; the App must be logged in before it scans or claims a pairing session.
 
+After a successful QR claim, `hermeslink pair` starts Hermes Link in the background and enables boot autostart. Boot autostart does not configure launchd/systemd restart policies; if the user stops Hermes Link, the operating system should not automatically relaunch it until the next login/boot autostart cycle.
+
 CLI output follows the current system language when it is Chinese or English. You can override it for a single command with `HERMESLINK_LANG=zh-CN` or `HERMESLINK_LANG=en`.
 
 ## Runtime data
@@ -38,3 +44,5 @@ Hermes Link keeps its local identity and runtime state under:
 ```
 
 Uninstalling the npm package does not remove this directory, so the same Link ID can be reused after reinstalling.
+
+Service logs are written as rotated JSONL files under `~/.hermeslink/logs/hermeslink.log`. A paired App can read the same service log stream through `GET /api/v1/logs` using the normal Link access token.

package/dist/{chunk-E2BRK5JT.js → chunk-T35GPRKF.js}

@@ -4,7 +4,7 @@ import Router from "@koa/router";
 import { Readable } from "stream";
 
 // src/constants.ts
-var LINK_VERSION = "0.1.2";
+var LINK_VERSION = "0.1.4";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -270,7 +270,7 @@ async function cancelHermesRun(runId, options = {}) {
   }
   fallbackRuns.delete(runId);
 }
-async function callHermesApi(path5, init, options) {
+async function callHermesApi(path6, init, options) {
   const config = await readHermesApiServerConfig();
   if (!config.port || !config.key) {
     return new Response(null, { status: 503 });
@@ -280,7 +280,7 @@ async function callHermesApi(path5, init, options) {
   headers.set("accept", headers.get("accept") ?? "application/json");
   headers.set("x-api-key", config.key);
   headers.set("authorization", `Bearer ${config.key}`);
-  return await fetcher(`http://127.0.0.1:${config.port}${path5}`, {
+  return await fetcher(`http://127.0.0.1:${config.port}${path6}`, {
     ...init,
     headers
   }).catch(() => new Response(null, { status: 503 }));
@@ -930,8 +930,8 @@ async function loadRequiredIdentity(paths) {
   }
   return identity;
 }
-async function postServerJson(serverBaseUrl, path5, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path5}`, {
+async function postServerJson(serverBaseUrl, path6, body) {
+  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path6}`, {
     method: "POST",
     headers: {
       accept: "application/json",
@@ -941,8 +941,8 @@ async function postServerJson(serverBaseUrl, path5, body) {
   });
   return readJsonResponse2(response);
 }
-async function patchServerJson(serverBaseUrl, path5, token, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path5}`, {
+async function patchServerJson(serverBaseUrl, path6, token, body) {
+  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path6}`, {
     method: "PATCH",
     headers: {
       accept: "application/json",
@@ -1048,11 +1048,217 @@ function base64UrlToBase64(value) {
   return normalized + "=".repeat((4 - normalized.length % 4) % 4);
 }
 
+// src/runtime/logger.ts
+import { appendFile, mkdir as mkdir5, open as open2, readFile as readFile3, rename as rename3, rm as rm3, stat as stat2 } from "fs/promises";
+import path5 from "path";
+var DEFAULT_LOG_FILE = "hermeslink.log";
+var DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
+var DEFAULT_MAX_FILES = 5;
+var DEFAULT_READ_LIMIT = 200;
+var MAX_READ_LIMIT = 1e3;
+var DEFAULT_MAX_BYTES_PER_FILE = 512 * 1024;
+var FileLogger = class {
+  filePath;
+  paths;
+  maxFileBytes;
+  maxFiles;
+  now;
+  queue = Promise.resolve();
+  constructor(options = {}) {
+    this.paths = options.paths ?? resolveRuntimePaths();
+    this.filePath = getLinkLogFile(this.paths, options.fileName);
+    this.maxFileBytes = Math.max(256, Math.floor(options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES));
+    this.maxFiles = Math.max(0, Math.floor(options.maxFiles ?? DEFAULT_MAX_FILES));
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  debug(message, fields) {
+    return this.write("debug", message, fields);
+  }
+  info(message, fields) {
+    return this.write("info", message, fields);
+  }
+  warn(message, fields) {
+    return this.write("warn", message, fields);
+  }
+  error(message, fields) {
+    return this.write("error", message, fields);
+  }
+  write(level, message, fields) {
+    const entry = {
+      ts: this.now().toISOString(),
+      level,
+      message,
+      ...fields ? { fields: sanitizeFields(fields) } : {}
+    };
+    const next = this.queue.then(() => this.appendEntry(entry)).catch(() => void 0);
+    this.queue = next;
+    return next;
+  }
+  flush() {
+    return this.queue;
+  }
+  async appendEntry(entry) {
+    await mkdir5(this.paths.logsDir, { recursive: true, mode: 448 });
+    const line = `${JSON.stringify(entry)}
+`;
+    await this.rotateIfNeeded(Buffer.byteLength(line, "utf8"));
+    await appendFile(this.filePath, line, { mode: 384 });
+  }
+  async rotateIfNeeded(nextBytes) {
+    const current = await stat2(this.filePath).catch(() => null);
+    if (!current || current.size === 0 || current.size + nextBytes <= this.maxFileBytes) {
+      return;
+    }
+    if (this.maxFiles === 0) {
+      await rm3(this.filePath, { force: true }).catch(() => void 0);
+      return;
+    }
+    await rm3(rotatedLogFile(this.filePath, this.maxFiles), { force: true }).catch(() => void 0);
+    for (let index = this.maxFiles - 1; index >= 1; index -= 1) {
+      await moveIfExists(rotatedLogFile(this.filePath, index), rotatedLogFile(this.filePath, index + 1));
+    }
+    await moveIfExists(this.filePath, rotatedLogFile(this.filePath, 1));
+  }
+};
+function createFileLogger(options = {}) {
+  return new FileLogger(options);
+}
+function getLinkLogFile(paths = resolveRuntimePaths(), fileName = DEFAULT_LOG_FILE) {
+  return path5.join(paths.logsDir, fileName);
+}
+async function readRecentLogEntries(options = {}) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  const filePath = getLinkLogFile(paths, options.fileName);
+  const limit = clampLimit(options.limit);
+  const maxFiles = Math.max(0, Math.floor(options.maxFiles ?? DEFAULT_MAX_FILES));
+  const maxBytesPerFile = Math.max(1024, Math.floor(options.maxBytesPerFile ?? DEFAULT_MAX_BYTES_PER_FILE));
+  const files = [filePath, ...Array.from({ length: maxFiles }, (_, index) => rotatedLogFile(filePath, index + 1))];
+  const entries = [];
+  for (const file of files) {
+    const raw = await readTail(file, maxBytesPerFile);
+    if (!raw) {
+      continue;
+    }
+    const lines = raw.split(/\r?\n/u).filter(Boolean);
+    for (let index = lines.length - 1; index >= 0 && entries.length < limit; index -= 1) {
+      const entry = parseLogLine(lines[index]);
+      if (entry) {
+        entries.push(entry);
+      }
+    }
+    if (entries.length >= limit) {
+      break;
+    }
+  }
+  return entries.reverse();
+}
+function clampLimit(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_READ_LIMIT;
+  }
+  return Math.min(MAX_READ_LIMIT, Math.max(1, Math.floor(value)));
+}
+function sanitizeFields(fields) {
+  return sanitizeObject(fields, 0);
+}
+function sanitizeValue(value, depth) {
+  if (value === null || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "string") {
+    return value.length > 2e3 ? `${value.slice(0, 2e3)}...` : value;
+  }
+  if (Array.isArray(value)) {
+    if (depth >= 3) {
+      return "[array]";
+    }
+    return value.slice(0, 20).map((item) => sanitizeValue(item, depth + 1));
+  }
+  if (typeof value === "object" && value !== null) {
+    if (depth >= 3) {
+      return "[object]";
+    }
+    return sanitizeObject(value, depth + 1);
+  }
+  return String(value);
+}
+function sanitizeObject(value, depth) {
+  const result = {};
+  for (const [key, child] of Object.entries(value).slice(0, 50)) {
+    if (isSensitiveKey(key)) {
+      result[key] = "[redacted]";
+      continue;
+    }
+    result[key] = sanitizeValue(child, depth);
+  }
+  return result;
+}
+function isSensitiveKey(key) {
+  return /(authorization|cookie|token|secret|password|private[_-]?key|api[_-]?key)/iu.test(key);
+}
+function parseLogLine(line) {
+  try {
+    const value = JSON.parse(line);
+    if (!value || typeof value.ts !== "string" || !isLogLevel(value.level) || typeof value.message !== "string") {
+      return null;
+    }
+    return {
+      ts: value.ts,
+      level: value.level,
+      message: value.message,
+      ...value.fields && typeof value.fields === "object" ? { fields: value.fields } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+function isLogLevel(value) {
+  return value === "debug" || value === "info" || value === "warn" || value === "error";
+}
+async function readTail(filePath, maxBytes) {
+  const info = await stat2(filePath).catch(() => null);
+  if (!info || info.size <= 0) {
+    return null;
+  }
+  if (info.size <= maxBytes) {
+    return await readFile3(filePath, "utf8").catch(() => null);
+  }
+  const handle = await open2(filePath, "r").catch(() => null);
+  if (!handle) {
+    return null;
+  }
+  try {
+    const length = Math.min(info.size, maxBytes);
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, info.size - length);
+    return buffer.toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+async function moveIfExists(from, to) {
+  await rm3(to, { force: true }).catch(() => void 0);
+  await rename3(from, to).catch((error) => {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  });
+}
+function rotatedLogFile(filePath, index) {
+  return `${filePath}.${index}`;
+}
+
 // src/http/app.ts
-async function createApp() {
+async function createApp(options = {}) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  const logger = options.logger ?? createFileLogger({ paths });
   const app = new Koa();
   const router = new Router();
   app.use(async (ctx, next) => {
+    const startedAt = Date.now();
     try {
       await next();
     } catch (error) {
@@ -1066,10 +1272,24 @@ async function createApp() {
           message: error instanceof Error ? error.message : "Internal error"
         }
       };
+      void logger.write(status >= 500 ? "error" : "warn", "http_request_failed", {
+        method: ctx.method,
+        path: ctx.path,
+        status,
+        code: isLinkHttpError(error) ? error.code : status === 400 ? "invalid_profile_name" : "internal_error",
+        error: error instanceof Error ? error.message : String(error)
+      });
+    } finally {
+      void logger.info("http_request", {
+        method: ctx.method,
+        path: ctx.path,
+        status: ctx.status,
+        duration_ms: Date.now() - startedAt
+      });
     }
   });
   router.get("/api/v1/bootstrap", async (ctx) => {
-    const [identity, config] = await Promise.all([loadIdentity(), loadConfig()]);
+    const [identity, config] = await Promise.all([loadIdentity(paths), loadConfig(paths)]);
     const routes = identity?.link_id ? await discoverRouteCandidates({
       port: config.port,
       relayBaseUrl: config.relayBaseUrl,
@@ -1091,7 +1311,8 @@ async function createApp() {
         runs: true,
         sse: true,
         relay: true,
-        profiles: true
+        profiles: true,
+        logs: true
       }
     };
   });
@@ -1102,16 +1323,28 @@ async function createApp() {
     if (!sessionId || !claimToken) {
       throw new LinkHttpError(400, "pairing_claim_invalid", "session_id and claim_token are required");
     }
-    ctx.body = await claimPairing({
+    const claimed = await claimPairing({
       sessionId,
       claimToken,
       deviceLabel: readString2(body, "device_label") ?? readString2(body, "deviceLabel") ?? "HermesPilot App",
-      devicePlatform: readString2(body, "device_platform") ?? readString2(body, "devicePlatform") ?? "unknown"
+      devicePlatform: readString2(body, "device_platform") ?? readString2(body, "devicePlatform") ?? "unknown",
+      paths
     });
+    ctx.body = claimed;
+    void logger.info("pairing_claimed", {
+      device_id: claimed.device.device_id,
+      device_platform: claimed.device.platform
+    });
+    if (options.onPairingClaimed) {
+      const timer = setTimeout(() => {
+        void options.onPairingClaimed?.();
+      }, 250);
+      timer.unref?.();
+    }
   });
   router.get("/api/v1/auth/me", async (ctx) => {
-    const auth = await authenticateRequest(ctx);
-    const identity = await loadRequiredIdentity2();
+    const auth = await authenticateRequest(ctx, paths);
+    const identity = await loadRequiredIdentity2(paths);
     ctx.body = {
       ok: true,
       auth: { kind: auth.kind, account_id: auth.accountId ?? null },
@@ -1134,7 +1367,7 @@ async function createApp() {
     if (!refreshToken) {
       throw new LinkHttpError(400, "refresh_token_required", "refresh_token is required");
     }
-    const session = await refreshDeviceSession(refreshToken);
+    const session = await refreshDeviceSession(refreshToken, paths);
     ctx.body = {
       ok: true,
       device: session.device,
@@ -1152,13 +1385,13 @@ async function createApp() {
     const body = await readJsonBody(ctx.req);
     const refreshToken = readString2(body, "refresh_token") ?? readString2(body, "refreshToken");
     if (refreshToken) {
-      await revokeDeviceRefreshToken(refreshToken);
+      await revokeDeviceRefreshToken(refreshToken, paths);
     }
     ctx.body = { ok: true };
   });
   router.get("/api/v1/status", async (ctx) => {
-    await authenticateRequest(ctx);
-    const [identity, config] = await Promise.all([loadIdentity(), loadConfig()]);
+    await authenticateRequest(ctx, paths);
+    const [identity, config] = await Promise.all([loadIdentity(paths), loadConfig(paths)]);
     ctx.body = {
       ok: true,
       version: LINK_VERSION,
@@ -1167,12 +1400,23 @@ async function createApp() {
       port: config.port
     };
   });
+  router.get("/api/v1/logs", async (ctx) => {
+    await authenticateRequest(ctx, paths);
+    ctx.set("cache-control", "no-store");
+    ctx.body = {
+      ok: true,
+      logs: await readRecentLogEntries({
+        paths,
+        limit: readLimit(ctx.query.limit)
+      })
+    };
+  });
   router.get("/api/v1/models", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     ctx.body = await listHermesModels();
   });
   router.post("/api/v1/runs", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     const body = await readJsonBody(ctx.req);
     const input = readString2(body, "input");
     if (!input) {
@@ -1186,7 +1430,7 @@ async function createApp() {
     });
   });
   router.get("/api/v1/runs/:runId/events", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     const response = await streamHermesRunEvents(ctx.params.runId);
     ctx.status = response.status;
     for (const [key, value] of response.headers.entries()) {
@@ -1205,12 +1449,12 @@ async function createApp() {
     }
   });
   router.post("/api/v1/runs/:runId/cancel", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     await cancelHermesRun(ctx.params.runId);
     ctx.body = { ok: true };
   });
   router.get("/api/v1/profiles", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     ctx.set("cache-control", "no-store");
     ctx.body = {
       ok: true,
@@ -1218,7 +1462,7 @@ async function createApp() {
     };
   });
   router.get("/api/v1/profiles/:name/status", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     ctx.set("cache-control", "no-store");
     ctx.body = {
       ok: true,
@@ -1226,7 +1470,7 @@ async function createApp() {
     };
   });
   router.post("/api/v1/profiles", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     const body = await readJsonBody(ctx.req);
     const name = readProfileName(body);
     ctx.status = 201;
@@ -1236,14 +1480,14 @@ async function createApp() {
     };
   });
   router.post("/api/v1/profiles/:name/use", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     ctx.body = {
       ok: true,
       profile: await useHermesProfile(ctx.params.name)
     };
   });
   router.patch("/api/v1/profiles/:name", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     const body = await readJsonBody(ctx.req);
     const name = readProfileName(body);
     ctx.body = {
@@ -1252,7 +1496,7 @@ async function createApp() {
     };
   });
   router.delete("/api/v1/profiles/:name", async (ctx) => {
-    await authenticateRequest(ctx);
+    await authenticateRequest(ctx, paths);
     await deleteHermesProfile(ctx.params.name);
     ctx.status = 204;
   });
@@ -1276,24 +1520,24 @@ function readProfileName(body) {
   }
   return body.name;
 }
-async function authenticateRequest(ctx) {
+async function authenticateRequest(ctx, paths) {
   const token = readBearerToken(ctx.get("authorization"));
   if (!token) {
     throw new LinkHttpError(401, "auth_required", "Authorization bearer token is required");
   }
-  const device = await authenticateDeviceAccessToken(token);
+  const device = await authenticateDeviceAccessToken(token, paths);
   if (device) {
     return { kind: "device", device };
   }
-  const [identity, config] = await Promise.all([loadRequiredIdentity2(), loadConfig()]);
+  const [identity, config] = await Promise.all([loadRequiredIdentity2(paths), loadConfig(paths)]);
   const claims = await verifyAppConnectToken(token, {
     config,
     linkId: identity.link_id
   });
   return { kind: "app-connect", accountId: claims.sub };
 }
-async function loadRequiredIdentity2() {
-  const identity = await loadIdentity();
+async function loadRequiredIdentity2(paths) {
+  const identity = await loadIdentity(paths);
   if (!identity?.link_id) {
     throw new LinkHttpError(409, "link_not_paired", "Hermes Link is not paired");
   }
@@ -1311,6 +1555,14 @@ function readString2(body, key) {
   const value = body[key];
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
+function readLimit(value) {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (typeof raw !== "string") {
+    return void 0;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
 function readConversationHistory(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -1345,6 +1597,8 @@ export {
   ensureIdentity,
   getIdentityStatus,
   preparePairing,
+  createFileLogger,
+  getLinkLogFile,
   createApp
 };
-//# sourceMappingURL=chunk-E2BRK5JT.js.map
+//# sourceMappingURL=chunk-T35GPRKF.js.map