@aaroncql/pim-agent 0.0.1

package/src/telegram/Config.test.ts

@@ -0,0 +1,275 @@
+import { chmod, mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { Fs } from "../shared/Fs";
+import { Config, type TelegramConfig } from "./Config";
+
+const ENV_KEYS = [
+  "PIM_TELEGRAM_BOT_TOKEN",
+  "PIM_TELEGRAM_ALLOW",
+  "PIM_HOME_DIR",
+] as const;
+
+let savedEnv: Record<string, string | undefined>;
+let tmp: string;
+
+beforeEach(async () => {
+  savedEnv = {};
+  for (const k of ENV_KEYS) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+  tmp = await mkdtemp(join(tmpdir(), "pim-telegram-test-"));
+});
+
+afterEach(async () => {
+  for (const k of ENV_KEYS) {
+    if (savedEnv[k] === undefined) {
+      delete process.env[k];
+    } else {
+      process.env[k] = savedEnv[k];
+    }
+  }
+  await rm(tmp, { recursive: true, force: true });
+});
+
+describe("Config.parseArgs", () => {
+  test("parses space-separated flags", () => {
+    const cli = Config.parseArgs([
+      "--mode",
+      "telegram",
+      "--token",
+      "abc:xyz",
+      "--allow",
+      "111,222",
+      "--cwd",
+      "/work",
+      "--model",
+      "sonnet",
+      "--config-dir",
+      "/c",
+    ]);
+    expect(cli).toEqual({
+      token: "abc:xyz",
+      allow: "111,222",
+      cwd: "/work",
+      model: "sonnet",
+      configDir: "/c",
+      printConfig: false,
+    });
+  });
+
+  test("parses --key=value form", () => {
+    const cli = Config.parseArgs([
+      "--mode=telegram",
+      "--token=abc",
+      "--allow=1",
+    ]);
+    expect(cli.token).toBe("abc");
+    expect(cli.allow).toBe("1");
+  });
+
+  test("--print-config is a boolean flag", () => {
+    const cli = Config.parseArgs(["--print-config", "--token", "t"]);
+    expect(cli.printConfig).toBe(true);
+    expect(cli.token).toBe("t");
+  });
+
+  test("ignores unknown positional args and unknown flags", () => {
+    const cli = Config.parseArgs([
+      "positional",
+      "--unknown",
+      "x",
+      "--token",
+      "t",
+    ]);
+    expect(cli.token).toBe("t");
+  });
+
+  test("consumes --mode value so it does not leak into the next flag", () => {
+    const cli = Config.parseArgs(["--mode", "telegram", "--token", "t"]);
+    expect(cli.token).toBe("t");
+  });
+});
+
+describe("Config.load precedence", () => {
+  test("CLI wins over env and file", async () => {
+    process.env.PIM_TELEGRAM_BOT_TOKEN = "env-tok";
+    process.env.PIM_TELEGRAM_ALLOW = "9";
+    await Bun.write(
+      join(tmp, "config.json"),
+      JSON.stringify({ token: "file-tok", allow: [1] })
+    );
+    const cfg = await Config.load({
+      token: "cli-tok",
+      allow: "2,3",
+      configDir: tmp,
+      printConfig: false,
+    });
+    expect(cfg.token).toBe("cli-tok");
+    expect(cfg.allow).toEqual([2, 3]);
+  });
+
+  test("env wins over file when no CLI value", async () => {
+    process.env.PIM_TELEGRAM_BOT_TOKEN = "env-tok";
+    process.env.PIM_TELEGRAM_ALLOW = "9";
+    await Bun.write(
+      join(tmp, "config.json"),
+      JSON.stringify({ token: "file-tok", allow: [1] })
+    );
+    const cfg = await Config.load({
+      configDir: tmp,
+      printConfig: false,
+    });
+    expect(cfg.token).toBe("env-tok");
+    expect(cfg.allow).toEqual([9]);
+  });
+
+  test("file values used when neither CLI nor env set", async () => {
+    await Bun.write(
+      join(tmp, "config.json"),
+      JSON.stringify({ token: "file-tok", allow: [1, 2], cwd: "/from-file" })
+    );
+    const cfg = await Config.load({
+      configDir: tmp,
+      printConfig: false,
+    });
+    expect(cfg.token).toBe("file-tok");
+    expect(cfg.allow).toEqual([1, 2]);
+    expect(cfg.cwd).toBe("/from-file");
+  });
+
+  test("PIM_HOME_DIR resolves the config directory", async () => {
+    process.env.PIM_HOME_DIR = tmp;
+    process.env.PIM_TELEGRAM_BOT_TOKEN = "t";
+    const cfg = await Config.load({ printConfig: false });
+    expect(cfg.configDir).toBe(join(tmp, "telegram"));
+  });
+
+  test("throws when no token from any source", async () => {
+    await expect(
+      Config.load({ configDir: tmp, printConfig: false })
+    ).rejects.toThrow(/token required/i);
+  });
+
+  test("missing config.json is not an error", async () => {
+    const cfg = await Config.load({
+      token: "t",
+      configDir: tmp,
+      printConfig: false,
+    });
+    expect(cfg.allow).toEqual([]);
+  });
+
+  test("rejects non-numeric allow entries", async () => {
+    await expect(
+      Config.load({
+        token: "t",
+        allow: "1,abc",
+        configDir: tmp,
+        printConfig: false,
+      })
+    ).rejects.toThrow(/Invalid chat ID/);
+  });
+
+  test("trims whitespace and drops empty entries in allow", async () => {
+    const cfg = await Config.load({
+      token: "t",
+      allow: " 1 , ,2 ",
+      configDir: tmp,
+      printConfig: false,
+    });
+    expect(cfg.allow).toEqual([1, 2]);
+  });
+
+  test("accepts allow as a single number in config.json", async () => {
+    await Bun.write(
+      join(tmp, "config.json"),
+      JSON.stringify({ token: "t", allow: 12345 })
+    );
+    const cfg = await Config.load({ configDir: tmp, printConfig: false });
+    expect(cfg.allow).toEqual([12345]);
+  });
+
+  test("accepts allow as a comma-separated string in config.json", async () => {
+    await Bun.write(
+      join(tmp, "config.json"),
+      JSON.stringify({ token: "t", allow: "1, 2 ,3" })
+    );
+    const cfg = await Config.load({ configDir: tmp, printConfig: false });
+    expect(cfg.allow).toEqual([1, 2, 3]);
+  });
+
+  test("accepts allow as a mixed-type array in config.json", async () => {
+    await Bun.write(
+      join(tmp, "config.json"),
+      JSON.stringify({ token: "t", allow: [1, "2", 3] })
+    );
+    const cfg = await Config.load({ configDir: tmp, printConfig: false });
+    expect(cfg.allow).toEqual([1, 2, 3]);
+  });
+
+  test("malformed config.json surfaces a clear error", async () => {
+    await Bun.write(join(tmp, "config.json"), "{not json");
+    await expect(
+      Config.load({ token: "t", configDir: tmp, printConfig: false })
+    ).rejects.toThrow(/Failed to parse/);
+  });
+});
+
+describe("Config.save + Fs.writeAtomic", () => {
+  test("save writes a file readable by load", async () => {
+    const cfg: TelegramConfig = {
+      token: "tok",
+      allow: [1, 2],
+      cwd: "/work",
+      model: "sonnet",
+      configDir: tmp,
+    };
+    await Config.save(cfg);
+    const reloaded = await Config.load({
+      configDir: tmp,
+      printConfig: false,
+    });
+    expect(reloaded.token).toBe("tok");
+    expect(reloaded.allow).toEqual([1, 2]);
+    expect(reloaded.cwd).toBe("/work");
+    expect(reloaded.model).toBe("sonnet");
+  });
+
+  test("writeAtomic applies explicit mode", async () => {
+    const path = join(tmp, "secret.json");
+    await Fs.writeAtomic(path, "{}", 0o600);
+    const s = await stat(path);
+    expect(s.mode & 0o777).toBe(0o600);
+  });
+
+  test("writeAtomic preserves an existing file's mode when no mode is passed", async () => {
+    const path = join(tmp, "existing.json");
+    await Bun.write(path, "{}");
+    await chmod(path, 0o640);
+    await Fs.writeAtomic(path, "{}");
+    const s = await stat(path);
+    expect(s.mode & 0o777).toBe(0o640);
+  });
+
+  test("Config.save writes config.json as 0600", async () => {
+    await Config.save({
+      token: "tok",
+      allow: [],
+      cwd: "/work",
+      configDir: tmp,
+    });
+    const s = await stat(join(tmp, "config.json"));
+    expect(s.mode & 0o777).toBe(0o600);
+  });
+
+  test("writeAtomic leaves no temp files behind", async () => {
+    await Fs.writeAtomic(join(tmp, "x.json"), "{}");
+    const glob = new Bun.Glob("x.json.tmp-*");
+    const leftovers = await Array.fromAsync(glob.scan({ cwd: tmp }));
+    expect(leftovers).toEqual([]);
+  });
+});

package/src/telegram/Config.ts

@@ -0,0 +1,162 @@
+import { join } from "node:path";
+
+import { Fs } from "../shared/Fs";
+import { Paths } from "../shared/Paths";
+
+export type Cli = {
+  readonly token?: string;
+  readonly allow?: string;
+  readonly cwd?: string;
+  readonly model?: string;
+  readonly configDir?: string;
+  readonly printConfig: boolean;
+};
+
+export type TelegramConfig = {
+  readonly token: string;
+  readonly allow: ReadonlyArray<number>;
+  readonly cwd: string;
+  readonly model?: string;
+  readonly configDir: string;
+};
+
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+export type ThinkingLevelOpt = (typeof THINKING_LEVELS)[number];
+
+export const LOGS_MODES = ["off", "tool", "text", "verbose"] as const;
+export type LogsMode = (typeof LOGS_MODES)[number];
+
+export class Config {
+  public static parseArgs(args: ReadonlyArray<string>): Cli {
+    let token: string | undefined;
+    let allow: string | undefined;
+    let cwd: string | undefined;
+    let model: string | undefined;
+    let configDir: string | undefined;
+    let printConfig = false;
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i]!;
+      if (!arg.startsWith("--")) {
+        continue;
+      }
+      const eqIdx = arg.indexOf("=");
+      const key = eqIdx >= 0 ? arg.slice(0, eqIdx) : arg;
+      const inline = eqIdx >= 0 ? arg.slice(eqIdx + 1) : undefined;
+      const take = (): string | undefined => {
+        if (inline !== undefined) {
+          return inline;
+        }
+        i += 1;
+        return args[i];
+      };
+
+      switch (key) {
+        case "--token":
+          token = take();
+          break;
+        case "--allow":
+          allow = take();
+          break;
+        case "--cwd":
+          cwd = take();
+          break;
+        case "--model":
+          model = take();
+          break;
+        case "--config-dir":
+          configDir = take();
+          break;
+        case "--print-config":
+          printConfig = true;
+          break;
+        case "--mode":
+          take();
+          break;
+      }
+    }
+    return { token, allow, cwd, model, configDir, printConfig };
+  }
+
+  public static async load(cli: Cli): Promise<TelegramConfig> {
+    const configDir = cli.configDir ?? join(Paths.pimHomeDir(), "telegram");
+
+    const filePath = join(configDir, "config.json");
+    const fileConfig = await Fs.readJsonOrEmpty<Partial<TelegramConfig>>(
+      filePath,
+      {}
+    );
+
+    const token =
+      cli.token ?? process.env.PIM_TELEGRAM_BOT_TOKEN ?? fileConfig.token;
+    if (!token) {
+      throw new Error(
+        "Bot token required (set --token, PIM_TELEGRAM_BOT_TOKEN, or 'token' in config.json)"
+      );
+    }
+
+    const allowSrc = cli.allow ?? process.env.PIM_TELEGRAM_ALLOW;
+    const allow = allowSrc
+      ? Config.parseAllow(allowSrc)
+      : Config.normalizeAllow(fileConfig.allow);
+
+    const cwd = cli.cwd ?? fileConfig.cwd ?? process.cwd();
+    const model = cli.model ?? fileConfig.model;
+
+    return { token, allow, cwd, model, configDir };
+  }
+
+  public static async save(config: TelegramConfig): Promise<void> {
+    const filePath = join(config.configDir, "config.json");
+    const data = JSON.stringify(
+      {
+        token: config.token,
+        allow: config.allow,
+        cwd: config.cwd,
+        model: config.model,
+      },
+      null,
+      2
+    );
+    await Fs.writeAtomic(filePath, data, 0o600);
+  }
+
+  private static parseAllow(s: string): ReadonlyArray<number> {
+    return s
+      .split(",")
+      .map((x) => x.trim())
+      .filter((x) => x.length > 0)
+      .map((x) => {
+        const n = Number(x);
+        if (!Number.isFinite(n)) {
+          throw new Error(`Invalid chat ID in allow list: ${x}`);
+        }
+        return n;
+      });
+  }
+
+  private static normalizeAllow(value: unknown): ReadonlyArray<number> {
+    if (value === undefined || value === null) {
+      return [];
+    }
+    if (typeof value === "string") {
+      return Config.parseAllow(value);
+    }
+    if (typeof value === "number") {
+      return Config.parseAllow(String(value));
+    }
+    if (Array.isArray(value)) {
+      return Config.parseAllow(value.join(","));
+    }
+    throw new Error(
+      `Invalid 'allow' in config.json: expected number, string, or array, got ${typeof value}`
+    );
+  }
+}

package/src/telegram/Markdown.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+
+import { Markdown } from "./Markdown";
+
+describe("toHtml", () => {
+  test("escapes html-special characters in plain text", () => {
+    expect(Markdown.toHtml("a < b & c > d")).toBe("a &lt; b &amp; c &gt; d");
+  });
+
+  test("bold + italic + strike + inline code", () => {
+    expect(Markdown.toHtml("**b** *i* ~~s~~ `c`")).toBe(
+      "<b>b</b> <i>i</i> <s>s</s> <code>c</code>"
+    );
+  });
+
+  test("headings: h1 is underline+bold, others bold", () => {
+    expect(Markdown.toHtml("# H1")).toBe("<u><b>H1</b></u>");
+    expect(Markdown.toHtml("## H2")).toBe("<b>H2</b>");
+    expect(Markdown.toHtml("### H3")).toBe("<b>H3</b>");
+  });
+
+  test("fenced code block with language", () => {
+    expect(Markdown.toHtml("```ts\nconst x = 1;\n```")).toBe(
+      '<pre><code class="language-ts">const x = 1;</code></pre>'
+    );
+  });
+
+  test("fenced code block without language", () => {
+    expect(Markdown.toHtml("```\nplain\n```")).toBe("<pre>plain</pre>");
+  });
+
+  test("escapes html inside code block", () => {
+    expect(Markdown.toHtml("```\na <b> & c\n```")).toBe(
+      "<pre>a &lt;b&gt; &amp; c</pre>"
+    );
+  });
+
+  test("safe links pass through, javascript: dropped", () => {
+    expect(Markdown.toHtml("[ok](https://example.com)")).toBe(
+      '<a href="https://example.com">ok</a>'
+    );
+    expect(Markdown.toHtml("[bad](javascript:alert(1))")).toBe("bad");
+  });
+
+  test("images render as link to src", () => {
+    expect(Markdown.toHtml("![alt](https://e.com/a.png)")).toBe(
+      '<a href="https://e.com/a.png">alt</a>'
+    );
+  });
+
+  test("blockquote wraps multi-line content", () => {
+    expect(Markdown.toHtml("> a\n> b")).toBe("<blockquote>a\nb</blockquote>");
+  });
+
+  test("unordered list bullets and nested ◦", () => {
+    const out = Markdown.toHtml("- one\n- two\n  - nested\n  - also");
+    expect(out).toBe("• one\n• two\n    ◦ nested\n    ◦ also");
+  });
+
+  test("ordered list renders 1. 2. markers", () => {
+    expect(Markdown.toHtml("1. a\n2. b\n3. c")).toBe("1. a\n2. b\n3. c");
+  });
+
+  test("task list checkboxes", () => {
+    const out = Markdown.toHtml("- [x] done\n- [ ] todo");
+    expect(out).toBe("✅ done\n⬜ todo");
+  });
+
+  test("thematic break renders em-dashes", () => {
+    expect(Markdown.toHtml("a\n\n───\n\nb")).toBe("a\n\n───\n\nb");
+  });
+
+  test("collapses 3+ newlines to two", () => {
+    expect(Markdown.toHtml("a\n\n\n\nb")).toBe("a\n\nb");
+  });
+
+  test("trims leading and trailing whitespace", () => {
+    expect(Markdown.toHtml("\n\nhello\n\n")).toBe("hello");
+  });
+
+  test("table renders as vertical labeled cards", () => {
+    const md = "| Name | Score |\n| ---- | ----- |\n| Aaron | 99 |\n| Bo | 7 |";
+    expect(Markdown.toHtml(md)).toBe(
+      "───\n<b>Name</b>: Aaron\n<b>Score</b>: 99\n───\n<b>Name</b>: Bo\n<b>Score</b>: 7\n───"
+    );
+  });
+
+  test("table renders markdown formatting in cells", () => {
+    const md = "| a | b |\n| - | - |\n| **x** | `y` |";
+    const out = Markdown.toHtml(md);
+    expect(out).toContain("<b>a</b>: <b>x</b>");
+    expect(out).toContain("<b>b</b>: <code>y</code>");
+  });
+
+  test("table escapes html inside cells", () => {
+    const md = "| a | b |\n| - | - |\n| <x> | & |";
+    const out = Markdown.toHtml(md);
+    expect(out).toContain("&lt;x&gt;");
+    expect(out).toContain("&amp;");
+    expect(out).not.toContain("<pre>");
+  });
+
+  test("table surrounded by prose is rendered with both segments", () => {
+    const md = "Hello\n\n| a | b |\n| - | - |\n| 1 | 2 |\n\nDone.";
+    const out = Markdown.toHtml(md);
+    expect(out.startsWith("Hello")).toBe(true);
+    expect(out).toContain("───");
+    expect(out).toContain("<b>a</b>: 1");
+    expect(out).toContain("<b>b</b>: 2");
+    expect(out.endsWith("Done.")).toBe(true);
+  });
+
+  test("link inside emphasis nests correctly", () => {
+    expect(Markdown.toHtml("*[a](https://e.com)*")).toBe(
+      '<i><a href="https://e.com">a</a></i>'
+    );
+  });
+
+  test("paragraphs are separated by blank line", () => {
+    expect(Markdown.toHtml("one\n\ntwo")).toBe("one\n\ntwo");
+  });
+
+  test("inline html in source is escaped, never passed through", () => {
+    expect(Markdown.toHtml("hello <script>alert(1)</script>")).toContain(
+      "&lt;script&gt;"
+    );
+  });
+
+  test("empty input returns empty string", () => {
+    expect(Markdown.toHtml("")).toBe("");
+    expect(Markdown.toHtml("   \n\n  ")).toBe("");
+  });
+
+  test("escape covers all four Telegram-supported named entities", () => {
+    expect(Markdown.escape('& < > "')).toBe("&amp; &lt; &gt; &quot;");
+  });
+
+  test('link href containing " is escaped to &quot;', () => {
+    expect(Markdown.toHtml('[x](https://e.com/?q="a")')).toBe(
+      '<a href="https://e.com/?q=&quot;a&quot;">x</a>'
+    );
+  });
+});