feat: add update command with daily auto-update (USE-24) (#41)

* Initial plan

* feat: add update command with daily auto-update (USE-24)

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

* feat: allow disabling auto-update via config env.USE_AGENTLY_AUTO_UPDATE

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

* refactor: use Zod for state/config schemas; log auto-update errors

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

* chore: plan simplification of update.ts and state relocation

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

* refactor: simplify update.ts — inline constants, move state, remove isNewerVersion

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

* update

* clean up

* fix testing problem

* fix

* clean up skill

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

Author: Copilot

bun.lock

@@ -29,7 +29,8 @@
     "@x402/fetch": "^2.4.0",
     "commander": "^14.0.3",
     "viem": "^2.46.3",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "^4"
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",

packages/use-agently/package.json

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
 import { cli } from "./cli";
+import { checkAutoUpdate } from "./commands/update.js";
 
-cli.parse();
+await cli.parseAsync();
+await checkAutoUpdate();

packages/use-agently/src/bin.ts

@@ -1,30 +1,37 @@
 import { Command } from "commander";
-import { initCommand } from "./commands/init.js";
-import { whoamiCommand } from "./commands/whoami.js";
-import { balanceCommand } from "./commands/balance.js";
-import { agentsCommand } from "./commands/agents.js";
-import { a2aCommand, a2aCardCommand } from "./commands/a2a.js";
-import { doctorCommand } from "./commands/doctor.js";
+import { initCommand } from "./commands/init";
+import { whoamiCommand } from "./commands/whoami";
+import { balanceCommand } from "./commands/balance";
+import { agentsCommand } from "./commands/agents";
+import { a2aCommand, a2aCardCommand } from "./commands/a2a";
+import { doctorCommand } from "./commands/doctor";
+import { updateCommand } from "./commands/update";
 
 export const cli = new Command();
 
 cli
   .name("use-agently")
-  .description("use-agently CLI")
+  .description(
+    "Agently is the way AI coordinate and transact. The routing and settlement layer for your agent economy.",
+  )
   .version("0.0.0")
   .option("-o, --output <format>", "Output format (text, json)", "text")
-  .addHelpCommand("help", "Print available commands")
-  .action(() => cli.outputHelp());
+  .action(() => {
+    cli.outputHelp();
+  });
 
-// Lifecycle & Health
-cli.addCommand(initCommand.helpGroup("Lifecycle & Health"));
-cli.addCommand(doctorCommand.helpGroup("Lifecycle & Health"));
-cli.addCommand(whoamiCommand.helpGroup("Lifecycle & Health"));
-cli.addCommand(balanceCommand.helpGroup("Lifecycle & Health"));
+// Diagnostics
+cli.addCommand(doctorCommand.helpGroup("Diagnostics"));
+cli.addCommand(whoamiCommand.helpGroup("Diagnostics"));
+cli.addCommand(balanceCommand.helpGroup("Diagnostics"));
 
 // Discovery
 cli.addCommand(agentsCommand.helpGroup("Discovery"));
 
 // Protocols
 cli.addCommand(a2aCommand.helpGroup("Protocols"));
 cli.addCommand(a2aCardCommand.helpGroup("Protocols"));
+
+// Lifecycle
+cli.addCommand(initCommand.helpGroup("Lifecycle"));
+cli.addCommand(updateCommand.helpGroup("Lifecycle"));

packages/use-agently/src/cli.ts

@@ -18,16 +18,16 @@ describe("help command", () => {
     exitSpy.mockRestore();
   });
 
-  test("use-agently help prints available commands", async () => {
+  test("use-agently --help prints available commands", async () => {
     try {
-      await cli.parseAsync(["test", "use-agently", "help"]);
+      await cli.parseAsync(["test", "use-agently", "--help"]);
     } catch {
-      // expected: help calls process.exit(0)
+      // expected: --help calls process.exit(0)
     }
 
     const output = writeSpy.mock.calls.map((c) => c[0]).join("");
     expect(output).toContain("use-agently");
-    expect(output).toContain("Commands:");
+    expect(output).toContain("Diagnostics");
     expect(exitSpy).toHaveBeenCalledWith(0);
   });
 
@@ -36,7 +36,7 @@ describe("help command", () => {
 
     const output = writeSpy.mock.calls.map((c) => c[0]).join("");
     expect(output).toContain("use-agently");
-    expect(output).toContain("Commands:");
+    expect(output).toContain("Diagnostics");
     expect(exitSpy).not.toHaveBeenCalled();
   });
 });

packages/use-agently/src/commands/help.test.ts

@@ -0,0 +1,185 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+import { captureOutput } from "../testing";
+
+const mockReadFile = mock(async (_path: string, _encoding: unknown) => JSON.stringify({}));
+const mockWriteFile = mock(async (_path: string, _data: string, _encoding?: unknown) => {});
+const mockMkdir = mock(async () => {});
+const mockLoadConfig = mock(async () => undefined as unknown);
+
+mock.module("node:fs/promises", () => ({
+  readFile: mockReadFile,
+  writeFile: mockWriteFile,
+  mkdir: mockMkdir,
+  rename: mock(async () => {}),
+}));
+
+mock.module("../config", () => ({
+  loadConfig: mockLoadConfig,
+  saveConfig: async () => {},
+  backupConfig: async () => "",
+  getConfigOrThrow: async () => {
+    throw new Error("No wallet configured.");
+  },
+}));
+
+mock.module("node:child_process", () => ({
+  execSync: mock(() => {}),
+}));
+
+const { cli } = await import("../cli");
+const { CURRENT_VERSION, checkAutoUpdate } = await import("./update");
+const updateModule = await import("./update");
+
+describe("update command", () => {
+  const out = captureOutput();
+  let fetchSpy: ReturnType<typeof spyOn>;
+  let exitSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    mockReadFile.mockClear();
+    mockWriteFile.mockClear();
+    mockMkdir.mockClear();
+    mockReadFile.mockImplementation(async () => JSON.stringify({}));
+    fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "9.9.9" }),
+    } as Response);
+    exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  test("text output - update available", async () => {
+    await cli.parseAsync(["test", "use-agently", "update"]);
+
+    expect(out.yaml).toEqual({
+      current: CURRENT_VERSION,
+      latest: "9.9.9",
+      updated: true,
+    });
+  });
+
+  test("json output - update available", async () => {
+    await cli.parseAsync(["test", "use-agently", "-o", "json", "update"]);
+
+    expect(out.json).toEqual({
+      current: CURRENT_VERSION,
+      latest: "9.9.9",
+      updated: true,
+    });
+  });
+
+  test("no update when already on latest", async () => {
+    fetchSpy.mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: CURRENT_VERSION }),
+    } as Response);
+
+    await cli.parseAsync(["test", "use-agently", "-o", "json", "update"]);
+
+    expect(out.json).toEqual({
+      current: CURRENT_VERSION,
+      latest: CURRENT_VERSION,
+      updated: false,
+    });
+  });
+
+  test("saves lastUpdateCheck after update", async () => {
+    await cli.parseAsync(["test", "use-agently", "update"]);
+
+    expect(mockWriteFile).toHaveBeenCalledTimes(1);
+    const written = JSON.parse(mockWriteFile.mock.calls[0][1] as string);
+    expect(typeof written.lastUpdateCheck).toBe("string");
+  });
+
+  test("exits with 1 on registry error", async () => {
+    fetchSpy.mockResolvedValue({ ok: false, status: 503 } as Response);
+
+    try {
+      await cli.parseAsync(["test", "use-agently", "update"]);
+    } catch {
+      // expected: process.exit throws
+    }
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe("checkAutoUpdate", () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+  let devVersionSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    mockReadFile.mockClear();
+    mockWriteFile.mockClear();
+    mockMkdir.mockClear();
+    mockLoadConfig.mockImplementation(async () => undefined);
+    mockReadFile.mockImplementation(async () => {
+      throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+    });
+    fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "9.9.9" }),
+    } as Response);
+    devVersionSpy = spyOn(updateModule, "isDevVersion").mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+    devVersionSpy.mockRestore();
+  });
+
+  test("skips update check when checked within 24h", async () => {
+    mockReadFile.mockResolvedValue(JSON.stringify({ lastUpdateCheck: new Date().toISOString() }));
+
+    await checkAutoUpdate();
+
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  test("runs update check when last check was >24h ago", async () => {
+    const yesterday = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString();
+    mockReadFile.mockResolvedValue(JSON.stringify({ lastUpdateCheck: yesterday }));
+
+    await checkAutoUpdate();
+
+    expect(mockWriteFile).toHaveBeenCalledTimes(1);
+  });
+
+  test("runs update check when no prior check recorded", async () => {
+    await checkAutoUpdate();
+
+    expect(mockWriteFile).toHaveBeenCalledTimes(1);
+  });
+
+  test("skips when USE_AGENTLY_AUTO_UPDATE is 0 in config", async () => {
+    mockLoadConfig.mockImplementation(async () => ({ env: { USE_AGENTLY_AUTO_UPDATE: 0 } }));
+
+    await checkAutoUpdate();
+
+    expect(mockWriteFile).not.toHaveBeenCalled();
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  test("runs when USE_AGENTLY_AUTO_UPDATE is 1 in config", async () => {
+    mockLoadConfig.mockImplementation(async () => ({ env: { USE_AGENTLY_AUTO_UPDATE: 1 } }));
+
+    await checkAutoUpdate();
+
+    expect(mockWriteFile).toHaveBeenCalledTimes(1);
+  });
+
+  test("logs warning but does not throw on errors", async () => {
+    fetchSpy.mockResolvedValue({ ok: false, status: 500 } as Response);
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+
+    await expect(checkAutoUpdate()).resolves.toBeUndefined();
+    expect(warnSpy).toHaveBeenCalledWith("Auto-update failed:", expect.any(String));
+    warnSpy.mockRestore();
+  });
+});

packages/use-agently/src/commands/update.test.ts

@@ -0,0 +1,100 @@
+import { Command } from "commander";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { output } from "../output.js";
+import { loadConfig } from "../config.js";
+import pkg from "../../package.json" with { type: "json" };
+
+const UpdateStateSchema = z.object({
+  lastUpdateCheck: z.string().optional(),
+});
+
+type UpdateState = z.infer<typeof UpdateStateSchema>;
+
+function getUpdateStatePath(): string {
+  return join(homedir(), ".use-agently", "update-state.json");
+}
+
+async function loadUpdateState(): Promise<UpdateState> {
+  try {
+    const contents = await readFile(getUpdateStatePath(), "utf8");
+    const result = UpdateStateSchema.safeParse(JSON.parse(contents));
+    return result.success ? result.data : {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveUpdateState(state: UpdateState): Promise<void> {
+  await mkdir(join(homedir(), ".use-agently"), { recursive: true });
+  await writeFile(getUpdateStatePath(), JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+export const CURRENT_VERSION: string = pkg.version;
+
+export function isDevVersion(): boolean {
+  return CURRENT_VERSION === "0.0.0";
+}
+
+export async function getLatestVersion(): Promise<string> {
+  const res = await fetch("https://registry.npmjs.org/use-agently/latest");
+  if (!res.ok) throw new Error(`Failed to check npm registry: ${res.status}`);
+  const data = (await res.json()) as { version: string };
+  return data.version;
+}
+
+export async function runUpdate(version: string): Promise<void> {
+  if (!/^\d+\.\d+\.\d+$/.test(version)) {
+    throw new Error(`Invalid version format received from registry: ${version}`);
+  }
+  execSync(`npm install -g use-agently@${version}`, { stdio: "pipe" });
+}
+
+export async function checkAndUpdate(): Promise<{ current: string; latest: string; updated: boolean }> {
+  const current = CURRENT_VERSION;
+  const latest = await getLatestVersion();
+  const needsUpdate = current !== latest;
+
+  if (needsUpdate) {
+    await runUpdate(latest);
+  }
+
+  const state = await loadUpdateState();
+  await saveUpdateState({ ...state, lastUpdateCheck: new Date().toISOString() });
+
+  return { current, latest, updated: needsUpdate };
+}
+
+export async function checkAutoUpdate(): Promise<void> {
+  try {
+    if (isDevVersion()) return;
+
+    const config = await loadConfig();
+    if ((config?.env?.USE_AGENTLY_AUTO_UPDATE ?? 1) === 0) return;
+
+    const state = await loadUpdateState();
+    const lastCheck = state.lastUpdateCheck ? new Date(state.lastUpdateCheck).getTime() : 0;
+    const hoursSinceLastCheck = (Date.now() - lastCheck) / (1000 * 60 * 60);
+
+    if (hoursSinceLastCheck < 24) return;
+
+    await checkAndUpdate();
+  } catch (err) {
+    console.warn("Auto-update failed:", err instanceof Error ? err.message : String(err));
+  }
+}
+
+export const updateCommand = new Command("update")
+  .description("Update use-agently to the latest version")
+  .action(async (_options: Record<string, never>, command: Command) => {
+    try {
+      const result = await checkAndUpdate();
+      output(command, result);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });