@aliou/pi-guardrails 0.11.2 → 0.12.1

package/extensions/guardrails/commands/settings/path-list-editor.ts

@@ -0,0 +1,158 @@
+import {
+  type Component,
+  Input,
+  Key,
+  matchesKey,
+  type SettingsListTheme,
+} from "@earendil-works/pi-tui";
+
+export class PathListEditor implements Component {
+  private readonly input = new Input();
+  private items: string[];
+  private selectedIndex = 0;
+  private mode: "list" | "add" | "edit" = "list";
+  private editIndex = -1;
+
+  constructor(
+    private readonly options: {
+      label: string;
+      items: string[];
+      theme: SettingsListTheme;
+      onSave: (items: string[]) => void;
+      onDone: () => void;
+      maxVisible?: number;
+    },
+  ) {
+    this.items = [...options.items];
+    this.input.onSubmit = () => this.submit();
+    this.input.onEscape = () => this.cancel();
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const lines = [
+      this.options.theme.label(` ${this.options.label}`, true),
+      "",
+    ];
+    if (this.mode === "add" || this.mode === "edit") {
+      lines.push(
+        this.options.theme.hint(
+          this.mode === "edit" ? "  Edit path:" : "  New path:",
+        ),
+        "",
+        ...this.input.render(Math.max(1, width - 4)).map((line) => `  ${line}`),
+        "",
+        this.options.theme.hint("  Enter: save · Esc: cancel"),
+      );
+      return lines;
+    }
+
+    if (this.items.length === 0) {
+      lines.push(this.options.theme.hint("  (empty)"));
+    } else {
+      const maxVisible = this.options.maxVisible ?? 10;
+      const startIndex = Math.max(
+        0,
+        Math.min(
+          this.selectedIndex - Math.floor(maxVisible / 2),
+          this.items.length - maxVisible,
+        ),
+      );
+      const endIndex = Math.min(startIndex + maxVisible, this.items.length);
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.items[i];
+        if (!item) continue;
+        const isSelected = i === this.selectedIndex;
+        const prefix = isSelected ? this.options.theme.cursor : "  ";
+        lines.push(prefix + this.options.theme.value(item, isSelected));
+      }
+      if (startIndex > 0 || endIndex < this.items.length) {
+        lines.push(
+          this.options.theme.hint(
+            `  (${this.selectedIndex + 1}/${this.items.length})`,
+          ),
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(
+      this.options.theme.hint(
+        "  a: add · e/Enter: edit · d: delete · Esc: back",
+      ),
+    );
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (this.mode === "add" || this.mode === "edit") {
+      this.input.handleInput(data);
+      return;
+    }
+
+    if (matchesKey(data, Key.up) || data === "k") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.items.length - 1
+          : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.items.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+    } else if (data === "a" || data === "A") {
+      this.mode = "add";
+      this.input.setValue("");
+    } else if (data === "e" || data === "E" || matchesKey(data, Key.enter)) {
+      this.startEdit();
+    } else if (data === "d" || data === "D") {
+      this.deleteSelected();
+    } else if (matchesKey(data, Key.escape)) {
+      this.options.onDone();
+    }
+  }
+
+  private startEdit(): void {
+    const item = this.items[this.selectedIndex];
+    if (!item) return;
+    this.mode = "edit";
+    this.editIndex = this.selectedIndex;
+    this.input.setValue(item);
+  }
+
+  private submit(): void {
+    const path = this.input.getValue().trim();
+    if (!path) {
+      this.cancel();
+      return;
+    }
+
+    if (this.mode === "edit") {
+      this.items[this.editIndex] = path;
+    } else {
+      this.items.push(path);
+      this.selectedIndex = this.items.length - 1;
+    }
+    this.items = [...new Set(this.items)];
+    this.options.onSave([...this.items]);
+    this.cancel();
+  }
+
+  private deleteSelected(): void {
+    if (this.items.length === 0) return;
+    this.items.splice(this.selectedIndex, 1);
+    if (this.selectedIndex >= this.items.length) {
+      this.selectedIndex = Math.max(0, this.items.length - 1);
+    }
+    this.options.onSave([...this.items]);
+  }
+
+  private cancel(): void {
+    this.mode = "list";
+    this.editIndex = -1;
+    this.input.setValue("");
+  }
+}

package/extensions/guardrails/commands/settings/scope-picker-submenu.ts

@@ -0,0 +1,69 @@
+import {
+  type Component,
+  Key,
+  matchesKey,
+  type SettingsListTheme,
+} from "@earendil-works/pi-tui";
+
+export class ScopePickerSubmenu implements Component {
+  private selectedIndex = 0;
+
+  constructor(
+    private readonly theme: SettingsListTheme,
+    private readonly scopes: Array<"global" | "local" | "memory">,
+    private readonly onSelect: (scope: "global" | "local" | "memory") => void,
+    private readonly onDone: (value?: string) => void,
+  ) {}
+
+  invalidate() {}
+
+  render(_width: number): string[] {
+    const lines: string[] = [
+      this.theme.label(" Add example to scope", true),
+      "",
+      this.theme.hint("  Select target scope:"),
+    ];
+
+    for (let i = 0; i < this.scopes.length; i++) {
+      const scope = this.scopes[i];
+      if (!scope) continue;
+      const isSelected = i === this.selectedIndex;
+      const prefix = isSelected ? this.theme.cursor : "  ";
+      lines.push(`${prefix}${this.theme.value(scope, isSelected)}`);
+    }
+
+    lines.push("");
+    lines.push(this.theme.hint("  Enter: apply · Esc: back"));
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.scopes.length - 1
+          : this.selectedIndex - 1;
+      return;
+    }
+
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.selectedIndex =
+        this.selectedIndex === this.scopes.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+      return;
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      const scope = this.scopes[this.selectedIndex];
+      if (!scope) return;
+      this.onSelect(scope);
+      this.onDone(`applied to ${scope}`);
+      return;
+    }
+
+    if (matchesKey(data, Key.escape)) {
+      this.onDone();
+    }
+  }
+}

package/extensions/guardrails/commands/settings/utils.ts

@@ -0,0 +1,108 @@
+import { getNestedValue, setNestedValue } from "@aliou/pi-utils-settings";
+import type {
+  GuardrailsConfig,
+  PatternConfig,
+  PolicyRule,
+  Protection,
+} from "../../../../src/shared/config";
+
+export interface NewPolicyRuleDraft {
+  name: string;
+  id: string;
+  protection: Protection;
+  patterns: PatternConfig[];
+}
+
+export function toKebabCase(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function countItems(config: GuardrailsConfig, id: string): string {
+  const val = (getNestedValue(config, id) as unknown[] | undefined) ?? [];
+  return `${val.length} items`;
+}
+
+export function setConfigValue(
+  config: GuardrailsConfig,
+  id: string,
+  value: unknown,
+): GuardrailsConfig {
+  const updated = structuredClone(config);
+  setNestedValue(updated, id, value);
+  return updated;
+}
+
+export function getPolicyRules(config: GuardrailsConfig): PolicyRule[] {
+  return config.policies?.rules?.map((rule) => ({ ...rule })) ?? [];
+}
+
+export function setPolicyRules(
+  config: GuardrailsConfig,
+  rules: PolicyRule[],
+): GuardrailsConfig {
+  const updated = structuredClone(config);
+  updated.policies = {
+    ...(updated.policies ?? {}),
+    rules,
+  };
+  return updated;
+}
+
+export function updatePolicyRule(
+  config: GuardrailsConfig,
+  index: number,
+  updater: (rule: PolicyRule) => PolicyRule,
+): GuardrailsConfig {
+  const rules = getPolicyRules(config);
+  const existing = rules[index];
+  if (!existing) return config;
+  rules[index] = updater(existing);
+  return setPolicyRules(config, rules);
+}
+
+export function deletePolicyRule(
+  config: GuardrailsConfig,
+  index: number,
+): GuardrailsConfig {
+  const rules = getPolicyRules(config);
+  if (!rules[index]) return config;
+  rules.splice(index, 1);
+  return setPolicyRules(config, rules);
+}
+
+export function addPolicyRuleDraft(
+  config: GuardrailsConfig,
+  draft: NewPolicyRuleDraft,
+): { config: GuardrailsConfig; index: number | null } {
+  const normalizedName = draft.name.trim();
+  if (!normalizedName || draft.patterns.length === 0) {
+    return { config, index: null };
+  }
+
+  const rules = getPolicyRules(config);
+  const baseId = toKebabCase(draft.id || normalizedName) || "policy";
+  const existingIds = new Set(rules.map((rule) => rule.id));
+
+  let id = baseId;
+  let i = 2;
+  while (existingIds.has(id)) {
+    id = `${baseId}-${i}`;
+    i++;
+  }
+
+  rules.push({
+    id,
+    name: normalizedName,
+    description: "",
+    patterns: draft.patterns,
+    protection: draft.protection,
+    onlyIfExists: true,
+    enabled: true,
+  });
+
+  return { config: setPolicyRules(config, rules), index: rules.length - 1 };
+}

package/extensions/guardrails/components/onboarding-choice-step.ts

@@ -0,0 +1,140 @@
+import { getSettingsTheme, type SettingsTheme } from "@aliou/pi-utils-settings";
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { Box, Key, Markdown, matchesKey } from "@earendil-works/pi-tui";
+import type { OnboardingState } from "./onboarding-types";
+
+abstract class OnboardingChoiceStep implements Component {
+  private selectedIndex = 0;
+  private readonly settingsTheme: SettingsTheme;
+
+  protected constructor(
+    private readonly theme: Theme,
+    private readonly onSelect: (selectedIndex: number) => void,
+  ) {
+    this.settingsTheme = getSettingsTheme(theme);
+  }
+
+  invalidate() {}
+
+  protected abstract getTitle(): string;
+  protected abstract getOptions(): string[];
+  protected abstract getExplanations(): string[];
+
+  render(width: number): string[] {
+    const options = this.getOptions();
+    const explanations = this.getExplanations();
+    const lines: string[] = [`  ${this.getTitle()}`, ""];
+
+    for (let i = 0; i < options.length; i++) {
+      const option = options[i];
+      if (!option) continue;
+      const selected = i === this.selectedIndex;
+      const prefix = selected ? this.settingsTheme.cursor : "  ";
+      const label = this.settingsTheme.value(` ${option}`, selected);
+      lines.push(`${prefix}${label}`);
+    }
+
+    lines.push("");
+
+    const explanationBox = new Box(1, 0, (s: string) => s);
+    explanationBox.addChild(
+      new Markdown(
+        explanations[this.selectedIndex] ?? "",
+        0,
+        0,
+        getMarkdownTheme(),
+        {
+          color: (s: string) => this.theme.fg("text", s),
+        },
+      ),
+    );
+
+    lines.push(...explanationBox.render(Math.max(1, width)));
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.selectedIndex = this.selectedIndex === 0 ? 1 : 0;
+      return;
+    }
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.selectedIndex = this.selectedIndex === 1 ? 0 : 1;
+      return;
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      this.onSelect(this.selectedIndex);
+    }
+  }
+}
+
+export class OnboardingDefaultsChoiceStep extends OnboardingChoiceStep {
+  constructor(state: OnboardingState, theme: Theme, onSelect: () => void) {
+    super(theme, (selectedIndex) => {
+      state.applyBuiltinDefaults = selectedIndex === 0;
+      onSelect();
+    });
+  }
+
+  protected getTitle(): string {
+    return "Pick how much built-in protection to start with.";
+  }
+
+  protected getOptions(): string[] {
+    return ["Recommended defaults", "Minimal setup"];
+  }
+
+  protected getExplanations(): string[] {
+    return [
+      [
+        "Use built-ins for common safety needs:",
+        "",
+        "- Protect secret files like `.env`, `.env.local`, `.env.production`, and `.dev.vars`",
+        "- Keep safe exceptions like `.env.example` and `*.sample.env`",
+        "- Require confirmation before running dangerous commands like `rm -rf`, `sudo`, and `dd of=`",
+      ].join("\n"),
+      [
+        "Start with no built-in file policy defaults.",
+        "",
+        "- Configure your own policies in `/guardrails:settings`",
+        "- Browse policy and command examples in `/guardrails:settings`",
+      ].join("\n"),
+    ];
+  }
+}
+
+export class OnboardingPathAccessStep extends OnboardingChoiceStep {
+  constructor(state: OnboardingState, theme: Theme, onSelect: () => void) {
+    super(theme, (selectedIndex) => {
+      state.pathAccessEnabled = selectedIndex === 0;
+      onSelect();
+    });
+  }
+
+  protected getTitle(): string {
+    return "Restrict access to your project directory?";
+  }
+
+  protected getOptions(): string[] {
+    return ["Ask before accessing outside files", "No restrictions"];
+  }
+
+  protected getExplanations(): string[] {
+    return [
+      [
+        "When enabled, guardrails will prompt you before the agent accesses files outside the current working directory.",
+        "",
+        "- You can grant access per-file or per-directory",
+        "- Grants can be session-only or permanent",
+        "- In non-interactive mode, outside access is blocked",
+      ].join("\n"),
+      [
+        "The agent can access any path on your system without prompting.",
+        "",
+        "- You can enable path access later in `/guardrails:settings`",
+      ].join("\n"),
+    ];
+  }
+}

package/extensions/guardrails/components/onboarding-finish-step.ts

@@ -0,0 +1,50 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { Key, Markdown, matchesKey } from "@earendil-works/pi-tui";
+import type { OnboardingState } from "./onboarding-types";
+
+export class OnboardingFinishStep implements Component {
+  private readonly recapMarkdown = new Markdown("", 2, 0, getMarkdownTheme());
+
+  constructor(
+    private readonly state: OnboardingState,
+    private readonly onFinish: () => void,
+  ) {}
+
+  invalidate() {
+    this.recapMarkdown.invalidate();
+  }
+
+  render(width: number): string[] {
+    const defaultsPart =
+      this.state.applyBuiltinDefaults === true
+        ? [
+            "You selected **Recommended defaults**.",
+            "",
+            "Guardrails will start with built-in protection, including:",
+            "- secret files like `.env`, `.env.local`, `.env.production`, `.dev.vars`",
+            "- safe exceptions like `.env.example` and `*.sample.env`",
+            "- confirmation before running dangerous commands like `rm -rf`, `sudo`, `dd of=`",
+          ].join("\n")
+        : [
+            "You selected **Minimal setup**.",
+            "",
+            "No built-in file policy defaults will be applied.",
+            "",
+            "You can configure policies later with `/guardrails:settings`.",
+          ].join("\n");
+
+    const pathAccessPart = this.state.pathAccessEnabled
+      ? "\n\n**Path access**: enabled (ask mode). The agent will prompt before accessing files outside the working directory."
+      : "\n\n**Path access**: disabled. No path restrictions.";
+
+    this.recapMarkdown.setText(defaultsPart + pathAccessPart);
+    return [...this.recapMarkdown.render(Math.max(1, width)), ""];
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.enter)) {
+      this.onFinish();
+    }
+  }
+}

package/extensions/guardrails/components/onboarding-intro-step.ts

@@ -0,0 +1,30 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { Key, matchesKey, Text } from "@earendil-works/pi-tui";
+
+export class OnboardingIntroStep implements Component {
+  private readonly introText = new Text("", 2, 0);
+
+  constructor(private readonly onNext: () => void) {}
+
+  invalidate() {
+    this.introText.invalidate();
+  }
+
+  render(width: number): string[] {
+    this.introText.setText(
+      "Guardrails helps prevent accidental exposure of secrets and risky actions.\n\nIt gives you two protections:\n- Policies: file access rules (`noAccess` or `readOnly`)\n- Permission gate: confirmation before dangerous commands run\n\nYou are choosing the starting defaults now. You can change them later in `/guardrails:settings`.",
+    );
+
+    return [
+      "  Welcome to Guardrails",
+      "",
+      ...this.introText.render(Math.max(1, width)),
+    ];
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.enter)) {
+      this.onNext();
+    }
+  }
+}

package/extensions/guardrails/components/onboarding-types.ts

@@ -0,0 +1,10 @@
+export interface OnboardingState {
+  applyBuiltinDefaults: boolean | null;
+  pathAccessEnabled: boolean | null;
+}
+
+export interface OnboardingResult {
+  completed: boolean;
+  applyBuiltinDefaults: boolean | null;
+  pathAccessEnabled: boolean | null;
+}

package/extensions/guardrails/components/onboarding-wizard.ts

@@ -0,0 +1,116 @@
+import { Wizard } from "@aliou/pi-utils-settings";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import {
+  OnboardingDefaultsChoiceStep,
+  OnboardingPathAccessStep,
+} from "./onboarding-choice-step";
+import { OnboardingFinishStep } from "./onboarding-finish-step";
+import { OnboardingIntroStep } from "./onboarding-intro-step";
+import type { OnboardingResult, OnboardingState } from "./onboarding-types";
+
+export type { OnboardingResult } from "./onboarding-types";
+
+export function createOnboardingWizard(
+  theme: Theme,
+  done: (result: OnboardingResult) => void,
+): Component {
+  const state: OnboardingState = {
+    applyBuiltinDefaults: null,
+    pathAccessEnabled: null,
+  };
+
+  let markWelcomeComplete: (() => void) | null = null;
+  let settled = false;
+
+  const finalize = (result: OnboardingResult) => {
+    if (settled) return;
+    settled = true;
+    done(result);
+  };
+
+  const wizard = new Wizard({
+    title: "Guardrails onboarding",
+    theme,
+    steps: [
+      {
+        label: "Welcome",
+        build: (ctx) => {
+          markWelcomeComplete = ctx.markComplete;
+          return new OnboardingIntroStep(() => {
+            ctx.markComplete();
+            ctx.goNext();
+          });
+        },
+      },
+      {
+        label: "Defaults",
+        build: (ctx) =>
+          new OnboardingDefaultsChoiceStep(state, theme, () => {
+            ctx.markComplete();
+            ctx.goNext();
+          }),
+      },
+      {
+        label: "Path access",
+        build: (ctx) =>
+          new OnboardingPathAccessStep(state, theme, () => {
+            ctx.markComplete();
+            ctx.goNext();
+          }),
+      },
+      {
+        label: "Recap",
+        build: (ctx) =>
+          new OnboardingFinishStep(state, () => {
+            if (state.applyBuiltinDefaults === null) return;
+            ctx.markComplete();
+            finalize({
+              completed: true,
+              applyBuiltinDefaults: state.applyBuiltinDefaults,
+              pathAccessEnabled: state.pathAccessEnabled,
+            });
+          }),
+      },
+    ],
+    onComplete: () => {
+      if (state.applyBuiltinDefaults === null) {
+        finalize({
+          completed: false,
+          applyBuiltinDefaults: null,
+          pathAccessEnabled: null,
+        });
+        return;
+      }
+      finalize({
+        completed: true,
+        applyBuiltinDefaults: state.applyBuiltinDefaults,
+        pathAccessEnabled: state.pathAccessEnabled,
+      });
+    },
+    onCancel: () =>
+      finalize({
+        completed: false,
+        applyBuiltinDefaults: null,
+        pathAccessEnabled: null,
+      }),
+    hintSuffix: "Enter select/continue",
+    minContentHeight: 12,
+  });
+
+  return {
+    render: (width) => wizard.render(width),
+    invalidate: () => wizard.invalidate(),
+    handleInput: (data: string) => {
+      if (
+        matchesKey(data, Key.tab) &&
+        wizard.getActiveIndex() === 0 &&
+        markWelcomeComplete
+      ) {
+        markWelcomeComplete();
+      }
+      wizard.handleInput(data);
+    },
+  };
+}