recallx-headless 1.0.2 → 1.0.4

package/README.md

@@ -5,7 +5,7 @@
 - This package is the npm-distributed headless runtime for RecallX.
 - It provides the `recallx` and `recallx-mcp` commands.
 - It can start the local RecallX API directly through `recallx serve`.
-- It does not include the renderer or desktop release artifacts.
+- It does not include the renderer.
 
 It defers behavior to the local RecallX API contract in [`docs/api.md`](../../docs/api.md).
 
@@ -28,6 +28,7 @@ In another shell:
 
 ```bash
 recallx health
+recallx update
 recallx-mcp --help
 recallx mcp install
 ```
@@ -55,7 +56,16 @@ recallx serve --workspace-name "Personal Workspace"
 recallx serve --api-token secret-token
 ```
 
-The headless package does not ship renderer pages or desktop release artifacts. At `/`, it returns a runtime notice instead of the renderer app.
+To update an npm-installed RecallX runtime from the CLI:
+
+```bash
+recallx update
+recallx update --apply
+```
+
+`recallx update` currently supports npm global installs of `recallx` and `recallx-headless`. Source checkouts should keep using their package manager directly.
+
+The headless package does not ship renderer pages. At `/`, it returns a runtime notice instead of the renderer app.
 
 You can also print the direct MCP command or a config snippet:
 
@@ -71,6 +81,7 @@ Quick health and workspace checks:
 
 ```bash
 recallx health
+recallx update
 recallx workspace current
 recallx workspace list
 ```
@@ -106,6 +117,7 @@ recallx mcp config
 
 ```bash
 recallx health
+recallx update [--apply]
 recallx mcp config
 recallx mcp install
 recallx mcp path

package/app/cli/src/cli.js

@@ -5,7 +5,8 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { getApiBase, getAuthToken, requestJson } from "./http.js";
 import { RECALLX_VERSION } from "../../shared/version.js";
-import { renderActivitySearchResults, renderBundleMarkdown, renderGovernanceIssues, renderJson, renderNode, renderRelated, renderSearchResults, renderTelemetryErrors, renderTelemetrySummary, renderText, renderWorkspaceSearchResults, renderWorkspaces, } from "./format.js";
+import { applyCliUpdate, getCliUpdatePlan } from "./update.js";
+import { renderActivitySearchResults, renderBundleMarkdown, renderGovernanceIssues, renderJson, renderNode, renderRelated, renderSearchResults, renderTelemetryErrors, renderTelemetrySummary, renderText, renderUpdateResult, renderWorkspaceSearchResults, renderWorkspaces, } from "./format.js";
 const DEFAULT_SOURCE = {
     actorType: "human",
     actorLabel: "recallx-cli",
@@ -27,6 +28,8 @@ export async function runCli(argv) {
             return runHealth(apiBase, token, format);
         case "serve":
             return runServe(args);
+        case "update":
+            return runUpdate(format, args);
         case "mcp":
             return runMcp(apiBase, token, format, args, positionals);
         case "search":
@@ -85,6 +88,15 @@ async function runServe(args) {
     }
     await import(pathToFileURL(resolveServerEntryScript()).href);
 }
+export async function runUpdate(format, args, dependencies = {}) {
+    const plan = await (dependencies.getCliUpdatePlan ?? getCliUpdatePlan)();
+    if (parseBooleanFlag(args.apply, false)) {
+        const result = await (dependencies.applyCliUpdate ?? applyCliUpdate)(plan);
+        outputData(result, format, "update");
+        return;
+    }
+    outputData(plan, format, "update");
+}
 async function runMcp(apiBase, token, format, args, positionals) {
     const action = positionals[0] || args.action || "config";
     const launcherPath = args.path || args.launcher || DEFAULT_MCP_LAUNCHER_PATH;
@@ -582,6 +594,9 @@ function outputData(data, format, command) {
                 "",
             ].join("\n"));
             return;
+        case "update":
+            writeStdout(renderUpdateResult(payload));
+            return;
         default:
             writeStdout(renderText(payload));
     }
@@ -657,6 +672,7 @@ Usage:
   recallx serve [--workspace-name Personal] [--api-token secret]
   recallx serve [--renderer-dist /path/to/dist/renderer]
   recallx health
+  recallx update [--apply]
   recallx mcp config
   recallx mcp install [--path ~/.recallx/bin/recallx-mcp]
   recallx mcp path

package/app/cli/src/format.js

@@ -144,6 +144,36 @@ export function renderWorkspaces(data) {
     .join("\n\n")}\n`;
 }
 
+export function renderUpdateResult(data) {
+  const lines = [
+    `package: ${data?.packageName || ""}`,
+    `current: ${data?.currentVersion || ""}`,
+    `latest: ${data?.latestVersion || ""}`,
+  ];
+
+  if (data?.status === "updated") {
+    lines.push("status: updated");
+  } else if (data?.status === "up_to_date") {
+    lines.push("status: up to date");
+  } else {
+    lines.push("status: update available");
+  }
+
+  if (data?.installCommand) {
+    lines.push(`command: ${data.installCommand}`);
+  }
+
+  if (data?.status === "update_available" && data?.applied !== true) {
+    lines.push("hint: re-run with `recallx update --apply` to install the latest npm package from this shell.");
+  }
+
+  if (data?.packageRoot) {
+    lines.push(`packageRoot: ${data.packageRoot}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
 export function renderBundleMarkdown(bundle) {
   const lines = [];
   lines.push(`# ${bundle.target?.title || bundle.target?.id || "Context bundle"}`);

package/app/cli/src/update.js

@@ -0,0 +1,118 @@
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const SUPPORTED_NPM_PACKAGES = new Set(["recallx", "recallx-headless"]);
+export async function getCliUpdatePlan(options = {}) {
+    const moduleUrl = options.moduleUrl ?? import.meta.url;
+    const packageRoot = options.packageRoot ?? resolveCliPackageRoot(moduleUrl);
+    const packageJson = readPackageJson(packageRoot, options.readFileSyncFn ?? readFileSync);
+    const packageName = options.packageName ?? packageJson.name;
+    const currentVersion = options.currentVersion ?? packageJson.version;
+    const platform = options.platform ?? process.platform;
+    const npmCommand = options.npmCommand ?? resolveNpmCommand(platform);
+    const execAsync = options.execFileAsyncFn ?? execFileAsync;
+    if (!SUPPORTED_NPM_PACKAGES.has(packageName)) {
+        throw new Error("UPDATE_UNSUPPORTED: `recallx update` currently supports npm-installed `recallx` and `recallx-headless` runtimes only.");
+    }
+    const globalRoot = (await runCommand(execAsync, npmCommand, ["root", "-g"])).trim();
+    if (!globalRoot || !isPathInside(packageRoot, globalRoot)) {
+        throw new Error("UPDATE_UNSUPPORTED: `recallx update` only works for npm global installs. For source checkouts or other install methods, update the package with your package manager directly.");
+    }
+    const latestVersionRaw = await runCommand(execAsync, npmCommand, ["view", packageName, "version", "--json"]);
+    const latestVersion = normalizeVersionPayload(latestVersionRaw);
+    const installArgs = ["install", "-g", `${packageName}@latest`];
+    return {
+        packageName,
+        currentVersion,
+        latestVersion,
+        packageRoot,
+        globalRoot,
+        npmCommand,
+        installArgs,
+        installCommand: [npmCommand, ...installArgs].map(quoteShellArg).join(" "),
+        status: currentVersion === latestVersion ? "up_to_date" : "update_available",
+        applied: false,
+    };
+}
+export function applyCliUpdate(plan, options = {}) {
+    if (!plan || typeof plan !== "object") {
+        throw new Error("UPDATE_INVALID_PLAN: Missing update plan.");
+    }
+    if (plan.status === "up_to_date") {
+        return {
+            ...plan,
+            applied: false,
+        };
+    }
+    const platform = options.platform ?? process.platform;
+    const npmCommand = options.npmCommand ?? plan.npmCommand ?? resolveNpmCommand(platform);
+    const execSync = options.execFileSyncFn ?? execFileSync;
+    execSync(npmCommand, plan.installArgs ?? ["install", "-g", `${plan.packageName}@latest`], {
+        stdio: "inherit",
+    });
+    return {
+        ...plan,
+        status: "updated",
+        applied: true,
+    };
+}
+function resolveCliPackageRoot(moduleUrl) {
+    const modulePath = fileURLToPath(moduleUrl);
+    return path.resolve(path.dirname(modulePath), "../../..");
+}
+function readPackageJson(packageRoot, readFileSyncFn) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        throw new Error(`UPDATE_UNSUPPORTED: Could not find package metadata at ${packageJsonPath}.`);
+    }
+    return JSON.parse(readFileSyncFn(packageJsonPath, "utf8"));
+}
+async function runCommand(execAsync, command, args) {
+    try {
+        const result = await execAsync(command, args, { encoding: "utf8" });
+        return typeof result.stdout === "string" ? result.stdout.trim() : "";
+    }
+    catch (error) {
+        const stderr = error && typeof error === "object" && "stderr" in error && typeof error.stderr === "string"
+            ? error.stderr.trim()
+            : "";
+        const detail = stderr || (error instanceof Error ? error.message : String(error));
+        throw new Error(`UPDATE_COMMAND_FAILED: ${detail}`);
+    }
+}
+function normalizeVersionPayload(value) {
+    if (!value) {
+        throw new Error("UPDATE_LOOKUP_FAILED: npm did not return a version.");
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (Array.isArray(parsed)) {
+            const last = parsed.at(-1);
+            if (typeof last === "string" && last.trim()) {
+                return last;
+            }
+        }
+        if (typeof parsed === "string" && parsed.trim()) {
+            return parsed;
+        }
+    }
+    catch {
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    throw new Error("UPDATE_LOOKUP_FAILED: npm returned an invalid version payload.");
+}
+function isPathInside(candidatePath, parentPath) {
+    const relative = path.relative(parentPath, candidatePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function quoteShellArg(value) {
+    return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+function resolveNpmCommand(platform) {
+    return platform === "win32" ? "npm.cmd" : "npm";
+}

package/app/server/app.js

@@ -14,7 +14,6 @@ import { buildProjectGraph } from "./project-graph.js";
 import { createId, isPathWithinRoot } from "./utils.js";
 const relationTypeSet = new Set(relationTypes);
 const allowedLoopbackHostnames = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
-const isDesktopManagedApi = process.env.ELECTRON_RUN_AS_NODE === "1";
 const updateNodeRequestSchema = updateNodeSchema.extend({
     source: sourceSchema
 });
@@ -453,7 +452,7 @@ function buildServiceIndex(workspaceInfo) {
             {
                 method: "GET",
                 path: "/api/v1/observability/errors?since=24h&surface=mcp",
-                purpose: "Inspect recent telemetry errors for the API, MCP bridge, or desktop shell."
+                purpose: "Inspect recent telemetry errors for the API or MCP bridge."
             },
             {
                 method: "POST",
@@ -543,7 +542,7 @@ export function createRecallXApp(params) {
             "observability.capturePayloadShape"
         ]);
         return {
-            enabled: isDesktopManagedApi ? parseBooleanSetting(settings["observability.enabled"], false) : true,
+            enabled: true,
             workspaceRoot: currentWorkspaceRoot(),
             workspaceName: currentWorkspaceInfo().workspaceName,
             retentionDays: Math.max(1, parseNumberSetting(settings["observability.retentionDays"], 14)),
@@ -1391,7 +1390,7 @@ export function createRecallXApp(params) {
     }));
     app.get("/api/v1/observability/errors", handleAsyncRoute(async (request, response) => {
         const surface = readRequestParam(request.query.surface);
-        const normalizedSurface = surface === "api" || surface === "mcp" || surface === "desktop" ? surface : "all";
+        const normalizedSurface = surface === "api" || surface === "mcp" ? surface : "all";
         const errors = await observability.listErrors({
             since: readRequestParam(request.query.since),
             surface: normalizedSurface,

package/app/shared/version.js

@@ -1 +1 @@
-export const RECALLX_VERSION = "1.0.2";
+export const RECALLX_VERSION = "1.0.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recallx-headless",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Headless RecallX runtime with API, CLI, and MCP entrypoint.",
   "type": "module",
   "bin": {