@chendpoc/pi-memory 0.2.2 → 0.2.3

package/src/utils/debugLog.ts

@@ -1,22 +0,0 @@
-import { theme } from "../cli/theme.js";
-
-export function isMemoryDebugEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.PI_MEMORY_DEBUG === "1" || env.PI_MEMORY_DEBUG === "true";
-}
-
-/** Debug-only stderr log; never shown to Pi UI or session. */
-export function debugMemory(
-  scope: string,
-  message: string,
-  fields?: Record<string, string | number | boolean | null | undefined>,
-  env: NodeJS.ProcessEnv = process.env,
-): void {
-  if (!isMemoryDebugEnabled(env)) return;
-
-  const suffix =
-    fields && Object.keys(fields).length > 0
-      ? ` ${JSON.stringify(fields, (_key, value) => (value === undefined ? null : value))}`
-      : "";
-
-  console.error(theme.dim(`[${scope}] ${message}${suffix}`));
-}

package/src/utils/fs.ts

@@ -1,115 +0,0 @@
-/** Runtime fs helpers. Pre-build postinstall mirror: scripts/platform-fs.mjs */
-import { accessSync, existsSync, mkdirSync, constants } from "node:fs";
-import {
-  appendFile,
-  mkdir,
-  readFile,
-  readdir,
-  unlink,
-  writeFile,
-} from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
-
-import { expandHomePath, mkdirOptions } from "./paths.js";
-
-/** Cross-platform path join (`\` on Windows, `/` on POSIX). */
-export function joinPath(...segments: string[]): string {
-  return join(...segments);
-}
-
-export function pathBasename(filePath: string): string {
-  return basename(filePath);
-}
-
-export function pathDirname(filePath: string): string {
-  return dirname(filePath);
-}
-
-export function pathExists(filePath: string): boolean {
-  return existsSync(expandHomePath(filePath));
-}
-
-/** True when the current process can read the path. */
-export function canRead(filePath: string): boolean {
-  try {
-    accessSync(expandHomePath(filePath), constants.R_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function isENOENT(error: unknown): boolean {
-  return (error as NodeJS.ErrnoException)?.code === "ENOENT";
-}
-
-/** Create directory tree; Unix applies secure mode, Windows omits mode. */
-export async function ensureDir(dirPath: string): Promise<void> {
-  await mkdir(expandHomePath(dirPath), mkdirOptions());
-}
-
-export function ensureDirSync(dirPath: string): void {
-  mkdirSync(expandHomePath(dirPath), mkdirOptions());
-}
-
-/** Read UTF-8 text; missing file → empty string. */
-export async function readText(filePath: string): Promise<string> {
-  try {
-    return await readFile(expandHomePath(filePath), "utf8");
-  } catch (error) {
-    if (isENOENT(error)) return "";
-    throw error;
-  }
-}
-
-/** Read UTF-8 text; propagates ENOENT. */
-export async function readTextRequired(filePath: string): Promise<string> {
-  return readFile(expandHomePath(filePath), "utf8");
-}
-
-/** Write UTF-8 text; creates parent directories. */
-export async function writeText(filePath: string, content: string): Promise<void> {
-  const resolved = expandHomePath(filePath);
-  await ensureDir(dirname(resolved));
-  await writeFile(resolved, content, "utf8");
-}
-
-/** Append UTF-8 text; creates parent directories. */
-export async function appendText(filePath: string, content: string): Promise<void> {
-  const resolved = expandHomePath(filePath);
-  await ensureDir(dirname(resolved));
-  await appendFile(resolved, content, "utf8");
-}
-
-/** List directory entries; missing dir → empty array. */
-export async function listDir(dirPath: string): Promise<string[]> {
-  try {
-    return await readdir(expandHomePath(dirPath));
-  } catch (error) {
-    if (isENOENT(error)) return [];
-    throw error;
-  }
-}
-
-/** Delete file; missing file → no-op. */
-export async function removeFile(filePath: string): Promise<void> {
-  try {
-    await unlink(expandHomePath(filePath));
-  } catch (error) {
-    if (isENOENT(error)) return;
-    throw error;
-  }
-}
-
-/** Ensure file exists (empty) for lockfile targets. */
-export async function ensureFile(filePath: string): Promise<void> {
-  try {
-    await readTextRequired(filePath);
-  } catch (error) {
-    if (isENOENT(error)) {
-      await writeText(filePath, "");
-      return;
-    }
-    throw error;
-  }
-}

package/src/utils/index.ts

@@ -1,68 +0,0 @@
-export {
-  getPlatform,
-  isMacOS,
-  isUnixLike,
-  isWindows,
-  type PiMemoryPlatform,
-} from "./platform.js";
-
-export {
-  CONFIG_DIR_NAME,
-  defaultMemoryAgentDir,
-  defaultPiConfigDir,
-  defaultPiMemoryEnvFile,
-  defaultPiLogsDir,
-  expandHomePath,
-  getAgentDir,
-  mkdirOptions,
-  secureDirMode,
-  secureFileMode,
-} from "./paths.js";
-
-export {
-  appendText,
-  canRead,
-  ensureDir,
-  ensureDirSync,
-  ensureFile,
-  isENOENT,
-  joinPath,
-  listDir,
-  pathBasename,
-  pathDirname,
-  pathExists,
-  readText,
-  readTextRequired,
-  removeFile,
-  writeText,
-} from "./fs.js";
-
-export { cleanupSocketFiles, removeSocketFile, secureSocketPath } from "./socket.js";
-
-export { debugMemory, isMemoryDebugEnabled } from "./debugLog.js";
-
-export {
-  daysSince,
-  epochTimestamp,
-  formatLocalDate,
-  formatTimestamp,
-  now,
-  nowMs,
-  parseTime,
-  remainingMs,
-  type TimeInput,
-} from "./time.js";
-
-export {
-  buildConsolidateCliArgs,
-  buildMaintenanceCliArgs,
-  defaultConsolidateSchedulerPaths,
-  formatConsolidateCronLine,
-  formatMaintenanceCronLine,
-  getConsolidateSchedulerKind,
-  getConsolidateTemplateNames,
-  type ConsolidateCliInvocation,
-  type ConsolidateSchedulerKind,
-  type ConsolidateSchedulerPaths,
-  type ConsolidateTemplateName,
-} from "./scheduler.js";

package/src/utils/paths.ts

@@ -1,67 +0,0 @@
-import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-import {
-  CONSOLIDATE_ERR_LOG_FILE,
-  CONSOLIDATE_LOG_FILE,
-  PI_MEMORY_DATA_SUBDIR,
-  PI_MEMORY_ENV_FILE_NAME,
-  PI_LOGS_SUBDIR,
-} from "../constants/paths.js";
-import { SECURE_DIR_MODE, SECURE_FILE_MODE } from "../constants/security.js";
-import { isWindows } from "./platform.js";
-
-export { CONFIG_DIR_NAME, getAgentDir };
-
-/** Expand leading `~` or `~/` using the current user's home directory. */
-export function expandHomePath(input: string): string {
-  const trimmed = input.trim();
-  if (trimmed === "~") return homedir();
-  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
-    return join(homedir(), trimmed.slice(2));
-  }
-  return trimmed;
-}
-
-/** Pi user config root (~/.pi). Uses Pi's CONFIG_DIR_NAME. */
-export function defaultPiConfigDir(): string {
-  return join(homedir(), CONFIG_DIR_NAME);
-}
-
-/** Memory data root: ~/.pi/pi-memory-data */
-export function defaultMemoryAgentDir(): string {
-  return join(defaultPiConfigDir(), PI_MEMORY_DATA_SUBDIR);
-}
-
-/** pi-memory config: ~/.pi/agent/pi-memory.env */
-export function defaultPiMemoryEnvFile(): string {
-  return join(getAgentDir(), PI_MEMORY_ENV_FILE_NAME);
-}
-
-export function defaultPiLogsDir(): string {
-  return join(defaultPiConfigDir(), PI_LOGS_SUBDIR);
-}
-
-export function defaultConsolidateLogPath(): string {
-  return join(defaultPiLogsDir(), CONSOLIDATE_LOG_FILE);
-}
-
-export function defaultConsolidateErrLogPath(): string {
-  return join(defaultPiLogsDir(), CONSOLIDATE_ERR_LOG_FILE);
-}
-
-/** Directory mode for agent / socket parent dirs (Unix only; ignored on Windows). */
-export function secureDirMode(): number | undefined {
-  return isWindows() ? undefined : SECURE_DIR_MODE;
-}
-
-/** File mode for socket files (Unix only; ignored on Windows). */
-export function secureFileMode(): number | undefined {
-  return isWindows() ? undefined : SECURE_FILE_MODE;
-}
-
-export function mkdirOptions(): { recursive: true; mode?: number } {
-  const mode = secureDirMode();
-  return mode === undefined ? { recursive: true } : { recursive: true, mode };
-}

package/src/utils/platform.ts

@@ -1,20 +0,0 @@
-export type PiMemoryPlatform = "darwin" | "win32" | "other";
-
-export function getPlatform(): PiMemoryPlatform {
-  if (process.platform === "darwin") return "darwin";
-  if (process.platform === "win32") return "win32";
-  return "other";
-}
-
-export function isWindows(): boolean {
-  return process.platform === "win32";
-}
-
-export function isMacOS(): boolean {
-  return process.platform === "darwin";
-}
-
-/** Unix-like platforms where chmod / UDS cleanup apply. */
-export function isUnixLike(): boolean {
-  return !isWindows();
-}

package/src/utils/scheduler.ts

@@ -1,98 +0,0 @@
-import {
-  LAUNCHD_LABEL,
-  SCHEDULER_TEMPLATE_FILES,
-  SCHTASKS_TASK_NAME,
-} from "../constants/paths.js";
-import {
-  defaultConsolidateErrLogPath,
-  defaultConsolidateLogPath,
-  defaultMemoryAgentDir,
-  defaultPiMemoryEnvFile,
-  defaultPiLogsDir,
-} from "./paths.js";
-import { getPlatform, isMacOS, isWindows, type PiMemoryPlatform } from "./platform.js";
-
-export type ConsolidateSchedulerKind = "launchd" | "crontab" | "schtasks";
-
-/** Recommended OS scheduler for daily consolidate on this platform. */
-export function getConsolidateSchedulerKind(platform: PiMemoryPlatform = getPlatform()): ConsolidateSchedulerKind {
-  if (platform === "darwin") return "launchd";
-  if (platform === "win32") return "schtasks";
-  return "crontab";
-}
-
-export type ConsolidateSchedulerPaths = {
-  agentDir: string;
-  envFile: string;
-  logsDir: string;
-  stdoutLog: string;
-  stderrLog: string;
-};
-
-export function defaultConsolidateSchedulerPaths(): ConsolidateSchedulerPaths {
-  return {
-    agentDir: defaultMemoryAgentDir(),
-    envFile: defaultPiMemoryEnvFile(),
-    logsDir: defaultPiLogsDir(),
-    stdoutLog: defaultConsolidateLogPath(),
-    stderrLog: defaultConsolidateErrLogPath(),
-  };
-}
-
-export type ConsolidateCliInvocation = {
-  nodePath: string;
-  cliPath: string;
-  cron: boolean;
-  verbose: boolean;
-  agentDir?: string;
-};
-
-/** argv for `pi-memory maintenance` (OS scheduler / wrapper scripts). */
-export function buildMaintenanceCliArgs(
-  opts: Pick<ConsolidateCliInvocation, "cron" | "verbose" | "agentDir">,
-): string[] {
-  const args = ["maintenance"];
-  if (opts.cron) args.push("--cron");
-  if (opts.verbose) args.push("--verbose");
-  if (opts.agentDir) args.push("--agent-dir", opts.agentDir);
-  return args;
-}
-
-/** @deprecated Prefer buildMaintenanceCliArgs for OS schedulers. */
-export function buildConsolidateCliArgs(opts: Pick<ConsolidateCliInvocation, "cron" | "verbose" | "agentDir">): string[] {
-  return buildMaintenanceCliArgs(opts);
-}
-
-/** Single-line shell command (macOS / Linux crontab). */
-export function formatMaintenanceCronLine(opts: ConsolidateCliInvocation & ConsolidateSchedulerPaths): string {
-  const args = buildMaintenanceCliArgs(opts).join(" ");
-  return [
-    `PI_MEMORY_ENV_FILE=${opts.envFile}`,
-    `PI_MEMORY_AGENT_DIR=${opts.agentDir}`,
-    opts.nodePath,
-    opts.cliPath,
-    args,
-    `>> ${opts.stdoutLog} 2>&1`,
-  ].join(" ");
-}
-
-/** @deprecated Prefer formatMaintenanceCronLine. */
-export function formatConsolidateCronLine(opts: ConsolidateCliInvocation & ConsolidateSchedulerPaths): string {
-  return formatMaintenanceCronLine(opts);
-}
-
-export type ConsolidateTemplateName =
-  (typeof SCHEDULER_TEMPLATE_FILES)[keyof typeof SCHEDULER_TEMPLATE_FILES];
-
-/** Template file basename shipped under templates/ for this platform. */
-export function getConsolidateTemplateNames(platform: PiMemoryPlatform = getPlatform()): ConsolidateTemplateName[] {
-  if (platform === "darwin") {
-    return [SCHEDULER_TEMPLATE_FILES.launchd, SCHEDULER_TEMPLATE_FILES.crontab];
-  }
-  if (platform === "win32") {
-    return [SCHEDULER_TEMPLATE_FILES.windowsCmd, SCHEDULER_TEMPLATE_FILES.windowsSchtasks];
-  }
-  return [SCHEDULER_TEMPLATE_FILES.crontab];
-}
-
-export { LAUNCHD_LABEL, SCHEDULER_TEMPLATE_FILES, SCHTASKS_TASK_NAME, isMacOS, isWindows };

package/src/utils/socket.ts

@@ -1,33 +0,0 @@
-import { chmodSync, unlinkSync } from "node:fs";
-
-import { secureFileMode } from "./paths.js";
-import { isUnixLike } from "./platform.js";
-
-/** Remove stale socket file before bind (Unix domain sockets only). */
-export function removeSocketFile(socketPath: string): void {
-  if (!isUnixLike()) return;
-  try {
-    unlinkSync(socketPath);
-  } catch {
-    // ENOENT or in-use; listen() will surface real errors
-  }
-}
-
-/** Restrict socket permissions after bind (Unix only). */
-export function secureSocketPath(socketPath: string): void {
-  const mode = secureFileMode();
-  if (mode === undefined) return;
-  chmodSync(socketPath, mode);
-}
-
-/** Remove socket and pid companion files on shutdown. */
-export function cleanupSocketFiles(socketPath: string, pidPath?: string): void {
-  for (const path of [socketPath, pidPath]) {
-    if (!path) continue;
-    try {
-      unlinkSync(path);
-    } catch {
-      // already gone
-    }
-  }
-}

package/src/utils/time.ts

@@ -1,51 +0,0 @@
-import dayjs, { type ConfigType, type Dayjs } from "dayjs";
-
-export type TimeInput = ConfigType;
-
-/** Current local time. */
-export function now(): Dayjs {
-  return dayjs();
-}
-
-/** Unix epoch ms (deadlines, lock files, external APIs). */
-export function nowMs(): number {
-  return dayjs().valueOf();
-}
-
-/** Parse stored or external input; invalid values fall back to epoch. */
-export function parseTime(input: TimeInput): Dayjs {
-  const parsed = dayjs(input);
-  return parsed.isValid() ? parsed : dayjs(0);
-}
-
-/**
- * Local timestamp for MEMORY entries, GC markers, shutdown queue.
- * Format: YYYY-MM-DDTHH:mm:ss.SSS (local wall clock, no Z suffix).
- */
-export function formatTimestamp(input?: TimeInput): string {
-  const t = input === undefined ? dayjs() : parseTime(input);
-  return t.format("YYYY-MM-DDTHH:mm:ss.SSS");
-}
-
-/** Local calendar date (e.g. auto-YYYY-MM-DD-*.md). */
-export function formatLocalDate(input?: TimeInput): string {
-  const t = input === undefined ? dayjs() : parseTime(input);
-  return t.format("YYYY-MM-DD");
-}
-
-/** Fallback timestamp when entry metadata is missing. */
-export function epochTimestamp(): string {
-  return formatTimestamp(0);
-}
-
-/** Whole calendar days from `from` until `to` (local; default `to` = now). */
-export function daysSince(from: TimeInput, to?: TimeInput): number {
-  const end = to === undefined ? dayjs() : parseTime(to);
-  const start = parseTime(from);
-  return end.startOf("day").diff(start.startOf("day"), "day");
-}
-
-/** Milliseconds left until `deadlineMs` (default clock: now). */
-export function remainingMs(deadlineMs: number, atMs: number = nowMs()): number {
-  return Math.max(0, deadlineMs - atMs);
-}