@selesai/code 0.5.13 → 0.5.15

package/dist/extensions/pi-powerline-footer/guide.ts

@@ -0,0 +1,227 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type GuideMode = "full" | "compact" | "off";
+export type GuideDisplayMode = "full" | "compact" | "none";
+
+export interface GuideFeature {
+  id: string;
+  section?: string;
+  title: string;
+  example: string;
+  introducedIn: string;
+}
+
+export interface GuidePreferences {
+  mode: GuideMode;
+  lastSeenVersion?: string;
+}
+
+export interface GuidePreferencesUpdate {
+  mode?: GuideMode;
+  lastSeenVersion?: string | null;
+}
+
+// Keep this map useful, not exhaustive: each row points at a real command, shortcut,
+// or prompt from the root README without reproducing the README in the overlay.
+export const GUIDE_FEATURES: readonly GuideFeature[] = [
+  {
+    id: "workflow-task",
+    section: "Start here",
+    title: "Task",
+    example: '/workflow-task "<goal>"',
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "workflow-quick",
+    section: "Start here",
+    title: "Quick",
+    example: '/workflow-quick "<goal>"',
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "workflow-prototype",
+    section: "Start here",
+    title: "Prototype",
+    example: '/workflow-prototype "<goal>"',
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "settings",
+    section: "Start here",
+    title: "Settings",
+    example: "/settings · /guide compact|off|reset · /reload",
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "subagents",
+    section: "Delegate / research",
+    title: "Plan",
+    example: '"Ask the architect to challenge this plan..."',
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "parallel-review",
+    section: "Delegate / research",
+    title: "Review",
+    example: '"Run parallel commentator agents for correctness..."',
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "web-research",
+    section: "Delegate / research",
+    title: "Research",
+    example: '"Ask the researcher to research <topic> and cite sources."',
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "skills",
+    section: "Delegate / research",
+    title: "Skills",
+    example: "/skill:*",
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "recovery",
+    section: "Recover",
+    title: "Recover",
+    example: "/undo · /tree · /fork · /cp <hash>",
+    introducedIn: "0.5.13",
+  },
+  {
+    id: "handoff",
+    section: "Recover",
+    title: "Handoff",
+    example: "/handoff-new Next: fix <problem>; start with a coding plan.",
+    introducedIn: "0.5.13",
+  },
+];
+
+export const GUIDE_DISMISS_HINT = "Press any key to continue";
+
+export const GUIDE_COMPACT_LINES = [
+  "/guide full · /settings",
+  '/workflow-task "<goal>" · /workflow-quick "<goal>"',
+  '/workflow-prototype "<goal>"',
+  '"Ask the researcher to research <topic>."',
+  "/skill:* · /undo · /handoff-new <next focus>",
+] as const;
+
+export type GuideLine =
+  | { kind: "section"; text: string }
+  | { kind: "feature"; feature: GuideFeature };
+
+export function getGuideFeatureLines(features: readonly GuideFeature[] = GUIDE_FEATURES): GuideLine[] {
+  return features.flatMap((feature, index) => {
+    const previous = features[index - 1];
+    const section = feature.section && feature.section !== previous?.section
+      ? [{ kind: "section" as const, text: feature.section }]
+      : [];
+    return [...section, { kind: "feature" as const, feature }];
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isGuideMode(value: unknown): value is GuideMode {
+  return value === "full" || value === "compact" || value === "off";
+}
+
+function versionParts(version: string): [number, number, number] {
+  const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : [0, 0, 0];
+}
+
+export function compareGuideVersions(left: string, right: string): number {
+  const leftParts = versionParts(left);
+  const rightParts = versionParts(right);
+  for (let i = 0; i < leftParts.length; i++) {
+    if (leftParts[i] !== rightParts[i]) return leftParts[i] - rightParts[i];
+  }
+  return 0;
+}
+
+export function getGuidePreferences(settings: unknown): GuidePreferences {
+  const raw = isRecord(settings) && isRecord(settings.selesaiGuide)
+    ? settings.selesaiGuide
+    : {};
+
+  return {
+    mode: isGuideMode(raw.mode) ? raw.mode : "full",
+    lastSeenVersion: typeof raw.lastSeenVersion === "string" ? raw.lastSeenVersion : undefined,
+  };
+}
+
+export function getNewGuideFeatures(
+  lastSeenVersion: string | undefined,
+  currentVersion: string,
+  features: readonly GuideFeature[] = GUIDE_FEATURES,
+): GuideFeature[] {
+  if (!lastSeenVersion || compareGuideVersions(lastSeenVersion, currentVersion) >= 0) {
+    return [];
+  }
+
+  return features.filter((feature) => (
+    compareGuideVersions(feature.introducedIn, lastSeenVersion) > 0
+    && compareGuideVersions(feature.introducedIn, currentVersion) <= 0
+  ));
+}
+
+export function resolveGuideDisplayMode(options: {
+  reason: string;
+  hasUI: boolean;
+  guideMode: GuideMode;
+}): GuideDisplayMode {
+  if (!options.hasUI || options.reason === "reload" || options.guideMode === "off") {
+    return "none";
+  }
+
+  return options.guideMode === "compact" ? "compact" : "full";
+}
+
+function readSettingsFile(settingsPath: string): Record<string, unknown> | null {
+  if (!existsSync(settingsPath)) return {};
+
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveGuidePreferences(
+  update: GuidePreferencesUpdate,
+  settingsPath: string,
+): boolean {
+  const settings = readSettingsFile(settingsPath);
+  if (!settings) return false;
+
+  const current = getGuidePreferences(settings);
+  const next: Record<string, unknown> = {
+    mode: update.mode ?? current.mode,
+  };
+  const lastSeenVersion = update.lastSeenVersion === null
+    ? undefined
+    : update.lastSeenVersion ?? current.lastSeenVersion;
+  if (lastSeenVersion) next.lastSeenVersion = lastSeenVersion;
+
+  settings.selesaiGuide = next;
+
+  try {
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function markGuideVersionSeen(
+  version: string,
+  settingsPath: string,
+): boolean {
+  return saveGuidePreferences({ lastSeenVersion: version }, settingsPath);
+}

package/dist/extensions/pi-powerline-footer/index.ts

@@ -3,6 +3,7 @@ import {
   CONFIG_DIR_NAME,
   getAgentDir,
   getSettingsPath,
+  VERSION,
   type ExtensionAPI,
   type ReadonlyFooterDataProvider,
   type Theme,
@@ -33,7 +34,7 @@ import { renderSegment } from "./segments.ts";
 import { getGitStatus, invalidateGitStatus, invalidateGitBranch } from "./git-status.ts";
 import { ansi, getFgAnsiCode } from "./colors.ts";
 import { WelcomeComponent, WelcomeHeader, discoverLoadedCounts, getRecentSessions } from "./welcome.ts";
-import { createWelcomeDismissScheduler } from "./welcome-dismiss.ts";
+import { getGuidePreferences, getNewGuideFeatures, markGuideVersionSeen, resolveGuideDisplayMode, saveGuidePreferences, type GuideFeature } from "./guide.ts";
 import { createRenderScheduler } from "./render-scheduler.ts";
 import { readCoreContextUsage } from "./context-usage.ts";
 import { renderFixedEditorCluster } from "./fixed-editor/cluster.ts";
@@ -940,6 +941,7 @@ export default function powerlineFooter(pi: ExtensionAPI) {
   let fixedWidgetContainerBelow: any = null;
   let stashShortcutInputUnsubscribe: (() => void) | null = null;
   let dismissWelcomeOverlay: (() => void) | null = null;
+  let guideOverlayBlocking = false;
   let welcomeHeaderActive = false;
   let welcomeOverlayShouldDismiss = false;
   let lastUserPrompt = "";
@@ -963,11 +965,6 @@ export default function powerlineFooter(pi: ExtensionAPI) {
 
   const getShellPath = () => process.env.SHELL || "/bin/sh";
   const getShellCwd = () => shellSession?.state.cwd ?? currentCtx?.cwd ?? process.cwd();
-  const welcomeDismissScheduler = createWelcomeDismissScheduler({
-    dismiss: (ctx: unknown) => dismissWelcome(ctx),
-    getGeneration: () => sessionGeneration,
-    isEnabled: () => enabled,
-  });
 
   const statusRenderScheduler = createRenderScheduler(() => {
     const msSinceInput = Date.now() - lastEditorInputAt;
@@ -1187,6 +1184,13 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     stashedEditorText = null;
 
     const settings = readSettings(ctx.cwd);
+    const guidePreferences = getGuidePreferences(settings);
+    const guideDisplayMode = resolveGuideDisplayMode({
+      reason: event.reason,
+      hasUI: ctx.hasUI,
+      guideMode: guidePreferences.mode,
+    });
+    const newGuideFeatures = getNewGuideFeatures(guidePreferences.lastSeenVersion, VERSION);
     bashModeSettings = parseBashModeSettings(settings);
     resolvedShortcuts = resolveShortcutConfig(settings);
     showLastPrompt = settings.showLastPrompt !== false;
@@ -1210,12 +1214,10 @@ export default function powerlineFooter(pi: ExtensionAPI) {
 
     if (enabled && ctx.hasUI) {
       setupCustomEditor(ctx);
-      if (event.reason === "startup") {
-        if (settings.quietStartup === true) {
-          setupWelcomeHeader(ctx);
-        } else {
-          setupWelcomeOverlay(ctx);
-        }
+      if (guideDisplayMode === "full") {
+        setupWelcomeOverlay(ctx, newGuideFeatures);
+      } else if (guideDisplayMode === "compact") {
+        setupWelcomeHeader(ctx, newGuideFeatures);
       } else {
         dismissWelcome(ctx);
       }
@@ -1228,9 +1230,9 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     completedAsyncSubagentUsage.clear();
     dismissWelcomeOverlay?.();
     dismissWelcomeOverlay = null;
+    guideOverlayBlocking = false;
     welcomeHeaderActive = false;
     welcomeOverlayShouldDismiss = false;
-    welcomeDismissScheduler.cancel();
     statusRenderScheduler.cancel();
     restoreFooterStatusRepaintHook?.();
     restoreFooterStatusRepaintHook = null;
@@ -1333,13 +1335,12 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     }
   });
 
-  // Track streaming state (footer only shows status during streaming)
-  // Also dismiss welcome when agent starts responding (handles `p "command"` case)
+  // Track streaming state (footer only shows status during streaming).
+  // A visible guide remains blocking until its own key handler dismisses it.
   pi.on("agent_start", async (_event, ctx) => {
     isStreaming = true;
     liveAssistantUsage = null;
     onVibeAgentStart();
-    dismissWelcome(ctx);
     currentCtx = ctx;
   });
 
@@ -1372,9 +1373,8 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     requestImmediateStatusRender({ deferDuringTyping: false });
   });
 
-  // Also dismiss on tool calls (agent is working) + refresh vibe if rate limit allows
+  // Refresh vibe if rate limit allows. The guide is dismissed only by its input handler.
   pi.on("tool_call", async (event, ctx) => {
-    dismissWelcome(ctx);
     if (ctx.hasUI) {
       // Extract recent agent context from session for richer vibe generation
       const agentContext = getRecentAgentContext(ctx);
@@ -1409,7 +1409,7 @@ export default function powerlineFooter(pi: ExtensionAPI) {
   }
 
   function dismissWelcome(ctx: any) {
-    welcomeDismissScheduler.cancel();
+    if (guideOverlayBlocking) return;
 
     if (dismissWelcomeOverlay) {
       dismissWelcomeOverlay();
@@ -1424,9 +1424,20 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     }
   }
 
-  function scheduleDismissWelcome(ctx: any) {
-    if (!dismissWelcomeOverlay && welcomeOverlayShouldDismiss && !welcomeHeaderActive) return;
-    welcomeDismissScheduler.schedule(ctx);
+  function closeWelcome(ctx: any): void {
+    dismissWelcomeOverlay?.();
+    dismissWelcomeOverlay = null;
+    guideOverlayBlocking = false;
+    if (welcomeHeaderActive) {
+      welcomeHeaderActive = false;
+      ctx.ui.setHeader(undefined);
+    }
+    welcomeOverlayShouldDismiss = false;
+  }
+
+  function currentGuideFeatures(ctx: any): GuideFeature[] {
+    const preferences = getGuidePreferences(readSettings(ctx.cwd));
+    return getNewGuideFeatures(preferences.lastSeenVersion, VERSION);
   }
 
   function addStashHistoryEntry(text: string): void {
@@ -1696,6 +1707,50 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     requestStatusRender();
   });
 
+  pi.registerCommand("guide", {
+    description: "Open the recurring Selesai feature guide",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) return;
+
+      const mode = args?.trim().toLowerCase() ?? "";
+      if (mode !== "" && !["full", "compact", "off", "reset"].includes(mode)) {
+        ctx.ui.notify("Usage: /guide [full|compact|off|reset]", "warning");
+        return;
+      }
+
+      if (!enabled) {
+        ctx.ui.notify("Powerline is disabled; use /powerline first", "info");
+        return;
+      }
+
+      if (mode === "off") {
+        const saved = saveGuidePreferences({ mode: "off" }, getSettingsPath());
+        closeWelcome(ctx);
+        ctx.ui.notify(saved ? "Guide hidden for future sessions" : "Guide hidden for this session; settings.json was not updated", saved ? "info" : "warning");
+        return;
+      }
+
+      if (mode === "compact") {
+        const saved = saveGuidePreferences({ mode: "compact" }, getSettingsPath());
+        closeWelcome(ctx);
+        setupWelcomeHeader(ctx, currentGuideFeatures(ctx));
+        if (!saved) ctx.ui.notify("Compact guide enabled for this session; settings.json was not updated", "warning");
+        return;
+      }
+
+      if (mode === "full" || mode === "reset") {
+        const saved = saveGuidePreferences({
+          mode: "full",
+          ...(mode === "reset" ? { lastSeenVersion: null } : {}),
+        }, getSettingsPath());
+        if (!saved) ctx.ui.notify("Guide opened, but settings.json was not updated", "warning");
+      }
+
+      closeWelcome(ctx);
+      setupWelcomeOverlay(ctx, currentGuideFeatures(ctx));
+    },
+  });
+
   // Command to toggle/configure
   pi.registerCommand("powerline", {
     description: "Configure powerline status (toggle, preset)",
@@ -1718,7 +1773,6 @@ export default function powerlineFooter(pi: ExtensionAPI) {
           dismissWelcomeOverlay = null;
           welcomeHeaderActive = false;
           welcomeOverlayShouldDismiss = false;
-          welcomeDismissScheduler.cancel();
           getPromptHistoryState().savedPromptHistory = [];
           stashedEditorText = null;
                 ctx.ui.setStatus("stash", undefined);
@@ -2520,7 +2574,6 @@ export default function powerlineFooter(pi: ExtensionAPI) {
         }
         if (isStashShortcutInput(data)) {
           stashOrRestoreEditorText(ctx);
-          scheduleDismissWelcome(ctx);
           tuiRef?.requestRender();
           return { consume: true };
         }
@@ -2531,7 +2584,6 @@ export default function powerlineFooter(pi: ExtensionAPI) {
         }
 
         runPowerlineShortcut(ctx, powerlineShortcutAction);
-        scheduleDismissWelcome(ctx);
         tuiRef?.requestRender();
         return { consume: true };
       })
@@ -2634,14 +2686,12 @@ export default function powerlineFooter(pi: ExtensionAPI) {
 
         if (isStashShortcutInput(data)) {
           stashOrRestoreEditorText(ctx);
-          scheduleDismissWelcome(ctx);
           return;
         }
 
         const powerlineShortcutAction = getPowerlineShortcutAction(data);
         if (powerlineShortcutAction) {
           runPowerlineShortcut(ctx, powerlineShortcutAction);
-          scheduleDismissWelcome(ctx);
           return;
         }
 
@@ -2658,7 +2708,6 @@ export default function powerlineFooter(pi: ExtensionAPI) {
 
         attachAutocompleteProvider();
         const followUpText = keybindings.matches(data, "app.message.followUp") ? getCurrentEditorText(ctx, editor) : "";
-        scheduleDismissWelcome(ctx);
         originalHandleInput(data);
         if (hasNonWhitespaceText(followUpText) && !hasNonWhitespaceText(getCurrentEditorText(ctx, editor))) {
           followSubmittedEditorToBottom();
@@ -2746,14 +2795,15 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     }
   }
 
-  function setupWelcomeHeader(ctx: any) {
+  function setupWelcomeHeader(ctx: any, newFeatures: GuideFeature[] = []) {
     const modelName = ctx.model?.name || ctx.model?.id || "No model";
     const providerName = ctx.model?.provider || "Unknown";
     const loadedCounts = discoverLoadedCounts();
     const recentSessions = getRecentSessions(3);
 
-    const header = new WelcomeHeader(modelName, providerName, recentSessions, loadedCounts);
+    const header = new WelcomeHeader(modelName, providerName, recentSessions, loadedCounts, "compact", newFeatures);
     welcomeHeaderActive = true;
+    markGuideVersionSeen(VERSION, getSettingsPath());
 
     ctx.ui.setHeader(() => {
       return {
@@ -2767,7 +2817,7 @@ export default function powerlineFooter(pi: ExtensionAPI) {
     });
   }
 
-  function setupWelcomeOverlay(ctx: any) {
+  function setupWelcomeOverlay(ctx: any, newFeatures: GuideFeature[] = []) {
     const modelName = ctx.model?.name || ctx.model?.id || "No model";
     const providerName = ctx.model?.provider || "Unknown";
     const loadedCounts = discoverLoadedCounts();
@@ -2782,45 +2832,29 @@ export default function powerlineFooter(pi: ExtensionAPI) {
         return;
       }
 
-      const sessionEvents = ctx.sessionManager?.getBranch?.() ?? [];
-      const hasActivity = sessionEvents.some((entry: unknown) => {
-        if (!isRecord(entry)) return false;
-        if (entry.type === "tool_call" || entry.type === "tool_result") return true;
-        return entry.type === "message" && isRecord(entry.message) && entry.message.role === "assistant";
-      });
-      if (hasActivity) {
-        return;
-      }
-
       ctx.ui.custom(
-        (tui: any, _theme: any, _keybindings: any, done: (result: void) => void) => {
+        (_tui: any, _theme: any, _keybindings: any, done: (result: void) => void) => {
           const welcome = new WelcomeComponent(
             modelName,
             providerName,
             recentSessions,
             loadedCounts,
+            "full",
+            newFeatures,
           );
+          markGuideVersionSeen(VERSION, getSettingsPath());
+          guideOverlayBlocking = true;
 
-          let countdown = 30;
           let dismissed = false;
-          let interval: ReturnType<typeof setInterval> | null = null;
 
           const dismiss = () => {
             if (dismissed) return;
             dismissed = true;
-            if (interval) clearInterval(interval);
             dismissWelcomeOverlay = null;
+            guideOverlayBlocking = false;
             done();
           };
 
-          interval = setInterval(() => {
-            if (dismissed) return;
-            countdown--;
-            welcome.setCountdown(countdown);
-            tui.requestRender();
-            if (countdown <= 0) dismiss();
-          }, 1000);
-
           dismissWelcomeOverlay = dismiss;
 
           if (welcomeOverlayShouldDismiss) {
@@ -2829,13 +2863,12 @@ export default function powerlineFooter(pi: ExtensionAPI) {
           }
 
           return {
-            focused: false,
+            focused: true,
             invalidate: () => welcome.invalidate(),
             render: (width: number) => welcome.render(width),
             handleInput: () => dismiss(),
             dispose: () => {
               dismissed = true;
-              if (interval) clearInterval(interval);
             },
           };
         },

package/dist/extensions/pi-powerline-footer/tests/editor-responsiveness.test.ts

@@ -1,6 +1,5 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { createWelcomeDismissScheduler } from "../welcome-dismiss.ts";
 import { createRenderScheduler } from "../render-scheduler.ts";
 
 test("render scheduler coalesces pending status renders", () => {
@@ -101,80 +100,3 @@ test("render scheduler cancels pending status renders", () => {
     globalThis.clearTimeout = originalClearTimeout;
   }
 });
-
-test("welcome dismissal scheduler coalesces pending work", () => {
-  const originalSetTimeout = globalThis.setTimeout;
-  const callbacks: Array<() => void> = [];
-  let dismissCount = 0;
-
-  globalThis.setTimeout = ((callback: () => void) => {
-    callbacks.push(callback);
-    return { id: callbacks.length } as ReturnType<typeof setTimeout>;
-  }) as typeof setTimeout;
-
-  try {
-    const scheduler = createWelcomeDismissScheduler({
-      dismiss: () => { dismissCount += 1; },
-      getGeneration: () => 1,
-      isEnabled: () => true,
-    });
-
-    scheduler.schedule(undefined);
-    scheduler.schedule(undefined);
-    scheduler.schedule(undefined);
-
-    assert.equal(callbacks.length, 1);
-    callbacks[0]?.();
-    assert.equal(dismissCount, 1);
-  } finally {
-    globalThis.setTimeout = originalSetTimeout;
-  }
-});
-
-test("welcome dismissal scheduler cancels stale pending work", () => {
-  const originalSetTimeout = globalThis.setTimeout;
-  const originalClearTimeout = globalThis.clearTimeout;
-  const callbacks: Array<() => void> = [];
-  const cleared = new Set<object>();
-  let dismissCount = 0;
-  let generation = 1;
-  let enabled = true;
-
-  globalThis.setTimeout = ((callback: () => void) => {
-    const handle = { id: callbacks.length + 1 };
-    callbacks.push(callback);
-    return handle as ReturnType<typeof setTimeout>;
-  }) as typeof setTimeout;
-  globalThis.clearTimeout = ((handle?: ReturnType<typeof setTimeout>) => {
-    if (handle && typeof handle === "object") {
-      cleared.add(handle);
-    }
-  }) as typeof clearTimeout;
-
-  try {
-    const scheduler = createWelcomeDismissScheduler({
-      dismiss: () => { dismissCount += 1; },
-      getGeneration: () => generation,
-      isEnabled: () => enabled,
-    });
-
-    scheduler.schedule(undefined);
-    generation += 1;
-    callbacks[0]?.();
-    assert.equal(dismissCount, 0);
-
-    scheduler.schedule(undefined);
-    enabled = false;
-    callbacks[1]?.();
-    assert.equal(dismissCount, 0);
-
-    enabled = true;
-    scheduler.schedule(undefined);
-    scheduler.cancel();
-    assert.equal(cleared.size, 1);
-    assert.equal(dismissCount, 0);
-  } finally {
-    globalThis.setTimeout = originalSetTimeout;
-    globalThis.clearTimeout = originalClearTimeout;
-  }
-});