@moor-sh/cli 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,75 @@
+# @moor-sh/cli
+
+Command-line interface for [moor](https://github.com/caiopizzol/moor) - manage your moor server's projects, logs, env vars, and container lifecycle from a terminal. Ships a `moor` binary.
+
+Requires [Bun](https://bun.sh) on the machine running the CLI.
+
+## Install
+
+**One-shot** (no install):
+
+```bash
+bunx @moor-sh/cli status
+```
+
+**Global install** (puts `moor` on PATH):
+
+```bash
+bun add -g @moor-sh/cli
+moor status
+```
+
+Don't use `bunx moor` (without the scope) - `moor` on npm is an unrelated package.
+
+## Configure
+
+```bash
+export MOOR_URL=https://moor.example.com   # or http://127.0.0.1:8080 via SSH tunnel
+export MOOR_API_KEY=your-api-key
+```
+
+`MOOR_API_KEY` grants admin-equivalent control of the moor host. See the [self-hosting guide](https://github.com/caiopizzol/moor/blob/main/docs/self-hosting.md#api-keys) for how to generate and rotate it.
+
+For a remote moor with private admin (the default), open an SSH tunnel from your laptop before running CLI commands:
+
+```bash
+ssh -L 8080:127.0.0.1:3000 your-server
+export MOOR_URL=http://127.0.0.1:8080
+```
+
+## Commands
+
+```
+moor status                          # list all projects
+moor logs <project> [-f] [-n 100]    # view container logs
+moor rebuild <project>               # rebuild from source
+moor restart <project>               # stop + start
+moor exec <project> <command>        # run a command in the container
+moor env list <project>              # list environment variables
+moor env set <project> KEY=VALUE     # set environment variables and restart
+moor stats                           # server resource usage
+moor mcp config --client <name>      # generate MCP client config snippet
+```
+
+## `moor mcp config`
+
+Generates a ready-to-paste config snippet for an MCP-compatible AI client. Removes the "open a doc, copy a JSON block, fill in the blanks" step from MCP setup.
+
+```bash
+moor mcp config --client claude        # or --client claude-code (alias)
+moor mcp config --client codex
+```
+
+Output is JSON for `claude` / `claude-code` and TOML for `codex`. Prints to stdout - redirect or paste into `~/.claude.json` or `~/.codex/config.toml`. Optional flags: `--url <url>` (default `http://127.0.0.1:8080`), `--api-key <key>` (else read from `MOOR_API_KEY` env, then cwd `.env`, then a placeholder).
+
+See [`@moor-sh/mcp`](https://www.npmjs.com/package/@moor-sh/mcp) for the MCP server itself.
+
+## Links
+
+- [moor repo](https://github.com/caiopizzol/moor) - main project, install instructions
+- [Self-hosting guide](https://github.com/caiopizzol/moor/blob/main/docs/self-hosting.md) - first boot, API keys, admin domain, port model
+- [`@moor-sh/mcp`](https://www.npmjs.com/package/@moor-sh/mcp) - MCP server for AI agent integration
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moor-sh/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Command-line interface for moor - manage your moor server's projects, logs, env vars, and container lifecycle.",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "https://github.com/caiopizzol/moor.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/caiopizzol/moor#cli",
+  "homepage": "https://github.com/caiopizzol/moor/tree/main/packages/cli",
   "bugs": "https://github.com/caiopizzol/moor/issues",
   "keywords": [
     "moor",

package/src/commands/history.test.ts

@@ -0,0 +1,37 @@
+// #133: regression test for the history arg parser. The original took the
+// first non-flag token as the project, so `--hours 1 fipe-pg` silently used
+// the hours value ("1") as the project. Parsing must be order-independent.
+
+import { describe, expect, test } from "bun:test";
+import { parseHistoryArgs } from "./history";
+
+describe("parseHistoryArgs", () => {
+  test("project then flag", () => {
+    expect(parseHistoryArgs(["fipe-pg", "--hours", "1"])).toEqual({ project: "fipe-pg", hours: 1 });
+  });
+
+  test("flag then project (regression: was mis-parsed as project '1')", () => {
+    expect(parseHistoryArgs(["--hours", "1", "fipe-pg"])).toEqual({ project: "fipe-pg", hours: 1 });
+  });
+
+  test("--hours=N form", () => {
+    expect(parseHistoryArgs(["--hours=6", "fipe-pg"])).toEqual({ project: "fipe-pg", hours: 6 });
+  });
+
+  test("default hours is 24 when omitted", () => {
+    expect(parseHistoryArgs(["fipe-pg"])).toEqual({ project: "fipe-pg", hours: 24 });
+  });
+
+  test("missing project → error, no project", () => {
+    const r = parseHistoryArgs(["--hours", "1"]);
+    expect(r.project).toBeUndefined();
+    expect(r.error).toBeTruthy();
+  });
+
+  test("invalid hours → error", () => {
+    expect(parseHistoryArgs(["fipe-pg", "--hours", "0"]).error).toBeTruthy();
+    expect(parseHistoryArgs(["fipe-pg", "--hours", "-3"]).error).toBeTruthy();
+    expect(parseHistoryArgs(["fipe-pg", "--hours", "abc"]).error).toBeTruthy();
+    expect(parseHistoryArgs(["fipe-pg", "--hours"]).error).toBeTruthy(); // no value
+  });
+});

package/src/commands/history.ts

@@ -0,0 +1,117 @@
+import { apiGet, resolveProject } from "../client";
+
+type HistoryResponse = {
+  from_ms: number;
+  to_ms: number;
+  events: Array<{ occurred_at_ms: number; source: string; action: string }>;
+  summary: {
+    sample_count: number;
+    running_sample_count: number;
+    cpu_percent_avg: number | null;
+    cpu_percent_max: number | null;
+    mem_bytes_max: number | null;
+    net_rx_bytes_total: number;
+    net_tx_bytes_total: number;
+    event_counts: Record<string, number>;
+    has_gap: boolean;
+  };
+};
+
+function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+  const val = bytes / 1024 ** i;
+  return `${val.toFixed(val < 10 ? 1 : 0)} ${units[i]}`;
+}
+
+// Parse `<project> [--hours N]` in any order. Critically, `--hours`'s value is
+// consumed as the flag's argument, not mistaken for the project — so both
+// `history p --hours 1` and `history --hours 1 p` resolve `p` (the old
+// first-non-flag-token approach silently took the hours value as the project).
+// Also accepts `--hours=N`. Pure + exported for tests.
+export function parseHistoryArgs(args: string[]): {
+  project?: string;
+  hours: number;
+  error?: string;
+} {
+  let project: string | undefined;
+  let hours = 24;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--hours") {
+      const n = Number(args[++i]); // consume the next token as the value
+      if (!Number.isFinite(n) || n <= 0)
+        return { hours, error: "--hours must be a positive number" };
+      hours = n;
+    } else if (a.startsWith("--hours=")) {
+      const n = Number(a.slice("--hours=".length));
+      if (!Number.isFinite(n) || n <= 0)
+        return { hours, error: "--hours must be a positive number" };
+      hours = n;
+    } else if (!a.startsWith("-") && project === undefined) {
+      project = a;
+    }
+    // other flags / extra positionals are ignored
+  }
+  if (!project) return { hours, error: "missing project" };
+  return { project, hours };
+}
+
+// Stored resource history + lifecycle events for one project (not live — use
+// `moor stats` for the host snapshot). Mirrors the moor_project_history MCP
+// tool: a window summary plus recent events.
+export async function historyCommand(args: string[]) {
+  const parsed = parseHistoryArgs(args);
+  if (parsed.error || !parsed.project) {
+    console.error(
+      parsed.error && parsed.error !== "missing project"
+        ? parsed.error
+        : "Usage: moor history <project> [--hours N]",
+    );
+    process.exit(1);
+  }
+
+  const project = await resolveProject(parsed.project);
+  const to = Date.now();
+  const from = to - parsed.hours * 3_600_000;
+  const res = await apiGet(`/api/projects/${project.id}/stats/history?from=${from}&to=${to}`);
+  if (!res.ok) {
+    console.error(`Failed to get history: ${res.status} ${await res.text()}`);
+    process.exit(1);
+  }
+
+  const h = (await res.json()) as HistoryResponse;
+  const s = h.summary;
+  const windowH = Math.round(((h.to_ms - h.from_ms) / 3_600_000) * 10) / 10;
+
+  console.log(`${project.name} — history over ~${windowH}h`);
+  if (s.has_gap) {
+    console.log("  \x1b[33m⚠ event gap recorded: events may be incomplete\x1b[0m");
+  }
+  console.log(`  Samples:   ${s.sample_count} total, ${s.running_sample_count} running`);
+  console.log(
+    `  CPU:       avg ${s.cpu_percent_avg ?? "n/a"}% / max ${s.cpu_percent_max ?? "n/a"}%`,
+  );
+  console.log(
+    `  Memory:    max ${s.mem_bytes_max !== null ? formatBytes(s.mem_bytes_max) : "n/a"}`,
+  );
+  console.log(
+    `  Network:   in ${formatBytes(s.net_rx_bytes_total)} / out ${formatBytes(s.net_tx_bytes_total)}`,
+  );
+  const counts = Object.entries(s.event_counts);
+  if (counts.length > 0) {
+    console.log(`  Events:    ${counts.map(([a, n]) => `${a} ${n}`).join(", ")}`);
+  }
+
+  const recent = h.events.slice(-10);
+  if (recent.length > 0) {
+    console.log("\nRecent events:");
+    for (const e of recent) {
+      console.log(`  ${new Date(e.occurred_at_ms).toISOString()}  ${e.action}  (${e.source})`);
+    }
+  }
+  if (s.sample_count === 0 && h.events.length === 0) {
+    console.log("  (no stored history in this window)");
+  }
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { envCommand } from "./commands/env";
 import { execCommand } from "./commands/exec";
+import { historyCommand } from "./commands/history";
 import { logsCommand } from "./commands/logs";
 import { mcpCommand } from "./commands/mcp";
 import { rebuildCommand } from "./commands/rebuild";
@@ -34,6 +35,7 @@ Commands:
   env list <project>              List environment variables
   env set <project> K=V [K=V ...] Set environment variables
   stats                           Show server resource usage
+  history <project> [--hours N]   Stored resource history + events (default 24h)
   mcp config --client <name>      Generate MCP client config snippet
 
 Environment:
@@ -66,6 +68,9 @@ switch (command) {
   case "stats":
     await statsCommand();
     break;
+  case "history":
+    await historyCommand(args.slice(1));
+    break;
   case "mcp":
     mcpCommand(args.slice(1));
     break;