@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/shared/goal-setup.ts

@@ -0,0 +1,336 @@
+export type GoalSetupStage = "interview" | "facts";
+
+export type GoalSetupAnswerMode =
+  | "text"
+  | "single"
+  | "multi"
+  | "single-custom"
+  | "multi-custom"
+  | "custom";
+
+export interface GoalSetupQuestionOption {
+  id: string;
+  label: string;
+  description?: string;
+}
+
+export interface GoalSetupQuestion {
+  id: string;
+  prompt: string;
+  description?: string;
+  answerMode?: GoalSetupAnswerMode;
+  recommendedAnswer?: string;
+  recommendedOptionIds?: string[];
+  options?: GoalSetupQuestionOption[];
+  required?: boolean;
+}
+
+export interface GoalSetupQuestionAnswer {
+  questionId: string;
+  selectedOptionIds: string[];
+  customAnswer: string;
+  note?: string;
+  answer: string;
+  completed: boolean;
+  skipped?: boolean;
+}
+
+export interface GoalSetupInterviewBundle {
+  stage: "interview";
+  title?: string;
+  goalSlug?: string;
+  questions: GoalSetupQuestion[];
+}
+
+export interface GoalSetupFact {
+  id: string;
+  text: string;
+  accepted: boolean;
+  removed: boolean;
+  comment?: string;
+  recommendedAutomatedVerification?: boolean;
+  automatedVerification: boolean;
+  previousText?: string;
+}
+
+export interface GoalSetupFactsBundle {
+  stage: "facts";
+  title?: string;
+  goalSlug?: string;
+  facts: GoalSetupFact[];
+  showAccepted?: boolean;
+}
+
+export type GoalSetupBundle = GoalSetupInterviewBundle | GoalSetupFactsBundle;
+
+export interface GoalSetupInterviewResult {
+  stage: "interview";
+  title?: string;
+  goalSlug?: string;
+  answers: GoalSetupQuestionAnswer[];
+}
+
+export interface GoalSetupFactResult {
+  id: string;
+  text: string;
+  accepted: boolean;
+  removed: boolean;
+  comment?: string;
+  automatedVerification: boolean;
+  recommendedAutomatedVerification?: boolean;
+}
+
+export interface GoalSetupFactsResult {
+  stage: "facts";
+  title?: string;
+  goalSlug?: string;
+  facts: GoalSetupFactResult[];
+  factsMarkdown: string;
+}
+
+export type GoalSetupResult = GoalSetupInterviewResult | GoalSetupFactsResult;
+
+function asRecord(value: unknown, context: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${context} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function normalizeId(value: unknown, fallback: string): string {
+  const raw = asString(value, fallback).trim();
+  return raw || fallback;
+}
+
+function normalizeAnswerMode(value: unknown): GoalSetupAnswerMode {
+  switch (value) {
+    case "single":
+    case "multi":
+    case "single-custom":
+    case "multi-custom":
+    case "custom":
+    case "text":
+      return value;
+    default:
+      return "text";
+  }
+}
+
+function normalizeOption(value: unknown, index: number): GoalSetupQuestionOption {
+  const item = asRecord(value, `questions[].options[${index}]`);
+  const label = asString(item.label).trim();
+  if (!label) {
+    throw new Error(`questions[].options[${index}].label is required`);
+  }
+  return {
+    id: normalizeId(item.id, `option-${index + 1}`),
+    label,
+    ...(asString(item.description).trim()
+      ? { description: asString(item.description).trim() }
+      : {}),
+  };
+}
+
+function normalizeQuestion(value: unknown, index: number): GoalSetupQuestion {
+  const item = asRecord(value, `questions[${index}]`);
+  const prompt = asString(item.prompt).trim();
+  if (!prompt) {
+    throw new Error(`questions[${index}].prompt is required`);
+  }
+  const options = Array.isArray(item.options)
+    ? item.options.map(normalizeOption)
+    : undefined;
+
+  const recommendedOptionIds = Array.isArray(item.recommendedOptionIds)
+    ? (item.recommendedOptionIds as unknown[]).filter((id): id is string => typeof id === 'string')
+    : undefined;
+
+  return {
+    id: normalizeId(item.id, `question-${index + 1}`),
+    prompt,
+    ...(asString(item.description).trim()
+      ? { description: asString(item.description).trim() }
+      : {}),
+    answerMode: normalizeAnswerMode(item.answerMode),
+    ...(asString(item.recommendedAnswer).trim()
+      ? { recommendedAnswer: asString(item.recommendedAnswer).trim() }
+      : {}),
+    ...(recommendedOptionIds && recommendedOptionIds.length > 0
+      ? { recommendedOptionIds }
+      : {}),
+    ...(options && options.length > 0 ? { options } : {}),
+    required: asBoolean(item.required, true),
+  };
+}
+
+function normalizeFact(value: unknown, index: number): GoalSetupFact {
+  const item = asRecord(value, `facts[${index}]`);
+  const text = asString(item.text).trim();
+  if (!text) {
+    throw new Error(`facts[${index}].text is required`);
+  }
+  const recommended = asBoolean(item.recommendedAutomatedVerification, false);
+  return {
+    id: normalizeId(item.id, `fact-${index + 1}`),
+    text,
+    accepted: asBoolean(item.accepted, false),
+    removed: asBoolean(item.removed, false),
+    ...(asString(item.comment).trim()
+      ? { comment: asString(item.comment).trim() }
+      : {}),
+    recommendedAutomatedVerification: recommended,
+    automatedVerification: asBoolean(item.automatedVerification, recommended),
+    ...(asString(item.previousText).trim()
+      ? { previousText: asString(item.previousText).trim() }
+      : {}),
+  };
+}
+
+export function normalizeInterviewBundle(value: unknown): GoalSetupInterviewBundle {
+  const raw = asRecord(value, "goal setup interview bundle");
+  if (!Array.isArray(raw.questions) || raw.questions.length === 0) {
+    throw new Error("interview bundle requires at least one question");
+  }
+  return {
+    stage: "interview",
+    ...(asString(raw.title).trim() ? { title: asString(raw.title).trim() } : {}),
+    ...(asString(raw.goalSlug).trim()
+      ? { goalSlug: asString(raw.goalSlug).trim() }
+      : {}),
+    questions: raw.questions.map(normalizeQuestion),
+  };
+}
+
+export function normalizeFactsBundle(value: unknown): GoalSetupFactsBundle {
+  const raw = asRecord(value, "goal setup facts bundle");
+  if (!Array.isArray(raw.facts)) {
+    throw new Error("facts bundle requires a facts array");
+  }
+  return {
+    stage: "facts",
+    ...(asString(raw.title).trim() ? { title: asString(raw.title).trim() } : {}),
+    ...(asString(raw.goalSlug).trim()
+      ? { goalSlug: asString(raw.goalSlug).trim() }
+      : {}),
+    facts: raw.facts.map(normalizeFact),
+    showAccepted: asBoolean(raw.showAccepted, false),
+  };
+}
+
+export function normalizeGoalSetupBundle(
+  value: unknown,
+  expectedStage?: GoalSetupStage
+): GoalSetupBundle {
+  const raw = asRecord(value, "goal setup bundle");
+  const stage = expectedStage ?? raw.stage;
+  if (stage === "interview") return normalizeInterviewBundle(raw);
+  if (stage === "facts") return normalizeFactsBundle(raw);
+  throw new Error("goal setup bundle stage must be interview or facts");
+}
+
+export function hasQuestionAnswer(answer: GoalSetupQuestionAnswer): boolean {
+  return (
+    answer.selectedOptionIds.length > 0 ||
+    answer.customAnswer.trim().length > 0 ||
+    answer.answer.trim().length > 0
+  );
+}
+
+export function createInterviewResult(
+  bundle: GoalSetupInterviewBundle,
+  answers: GoalSetupQuestionAnswer[]
+): GoalSetupInterviewResult {
+  const byId = new Map(answers.map((answer) => [answer.questionId, answer]));
+  return {
+    stage: "interview",
+    title: bundle.title,
+    goalSlug: bundle.goalSlug,
+    answers: bundle.questions.map((question) => {
+      const answer = byId.get(question.id);
+      const normalized: GoalSetupQuestionAnswer = {
+        questionId: question.id,
+        selectedOptionIds: Array.isArray(answer?.selectedOptionIds)
+          ? answer!.selectedOptionIds
+          : [],
+        customAnswer: asString(answer?.customAnswer),
+        ...(asString(answer?.note).trim()
+          ? { note: asString(answer?.note).trim() }
+          : {}),
+        answer: asString(answer?.answer),
+        completed: asBoolean(answer?.completed, false),
+      };
+      const completed = normalized.completed || hasQuestionAnswer(normalized);
+      const skipped = asBoolean(answer?.skipped, false) && !completed;
+      return {
+        ...normalized,
+        completed,
+        ...(skipped ? { skipped: true } : {}),
+      };
+    }),
+  };
+}
+
+export function filterReviewableFacts(bundle: GoalSetupFactsBundle): GoalSetupFact[] {
+  if (bundle.showAccepted) return bundle.facts;
+  return bundle.facts.filter((fact) => !fact.accepted);
+}
+
+export function createFactsResult(
+  bundle: GoalSetupFactsBundle,
+  facts: GoalSetupFactResult[]
+): GoalSetupFactsResult {
+  const byId = new Map(facts.map((fact) => [fact.id, fact]));
+  const merged = bundle.facts.map((fact) => {
+    const next = byId.get(fact.id);
+    const removed = asBoolean(next?.removed, fact.removed);
+    const text = asString(next?.text, fact.text).trim();
+    if (!removed && !text) {
+      throw new Error(`Fact "${fact.id}" text cannot be empty; edit it or remove the fact.`);
+    }
+    const comment = (next && Object.prototype.hasOwnProperty.call(next, "comment")
+      ? asString(next.comment)
+      : asString(fact.comment)
+    ).trim();
+    return {
+      id: fact.id,
+      text: text || fact.text,
+      accepted: asBoolean(next?.accepted, fact.accepted),
+      removed,
+      ...(comment ? { comment } : {}),
+      automatedVerification: asBoolean(
+        next?.automatedVerification,
+        fact.automatedVerification
+      ),
+      recommendedAutomatedVerification:
+        next?.recommendedAutomatedVerification ??
+        fact.recommendedAutomatedVerification,
+    };
+  });
+
+  return {
+    stage: "facts",
+    title: bundle.title,
+    goalSlug: bundle.goalSlug,
+    facts: merged,
+    factsMarkdown: factsResultToMarkdown(merged),
+  };
+}
+
+export function factsResultToMarkdown(facts: GoalSetupFactResult[]): string {
+  const accepted = facts.filter((fact) => fact.accepted && !fact.removed);
+  if (accepted.length === 0) return "# Facts\n\nNo accepted facts.";
+
+  const lines = ["# Facts", ""];
+  for (const fact of accepted) {
+    lines.push(`- ${fact.text}`);
+  }
+  return lines.join("\n");
+}

package/3p/pi-plannotator/packages/shared/html-to-markdown.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { htmlToMarkdown } from "./html-to-markdown";
+
+describe("htmlToMarkdown", () => {
+  test("converts basic HTML to markdown", () => {
+    const md = htmlToMarkdown("<h1>Hello</h1><p>World</p>");
+    expect(md).toContain("# Hello");
+    expect(md).toContain("World");
+  });
+
+  test("converts tables with explicit thead", () => {
+    const html = "<table><thead><tr><th>A</th><th>B</th></tr></thead><tbody><tr><td>1</td><td>2</td></tr></tbody></table>";
+    const md = htmlToMarkdown(html);
+    expect(md).toContain("| A");
+    expect(md).toContain("| ---");
+    expect(md).toContain("| 1");
+  });
+
+  test("converts tables WITHOUT thead (common HTML pattern)", () => {
+    const html = "<table><tr><th>Name</th><th>Value</th></tr><tr><td>foo</td><td>bar</td></tr></table>";
+    const md = htmlToMarkdown(html);
+    expect(md).toContain("| Name");
+    expect(md).toContain("| ---");
+    expect(md).toContain("| foo");
+  });
+
+  test("strips script, style, and noscript tags", () => {
+    const html = '<p>Visible</p><script>alert("xss")</script><style>.x{}</style><noscript>Hidden</noscript>';
+    const md = htmlToMarkdown(html);
+    expect(md).toContain("Visible");
+    expect(md).not.toContain("alert");
+    expect(md).not.toContain(".x{}");
+    expect(md).not.toContain("Hidden");
+  });
+
+  test("converts strikethrough (GFM)", () => {
+    const md = htmlToMarkdown("<p>This is <del>deleted</del> text</p>");
+    expect(md).toContain("~deleted~");
+  });
+
+  test("preserves code blocks as fenced markdown", () => {
+    const md = htmlToMarkdown('<pre><code>const x = 1;</code></pre>');
+    expect(md).toContain("```");
+    expect(md).toContain("const x = 1;");
+  });
+
+  test("converts links", () => {
+    const md = htmlToMarkdown('<a href="https://example.com">Click</a>');
+    expect(md).toContain("[Click](https://example.com)");
+  });
+
+  test("preserves dangerous link hrefs (sanitization is in the renderer, not here)", () => {
+    const md = htmlToMarkdown('<a href="javascript:alert(1)">XSS</a>');
+    // Turndown preserves the link — the UI renderer blocks it
+    expect(md).toContain("javascript:");
+  });
+
+  test("handles empty HTML gracefully", () => {
+    expect(htmlToMarkdown("")).toBe("");
+    expect(htmlToMarkdown("<html><body></body></html>")).toBe("");
+  });
+});

package/3p/pi-plannotator/packages/shared/html-to-markdown.ts

@@ -0,0 +1,32 @@
+/**
+ * HTML-to-Markdown conversion via Turndown.
+ *
+ * Shared between the CLI (single HTML file / URL) and the server
+ * (on-demand conversion for HTML files in folder mode).
+ */
+
+import TurndownService from "turndown";
+// @ts-expect-error — @joplin/turndown-plugin-gfm ships JS only, no .d.ts (see declarations.d.ts for local types)
+import { gfm } from "@joplin/turndown-plugin-gfm";
+
+const td = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  bulletListMarker: "-",
+});
+
+td.use(gfm);
+
+// Strip <style> and <script> tags entirely (Turndown keeps unrecognised
+// tags as blank by default, but their text content can leak through).
+td.remove(["style", "script", "noscript"]);
+
+/**
+ * Convert an HTML string to Markdown.
+ *
+ * Uses a module-level TurndownService singleton (stateless, safe to reuse).
+ * GFM tables, strikethrough, and task lists are supported via turndown-plugin-gfm.
+ */
+export function htmlToMarkdown(html: string): string {
+  return td.turndown(html);
+}

package/3p/pi-plannotator/packages/shared/improvement-hooks.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for improvement hook reader.
+ *
+ * Run: bun test packages/shared/improvement-hooks.test.ts
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+// We need to override the base dirs used by readImprovementHook.
+// Since the module uses homedir() at import time, we mock it via
+// a test harness that sets HOME to a temp directory.
+
+const TEST_HOME = join(tmpdir(), `improvement-hooks-test-${Date.now()}`);
+const NEW_BASE = join(TEST_HOME, ".plannotator", "hooks");
+const LEGACY_BASE = join(TEST_HOME, ".plannotator");
+const HOOK_RELATIVE = "compound/enterplanmode-improve-hook.txt";
+
+function setupTestHome() {
+  mkdirSync(join(NEW_BASE, "compound"), { recursive: true });
+  mkdirSync(join(LEGACY_BASE, "compound"), { recursive: true });
+}
+
+function cleanTestHome() {
+  if (existsSync(TEST_HOME)) {
+    rmSync(TEST_HOME, { recursive: true, force: true });
+  }
+}
+
+// Since the module reads homedir() at import time, we need to
+// re-import with HOME overridden. Use a helper that spawns a
+// small inline script to test each scenario in isolation.
+async function runScenario(setup: {
+  newPathContent?: string | null;
+  legacyPathContent?: string | null;
+}): Promise<{ content: string; filePath: string } | null> {
+  setupTestHome();
+
+  const newPath = join(NEW_BASE, HOOK_RELATIVE);
+  const legacyPath = join(LEGACY_BASE, HOOK_RELATIVE);
+
+  if (setup.newPathContent !== undefined && setup.newPathContent !== null) {
+    writeFileSync(newPath, setup.newPathContent);
+  }
+  if (setup.legacyPathContent !== undefined && setup.legacyPathContent !== null) {
+    writeFileSync(legacyPath, setup.legacyPathContent);
+  }
+
+  // Run in a subprocess with HOME overridden so homedir() returns TEST_HOME
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "-e",
+      `
+      import { readImprovementHook } from "./packages/shared/improvement-hooks";
+      const result = readImprovementHook("enterplanmode-improve");
+      console.log(JSON.stringify(result));
+    `,
+    ],
+    {
+      env: { ...process.env, HOME: TEST_HOME },
+      cwd: join(import.meta.dir, "../.."),
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+  );
+
+  const stdout = await new Response(proc.stdout).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`Subprocess failed (exit ${exitCode}): ${stderr}`);
+  }
+
+  const parsed = JSON.parse(stdout.trim());
+  return parsed;
+}
+
+describe("readImprovementHook", () => {
+  beforeEach(setupTestHome);
+  afterEach(cleanTestHome);
+
+  test("returns content from new path when file exists", async () => {
+    const result = await runScenario({
+      newPathContent: "Focus on error handling",
+    });
+    expect(result).not.toBeNull();
+    expect(result!.content).toBe("Focus on error handling");
+    expect(result!.filePath).toContain(".plannotator/hooks/compound/");
+  });
+
+  test("new path wins over legacy path", async () => {
+    const result = await runScenario({
+      newPathContent: "New instructions",
+      legacyPathContent: "Old instructions",
+    });
+    expect(result).not.toBeNull();
+    expect(result!.content).toBe("New instructions");
+    expect(result!.filePath).toContain(".plannotator/hooks/compound/");
+  });
+
+  test("falls back to legacy path when new path is absent", async () => {
+    const result = await runScenario({
+      legacyPathContent: "Legacy instructions",
+    });
+    expect(result).not.toBeNull();
+    expect(result!.content).toBe("Legacy instructions");
+    expect(result!.filePath).toContain(".plannotator/compound/");
+    expect(result!.filePath).not.toContain(".plannotator/hooks/");
+  });
+
+  test("returns null when new path exists but is empty (no legacy fallback)", async () => {
+    const result = await runScenario({
+      newPathContent: "",
+      legacyPathContent: "Legacy instructions",
+    });
+    expect(result).toBeNull();
+  });
+
+  test("returns null when no files exist", async () => {
+    const result = await runScenario({});
+    expect(result).toBeNull();
+  });
+
+  test("returns null when new path is whitespace-only (no legacy fallback)", async () => {
+    const result = await runScenario({
+      newPathContent: "   \n  \n  ",
+      legacyPathContent: "Legacy instructions",
+    });
+    expect(result).toBeNull();
+  });
+});

package/3p/pi-plannotator/packages/shared/improvement-hooks.ts

@@ -0,0 +1,115 @@
+/**
+ * Improvement Hook Reader
+ *
+ * Reads improvement hook files from ~/.plannotator/hooks/.
+ * Falls back to the legacy path (~/.plannotator/) when the new-path
+ * file is absent, for compatibility with files written before the
+ * path migration. If the new-path file exists but is invalid (empty,
+ * oversized, not a regular file), the legacy path is NOT consulted —
+ * this prevents resurrecting stale instructions.
+ *
+ * Runtime-agnostic: uses only node:fs, node:path, node:os.
+ *
+ * Security model:
+ * - Hardcoded base paths (no user input determines file path)
+ * - KNOWN_HOOKS allowlist (only pre-registered relative paths)
+ * - Size cap to prevent runaway context injection
+ * - Same trust model as ~/.plannotator/config.json
+ */
+
+import { join } from "path";
+import { readFileSync, statSync } from "fs";
+import { getPlannotatorDataDir } from "./data-dir";
+
+const DATA_DIR = getPlannotatorDataDir();
+
+/** Hooks subdirectory (preferred location) */
+const HOOKS_BASE_DIR = join(DATA_DIR, "hooks");
+
+/** Fallback: hooks placed directly in the data dir (pre-hooks-subdir layout) */
+const LEGACY_BASE_DIR = DATA_DIR;
+
+/** Maximum file size to read (50 KB) */
+const MAX_FILE_SIZE = 50 * 1024;
+
+/**
+ * Known improvement hook file paths, keyed by hook name.
+ * `path` is relative to HOOKS_BASE_DIR (~/.plannotator/hooks/).
+ * `legacyPath` is relative to LEGACY_BASE_DIR (~/.plannotator/).
+ */
+const KNOWN_HOOKS = {
+  "enterplanmode-improve": {
+    path: "compound/enterplanmode-improve-hook.txt",
+    legacyPath: "compound/enterplanmode-improve-hook.txt",
+  },
+} as const;
+
+export type ImprovementHookName = keyof typeof KNOWN_HOOKS;
+
+export function getImprovementHookExpectedPath(
+  hookName: ImprovementHookName,
+): string | null {
+  const entry = KNOWN_HOOKS[hookName];
+  if (!entry) return null;
+  return join(HOOKS_BASE_DIR, entry.path);
+}
+
+export interface ImprovementHookResult {
+  content: string;
+  hookName: ImprovementHookName;
+  filePath: string;
+}
+
+/** Check whether a path exists on disk (any file type). */
+function fileExists(path: string): boolean {
+  try {
+    statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Validate and read a hook file. Returns the result, or null if invalid. */
+function tryReadHookFile(
+  filePath: string,
+  hookName: ImprovementHookName,
+): ImprovementHookResult | null {
+  try {
+    const stat = statSync(filePath);
+    if (!stat.isFile() || stat.size === 0 || stat.size > MAX_FILE_SIZE) return null;
+
+    const content = readFileSync(filePath, "utf-8").trim();
+    if (!content) return null;
+
+    return { content, hookName, filePath };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read an improvement hook file by name.
+ *
+ * Lookup order:
+ * 1. New path (HOOKS_BASE_DIR + path). If it exists and validates, return it.
+ * 2. If the new path exists but is invalid (empty, oversized, etc.), return null.
+ * 3. Only if the new path does not exist, try the legacy path (LEGACY_BASE_DIR + legacyPath).
+ */
+export function readImprovementHook(
+  hookName: ImprovementHookName,
+): ImprovementHookResult | null {
+  const entry = KNOWN_HOOKS[hookName];
+  if (!entry) return null;
+
+  const newPath = join(HOOKS_BASE_DIR, entry.path);
+
+  // New path exists — use it exclusively (even if invalid)
+  if (fileExists(newPath)) {
+    return tryReadHookFile(newPath, hookName);
+  }
+
+  // New path absent — fall back to legacy path
+  const legacyFilePath = join(LEGACY_BASE_DIR, entry.legacyPath);
+  return tryReadHookFile(legacyFilePath, hookName);
+}