@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/shared/annotate-args.ts

@@ -0,0 +1,107 @@
+/**
+ * Parse CLI-style args arriving as a single whitespace-delimited string.
+ *
+ * Extracts known annotate flags from the remainder, which is treated as the
+ * target path. Leading `@` is
+ * stripped via the shared at-reference helper — reference-mode is primary.
+ * Scoped-package-style literal `@` paths are handled by a fallback that the
+ * downstream resolver opts into (see at-reference.ts).
+ *
+ * Used by the OpenCode plugin and Pi extension, where the whole args string
+ * arrives pre-joined from the harness slash-command dispatcher. The Claude
+ * Code binary parses argv directly with indexOf/splice and does not use
+ * this helper.
+ *
+ * Implementation: walks the raw string once, preserving whitespace runs and
+ * non-whitespace tokens as separate segments. Only known flag tokens
+ * (whole-word match) plus one adjacent whitespace run are removed.
+ * This keeps double-spaces and tabs inside file paths intact — which
+ * matches the pre-PR behavior on `main`, where OpenCode and Pi passed
+ * the raw args string straight through to the filesystem resolver.
+ *
+ * Remaining edge: if a path literally contains a known flag as a standalone
+ * whitespace-separated token (e.g. `"Feature --gate spec.md"`), that token
+ * is stripped. Supporting this would need shell-style quoting, which isn't
+ * worth the complexity for a vanishingly rare naming pattern.
+ */
+
+import { stripAtPrefix } from "./at-reference";
+import { stripWrappingQuotes } from "./resolve-file";
+
+export interface ParsedAnnotateArgs {
+  /**
+   * Primary resolution path with any leading `@` stripped (reference-mode
+   * convention). Most call sites should use this directly.
+   */
+  filePath: string;
+  /**
+   * Raw path with the `@` prefix preserved (if the user supplied one).
+   * Callers that want the literal-`@` fallback for scoped-package-style
+   * paths pair this with `resolveAtReference` from at-reference.ts.
+   */
+  rawFilePath: string;
+  gate: boolean;
+  json: boolean;
+  hook: boolean;
+  renderHtml: boolean;
+  noJina: boolean;
+}
+
+type Segment = { type: "ws" | "tok"; text: string };
+
+const FLAG_MAP = {
+  "--gate": "gate",
+  "--json": "json",
+  "--hook": "hook",
+  "--render-html": "renderHtml",
+  "--no-jina": "noJina",
+} as const satisfies Record<string, keyof Omit<ParsedAnnotateArgs, "filePath" | "rawFilePath">>;
+
+export function parseAnnotateArgs(raw: string): ParsedAnnotateArgs {
+  const s = (raw ?? "").trim();
+  const flags = { gate: false, json: false, hook: false, renderHtml: false, noJina: false };
+
+  const segments: Segment[] = [];
+  for (let i = 0; i < s.length;) {
+    const isWs = /\s/.test(s[i]);
+    const start = i;
+    while (i < s.length && /\s/.test(s[i]) === isWs) i++;
+    segments.push({ type: isWs ? "ws" : "tok", text: s.slice(start, i) });
+  }
+
+  const keep = segments.map(() => true);
+  for (let j = 0; j < segments.length; j++) {
+    const seg = segments[j];
+    if (seg.type !== "tok") continue;
+    const key = FLAG_MAP[seg.text as keyof typeof FLAG_MAP];
+    if (!key) continue;
+
+    flags[key] = true;
+    keep[j] = false;
+
+    // Drop one adjacent whitespace run so removed flags don't leave dangling
+    // spaces. Prefer trailing whitespace; fall back to leading if at the end.
+    if (j + 1 < segments.length && segments[j + 1].type === "ws") {
+      keep[j + 1] = false;
+    } else if (j > 0 && segments[j - 1].type === "ws") {
+      keep[j - 1] = false;
+    }
+  }
+
+  // Trim covers the case where two adjacent flags (`... --gate --json`)
+  // both claim the single whitespace between them, leaving a trailing space
+  // after the kept token. Wrapping quotes come from OpenCode/Pi users who
+  // quote paths with spaces (shell muscle memory); strip them here so
+  // downstream callers never see tokenization artifacts.
+  const rawFilePath = stripWrappingQuotes(
+    segments
+      .filter((_, j) => keep[j])
+      .map((seg) => seg.text)
+      .join("")
+      .trim(),
+  );
+
+  if (flags.hook) flags.gate = true;
+
+  return { filePath: stripAtPrefix(rawFilePath), rawFilePath, ...flags };
+}

package/3p/pi-plannotator/packages/shared/at-reference.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from "bun:test";
+import { stripAtPrefix, resolveAtReference } from "./at-reference";
+
+// The `@foo.md` convention — popularised by Claude Code but supported by
+// several harnesses — treats `@` as a reference marker, not part of the
+// filename. These helpers exist so every harness strips the same way and
+// optionally falls back to the literal path for scoped-package-style names.
+
+describe("stripAtPrefix", () => {
+  test("removes a single leading @", () => {
+    expect(stripAtPrefix("@foo.md")).toBe("foo.md");
+  });
+
+  test("removes only one @ (does not recurse)", () => {
+    expect(stripAtPrefix("@@foo.md")).toBe("@foo.md");
+  });
+
+  test("leaves paths without @ unchanged", () => {
+    expect(stripAtPrefix("foo.md")).toBe("foo.md");
+  });
+
+  test("leaves @ that is not at the start unchanged", () => {
+    expect(stripAtPrefix("dir/@foo.md")).toBe("dir/@foo.md");
+  });
+
+  test("strips @ from scoped-package-style paths", () => {
+    expect(stripAtPrefix("@scope/pkg/README.md")).toBe("scope/pkg/README.md");
+  });
+
+  test("handles empty string", () => {
+    expect(stripAtPrefix("")).toBe("");
+  });
+
+  // Wrapping quotes come from harnesses that tokenize on whitespace (OpenCode,
+  // Pi). Users have to quote paths with spaces: `"@My Notes.md"`. Without
+  // unwrapping the quotes first, stripAtPrefix would never see the `@`.
+  test("strips wrapping double quotes before stripping @", () => {
+    expect(stripAtPrefix(`"@foo.md"`)).toBe("foo.md");
+  });
+
+  test("strips wrapping single quotes before stripping @", () => {
+    expect(stripAtPrefix(`'@foo.md'`)).toBe("foo.md");
+  });
+
+  test("strips wrapping quotes around a path with spaces", () => {
+    expect(stripAtPrefix(`"@My Notes.md"`)).toBe("My Notes.md");
+  });
+
+  test("strips wrapping quotes when no @ present", () => {
+    expect(stripAtPrefix(`"foo.md"`)).toBe("foo.md");
+  });
+
+  test("leaves mismatched quotes alone (not wrapping)", () => {
+    expect(stripAtPrefix(`"@foo.md`)).toBe(`"@foo.md`);
+    expect(stripAtPrefix(`@foo.md"`)).toBe(`foo.md"`);
+  });
+});
+
+describe("resolveAtReference", () => {
+  // Primary behavior: stripped form wins if it resolves.
+  test("returns the stripped path when it resolves", () => {
+    const exists = (p: string) => p === "foo.md";
+    expect(resolveAtReference("@foo.md", exists)).toBe("foo.md");
+  });
+
+  // Fallback: literal path used only when stripped form doesn't resolve.
+  test("falls back to the literal path when only that resolves", () => {
+    const exists = (p: string) => p === "@scope/pkg/README.md";
+    expect(resolveAtReference("@scope/pkg/README.md", exists)).toBe("@scope/pkg/README.md");
+  });
+
+  // When BOTH resolve, stripped form wins (reference-mode primacy).
+  test("prefers the stripped path when both resolve (reference wins)", () => {
+    const exists = (_p: string) => true;
+    expect(resolveAtReference("@foo.md", exists)).toBe("foo.md");
+  });
+
+  // Returns null when neither candidate resolves — caller handles the error.
+  test("returns null when neither candidate resolves", () => {
+    const exists = (_p: string) => false;
+    expect(resolveAtReference("@nope.md", exists)).toBeNull();
+  });
+
+  // Inputs without @ have no fallback, just a single existence check.
+  test("handles non-@ inputs with a single check", () => {
+    let calls = 0;
+    const exists = (p: string) => { calls++; return p === "plain.md"; };
+    expect(resolveAtReference("plain.md", exists)).toBe("plain.md");
+    expect(calls).toBe(1);
+  });
+
+  // Non-@ input that doesn't resolve returns null without a retry.
+  test("returns null for non-@ input that doesn't resolve", () => {
+    let calls = 0;
+    const exists = (_p: string) => { calls++; return false; };
+    expect(resolveAtReference("missing.md", exists)).toBeNull();
+    expect(calls).toBe(1);
+  });
+});

package/3p/pi-plannotator/packages/shared/at-reference.ts

@@ -0,0 +1,52 @@
+/**
+ * `@`-reference handling for user-provided paths.
+ *
+ * Several agent harnesses (Claude Code, OpenCode, Pi) let users reference
+ * files with an `@` prefix, e.g. `@README.md`. The `@` is the team's
+ * reference marker, not part of the filename. Stripping it is the primary
+ * resolution path — that's the common case and it's supported first-class.
+ *
+ * The secondary path handles scoped-package-style names like
+ * `@scope/pkg/README.md`: if the stripped form doesn't resolve, fall back
+ * to the literal form so those paths still open.
+ *
+ * Both functions are pure and take any filesystem-ish predicate via a
+ * callback, so they're trivial to unit-test without stubbing anything.
+ */
+
+import { stripWrappingQuotes } from "./resolve-file";
+
+/**
+ * Normalize a user-typed path reference by unwrapping matching `"..."` or
+ * `'...'` quotes and removing a single leading `@`. Quotes come from
+ * harnesses that tokenize on whitespace (OpenCode, Pi), where paths
+ * containing spaces have to be quoted. The quote-stripping has to run
+ * first so the `@` check sees the real first character.
+ *
+ * Non-`@` inputs are returned unchanged except for quote unwrapping.
+ * Does not recurse: `@@foo` becomes `@foo`, not `foo`.
+ */
+export function stripAtPrefix(input: string): string {
+  const unquoted = stripWrappingQuotes(input);
+  return unquoted.startsWith("@") ? unquoted.slice(1) : unquoted;
+}
+
+/**
+ * Resolve an `@`-prefixed user input by trying the stripped form first
+ * (reference mode, primary) and falling back to the literal form if the
+ * stripped form doesn't resolve. Returns the candidate that resolves, or
+ * null if neither does.
+ *
+ * `exists` defines what "resolves" means — use `existsSync` for a bare
+ * filesystem check, or wrap `resolveMarkdownFile` / `statSync` for richer
+ * predicates. The helper itself is filesystem-agnostic.
+ */
+export function resolveAtReference(
+  input: string,
+  exists: (candidate: string) => boolean,
+): string | null {
+  const stripped = stripAtPrefix(input);
+  if (exists(stripped)) return stripped;
+  if (stripped !== input && exists(input)) return input;
+  return null;
+}

package/3p/pi-plannotator/packages/shared/checklist.ts

@@ -0,0 +1,52 @@
+/**
+ * Checklist parsing and progress tracking utilities.
+ *
+ * Shared between Pi extension and OpenCode plugin for plan execution tracking.
+ */
+
+export interface ChecklistItem {
+  /** 1-based step number, compatible with markCompletedSteps/extractDoneSteps. */
+  step: number;
+  text: string;
+  completed: boolean;
+}
+
+/**
+ * Parse standard markdown checkboxes from file content.
+ *
+ * Matches lines like:
+ *   - [ ] Step description
+ *   - [x] Completed step
+ *   * [ ] Alternative bullet
+ */
+export function parseChecklist(content: string): ChecklistItem[] {
+  const items: ChecklistItem[] = [];
+  const pattern = /^[-*]\s*\[([ xX])\]\s+(.+)$/gm;
+
+  for (const match of content.matchAll(pattern)) {
+    const completed = match[1] !== " ";
+    const text = match[2].trim();
+    if (text.length > 0) {
+      items.push({ step: items.length + 1, text, completed });
+    }
+  }
+  return items;
+}
+
+export function extractDoneSteps(message: string): number[] {
+  const steps: number[] = [];
+  for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
+    const step = Number(match[1]);
+    if (Number.isFinite(step)) steps.push(step);
+  }
+  return steps;
+}
+
+export function markCompletedSteps(text: string, items: ChecklistItem[]): number {
+  const doneSteps = extractDoneSteps(text);
+  for (const step of doneSteps) {
+    const item = items.find((t) => t.step === step);
+    if (item) item.completed = true;
+  }
+  return doneSteps.length;
+}

package/3p/pi-plannotator/packages/shared/code-file.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  isCodeFilePath,
+  isCodeFilePathStrict,
+  isPlausibleCodeFilePath,
+  CODE_PATH_BARE_REGEX,
+} from './code-file';
+
+describe('isCodeFilePath', () => {
+  test('matches common extensions', () => {
+    expect(isCodeFilePath('button.tsx')).toBe(true);
+    expect(isCodeFilePath('utils.ts')).toBe(true);
+    expect(isCodeFilePath('main.py')).toBe(true);
+    expect(isCodeFilePath('lib.rs')).toBe(true);
+    expect(isCodeFilePath('config.json')).toBe(true);
+    expect(isCodeFilePath('styles.css')).toBe(true);
+  });
+
+  test('matches paths with directories', () => {
+    expect(isCodeFilePath('src/components/Button.tsx')).toBe(true);
+    expect(isCodeFilePath('./utils/helpers.ts')).toBe(true);
+    expect(isCodeFilePath('../lib/main.py')).toBe(true);
+  });
+
+  test('matches special filenames', () => {
+    expect(isCodeFilePath('Dockerfile')).toBe(true);
+    expect(isCodeFilePath('Makefile')).toBe(true);
+    expect(isCodeFilePath('path/to/Dockerfile')).toBe(true);
+  });
+
+  test('strips hash fragments', () => {
+    expect(isCodeFilePath('src/foo.ts#L42')).toBe(true);
+  });
+
+  test('rejects URLs', () => {
+    expect(isCodeFilePath('https://github.com/foo.ts')).toBe(false);
+    expect(isCodeFilePath('http://example.com/main.py')).toBe(false);
+  });
+
+  test('rejects non-code files', () => {
+    expect(isCodeFilePath('.env')).toBe(false);
+    expect(isCodeFilePath('readme.txt')).toBe(false);
+    expect(isCodeFilePath('npm install')).toBe(false);
+  });
+});
+
+describe('isCodeFilePathStrict', () => {
+  test('requires a / separator', () => {
+    expect(isCodeFilePathStrict('button.tsx')).toBe(false);
+    expect(isCodeFilePathStrict('Dockerfile')).toBe(false);
+    expect(isCodeFilePathStrict('package.json')).toBe(false);
+  });
+
+  test('matches paths with directories', () => {
+    expect(isCodeFilePathStrict('src/components/Button.tsx')).toBe(true);
+    expect(isCodeFilePathStrict('./utils/helpers.ts')).toBe(true);
+    expect(isCodeFilePathStrict('../lib/main.py')).toBe(true);
+    expect(isCodeFilePathStrict('path/to/Makefile')).toBe(true);
+  });
+
+  test('rejects URLs even with /', () => {
+    expect(isCodeFilePathStrict('https://github.com/foo.ts')).toBe(false);
+  });
+
+  test('rejects non-code paths with /', () => {
+    expect(isCodeFilePathStrict('path/to/readme.txt')).toBe(false);
+    expect(isCodeFilePathStrict('some/dir/.env')).toBe(false);
+  });
+
+  test('rejects shape-implausible bare prose', () => {
+    expect(isCodeFilePathStrict('packages/ui/{a,b}.ts')).toBe(false);
+  });
+});
+
+describe('isPlausibleCodeFilePath', () => {
+  test('accepts plain code paths', () => {
+    expect(isPlausibleCodeFilePath('packages/editor/App.tsx')).toBe(true);
+    expect(isPlausibleCodeFilePath('foo.ts')).toBe(true);
+  });
+
+  test('accepts Next.js dynamic routes', () => {
+    expect(isPlausibleCodeFilePath('app/[slug]/page.tsx')).toBe(true);
+    expect(isPlausibleCodeFilePath('app/[...rest]/page.tsx')).toBe(true);
+  });
+
+  test('rejects shell brace expansion', () => {
+    expect(isPlausibleCodeFilePath('packages/ui/{a,b,c}.ts')).toBe(false);
+  });
+
+  test('rejects glob wildcards', () => {
+    expect(isPlausibleCodeFilePath('src/*.ts')).toBe(false);
+    expect(isPlausibleCodeFilePath('src/foo?.ts')).toBe(false);
+  });
+
+  test('rejects whitespace', () => {
+    expect(isPlausibleCodeFilePath('path with space.ts')).toBe(false);
+  });
+});
+
+describe('CODE_PATH_BARE_REGEX', () => {
+  test('matches abbreviated paths', () => {
+    const re = new RegExp(CODE_PATH_BARE_REGEX.source, 'g');
+    const m = 'see editor/App.tsx for details'.match(re);
+    expect(m).toContain('editor/App.tsx');
+  });
+
+  test('matches Next.js dynamic-route paths', () => {
+    const re = new RegExp(CODE_PATH_BARE_REGEX.source, 'g');
+    const m = 'visit app/[slug]/page.tsx'.match(re);
+    expect(m).toContain('app/[slug]/page.tsx');
+  });
+});

package/3p/pi-plannotator/packages/shared/code-file.ts

@@ -0,0 +1,41 @@
+export const CODE_FILE_REGEX = /(?:\.(tsx?|jsx?|py|rb|go|rs|java|c|cpp|h|hpp|cs|swift|kt|scala|sh|bash|zsh|sql|graphql|json|ya?ml|toml|ini|css|scss|less|xml|tf|lua|r|dart|ex|exs|vue|svelte|astro|zig|proto)|(?:^|\/)(Dockerfile|Makefile|Rakefile|Gemfile|Procfile|Vagrantfile|Brewfile|Justfile))$/i;
+
+export const CODE_PATH_BARE_REGEX = /(?:\.{0,2}\/)?(?:[a-zA-Z0-9_@.\-\[\]]+\/)+[a-zA-Z0-9_.\-\[\]]+\.[a-zA-Z0-9]+(?::\d+(?:-\d+)?)?/g;
+
+const IMPLAUSIBLE_CHARS = /[{},*?\s]/;
+
+export function isPlausibleCodeFilePath(input: string): boolean {
+	return !IMPLAUSIBLE_CHARS.test(input);
+}
+
+export interface ParsedCodePath {
+	filePath: string;
+	line?: number;
+	lineEnd?: number;
+}
+
+const LINE_SUFFIX_RE = /:(\d+)(?:-(\d+))?$/;
+
+export function parseCodePath(input: string): ParsedCodePath {
+	const clean = input.replace(/#.*$/, '');
+	const m = clean.match(LINE_SUFFIX_RE);
+	if (!m) return { filePath: clean };
+	let line = Number.parseInt(m[1], 10);
+	let lineEnd = m[2] ? Number.parseInt(m[2], 10) : undefined;
+	if (lineEnd != null && lineEnd < line) { const tmp = line; line = lineEnd; lineEnd = tmp; }
+	return { filePath: clean.replace(LINE_SUFFIX_RE, ''), line, lineEnd };
+}
+
+export function stripLineRef(input: string): string {
+	return input.replace(/#.*$/, '').replace(LINE_SUFFIX_RE, '');
+}
+
+export function isCodeFilePath(input: string): boolean {
+	if (!isPlausibleCodeFilePath(input)) return false;
+	return CODE_FILE_REGEX.test(stripLineRef(input))
+		&& !input.startsWith('http://') && !input.startsWith('https://');
+}
+
+export function isCodeFilePathStrict(input: string): boolean {
+	return input.includes('/') && isCodeFilePath(input);
+}