recallx 1.0.2 → 1.0.5

package/README.md

@@ -35,13 +35,14 @@ RecallX is documented around three public ways to use it:
 2. npm package `recallx` for the full local runtime
 3. npm package `recallx-headless` for the headless runtime
 
+RecallX does not currently ship separate OS-native installers or package formats such as `.dmg`, `.msi`, `.deb`, or `AppImage`.
+
 ## 1. Git Public Repo
 
 Use the public repo when you want the full source-run surface:
 
 - local API under `/api/v1`
 - source-run renderer workflow through `npm run dev`
-- source-run desktop workflow through `npm run dev:desktop`
 - stdio MCP bridge through `npm run mcp`
 - runtime workspace create/open switching without restarting the service
 
@@ -52,12 +53,6 @@ npm install
 npm run dev
 ```
 
-Desktop runtime from source:
-
-```bash
-npm run dev:desktop
-```
-
 MCP from source:
 
 ```bash
@@ -74,11 +69,25 @@ npm start
 Checks:
 
 ```bash
+npm run branch:check
+npm run version:check
 npm run check
 npm test
 npm run build
 ```
 
+Start unrelated work in a separate branch/worktree instead of stacking it on the current checkout:
+
+```bash
+npm run branch:new -- fix-short-name
+```
+
+When you are preparing a release, bump from the highest known version instead of whatever the current branch happens to say:
+
+```bash
+npm run version:bump -- patch
+```
+
 If you want an installable runtime instead of source-run workflows, use one of the npm distribution paths below.
 
 ## 2. npm Full Runtime (`recallx`)
@@ -94,6 +103,7 @@ In another shell:
 
 ```bash
 recallx health
+recallx update
 recallx mcp install
 recallx-mcp --help
 ```
@@ -106,10 +116,6 @@ The full npm package includes:
 - `recallx serve` and subcommands
 - `recallx-mcp`
 
-The full npm package does not include:
-
-- desktop release artifacts
-
 `recallx mcp install` writes a stable launcher to `~/.recallx/bin/recallx-mcp`, which is the recommended command path for Codex and other editor MCP configs.
 
 If the API is running in bearer mode, set `RECALLX_API_TOKEN` in the MCP client environment. The launcher does not write tokens to disk.
@@ -128,6 +134,15 @@ recallx serve --workspace-root /Users/name/Documents/RecallX
 recallx serve --api-token secret-token
 ```
 
+To update an npm-installed full runtime:
+
+```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.
+
 ## 3. npm Headless Runtime (`recallx-headless`)
 
 Use the headless npm package when you want the local API, CLI, and MCP entrypoint without shipping the renderer bundle:
@@ -141,6 +156,7 @@ In another shell:
 
 ```bash
 recallx health
+recallx update
 recallx-mcp --help
 ```
 
@@ -154,10 +170,16 @@ The headless npm package includes:
 The headless npm package does not include:
 
 - renderer pages
-- desktop release artifacts
 
 At `/`, the headless runtime returns a small runtime notice instead of the renderer.
 
+To update an npm-installed headless runtime:
+
+```bash
+recallx update
+recallx update --apply
+```
+
 Node requirements:
 
 - npm packages: Node 22.13+

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.5";