paseo-form-render 0.0.0-stage → 0.2.0

package/shared/parser.ts

@@ -0,0 +1,119 @@
+import {
+  capIssues,
+  findDuplicateIdIssues,
+  formatIssues,
+  formatJsonParseError,
+  formatZodIssues,
+  type FormIssue,
+} from "./form-errors";
+import { PfrForm, PfrFormSchema } from "./schema";
+
+export interface ParsedBlock {
+  type: "text" | "form";
+  content?: string;
+  form?: PfrForm;
+  rawJson?: string;
+  /** Structured problems (at most 10, plus an "...and N more" entry); set when the block failed. */
+  errors?: FormIssue[];
+  /** `errors` joined one per line, for display. */
+  error?: string;
+}
+
+interface FenceBlock {
+  start: number;
+  contentStart: number;
+  contentEnd: number;
+  end: number;
+}
+
+function findBlocks(text: string): FenceBlock[] {
+  const blocks: FenceBlock[] = [];
+  const fences = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)\r?$/gm;
+  let opening: RegExpExecArray | null;
+
+  while ((opening = fences.exec(text)) !== null) {
+    const marker = opening[1];
+    const label = opening[2].trim();
+    const contentStart = opening.index + opening[0].length;
+    const closing = new RegExp(
+      `^ {0,3}${marker[0]}{${marker.length},}[ \\t]*\\r?$`,
+      "gm",
+    );
+    closing.lastIndex = contentStart;
+    const end = closing.exec(text);
+
+    if (label === "pfr-form") {
+      blocks.push({
+        start: opening.index,
+        contentStart,
+        contentEnd: end ? end.index : text.length,
+        end: end ? end.index + end[0].length : text.length,
+      });
+    }
+
+    if (!end) break;
+    fences.lastIndex = end.index + end[0].length;
+  }
+
+  return blocks;
+}
+
+export function hasFormBlock(text: string): boolean {
+  return findBlocks(text).length > 0;
+}
+
+function failedBlock(rawJson: string, issues: FormIssue[]): ParsedBlock {
+  const errors = capIssues(issues);
+  return { type: "form", rawJson, errors, error: formatIssues(errors).join("\n") };
+}
+
+export function parseFormBlock(jsonStr: string): ParsedBlock {
+  const trimmed = jsonStr.trim();
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(trimmed);
+  } catch (e) {
+    return failedBlock(trimmed, formatJsonParseError(trimmed, e));
+  }
+
+  const validation = PfrFormSchema.safeParse(parsedJson);
+  const issues = [
+    ...(validation.success ? [] : formatZodIssues(validation.error.issues, parsedJson)),
+    ...findDuplicateIdIssues(parsedJson),
+  ];
+  if (issues.length > 0) {
+    return failedBlock(trimmed, issues);
+  }
+  return { type: "form", form: validation.data as PfrForm, rawJson: trimmed };
+}
+
+export function parseMessageContent(text: string): ParsedBlock[] {
+  const blocks: ParsedBlock[] = [];
+  const fenceBlocks = findBlocks(text);
+  let cursor = 0;
+
+  for (const block of fenceBlocks) {
+    // Leading text
+    if (block.start > cursor) {
+      const leadingText = text.slice(cursor, block.start).trim();
+      if (leadingText) {
+        blocks.push({ type: "text", content: leadingText });
+      }
+    }
+
+    const jsonStr = text.slice(block.contentStart, block.contentEnd).trim();
+    blocks.push(parseFormBlock(jsonStr));
+
+    cursor = block.end;
+  }
+
+  // Trailing text
+  if (cursor < text.length) {
+    const trailingText = text.slice(cursor).trim();
+    if (trailingText) {
+      blocks.push({ type: "text", content: trailingText });
+    }
+  }
+
+  return blocks;
+}

package/shared/pickers.ts

@@ -0,0 +1,50 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const ProjectFileEntrySchema = z.object({
+  name: z.string(),
+  isDirectory: z.boolean(),
+  relativePath: z.string(),
+  fullPath: z.string().optional(),
+});
+export type ProjectFileEntry = z.infer<typeof ProjectFileEntrySchema>;
+
+export const FilePickerShortcutSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  icon: z.string(),
+  path: z.string(),
+});
+export type FilePickerShortcut = z.infer<typeof FilePickerShortcutSchema>;
+
+export const listProjectFilesRpc = defineRpc({
+  name: "pfr.list-project-files",
+  input: z.object({
+    agentId: z.string(),
+    subPath: z.string().optional(),
+    targetPath: z.string().optional(),
+  }),
+  output: z.object({
+    currentPath: z.string(),
+    parentPath: z.string().nullable(),
+    entries: z.array(ProjectFileEntrySchema),
+    shortcuts: z.array(FilePickerShortcutSchema).optional(),
+    isWorkspaceRelative: z.boolean().optional(),
+    error: z.string().optional(),
+  }),
+});
+
+export const createDirectoryRpc = defineRpc({
+  name: "pfr.create-directory",
+  input: z.object({
+    agentId: z.string(),
+    parentPath: z.string().min(1),
+    name: z.string().min(1),
+  }),
+  output: z.object({
+    success: z.boolean(),
+    fullPath: z.string().optional(),
+    relativePath: z.string().optional(),
+    error: z.string().optional(),
+  }),
+});

package/shared/prompt.ts

@@ -0,0 +1,96 @@
+import { PFR_FIX_MARKER } from "./form-fix";
+
+export const PFR_FORM_TAG = "pfr-form";
+
+const PROMPT_BODY = `You can render interactive forms, dashboards, parameter inputs, and approval cards by outputting a JSON specification inside a fenced code block with the tag \`\`\`pfr-form.
+
+Use this format whenever you need to:
+1. Collect input or configuration from the user (text, choices, toggles).
+2. Ask for user confirmation or approval before running an action.
+3. Present metrics, status progress, or structured data tables clearly.
+
+### Protocol Specification
+The JSON is a nested component tree starting with a root node (usually a "Card").
+Available component types:
+- **Card**: { "type": "Card", "title"?: string, "description"?: string, "children": [...] }
+- **Stack**: { "type": "Stack", "direction"?: "vertical"|"horizontal", "children": [...] }
+- **Heading**: { "type": "Heading", "text": string }
+- **Text**: { "type": "Text", "text": string, "muted"?: boolean }
+- **Divider**: { "type": "Divider" }
+- **Metric**: { "type": "Metric", "label": string, "value": string|number }
+- **Badge**: { "type": "Badge", "text": string, "tone"?: "neutral"|"info"|"success"|"warning"|"danger" }
+- **Alert**: { "type": "Alert", "title"?: string, "text": string, "tone"?: "neutral"|"info"|"success"|"warning"|"danger" }
+- **Progress**: { "type": "Progress", "label": string, "value": number (0-100) }
+- **Table**: { "type": "Table", "columns": [{ "key": string, "label": string }], "rows": [{ [key: string]: any }] }
+- **Input**: { "type": "Input", "id": string, "label": string, "placeholder"?: string, "defaultValue"?: string|number, "inputType"?: "text"|"number"|"integer"|"email"|"password"|"url", "multiline"?: boolean, "required"?: boolean, "min"?: number, "max"?: number, "minLength"?: number, "maxLength"?: number, "pattern"?: string }
+- **Select**: { "type": "Select", "id": string, "label": string, "options": [{ "label": string, "value": string }], "defaultValue"?: string, "required"?: boolean }
+- **MultiSelect**: { "type": "MultiSelect", "id": string, "label": string, "placeholder"?: string, "options": [{ "label": string, "value": string }], "defaultValue"?: string[], "required"?: boolean, "min"?: number, "max"?: number }
+- **FilePicker**: { "type": "FilePicker", "id": string, "label": string, "placeholder"?: string, "pickerType"?: "file"|"folder", "extensions"?: string[], "defaultValue"?: string, "required"?: boolean }
+  * Unified in-app modal file and folder picker with quick shortcuts (Project, Home, Desktop, Downloads, OneDrive). Returns project-relative path if inside workspace, or host absolute path if outside. Zero cold start latency, foreground-guaranteed. When asking for specific file types (e.g. mp4, mov, png, json), ALWAYS specify "extensions": ["mp4"].
+- **Toggle**: { "type": "Toggle", "id": string, "label": string, "defaultValue"?: boolean, "required"?: boolean }
+- **Button**: { "type": "Button", "label": string, "variant"?: "primary"|"secondary"|"danger", "action": "submit"|"reset", "message"?: string }
+
+### Important Rules:
+1. Always give input fields (\`Input\`, \`Select\`, \`MultiSelect\`, \`FilePicker\`, \`Toggle\`) a unique \`id\`.
+2. When filtering files by extension, use \`"extensions": ["mp4"]\` (or comma-separated string, leading dot optional).
+3. When the user clicks a \`Button\` with \`action: "submit"\`, the client automatically sends the button's \`message\` along with all field values back to you.
+4. Keep conversational text outside the code fence. The code block should only contain valid JSON.
+5. If you receive a message starting with \`${PFR_FIX_MARKER}\`, a previous pfr-form block failed validation. Re-output only the corrected, complete pfr-form block(s), addressing every listed issue, with valid JSON and no comments.
+
+### Example:
+\`\`\`pfr-form
+{
+  "type": "Card",
+  "title": "Deployment Confirmation",
+  "description": "Please review settings before releasing.",
+  "children": [
+    {
+      "type": "Metric",
+      "label": "Target Environment",
+      "value": "Production"
+    },
+    {
+      "type": "Input",
+      "id": "release_tag",
+      "label": "Release Tag",
+      "placeholder": "e.g., v1.0.4",
+      "required": true
+    },
+    {
+      "type": "Select",
+      "id": "strategy",
+      "label": "Deploy Strategy",
+      "options": [
+        { "label": "Rolling Update", "value": "rolling" },
+        { "label": "Canary (10%)", "value": "canary" }
+      ],
+      "defaultValue": "rolling"
+    },
+    {
+      "type": "Button",
+      "label": "Confirm & Deploy",
+      "variant": "primary",
+      "action": "submit",
+      "message": "Start deployment with the selected parameters."
+    }
+  ]
+}
+\`\`\`
+`.trim();
+
+/** Appended when the "prefer forms" setting is on; the default prompt only says the agent *can* use pfr-form. */
+const PREFER_FORMS_INSTRUCTION = `
+### Required usage:
+Prefer pfr-form over plain text for interacting with the user:
+- When you need anything from the user — a choice, a parameter, a value, or a go/no-go confirmation — you MUST ask with an \`pfr-form\` block, not plain-text questions.
+- When presenting results, status, or structured data (metrics, progress, tables, warnings), use the matching components (Metric, Progress, Table, Alert, Badge) where they make the result clearer.
+Plain text is fine for ordinary explanation and short conversational replies.
+`.trim();
+
+export function buildPromptInstruction(options: { preferForms?: boolean } = {}): string {
+  const parts = [PROMPT_BODY];
+  if (options.preferForms) parts.push(PREFER_FORMS_INSTRUCTION);
+  return `[paseo-form-render]\n${parts.join("\n\n")}\n[/paseo-form-render]`;
+}
+
+export const PFR_PROMPT_INSTRUCTION = buildPromptInstruction();

package/shared/schema.ts

@@ -0,0 +1,330 @@
+import { z } from "zod";
+
+// Basic field options
+export const OptionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+export type Option = z.infer<typeof OptionSchema>;
+
+// Table column schema
+export const TableColumnSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+});
+export type TableColumn = z.infer<typeof TableColumnSchema>;
+
+// Tone variants for Alert and Badge
+export const ToneSchema = z.enum(["neutral", "info", "success", "warning", "danger"]);
+export type Tone = z.infer<typeof ToneSchema>;
+
+// Node base definition
+export type PfrNode =
+  | CardNode
+  | StackNode
+  | HeadingNode
+  | TextNode
+  | DividerNode
+  | MetricNode
+  | BadgeNode
+  | AlertNode
+  | ProgressNode
+  | TableNode
+  | InputNode
+  | SelectNode
+  | MultiSelectNode
+  | ToggleNode
+  | FilePickerNode
+  | ButtonNode;
+
+/** Every valid node `type`. The compile-time check below fails if a node type is missing from this list. */
+export const PFR_NODE_TYPES = [
+  "Card",
+  "Stack",
+  "Heading",
+  "Text",
+  "Divider",
+  "Metric",
+  "Badge",
+  "Alert",
+  "Progress",
+  "Table",
+  "Input",
+  "Select",
+  "MultiSelect",
+  "Toggle",
+  "FilePicker",
+  "Button",
+] as const satisfies readonly PfrNode["type"][];
+type MissingNodeTypes = Exclude<PfrNode["type"], (typeof PFR_NODE_TYPES)[number]>;
+const _allNodeTypesListed: [MissingNodeTypes] extends [never] ? true : never = true;
+void _allNodeTypesListed;
+
+/** Node types that collect a value and therefore need a unique `id`. */
+export const PFR_FIELD_TYPES = ["Input", "Select", "MultiSelect", "Toggle", "FilePicker"] as const;
+
+export interface CardNode {
+  type: "Card";
+  title?: string;
+  description?: string;
+  children: PfrNode[];
+}
+
+export interface StackNode {
+  type: "Stack";
+  direction?: "vertical" | "horizontal";
+  children: PfrNode[];
+}
+
+export interface HeadingNode {
+  type: "Heading";
+  text: string;
+}
+
+export interface TextNode {
+  type: "Text";
+  text: string;
+  muted?: boolean;
+}
+
+export interface DividerNode {
+  type: "Divider";
+}
+
+export interface MetricNode {
+  type: "Metric";
+  label: string;
+  value: string | number;
+}
+
+export interface BadgeNode {
+  type: "Badge";
+  text: string;
+  tone?: Tone;
+}
+
+export interface AlertNode {
+  type: "Alert";
+  title?: string;
+  text: string;
+  tone?: Tone;
+}
+
+export interface ProgressNode {
+  type: "Progress";
+  label: string;
+  value: number; // 0 - 100
+}
+
+export interface TableNode {
+  type: "Table";
+  columns: TableColumn[];
+  rows: Record<string, string | number | boolean | null>[];
+}
+
+export type InputType = "text" | "number" | "integer" | "email" | "password" | "url";
+
+export interface InputNode {
+  type: "Input";
+  id: string;
+  label: string;
+  placeholder?: string;
+  defaultValue?: string | number;
+  inputType?: InputType;
+  multiline?: boolean;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+}
+
+export interface SelectNode {
+  type: "Select";
+  id: string;
+  label: string;
+  options: Option[];
+  defaultValue?: string;
+  required?: boolean;
+}
+
+export interface MultiSelectNode {
+  type: "MultiSelect";
+  id: string;
+  label: string;
+  placeholder?: string;
+  options: Option[];
+  defaultValue?: string[];
+  required?: boolean;
+  min?: number;
+  max?: number;
+}
+
+export interface ToggleNode {
+  type: "Toggle";
+  id: string;
+  label: string;
+  defaultValue?: boolean;
+  required?: boolean;
+}
+
+export function normalizeExtensions(
+  extensions?: string[] | string,
+  extension?: string,
+): string[] | undefined {
+  const rawList: string[] = [];
+  if (Array.isArray(extensions)) {
+    rawList.push(...extensions);
+  } else if (typeof extensions === "string") {
+    rawList.push(...extensions.split(","));
+  }
+  if (typeof extension === "string") {
+    rawList.push(...extension.split(","));
+  }
+
+  const cleaned = rawList
+    .map((e) => e.trim().toLowerCase().replace(/^\./, ""))
+    .filter(Boolean);
+
+  return cleaned.length > 0 ? Array.from(new Set(cleaned)) : undefined;
+}
+
+export interface FilePickerNode {
+  type: "FilePicker";
+  id: string;
+  label: string;
+  pickerType?: "file" | "folder";
+  scope?: "workspace" | "global";
+  placeholder?: string;
+  defaultValue?: string;
+  required?: boolean;
+  extensions?: string[] | string;
+  extension?: string;
+}
+
+export interface ButtonNode {
+  type: "Button";
+  label: string;
+  variant?: "primary" | "secondary" | "danger";
+  action: "submit" | "reset";
+  message?: string; // Prompt/message returned to agent when submitted
+}
+
+// Recursive Zod Schema for validation
+export const PfrNodeSchema: z.ZodType<PfrNode> = z.lazy(() =>
+  z.discriminatedUnion("type", [
+    z.object({
+      type: z.literal("Card"),
+      title: z.string().optional(),
+      description: z.string().optional(),
+      children: z.array(PfrNodeSchema),
+    }),
+    z.object({
+      type: z.literal("Stack"),
+      direction: z.enum(["vertical", "horizontal"]).optional(),
+      children: z.array(PfrNodeSchema),
+    }),
+    z.object({
+      type: z.literal("Heading"),
+      text: z.string(),
+    }),
+    z.object({
+      type: z.literal("Text"),
+      text: z.string(),
+      muted: z.boolean().optional(),
+    }),
+    z.object({
+      type: z.literal("Divider"),
+    }),
+    z.object({
+      type: z.literal("Metric"),
+      label: z.string(),
+      value: z.union([z.string(), z.number()]),
+    }),
+    z.object({
+      type: z.literal("Badge"),
+      text: z.string(),
+      tone: ToneSchema.optional(),
+    }),
+    z.object({
+      type: z.literal("Alert"),
+      title: z.string().optional(),
+      text: z.string(),
+      tone: ToneSchema.optional(),
+    }),
+    z.object({
+      type: z.literal("Progress"),
+      label: z.string(),
+      value: z.number().min(0).max(100),
+    }),
+    z.object({
+      type: z.literal("Table"),
+      columns: z.array(TableColumnSchema).min(1),
+      rows: z.array(z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))),
+    }),
+    z.object({
+      type: z.literal("Input"),
+      id: z.string().min(1),
+      label: z.string(),
+      placeholder: z.string().optional(),
+      defaultValue: z.union([z.string(), z.number()]).optional(),
+      inputType: z.enum(["text", "number", "integer", "email", "password", "url"]).optional(),
+      multiline: z.boolean().optional(),
+      required: z.boolean().optional(),
+      min: z.number().optional(),
+      max: z.number().optional(),
+      minLength: z.number().int().nonnegative().optional(),
+      maxLength: z.number().int().nonnegative().optional(),
+      pattern: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal("Select"),
+      id: z.string().min(1),
+      label: z.string(),
+      options: z.array(OptionSchema).min(1),
+      defaultValue: z.string().optional(),
+      required: z.boolean().optional(),
+    }),
+    z.object({
+      type: z.literal("MultiSelect"),
+      id: z.string().min(1),
+      label: z.string(),
+      placeholder: z.string().optional(),
+      options: z.array(OptionSchema).min(1),
+      defaultValue: z.array(z.string()).optional(),
+      required: z.boolean().optional(),
+      min: z.number().int().nonnegative().optional(),
+      max: z.number().int().nonnegative().optional(),
+    }),
+    z.object({
+      type: z.literal("Toggle"),
+      id: z.string().min(1),
+      label: z.string(),
+      defaultValue: z.boolean().optional(),
+      required: z.boolean().optional(),
+    }),
+    z.object({
+      type: z.literal("FilePicker"),
+      id: z.string().min(1),
+      label: z.string(),
+      pickerType: z.enum(["file", "folder"]).optional(),
+      scope: z.enum(["workspace", "global"]).optional(),
+      placeholder: z.string().optional(),
+      defaultValue: z.string().optional(),
+      required: z.boolean().optional(),
+      extensions: z.union([z.string(), z.array(z.string())]).optional(),
+      extension: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal("Button"),
+      label: z.string(),
+      variant: z.enum(["primary", "secondary", "danger"]).optional(),
+      action: z.enum(["submit", "reset"]),
+      message: z.string().optional(),
+    }),
+  ]),
+);
+
+export const PfrFormSchema = PfrNodeSchema;
+export type PfrForm = PfrNode;

package/shared/settings.ts

@@ -0,0 +1,18 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const MAX_AUTO_FIX_RETRIES = 5;
+export const DEFAULT_AUTO_FIX_RETRIES = 2;
+export const DEFAULT_PREFER_FORMS = true;
+
+export const pfrSettings = defineSettings({
+  id: "paseo-form-render",
+  scope: "host",
+  version: 1,
+  schema: z.object({
+    /** How many times the agent is asked to repair an invalid pfr-form block in a row. 0 disables auto-fix. */
+    autoFixMaxRetries: z.number().int().min(0).max(MAX_AUTO_FIX_RETRIES).default(DEFAULT_AUTO_FIX_RETRIES),
+    /** When on, the injected prompt requires agents to ask for user input with pfr-form instead of plain text. */
+    preferForms: z.boolean().default(DEFAULT_PREFER_FORMS),
+  }),
+});