@withone/cli 1.56.1 → 1.57.1

package/README.md

@@ -280,6 +280,18 @@ one actions knowledge shopify 67890abcdef
 
 Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.
 
+In `--agent` mode the response is a **digest**: request-building sections in full (method/URL, headers, description, enforcement rules, required and optional parameters, sample request, gotchas, error handling) plus a table of contents for the rest. Response shapes, response-field tables, and worked examples — the bulk of every large doc — are loaded on demand:
+
+```bash
+one --agent actions knowledge github <actionId>                              # digest + sections[] table of contents
+one --agent actions knowledge github <actionId> --section "Response Fields"  # one section, by heading or id
+one --agent actions knowledge github <actionId> --section response,examples  # several, by alias
+one --agent actions knowledge github <actionId> --full                       # whole document
+one --agent actions knowledge github <actionId> --toc                        # every section id, no document
+```
+
+The JSON carries `truncated`, `sections[]` (the omitted sections: id, heading, chars), and `more` (the commands to load the rest); the markdown ends with the same notice so it is never mistaken for the complete doc. Small documents are returned whole. Section requests are served from the local cache. Human (non-agent) output always prints the full document; `--section` works there too.
+
 ### `one actions execute <platform> <actionId> <connectionKey>`
 
 Execute an API action on a connected platform.
@@ -354,6 +366,7 @@ Knowledge and search commands also support cache flags:
 ```bash
 one actions knowledge gmail <actionId> --no-cache       # Skip cache, fetch fresh
 one actions knowledge gmail <actionId> --cache-status   # Check cache status
+one actions knowledge gmail <actionId> --section response   # Served from the cached doc, no fetch
 one actions search gmail "send email" --no-cache        # Skip cache for search
 one actions execute gmail <actionId> <key> --no-cache   # Fresh action-details lookup
 ```
@@ -364,7 +377,7 @@ Note: execution responses are never cached — the action always runs live. Only
 
 ### `one mem` — unified memory store
 
-One ships a local memory store (a real Postgres process bootstrapped on demand via the bundled `embedded-postgres` plugin, with a `postgres` plugin for remote/self-hosted) that backs both user-authored notes and synced platform data. **Zero-config** — the first `one mem` call on a fresh machine auto-initializes the cluster at `~/.one/pg/cluster/` and writes a daemon PID file so subsequent CLI invocations reuse it.
+One ships a local memory store (a real Postgres process bootstrapped on demand via the bundled `embedded-postgres` plugin, with a `postgres` plugin for remote/self-hosted) that backs both user-authored notes and synced platform data. **Zero-config** — the first `one mem` call on a fresh machine auto-initializes the cluster at `~/.one/pg/cluster/` and writes a daemon PID file so subsequent CLI invocations reuse it. The daemon listens on port 5434, moving to the next free port if another program already holds it; pin a port with `one mem config set embedded-postgres.port <n>`.
 
 ```bash
 # User memories — works immediately on a new install

package/dist/{chunk-KAF5SVJS.js → chunk-GKAIRI4Y.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-OLQ55K6B.js";
 import {
   getBackend
-} from "./chunk-VH46MAE4.js";
+} from "./chunk-IMU2X3ZV.js";
 
 // src/commands/mem/sql.ts
 async function memSqlCommand(sql) {

package/dist/{chunk-VH46MAE4.js → chunk-IMU2X3ZV.js}

@@ -1456,12 +1456,333 @@ var postgresPlugin = {
 };
 
 // src/lib/memory/plugins/embedded-postgres/index.ts
+import path2 from "path";
+
+// src/lib/memory/plugins/embedded-postgres/daemon.ts
 import fs from "fs";
 import net from "net";
 import path from "path";
 import { createRequire } from "module";
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 var requireFromHere = createRequire(import.meta.url);
+var PG_PORT_OFFSET = 1e3;
+var PORT_SEARCH_SPAN = 20;
+var LOG_MAX_BYTES = 10 * 1024 * 1024;
+var LOG_KEEP_BYTES = 1024 * 1024;
+var DEFAULT_STOP_TIMEOUT_MS = 15e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function pidFilePath(dataDir) {
+  return path.join(dataDir, ".pgserve.json");
+}
+function readPidFile(dataDir) {
+  try {
+    return JSON.parse(fs.readFileSync(pidFilePath(dataDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writePidFile(dataDir, rec) {
+  fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(pidFilePath(dataDir), JSON.stringify(rec, null, 2), { mode: 384 });
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function waitForExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (isPidAlive(pid)) {
+    if (Date.now() >= deadline) return false;
+    await sleep(50);
+  }
+  return true;
+}
+function signal(pid, sig) {
+  try {
+    process.kill(pid, sig);
+  } catch {
+  }
+}
+function canBind(host, port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen({ port, host, exclusive: true }, () => server.close(() => resolve(true)));
+  });
+}
+async function portPairFree(host, port) {
+  return port + PG_PORT_OFFSET <= 65535 && await canBind(host, port) && await canBind("127.0.0.1", port + PG_PORT_OFFSET);
+}
+async function choosePort(host, preferred, explicit) {
+  if (await portPairFree(host, preferred)) return preferred;
+  const hint = 'set a different "memory.embedded-postgres.port" in ~/.one/config.json';
+  if (explicit) {
+    throw new Error(
+      `Port ${preferred} (or ${preferred + PG_PORT_OFFSET}, its internal Postgres port) on ${host} is already in use by another program, so the embedded Postgres can't start there. Free it, or ${hint}.`
+    );
+  }
+  for (let port = preferred + 1; port <= preferred + PORT_SEARCH_SPAN; port++) {
+    if (await portPairFree(host, port)) return port;
+  }
+  throw new Error(
+    `Ports ${preferred}-${preferred + PORT_SEARCH_SPAN} on ${host} are all already in use, so the embedded Postgres can't start. Free one, or ${hint}.`
+  );
+}
+function readRange(file, start, length) {
+  const fd = fs.openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    const n = fs.readSync(fd, buf, 0, length, start);
+    return buf.subarray(0, n);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function fileSize(file) {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+function trimLog(logPath, maxBytes = LOG_MAX_BYTES, keepBytes = LOG_KEEP_BYTES) {
+  const size = fileSize(logPath);
+  if (size <= maxBytes) return;
+  const tail = readRange(logPath, size - keepBytes, keepBytes);
+  const nl = tail.indexOf(10);
+  const kept = nl === -1 ? tail : tail.subarray(nl + 1);
+  const notice = `[one] pgserve.log passed ${maxBytes} bytes; kept the last ${kept.length} (${(/* @__PURE__ */ new Date()).toISOString()})
+`;
+  fs.writeFileSync(logPath, Buffer.concat([Buffer.from(notice), kept]));
+}
+function logSince(logPath, offset, maxBytes = 2e3) {
+  const size = fileSize(logPath);
+  const start = Math.max(offset, size - maxBytes);
+  if (size <= start) return "";
+  return readRange(logPath, start, size - start).toString("utf8").replace(/\x1b\[[0-9;]*m/g, "").trim();
+}
+function lockIsStale(lockPath, ttlMs) {
+  try {
+    if (Date.now() - fs.statSync(lockPath).mtimeMs > ttlMs) return true;
+    const { pid } = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    return typeof pid === "number" && !isPidAlive(pid);
+  } catch {
+    return false;
+  }
+}
+async function withStartupLock(dataDir, waitMs, fn) {
+  const lockPath = path.join(dataDir, ".pgserve.lock");
+  const deadline = Date.now() + waitMs;
+  for (; ; ) {
+    try {
+      fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: "wx" });
+      break;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+    if (lockIsStale(lockPath, waitMs)) {
+      fs.rmSync(lockPath, { force: true });
+      continue;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out waiting for another \`one\` process to start the embedded Postgres (lock: ${lockPath}).`);
+    }
+    await sleep(100);
+  }
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+function readPostmasterPid(clusterDir) {
+  try {
+    const lines = fs.readFileSync(path.join(clusterDir, "postmaster.pid"), "utf8").split("\n");
+    const pid = Number.parseInt(lines[0] ?? "", 10);
+    const port = Number.parseInt(lines[3] ?? "", 10);
+    return pid > 0 && port > 0 ? { pid, port } : null;
+  } catch {
+    return null;
+  }
+}
+function pgserveOwner(postmasterPid, deps) {
+  const ppid = deps.processInfo(postmasterPid)?.ppid;
+  if (!ppid || ppid <= 1) return null;
+  const command = deps.processInfo(ppid)?.command ?? "";
+  return /pgserve[\\/]bin[\\/]postgres-server\.js/.test(command) ? ppid : null;
+}
+async function stopStaleCluster(clusterDir, deps, timeoutMs) {
+  const holder = readPostmasterPid(clusterDir);
+  if (!holder || !isPidAlive(holder.pid)) return;
+  if (await deps.probe(holder.port, "postmaster") !== "ours") return;
+  const owner = pgserveOwner(holder.pid, deps);
+  if (owner !== null) {
+    signal(owner, "SIGTERM");
+    if (!await waitForExit(owner, timeoutMs)) signal(owner, "SIGKILL");
+  }
+  if (!isPidAlive(holder.pid)) return;
+  signal(holder.pid, "SIGINT");
+  if (!await waitForExit(holder.pid, timeoutMs)) {
+    throw new Error(
+      `The embedded Postgres (PID ${holder.pid}) is holding ${clusterDir} and did not stop. Stop it (kill ${holder.pid}) and retry.`
+    );
+  }
+}
+async function findHealthyDaemon(dataDir, deps) {
+  const rec = readPidFile(dataDir);
+  if (!rec || !isPidAlive(rec.pid)) return null;
+  return await deps.probe(rec.port, "router") === "ours" ? rec.port : null;
+}
+function pgserveArgs(cfg, clusterDir, port) {
+  const args = [
+    "--data",
+    clusterDir,
+    "--port",
+    String(port),
+    "--host",
+    cfg.host,
+    "--log",
+    cfg.logLevel,
+    "--no-stats",
+    // Single process. In cluster mode a worker that can't bind the port is
+    // re-forked immediately, forever, each crash logging a full stack trace.
+    "--no-cluster"
+  ];
+  if (cfg.pgvector) args.push("--pgvector");
+  return args;
+}
+async function waitUntilServing(child, cfg, port, deps, log) {
+  const deadline = Date.now() + cfg.startupTimeoutMs;
+  const details = () => {
+    const tail = logSince(log.path, log.offset);
+    return `
+Log: ${log.path}${tail ? `
+${tail}` : ""}`;
+  };
+  for (; ; ) {
+    const exit = child.exitStatus();
+    if (exit) throw new Error(`pgserve exited (${exit}) before it was ready.${details()}`);
+    if (await deps.probe(port, "router") === "ours") return;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `pgserve did not start serving on ${cfg.host}:${port} within ${Math.round(cfg.startupTimeoutMs / 1e3)}s.${details()}`
+      );
+    }
+    await sleep(250);
+  }
+}
+async function ensureRunning(cfg, deps) {
+  const reused = await findHealthyDaemon(cfg.dataDir, deps);
+  if (reused !== null) return reused;
+  fs.mkdirSync(cfg.dataDir, { recursive: true });
+  const stopTimeoutMs = deps.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS;
+  return withStartupLock(cfg.dataDir, cfg.startupTimeoutMs + 3 * stopTimeoutMs, async () => {
+    const raced = await findHealthyDaemon(cfg.dataDir, deps);
+    if (raced !== null) return raced;
+    const clusterDir = path.join(cfg.dataDir, "cluster");
+    fs.mkdirSync(clusterDir, { recursive: true });
+    await stopStaleCluster(clusterDir, deps, stopTimeoutMs);
+    const port = await choosePort(cfg.host, cfg.port, cfg.portExplicit);
+    const logPath = path.join(cfg.dataDir, "pgserve.log");
+    trimLog(logPath);
+    const log = { path: logPath, offset: fileSize(logPath) };
+    const fd = fs.openSync(logPath, "a");
+    let child;
+    try {
+      child = deps.spawnPgserve(pgserveArgs(cfg, clusterDir, port), fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    await waitUntilServing(child, cfg, port, deps, log);
+    writePidFile(cfg.dataDir, {
+      pid: child.pid,
+      port,
+      dataDir: cfg.dataDir,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return port;
+  });
+}
+function sameDir(a, b) {
+  const norm = (p) => {
+    let r = path.resolve(p);
+    try {
+      r = fs.realpathSync.native(r);
+    } catch {
+    }
+    return process.platform === "win32" ? r.toLowerCase() : r;
+  };
+  return a !== "" && norm(a) === norm(b);
+}
+async function probeDataDirectory(Client, target, clusterDir) {
+  const client = new Client({ ...target, connectionTimeoutMillis: 3e3, query_timeout: 3e3 });
+  client.on("error", () => {
+  });
+  try {
+    await client.connect();
+  } catch (err) {
+    return err.code === "ECONNREFUSED" ? "down" : "other";
+  }
+  try {
+    const { rows } = await client.query("SHOW data_directory");
+    return sameDir(String(rows[0]?.data_directory ?? ""), clusterDir) ? "ours" : "other";
+  } catch {
+    return "other";
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
+function resolvePgserveBin() {
+  const pkg = requireFromHere.resolve("pgserve/package.json");
+  return path.resolve(path.dirname(pkg), "bin/pgserve-wrapper.cjs");
+}
+function spawnPgserve(args, logFd, cwd) {
+  const child = spawn(process.execPath, [resolvePgserveBin(), ...args], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    // pgserve resolves the bundled bun binary relative to its own package
+    // location, not cwd, so cwd doesn't matter — but pin it for clarity.
+    cwd
+  });
+  let status = null;
+  child.once("error", (err) => {
+    status = `failed to start: ${err.message}`;
+  });
+  child.once("exit", (code, sig) => {
+    status = sig ? `signal ${sig}` : `code ${code}`;
+  });
+  child.unref();
+  if (typeof child.pid !== "number") {
+    throw new Error("Failed to spawn pgserve \u2014 no PID returned.");
+  }
+  return { pid: child.pid, exitStatus: () => status };
+}
+function processInfo(pid) {
+  if (process.platform === "win32") return null;
+  const res = spawnSync("ps", ["-o", "ppid=", "-o", "command=", "-p", String(pid)], { encoding: "utf8" });
+  const match = /^(\d+)\s+(.*)$/.exec((res.stdout ?? "").trim());
+  return match ? { ppid: Number(match[1]), command: match[2] } : null;
+}
+function nodeDaemonDeps(cfg, Client, router) {
+  const clusterDir = path.join(cfg.dataDir, "cluster");
+  const direct = { user: "postgres", password: "postgres", database: "postgres" };
+  return {
+    probe: (port, via) => probeDataDirectory(
+      Client,
+      via === "router" ? { host: cfg.host, port, ...router } : { host: "127.0.0.1", port, ...direct },
+      clusterDir
+    ),
+    spawnPgserve: (args, logFd) => spawnPgserve(args, logFd, cfg.dataDir),
+    processInfo
+  };
+}
+
+// src/lib/memory/plugins/embedded-postgres/index.ts
 var BASE_CAPABILITIES = {
   vectorSearch: true,
   fullTextSearch: true,
@@ -1477,13 +1798,14 @@ var DEFAULTS = {
   // `path.join(homeDir(), ...)` here would capture the home directory before
   // ONE_HOME could take effect. See lib/home.ts.
   get dataDir() {
-    return path.join(homeDir(), ".one", "pg");
+    return path2.join(homeDir(), ".one", "pg");
   },
   database: "one_mem",
   schema: "public",
   pgvector: true,
   host: "127.0.0.1",
   port: 5434,
+  portExplicit: false,
   // pgserve auto-provisions databases; the bundled superuser is `postgres`
   // with no password by default. We don't expose the password to the user
   // since the daemon only listens on 127.0.0.1.
@@ -1501,6 +1823,7 @@ function parseConfig2(raw) {
     pgvector: r.pgvector ?? DEFAULTS.pgvector,
     host: r.host ?? DEFAULTS.host,
     port: r.port ?? DEFAULTS.port,
+    portExplicit: r.port !== void 0,
     user: r.user ?? DEFAULTS.user,
     password: r.password ?? DEFAULTS.password,
     logLevel: r.logLevel ?? DEFAULTS.logLevel,
@@ -1547,104 +1870,6 @@ function wrapClient2(pool) {
     }
   };
 }
-function pidFilePath(dataDir) {
-  return path.join(dataDir, ".pgserve.json");
-}
-function readPidFile(dataDir) {
-  try {
-    const raw = fs.readFileSync(pidFilePath(dataDir), "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-function writePidFile(dataDir, rec) {
-  fs.mkdirSync(dataDir, { recursive: true });
-  fs.writeFileSync(pidFilePath(dataDir), JSON.stringify(rec, null, 2), { mode: 384 });
-}
-function isPidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function isPortListening(host, port, timeoutMs = 1e3) {
-  return new Promise((resolve) => {
-    const socket = new net.Socket();
-    let resolved = false;
-    const finish = (ok) => {
-      if (resolved) return;
-      resolved = true;
-      socket.destroy();
-      resolve(ok);
-    };
-    socket.setTimeout(timeoutMs);
-    socket.once("connect", () => finish(true));
-    socket.once("timeout", () => finish(false));
-    socket.once("error", () => finish(false));
-    socket.connect(port, host);
-  });
-}
-async function waitForPort(host, port, deadlineAt) {
-  while (Date.now() < deadlineAt) {
-    if (await isPortListening(host, port)) return;
-    await new Promise((r) => setTimeout(r, 250));
-  }
-  throw new Error(
-    `pgserve did not start listening on ${host}:${port} within ${Math.round((deadlineAt - Date.now() + 3e4) / 1e3)}s. Check the data dir for the postgres log, or remove ${path.basename(pidFilePath("<dataDir>"))} and retry.`
-  );
-}
-function resolvePgserveBin() {
-  const pkg = requireFromHere.resolve("pgserve/package.json");
-  return path.resolve(path.dirname(pkg), "bin/pgserve-wrapper.cjs");
-}
-async function ensureRunning(cfg) {
-  const existing = readPidFile(cfg.dataDir);
-  if (existing && isPidAlive(existing.pid)) {
-    if (await isPortListening(cfg.host, existing.port)) {
-      cfg.port = existing.port;
-      return;
-    }
-  }
-  fs.mkdirSync(cfg.dataDir, { recursive: true });
-  const clusterDir = path.join(cfg.dataDir, "cluster");
-  fs.mkdirSync(clusterDir, { recursive: true });
-  const args = [
-    "--data",
-    clusterDir,
-    "--port",
-    String(cfg.port),
-    "--host",
-    cfg.host,
-    "--log",
-    cfg.logLevel,
-    "--no-stats"
-  ];
-  if (cfg.pgvector) args.push("--pgvector");
-  const bin = resolvePgserveBin();
-  const out = fs.openSync(path.join(cfg.dataDir, "pgserve.log"), "a");
-  const child = spawn(process.execPath, [bin, ...args], {
-    detached: true,
-    stdio: ["ignore", out, out],
-    // pgserve resolves the bundled bun binary relative to its own package
-    // location, not cwd, so cwd doesn't matter — but pin it for clarity.
-    cwd: cfg.dataDir
-  });
-  child.unref();
-  if (typeof child.pid !== "number") {
-    throw new Error("Failed to spawn pgserve \u2014 no PID returned.");
-  }
-  const deadlineAt = Date.now() + cfg.startupTimeoutMs;
-  await waitForPort(cfg.host, cfg.port, deadlineAt);
-  writePidFile(cfg.dataDir, {
-    pid: child.pid,
-    port: cfg.port,
-    dataDir: cfg.dataDir,
-    startedAt: (/* @__PURE__ */ new Date()).toISOString()
-  });
-}
 async function probePgvector(client) {
   try {
     await client.query("CREATE EXTENSION IF NOT EXISTS vector");
@@ -1662,12 +1887,20 @@ var LazyEmbeddedPostgresBackend = class {
   }
   async ensure() {
     if (this.backend) return this.backend;
-    await ensureRunning(this.config);
     const pgMod = await import("pg").catch((err) => {
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(`pg is not installed. Run \`npm i pg\` or pick a different backend. (${msg})`);
     });
-    const PoolCtor = pgMod.Pool ?? pgMod.default.Pool;
+    const pgExports = pgMod.Pool ? pgMod : pgMod.default;
+    const PoolCtor = pgExports.Pool;
+    this.config.port = await ensureRunning(
+      this.config,
+      nodeDaemonDeps(this.config, pgExports.Client, {
+        user: this.config.user,
+        password: this.config.password,
+        database: this.config.database
+      })
+    );
     const pool = new PoolCtor({
       host: this.config.host,
       port: this.config.port,

package/dist/{chunk-XWTV7FA3.js → chunk-YTM6HJKA.js}

@@ -10,7 +10,7 @@ import {
 import {
   getBackend,
   upsertRecord
-} from "./chunk-VH46MAE4.js";
+} from "./chunk-IMU2X3ZV.js";
 
 // src/commands/mem/migrate.ts
 import fs4 from "fs";