@shetty4l/core 0.1.3

package/src/scripts/version-bump.ts

@@ -0,0 +1,144 @@
+/**
+ * Creates a version bump marker commit for the release workflow.
+ *
+ * Usage:
+ *   bun run version:bump minor   # next release bumps minor (e.g. 0.1.18 -> 0.2.0)
+ *   bun run version:bump major   # next release bumps major (e.g. 0.1.18 -> 1.0.0)
+ *
+ * Patch bumps are the default in the release workflow and need no marker.
+ *
+ * The script creates an empty commit with a [minor] or [major] tag in the
+ * message. The release workflow scans all commits since the last tag for
+ * these markers to determine the bump level.
+ */
+
+type BumpLevel = "minor" | "major";
+
+const VALID_BUMPS: ReadonlySet<string> = new Set(["minor", "major"]);
+
+const run = (cmd: string[]): { stdout: string; exitCode: number } => {
+  const result = Bun.spawnSync({
+    cmd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    stdout: new TextDecoder().decode(result.stdout).trim(),
+    exitCode: result.exitCode,
+  };
+};
+
+const fail = (message: string): never => {
+  console.error(`error: ${message}`);
+  return process.exit(1) as never;
+};
+
+const getLatestTag = (): string => {
+  const { stdout, exitCode } = run(["git", "describe", "--tags", "--abbrev=0"]);
+  if (exitCode !== 0 || !stdout.startsWith("v")) {
+    fail("no git tags found. Create an initial tag (e.g. v0.1.0) first.");
+  }
+  return stdout;
+};
+
+const parseVersion = (tag: string): [number, number, number] => {
+  const match = tag.match(/^v(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) {
+    return fail(`cannot parse tag "${tag}" as semver.`);
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+};
+
+const computeNext = (
+  current: [number, number, number],
+  bump: BumpLevel,
+): string => {
+  const [major, minor] = current;
+  if (bump === "major") {
+    return `${major + 1}.0.0`;
+  }
+  return `${major}.${minor + 1}.0`;
+};
+
+const assertCleanTree = (): void => {
+  const { stdout } = run(["git", "status", "--porcelain"]);
+  if (stdout.length > 0) {
+    fail(
+      "working tree is dirty. Commit or stash changes first.\n" +
+        "  (version bump creates an empty commit and requires a clean tree)",
+    );
+  }
+};
+
+const assertHasCommits = (latestTag: string): void => {
+  const { stdout } = run(["git", "rev-list", "--count", `${latestTag}..HEAD`]);
+  if (stdout === "0") {
+    fail(`no commits since ${latestTag}. Make changes before bumping version.`);
+  }
+};
+
+const assertNoPendingBump = (latestTag: string, bump: BumpLevel): void => {
+  const { stdout } = run(["git", "log", `${latestTag}..HEAD`, "--format=%s"]);
+  if (stdout.includes(`[${bump}]`)) {
+    fail(
+      `a [${bump}] bump marker already exists in commits since ${latestTag}.\n` +
+        "  There is no need to run this again.",
+    );
+  }
+  // Warn if there's a different bump already pending
+  const other: BumpLevel = bump === "minor" ? "major" : "minor";
+  if (stdout.includes(`[${other}]`)) {
+    console.warn(
+      `warning: a [${other}] bump marker already exists since ${latestTag}.` +
+        ` Adding [${bump}] — the release workflow will use the higher of the two.`,
+    );
+  }
+};
+
+// --- main ---
+
+const bumpArg = process.argv[2];
+
+if (!bumpArg || !VALID_BUMPS.has(bumpArg)) {
+  console.error("usage: bun run version:bump <minor|major>");
+  console.error("");
+  console.error(
+    "  minor   bump minor version, reset patch (e.g. 0.1.18 -> 0.2.0)",
+  );
+  console.error(
+    "  major   bump major version, reset minor + patch (e.g. 0.1.18 -> 1.0.0)",
+  );
+  console.error("");
+  console.error("  Patch bumps are automatic and need no marker.");
+  process.exit(1);
+}
+
+const bump = bumpArg as BumpLevel;
+const latestTag = getLatestTag();
+const current = parseVersion(latestTag);
+const next = computeNext(current, bump);
+
+assertCleanTree();
+assertHasCommits(latestTag);
+assertNoPendingBump(latestTag, bump);
+
+const commitMessage = `chore: version bump v${next} [${bump}]`;
+
+const commitResult = run([
+  "git",
+  "commit",
+  "--allow-empty",
+  "-m",
+  commitMessage,
+]);
+
+if (commitResult.exitCode !== 0) {
+  fail("git commit failed.");
+}
+
+console.log("");
+console.log(`  current version:  ${latestTag}`);
+console.log(`  next version:     v${next} (${bump} bump)`);
+console.log("");
+console.log(`  created commit: ${commitMessage}`);
+console.log("");

package/src/signals.ts

@@ -0,0 +1,69 @@
+/**
+ * Graceful shutdown signal handling.
+ *
+ * Registers SIGINT/SIGTERM handlers that call a cleanup function
+ * before exiting. Supports timeout-based forced exit and
+ * double-signal emergency exit.
+ */
+
+export interface ShutdownOpts {
+  /** Signals to handle. Defaults to ["SIGINT", "SIGTERM"]. */
+  signals?: string[];
+  /** Force exit after this many ms. No timeout if omitted. */
+  timeoutMs?: number;
+}
+
+/**
+ * Register graceful shutdown handlers.
+ *
+ * On first signal: calls `cleanup()`, then `process.exit(0)`.
+ * On second signal (while cleanup is running): forces `process.exit(1)`.
+ * If `timeoutMs` is set: forces `process.exit(1)` after timeout.
+ */
+export function onShutdown(
+  cleanup: () => void | Promise<void>,
+  opts?: ShutdownOpts,
+): void {
+  const signals = opts?.signals ?? ["SIGINT", "SIGTERM"];
+  const timeoutMs = opts?.timeoutMs;
+  let shutting = false;
+
+  const handler = (signal: string) => {
+    if (shutting) {
+      process.exit(1);
+    }
+    shutting = true;
+    console.log(`\n${signal} received, shutting down...`);
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        console.error(`Shutdown timed out after ${timeoutMs}ms, forcing exit`);
+        process.exit(1);
+      }, timeoutMs);
+      // Don't block the event loop from exiting
+      timer.unref();
+    }
+
+    const maybePromise = cleanup();
+    if (maybePromise && typeof maybePromise.then === "function") {
+      maybePromise
+        .then(() => {
+          if (timer) clearTimeout(timer);
+          process.exit(0);
+        })
+        .catch((err) => {
+          console.error("Shutdown cleanup error:", err);
+          if (timer) clearTimeout(timer);
+          process.exit(1);
+        });
+    } else {
+      if (timer) clearTimeout(timer);
+      process.exit(0);
+    }
+  };
+
+  for (const signal of signals) {
+    process.on(signal, () => handler(signal));
+  }
+}

package/src/version.ts

@@ -0,0 +1,27 @@
+/**
+ * Read the VERSION file from a project root directory.
+ * Falls back to a default version string if the file doesn't exist.
+ *
+ * The VERSION file is written by CI during the release workflow.
+ * In local development, the fallback is used.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * Read a VERSION file from the given directory (project root).
+ *
+ * @param rootDir - Absolute path to the project root (where VERSION lives).
+ * @param fallback - Version string to use when VERSION file doesn't exist. Defaults to "0.0.0-dev".
+ */
+export function readVersion(
+  rootDir: string,
+  fallback: string = "0.0.0-dev",
+): string {
+  const versionFile = join(rootDir, "VERSION");
+  if (existsSync(versionFile)) {
+    return readFileSync(versionFile, "utf-8").trim();
+  }
+  return fallback;
+}

package/test/cli.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { formatUptime, parseArgs } from "../src/cli";
+
+// --- parseArgs ---
+
+describe("parseArgs", () => {
+  test("extracts command and args", () => {
+    const result = parseArgs(["start", "--port", "8080"]);
+    expect(result.command).toBe("start");
+    expect(result.args).toEqual(["--port", "8080"]);
+    expect(result.json).toBe(false);
+  });
+
+  test("strips --json flag", () => {
+    const result = parseArgs(["status", "--json"]);
+    expect(result.command).toBe("status");
+    expect(result.args).toEqual([]);
+    expect(result.json).toBe(true);
+  });
+
+  test("--json can appear anywhere", () => {
+    const result = parseArgs(["--json", "health"]);
+    expect(result.command).toBe("health");
+    expect(result.json).toBe(true);
+  });
+
+  test("defaults to help when empty", () => {
+    const result = parseArgs([]);
+    expect(result.command).toBe("help");
+    expect(result.args).toEqual([]);
+    expect(result.json).toBe(false);
+  });
+});
+
+// --- formatUptime ---
+
+describe("formatUptime", () => {
+  test("formats seconds", () => {
+    expect(formatUptime(45)).toBe("45s");
+  });
+
+  test("formats minutes and seconds", () => {
+    expect(formatUptime(192)).toBe("3m 12s");
+  });
+
+  test("formats hours and minutes", () => {
+    expect(formatUptime(8100)).toBe("2h 15m");
+  });
+
+  test("edge case: exactly 60 seconds", () => {
+    expect(formatUptime(60)).toBe("1m 0s");
+  });
+
+  test("edge case: exactly 1 hour", () => {
+    expect(formatUptime(3600)).toBe("1h 0m");
+  });
+
+  test("zero seconds", () => {
+    expect(formatUptime(0)).toBe("0s");
+  });
+});

package/test/config.test.ts

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import {
+  expandPath,
+  getConfigDir,
+  getDataDir,
+  interpolateDeep,
+  interpolateEnvVars,
+  loadJsonConfig,
+  parsePort,
+} from "../src/config";
+
+const TMP = join(import.meta.dir, ".tmp-config");
+
+beforeEach(() => {
+  if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+  mkdirSync(TMP, { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+  // Clean up env vars
+  delete process.env.XDG_DATA_HOME;
+  delete process.env.XDG_CONFIG_HOME;
+  delete process.env.CORE_TEST_VAR;
+});
+
+// --- getDataDir ---
+
+describe("getDataDir", () => {
+  test("uses XDG_DATA_HOME when set", () => {
+    process.env.XDG_DATA_HOME = "/custom/data";
+    expect(getDataDir("engram")).toBe("/custom/data/engram");
+  });
+
+  test("falls back to ~/.local/share/{name}", () => {
+    delete process.env.XDG_DATA_HOME;
+    expect(getDataDir("engram")).toBe(
+      join(homedir(), ".local", "share", "engram"),
+    );
+  });
+});
+
+// --- getConfigDir ---
+
+describe("getConfigDir", () => {
+  test("uses XDG_CONFIG_HOME when set", () => {
+    process.env.XDG_CONFIG_HOME = "/custom/config";
+    expect(getConfigDir("synapse")).toBe("/custom/config/synapse");
+  });
+
+  test("falls back to ~/.config/{name}", () => {
+    delete process.env.XDG_CONFIG_HOME;
+    expect(getConfigDir("synapse")).toBe(join(homedir(), ".config", "synapse"));
+  });
+});
+
+// --- expandPath ---
+
+describe("expandPath", () => {
+  test("expands ~ to homedir", () => {
+    const result = expandPath("~/foo/bar");
+    expect(result).toBe(join(homedir(), "foo/bar"));
+  });
+
+  test("leaves absolute paths unchanged", () => {
+    expect(expandPath("/usr/bin")).toBe("/usr/bin");
+  });
+
+  test("leaves relative paths unchanged", () => {
+    expect(expandPath("foo/bar")).toBe("foo/bar");
+  });
+});
+
+// --- interpolateEnvVars ---
+
+describe("interpolateEnvVars", () => {
+  test("replaces env var references", () => {
+    process.env.CORE_TEST_VAR = "hello";
+    const result = interpolateEnvVars("prefix-${CORE_TEST_VAR}-suffix");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe("prefix-hello-suffix");
+  });
+
+  test("returns err for missing env var", () => {
+    delete process.env.CORE_TEST_VAR;
+    const result = interpolateEnvVars("${CORE_TEST_VAR}");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("CORE_TEST_VAR");
+  });
+
+  test("returns string unchanged when no vars present", () => {
+    const result = interpolateEnvVars("plain string");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe("plain string");
+  });
+
+  test("ignores malformed env var references", () => {
+    const result = interpolateEnvVars("${not valid}");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe("${not valid}");
+  });
+
+  test("ignores empty braces", () => {
+    const result = interpolateEnvVars("${}");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe("${}");
+  });
+});
+
+// --- interpolateDeep ---
+
+describe("interpolateDeep", () => {
+  test("interpolates strings in nested objects", () => {
+    process.env.CORE_TEST_VAR = "world";
+    const result = interpolateDeep({
+      greeting: "hello ${CORE_TEST_VAR}",
+      nested: { value: "${CORE_TEST_VAR}" },
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual({
+        greeting: "hello world",
+        nested: { value: "world" },
+      });
+    }
+  });
+
+  test("interpolates strings in arrays", () => {
+    process.env.CORE_TEST_VAR = "item";
+    const result = interpolateDeep(["${CORE_TEST_VAR}", 42, true]);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual(["item", 42, true]);
+    }
+  });
+
+  test("passes through non-string primitives", () => {
+    const result = interpolateDeep({ num: 42, bool: true, nil: null });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual({ num: 42, bool: true, nil: null });
+    }
+  });
+
+  test("returns err on missing env var in nested value", () => {
+    delete process.env.CORE_TEST_VAR;
+    const result = interpolateDeep({ deep: { value: "${CORE_TEST_VAR}" } });
+    expect(result.ok).toBe(false);
+  });
+});
+
+// --- parsePort ---
+
+describe("parsePort", () => {
+  test("valid port returns Ok with branded Port", () => {
+    const result = parsePort("8080", "TEST");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value as number).toBe(8080);
+  });
+
+  test("port 1 is valid", () => {
+    const result = parsePort("1", "TEST");
+    expect(result.ok).toBe(true);
+  });
+
+  test("port 65535 is valid", () => {
+    const result = parsePort("65535", "TEST");
+    expect(result.ok).toBe(true);
+  });
+
+  test("port 0 is invalid", () => {
+    const result = parsePort("0", "TEST");
+    expect(result.ok).toBe(false);
+  });
+
+  test("port 65536 is invalid", () => {
+    const result = parsePort("65536", "TEST");
+    expect(result.ok).toBe(false);
+  });
+
+  test("non-numeric returns error", () => {
+    const result = parsePort("abc", "SOURCE");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("abc");
+      expect(result.error).toContain("SOURCE");
+    }
+  });
+});
+
+// --- loadJsonConfig ---
+
+describe("loadJsonConfig", () => {
+  const defaults = { host: "localhost", port: 3000 };
+
+  test("returns defaults when config file missing", () => {
+    const result = loadJsonConfig({
+      name: "test",
+      defaults,
+      configPath: join(TMP, "nonexistent.json"),
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.config).toEqual(defaults);
+      expect(result.value.source).toBe("defaults");
+    }
+  });
+
+  test("merges file config with defaults", () => {
+    const configPath = join(TMP, "config.json");
+    writeFileSync(configPath, JSON.stringify({ port: 9999 }));
+
+    const result = loadJsonConfig({ name: "test", defaults, configPath });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.config).toEqual({ host: "localhost", port: 9999 });
+      expect(result.value.source).toBe("file");
+    }
+  });
+
+  test("interpolates env vars in config file", () => {
+    process.env.CORE_TEST_VAR = "from-env";
+    const configPath = join(TMP, "config.json");
+    writeFileSync(configPath, JSON.stringify({ host: "${CORE_TEST_VAR}" }));
+
+    const result = loadJsonConfig({ name: "test", defaults, configPath });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.config.host).toBe("from-env");
+    }
+  });
+
+  test("returns err for invalid JSON", () => {
+    const configPath = join(TMP, "config.json");
+    writeFileSync(configPath, "not json{{{");
+
+    const result = loadJsonConfig({ name: "test", defaults, configPath });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("invalid JSON");
+  });
+
+  test("returns err for non-object JSON", () => {
+    const configPath = join(TMP, "config.json");
+    writeFileSync(configPath, "[1, 2, 3]");
+
+    const result = loadJsonConfig({ name: "test", defaults, configPath });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("must be a JSON object");
+  });
+
+  test("returns err for missing env var in config", () => {
+    delete process.env.CORE_TEST_VAR;
+    const configPath = join(TMP, "config.json");
+    writeFileSync(configPath, JSON.stringify({ host: "${CORE_TEST_VAR}" }));
+
+    const result = loadJsonConfig({ name: "test", defaults, configPath });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("CORE_TEST_VAR");
+  });
+});

package/test/daemon.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { DaemonManager } from "../src/daemon";
+import { createDaemonManager } from "../src/daemon";
+
+const TMP = join(import.meta.dir, ".tmp-daemon");
+
+function setup(): string {
+  if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+  mkdirSync(TMP, { recursive: true });
+  return TMP;
+}
+
+function teardown() {
+  if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+}
+
+describe("createDaemonManager", () => {
+  test("creates a manager with all methods", () => {
+    const configDir = setup();
+    try {
+      const manager = createDaemonManager({
+        name: "test",
+        configDir,
+        cliPath: "/nonexistent/cli.ts",
+      });
+      expect(typeof manager.start).toBe("function");
+      expect(typeof manager.stop).toBe("function");
+      expect(typeof manager.restart).toBe("function");
+      expect(typeof manager.status).toBe("function");
+    } finally {
+      teardown();
+    }
+  });
+
+  test("status returns not running when no PID file", async () => {
+    const configDir = setup();
+    try {
+      const manager = createDaemonManager({
+        name: "test",
+        configDir,
+        cliPath: "/nonexistent/cli.ts",
+      });
+      const status = await manager.status();
+      expect(status.running).toBe(false);
+      expect(status.pid).toBeUndefined();
+    } finally {
+      teardown();
+    }
+  });
+
+  test("status cleans up stale PID file", async () => {
+    const configDir = setup();
+    try {
+      // Write a PID that doesn't correspond to a running process
+      writeFileSync(join(configDir, "test.pid"), "999999");
+
+      const manager = createDaemonManager({
+        name: "test",
+        configDir,
+        cliPath: "/nonexistent/cli.ts",
+      });
+      const status = await manager.status();
+      expect(status.running).toBe(false);
+
+      // PID file should be cleaned up
+      expect(existsSync(join(configDir, "test.pid"))).toBe(false);
+    } finally {
+      teardown();
+    }
+  });
+
+  test("stop returns err when not running", async () => {
+    const configDir = setup();
+    try {
+      const manager = createDaemonManager({
+        name: "test",
+        configDir,
+        cliPath: "/nonexistent/cli.ts",
+      });
+      const result = await manager.stop();
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("not running");
+    } finally {
+      teardown();
+    }
+  });
+});