@pyxmate/memory 1.27.0 → 1.27.2

package/dist/doctor-AERNUHEZ.mjs

@@ -0,0 +1,143 @@
+import {
+  probeCredentials
+} from "./chunk-S3CX323Z.mjs";
+import {
+  KeychainError,
+  getDefaultKeychain
+} from "./chunk-7TATCSSN.mjs";
+import {
+  EXIT
+} from "./chunk-4DXEQC6X.mjs";
+
+// src/cli/commands/doctor.ts
+async function doctorCommand(opts = {}) {
+  const provider = opts.keychain ?? getDefaultKeychain();
+  const fetcher = opts.fetchImpl ?? fetch;
+  const checks = [];
+  const accessCheck = await provider.check();
+  if (accessCheck.ok) {
+    checks.push({ id: "provider.import", status: "pass", message: "native keyring module loaded" });
+    checks.push({ id: "keychain.access", status: "pass", message: accessCheck.message });
+  } else if (accessCheck.code === "provider-import-failed") {
+    checks.push({
+      id: "provider.import",
+      status: "fail",
+      code: accessCheck.code,
+      message: accessCheck.message,
+      guidance: accessCheck.guidance
+    });
+    checks.push({
+      id: "keychain.access",
+      status: "skip",
+      message: "skipped \u2014 provider import failed"
+    });
+  } else {
+    checks.push({ id: "provider.import", status: "pass", message: "native keyring module loaded" });
+    checks.push({
+      id: "keychain.access",
+      status: "fail",
+      code: accessCheck.code,
+      message: accessCheck.message,
+      guidance: accessCheck.guidance
+    });
+  }
+  const accessOk = accessCheck.ok;
+  let creds = null;
+  if (accessOk) {
+    try {
+      creds = await provider.read();
+      if (creds) {
+        checks.push({
+          id: "credentials.present",
+          status: "pass",
+          message: "credentials present in keychain",
+          endpoint: creds.endpoint
+        });
+      } else {
+        checks.push({
+          id: "credentials.present",
+          status: "fail",
+          code: "not-logged-in",
+          message: "no pyx-memory credentials stored",
+          guidance: "Run: pyx-mem login"
+        });
+      }
+    } catch (err) {
+      if (err instanceof KeychainError) {
+        checks.push({
+          id: "credentials.present",
+          status: "fail",
+          code: err.code,
+          message: err.message,
+          guidance: err.guidance
+        });
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    checks.push({
+      id: "credentials.present",
+      status: "skip",
+      message: "skipped \u2014 keychain access failed"
+    });
+  }
+  if (creds) {
+    const probe = await probeCredentials({
+      endpoint: creds.endpoint,
+      apiKey: creds.apiKey,
+      fetcher
+    });
+    if (probe.kind === "ok") {
+      checks.push({
+        id: "backend.reachable",
+        status: "pass",
+        message: `pyx-memory API reachable (HTTP ${probe.status})`,
+        endpoint: creds.endpoint
+      });
+    } else if (probe.kind === "invalid") {
+      checks.push({
+        id: "backend.reachable",
+        status: "fail",
+        code: "key-rejected",
+        message: `API key rejected (HTTP ${probe.status})`,
+        endpoint: creds.endpoint,
+        guidance: "Re-login with a valid key: pyx-mem login"
+      });
+    } else {
+      checks.push({
+        id: "backend.reachable",
+        status: "fail",
+        code: "unreachable",
+        message: `no pyx-memory API at this endpoint (${probe.reason})`,
+        endpoint: creds.endpoint,
+        guidance: "Verify the endpoint is the API backend, not a web UI: pyx-mem login --endpoint <API_URL>"
+      });
+    }
+  } else {
+    checks.push({
+      id: "backend.reachable",
+      status: "skip",
+      message: "skipped \u2014 no credentials to probe"
+    });
+  }
+  const ok = checks.every((c) => c.status !== "fail");
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ ok, checks })}
+`);
+  } else {
+    for (const c of checks) {
+      const tag = c.status === "pass" ? "OK  " : c.status === "skip" ? "SKIP" : "FAIL";
+      process.stdout.write(`[${tag}] ${c.id}: ${c.message}
+`);
+      if (c.endpoint) process.stdout.write(`       endpoint: ${c.endpoint}
+`);
+      if (c.status === "fail" && c.guidance) process.stdout.write(`       ${c.guidance}
+`);
+    }
+  }
+  return ok ? EXIT.OK : EXIT.DOCTOR_FAIL;
+}
+export {
+  doctorCommand
+};

package/dist/insights-PD7Y6QDX.mjs

@@ -0,0 +1,139 @@
+import {
+  readSurface
+} from "./chunk-UESIQ47D.mjs";
+import "./chunk-THLUBOGD.mjs";
+import "./chunk-7TATCSSN.mjs";
+import {
+  MEMORY_PROJECT_LABEL_MAX_CHARS,
+  TAXONOMY_MAX_PROJECTS,
+  normalizeMemoryActorLabel
+} from "./chunk-RWQTBXUC.mjs";
+import "./chunk-HTQBKJTD.mjs";
+import {
+  EXIT
+} from "./chunk-4DXEQC6X.mjs";
+
+// src/cli/commands/insights.ts
+import { z } from "zod";
+var INSIGHTS_SCHEMA_VERSION = 1;
+var metricsSchema = z.object({
+  activeEntries: z.number().int().nonnegative(),
+  retainedAdditions7d: z.number().int().nonnegative(),
+  appliedRecalls: z.number().int().nonnegative(),
+  reinforcedEntries: z.number().int().nonnegative(),
+  retrievedEntries: z.number().int().nonnegative(),
+  retrievals: z.number().int().nonnegative(),
+  lastAppliedAt: z.string().nullable(),
+  lastRetrievedAt: z.string().nullable()
+});
+var insightsSchema = z.object({
+  generatedAt: z.string(),
+  scope: z.literal("connected_memory"),
+  coverage: z.object({
+    retainedAdditions: z.object({
+      state: z.enum(["measured", "partial"]),
+      trackingSince: z.string().nullable(),
+      trackedEntries: z.number().int().nonnegative(),
+      totalEntries: z.number().int().nonnegative(),
+      reason: z.string().nullable()
+    }),
+    projectLabels: z.object({ state: z.literal("measured") }),
+    retrievalUsage: z.object({ state: z.literal("partial"), reason: z.string() }),
+    tokenEfficiency: z.object({ state: z.literal("not_instrumented"), reason: z.string() }),
+    contextAccuracy: z.object({ state: z.literal("not_instrumented"), reason: z.string() })
+  }),
+  summary: z.object({
+    activeEntries: z.number().int().nonnegative(),
+    observedProjectLabels: z.number().int().nonnegative(),
+    retainedAdditions7d: z.number().int().nonnegative().nullable(),
+    trackedEntries: z.number().int().nonnegative(),
+    appliedRecalls: z.number().int().nonnegative(),
+    reinforcedEntries: z.number().int().nonnegative(),
+    retrievedEntries: z.number().int().nonnegative(),
+    retrievals: z.number().int().nonnegative()
+  }),
+  projects: z.array(
+    metricsSchema.extend({
+      label: z.string().min(1).max(MEMORY_PROJECT_LABEL_MAX_CHARS)
+    })
+  ).max(TAXONOMY_MAX_PROJECTS),
+  other: metricsSchema.nullable(),
+  recentApplied: z.array(
+    z.object({
+      topic: z.string().min(1).max(MEMORY_PROJECT_LABEL_MAX_CHARS).nullable(),
+      project: z.string().min(1).max(MEMORY_PROJECT_LABEL_MAX_CHARS).nullable(),
+      at: z.string()
+    })
+  ).max(5)
+});
+var actorSchema = z.string().refine((value) => normalizeMemoryActorLabel(value) === value).nullable().default(null);
+var insightsWithProvenanceSchema = insightsSchema.extend({
+  recentApplied: z.array(
+    insightsSchema.shape.recentApplied.element.extend({
+      writtenBy: actorSchema,
+      writtenAt: z.iso.datetime({ offset: true }).nullable().default(null),
+      appliedBy: actorSchema
+    })
+  ).max(5)
+});
+async function insightsCommand(opts = {}) {
+  const schema = opts.withProvenance === true ? insightsWithProvenanceSchema : insightsSchema;
+  const result = await readSurface({
+    surface: "insights",
+    request: { method: "GET", path: "/api/memory/insights" },
+    schema: z.union([
+      schema,
+      z.object({ success: z.literal(true), data: schema }).transform(({ data }) => data)
+    ]),
+    minimumServiceVersion: "1.19.0",
+    keychain: opts.keychain,
+    fetchImpl: opts.fetchImpl
+  });
+  const withIdentity = opts.withIdentity === true;
+  if (!result.ok) {
+    emit(
+      report(result.state, result.endpoint, result.keySource, result.problem, {
+        withIdentity,
+        credentialFingerprint: result.credentialFingerprint
+      })
+    );
+    return result.exit;
+  }
+  emit({
+    schemaVersion: INSIGHTS_SCHEMA_VERSION,
+    state: "ready",
+    endpoint: result.endpoint,
+    keySource: "keychain",
+    ...identityField({ withIdentity, credentialFingerprint: result.credentialFingerprint }),
+    ...result.data,
+    problem: null
+  });
+  return EXIT.OK;
+}
+function identityField(identity) {
+  return identity.withIdentity ? { credentialFingerprint: identity.credentialFingerprint } : {};
+}
+function report(state, endpoint, keySource, problem, identity) {
+  return {
+    schemaVersion: INSIGHTS_SCHEMA_VERSION,
+    state,
+    endpoint,
+    keySource,
+    ...identityField(identity),
+    generatedAt: null,
+    scope: "connected_memory",
+    coverage: null,
+    summary: null,
+    projects: [],
+    other: null,
+    recentApplied: [],
+    problem
+  };
+}
+function emit(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+export {
+  insightsCommand
+};

package/dist/login-4ALCAN4M.mjs

@@ -0,0 +1,179 @@
+import {
+  probeCredentials
+} from "./chunk-S3CX323Z.mjs";
+import {
+  BUSY,
+  KeychainError,
+  getLifecycleKeychain,
+  supersedeLogout,
+  withLifecycleLock
+} from "./chunk-7TATCSSN.mjs";
+import {
+  EXIT
+} from "./chunk-4DXEQC6X.mjs";
+
+// src/cli/prompt.ts
+async function readApiKeySecret() {
+  if (process.stdin.isTTY) {
+    return promptMasked("API key: ");
+  }
+  return readSingleLineFromStdin();
+}
+async function promptMasked(label) {
+  const { stdin, stdout } = process;
+  stdout.write(label);
+  const hadRawMode = typeof stdin.setRawMode === "function";
+  if (!hadRawMode) {
+    const value = await readSingleLineFromStdin();
+    stdout.write(`${"\u2022".repeat(Math.min(value.length, 80))}
+`);
+    return value;
+  }
+  return new Promise((resolve, reject) => {
+    const previousEncoding = stdin.readableEncoding;
+    stdin.setEncoding("utf8");
+    stdin.setRawMode(true);
+    stdin.resume();
+    let buf = "";
+    const cleanup = () => {
+      stdin.removeListener("data", onData);
+      stdin.removeListener("error", onError);
+      stdin.setRawMode(false);
+      stdin.pause();
+      if (previousEncoding) stdin.setEncoding(previousEncoding);
+    };
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === "\n" || ch === "\r") {
+          cleanup();
+          stdout.write("\n");
+          resolve(buf.trim());
+          return;
+        }
+        if (ch === "") {
+          cleanup();
+          stdout.write("\n");
+          process.exit(130);
+        }
+        if (ch === "\x7F" || ch === "\b") {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (ch < " ") {
+          continue;
+        }
+        buf += ch;
+        stdout.write("\u2022");
+      }
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+    stdin.on("data", onData);
+    stdin.on("error", onError);
+  });
+}
+async function readSingleLineFromStdin() {
+  let buf = "";
+  for await (const chunk of process.stdin) {
+    buf += chunk.toString("utf8");
+    const nl = buf.indexOf("\n");
+    if (nl >= 0) return buf.slice(0, nl).trim();
+  }
+  return buf.trim();
+}
+
+// src/cli/commands/login.ts
+var DEFAULT_ENDPOINT = "https://memory.api.pyxmate.com";
+async function loginCommand(opts = {}) {
+  const provider = opts.keychain ?? getLifecycleKeychain();
+  const fetcher = opts.fetchImpl ?? fetch;
+  const endpoint = normalizeEndpoint(
+    opts.endpoint ?? await readExistingEndpoint(provider) ?? DEFAULT_ENDPOINT
+  );
+  if (!isHttpUrl(endpoint)) {
+    process.stderr.write(`Error: invalid --endpoint \`${endpoint}\` (expected http(s) URL).
+`);
+    return EXIT.USAGE;
+  }
+  let apiKey;
+  try {
+    apiKey = opts.apiKey?.trim() || await readApiKeySecret();
+  } catch (err) {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+    return EXIT.USAGE;
+  }
+  if (!apiKey) {
+    process.stderr.write("Error: API key is empty.\n");
+    return EXIT.USAGE;
+  }
+  const probe = await probeCredentials({ endpoint, apiKey, fetcher });
+  if (probe.kind === "invalid") {
+    process.stderr.write(
+      `Error: API key was rejected by ${endpoint} (HTTP ${probe.status}).
+No credentials were written.
+`
+    );
+    return EXIT.NOT_LOGGED_IN;
+  }
+  try {
+    const written = await withLifecycleLock(provider, async () => {
+      await supersedeLogout(provider, endpoint, apiKey);
+      await provider.write({ schemaVersion: 1, endpoint, apiKey });
+    });
+    if (written === BUSY) {
+      process.stderr.write(
+        "Error: another pyx-mem sign-in or sign-out is in progress. Retry in a moment.\nNo credentials were written.\n"
+      );
+      return EXIT.BUSY;
+    }
+  } catch (err) {
+    if (err instanceof KeychainError) {
+      process.stderr.write(
+        `Error: ${err.message}
+${err.guidance}
+No credentials were written. pyx-mem does not write plaintext token files.
+`
+      );
+      return err.exit;
+    }
+    throw err;
+  }
+  if (probe.kind === "unreachable") {
+    process.stdout.write(
+      `Stored credentials for ${endpoint}. Warning: validation probe failed (${probe.reason}). Run: pyx-mem doctor
+`
+    );
+  } else {
+    process.stdout.write(`Logged in to ${endpoint}. Run: pyx-mem doctor
+`);
+  }
+  return EXIT.OK;
+}
+async function readExistingEndpoint(provider) {
+  try {
+    const creds = await provider.read();
+    return creds?.endpoint ?? null;
+  } catch {
+    return null;
+  }
+}
+function normalizeEndpoint(input) {
+  return input.replace(/\/+$/, "");
+}
+function isHttpUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+export {
+  loginCommand
+};