@rmrdeveloper/sideroom-pi 5.0.1 → 7.0.0

package/extensions/ask/model.ts

@@ -0,0 +1,196 @@
+import { type Static, Type } from 'typebox';
+import { Check, Errors } from 'typebox/value';
+
+export const TOOL_NAME = 'sideroom_ask';
+export const OUT_OF_SCOPE_VALUE = 'Out of scope';
+export const OUT_OF_SCOPE_LABEL = 'Out of scope';
+export const CUSTOM_VALUE = '__other__';
+export const CUSTOM_LABEL = 'Write a custom answer';
+export const UI_UNAVAILABLE =
+  'Error: UI not available (running in non-interactive mode)';
+
+const QuestionOptionSchema = Type.Object({
+  value: Type.String({ description: 'The value returned when selected' }),
+  label: Type.String({ description: 'Display label for the option' }),
+  description: Type.Optional(
+    Type.String({ description: 'Optional description shown below the label' }),
+  ),
+});
+
+const QuestionSchema = Type.Object({
+  id: Type.String({ description: 'Unique identifier for this question' }),
+  label: Type.Optional(
+    Type.String({
+      description:
+        "Short contextual label for the tab bar, e.g. 'Scope' (defaults to Q1, Q2)",
+    }),
+  ),
+  prompt: Type.String({ description: 'The full question text to display' }),
+  options: Type.Array(QuestionOptionSchema, {
+    minItems: 2,
+    description: 'At least two mutually exclusive options',
+  }),
+  recommendationIndex: Type.Integer({
+    minimum: 0,
+    description: 'Index into options pointing at the recommended option',
+  }),
+});
+
+export const AskParamsSchema = Type.Object({
+  questions: Type.Array(QuestionSchema, {
+    minItems: 1,
+    description: 'Questions to ask the user in this batch',
+  }),
+});
+
+export type AskParams = Static<typeof AskParamsSchema>;
+export type QuestionOption = AskParams['questions'][number]['options'][number];
+
+export interface AskQuestion {
+  readonly id: string;
+  readonly label: string;
+  readonly prompt: string;
+  readonly options: readonly QuestionOption[];
+  readonly recommendationIndex: number;
+}
+
+export interface AskAnswer {
+  readonly id: string;
+  readonly value: string;
+  readonly label: string;
+  readonly wasCustom: boolean;
+  readonly outOfScope: boolean;
+  readonly index?: number;
+}
+
+export interface AskResult {
+  readonly questions: readonly AskQuestion[];
+  readonly answers: readonly AskAnswer[];
+  readonly cancelled: boolean;
+}
+
+export type RenderOption = QuestionOption & {
+  readonly isOther?: boolean;
+  readonly isOutOfScope?: boolean;
+  readonly isRecommended?: boolean;
+};
+
+export type ParseAskResult =
+  | { readonly ok: true; readonly questions: readonly AskQuestion[] }
+  | { readonly ok: false; readonly message: string };
+
+export function parseAskParams(value: unknown): ParseAskResult {
+  if (!Check(AskParamsSchema, value)) {
+    return { ok: false, message: schemaErrorMessage(value) };
+  }
+
+  const seen = new Set<string>();
+  for (const question of value.questions) {
+    if (seen.has(question.id)) {
+      return {
+        ok: false,
+        message: `Error: Duplicate question id: ${question.id}`,
+      };
+    }
+    seen.add(question.id);
+    if (question.recommendationIndex >= question.options.length) {
+      return {
+        ok: false,
+        message: `Error: recommendationIndex ${String(question.recommendationIndex)} is out of range for question '${question.id}'`,
+      };
+    }
+  }
+
+  return { ok: true, questions: normalizeQuestions(value.questions) };
+}
+
+export function normalizeQuestions(
+  questions: AskParams['questions'],
+): AskQuestion[] {
+  return questions.map((question, index) => {
+    const label = question.label;
+    return {
+      id: question.id,
+      label:
+        label !== undefined && label.trim().length > 0
+          ? label
+          : `Q${String(index + 1)}`,
+      prompt: question.prompt,
+      options: question.options,
+      recommendationIndex: question.recommendationIndex,
+    };
+  });
+}
+
+export function renderOptions(question: AskQuestion): RenderOption[] {
+  const options: RenderOption[] = question.options.map((option, index) => ({
+    ...option,
+    isRecommended: index === question.recommendationIndex,
+  }));
+  options.push({
+    value: OUT_OF_SCOPE_VALUE,
+    label: OUT_OF_SCOPE_LABEL,
+    isOutOfScope: true,
+  });
+  options.push({
+    value: CUSTOM_VALUE,
+    label: CUSTOM_LABEL,
+    isOther: true,
+  });
+  return options;
+}
+
+export function formatAnswerLines(
+  questions: readonly AskQuestion[],
+  answers: readonly AskAnswer[],
+): string[] {
+  return answers.map((answer) => {
+    const question = questions.find((entry) => entry.id === answer.id);
+    const questionLabel = question?.label ?? answer.id;
+    if (answer.outOfScope) {
+      return `${questionLabel}: Out of scope`;
+    }
+    if (answer.wasCustom) {
+      return `${questionLabel}: user wrote: ${answer.label}`;
+    }
+    if (answer.index !== undefined) {
+      return `${questionLabel}: user selected: ${String(answer.index)}. ${answer.label}`;
+    }
+    return `${questionLabel}: user selected: ${answer.label}`;
+  });
+}
+
+function schemaErrorMessage(value: unknown): string {
+  const [error] = Errors(AskParamsSchema, value);
+  if (error === undefined) {
+    return 'Error: Invalid sideroom_ask parameters';
+  }
+  if (error.keyword === 'minItems' && error.instancePath === '/questions') {
+    return 'Error: No questions provided';
+  }
+  const optionsMatch = /\/questions\/(\d+)\/options$/.exec(error.instancePath);
+  if (error.keyword === 'minItems' && optionsMatch !== null) {
+    const questionIndex = Number(optionsMatch[1]);
+    const questions = asQuestions(value);
+    const question = questions[questionIndex];
+    const id =
+      question !== undefined && typeof question.id === 'string'
+        ? question.id
+        : String(questionIndex);
+    return `Error: Question '${id}' must include at least two options`;
+  }
+  return `Error: Invalid sideroom_ask parameters`;
+}
+
+function asQuestions(value: unknown): readonly Record<string, unknown>[] {
+  if (typeof value !== 'object' || value === null) {
+    return [];
+  }
+  if (!('questions' in value) || !Array.isArray(value.questions)) {
+    return [];
+  }
+  return value.questions.filter(
+    (question): question is Record<string, unknown> =>
+      typeof question === 'object' && question !== null,
+  );
+}

package/extensions/ask/ui.ts

@@ -0,0 +1,445 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import {
+  Editor,
+  type EditorTheme,
+  Key,
+  matchesKey,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from '@earendil-works/pi-tui';
+import {
+  type AskAnswer,
+  type AskQuestion,
+  type AskResult,
+  type RenderOption,
+  renderOptions,
+} from './model.ts';
+
+export async function runAskUi(
+  ui: Pick<ExtensionUIContext, 'custom'>,
+  questions: readonly AskQuestion[],
+): Promise<AskResult> {
+  const isMulti = questions.length > 1;
+  const totalTabs = questions.length + 1;
+
+  return ui.custom<AskResult>((tui, theme, _keybindings, done) => {
+    let currentTab = 0;
+    const firstQuestion = questions[0];
+    let optionIndex =
+      firstQuestion === undefined ? 0 : firstQuestion.recommendationIndex;
+    let inputMode = false;
+    let inputQuestionId: string | null = null;
+    let cachedLines: string[] | undefined;
+    const answers = new Map<string, AskAnswer>();
+
+    const editorTheme: EditorTheme = {
+      borderColor: (s) => theme.fg('accent', s),
+      selectList: {
+        selectedPrefix: (t) => theme.fg('accent', t),
+        selectedText: (t) => theme.fg('accent', t),
+        description: (t) => theme.fg('muted', t),
+        scrollInfo: (t) => theme.fg('dim', t),
+        noMatch: (t) => theme.fg('warning', t),
+      },
+    };
+    const editor = new Editor(tui, editorTheme);
+
+    function refresh(): void {
+      cachedLines = undefined;
+      tui.requestRender();
+    }
+
+    function submit(cancelled: boolean): void {
+      done({
+        questions,
+        answers: Array.from(answers.values()),
+        cancelled,
+      });
+    }
+
+    function currentQuestion(): AskQuestion | undefined {
+      return questions[currentTab];
+    }
+
+    function currentOptions(): RenderOption[] {
+      const question = currentQuestion();
+      if (question === undefined) {
+        return [];
+      }
+      return renderOptions(question);
+    }
+
+    function allAnswered(): boolean {
+      return questions.every((question) => answers.has(question.id));
+    }
+
+    function focusTab(tab: number): void {
+      currentTab = tab;
+      const question = questions[tab];
+      if (question === undefined) {
+        optionIndex = 0;
+        refresh();
+        return;
+      }
+      const saved = answers.get(question.id);
+      if (saved?.index !== undefined) {
+        optionIndex = saved.index - 1;
+      } else {
+        optionIndex = question.recommendationIndex;
+      }
+      refresh();
+    }
+
+    function advanceAfterAnswer(): void {
+      if (!isMulti) {
+        submit(false);
+        return;
+      }
+      if (currentTab < questions.length - 1) {
+        focusTab(currentTab + 1);
+        return;
+      }
+      focusTab(questions.length);
+    }
+
+    function saveAnswer(answer: AskAnswer): void {
+      answers.set(answer.id, answer);
+    }
+
+    function openCustomEditor(question: AskQuestion): void {
+      inputMode = true;
+      inputQuestionId = question.id;
+      const saved = answers.get(question.id);
+      if (saved?.wasCustom === true) {
+        editor.setText(saved.label);
+      } else {
+        editor.setText('');
+      }
+      refresh();
+    }
+
+    function confirmOption(
+      question: AskQuestion,
+      opts: readonly RenderOption[],
+      index: number,
+    ): void {
+      const opt = opts[index];
+      if (opt === undefined) {
+        return;
+      }
+      if (opt.isOther === true) {
+        openCustomEditor(question);
+        return;
+      }
+      if (opt.isOutOfScope === true) {
+        saveAnswer({
+          id: question.id,
+          value: opt.value,
+          label: opt.label,
+          wasCustom: false,
+          outOfScope: true,
+          index: index + 1,
+        });
+        advanceAfterAnswer();
+        return;
+      }
+      const original = question.options[index];
+      saveAnswer({
+        id: question.id,
+        value: original?.value ?? opt.value,
+        label: original?.label ?? opt.label,
+        wasCustom: false,
+        outOfScope: false,
+        index: index + 1,
+      });
+      advanceAfterAnswer();
+    }
+
+    editor.onSubmit = (value) => {
+      if (inputQuestionId === null) {
+        return;
+      }
+      const trimmed = value.trim();
+      if (trimmed.length === 0) {
+        inputMode = false;
+        inputQuestionId = null;
+        editor.setText('');
+        refresh();
+        return;
+      }
+      const question = questions.find((entry) => entry.id === inputQuestionId);
+      const displayIndex =
+        question === undefined ? 1 : renderOptions(question).length;
+      saveAnswer({
+        id: inputQuestionId,
+        value: trimmed,
+        label: trimmed,
+        wasCustom: true,
+        outOfScope: false,
+        index: displayIndex,
+      });
+      inputMode = false;
+      inputQuestionId = null;
+      editor.setText('');
+      advanceAfterAnswer();
+    };
+
+    function handleInput(data: string): void {
+      if (inputMode) {
+        if (matchesKey(data, Key.escape)) {
+          inputMode = false;
+          inputQuestionId = null;
+          editor.setText('');
+          refresh();
+          return;
+        }
+        editor.handleInput(data);
+        refresh();
+        return;
+      }
+
+      const question = currentQuestion();
+      const opts = currentOptions();
+
+      if (isMulti) {
+        if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+          focusTab((currentTab + 1) % totalTabs);
+          return;
+        }
+        if (matchesKey(data, Key.shift('tab')) || matchesKey(data, Key.left)) {
+          focusTab((currentTab - 1 + totalTabs) % totalTabs);
+          return;
+        }
+      }
+
+      if (currentTab === questions.length) {
+        if (matchesKey(data, Key.enter) && allAnswered()) {
+          submit(false);
+        } else if (matchesKey(data, Key.escape)) {
+          submit(true);
+        }
+        return;
+      }
+
+      if (matchesKey(data, Key.up)) {
+        optionIndex = Math.max(0, optionIndex - 1);
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.down)) {
+        optionIndex = Math.min(opts.length - 1, optionIndex + 1);
+        refresh();
+        return;
+      }
+
+      const digit = optionIndexFromDigit(data, opts.length);
+      if (digit !== undefined && question !== undefined) {
+        optionIndex = digit;
+        confirmOption(question, opts, digit);
+        return;
+      }
+
+      if (matchesKey(data, Key.enter) && question !== undefined) {
+        confirmOption(question, opts, optionIndex);
+        return;
+      }
+
+      if (matchesKey(data, Key.escape)) {
+        submit(true);
+      }
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines !== undefined) {
+        return cachedLines;
+      }
+
+      const lines: string[] = [];
+      const renderWidth = Math.max(1, width);
+      const question = currentQuestion();
+      const opts = currentOptions();
+
+      function addWrapped(text: string): void {
+        lines.push(...wrapTextWithAnsi(text, renderWidth));
+      }
+
+      function addWrappedWithPrefix(prefix: string, text: string): void {
+        const prefixWidth = visibleWidth(prefix);
+        if (prefixWidth >= renderWidth) {
+          addWrapped(prefix + text);
+          return;
+        }
+        const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
+        const continuationPrefix = ' '.repeat(prefixWidth);
+        for (let index = 0; index < wrapped.length; index += 1) {
+          const part = wrapped[index];
+          if (part === undefined) {
+            continue;
+          }
+          lines.push(`${index === 0 ? prefix : continuationPrefix}${part}`);
+        }
+      }
+
+      lines.push(theme.fg('accent', '─'.repeat(renderWidth)));
+
+      if (isMulti) {
+        const tabs: string[] = [];
+        for (let index = 0; index < questions.length; index += 1) {
+          const entry = questions[index];
+          if (entry === undefined) {
+            continue;
+          }
+          const isActive = index === currentTab;
+          const isAnswered = answers.has(entry.id);
+          const mark = isAnswered ? '●' : '○';
+          const color = isAnswered ? 'success' : 'muted';
+          const text = ` ${mark} ${entry.label} `;
+          const styled = isActive
+            ? theme.bg('selectedBg', theme.fg('text', text))
+            : theme.fg(color, text);
+          tabs.push(styled);
+        }
+        const canSubmit = allAnswered();
+        const isSubmitTab = currentTab === questions.length;
+        const submitText = ' Submit ';
+        const submitStyled = isSubmitTab
+          ? theme.bg('selectedBg', theme.fg('text', submitText))
+          : theme.fg(canSubmit ? 'success' : 'dim', submitText);
+        tabs.push(submitStyled);
+        addWrappedWithPrefix(' ', tabs.join(' '));
+        lines.push('');
+      }
+
+      function renderOptionList(): void {
+        for (let index = 0; index < opts.length; index += 1) {
+          const opt = opts[index];
+          if (opt === undefined) {
+            continue;
+          }
+          if (opt.isOutOfScope === true) {
+            lines.push('');
+          }
+          const selected = index === optionIndex;
+          const prefix = selected ? theme.fg('accent', '> ') : '  ';
+          const color = selected ? 'accent' : 'text';
+          let line = theme.fg(color, `${String(index + 1)}. ${opt.label}`);
+          if (opt.isRecommended === true) {
+            line = `${line} ${theme.fg('dim', 'recommended')}`;
+          }
+          addWrappedWithPrefix(prefix, line);
+          if (opt.description !== undefined) {
+            addWrappedWithPrefix('     ', theme.fg('muted', opt.description));
+          }
+        }
+      }
+
+      if (inputMode && question !== undefined) {
+        addWrappedWithPrefix(
+          ' ',
+          theme.fg('accent', theme.bold(question.prompt)),
+        );
+        lines.push('');
+        addWrappedWithPrefix(' ', theme.fg('muted', 'Custom answer'));
+        for (const line of editor.render(Math.max(1, renderWidth - 2))) {
+          lines.push(` ${line}`);
+        }
+        lines.push('');
+        addWrappedWithPrefix(
+          ' ',
+          theme.fg('dim', 'Enter save · Esc back to options'),
+        );
+      } else if (currentTab === questions.length) {
+        for (const entry of questions) {
+          const answer = answers.get(entry.id);
+          const name = theme.fg('muted', `${entry.label}: `);
+          if (answer === undefined) {
+            addWrappedWithPrefix(
+              ' ',
+              `${name}${theme.fg('warning', 'not answered')}`,
+            );
+            continue;
+          }
+          let kind = '';
+          if (answer.outOfScope) {
+            kind = 'out of scope · ';
+          } else if (answer.wasCustom) {
+            kind = 'custom · ';
+          }
+          addWrappedWithPrefix(
+            ' ',
+            `${name}${theme.fg('dim', kind)}${theme.fg('text', answer.label)}`,
+          );
+        }
+        lines.push('');
+        if (allAnswered()) {
+          addWrappedWithPrefix(
+            ' ',
+            theme.fg('success', 'Enter send answers · Esc cancel'),
+          );
+        } else {
+          const missing = questions
+            .filter((entry) => !answers.has(entry.id))
+            .map((entry) => entry.label)
+            .join(', ');
+          addWrappedWithPrefix(
+            ' ',
+            theme.fg('warning', `Answer ${missing} to continue`),
+          );
+        }
+      } else if (question !== undefined) {
+        addWrappedWithPrefix(
+          ' ',
+          theme.fg('accent', theme.bold(question.prompt)),
+        );
+        const saved = answers.get(question.id);
+        if (saved !== undefined) {
+          addWrappedWithPrefix(
+            ' ',
+            theme.fg('muted', `Current: ${saved.label}`),
+          );
+        }
+        lines.push('');
+        renderOptionList();
+      }
+
+      if (!inputMode && currentTab !== questions.length) {
+        lines.push('');
+        const count = String(opts.length);
+        const help = isMulti
+          ? `↑↓ or 1–${count} · Enter · Tab next · Esc cancel`
+          : `↑↓ or 1–${count} · Enter select · Esc cancel`;
+        addWrappedWithPrefix(' ', theme.fg('dim', help));
+      }
+      lines.push(theme.fg('accent', '─'.repeat(renderWidth)));
+
+      cachedLines = lines;
+      return lines;
+    }
+
+    return {
+      render,
+      invalidate: () => {
+        cachedLines = undefined;
+      },
+      handleInput,
+    };
+  });
+}
+
+function optionIndexFromDigit(
+  data: string,
+  optionCount: number,
+): number | undefined {
+  if (data.length !== 1) {
+    return undefined;
+  }
+  const code = data.charCodeAt(0);
+  if (code < 49 || code > 57) {
+    return undefined;
+  }
+  const index = code - 49;
+  if (index >= optionCount) {
+    return undefined;
+  }
+  return index;
+}

package/extensions/guidelines/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { appendGuidelinesReminder } from './prompt.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerGuidelines(pi: ExtensionAPI): void {
+  pi.on('before_agent_start', (event) => {
+    const systemPrompt = appendGuidelinesReminder(event.systemPrompt);
+    if (systemPrompt === event.systemPrompt) {
+      return;
+    }
+    return { systemPrompt };
+  });
+}

package/extensions/guidelines/prompt.ts

@@ -0,0 +1,26 @@
+export const GUIDELINES_REMINDER_HEADING =
+  'Sideroom coding guidelines (always-on reminder):';
+
+export const GUIDELINES_REMINDER = `${GUIDELINES_REMINDER_HEADING}
+Before write or edit, read the sideroom-guidelines skill.
+Apply its Do/Don't table. If the path is .java, .php, .ts/.tsx, .py, .go, or .rs, also read that language file under the skill's references/languages/.
+Do not load other language files.`;
+
+export const LANGUAGE_DELTA_FILES = [
+  'go.md',
+  'java.md',
+  'php-laravel.md',
+  'python.md',
+  'rust.md',
+  'typescript.md',
+] as const;
+
+export function appendGuidelinesReminder(systemPrompt: string): string {
+  if (systemPrompt.includes(GUIDELINES_REMINDER_HEADING)) {
+    return systemPrompt;
+  }
+  if (systemPrompt.length === 0) {
+    return GUIDELINES_REMINDER;
+  }
+  return `${systemPrompt}\n\n${GUIDELINES_REMINDER}`;
+}