@thurstonsand/pi-librarian 0.1.0

package/docs/release.md

@@ -0,0 +1,22 @@
+# Release
+
+`@thurstonsand/pi-librarian` publishes to npm from GitHub Actions when a stable `v*` tag is pushed.
+
+## Release flow
+
+1. Prepare `RELEASE.md` with a new `## X.Y.Z` entry.
+2. Verify locally with `npm run check` and `npm pack --dry-run`.
+3. Commit the release prep.
+4. Create an annotated `vX.Y.Z` tag using the matching `RELEASE.md` entry as the tag body.
+5. Push `main` and the tag.
+6. The `Release` workflow runs CI, sets the package version from the tag, packs the package, and publishes it to npm with the `latest` dist-tag.
+
+## Release note extraction
+
+Use the helper script to extract the exact release entry for the git tag body:
+
+```sh
+VERSION=X.Y.Z
+scripts/extract-release-notes.sh "v${VERSION}" > "/tmp/pi-librarian-v${VERSION}-notes.md"
+git tag -a "v${VERSION}" --cleanup=verbatim -F "/tmp/pi-librarian-v${VERSION}-notes.md"
+```

package/extensions/librarian/attach.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import { ATTACHABLE_TOOL_NAMES } from "./tools/names.ts";
+
+export const ATTACH_ENTRY_TYPE = "pi-librarian:attach";
+
+const ATTACH_STATE_SCHEMA = Type.Object({
+  attached: Type.Boolean(),
+});
+
+export function readAttachState(ctx: ExtensionContext): boolean {
+  let attached = false;
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type !== "custom" || entry.customType !== ATTACH_ENTRY_TYPE) {
+      continue;
+    }
+    const parsed = safeParseTypeBoxValue(ATTACH_STATE_SCHEMA, entry.data);
+    if (parsed) {
+      attached = parsed.attached;
+    }
+  }
+  return attached;
+}
+
+export function applyAttachState(pi: ExtensionAPI, attached: boolean): void {
+  const active = new Set(pi.getActiveTools());
+  for (const name of ATTACHABLE_TOOL_NAMES) {
+    if (attached) {
+      active.add(name);
+    } else {
+      active.delete(name);
+    }
+  }
+  pi.setActiveTools([...active]);
+}
+
+export function setAttachState(pi: ExtensionAPI, attached: boolean): void {
+  applyAttachState(pi, attached);
+  pi.appendEntry(ATTACH_ENTRY_TYPE, { attached });
+}

package/extensions/librarian/checkout.ts

@@ -0,0 +1,239 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const FETCH_DEBOUNCE_MS = 15 * 60 * 1000;
+
+export class CheckoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CheckoutError";
+  }
+}
+
+export interface CheckoutResult {
+  repo: string;
+  path: string;
+  headSha: string;
+  ref: string;
+  fileCount: number;
+  reusedClone: boolean;
+}
+
+interface RepoReference {
+  key: string;
+  cloneUrls: string[];
+}
+
+export function repoCachePath(cacheDir: string, repo: string): string {
+  return path.join(cacheDir, "repos", ...repo.split("/"));
+}
+
+function isGitHubHost(host: string): boolean {
+  return host === "github.com" || host === "www.github.com";
+}
+
+function normalizeRepoPath(rawPath: string): string | undefined {
+  const repoPath = rawPath.replace(/^\/+/, "").replace(/\.git$/, "");
+  const parts = repoPath.split("/");
+  if (parts.length < 2 || parts.some((part) => !/^[\w.-]+$/.test(part))) {
+    return undefined;
+  }
+  return parts.join("/");
+}
+
+function cloneKey(host: string, repoPath: string): string {
+  return isGitHubHost(host) ? repoPath : `${host}/${repoPath}`;
+}
+
+function parseRepoReference(input: string): RepoReference {
+  const trimmed = input.trim().replace(/\/+$/, "");
+  const githubPath = normalizeRepoPath(trimmed);
+  if (githubPath && githubPath.split("/").length === 2) {
+    return {
+      key: githubPath,
+      cloneUrls: [`https://github.com/${githubPath}.git`, `git@github.com:${githubPath}.git`],
+    };
+  }
+
+  const scpMatch = /^(?<user>[\w.-]+)@(?<host>[\w.-]+):(?<path>[\w./-]+?)(?:\.git)?$/.exec(trimmed);
+  if (scpMatch?.groups) {
+    const user = scpMatch.groups.user;
+    const host = scpMatch.groups.host;
+    const repoPath = scpMatch.groups.path ? normalizeRepoPath(scpMatch.groups.path) : undefined;
+    if (user && host && repoPath && (!isGitHubHost(host) || repoPath.split("/").length === 2)) {
+      return {
+        key: cloneKey(host, repoPath),
+        cloneUrls: [`${user}@${host}:${repoPath}.git`],
+      };
+    }
+  }
+
+  let url: URL;
+  try {
+    url = new URL(trimmed.replace(/\.git$/, ""));
+  } catch {
+    throw new CheckoutError(
+      `Invalid repository "${input}". Use owner/repo or an HTTPS/SSH repository URL.`,
+    );
+  }
+
+  if (url.protocol !== "https:" && url.protocol !== "ssh:") {
+    throw new CheckoutError(
+      `Invalid repository "${input}". Use owner/repo or an HTTPS/SSH repository URL.`,
+    );
+  }
+
+  const repoPath = normalizeRepoPath(url.pathname);
+  if (!repoPath || (isGitHubHost(url.hostname) && repoPath.split("/").length !== 2)) {
+    throw new CheckoutError(
+      `Invalid repository "${input}". Use owner/repo or an HTTPS/SSH repository URL.`,
+    );
+  }
+
+  const key = cloneKey(url.hostname, repoPath);
+  if (url.protocol === "ssh:") {
+    const user = url.username || "git";
+    return { key, cloneUrls: [`ssh://${user}@${url.hostname}/${repoPath}.git`] };
+  }
+
+  if (isGitHubHost(url.hostname)) {
+    return {
+      key,
+      cloneUrls: [`https://github.com/${repoPath}.git`, `git@github.com:${repoPath}.git`],
+    };
+  }
+
+  return {
+    key,
+    cloneUrls: [`https://${url.hostname}/${repoPath}.git`, `git@${url.hostname}:${repoPath}.git`],
+  };
+}
+
+export function parseRepoName(input: string): string {
+  return parseRepoReference(input).key;
+}
+
+async function git(
+  args: string[],
+  cwd: string | undefined,
+  signal: AbortSignal | undefined,
+): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      ...(cwd ? { cwd } : {}),
+      ...(signal ? { signal } : {}),
+      timeout: 300_000,
+      maxBuffer: 32 * 1024 * 1024,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return stdout.trim();
+  } catch (error) {
+    const stderr =
+      error && typeof error === "object" && "stderr" in error ? String(error.stderr) : "";
+    const message = stderr.trim() || (error instanceof Error ? error.message : String(error));
+    throw new CheckoutError(`git ${args[0]} failed: ${message.slice(0, 500)}`);
+  }
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function clone(
+  reference: RepoReference,
+  dest: string,
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+
+  let lastError: unknown;
+  for (const url of reference.cloneUrls) {
+    try {
+      await git(["clone", "--filter=blob:none", url, dest], undefined, signal);
+      return;
+    } catch (error) {
+      lastError = error;
+      await fs.rm(dest, { recursive: true, force: true });
+    }
+  }
+
+  throw lastError instanceof Error
+    ? lastError
+    : new CheckoutError(`Failed to clone ${reference.key}.`);
+}
+
+async function fetchIfStale(dest: string, signal: AbortSignal | undefined): Promise<void> {
+  let lastFetched = 0;
+  try {
+    const stat = await fs.stat(path.join(dest, ".git", "FETCH_HEAD"));
+    lastFetched = stat.mtimeMs;
+  } catch {
+    // Never fetched since clone; the clone itself counts only via HEAD age, so fetch.
+  }
+
+  if (Date.now() - lastFetched < FETCH_DEBOUNCE_MS) {
+    return;
+  }
+
+  await git(["fetch", "origin", "--prune"], dest, signal);
+}
+
+async function defaultBranch(dest: string, signal: AbortSignal | undefined): Promise<string> {
+  try {
+    const ref = await git(["symbolic-ref", "refs/remotes/origin/HEAD"], dest, signal);
+    return ref.replace("refs/remotes/origin/", "");
+  } catch {
+    await git(["remote", "set-head", "origin", "--auto"], dest, signal);
+    const ref = await git(["symbolic-ref", "refs/remotes/origin/HEAD"], dest, signal);
+    return ref.replace("refs/remotes/origin/", "");
+  }
+}
+
+export async function checkoutRepo(
+  repoInput: string,
+  ref: string | undefined,
+  cacheDir: string,
+  signal: AbortSignal | undefined,
+): Promise<CheckoutResult> {
+  const repo = parseRepoReference(repoInput);
+  const dest = repoCachePath(cacheDir, repo.key);
+
+  const reusedClone = await pathExists(path.join(dest, ".git"));
+  if (reusedClone) {
+    await fetchIfStale(dest, signal);
+  } else {
+    await clone(repo, dest, signal);
+  }
+
+  let checkedOutRef: string;
+  if (ref) {
+    try {
+      await git(["fetch", "origin", ref], dest, signal);
+      await git(["checkout", "--force", "--detach", "FETCH_HEAD"], dest, signal);
+    } catch {
+      // Refs already fetched (e.g. a sha reachable from an earlier fetch) check out directly.
+      await git(["checkout", "--force", "--detach", ref], dest, signal);
+    }
+    checkedOutRef = ref;
+  } else {
+    const branch = await defaultBranch(dest, signal);
+    await git(["checkout", "--force", branch], dest, signal);
+    await git(["reset", "--hard", `origin/${branch}`], dest, signal);
+    checkedOutRef = branch;
+  }
+
+  const headSha = await git(["rev-parse", "HEAD"], dest, signal);
+  const files = await git(["ls-files"], dest, signal);
+  const fileCount = files.length === 0 ? 0 : files.split("\n").length;
+
+  return { repo: repo.key, path: dest, headSha, ref: checkedOutRef, fileCount, reusedClone };
+}

package/extensions/librarian/github.ts

@@ -0,0 +1,364 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { RequestError } from "@octokit/request-error";
+import { Octokit } from "@octokit/rest";
+import { type Static, Type } from "typebox";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+
+const execFileAsync = promisify(execFile);
+
+export class GitHubApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly retryAfterSeconds: number | undefined,
+    override readonly cause?: unknown,
+  ) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "GitHubApiError";
+  }
+}
+
+export interface GitHubRepoSlug {
+  owner: string;
+  repo: string;
+}
+
+function repoFullName(repo: GitHubRepoSlug): string {
+  return `${repo.owner}/${repo.repo}`;
+}
+
+export type GitHubClientProvider = () => Promise<GitHubClient>;
+
+export async function resolveGitHubToken(): Promise<string | undefined> {
+  const envToken = process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim();
+  if (envToken) {
+    return envToken;
+  }
+
+  try {
+    const { stdout } = await execFileAsync("gh", ["auth", "token"], { timeout: 10_000 });
+    const token = stdout.trim();
+    return token.length > 0 ? token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createGitHubClient(token: string | undefined): GitHubClient {
+  return new GitHubClient(
+    new Octokit({
+      ...(token ? { auth: token } : {}),
+      userAgent: "pi-librarian",
+      log: {
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      },
+      request: {
+        headers: {
+          "x-github-api-version": "2022-11-28",
+        },
+      },
+    }),
+  );
+}
+
+export function createGitHubClientProvider(
+  tokenResolver: () => Promise<string | undefined> = resolveGitHubToken,
+): GitHubClientProvider {
+  let client: Promise<GitHubClient> | undefined;
+  return () => {
+    client ??= tokenResolver().then((token) => createGitHubClient(token));
+    return client;
+  };
+}
+
+function retryAfterSeconds(
+  headers: Record<string, string | number | undefined> | undefined,
+): number | undefined {
+  const retryAfter = headers?.["retry-after"];
+  const rateReset = headers?.["x-ratelimit-reset"];
+
+  let seconds: number | undefined;
+  if (retryAfter) {
+    seconds = Number(retryAfter);
+  } else if (rateReset) {
+    seconds = Math.max(0, Number(rateReset) - Math.floor(Date.now() / 1000));
+  }
+
+  return Number.isFinite(seconds) ? seconds : undefined;
+}
+
+const GITHUB_ERROR_DATA_SCHEMA = Type.Object({
+  message: Type.Optional(Type.String()),
+});
+
+function errorDetail(error: RequestError): string {
+  const parsed = safeParseTypeBoxValue(GITHUB_ERROR_DATA_SCHEMA, error.response?.data);
+  if (parsed?.message) {
+    return parsed.message;
+  }
+  return error.message;
+}
+
+function normalizeGitHubError(error: unknown, operation: string): never {
+  if (error instanceof RequestError) {
+    const detail = errorDetail(error).slice(0, 300);
+    throw new GitHubApiError(
+      `GitHub API ${error.status} during ${operation}${detail ? `: ${detail}` : ""}`,
+      error.status,
+      retryAfterSeconds(error.response?.headers),
+      error,
+    );
+  }
+
+  throw error;
+}
+
+const REPO_SEARCH_ITEM_SCHEMA = Type.Object({
+  full_name: Type.String(),
+  description: Type.Union([Type.String(), Type.Null()]),
+  stargazers_count: Type.Number(),
+  language: Type.Union([Type.String(), Type.Null()]),
+  topics: Type.Optional(Type.Array(Type.String())),
+  pushed_at: Type.Union([Type.String(), Type.Null()]),
+  archived: Type.Boolean(),
+  fork: Type.Boolean(),
+});
+
+const REPO_SEARCH_RESPONSE_SCHEMA = Type.Object({
+  total_count: Type.Number(),
+  items: Type.Array(Type.Unknown()),
+});
+
+export interface RepoSearchHit {
+  repo: string;
+  description: string | undefined;
+  stars: number;
+  language: string | undefined;
+  topics: string[];
+  pushedAt: string | undefined;
+  archived: boolean;
+  fork: boolean;
+}
+
+export interface RepoSearchResult {
+  totalCount: number;
+  hits: RepoSearchHit[];
+}
+
+export interface SearchRepositoriesParams {
+  query: string;
+  sort: "stars" | "updated" | "best-match";
+  limit: number;
+}
+
+const CODE_SEARCH_MATCH_SCHEMA = Type.Object({
+  fragment: Type.Optional(Type.String()),
+});
+
+const CODE_SEARCH_ITEM_SCHEMA = Type.Object({
+  path: Type.String(),
+  repository: Type.Object({ full_name: Type.String() }),
+  text_matches: Type.Optional(Type.Array(Type.Unknown())),
+});
+
+const CODE_SEARCH_RESPONSE_SCHEMA = Type.Object({
+  total_count: Type.Number(),
+  items: Type.Array(Type.Unknown()),
+});
+
+export interface CodeSearchHit {
+  repo: string;
+  path: string;
+  fragments: string[];
+}
+
+export interface GitHubCodeSearchResult {
+  totalCount: number;
+  hits: CodeSearchHit[];
+}
+
+export interface SearchGitHubCodeParams {
+  pattern: string;
+  repos?: GitHubRepoSlug[];
+  owners?: string[];
+  language?: string;
+  path?: string;
+  limit: number;
+}
+
+const CONTENTS_DIR_ENTRY_SCHEMA = Type.Object({
+  type: Type.String(),
+  path: Type.String(),
+  size: Type.Optional(Type.Number()),
+});
+
+export type FileContents = {
+  kind: "file";
+  text: string;
+};
+
+export type DirectoryContents = {
+  kind: "directory";
+  entries: { type: string; path: string; size: number | undefined }[];
+};
+
+export interface ReadContentsParams {
+  repo: GitHubRepoSlug;
+  path: string;
+  ref: string | undefined;
+}
+
+const REPO_META_SCHEMA = Type.Object({
+  default_branch: Type.String(),
+  private: Type.Boolean(),
+});
+
+export interface RepoMeta {
+  defaultBranch: string;
+  isPrivate: boolean;
+}
+
+function buildGitHubCodeQuery(params: SearchGitHubCodeParams): string {
+  const parts: string[] = [params.pattern.replace(/^\/|\/$/g, "")];
+
+  for (const repo of params.repos ?? []) {
+    parts.push(`repo:${repoFullName(repo)}`);
+  }
+  for (const owner of params.owners ?? []) {
+    parts.push(`user:${owner}`);
+  }
+  if (params.language) {
+    parts.push(`language:${params.language}`);
+  }
+  if (params.path) {
+    parts.push(`path:${params.path}`);
+  }
+
+  return parts.join(" ");
+}
+
+export class GitHubClient {
+  constructor(private readonly octokit: Octokit) {}
+
+  async searchRepositories(params: SearchRepositoriesParams): Promise<RepoSearchResult> {
+    try {
+      const response = await this.octokit.rest.search.repos({
+        q: params.query,
+        per_page: params.limit,
+        ...(params.sort === "best-match" ? {} : { sort: params.sort, order: "desc" as const }),
+      });
+      const payload = safeParseTypeBoxValue(REPO_SEARCH_RESPONSE_SCHEMA, response.data);
+      if (!payload) {
+        throw new Error("GitHub repository search returned an unexpected payload shape.");
+      }
+
+      const hits: RepoSearchHit[] = [];
+      for (const item of payload.items) {
+        const parsed = safeParseTypeBoxValue(REPO_SEARCH_ITEM_SCHEMA, item);
+        if (!parsed) {
+          continue;
+        }
+
+        hits.push({
+          repo: parsed.full_name,
+          description: parsed.description ?? undefined,
+          stars: parsed.stargazers_count,
+          language: parsed.language ?? undefined,
+          topics: parsed.topics ?? [],
+          pushedAt: parsed.pushed_at ?? undefined,
+          archived: parsed.archived,
+          fork: parsed.fork,
+        });
+      }
+
+      return { totalCount: payload.total_count, hits };
+    } catch (error) {
+      normalizeGitHubError(error, "repository search");
+    }
+  }
+
+  async searchCode(params: SearchGitHubCodeParams): Promise<GitHubCodeSearchResult> {
+    try {
+      const response = await this.octokit.rest.search.code({
+        q: buildGitHubCodeQuery(params),
+        per_page: params.limit,
+        mediaType: { format: "text-match" },
+      });
+
+      const payload = safeParseTypeBoxValue(CODE_SEARCH_RESPONSE_SCHEMA, response.data);
+      if (!payload) {
+        throw new Error("GitHub code search returned an unexpected payload shape.");
+      }
+
+      const hits: CodeSearchHit[] = [];
+      for (const item of payload.items) {
+        const parsed = safeParseTypeBoxValue(CODE_SEARCH_ITEM_SCHEMA, item);
+        if (!parsed) {
+          continue;
+        }
+
+        const fragments: string[] = [];
+        for (const match of parsed.text_matches ?? []) {
+          const parsedMatch = safeParseTypeBoxValue(CODE_SEARCH_MATCH_SCHEMA, match);
+          if (parsedMatch?.fragment) {
+            fragments.push(parsedMatch.fragment);
+          }
+        }
+
+        hits.push({ repo: parsed.repository.full_name, path: parsed.path, fragments });
+      }
+
+      return { totalCount: payload.total_count, hits };
+    } catch (error) {
+      normalizeGitHubError(error, "code search");
+    }
+  }
+
+  async readContents(params: ReadContentsParams): Promise<FileContents | DirectoryContents> {
+    try {
+      const response = await this.octokit.rest.repos.getContent({
+        owner: params.repo.owner,
+        repo: params.repo.repo,
+        path: params.path,
+        ...(params.ref ? { ref: params.ref } : {}),
+        mediaType: { format: "raw" },
+      });
+
+      if (Array.isArray(response.data)) {
+        const entries = response.data
+          .map((entry) => safeParseTypeBoxValue(CONTENTS_DIR_ENTRY_SCHEMA, entry))
+          .filter((entry): entry is Static<typeof CONTENTS_DIR_ENTRY_SCHEMA> => entry !== undefined)
+          .map((entry) => ({ type: entry.type, path: entry.path, size: entry.size }));
+        return { kind: "directory", entries };
+      }
+
+      if (typeof response.data === "string") {
+        return { kind: "file", text: response.data };
+      }
+
+      throw new Error(`Unexpected payload reading ${repoFullName(params.repo)}:${params.path}.`);
+    } catch (error) {
+      normalizeGitHubError(error, `read ${repoFullName(params.repo)}:${params.path}`);
+    }
+  }
+
+  async getRepo(repo: GitHubRepoSlug): Promise<RepoMeta> {
+    try {
+      const response = await this.octokit.rest.repos.get({ owner: repo.owner, repo: repo.repo });
+      const payload = safeParseTypeBoxValue(REPO_META_SCHEMA, response.data);
+      if (!payload) {
+        throw new Error(
+          `GitHub repo metadata for ${repoFullName(repo)} returned an unexpected payload shape.`,
+        );
+      }
+
+      return { defaultBranch: payload.default_branch, isPrivate: payload.private };
+    } catch (error) {
+      normalizeGitHubError(error, `repo metadata for ${repoFullName(repo)}`);
+    }
+  }
+}