pi-para 0.5.2 → 0.6.0

package/src/scheduler/session-capture.ts

@@ -0,0 +1,146 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { Model } from "@earendil-works/pi-ai";
+import type { QMDStore } from "qmd-engine";
+import { StateDB } from "../state.js";
+import { processSession, type ProcessResult } from "../processor.js";
+import type { QueueItem } from "./state.js";
+import type { WikiScheduler, SchedulerTaskHandler } from "./index.js";
+
+export interface CompletedSessionEntry {
+  timestamp: string;
+  sessionPath: string;
+}
+
+export interface CaptureSessionPayload {
+  sessionPath: string;
+  scope?: string;
+}
+
+export interface CaptureSessionDeps {
+  wikiDir: string;
+  storeProvider: () => QMDStore | null;
+  model?: Model<any>;
+  getApiKey?: (provider: string) => Promise<string | undefined>;
+  stateDb?: StateDB;
+  processor?: (
+    sessionPath: string,
+    wikiDir: string,
+    store: QMDStore,
+    scope: string,
+    model: Model<any>,
+    getApiKey: (provider: string) => Promise<string | undefined>,
+  ) => Promise<ProcessResult>;
+}
+
+export function parseCompletedSessionLine(line: string): CompletedSessionEntry | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  const parts = trimmed.split("|", 2);
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return null;
+  return { timestamp: parts[0], sessionPath: parts[1] };
+}
+
+export async function readCompletedSessionRegistry(wikiDir: string): Promise<CompletedSessionEntry[]> {
+  const registryPath = join(wikiDir, ".completed-sessions");
+  if (!existsSync(registryPath)) return [];
+  const content = await readFile(registryPath, "utf-8");
+  return content
+    .split(/\r?\n/)
+    .map(parseCompletedSessionLine)
+    .filter((entry): entry is CompletedSessionEntry => entry !== null);
+}
+
+export async function appendCompletedSession(
+  wikiDir: string,
+  sessionPath: string,
+  timestamp = new Date().toISOString(),
+): Promise<CompletedSessionEntry> {
+  const registryPath = join(wikiDir, ".completed-sessions");
+  await appendFile(registryPath, `${timestamp}|${sessionPath}\n`, "utf-8");
+  return { timestamp, sessionPath };
+}
+
+export async function enqueueCompletedSessionsFromRegistry(
+  scheduler: WikiScheduler,
+  wikiDir: string,
+  opts: { stateDb?: StateDB } = {},
+): Promise<number[]> {
+  const entries = await readCompletedSessionRegistry(wikiDir);
+  return enqueueCompletedSessions(scheduler, entries, opts);
+}
+
+export function enqueueCompletedSessions(
+  scheduler: WikiScheduler,
+  entries: CompletedSessionEntry[],
+  opts: { stateDb?: StateDB } = {},
+): number[] {
+  const ids: number[] = [];
+  for (const entry of entries) {
+    if (!existsSync(entry.sessionPath)) continue;
+    if (opts.stateDb?.isProcessed(entry.sessionPath)) continue;
+    ids.push(scheduler.enqueue(
+      "capture-session",
+      { sessionPath: entry.sessionPath, scope: detectScopeFromSessionPath(entry.sessionPath) } satisfies CaptureSessionPayload,
+      { dedupeKey: `capture-session:${entry.sessionPath}`, priority: 20 },
+    ));
+  }
+  return ids;
+}
+
+export function createCaptureSessionHandler(deps: CaptureSessionDeps): SchedulerTaskHandler {
+  return async (item: QueueItem) => {
+    const payload = item.payload as CaptureSessionPayload;
+    if (!payload.sessionPath) throw new Error("capture-session payload missing sessionPath");
+    if (!existsSync(payload.sessionPath)) throw new Error(`Session file not found: ${payload.sessionPath}`);
+
+    const store = deps.storeProvider();
+    if (!store) throw new Error("QMD store unavailable for capture-session");
+    if (!deps.model) throw new Error("Capture model unavailable for capture-session");
+    if (!deps.getApiKey) throw new Error("API key resolver unavailable for capture-session");
+
+    const stateDb = deps.stateDb ?? new StateDB(deps.wikiDir);
+    const ownsState = !deps.stateDb;
+    const scope = payload.scope ?? detectScopeFromSessionPath(payload.sessionPath);
+    try {
+      if (stateDb.isProcessed(payload.sessionPath)) return;
+      const run = deps.processor ?? processSession;
+      const result = await run(payload.sessionPath, deps.wikiDir, store, scope, deps.model, deps.getApiKey);
+      if (result.skipped) {
+        stateDb.recordSuccess(payload.sessionPath, scope, [], []);
+      } else {
+        stateDb.recordSuccess(payload.sessionPath, scope, result.pagesCreated, result.pagesUpdated);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stateDb.recordFailure(payload.sessionPath, scope, message);
+      throw err;
+    } finally {
+      if (ownsState) stateDb.close();
+    }
+  };
+}
+
+export function detectScopeFromSessionPath(sessionPath: string): string {
+  try {
+    const firstLine = requireReadFirstLine(sessionPath);
+    const header = JSON.parse(firstLine) as { cwd?: string };
+    if (header.cwd) return basename(header.cwd) || "unknown";
+  } catch {
+    // fall through to path decoding
+  }
+
+  const dirName = basename(dirname(sessionPath));
+  if (dirName.startsWith("--") && dirName.endsWith("--")) {
+    const inner = dirName.slice(2, -2);
+    const projectsIdx = inner.indexOf("projects-");
+    if (projectsIdx >= 0) return inner.slice(projectsIdx + "projects-".length);
+  }
+  return "unknown";
+}
+
+function requireReadFirstLine(path: string): string {
+  const content = readFileSync(path, "utf-8");
+  return content.split("\n")[0] ?? "";
+}

package/src/scheduler/state.ts

@@ -0,0 +1,304 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { getParaPaths } from "../paths.js";
+import { ensureLeaseSchema } from "./leases.js";
+
+export type QueueStatus = "queued" | "running" | "done" | "failed";
+
+export interface QueueItem<T = unknown> {
+  id: number;
+  taskName: string;
+  payload: T;
+  priority: number;
+  availableAt: string;
+  dedupeKey: string | null;
+  status: QueueStatus;
+  attempts: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EnqueueOptions {
+  priority?: number;
+  availableAt?: Date;
+  dedupeKey?: string;
+  now?: Date;
+}
+
+export interface SchedulerHistoryItem<T = unknown> {
+  id: number;
+  taskName: string;
+  payload: T | null;
+  status: string;
+  startedAt: string;
+  finishedAt: string | null;
+  durationMs: number | null;
+  error: string | null;
+}
+
+export class SchedulerStateDB {
+  readonly db: Database.Database;
+
+  constructor(dbPath = getParaPaths().schedulerDbPath) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.migrate();
+  }
+
+  migrate(): void {
+    ensureLeaseSchema(this.db);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS scheduler_tasks (
+        task_key TEXT PRIMARY KEY,
+        task_name TEXT NOT NULL,
+        scope TEXT,
+        schedule TEXT,
+        next_due_at TEXT,
+        last_run_at TEXT,
+        last_status TEXT,
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS scheduler_queue (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_name TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 0,
+        available_at TEXT NOT NULL,
+        dedupe_key TEXT,
+        status TEXT NOT NULL DEFAULT 'queued',
+        attempts INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS scheduler_queue_dedupe
+        ON scheduler_queue(dedupe_key)
+        WHERE dedupe_key IS NOT NULL AND status IN ('queued', 'running');
+
+      CREATE TABLE IF NOT EXISTS scheduler_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_name TEXT NOT NULL,
+        payload_json TEXT,
+        status TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        duration_ms INTEGER,
+        error TEXT
+      );
+    `);
+  }
+
+  enqueue(taskName: string, payload: unknown, opts: EnqueueOptions = {}): number {
+    const now = opts.now ?? new Date();
+    const availableAt = opts.availableAt ?? now;
+    const payloadJson = JSON.stringify(payload ?? {});
+    const existing = opts.dedupeKey ? this.getQueuedByDedupe(opts.dedupeKey) : null;
+    if (existing) return existing.id;
+
+    const result = this.db.prepare(`
+      INSERT INTO scheduler_queue
+      (task_name, payload_json, priority, available_at, dedupe_key, status, attempts, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 'queued', 0, ?, ?)
+    `).run(
+      taskName,
+      payloadJson,
+      opts.priority ?? 0,
+      availableAt.toISOString(),
+      opts.dedupeKey ?? null,
+      now.toISOString(),
+      now.toISOString(),
+    );
+    return Number(result.lastInsertRowid);
+  }
+
+  claimNext(now = new Date()): QueueItem | null {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const row = this.db.prepare(`
+        SELECT * FROM scheduler_queue
+        WHERE status = 'queued' AND available_at <= ?
+        ORDER BY priority DESC, id ASC
+        LIMIT 1
+      `).get(now.toISOString()) as QueueRow | undefined;
+
+      if (!row) {
+        this.db.exec("COMMIT");
+        return null;
+      }
+
+      this.db.prepare(`
+        UPDATE scheduler_queue
+        SET status = 'running', attempts = attempts + 1, updated_at = ?
+        WHERE id = ?
+      `).run(now.toISOString(), row.id);
+      this.db.exec("COMMIT");
+      return rowToItem({ ...row, status: "running", attempts: row.attempts + 1, updated_at: now.toISOString() });
+    } catch (err) {
+      try { this.db.exec("ROLLBACK"); } catch {}
+      throw err;
+    }
+  }
+
+  complete(id: number, now = new Date()): void {
+    this.db.prepare("UPDATE scheduler_queue SET status = 'done', updated_at = ? WHERE id = ?").run(now.toISOString(), id);
+  }
+
+  fail(id: number, error: string, opts: { retryAt?: Date; maxAttempts?: number; now?: Date } = {}): void {
+    const now = opts.now ?? new Date();
+    const row = this.get(id);
+    if (!row) return;
+    const maxAttempts = opts.maxAttempts ?? 3;
+    if (row.attempts < maxAttempts && opts.retryAt) {
+      this.db.prepare(`
+        UPDATE scheduler_queue
+        SET status = 'queued', available_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(opts.retryAt.toISOString(), now.toISOString(), id);
+    } else {
+      this.db.prepare("UPDATE scheduler_queue SET status = 'failed', updated_at = ? WHERE id = ?").run(now.toISOString(), id);
+    }
+    this.recordHistory(row.taskName, row.payload, "failed", now, now, 0, error);
+  }
+
+  get(id: number): QueueItem | null {
+    const row = this.db.prepare("SELECT * FROM scheduler_queue WHERE id = ?").get(id) as QueueRow | undefined;
+    return row ? rowToItem(row) : null;
+  }
+
+  list(status?: QueueStatus): QueueItem[] {
+    const rows = status
+      ? this.db.prepare("SELECT * FROM scheduler_queue WHERE status = ? ORDER BY id ASC").all(status) as QueueRow[]
+      : this.db.prepare("SELECT * FROM scheduler_queue ORDER BY id ASC").all() as QueueRow[];
+    return rows.map(rowToItem);
+  }
+
+  requeueRunning(now = new Date()): number {
+    const result = this.db.prepare(`
+      UPDATE scheduler_queue
+      SET status = 'queued', available_at = ?, updated_at = ?
+      WHERE status = 'running'
+    `).run(now.toISOString(), now.toISOString());
+    return result.changes;
+  }
+
+  retryFailed(taskName?: string, now = new Date()): number {
+    const result = taskName
+      ? this.db.prepare(`
+        UPDATE scheduler_queue
+        SET status = 'queued', available_at = ?, updated_at = ?
+        WHERE status = 'failed' AND task_name = ?
+      `).run(now.toISOString(), now.toISOString(), taskName)
+      : this.db.prepare(`
+        UPDATE scheduler_queue
+        SET status = 'queued', available_at = ?, updated_at = ?
+        WHERE status = 'failed'
+      `).run(now.toISOString(), now.toISOString());
+    return result.changes;
+  }
+
+  listHistory(opts: { taskName?: string; limit?: number } = {}): SchedulerHistoryItem[] {
+    const limit = opts.limit ?? 20;
+    const rows = opts.taskName
+      ? this.db.prepare("SELECT * FROM scheduler_history WHERE task_name = ? ORDER BY id DESC LIMIT ?").all(opts.taskName, limit) as HistoryRow[]
+      : this.db.prepare("SELECT * FROM scheduler_history ORDER BY id DESC LIMIT ?").all(limit) as HistoryRow[];
+    return rows.map(rowToHistoryItem);
+  }
+
+  getHistoryItem(id: number): SchedulerHistoryItem | null {
+    const row = this.db.prepare("SELECT * FROM scheduler_history WHERE id = ?").get(id) as HistoryRow | undefined;
+    return row ? rowToHistoryItem(row) : null;
+  }
+
+  recordHistory(
+    taskName: string,
+    payload: unknown,
+    status: string,
+    startedAt: Date,
+    finishedAt: Date | null,
+    durationMs: number | null,
+    error: string | null,
+  ): void {
+    this.db.prepare(`
+      INSERT INTO scheduler_history
+      (task_name, payload_json, status, started_at, finished_at, duration_ms, error)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      taskName,
+      JSON.stringify(payload ?? {}),
+      status,
+      startedAt.toISOString(),
+      finishedAt?.toISOString() ?? null,
+      durationMs,
+      error,
+    );
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private getQueuedByDedupe(dedupeKey: string): QueueItem | null {
+    const row = this.db.prepare(`
+      SELECT * FROM scheduler_queue
+      WHERE dedupe_key = ? AND status IN ('queued', 'running')
+      ORDER BY id ASC LIMIT 1
+    `).get(dedupeKey) as QueueRow | undefined;
+    return row ? rowToItem(row) : null;
+  }
+}
+
+interface QueueRow {
+  id: number;
+  task_name: string;
+  payload_json: string;
+  priority: number;
+  available_at: string;
+  dedupe_key: string | null;
+  status: QueueStatus;
+  attempts: number;
+  created_at: string;
+  updated_at: string;
+}
+
+interface HistoryRow {
+  id: number;
+  task_name: string;
+  payload_json: string | null;
+  status: string;
+  started_at: string;
+  finished_at: string | null;
+  duration_ms: number | null;
+  error: string | null;
+}
+
+function rowToItem(row: QueueRow): QueueItem {
+  return {
+    id: row.id,
+    taskName: row.task_name,
+    payload: JSON.parse(row.payload_json) as unknown,
+    priority: row.priority,
+    availableAt: row.available_at,
+    dedupeKey: row.dedupe_key,
+    status: row.status,
+    attempts: row.attempts,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function rowToHistoryItem(row: HistoryRow): SchedulerHistoryItem {
+  return {
+    id: row.id,
+    taskName: row.task_name,
+    payload: row.payload_json ? JSON.parse(row.payload_json) as unknown : null,
+    status: row.status,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    durationMs: row.duration_ms,
+    error: row.error,
+  };
+}

package/src/session-tools.ts

@@ -8,7 +8,7 @@
 
 import { readFileSync } from "node:fs";
 import { Type, type Static } from "typebox";
-import type { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 
 // -- Session loading ---------------------------------------------------------
 

package/src/settings.ts

@@ -0,0 +1,126 @@
+import type { ParaUserConfig, ProviderCredentialRef } from "./config.js";
+
+export function modelSelectionLabel(selection: ParaUserConfig["models"]["capture"]): string {
+  if (selection === "auto") return "auto";
+  return `${selection.provider}/${selection.model ?? "auto"} via ${selection.credentialRef}`;
+}
+
+export function providerProfileLabel(profile: ProviderCredentialRef | null | undefined): string {
+  if (!profile) return "not configured";
+  const model = profile.model ?? "model not set";
+  const location = profile.baseUrl ? ` at ${profile.baseUrl}` : "";
+  return `${profile.provider}/${model}${location} via ${profile.credentialRef}`;
+}
+
+export function setContextMaxTokens(config: ParaUserConfig, value: string): number {
+  const parsed = parsePositiveInteger(value, config.context.maxTokens);
+  config.context.maxTokens = parsed;
+  return parsed;
+}
+
+export function setSearchLimit(config: ParaUserConfig, value: string): number {
+  const parsed = parsePositiveInteger(value, config.context.searchLimit);
+  config.context.searchLimit = parsed;
+  return parsed;
+}
+
+export function setLintStaleDays(config: ParaUserConfig, value: string): number {
+  const parsed = parsePositiveInteger(value, config.lint.staleDays);
+  config.lint.staleDays = parsed;
+  return parsed;
+}
+
+export function toggleSearchGraphBoost(config: ParaUserConfig): boolean {
+  config.context.searchGraphBoost = !config.context.searchGraphBoost;
+  return config.context.searchGraphBoost;
+}
+
+export function toggleLintAutoFix(config: ParaUserConfig): boolean {
+  config.lint.autoFix = !config.lint.autoFix;
+  return config.lint.autoFix;
+}
+
+export function setCaptureModelAuto(config: ParaUserConfig): void {
+  config.models.capture = "auto";
+}
+
+export function setCaptureModel(config: ParaUserConfig, provider: string, model: string): ProviderCredentialRef {
+  const profile: ProviderCredentialRef = {
+    provider,
+    model,
+    credentialRef: `pi-auth:${provider}`,
+  };
+  config.models.capture = profile;
+  return profile;
+}
+
+export function setWebWikiEnabled(config: ParaUserConfig, enabled: boolean): void {
+  config.webWiki.enabled = enabled;
+}
+
+export function setWebWikiHost(config: ParaUserConfig, host: string): void {
+  config.webWiki.host = host.trim() || config.webWiki.host;
+}
+
+export function setWebWikiPort(config: ParaUserConfig, value: string): number {
+  const parsed = parsePositiveInteger(value, config.webWiki.port);
+  config.webWiki.port = parsed;
+  return parsed;
+}
+
+export function setProviderProfileField(
+  profile: ProviderCredentialRef,
+  field: "provider" | "baseUrl" | "model" | "apiFormat" | "credentialRef",
+  value: string,
+): void {
+  if (field === "apiFormat") {
+    if (value !== "openai" && value !== "anthropic" && value !== "custom") {
+      throw new Error("apiFormat must be openai, anthropic, or custom");
+    }
+    profile.apiFormat = value;
+    return;
+  }
+  if (field === "credentialRef") {
+    if (value !== "none" && !value.startsWith("pi-auth:") && !value.startsWith("secret:")) {
+      throw new Error("credentialRef must be pi-auth:<provider>, secret:<name>, or none");
+    }
+    profile.credentialRef = value as ProviderCredentialRef["credentialRef"];
+    return;
+  }
+  profile[field] = value;
+}
+
+export function setProviderDims(profile: ProviderCredentialRef, value: string): number {
+  const parsed = parsePositiveInteger(value, profile.dims ?? 0);
+  profile.dims = parsed;
+  return parsed;
+}
+
+export function ensureEmbeddingProfile(config: ParaUserConfig): ProviderCredentialRef {
+  config.qmd.embedding ??= {
+    provider: "openai",
+    model: "text-embedding-3-small",
+    apiFormat: "openai",
+    credentialRef: "secret:embedding",
+  };
+  return config.qmd.embedding;
+}
+
+export function ensureRerankProfile(config: ParaUserConfig): ProviderCredentialRef {
+  config.qmd.rerank ??= {
+    provider: "jina",
+    model: "jina-reranker-v2-base-multilingual",
+    apiFormat: "openai",
+    credentialRef: "secret:rerank",
+  };
+  return config.qmd.rerank;
+}
+
+export function disableRerank(config: ParaUserConfig): void {
+  config.qmd.rerank = null;
+}
+
+function parsePositiveInteger(value: string, fallback: number): number {
+  const parsed = parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}

package/src/setup.ts

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { atomicWriteFile } from "./atomic-write.js";
+import { loadParaConfig, type LoadedParaConfig } from "./config.js";
+import { getParaPaths, resolvePath } from "./paths.js";
+import { initWiki } from "./wiki.js";
+import { openStore, closeStore } from "./store.js";
+
+export interface SetupOptions {
+  homeDir?: string;
+  yes?: boolean;
+  dryRun?: boolean;
+  localPath?: string;
+  validateQmd?: boolean;
+  initWiki?: boolean;
+}
+
+export interface SetupResult {
+  dryRun: boolean;
+  extensionRef: string;
+  configPath: string;
+  wikiDir: string;
+  changes: string[];
+  warnings: string[];
+  migratedFromLegacy: boolean;
+}
+
+export async function runSetup(options: SetupOptions = {}): Promise<SetupResult> {
+  const loaded = await loadParaConfig({ homeDir: options.homeDir, migrate: true });
+  const paths = getParaPaths({ homeDir: options.homeDir, wikiDir: loaded.config.wiki.dir });
+  const extensionRef = resolveExtensionRef(options.localPath);
+  const changes: string[] = [];
+  const warnings: string[] = [];
+
+  if (loaded.migratedFromLegacy) {
+    changes.push(`migrated legacy config to ${paths.userConfigPath}`);
+  } else {
+    changes.push(`config ready at ${paths.userConfigPath}`);
+  }
+
+  if (options.initWiki !== false) {
+    if (!options.dryRun) await initWiki(paths.wikiDir);
+    changes.push(`initialized wiki at ${paths.wikiDir}`);
+  }
+
+  const registration = await ensurePiExtensionRegistration(paths.piSettingsPath, extensionRef, {
+    dryRun: options.dryRun ?? false,
+  });
+  changes.push(registration.changed ? `registered extension ${extensionRef}` : `extension already registered: ${extensionRef}`);
+
+  if (options.validateQmd !== false) {
+    try {
+      if (!options.dryRun) {
+        const store = await openStore(paths.wikiDir, {
+          paraConfig: { ...loaded.config, qmd: { ...loaded.config.qmd, embedEnabled: false } },
+          secretsPath: paths.secretsPath,
+        });
+        await closeStore(store);
+      }
+      changes.push("validated QMD SDK store");
+    } catch (err) {
+      warnings.push(`QMD SDK validation failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return {
+    dryRun: options.dryRun ?? false,
+    extensionRef,
+    configPath: paths.userConfigPath,
+    wikiDir: paths.wikiDir,
+    changes,
+    warnings,
+    migratedFromLegacy: loaded.migratedFromLegacy,
+  };
+}
+
+export function formatSetupResult(result: SetupResult): string {
+  const lines = [`pi-para setup ${result.dryRun ? "dry run " : ""}complete.`];
+  for (const change of result.changes) lines.push(`  ✓ ${change}`);
+  for (const warning of result.warnings) lines.push(`  ⚠ ${warning}`);
+  lines.push("", "Next: restart open Pi sessions, then run /wiki or pi-para doctor.");
+  return lines.join("\n");
+}
+
+export function resolveExtensionRef(localPath?: string): string {
+  if (!localPath) return "npm:pi-para";
+  return resolvePath(localPath, process.cwd());
+}
+
+export async function ensurePiExtensionRegistration(
+  settingsPath: string,
+  extensionRef: string,
+  opts: { dryRun?: boolean } = {},
+): Promise<{ changed: boolean; packages: string[] }> {
+  const settings = readPiSettings(settingsPath);
+  const packages = Array.isArray(settings.packages) ? settings.packages.map(String) : [];
+  if (packages.includes(extensionRef)) return { changed: false, packages };
+
+  const nextPackages = [...packages, extensionRef];
+  settings.packages = nextPackages;
+  if (!opts.dryRun) {
+    await mkdir(dirname(settingsPath), { recursive: true });
+    await atomicWriteFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 0o600);
+  }
+  return { changed: true, packages: nextPackages };
+}
+
+function readPiSettings(settingsPath: string): Record<string, unknown> {
+  if (!existsSync(settingsPath)) return {};
+  return JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
+}
+
+export function summarizeSetupConfig(loaded: LoadedParaConfig): string {
+  return `config=${loaded.sourcePath} wiki=${loaded.config.wiki.dir}`;
+}