@firstpick/pi-utils 0.1.8 → 0.2.0

package/README.md

@@ -26,8 +26,17 @@ Shared helper utilities used by `@firstpick/pi-extension-*` packages.
 - `buildInitialPromptCalibrationRecord(args)`
 - `appendInitialPromptCalibrationRecord(appendEntry, record)`
 - `delay(ms)`
+- `tokenizeArgs(input)` / `takeValue(tokens, index, flag)`
+- `readJsonFile(path)` / `readJsonIfExists(path, fallback)` / `writeJsonFile(path, data)`
+- `runCommand(command, args, options?)` / `runShellCommand(cwd, command, options?)`
+- `shellQuote(value)` / `stripAnsi(input)` / `resolveExecutableFromPath(name)`
+- `jsonToolResult(payload)` / `textToolResult(text, details?)`
+- `createRunLog(cwd)` / `appendRunLog(log, chunk)` / `saveRunLog(log, options)` / `listRunLogs(dir)`
+- `parseChecklistLine(line)` / `extractChecklist(text)` / `stripChecklistLines(text)` / `countChecklistProgress(textOrItems)`
+- `expandTilde(input)` / `resolveUserPath(input, cwd?)` / `safeResolveInside(base, ref)` / `formatUserPath(path)`
 - `createExtensionWorkingIndicator(ctx, initialMessage, options?)`
 - `withExtensionWorkingIndicator(ctx, initialMessage, run, options?)`
+- `appendDisplayChunk(lines, chunk)` / `outputLinesFromDisplay(lines)` / `formatElapsed(startMs)`
 - `createLocalWikiEngine(config)`
 
 `createExtensionWorkingIndicator` renders a reusable extension-owned spinner using `ctx.ui.setWidget` plus footer `setStatus`, so it works inside slash-command handlers where Pi's built-in model-streaming working row is not shown.

package/index.ts

@@ -4,8 +4,17 @@ export * from "./src/text";
 export * from "./src/tokens";
 export * from "./src/prompt-calibration";
 export * from "./src/prompt-export-estimate";
+export * from "./src/initial-prompt-estimate-state";
+export * from "./src/initial-prompt-estimate-service";
 export * from "./src/async";
+export * from "./src/cli";
+export * from "./src/json";
+export * from "./src/process";
+export * from "./src/tool-result";
+export * from "./src/markdown";
+export * from "./src/release-log";
 export * from "./src/ui/working-indicator";
+export * from "./src/ui/live-output";
 export * from "./src/local-wiki";
 
 export { default } from "./src/extension";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-utils",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Shared utilities for Firstpick Pi extension packages.",
   "main": "index.ts",
   "exports": {
@@ -11,11 +11,25 @@
     "./tokens": "./src/tokens.ts",
     "./prompt-calibration": "./src/prompt-calibration.ts",
     "./prompt-export-estimate": "./src/prompt-export-estimate.ts",
+    "./initial-prompt-estimate-state": "./src/initial-prompt-estimate-state.ts",
+    "./initial-prompt-estimate-service": "./src/initial-prompt-estimate-service.ts",
     "./async": "./src/async.ts",
+    "./cli": "./src/cli.ts",
+    "./json": "./src/json.ts",
+    "./process": "./src/process.ts",
+    "./tool-result": "./src/tool-result.ts",
+    "./markdown": "./src/markdown.ts",
+    "./release-log": "./src/release-log.ts",
     "./ui": "./src/ui/working-indicator.ts",
+    "./ui/live-output": "./src/ui/live-output.ts",
     "./local-wiki": "./src/local-wiki.ts"
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Firstp1ck/npm-packages.git",
+    "directory": "pi-utils"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -27,6 +41,10 @@
       "./index.ts"
     ]
   },
+  "scripts": {
+    "check": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types tests/initial-prompt-estimate-state.test.mjs",
+    "test": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types tests/initial-prompt-estimate-state.test.mjs"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },

package/src/cli.ts

@@ -0,0 +1,56 @@
+export function tokenizeArgs(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | undefined;
+  let escaped = false;
+
+  for (const char of input) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else current += char;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escaped) current += "\\";
+  if (quote) throw new Error(`Unclosed ${quote} quote`);
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+export function takeValue(tokens: string[], index: number, flag: string): string {
+  const value = tokens[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+export function takeOptionalValue(tokens: string[], index: number): string | undefined {
+  const value = tokens[index + 1];
+  return value && !value.startsWith("--") ? value : undefined;
+}

package/src/initial-prompt-estimate-service.ts

@@ -0,0 +1,202 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { InitialPromptCalibration, InitialPromptInputEstimate, InitialPromptToolInfo } from "./tokens";
+import {
+  estimateInitialPromptForPiContext,
+  estimateInitialPromptFromPiExport,
+  getActiveInitialPromptToolInfos,
+  type ExportBackedInitialPromptEstimate,
+} from "./prompt-export-estimate";
+import {
+  buildInitialPromptEstimateKey,
+  resolveInitialPromptEstimateRefreshDecision,
+} from "./initial-prompt-estimate-state";
+
+export type InitialPromptEstimatePiApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools">;
+export type InitialPromptEstimateContext = Pick<ExtensionContext, "getSystemPrompt" | "sessionManager">;
+export type InitialPromptEstimateSource = ExportBackedInitialPromptEstimate["source"] | "fallback";
+
+export type InitialPromptEstimateSnapshot = {
+  key: string;
+  estimate: InitialPromptInputEstimate;
+  systemPrompt: string;
+  tools: InitialPromptToolInfo[];
+  source: InitialPromptEstimateSource;
+  settled: boolean;
+  attempts: number;
+  warning?: string;
+};
+
+export type InitialPromptCalibrationGetter<Ctx extends InitialPromptEstimateContext> = (
+  ctx: Ctx,
+) => InitialPromptCalibration | null | undefined;
+
+export type StableInitialPromptEstimateOptions = {
+  maxAttempts?: number;
+};
+
+export type InitialPromptEstimateServiceOptions<Ctx extends InitialPromptEstimateContext> = StableInitialPromptEstimateOptions & {
+  pi: InitialPromptEstimatePiApi;
+  getCalibration: InitialPromptCalibrationGetter<Ctx>;
+  /** Publish provisional fallback snapshots while export-backed estimation is still running. */
+  publishFallback?: boolean;
+  onUpdate?: (snapshot: InitialPromptEstimateSnapshot, ctx: Ctx) => void;
+};
+
+export type InitialPromptEstimateRefreshResult =
+  | { status: "updated"; snapshot: InitialPromptEstimateSnapshot }
+  | { status: "unsettled"; snapshot: InitialPromptEstimateSnapshot }
+  | { status: "stale"; snapshot: null };
+
+const DEFAULT_STABLE_ESTIMATE_ATTEMPTS = 3;
+
+function resolveMaxAttempts(value: number | undefined): number {
+  const attempts = Math.floor(Number(value ?? DEFAULT_STABLE_ESTIMATE_ATTEMPTS));
+  return Number.isFinite(attempts) && attempts > 0 ? attempts : DEFAULT_STABLE_ESTIMATE_ATTEMPTS;
+}
+
+function appendWarning(existing: string | undefined, warning: string): string {
+  return existing ? `${existing} ${warning}` : warning;
+}
+
+export function buildInitialPromptFallbackSnapshot(
+  pi: InitialPromptEstimatePiApi,
+  ctx: InitialPromptEstimateContext,
+  calibration?: InitialPromptCalibration | null,
+  attempts = 0,
+): InitialPromptEstimateSnapshot {
+  const systemPrompt = ctx.getSystemPrompt();
+  const tools = getActiveInitialPromptToolInfos(pi);
+  const estimate = estimateInitialPromptForPiContext(pi, systemPrompt, calibration, tools);
+  return {
+    key: buildInitialPromptEstimateKey(estimate),
+    estimate,
+    systemPrompt,
+    tools,
+    source: "fallback",
+    settled: false,
+    attempts,
+  };
+}
+
+function snapshotFromExportEstimate(
+  key: string,
+  promptEstimate: ExportBackedInitialPromptEstimate,
+  attempts: number,
+): InitialPromptEstimateSnapshot {
+  return {
+    key,
+    estimate: promptEstimate.estimate,
+    systemPrompt: promptEstimate.systemPrompt,
+    tools: promptEstimate.tools,
+    source: promptEstimate.source,
+    settled: true,
+    attempts,
+    warning: promptEstimate.warning,
+  };
+}
+
+export async function estimateStableInitialPromptFromPiContext<Ctx extends InitialPromptEstimateContext>(
+  pi: InitialPromptEstimatePiApi,
+  ctx: Ctx,
+  getCalibration: InitialPromptCalibrationGetter<Ctx>,
+  options: StableInitialPromptEstimateOptions = {},
+): Promise<InitialPromptEstimateSnapshot> {
+  const maxAttempts = resolveMaxAttempts(options.maxAttempts);
+  let latestFallback = buildInitialPromptFallbackSnapshot(pi, ctx, getCalibration(ctx) ?? null, 0);
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const calibration = getCalibration(ctx) ?? null;
+    const fallback = buildInitialPromptFallbackSnapshot(pi, ctx, calibration, attempt - 1);
+    const promptEstimate = await estimateInitialPromptFromPiExport(pi, ctx, calibration);
+    latestFallback = buildInitialPromptFallbackSnapshot(pi, ctx, getCalibration(ctx) ?? null, attempt);
+
+    const decision = resolveInitialPromptEstimateRefreshDecision({
+      requestId: attempt,
+      currentRequestId: attempt,
+      initialKey: fallback.key,
+      latestKey: latestFallback.key,
+    });
+    if (decision === "accept-exported-estimate") {
+      return snapshotFromExportEstimate(fallback.key, promptEstimate, attempt);
+    }
+  }
+
+  return {
+    ...latestFallback,
+    attempts: maxAttempts,
+    warning: appendWarning(
+      latestFallback.warning,
+      "Initial prompt inputs changed while estimating; used live context fallback.",
+    ),
+  };
+}
+
+export function createInitialPromptEstimateService<Ctx extends InitialPromptEstimateContext>(
+  options: InitialPromptEstimateServiceOptions<Ctx>,
+) {
+  let snapshot: InitialPromptEstimateSnapshot | null = null;
+  let activeRequestId = 0;
+
+  const publish = (nextSnapshot: InitialPromptEstimateSnapshot, ctx: Ctx): InitialPromptEstimateSnapshot => {
+    snapshot = nextSnapshot;
+    options.onUpdate?.(nextSnapshot, ctx);
+    return nextSnapshot;
+  };
+
+  const getFallbackSnapshot = (ctx: Ctx, attempts = 0): InitialPromptEstimateSnapshot => {
+    return buildInitialPromptFallbackSnapshot(options.pi, ctx, options.getCalibration(ctx) ?? null, attempts);
+  };
+
+  const refresh = async (ctx: Ctx): Promise<InitialPromptEstimateRefreshResult> => {
+    const requestId = ++activeRequestId;
+    const maxAttempts = resolveMaxAttempts(options.maxAttempts);
+    let latestFallback = getFallbackSnapshot(ctx, 0);
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const calibration = options.getCalibration(ctx) ?? null;
+      const fallback = buildInitialPromptFallbackSnapshot(options.pi, ctx, calibration, attempt - 1);
+      latestFallback = fallback;
+      if (options.publishFallback) publish(fallback, ctx);
+
+      const promptEstimate = await estimateInitialPromptFromPiExport(options.pi, ctx, calibration);
+      latestFallback = getFallbackSnapshot(ctx, attempt);
+
+      const decision = resolveInitialPromptEstimateRefreshDecision({
+        requestId,
+        currentRequestId: activeRequestId,
+        initialKey: fallback.key,
+        latestKey: latestFallback.key,
+      });
+      if (decision === "ignore-stale-request") return { status: "stale", snapshot: null };
+      if (decision === "restart-inputs-changed") continue;
+
+      return {
+        status: "updated",
+        snapshot: publish(snapshotFromExportEstimate(fallback.key, promptEstimate, attempt), ctx),
+      };
+    }
+
+    const unsettled = {
+      ...latestFallback,
+      attempts: maxAttempts,
+      warning: appendWarning(
+        latestFallback.warning,
+        "Initial prompt inputs changed while estimating; kept the previous settled estimate.",
+      ),
+    };
+    if (options.publishFallback) publish(unsettled, ctx);
+    return { status: "unsettled", snapshot: unsettled };
+  };
+
+  return {
+    clear() {
+      activeRequestId++;
+      snapshot = null;
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    getFallbackSnapshot,
+    refresh,
+  };
+}

package/src/initial-prompt-estimate-state.ts

@@ -0,0 +1,48 @@
+export type InitialPromptEstimateRefreshDecision =
+  | "accept-exported-estimate"
+  | "ignore-stale-request"
+  | "restart-inputs-changed";
+
+export type InitialPromptEstimateRefreshDecisionInput = {
+  requestId: number;
+  currentRequestId: number;
+  initialKey: string;
+  latestKey: string;
+};
+
+export type InitialPromptEstimateKeyInput = {
+  uncalibratedTotal: number;
+  promptText: number;
+  toolSchemas: number;
+  framing: number;
+  toolCount: number;
+  calibrationMultiplier: number;
+  calibrationSamples: number;
+  low: number;
+  high: number;
+};
+
+export function buildInitialPromptEstimateKey(estimate: InitialPromptEstimateKeyInput): string {
+  return [
+    estimate.uncalibratedTotal,
+    estimate.promptText,
+    estimate.toolSchemas,
+    estimate.framing,
+    estimate.toolCount,
+    estimate.calibrationMultiplier,
+    estimate.calibrationSamples,
+    estimate.low,
+    estimate.high,
+  ].join(":");
+}
+
+export function resolveInitialPromptEstimateRefreshDecision({
+  requestId,
+  currentRequestId,
+  initialKey,
+  latestKey,
+}: InitialPromptEstimateRefreshDecisionInput): InitialPromptEstimateRefreshDecision {
+  if (requestId !== currentRequestId) return "ignore-stale-request";
+  if (latestKey !== initialKey) return "restart-inputs-changed";
+  return "accept-exported-estimate";
+}

package/src/json.ts

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function readJsonFile<T = unknown>(filePath: string): T {
+  return JSON.parse(fs.readFileSync(filePath, "utf8")) as T;
+}
+
+export function readJsonIfExists<T>(filePath: string, fallback: T): T {
+  if (!fs.existsSync(filePath)) return fallback;
+  return readJsonFile<T>(filePath);
+}
+
+export function writeJsonFile(filePath: string, data: unknown, options: { mode?: number } = {}): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8", mode: options.mode });
+}
+
+export async function readJsonFileAsync<T = unknown>(filePath: string): Promise<T> {
+  return JSON.parse(await fs.promises.readFile(filePath, "utf8")) as T;
+}
+
+export async function readJsonIfExistsAsync<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    return await readJsonFileAsync<T>(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+export async function writeJsonFileAsync(filePath: string, data: unknown, options: { mode?: number } = {}): Promise<void> {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.promises.writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8", mode: options.mode });
+}

package/src/local-wiki.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fsp from "node:fs/promises";
 
-export type LocalWikiFormat = "markdown" | "html";
+export type LocalWikiFormat = "markdown" | "html" | "asciidoc";
 
 export interface LocalWikiSection {
   title: string;
@@ -68,6 +68,9 @@ export interface LocalWikiEngineConfig {
   statusExtra?: () => Promise<Record<string, unknown>>;
   transformText?: (text: string, title: string, filePath: string) => string;
   titleFromHtml?: (html: string, filePath: string, fallback: string) => string;
+  /** Expand AsciiDoc include:: directives before parsing text/sections. Defaults to true for asciidoc format. */
+  expandIncludes?: boolean;
+  maxIncludeDepth?: number;
 }
 
 export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
@@ -130,6 +133,31 @@ export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
       .trim();
   }
 
+  function stripAsciidocDecorators(input: string): string {
+    return input
+      .replace(/^={1,6}\s+/, "")
+      .replace(/^\[\[[^\]]+\]\]\s*/, "")
+      .replace(/xref:([^\[]+)\[([^\]]*)\]/g, (_m, target: string, label: string) => label || titleFromPath(target))
+      .replace(/https?:[^\[]+\[([^\]]+)\]/g, "$1")
+      .replace(/(?:kbd|btn|menu):\[([^\]]+)\]/g, "$1")
+      .replace(/[*_`]/g, "")
+      .trim();
+  }
+
+  function asciidocToText(asciidoc: string): string {
+    return normalizeWhitespace(asciidoc
+      .replace(/^\s*:[^:\n]+:.*$/gm, "")
+      .replace(/^\s*\/\/.*$/gm, "")
+      .replace(/^\[\[[^\]]+\]\]\s*$/gm, "")
+      .replace(/^\[(?:source|console|bash|python|json|ini|subs|NOTE|TIP|IMPORTANT|WARNING|CAUTION)[^\]]*\]\s*$/gim, "")
+      .replace(/^(?:----|====|\+{4}|`{3})\s*$/gm, "")
+      .replace(/^image::[^\[]+\[[^\]]*\]\s*$/gm, "")
+      .replace(/include::([^\[]+)\[[^\]]*\]/g, "")
+      .replace(/xref:([^\[]+)\[([^\]]*)\]/g, (_m, target: string, label: string) => label || titleFromPath(target))
+      .replace(/https?:[^\[]+\[([^\]]+)\]/g, "$1")
+      .replace(/(?:kbd|btn|menu):\[([^\]]+)\]/g, "$1"));
+  }
+
   function stripYamlFrontmatter(markdown: string): string {
     return markdown.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
   }
@@ -195,6 +223,33 @@ export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
     return sections;
   }
 
+  function asciidocTitle(asciidoc: string, filePath: string): string {
+    for (const line of asciidoc.split(/\n/)) {
+      const match = line.match(/^(={1,6})\s+(.+)$/);
+      if (match) return stripAsciidocDecorators(match[2]);
+    }
+    return titleFromPath(filePath);
+  }
+
+  function asciidocSections(asciidoc: string, fallbackTitle: string): LocalWikiSection[] {
+    const sections: LocalWikiSection[] = [];
+    let current: LocalWikiSection | undefined;
+    for (const line of asciidoc.split(/\n/)) {
+      const match = line.match(/^(={1,6})\s+(.+)$/);
+      if (match) {
+        if (current) current.text = asciidocToText(current.text);
+        const title = stripAsciidocDecorators(match[2]);
+        current = { title, level: match[1].length, anchor: anchorFromHeading(title), text: "" };
+        sections.push(current);
+        continue;
+      }
+      if (current) current.text += `${line}\n`;
+    }
+    if (!current) sections.push({ title: fallbackTitle, level: 1, anchor: anchorFromHeading(fallbackTitle), text: asciidocToText(asciidoc) });
+    else current.text = asciidocToText(current.text);
+    return sections;
+  }
+
   function htmlToText(html: string): string {
     let body = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i)?.[1] ?? html;
     body = body.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ");
@@ -215,15 +270,35 @@ export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
     return (config.titleFromHtml?.(html, filePath, fallback) ?? stripTags(html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? "")) || fallback;
   }
 
+  function candidateLocalPaths(currentFile: string, href: string): string[] {
+    if (/^(https?:|mailto:|#)/i.test(href)) return [];
+    const cleanHref = decodeEntities(href).split("#")[0].split("?")[0].trim();
+    if (!cleanHref) return [];
+    const variants = [...new Set([cleanHref, cleanHref.replace(/^\.\/+/g, "")].filter(Boolean))];
+    const expand = (candidate: string): string[] => {
+      if (path.extname(candidate)) return [candidate];
+      if (config.format === "html") return [`${candidate}.html`, `${candidate}.htm`, path.join(candidate, "index.html")];
+      if (config.format === "asciidoc") return [`${candidate}.adoc`, `${candidate}.asciidoc`, `${candidate}.asc`, path.join(candidate, "index.adoc")];
+      return [`${candidate}.md`, `${candidate}.mdx`, `${candidate}.rst`, path.join(candidate, "index.md")];
+    };
+    const bases = [path.dirname(currentFile), path.dirname(path.dirname(currentFile)), config.docsPath];
+    const resolved: string[] = [];
+    for (const variant of variants) {
+      for (const expanded of expand(variant)) {
+        if (path.isAbsolute(expanded)) resolved.push(path.normalize(expanded));
+        for (const base of bases) resolved.push(path.normalize(path.resolve(base, expanded)));
+      }
+    }
+    return [...new Set(resolved)].filter((candidate) => candidate === config.docsPath || candidate.startsWith(`${config.docsPath}${path.sep}`));
+  }
+
   function resolveLocalPath(currentFile: string, href: string): string | undefined {
-    if (/^(https?:|mailto:|#)/i.test(href)) return undefined;
-    const cleanHref = decodeEntities(href).split("#")[0].split("?")[0];
-    if (!cleanHref) return undefined;
-    const ext = config.format === "html" ? ".html" : ".md";
-    const candidates = path.extname(cleanHref) ? [cleanHref] : [cleanHref + ext, `${cleanHref}.mdx`, `${cleanHref}.rst`, path.join(cleanHref, "index.md")];
-    for (const candidate of candidates) {
-      const resolved = path.normalize(path.resolve(path.dirname(currentFile), candidate));
-      if (resolved.startsWith(config.docsPath)) return resolved;
+    return candidateLocalPaths(currentFile, href)[0];
+  }
+
+  async function resolveExistingLocalPath(currentFile: string, href: string): Promise<string | undefined> {
+    for (const candidate of candidateLocalPaths(currentFile, href)) {
+      if (await localExists(candidate)) return candidate;
     }
     return undefined;
   }
@@ -238,6 +313,38 @@ export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
     return [...links.values()];
   }
 
+  function asciidocLinks(asciidoc: string, currentFile: string): LocalWikiLink[] {
+    const links = new Map<string, LocalWikiLink>();
+    const add = (href: string, label: string) => {
+      const resolved = resolveLocalPath(currentFile, href.trim());
+      if (!resolved) return;
+      links.set(resolved, { title: stripAsciidocDecorators(label) || titleFromPath(resolved), path: resolved });
+    };
+    for (const match of asciidoc.matchAll(/xref:([^\[]+)\[([^\]]*)\]/g)) add(match[1], match[2]);
+    for (const match of asciidoc.matchAll(/^include::([^\[]+)\[([^\]]*)\]/gm)) add(match[1], match[2]);
+    return [...links.values()];
+  }
+
+  async function expandAsciidocIncludes(raw: string, currentFile: string, depth = 0, seen = new Set<string>()): Promise<string> {
+    const maxDepth = Math.max(0, config.maxIncludeDepth ?? 4);
+    if (depth >= maxDepth) return raw;
+    const includeRe = /^include::([^\[]+)\[[^\]]*\]\s*$/gm;
+    const replacements = await Promise.all([...raw.matchAll(includeRe)].map(async (match) => {
+      const resolved = await resolveExistingLocalPath(currentFile, match[1].trim());
+      if (!resolved || seen.has(resolved)) return { from: match[0], to: "" };
+      try {
+        seen.add(resolved);
+        const included = await fsp.readFile(resolved, "utf8");
+        return { from: match[0], to: await expandAsciidocIncludes(included, resolved, depth + 1, seen) };
+      } catch {
+        return { from: match[0], to: "" };
+      }
+    }));
+    let expanded = raw;
+    for (const { from, to } of replacements) expanded = expanded.replace(from, to);
+    return expanded;
+  }
+
   function htmlLinks(html: string, currentFile: string): LocalWikiLink[] {
     const links = new Map<string, LocalWikiLink>();
     for (const match of html.matchAll(/<a\s+[^>]*href=["']([^"'#?]+)(?:#[^"']*)?["'][^>]*>([\s\S]*?)<\/a>/gi)) {
@@ -248,13 +355,29 @@ export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
     return [...links.values()];
   }
 
-  function parsePage(raw: string, filePath: string, mtimeMs: number): LocalWikiPage {
-    const title = config.format === "html" ? htmlTitle(raw, filePath) : markdownTitle(raw, filePath);
-    const markdownBody = config.format === "html" ? raw : stripYamlFrontmatter(raw);
-    const baseText = config.format === "html" ? htmlToText(raw) : normalizeWhitespace(markdownBody);
+  function parsePage(raw: string, filePath: string, mtimeMs: number, sourceRaw = raw): LocalWikiPage {
+    if (config.format === "html") {
+      const title = htmlTitle(sourceRaw, filePath);
+      const baseText = htmlToText(raw);
+      const text = config.transformText?.(baseText, title, filePath) ?? baseText;
+      const sections = markdownSections(text, title);
+      return { title, slug: path.relative(config.docsPath, filePath).replace(config.fileExtensions, ""), path: filePath, source: config.sourceName?.(filePath, config.docsPath), headings: sections.map((s) => s.title), sections, links: htmlLinks(sourceRaw, filePath), text, mtimeMs };
+    }
+
+    if (config.format === "asciidoc") {
+      const title = asciidocTitle(sourceRaw, filePath);
+      const baseText = asciidocToText(raw);
+      const text = config.transformText?.(baseText, title, filePath) ?? baseText;
+      const sections = asciidocSections(raw, title);
+      return { title, slug: path.relative(config.docsPath, filePath).replace(config.fileExtensions, ""), path: filePath, source: config.sourceName?.(filePath, config.docsPath), headings: sections.map((s) => s.title), sections, links: asciidocLinks(sourceRaw, filePath), text, mtimeMs };
+    }
+
+    const title = markdownTitle(sourceRaw, filePath);
+    const markdownBody = stripYamlFrontmatter(raw);
+    const baseText = normalizeWhitespace(markdownBody);
     const text = config.transformText?.(baseText, title, filePath) ?? baseText;
     const sections = markdownSections(text, title);
-    return { title, slug: path.relative(config.docsPath, filePath).replace(config.fileExtensions, ""), path: filePath, source: config.sourceName?.(filePath, config.docsPath), headings: sections.map((s) => s.title), sections, links: config.format === "html" ? htmlLinks(raw, filePath) : markdownLinks(markdownBody, filePath), text, mtimeMs };
+    return { title, slug: path.relative(config.docsPath, filePath).replace(config.fileExtensions, ""), path: filePath, source: config.sourceName?.(filePath, config.docsPath), headings: sections.map((s) => s.title), sections, links: markdownLinks(markdownBody, filePath), text, mtimeMs };
   }
 
   function limitText(text: string, maxChars = 12000): { text: string; truncated: boolean } {
@@ -270,7 +393,10 @@ export function createLocalWikiEngine(config: LocalWikiEngineConfig) {
     for (const file of files) {
       const stat = await fsp.stat(file);
       newestMtimeMs = Math.max(newestMtimeMs, stat.mtimeMs);
-      pages.push(parsePage(await fsp.readFile(file, "utf8"), file, stat.mtimeMs));
+      const raw = await fsp.readFile(file, "utf8");
+      const shouldExpandIncludes = config.format === "asciidoc" && config.expandIncludes !== false;
+      const expanded = shouldExpandIncludes ? await expandAsciidocIncludes(raw, file) : raw;
+      pages.push(parsePage(expanded, file, stat.mtimeMs, raw));
     }
     const metadata: LocalWikiCacheMetadata = { schemaVersion, docsPath: config.docsPath, generatedAt: new Date().toISOString(), pageCount: pages.length, newestMtimeMs, extra: await config.metadataExtra?.() };
     await fsp.writeFile(pagesCache, JSON.stringify(pages, null, 2));

package/src/markdown.ts

@@ -0,0 +1,77 @@
+export type ChecklistStatus = "todo" | "partial" | "done";
+
+export type ChecklistItem = {
+  text: string;
+  status: ChecklistStatus;
+};
+
+export type ChecklistProgress = {
+  total: number;
+  done: number;
+  partial: number;
+  remaining: number;
+};
+
+export const CHECKLIST_LINE_REGEX = /^\s*(?:(?:[-*]|\d+[.)])\s*)?\[( |x|X|-)\]\s+(.+)$/;
+
+export function parseChecklistLine(line: string): ChecklistItem | undefined {
+  const match = CHECKLIST_LINE_REGEX.exec(line);
+  if (!match) return undefined;
+
+  const mark = (match[1] || " ").toLowerCase();
+  const label = (match[2] || "").trim().replace(/\s+/g, " ");
+  if (!label) return undefined;
+
+  return {
+    status: mark === "x" ? "done" : mark === "-" ? "partial" : "todo",
+    text: label,
+  };
+}
+
+export function extractChecklist(text: string): ChecklistItem[] {
+  const checklist: ChecklistItem[] = [];
+  let inFence = false;
+
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const item = parseChecklistLine(line);
+    if (item) checklist.push(item);
+  }
+
+  return checklist;
+}
+
+export function stripChecklistLines(text: string): string {
+  let inFence = false;
+  const kept: string[] = [];
+
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      kept.push(line);
+      continue;
+    }
+
+    if (!inFence && parseChecklistLine(line)) continue;
+    kept.push(line);
+  }
+
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+export function countChecklistProgress(textOrItems: string | ChecklistItem[]): ChecklistProgress {
+  const items = typeof textOrItems === "string" ? extractChecklist(textOrItems) : textOrItems;
+  const done = items.filter((item) => item.status === "done").length;
+  const partial = items.filter((item) => item.status === "partial").length;
+  return {
+    total: items.length,
+    done,
+    partial,
+    remaining: Math.max(0, items.length - done),
+  };
+}

package/src/paths.ts

@@ -26,3 +26,41 @@ export function getAgentSettingsPath(): string {
 export function getWorkspaceEnvPath(cwd = process.cwd()): string {
   return path.join(cwd, ".env");
 }
+
+export function expandTilde(input: string, homeDir = os.homedir()): string {
+  if (input === "~") return homeDir;
+  if (input.startsWith("~/")) return path.join(homeDir, input.slice(2));
+  if (input === "$HOME") return homeDir;
+  if (input.startsWith("$HOME/")) return path.join(homeDir, input.slice(6));
+  return input;
+}
+
+export function stripAtPathPrefix(input: string): string {
+  return input.trim().replace(/^@+/, "");
+}
+
+export function resolveUserPath(input: string, cwd = process.cwd(), options: { stripAtPrefix?: boolean } = {}): string {
+  const cleaned = options.stripAtPrefix === false ? input.trim() : stripAtPathPrefix(input);
+  const expanded = expandTilde(cleaned);
+  return path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(cwd, expanded);
+}
+
+export function isPathInside(basePath: string, candidatePath: string): boolean {
+  const relative = path.relative(path.resolve(basePath), path.resolve(candidatePath));
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function safeResolveInside(basePath: string, reference: string): string {
+  const base = path.resolve(basePath);
+  const candidate = resolveUserPath(reference, base);
+  if (!isPathInside(base, candidate)) throw new Error(`Path escapes base directory: ${reference}`);
+  return candidate;
+}
+
+export function formatUserPath(filePath: string, homeDir = os.homedir()): string {
+  const normalized = path.resolve(filePath);
+  const home = path.resolve(homeDir);
+  if (normalized === home) return "~";
+  if (normalized.startsWith(`${home}${path.sep}`)) return `~/${normalized.slice(home.length + 1).split(path.sep).join("/")}`;
+  return normalized;
+}

package/src/process.ts

@@ -0,0 +1,152 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile, spawn, type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+
+export const ANSI_ESCAPE_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+
+export type CommandResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode?: number;
+  signal?: NodeJS.Signals | null;
+  error?: string;
+  timedOut?: boolean;
+};
+
+export type RunCommandOptions = {
+  cwd?: string;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+  maxStdoutChars?: number;
+  maxStderrChars?: number;
+};
+
+export type AbortableProcess = ChildProcessByStdio<null, Readable, Readable> & {
+  abortProcessGroup?: () => void;
+  abortReleaseStep?: () => void;
+};
+
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export function stripAnsi(input: string): string {
+  return input.replace(ANSI_ESCAPE_RE, "");
+}
+
+export function resolveExecutableFromPath(binName: string, envPath = process.env.PATH ?? ""): string | undefined {
+  const candidates = os.platform() === "win32" && !binName.toLowerCase().endsWith(".exe") ? [binName, `${binName}.exe`] : [binName];
+  for (const dir of envPath.split(path.delimiter).filter(Boolean)) {
+    for (const name of candidates) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+export async function commandExists(command: string, args: string[] = ["--version"], timeoutMs = 3000): Promise<boolean> {
+  const result = await runCommand(command, args, { timeoutMs });
+  return result.ok;
+}
+
+function trimBuffer(value: string, maxChars: number | undefined): string {
+  if (!maxChars || value.length <= maxChars) return value;
+  return value.slice(-maxChars);
+}
+
+export function runCommand(command: string, args: string[] = [], options: RunCommandOptions = {}): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    const child = execFile(command, args, { cwd: options.cwd, env: options.env, timeout: options.timeoutMs }, (error, stdout, stderr) => {
+      const exitCode = error && "code" in error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+      resolve({
+        ok: !error,
+        stdout: trimBuffer(String(stdout ?? ""), options.maxStdoutChars),
+        stderr: trimBuffer(String(stderr ?? ""), options.maxStderrChars),
+        exitCode,
+        signal: error && "signal" in error ? (error.signal as NodeJS.Signals | null) : null,
+        error: error instanceof Error ? error.message : undefined,
+        timedOut: error && "killed" in error ? Boolean(error.killed) : false,
+      });
+    });
+    child.on("error", (error) => {
+      resolve({ ok: false, stdout: "", stderr: "", error: error.message, exitCode: 1 });
+    });
+  });
+}
+
+export function runShellCommand(cwd: string, command: string, options: RunCommandOptions = {}): Promise<CommandResult> {
+  return runCommand("bash", ["-lc", command], { ...options, cwd });
+}
+
+export function runLiveShellCommand(args: {
+  cwd: string;
+  command: string;
+  onChunk: (chunk: string) => void;
+  onChild?: (child: AbortableProcess) => void;
+  timeoutMs?: number;
+  detached?: boolean;
+}): Promise<CommandResult & { output: string; aborted: boolean }> {
+  return new Promise((resolve) => {
+    const child = spawn("bash", ["-lc", args.command], {
+      cwd: args.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: args.detached ?? true,
+    }) as AbortableProcess;
+    let output = "";
+    let aborted = false;
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+
+    const abort = () => {
+      aborted = true;
+      try {
+        if (child.pid && child.pid > 0) process.kill(-child.pid, "SIGINT");
+      } catch {
+        child.kill("SIGINT");
+      }
+      setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) {
+          try {
+            if (child.pid && child.pid > 0) process.kill(-child.pid, "SIGTERM");
+          } catch {
+            child.kill("SIGTERM");
+          }
+        }
+      }, 1500).unref();
+    };
+    child.abortProcessGroup = abort;
+    child.abortReleaseStep = abort;
+
+    const finish = (result: CommandResult & { output: string; aborted: boolean }) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+
+    if (args.timeoutMs && args.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        abort();
+        finish({ ok: false, stdout: output, stderr: "", output, aborted: true, timedOut: true });
+      }, args.timeoutMs);
+    }
+
+    args.onChild?.(child);
+    child.stdout.on("data", (d) => {
+      const chunk = String(d);
+      output += chunk;
+      args.onChunk(chunk);
+    });
+    child.stderr.on("data", (d) => {
+      const chunk = String(d);
+      output += chunk;
+      args.onChunk(chunk);
+    });
+    child.on("error", (error) => finish({ ok: false, stdout: output, stderr: error.message, output, aborted, error: error.message }));
+    child.on("close", (code, signal) => finish({ ok: code === 0 && !aborted, stdout: output, stderr: "", output, aborted, exitCode: code ?? undefined, signal }));
+  });
+}

package/src/release-log.ts

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type RunLog = {
+  id: string;
+  startedAt: string;
+  cwd: string;
+  chunks: string[];
+  saved: boolean;
+};
+
+export type RunLogEntry = {
+  file: string;
+  title: string;
+  mtimeMs: number;
+};
+
+export function sanitizeLogId(value: string): string {
+  return value.replace(/[^0-9A-Za-z._-]/g, "-");
+}
+
+export function createRunLog(cwd: string, now = new Date()): RunLog {
+  const startedAt = now.toISOString();
+  return { id: sanitizeLogId(startedAt), startedAt, cwd, chunks: [], saved: false };
+}
+
+export function appendRunLog(runLog: RunLog, chunk: string): void {
+  runLog.chunks.push(chunk);
+}
+
+export function saveRunLog(runLog: RunLog, args: { logDir: string; title: string; status: string; summary?: string; now?: Date }): string | undefined {
+  if (runLog.saved) return undefined;
+  runLog.saved = true;
+  try {
+    mkdirSync(args.logDir, { recursive: true });
+    const filePath = join(args.logDir, `${runLog.id}-${sanitizeLogId(args.status)}.log`);
+    const content = [
+      args.title,
+      `started_at=${runLog.startedAt}`,
+      `finished_at=${(args.now ?? new Date()).toISOString()}`,
+      `status=${args.status}`,
+      `cwd=${runLog.cwd}`,
+      args.summary ? `summary=${args.summary.replace(/\r?\n/g, " | ")}` : undefined,
+      "",
+      "--- output ---",
+      runLog.chunks.join(""),
+    ].filter((line): line is string => line !== undefined).join("\n");
+    writeFileSync(filePath, content, "utf8");
+    return filePath;
+  } catch {
+    return undefined;
+  }
+}
+
+export function listRunLogs(logDir: string): RunLogEntry[] {
+  if (!existsSync(logDir)) return [];
+  return readdirSync(logDir)
+    .filter((file) => file.endsWith(".log"))
+    .map((file) => {
+      const filePath = join(logDir, file);
+      const stat = statSync(filePath);
+      return { file: filePath, title: file.replace(/\.log$/, ""), mtimeMs: stat.mtimeMs };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}

package/src/tool-result.ts

@@ -0,0 +1,17 @@
+export type TextToolResult<T = unknown> = {
+  content: Array<{ type: "text"; text: string }>;
+  details?: T;
+  isError?: boolean;
+};
+
+export function textToolResult<T = unknown>(text: string, details?: T, options: { isError?: boolean } = {}): TextToolResult<T> {
+  return {
+    content: [{ type: "text", text }],
+    ...(details === undefined ? {} : { details }),
+    ...(options.isError === undefined ? {} : { isError: options.isError }),
+  };
+}
+
+export function jsonToolResult<T = unknown>(payload: T, options: { space?: number; isError?: boolean } = {}): TextToolResult<T> {
+  return textToolResult(JSON.stringify(payload, null, options.space ?? 2), payload, { isError: options.isError });
+}

package/src/ui/live-output.ts

@@ -0,0 +1,48 @@
+export function isCtrlO(data: string): boolean {
+  const key = data.toLowerCase();
+  return data === "\x0f" || key === "ctrl+o" || data === "\x1b[111;5u" || data === "\x1b[27;5;111~";
+}
+
+export function isCtrlC(data: string): boolean {
+  const key = data.toLowerCase();
+  return data === "\x03" || key === "ctrl+c" || data === "\x1b[99;5u" || data === "\x1b[27;5;99~";
+}
+
+export function appendDisplayChunk(lines: string[], chunk: string): void {
+  if (lines.length === 0) lines.push("");
+
+  for (let i = 0; i < chunk.length; i++) {
+    const char = chunk[i];
+    if (char === "\r") {
+      if (chunk[i + 1] === "\n") {
+        lines.push("");
+        i++;
+      } else {
+        lines[lines.length - 1] = "";
+      }
+      continue;
+    }
+    if (char === "\n") {
+      lines.push("");
+      continue;
+    }
+    lines[lines.length - 1] += char;
+  }
+}
+
+export function outputLinesFromDisplay(lines: string[]): string[] {
+  const visible = lines.slice();
+  while (visible.length > 0 && visible[visible.length - 1] === "") visible.pop();
+  return visible;
+}
+
+export function formatElapsed(startMs: number, nowMs = Date.now()): string {
+  const seconds = Math.max(0, Math.floor((nowMs - startMs) / 1000));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return minutes > 0 ? `${minutes}m${String(remainder).padStart(2, "0")}s` : `${remainder}s`;
+}
+
+export function truncateLine(line: string, width: number): string {
+  return line.length > width ? `${line.slice(0, Math.max(0, width - 1))}…` : line;
+}