@scoutmesh/viewer 0.2.0

package/dist/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { once } from "node:events";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { openExternalBrowser } from "./external-browser.js";
+import { createViewerServer } from "./server.js";
+import { writeStateFile } from "./state-file.js";
+import { ViewStore } from "./store.js";
+import { launchPackage, managedCommand } from "./update-manager.js";
+import { viewerVersion } from "./version.js";
+
+const stateFile = path.resolve(
+  process.env.VIEWER_STATE_FILE ??
+    path.join(
+      process.env.SCOUTMESH_VIEWER_HOME ??
+        path.join(homedir(), ".scoutmesh", "workspaces"),
+      "state.json"
+    )
+);
+const runtimeFile = `${stateFile}.runtime.json`;
+const lockFile = `${stateFile}.lock`;
+const logFile = `${stateFile}.log`;
+                   
+              
+                
+              
+                   
+ 
+
+function runtime()                      {
+  if (!existsSync(runtimeFile)) {
+    return undefined;
+  }
+  const value          = JSON.parse(readFileSync(runtimeFile, "utf-8"));
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("pid" in value) ||
+    !("token" in value) ||
+    !("url" in value) ||
+    !Number.isSafeInteger(value.pid) ||
+    typeof value.pid !== "number" ||
+    value.pid < 1 ||
+    typeof value.token !== "string" ||
+    !/^[a-f0-9]{64}$/u.test(value.token) ||
+    typeof value.url !== "string" ||
+    !/^http:\/\/127\.0\.0\.1:\d+$/u.test(value.url)
+  ) {
+    throw new Error(
+      `Invalid runtime file: ${runtimeFile}. Stop the viewer before repairing it.`
+    );
+  }
+  return { pid: value.pid, token: value.token, url: value.url };
+}
+
+async function call(
+  info         ,
+  route        ,
+  method = "GET",
+  body         
+) {
+  return await fetch(`${info.url}${route}`, {
+    ...(body === undefined ? {} : { body }),
+    headers: {
+      Authorization: `Bearer ${info.token}`,
+      "Content-Type": "application/json",
+    },
+    method,
+    redirect: "error",
+    signal: AbortSignal.timeout(3000),
+  });
+}
+
+async function running()                               {
+  const info = runtime();
+  if (!info) {
+    return undefined;
+  }
+  try {
+    const response = await call(info, "/api/health");
+    const health          = await response.json();
+    if (
+      response.ok &&
+      health &&
+      typeof health === "object" &&
+      "service" in health &&
+      "pid" in health &&
+      health.service === "scoutmesh-viewer" &&
+      health.pid === info.pid
+    ) {
+      return {
+        ...info,
+        version:
+          "version" in health && typeof health.version === "string"
+            ? health.version
+            : "unknown",
+      };
+    }
+  } catch {
+    /* Check process ownership before treating an unreachable server as stopped. */
+  }
+  if (alive(info.pid)) {
+    throw new Error(
+      `Viewer process ${info.pid} exists, but its authenticated endpoint at ${info.url} could not be reached or verified. Localhost access may require agent permission. Retry this CLI with approved local access; do not start a second server or read credential files manually.`
+    );
+  }
+  return undefined;
+}
+
+function alive(pid        ) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !(
+      error instanceof Error &&
+      "code" in error &&
+      error.code === "ESRCH"
+    );
+  }
+}
+
+function acquireLock() {
+  mkdirSync(path.dirname(stateFile), { mode: 0o700, recursive: true });
+  const claim = () => {
+    const descriptor = openSync(lockFile, "wx", 0o600);
+    try {
+      writeFileSync(descriptor, String(process.pid));
+    } finally {
+      closeSync(descriptor);
+    }
+  };
+  try {
+    claim();
+    return;
+  } catch (error) {
+    if (
+      !(error instanceof Error) ||
+      !("code" in error) ||
+      error.code !== "EEXIST"
+    ) {
+      throw error;
+    }
+  }
+  // Serialize stale-lock recovery so simultaneous starts cannot remove a new owner.
+  const recoveryFile = `${lockFile}.recovery`;
+  const recovery = openSync(recoveryFile, "wx", 0o600);
+  try {
+    if (existsSync(lockFile)) {
+      const owner = Number(readFileSync(lockFile, "utf-8"));
+      if (!Number.isSafeInteger(owner) || owner < 1 || alive(owner)) {
+        throw new Error(
+          `Another viewer owns ${lockFile}. Use status or stop; do not start a second writer.`
+        );
+      }
+      rmSync(lockFile);
+    }
+    claim();
+  } finally {
+    closeSync(recovery);
+    rmSync(recoveryFile, { force: true });
+  }
+}
+
+function shutdown() {
+  process.exit(0);
+}
+
+async function serve() {
+  const port = Number(process.env.VIEWER_PORT ?? 4317);
+  if (!Number.isInteger(port) || (port !== 0 && port < 1024) || port > 65_535) {
+    throw new Error(
+      "VIEWER_PORT must be 0 (automatic) or an integer between 1024 and 65535."
+    );
+  }
+  acquireLock();
+  const token = randomBytes(32).toString("hex");
+  const clean = () => {
+    // Only this lock owner removes its runtime metadata.
+    if (
+      existsSync(lockFile) &&
+      readFileSync(lockFile, "utf-8") === String(process.pid)
+    ) {
+      rmSync(runtimeFile, { force: true });
+      rmSync(lockFile, { force: true });
+    }
+  };
+  process.once("exit", clean);
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+  const store = new ViewStore(stateFile);
+  const server = createViewerServer(openExternalBrowser, store, {
+    shutdown,
+    token,
+  });
+  try {
+    server.listen(port, "127.0.0.1");
+    await once(server, "listening");
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Viewer did not bind a local TCP port.");
+    }
+    writeStateFile(runtimeFile, {
+      pid: process.pid,
+      token,
+      url: `http://127.0.0.1:${address.port}`,
+    });
+  } catch (error) {
+    if (server.listening) {
+      server.closeAllConnections();
+      server.close();
+    }
+    throw error;
+  }
+}
+
+function printStatus(info          , reused = false) {
+  console.info(
+    JSON.stringify(
+      info
+        ? {
+            pid: info.pid,
+            reused,
+            stateFile,
+            status: "running",
+            url: info.url,
+            version: info.version,
+          }
+        : { stateFile, status: "stopped", version: viewerVersion }
+    )
+  );
+}
+
+async function start() {
+  const existing = await running();
+  if (existing) {
+    if (existing.version !== viewerVersion) {
+      throw new Error(
+        `Viewer ${existing.version} is already running; this CLI is ${viewerVersion}. Use the managed launcher to upgrade, or stop the previous viewer before starting this version.`
+      );
+    }
+    printStatus(existing, true);
+    return;
+  }
+  mkdirSync(path.dirname(stateFile), { mode: 0o700, recursive: true });
+  const log = openSync(logFile, "a", 0o600);
+  const child = spawn(process.execPath, [import.meta.filename, "serve"], {
+    detached: true,
+    env: { ...process.env, VIEWER_STATE_FILE: stateFile },
+    stdio: ["ignore", log, log],
+    windowsHide: true,
+  });
+  closeSync(log);
+  let spawnError                   ;
+  child.once("error", (error) => {
+    spawnError = error;
+  });
+  child.unref();
+  const info = await waitForStart(() => spawnError);
+  printStatus(info, info.pid !== child.pid);
+}
+
+async function waitForStart(
+  spawnError                         ,
+  remaining = 60
+)                   {
+  const error = spawnError();
+  if (error) {
+    throw error;
+  }
+  const info = await running();
+  if (info) {
+    return info;
+  }
+  if (remaining === 0) {
+    throw new Error(
+      `Viewer did not start. Check ${logFile}. Port ${process.env.VIEWER_PORT ?? 4317} may be in use; set VIEWER_PORT to a free port. Saved state was not cleared.`
+    );
+  }
+  await delay(100);
+  return await waitForStart(spawnError, remaining - 1);
+}
+
+async function waitForStop(remaining = 50)                {
+  if (!existsSync(lockFile)) {
+    return;
+  }
+  if (remaining === 0) {
+    throw new Error("Viewer is still stopping. Check status.");
+  }
+  await delay(100);
+  await waitForStop(remaining - 1);
+}
+
+async function stop(info                     ) {
+  if (info) {
+    const response = await call(info, "/api/shutdown", "POST");
+    if (!response.ok) {
+      throw new Error(`Stop failed: HTTP ${response.status}`);
+    }
+    await waitForStop();
+  }
+  printStatus();
+}
+
+async function sendRequest(
+  info         ,
+  method         ,
+  route         ,
+  bodyFile         
+) {
+  if (
+    !method ||
+    !["GET", "POST", "PATCH", "PUT", "DELETE"].includes(method) ||
+    !route ||
+    !/^\/api\/views(?:\/[\w-]+(?:\/state)?)?$/u.test(route)
+  ) {
+    throw new Error(
+      "Use request GET|POST|PATCH|PUT|DELETE /api/views[/id[/state]] [body.json]."
+    );
+  }
+  const body = bodyFile
+    ? readFileSync(path.resolve(bodyFile), "utf-8")
+    : undefined;
+  if (body !== undefined) {
+    JSON.parse(body);
+  }
+  const response = await call(info, route, method, body);
+  console.info(await response.text());
+  if (!response.ok) {
+    process.exitCode = 1;
+  }
+}
+
+async function main() {
+  const [command = "help", method, route, bodyFile] = process.argv.slice(2);
+  if (command === "managed") {
+    if (!method) {
+      throw new Error("Missing managed installation path.");
+    }
+    await managedCommand(path.resolve(method), process.argv.slice(4));
+    return;
+  }
+  if (command === "--version") {
+    console.info(viewerVersion);
+    return;
+  }
+  if (command === "serve") {
+    await serve();
+    return;
+  }
+  if (command === "launch") {
+    if (process.env.VIEWER_STATE_FILE) {
+      throw new Error(
+        "launch uses SCOUTMESH_VIEWER_HOME; unset VIEWER_STATE_FILE to avoid switching workspaces."
+      );
+    }
+    console.info(
+      JSON.stringify(
+        await launchPackage(
+          path.resolve(import.meta.dirname, ".."),
+          path.dirname(stateFile)
+        )
+      )
+    );
+    return;
+  }
+  if (command === "start") {
+    await start();
+    return;
+  }
+  if (command === "help" || command === "--help") {
+    console.info(
+      "scoutmesh-viewer launch | start | status | stop | token | skill | request METHOD /api/path [body.json]\nRequires Node.js 24+. Settings: SCOUTMESH_VIEWER_HOME, VIEWER_STATE_FILE, VIEWER_PORT.\nlaunch installs/upgrades a durable npm workspace with backup/rollback; start only reuses the same version. token is a local credential: never share it in chat or URLs."
+    );
+    return;
+  }
+  if (command === "skill") {
+    console.info(
+      readFileSync(
+        new URL("../skills/local-candidate-viewer/SKILL.md", import.meta.url),
+        "utf-8"
+      )
+    );
+    return;
+  }
+  const info = await running();
+  if (command === "status") {
+    printStatus(info);
+    return;
+  }
+  if (command === "stop") {
+    await stop(info);
+    return;
+  }
+  if (!info) {
+    throw new Error("Viewer is not running. Run scoutmesh-viewer start first.");
+  }
+  if (command === "token") {
+    console.info(info.token);
+    return;
+  }
+  if (command === "request") {
+    await sendRequest(info, method, route, bodyFile);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}. Run scoutmesh-viewer --help.`);
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error(
+    error instanceof Error ? error.message : "Viewer command failed."
+  );
+  process.exitCode = 1;
+}

package/dist/external-browser.js

@@ -0,0 +1,62 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { InputError } from "./input-error.js";
+
+const execute = promisify(execFile);
+
+export function externalUrl(value         )         {
+  if (typeof value !== "string" || value.length > 8192) {
+    throw new InputError("Provide an HTTP or HTTPS link.");
+  }
+  let url     ;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new InputError("Provide a valid HTTP or HTTPS link.");
+  }
+  if (
+    !["https:", "http:"].includes(url.protocol) ||
+    url.username ||
+    url.password
+  ) {
+    throw new InputError(
+      "Only HTTP and HTTPS links without credentials can be opened."
+    );
+  }
+  return url.href;
+}
+
+export async function openExternalBrowser(url        )                {
+  const destination = externalUrl(url);
+  if (!["darwin", "win32"].includes(process.platform)) {
+    throw new InputError(
+      "External browser opening requires macOS or Windows.",
+      501
+    );
+  }
+  try {
+    // Pass the URL as one argument. Never interpret candidate data as shell code.
+    if (process.platform === "darwin") {
+      await execute("/usr/bin/open", ["--", destination], { timeout: 10_000 });
+    } else {
+      const command = Buffer.from(
+        "$ErrorActionPreference = 'Stop'; Start-Process -FilePath $env:SCOUTMESH_EXTERNAL_URL",
+        "utf16le"
+      ).toString("base64");
+      await execute(
+        "powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-EncodedCommand", command],
+        {
+          env: { ...process.env, SCOUTMESH_EXTERNAL_URL: destination },
+          timeout: 10_000,
+        }
+      );
+    }
+  } catch {
+    throw new InputError(
+      "Could not open your default browser. Try the link again.",
+      502
+    );
+  }
+}

package/dist/input-error.js

@@ -0,0 +1,8 @@
+export class InputError extends Error {
+           name = "InputError";
+  status        ;
+  constructor(message        , status = 400) {
+    super(message);
+    this.status = status;
+  }
+}

package/dist/launcher.js

@@ -0,0 +1,39 @@
+// Stable entry point: read the active package on every invocation.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const root = import.meta.dirname;
+const config          = JSON.parse(
+  readFileSync(path.join(root, "launcher.json"), "utf-8").replace(
+    /^\uFEFF/u,
+    ""
+  )
+);
+if (
+  !config ||
+  typeof config !== "object" ||
+  !("cli" in config) ||
+  typeof config.cli !== "string" ||
+  !("node" in config) ||
+  typeof config.node !== "string"
+) {
+  throw new Error(
+    "Invalid launcher configuration. Rerun the official bootstrap."
+  );
+}
+const child = spawn(
+  config.node,
+  [config.cli, "managed", root, ...process.argv.slice(2)],
+  {
+    stdio: "inherit",
+    windowsHide: true,
+  }
+);
+child.once("error", (error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+child.once("exit", (code) => {
+  process.exitCode = code ?? 1;
+});