pi-scout 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
+
+## [Unreleased]
+
+## [0.1.0] - TBD
+
+### Added
+
+- Initial `pi-scout` package scaffold.
+- `/scout` command for registering, listing, and removing reference repositories.
+- `scout_add` and conditional `scout_rm` tools.
+- Compact system prompt injection for registered local repository paths with stale-temp pruning.
+- GitHub `owner/repo` shorthand for repository registration.
+- `scout_add` tool schema minimized to a single `source` parameter.
+- Repository registration now defaults to shallow clones with depth `1`.
+- Unix-like systems now use `/tmp/pi-scout` for shorter registered paths.
+- Package-level extension entry point so Pi displays the extension as `pi-scout` instead of `extensions`/`extension`.
+- Optional temporary clone deletion when removing repository records.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and may remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers through GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Thanks for your interest in contributing to `pi-scout`.
+
+## Development setup
+
+```bash
+npm install
+npm run check
+```
+
+This package is source-distributed: Pi loads the TypeScript extension files directly. There is no build step for runtime use.
+
+## Local testing
+
+Install this checkout into a temporary Pi project:
+
+```bash
+mkdir -p <test-project>
+cd <test-project>
+pi install -l /path/to/pi-mono/packages/pi-scout
+pi
+```
+
+For a one-off run without changing settings:
+
+```bash
+pi -e /path/to/pi-mono/packages/pi-scout --print "list your tools"
+```
+
+## Pull request checklist
+
+Before opening a pull request:
+
+- Run `npm run check`.
+- Run `npm audit --omit=dev`.
+- Run `npm run pack:dry-run` and confirm the package contents are intentional.
+- Update `README.md` if user-facing behavior changes.
+- Update `CHANGELOG.md` for notable changes.
+- Keep examples and paths generic; do not commit machine-specific paths, API keys, tokens, or provider config containing secrets.
+
+## Coding guidelines
+
+- Keep `extensions/index.ts` focused on Pi extension wiring and move reusable implementation details into `src/`.
+- When adding tools, update Typebox schemas, runtime validation, README parameter docs, and tests together.
+- Treat config keys, environment variables, and command names as public interface; changes to defaults or precedence are breaking changes.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Mocito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# pi-scout
+
+A source-distributed [Pi](https://pi.dev) package for registering local reference codebases for agent exploration.
+
+> [!WARNING]
+> Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.
+
+## Features
+
+- `/scout` slash command with a simple TUI flow for registering, listing, and removing reference repositories.
+- `scout_add` tool for cloning a Git repository into a local temporary cache.
+- `scout_rm` tool for agent-driven removal once repositories exist.
+- Compact per-turn system prompt guidance with registered repo names and local clone paths.
+- Automatic pruning: if the OS cleans a temporary clone, Pi Scout removes that stale entry before adding prompt context.
+
+Registered repositories are cloned under `/tmp/pi-scout/<name>-<id>` on Unix-like systems, or the OS temp directory on Windows. Set `PI_SCOUT_TMPDIR` to override the parent temp directory. Pi Scout uses shallow clones with depth `1` by default because it is for code exploration, not history exploration. Pi Scout keeps records in Pi's agent directory and reuses them across sessions while the cloned directories still exist.
+
+## Installation
+
+Install from npm:
+
+```bash
+pi install npm:pi-scout
+```
+
+Install project-locally with Pi's `-l` flag:
+
+```bash
+pi install -l npm:pi-scout
+```
+
+During local development from this monorepo:
+
+```bash
+pi install /path/to/pi-mono/packages/pi-scout
+```
+
+For a one-off test run without installing:
+
+```bash
+pi -e /path/to/pi-mono/packages/pi-scout --print "list your tools"
+```
+
+This is an npm-compatible TypeScript Pi package. There is no runtime build step.
+
+## Quick usage
+
+Open the Pi Scout menu:
+
+```text
+/scout
+```
+
+Register a repository directly with a Git URL/path or GitHub shorthand:
+
+```text
+/scout https://github.com/owner/repo.git
+/scout owner/repo
+```
+
+Ask the agent to register one:
+
+```text
+Register https://github.com/owner/repo.git with Pi Scout, then inspect how it implements feature flags.
+```
+
+After a repository is registered, the agent sees its local path in the system prompt and can inspect it with local file tools.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `scout_add` | Clone and register a Git repository as a local reference codebase. Takes only `source`: Git URL, local path, or GitHub `owner/repo` shorthand. |
+| `scout_rm` | Remove a repository from Pi Scout records, optionally deleting the temporary clone. Available to the model only while repos are registered. |
+
+## Notes
+
+- Pi Scout uses local file access for exploration. It does not provide web search or remote content-fetching tools.
+- Registering a Git URL still uses `git clone`, so Git may contact the configured remote.
+- Registered repositories are intended as read-only references unless the user explicitly asks otherwise.
+- The system prompt includes only registered repo names and local paths, not origin URLs or branch metadata.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run pack:dry-run
+```

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version of `pi-scout`.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected security vulnerabilities.
+
+Report privately by contacting the repository maintainer through GitHub. Include:
+
+- a description of the issue;
+- steps to reproduce;
+- affected versions or commits, if known;
+- any suggested mitigation.
+
+The maintainer will acknowledge reports as soon as practical and coordinate disclosure once a fix or mitigation is available.
+
+## Security model
+
+`pi-scout` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
+
+Do not commit API keys, tokens, credentials, local settings, or machine-specific paths.
+
+`pi-scout` stores repository records under Pi's agent directory and clones registered repositories into the OS temporary directory. It does not provide web search or content-fetching tools, but registering a Git URL uses `git clone`, which may contact the configured remote. Registered repository paths are appended to the system prompt so the agent can inspect them with local file tools.

package/extensions/index.ts

@@ -0,0 +1,147 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { buildScoutPrompt, formatRepo, loadPrunedState, registerRepo, removeRepo } from "../src/index.js";
+
+const RegisterRepoParams = Type.Object({
+  source: Type.String({ description: "Git URL/path or owner/repo." }),
+});
+
+const RemoveRepoParams = Type.Object({
+  idOrName: Type.String({ description: "Repo id or name." }),
+  deleteClone: Type.Optional(Type.Boolean({ description: "Delete temp clone too." })),
+});
+
+export default function piScout(pi: ExtensionAPI) {
+  let scoutRmRegistered = false;
+
+  function setToolActive(name: string, active: boolean): void {
+    const activeTools = pi.getActiveTools();
+    const hasTool = activeTools.includes(name);
+    if (active && !hasTool) pi.setActiveTools([...activeTools, name]);
+    if (!active && hasTool) pi.setActiveTools(activeTools.filter((tool) => tool !== name));
+  }
+
+  async function syncScoutRmTool(): Promise<void> {
+    const hasRepos = (await loadPrunedState()).repos.length > 0;
+    if (hasRepos && !scoutRmRegistered) {
+      pi.registerTool({
+        name: "scout_rm",
+        label: "Scout Remove",
+        description: "Remove a Scout repo record.",
+        promptSnippet: "Remove Scout repo records.",
+        promptGuidelines: [
+          "Use scout_rm only when asked to unregister a Scout repo.",
+        ],
+        parameters: RemoveRepoParams,
+        async execute(_toolCallId, rawParams) {
+          const params = rawParams as { idOrName: string; deleteClone?: boolean };
+          const removed = await removeRepo(params.idOrName, { deleteClone: params.deleteClone });
+          await syncScoutRmTool();
+          const text = removed
+            ? `Removed Pi Scout repository from records:\n${formatRepo(removed)}\n\nLocal clone ${params.deleteClone ? "deleted" : "was not deleted"}.`
+            : `No Pi Scout repository matched "${params.idOrName}".`;
+          return { content: [{ type: "text", text }], details: { removed, deletedClone: Boolean(params.deleteClone && removed) } };
+        },
+      });
+      scoutRmRegistered = true;
+    }
+    if (scoutRmRegistered) setToolActive("scout_rm", hasRepos);
+  }
+
+  pi.on("session_start", async () => {
+    await syncScoutRmTool();
+  });
+
+  pi.registerCommand("scout", {
+    description: "Manage Scout reference repos",
+    handler: async (args, ctx) => {
+      await handleScoutCommand(pi, args, ctx, syncScoutRmTool);
+    },
+  });
+
+  pi.registerTool({
+    name: "scout_add",
+    label: "Scout Add",
+    description: "Clone/register a reference repo.",
+    promptSnippet: "Add Scout reference repos.",
+    promptGuidelines: [
+      "Use scout_add to register a Git repo for code exploration.",
+    ],
+    parameters: RegisterRepoParams,
+    async execute(_toolCallId, rawParams, signal) {
+      const params = rawParams as { source: string };
+      const repo = await registerRepo(pi, { source: params.source, signal });
+      await syncScoutRmTool();
+      return {
+        content: [{ type: "text", text: `Registered Pi Scout repository:\n${formatRepo(repo)}` }],
+        details: { repo },
+      };
+    },
+  });
+
+
+  pi.on("before_agent_start", async (event) => {
+    await syncScoutRmTool();
+    const state = await loadPrunedState();
+    const scoutPrompt = buildScoutPrompt(state.repos);
+    if (!scoutPrompt) return;
+    return { systemPrompt: `${event.systemPrompt}\n\n${scoutPrompt}` };
+  });
+}
+
+async function handleScoutCommand(
+  pi: ExtensionAPI,
+  args: string,
+  ctx: ExtensionCommandContext,
+  syncScoutRmTool: () => Promise<void>,
+): Promise<void> {
+  const trimmed = args.trim();
+  if (trimmed) {
+    const repo = await registerRepo(pi, { source: trimmed });
+    await syncScoutRmTool();
+    ctx.ui.notify(`Pi Scout registered ${repo.name}`, "info");
+    return;
+  }
+
+  const action = await ctx.ui.select("Pi Scout", [
+    "Register repository",
+    "List repositories",
+    "Remove repository",
+  ]);
+
+  if (action === "Register repository") {
+    const source = await ctx.ui.input("Repository URL or local path", "https://github.com/owner/repo.git");
+    if (!source?.trim()) return;
+    const name = await ctx.ui.input("Optional friendly name", "");
+    const repo = await registerRepo(pi, { source, name: name?.trim() || undefined });
+    await syncScoutRmTool();
+    ctx.ui.notify(`Pi Scout registered ${repo.name}`, "info");
+    return;
+  }
+
+  if (action === "List repositories") {
+    const state = await loadPrunedState();
+    const text = state.repos.length === 0
+      ? "No Pi Scout repositories are currently registered."
+      : state.repos.map(formatRepo).join("\n\n");
+    await ctx.ui.editor("Pi Scout repositories", text);
+    return;
+  }
+
+  if (action === "Remove repository") {
+    const state = await loadPrunedState();
+    if (state.repos.length === 0) {
+      ctx.ui.notify("No Pi Scout repositories are currently registered.", "info");
+      return;
+    }
+    const labels = state.repos.map((repo) => `${repo.name} (${repo.id})`);
+    const selected = await ctx.ui.select("Remove repository", labels);
+    if (!selected) return;
+    const id = selected.match(/\(([^)]+)\)$/)?.[1];
+    if (!id) return;
+    const deleteClone = await ctx.ui.confirm("Delete local clone?", "Also delete the cloned temporary directory?");
+    const removed = await removeRepo(id, { deleteClone });
+    await syncScoutRmTool();
+    if (removed) ctx.ui.notify(`Removed ${removed.name}${deleteClone ? " and deleted its clone" : " from Pi Scout records"}`, "info");
+  }
+}

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./extensions/index.js";

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pi-scout",
+  "version": "0.1.0",
+  "description": "Register local reference codebases for Pi agent exploration.",
+  "type": "module",
+  "license": "MIT",
+  "author": "jvm",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jvm/pi-mono.git",
+    "directory": "packages/pi-scout"
+  },
+  "bugs": {
+    "url": "https://github.com/jvm/pi-mono/issues"
+  },
+  "homepage": "https://github.com/jvm/pi-mono/tree/main/packages/pi-scout#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "scout",
+    "codebase-exploration",
+    "reference-repos"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^25.6.2",
+    "typebox": "^1.1.33",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export const PACKAGE_NAME = "pi-scout";
+
+export * from "./prompt.js";
+export * from "./repo.js";
+export * from "./state.js";

package/src/prompt.ts

@@ -0,0 +1,9 @@
+import type { ScoutRepo } from "./state.js";
+
+export function buildScoutPrompt(repos: ScoutRepo[]): string {
+  if (repos.length === 0) return "";
+
+  const repoList = repos.map((repo) => `- ${repo.name}: ${repo.path}`).join("\n");
+
+  return `Scout repos:\n${repoList}\nUse as read-only reference codebases when relevant.`;
+}

package/src/repo.ts

@@ -0,0 +1,111 @@
+import { mkdir, rm } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { platform, tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadPrunedState, saveState, type ScoutRepo } from "./state.js";
+
+export interface RegisterRepoOptions {
+  source: string;
+  name?: string;
+  branch?: string;
+  depth?: number;
+  signal?: AbortSignal;
+}
+
+export async function registerRepo(pi: ExtensionAPI, options: RegisterRepoOptions): Promise<ScoutRepo> {
+  const source = normalizeSource(options.source.trim());
+  if (!source) throw new Error("Repository source is required.");
+
+  const id = randomUUID().slice(0, 12);
+  const name = sanitizeName(options.name?.trim() || inferName(source) || `repo-${id}`);
+  const root = getScoutCloneRoot();
+  const destination = join(root, `${name}-${id}`);
+  await mkdir(root, { recursive: true });
+
+  const args = ["clone"];
+  if (options.branch?.trim()) args.push("--branch", options.branch.trim());
+  const depth = options.depth && Number.isInteger(options.depth) && options.depth > 0 ? options.depth : 1;
+  args.push("--depth", String(depth));
+  args.push(source, destination);
+
+  const result = await pi.exec("git", args, { signal: options.signal, timeout: 120_000 });
+  if (result.code !== 0) {
+    const stderr = result.stderr?.trim() || result.stdout?.trim() || "git clone failed";
+    throw new Error(stderr);
+  }
+
+  const now = new Date().toISOString();
+  const repo: ScoutRepo = {
+    id,
+    name,
+    source,
+    path: destination,
+    branch: options.branch?.trim() || undefined,
+    createdAt: now,
+    lastSeenAt: now,
+  };
+
+  const state = await loadPrunedState();
+  state.repos.push(repo);
+  await saveState(state);
+  return repo;
+}
+
+export async function removeRepo(idOrName: string, options: { deleteClone?: boolean } = {}): Promise<ScoutRepo | undefined> {
+  const needle = idOrName.trim();
+  if (!needle) return undefined;
+
+  const state = await loadPrunedState();
+  const index = state.repos.findIndex((repo) => repo.id === needle || repo.name === needle);
+  if (index === -1) return undefined;
+
+  const [removed] = state.repos.splice(index, 1);
+  await saveState(state);
+
+  if (options.deleteClone && removed) {
+    await rm(removed.path, { recursive: true, force: true });
+  }
+
+  return removed;
+}
+
+export function formatRepo(repo: ScoutRepo): string {
+  const branch = repo.branch ? ` (${repo.branch})` : "";
+  return `${repo.name}${branch}\n  id: ${repo.id}\n  source: ${repo.source}\n  path: ${repo.path}`;
+}
+
+function getScoutCloneRoot(): string {
+  if (process.env.PI_SCOUT_TMPDIR) return join(process.env.PI_SCOUT_TMPDIR, "pi-scout");
+  if (platform() !== "win32") return "/tmp/pi-scout";
+  return join(tmpdir(), "pi-scout");
+}
+
+function inferName(source: string): string {
+  const shorthand = parseGitHubShorthand(source);
+  if (shorthand) return shorthand.repo;
+
+  const withoutTrailingSlash = source.replace(/[\\/]+$/, "");
+  const last = basename(withoutTrailingSlash).replace(/\.git$/i, "");
+  return last || "repo";
+}
+
+function normalizeSource(source: string): string {
+  const shorthand = parseGitHubShorthand(source);
+  if (!shorthand) return source;
+  return `https://github.com/${shorthand.owner}/${shorthand.repo}.git`;
+}
+
+function parseGitHubShorthand(source: string): { owner: string; repo: string } | undefined {
+  const match = source.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/);
+  if (!match) return undefined;
+  return { owner: match[1]!, repo: match[2]!.replace(/\.git$/i, "") };
+}
+
+function sanitizeName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64) || "repo";
+}

package/src/state.ts

@@ -0,0 +1,83 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface ScoutRepo {
+  id: string;
+  name: string;
+  source: string;
+  path: string;
+  branch?: string;
+  createdAt: string;
+  lastSeenAt: string;
+}
+
+export interface ScoutState {
+  repos: ScoutRepo[];
+}
+
+const STATE_DIR = join(getAgentDir(), "scout");
+const STATE_PATH = join(STATE_DIR, "repos.json");
+
+export function getScoutStatePath(): string {
+  return STATE_PATH;
+}
+
+export async function loadState(): Promise<ScoutState> {
+  try {
+    const raw = await readFile(STATE_PATH, "utf8");
+    const parsed = JSON.parse(raw) as Partial<ScoutState>;
+    return { repos: Array.isArray(parsed.repos) ? parsed.repos.filter(isScoutRepo) : [] };
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return { repos: [] };
+    throw new Error(`Failed to read pi-scout state at ${STATE_PATH}: ${error?.message ?? String(error)}`);
+  }
+}
+
+export async function saveState(state: ScoutState): Promise<void> {
+  await mkdir(STATE_DIR, { recursive: true });
+  await writeFile(STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+export async function pruneMissingRepos(state: ScoutState): Promise<{ state: ScoutState; removed: ScoutRepo[] }> {
+  const repos: ScoutRepo[] = [];
+  const removed: ScoutRepo[] = [];
+  const now = new Date().toISOString();
+
+  for (const repo of state.repos) {
+    if (await pathExists(repo.path)) {
+      repos.push({ ...repo, lastSeenAt: now });
+    } else {
+      removed.push(repo);
+    }
+  }
+
+  const next = { repos };
+  if (removed.length > 0) await saveState(next);
+  return { state: next, removed };
+}
+
+export async function loadPrunedState(): Promise<ScoutState> {
+  return (await pruneMissingRepos(await loadState())).state;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function isScoutRepo(value: unknown): value is ScoutRepo {
+  if (!value || typeof value !== "object") return false;
+  const repo = value as Record<string, unknown>;
+  return typeof repo.id === "string"
+    && typeof repo.name === "string"
+    && typeof repo.source === "string"
+    && typeof repo.path === "string"
+    && typeof repo.createdAt === "string"
+    && typeof repo.lastSeenAt === "string";
+}