@pyxmate/memory 1.17.18 → 1.17.19

package/dist/cli/pyx-mem.mjs

@@ -836,7 +836,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.17.18" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.17.19" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     const text = read.result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();
@@ -1540,6 +1540,147 @@ function resolveMcpMode(flags) {
   return { ok: true };
 }
 
+// src/cli/commands/overview.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { z } from "zod";
+var OVERVIEW_SCHEMA_VERSION = 1;
+var RECENT_ENTRY_LIMIT = 3;
+var MAX_TOPIC_CHARS = 160;
+var MAX_PROJECT_CHARS = 80;
+var entrySchema = z.object({
+  id: z.string().min(1),
+  metadata: z.record(z.string(), z.unknown())
+}).passthrough();
+var hostedEntriesResponseSchema = z.object({
+  memories: z.array(entrySchema),
+  total: z.number().int().nonnegative()
+}).passthrough();
+var selfHostedEntriesResponseSchema = z.object({
+  success: z.literal(true),
+  data: z.object({
+    entries: z.array(entrySchema),
+    totalCount: z.number().int().nonnegative()
+  }).passthrough()
+}).passthrough();
+var entriesResponseSchema = z.union([
+  hostedEntriesResponseSchema.transform(({ memories, total }) => ({
+    entries: memories,
+    totalCount: total
+  })),
+  selfHostedEntriesResponseSchema.transform(({ data }) => data)
+]);
+async function overviewCommand(opts = {}) {
+  const provider = opts.keychain ?? getDefaultKeychain();
+  let credentials;
+  try {
+    credentials = await provider.read();
+  } catch (error) {
+    const detail = error instanceof KeychainError ? [error.message, error.guidance].filter(Boolean).join(" ") : "The OS credential store could not be read.";
+    emit(report("error", null, null, detail));
+    return error instanceof KeychainError ? error.exit : EXIT.CRED_UNAVAILABLE;
+  }
+  if (!credentials) {
+    emit(report("signed_out", null, null, null));
+    return EXIT.NOT_LOGGED_IN;
+  }
+  if (!isHttpUrl2(credentials.endpoint)) {
+    emit(
+      report(
+        "error",
+        null,
+        "keychain",
+        "The stored pyx-memory endpoint is invalid. Run: pyx-mem login"
+      )
+    );
+    return EXIT.DOCTOR_FAIL;
+  }
+  const http = createHttpClient(credentials, opts.fetchImpl ?? fetch);
+  const response = await http.requestJson({
+    method: "GET",
+    path: "/api/memory/entries",
+    query: { status: "active", limit: RECENT_ENTRY_LIMIT },
+    idempotencyKey: `cli-overview-${randomUUID3()}`
+  });
+  if (!response.ok) {
+    const signedOut = response.status === 401;
+    emit(
+      report(
+        signedOut ? "signed_out" : "error",
+        credentials.endpoint,
+        "keychain",
+        overviewFailure(response.status)
+      )
+    );
+    return signedOut ? EXIT.NOT_LOGGED_IN : EXIT.DOCTOR_FAIL;
+  }
+  const parsed = entriesResponseSchema.safeParse(response.data);
+  if (!parsed.success) {
+    emit(
+      report(
+        "error",
+        credentials.endpoint,
+        "keychain",
+        "pyx-memory returned an invalid overview response. Run: pyx-mem doctor"
+      )
+    );
+    return EXIT.DOCTOR_FAIL;
+  }
+  emit({
+    ...report("ready", credentials.endpoint, "keychain", null),
+    totalCount: parsed.data.totalCount,
+    entries: parsed.data.entries.slice(0, RECENT_ENTRY_LIMIT).map((entry) => ({
+      id: entry.id,
+      topic: boundedLabel(entry.metadata.topic, "Untitled", MAX_TOPIC_CHARS),
+      project: boundedLabel(entry.metadata.project, "Unscoped", MAX_PROJECT_CHARS)
+    }))
+  });
+  return EXIT.OK;
+}
+function report(state, endpoint, keySource, problem) {
+  return {
+    schemaVersion: OVERVIEW_SCHEMA_VERSION,
+    state,
+    endpoint,
+    keySource,
+    totalCount: 0,
+    entries: [],
+    problem
+  };
+}
+function emit(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+function overviewFailure(status) {
+  if (status === 401) {
+    return "Stored pyx-memory credentials were rejected. Run: pyx-mem login";
+  }
+  if (status === 403) {
+    return "pyx-memory denied access (HTTP 403). Check the key scope and project access.";
+  }
+  if (status === void 0) {
+    return "Unable to reach pyx-memory. Run: pyx-mem doctor";
+  }
+  if (status >= 500) {
+    return `pyx-memory is unavailable (HTTP ${status}). Run: pyx-mem doctor`;
+  }
+  return `pyx-memory overview failed (HTTP ${status}). Run: pyx-mem doctor`;
+}
+function boundedLabel(value, fallback, maxChars) {
+  if (typeof value !== "string" || value.trim().length === 0) return fallback;
+  const normalized = value.trim();
+  const chars = [...normalized];
+  return chars.length > maxChars ? `${chars.slice(0, maxChars).join("")}\u2026` : normalized;
+}
+function isHttpUrl2(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
 // src/cli/commands/scaffold.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
 import { basename as basename2, join as join2, resolve as resolve2 } from "path";
@@ -1720,10 +1861,10 @@ function scaffoldCommand(args = {}) {
 // src/cli/commands/status.ts
 async function statusCommand(opts = {}) {
   const provider = opts.keychain ?? getDefaultKeychain();
-  let report;
+  let report2;
   try {
     const creds = await provider.read();
-    report = {
+    report2 = {
       endpoint: creds?.endpoint ?? null,
       keyPresent: creds !== null,
       keySource: creds !== null ? "keychain" : null,
@@ -1734,17 +1875,17 @@ async function statusCommand(opts = {}) {
     throw err;
   }
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(report)}
+    process.stdout.write(`${JSON.stringify(report2)}
 `);
   } else {
     const lines = [
-      `endpoint:    ${report.endpoint ?? "(not set)"}`,
-      `credentials: ${report.loggedIn ? "present (keychain)" : "not logged in \u2014 run: pyx-mem login"}`
+      `endpoint:    ${report2.endpoint ?? "(not set)"}`,
+      `credentials: ${report2.loggedIn ? "present (keychain)" : "not logged in \u2014 run: pyx-mem login"}`
     ];
     process.stdout.write(`${lines.join("\n")}
 `);
   }
-  return report.loggedIn ? EXIT.OK : EXIT.NOT_LOGGED_IN;
+  return report2.loggedIn ? EXIT.OK : EXIT.NOT_LOGGED_IN;
 }
 function emitError(err, json) {
   if (json) {
@@ -1769,6 +1910,7 @@ Usage:
 Commands:
   login [--endpoint <url>] [--api-key <key>]   Store endpoint and API key in OS credential store.
   status [--json]                              Show endpoint, key presence, MCP config status.
+  overview --json                              Read memory count and three recent safe labels.
   logout                                       Delete stored pyx-memory credentials.
   doctor [--json]                              Diagnose keychain, credentials, backend, MCP startup.
   scaffold [--name <dir>]                      Generate Docker, env, SDK, and memory design-guide starter files.
@@ -1915,6 +2057,12 @@ async function main() {
       });
     case "status":
       return statusCommand({ json: parsed.flags.json === true });
+    case "overview":
+      if (parsed.flags.json !== true) {
+        process.stderr.write("Error: `pyx-mem overview` requires --json.\n");
+        return EXIT.USAGE;
+      }
+      return overviewCommand();
     case "logout":
       return logoutCommand();
     case "doctor":
@@ -1932,10 +2080,10 @@ async function main() {
   }
 }
 main().then((code) => {
-  process.exit(code);
+  process.exitCode = code;
 }).catch((err) => {
   const msg = err instanceof Error ? err.message : String(err);
   process.stderr.write(`Internal error: ${msg}
 `);
-  process.exit(1);
+  process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "1.17.18",
+  "version": "1.17.19",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",