@groeponline/pi-wishcraft 1.4.0 → 1.6.0

package/src/studio/actions.ts

@@ -0,0 +1,105 @@
+/**
+ * Studio action executor (U7). Wires the existing skill backend
+ * (templates, doctor) into a single action runner the Studio action pane
+ * calls. Destructive paths (overwrite) route through the supplied
+ * `confirm` callback so the action pane can render the same
+ * confirm step it already shows for delete/overwrite elsewhere.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  SkillNameError,
+  writeSkillFromTemplate,
+  type SkillTemplateId,
+} from "../extension/skills/skill-templates.ts";
+import { collectSkillDoctorInputs, diagnoseSkills } from "../extension/skills/skill-doctor.ts";
+
+export type StudioAction =
+  | {
+      type: "create";
+      name: string;
+      template: SkillTemplateId;
+      skillsRoot: string;
+    }
+  | {
+      type: "doctor";
+      cwd: string;
+    };
+
+export interface ActionContext {
+  confirm: (message: string) => Promise<boolean>;
+}
+
+export type ActionResultKind = "ok" | "error" | "declined";
+
+export interface ActionResult {
+  kind: ActionResultKind;
+  message: string;
+  filePath?: string;
+}
+
+export async function runStudioAction(
+  action: StudioAction,
+  ctx: ActionContext,
+): Promise<ActionResult> {
+  if (action.type === "create") {
+    return runCreate(action, ctx);
+  }
+  if (action.type === "doctor") {
+    return runDoctor(action);
+  }
+  return { kind: "error", message: `Unknown action` };
+}
+
+async function runCreate(
+  action: Extract<StudioAction, { type: "create" }>,
+  ctx: ActionContext,
+): Promise<ActionResult> {
+  const safe = action.name.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  if (!safe || safe === "-" || safe.includes("..")) {
+    return { kind: "error", message: `Invalid skill name: ${action.name}` };
+  }
+  const filePath = join(action.skillsRoot, safe, "SKILL.md");
+  if (existsSync(filePath)) {
+    const ok = await ctx.confirm(`Skill "${safe}" exists. Overwrite?`);
+    if (!ok) {
+      return { kind: "declined", message: `Cancelled: ${safe} unchanged`, filePath };
+    }
+    try {
+      // Atomic overwrite: the replacement is written to a temp file and
+      // renamed over SKILL.md only after it succeeds, so a failed write
+      // never destroys the existing skill.
+      writeSkillFromTemplate(safe, action.template, action.skillsRoot, {
+        overwrite: true,
+      });
+      return { kind: "ok", message: `Overwrote ${safe}`, filePath };
+    } catch (err) {
+      return { kind: "error", message: errorMessage(err) };
+    }
+  }
+  try {
+    writeSkillFromTemplate(safe, action.template, action.skillsRoot);
+    return { kind: "ok", message: `Created ${safe}`, filePath };
+  } catch (err) {
+    return { kind: "error", message: errorMessage(err) };
+  }
+}
+
+function runDoctor(action: Extract<StudioAction, { type: "doctor" }>): ActionResult {
+  const { entries, usage, contents } = collectSkillDoctorInputs(action.cwd);
+  const rows = diagnoseSkills(entries, usage, contents);
+  const ok = rows.filter((r) => r.status === "ok").length;
+  const warn = rows.filter((r) => r.status === "warn").length;
+  const fail = rows.filter((r) => r.status === "fail").length;
+  return {
+    kind: "ok",
+    message: `Doctor: ${rows.length} skills · ${ok} ok · ${warn} warn · ${fail} fail`,
+  };
+}
+
+function errorMessage(err: unknown): string {
+  if (err instanceof SkillNameError) return err.message;
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/studio/advice-pane.ts

@@ -0,0 +1,73 @@
+import { runAdvice, type RunAdviceOptions, type AdviseStreamProvider } from "./advise/engine.ts";
+
+export type AdvicePaneState = "idle" | "running" | "ok" | "unavailable";
+
+export interface AdvicePane {
+  state: AdvicePaneState;
+  text: string;
+  error: string | null;
+  run(opts: Omit<RunAdviceOptions, "onChunk" | "provider"> & {
+    provider: AdviseStreamProvider | null;
+    callbacks?: AdvicePaneCallbacks;
+  }): Promise<void>;
+  reset(): void;
+}
+
+export interface AdvicePaneCallbacks {
+  onChunk?: (text: string) => void;
+}
+
+export function createAdvicePane(): AdvicePane {
+  const pane: AdvicePane = {
+    state: "idle",
+    text: "",
+    error: null,
+    async run(opts) {
+      pane.state = "running";
+      pane.text = "";
+      pane.error = null;
+      const result = await runAdvice({
+        mode: opts.mode,
+        skillName: opts.skillName,
+        body: opts.body,
+        references: opts.references,
+        wiki: opts.wiki,
+        maxChars: opts.maxChars,
+        provider: opts.provider,
+        model: opts.model,
+        signal: opts.signal,
+        onChunk: (delta) => {
+          pane.text += delta;
+          opts.callbacks?.onChunk?.(delta);
+        },
+      });
+      if (result.kind === "ok") {
+        pane.state = "ok";
+        pane.error = null;
+      } else {
+        pane.state = "unavailable";
+        pane.error = result.reason;
+      }
+    },
+    reset() {
+      pane.state = "idle";
+      pane.text = "";
+      pane.error = null;
+    },
+  };
+  return pane;
+}
+
+// ponytail: typed `unknown` session — Studio wires the real session at call
+// time. Kept narrow to `appendUserMessage(string)` so we do not depend on
+// the full AgentSession shape (TUI imports, model registry, etc.).
+export interface AdviceSessionSink {
+  appendUserMessage(text: string): unknown;
+}
+
+export function advicePaneInsert(pane: AdvicePane, session: AdviceSessionSink): boolean {
+  if (pane.state !== "ok") return false;
+  if (pane.text.length === 0) return false;
+  session.appendUserMessage(pane.text);
+  return true;
+}

package/src/studio/advise/context.ts

@@ -0,0 +1,89 @@
+// ponytail: char-based cap; full token-aware budgeting needs a tokenizer that
+// we do not want to depend on. Document the ceiling and upgrade path.
+export interface AdviseContextSection {
+  name: string;
+  content: string;
+}
+
+export interface AdviseContextInput {
+  body: string;
+  references: AdviseContextSection[];
+  wiki: AdviseContextSection[];
+  maxChars: number;
+}
+
+export interface AdviseContext {
+  body: string;
+  references: AdviseContextSection[];
+  wiki: AdviseContextSection[];
+  dropped: { wiki: number; references: number; body: boolean };
+  budget: { cap: number; used: number };
+}
+
+export function capContextByChars(text: string, cap: number): { content: string; truncated: boolean } {
+  if (text.length <= cap) {
+    return { content: text, truncated: false };
+  }
+  return { content: text.slice(0, cap), truncated: true };
+}
+
+export function buildAdviseContext(input: AdviseContextInput): AdviseContext {
+  const cap = Math.max(0, input.maxChars);
+  let used = 0;
+  const dropped = { wiki: 0, references: 0, body: false };
+
+  // Body is highest priority and never truncated: if the body itself exceeds
+  // the cap, we still keep it and mark body=true so the caller knows. Body
+  // shape (skill file) is what advice is grounded in.
+  const body = input.body;
+  used += body.length;
+
+  const references: AdviseContextSection[] = [];
+  for (const ref of input.references) {
+    if (used >= cap) {
+      dropped.references += 1;
+      continue;
+    }
+    const remaining = cap - used;
+    const capped = capContextByChars(ref.content, remaining);
+    references.push({ name: ref.name, content: capped.content });
+    used += capped.content.length;
+    if (capped.truncated) {
+      // We filled the rest of the budget with this reference; drop the rest.
+      dropped.references += input.references.length - references.length;
+      break;
+    }
+  }
+
+  // Wiki is lowest priority: drop from the back when full.
+  const wiki: AdviseContextSection[] = [];
+  for (const w of input.wiki) {
+    if (used + w.content.length > cap) {
+      // Try a partial if there is room at all.
+      const remaining = Math.max(0, cap - used);
+      if (remaining > 0) {
+        const capped = capContextByChars(w.content, remaining);
+        wiki.push({ name: w.name, content: capped.content });
+        used += capped.content.length;
+        dropped.wiki += 1;
+      } else {
+        dropped.wiki += 1;
+      }
+      continue;
+    }
+    wiki.push({ name: w.name, content: w.content });
+    used += w.content.length;
+  }
+
+  if (used > cap) {
+    dropped.body = true;
+  }
+
+  return {
+    body,
+    references,
+    wiki,
+    dropped,
+    budget: { cap, used: Math.min(used, cap + body.length) },
+  };
+}

package/src/studio/advise/engine.ts

@@ -0,0 +1,117 @@
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { buildAdviseContext, type AdviseContext, type AdviseContextSection } from "./context.ts";
+import { buildPrompt, type AdviseMode, type AdvisePrompt } from "./prompts.ts";
+
+/**
+ * Provider-agnostic surface the engine needs: any object exposing a
+ * `stream` with the pi-ai shape. The model is the engine's local
+ * {@link AdviseModel} contract — production adapters map it to a fully
+ * populated pi-ai `Model` at the boundary, so no incomplete object is ever
+ * cast into one here.
+ */
+export interface AdviseStreamContext extends AdviseContext {
+  /** Built prompt (system + rendered user instructions). Providers that
+   *  construct their own LLM context from the sections may ignore it. */
+  prompt?: AdvisePrompt;
+}
+
+export interface AdviseStreamProvider {
+  stream(
+    model: AdviseModel,
+    context: AdviseStreamContext,
+    options: { signal: AbortSignal; maxTokens?: number },
+  ): AsyncIterable<unknown>;
+}
+
+export interface AdviseModel {
+  id: string;
+  contextWindow: number;
+  maxTokens?: number;
+}
+
+export interface RunAdviceOptions {
+  mode: AdviseMode;
+  skillName: string;
+  body: string;
+  references: AdviseContextSection[];
+  wiki: AdviseContextSection[];
+  maxChars?: number;
+  provider: AdviseStreamProvider | null;
+  model?: AdviseModel;
+  signal: AbortSignal;
+  onChunk?: (text: string) => void;
+}
+
+export type RunAdviceResult =
+  | { kind: "ok"; text: string }
+  | { kind: "unavailable"; reason: "no-model" | "aborted" | "no-text" };
+
+const DEFAULT_MAX_CHARS = 24_000;
+const DEFAULT_MODEL: AdviseModel = {
+  id: "advisor-faux",
+  contextWindow: 32_000,
+  maxTokens: 1024,
+};
+
+export async function runAdvice(opts: RunAdviceOptions): Promise<RunAdviceResult> {
+  if (opts.signal.aborted) {
+    return { kind: "unavailable", reason: "aborted" };
+  }
+  if (!opts.provider) {
+    return { kind: "unavailable", reason: "no-model" };
+  }
+  const model = opts.model ?? DEFAULT_MODEL;
+  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+  const ctx: AdviseStreamContext = buildAdviseContext({
+    body: opts.body,
+    references: opts.references,
+    wiki: opts.wiki,
+    maxChars,
+  });
+  ctx.prompt = buildPrompt(opts.mode, {
+    skillName: opts.skillName,
+    body: ctx.body,
+    references: ctx.references,
+    wiki: ctx.wiki,
+  });
+
+  const stream = opts.provider.stream(model, ctx, {
+    signal: opts.signal,
+    maxTokens: opts.model?.maxTokens ?? DEFAULT_MODEL.maxTokens,
+  });
+
+  let text = "";
+  try {
+    for await (const ev of stream) {
+      if (opts.signal.aborted) {
+        return { kind: "unavailable", reason: "aborted" };
+      }
+      // Defensive text extraction: anything with a string .delta or .text
+      // counts. Avoids pinning the engine to pi-ai's AssistantMessageEvent.
+      const anyEv = ev as { delta?: unknown; text?: unknown };
+      const delta =
+        typeof anyEv.delta === "string"
+          ? anyEv.delta
+          : typeof anyEv.text === "string"
+            ? anyEv.text
+            : "";
+      if (delta) {
+        text += delta;
+        opts.onChunk?.(delta);
+      }
+    }
+  } catch (err) {
+    if (opts.signal.aborted) {
+      return { kind: "unavailable", reason: "aborted" };
+    }
+    throw err;
+  }
+  if (text.length === 0) {
+    return { kind: "unavailable", reason: "no-text" };
+  }
+  return { kind: "ok", text };
+}
+
+// Re-export the pi-ai factory so call sites that want to plug a real stream
+// do not have to import pi-ai themselves.
+export { createAssistantMessageEventStream };

package/src/studio/advise/prompts.ts

@@ -0,0 +1,68 @@
+import type { AdviseContextSection } from "./context.ts";
+
+export type AdviseMode = "explain" | "integrate" | "examples" | "improve";
+
+export interface AdvisePromptInput {
+  skillName: string;
+  body: string;
+  references: AdviseContextSection[];
+  wiki: AdviseContextSection[];
+}
+
+export interface AdvisePrompt {
+  system: string;
+  user: string;
+}
+
+const SYSTEM_BASE =
+  "You advise a chef who is building or auditing a skill. Reply in English. " +
+  "Stay grounded in the skill body and the provided references; do not invent " +
+  "APIs or behavior. Prefer concrete, copy-paste-ready guidance.";
+
+const MODE_INSTRUCTIONS: Record<AdviseMode, string> = {
+  explain:
+    "Explain what this skill does, when to use it, and when to avoid it. " +
+    "Be specific. Reference the existing body rather than restating it.",
+  integrate:
+    "Show how to wire this skill into the existing repo. Identify the files, " +
+    "settings, and commands that already exist, and describe the smallest " +
+    "change that adds the skill to the user-facing flow.",
+  examples:
+    "Produce two or three example invocations or scenarios that demonstrate " +
+    "the skill's value. Each example must be runnable as written.",
+  improve:
+    "Find concrete weaknesses in the skill body: missing inputs, broken " +
+    "promises, unclear copy, missing tests. Suggest the smallest change for " +
+    "each finding.",
+};
+
+function renderSection(title: string, sections: AdviseContextSection[]): string {
+  if (sections.length === 0) return `## ${title}\n(none)`;
+  const lines = [`## ${title}`];
+  for (const s of sections) {
+    lines.push(`### ${s.name}`);
+    lines.push(s.content);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export function buildPrompt(mode: AdviseMode, input: AdvisePromptInput): AdvisePrompt {
+  const lines: string[] = [];
+  lines.push(`# Skill: ${input.skillName}`);
+  lines.push("");
+  lines.push("## Body");
+  lines.push(input.body);
+  lines.push("");
+  lines.push(renderSection("References", input.references));
+  lines.push("");
+  lines.push(renderSection("Upstream wiki (context only)", input.wiki));
+  lines.push("");
+  lines.push("## Task");
+  lines.push(MODE_INSTRUCTIONS[mode]);
+
+  return {
+    system: SYSTEM_BASE,
+    user: lines.join("\n"),
+  };
+}

package/src/studio/component.ts

@@ -0,0 +1,105 @@
+/**
+ * Fullscreen studio component (U5, KTD3). Non-overlay `ctx.ui.custom()` —
+ * the editor-replacing variant, unlike the Deck's centered overlay. Panes are
+ * placeholders here; U6-U10 fill list/detail/actions/advice content.
+ */
+
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  createStudioState,
+  handleStudioKey,
+  STUDIO_PANES,
+} from "./state.ts";
+import type { StudioKeyEvent, StudioState } from "./types.ts";
+
+const PANE_LABELS: Record<string, string> = {
+  list: "Skills",
+  detail: "Detail",
+  actions: "Actions",
+  advice: "AI Advice",
+};
+
+const HELP_LINES: readonly string[] = [
+  "Skill Studio — keys",
+  "",
+  "  j / k or arrows   Move selection",
+  "  /                 Filter skills",
+  "  Tab               Cycle pane focus",
+  "  ?                 Toggle this help",
+  "  q / Esc           Exit studio",
+];
+
+export function mapRawInput(data: string): StudioKeyEvent {
+  if (matchesKey(data, "escape")) return { key: "escape" };
+  if (matchesKey(data, "return")) return { key: "return" };
+  if (matchesKey(data, "tab")) return { key: "tab" };
+  if (matchesKey(data, "up")) return { key: "up" };
+  if (matchesKey(data, "down")) return { key: "down" };
+  if (data === "\x7f" || data === "\b" || matchesKey(data, "backspace")) {
+    return { key: "backspace" };
+  }
+  if (data.length === 1 && data >= " " && data <= "~") {
+    return { key: "printable", char: data };
+  }
+  return { key: "other" };
+}
+
+export function renderStudioFrame(theme: Theme, width: number, state: StudioState): string[] {
+  if (state.mode === "help") {
+    const lines = [theme.fg("accent", HELP_LINES[0] ?? ""), ""];
+    for (const line of HELP_LINES.slice(2)) {
+      lines.push(theme.fg("muted", line));
+    }
+    lines.push("", theme.fg("dim", "Press q, Esc, or Enter to close help"));
+    return lines;
+  }
+
+  const focusMark = (pane: string): string =>
+    state.focus === pane ? theme.fg("accent", `[${PANE_LABELS[pane] ?? pane}]`) : theme.fg("dim", ` ${PANE_LABELS[pane] ?? pane} `);
+
+  const header = STUDIO_PANES.map((pane) => focusMark(pane)).join(" ");
+  const filterLine = state.mode === "filter"
+    ? theme.fg("accent", `filter: ${state.filterQuery}_`)
+    : state.filterQuery
+      ? theme.fg("muted", `filter: ${state.filterQuery}`)
+      : theme.fg("dim", "press / to filter, ? for help");
+
+  const lines: string[] = [
+    theme.fg("accent", "Skill Studio"),
+    header,
+    filterLine,
+    theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 60)))),
+    theme.fg("muted", `selected: ${state.selectedIndex}`),
+    theme.fg("dim", "panes populate in upcoming units (browse, actions, advice)"),
+    theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 60)))),
+    theme.fg("dim", "q/Esc exit · / filter · Tab focus · ? help"),
+  ];
+  return lines;
+}
+
+export function createStudioComponent(
+  theme: Theme,
+  done: (value: string | null) => void,
+  onStateChange?: (state: StudioState) => void,
+) {
+  let state = createStudioState();
+
+  return {
+    focused: true,
+    invalidate() {},
+    render(width: number) {
+      return renderStudioFrame(theme, width, state);
+    },
+    handleInput(data: string) {
+      const next = handleStudioKey(state, mapRawInput(data));
+      if (next !== state) {
+        state = next;
+        onStateChange?.(state);
+      }
+      if (state.exitRequested) {
+        done(null);
+      }
+    },
+  };
+}

package/src/studio/deepwiki/cache.ts

@@ -0,0 +1,74 @@
+/** DeepWiki disk cache (U9). TTL + stale fallback, no LRU (ponytail: add when
+ *  the cache directory count actually grows). */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentPath } from "../../paths/agent-dirs.ts";
+import type { RepoRef } from "./extract.ts";
+
+export function resolveCacheDir(override?: string): string {
+  return override ?? getAgentPath("wishcraft-cache", "deepwiki");
+}
+
+export interface CacheFile<T> {
+  savedAt: number;
+  data: T;
+}
+
+export interface CacheReadResult<T> {
+  status: "hit" | "miss";
+  stale: boolean;
+  entry: CacheFile<T> | null;
+}
+
+function fileFor(dir: string, repo: RepoRef): string {
+  return join(dir, repo.owner, `${repo.repo}.json`);
+}
+
+export async function writeCacheEntry<T>(
+  dir: string,
+  repo: RepoRef,
+  data: T,
+  options: { ttlMs: number; now?: number },
+): Promise<void> {
+  const now = options.now ?? Date.now();
+  const file = fileFor(dir, repo);
+  mkdirSync(join(dir, repo.owner), { recursive: true });
+  writeFileSync(file, JSON.stringify({ savedAt: now, data }), "utf8");
+}
+
+export async function readCacheEntry<T>(
+  dir: string,
+  repo: RepoRef,
+  options: { ttlMs: number; now?: number },
+): Promise<CacheReadResult<T>> {
+  const now = options.now ?? Date.now();
+  const file = fileFor(dir, repo);
+  if (!existsSync(file)) return { status: "miss", stale: false, entry: null };
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8")) as CacheFile<T>;
+    const fresh = now - raw.savedAt <= options.ttlMs;
+    return { status: fresh ? "hit" : "miss", stale: !fresh, entry: raw };
+  } catch {
+    return { status: "miss", stale: false, entry: null };
+  }
+}
+
+export async function withCache<T>(
+  dir: string,
+  repo: RepoRef,
+  options: { ttlMs: number; now?: number },
+  networkFetch: () => Promise<T>,
+): Promise<CacheReadResult<T>> {
+  const fresh = await readCacheEntry<T>(dir, repo, options);
+  if (fresh.status === "hit") return fresh;
+  try {
+    const data = await networkFetch();
+    await writeCacheEntry(dir, repo, data, options);
+    const read = await readCacheEntry<T>(dir, repo, { ...options, now: Date.now() });
+    return read;
+  } catch {
+    if (fresh.entry) return { status: "miss", stale: true, entry: fresh.entry };
+    return { status: "miss", stale: false, entry: null };
+  }
+}