@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/config/validation/permissions.ts

@@ -0,0 +1,312 @@
+import {
+  EMPTY_PERMISSIONS,
+  type BashApprovalSource,
+  type BashMode,
+  type BashPermission,
+  type BashRule,
+  type StepPermissions,
+  type StepRequirements,
+} from '../types.ts';
+import {
+  BASH_APPROVAL_SOURCE_PATTERN,
+  EXECUTABLE_PATTERN,
+  isJsonObject,
+  MCP_SELECTOR_PATTERN,
+  readString,
+  readStringList,
+  rejectUnknownKeys,
+  RESOURCE_SELECTOR_PATTERN,
+  TOOL_PATTERN,
+  type ValidationErrors,
+} from './shared.ts';
+
+const BASH_APPROVAL_SOURCES = [
+  'verification-worker',
+  'verification-reviewer',
+  'remote-actions',
+  'remote-push',
+  'remote-drafts',
+] as const satisfies ReadonlyArray<BashApprovalSource>;
+
+function isBashApprovalSource(value: string): value is BashApprovalSource {
+  return BASH_APPROVAL_SOURCES.some((source) => source === value);
+}
+
+function emptyPermissions(): StepPermissions {
+  return {
+    tools: [],
+    mcp: [],
+    extensions: [],
+    skills: [],
+    bash: { mode: 'deny', allow: [] },
+  };
+}
+
+function emptyRequirements(): StepRequirements {
+  return {
+    tools: [],
+    extensions: [],
+    skills: [],
+  };
+}
+
+function parseBashRule(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): Array<BashRule> {
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return [];
+  }
+  rejectUnknownKeys(
+    value,
+    ['executable', 'argsPrefix', 'argsPrefixes'],
+    path,
+    errors,
+  );
+
+  const executable = readString(
+    value.executable,
+    `${path}.executable`,
+    errors,
+    { pattern: EXECUTABLE_PATTERN },
+  );
+  if (value.argsPrefix !== undefined && value.argsPrefixes !== undefined) {
+    errors.push(`${path}: argsPrefix and argsPrefixes are mutually exclusive`);
+  }
+
+  if (value.argsPrefixes === undefined) {
+    const argsPrefix = readStringList(
+      value.argsPrefix,
+      `${path}.argsPrefix`,
+      errors,
+      /^[^\s]+$/,
+    );
+    return executable ? [{ executable, argsPrefix }] : [];
+  }
+  if (!Array.isArray(value.argsPrefixes)) {
+    errors.push(`${path}.argsPrefixes: expected an array of argument arrays`);
+    return [];
+  }
+  if (value.argsPrefixes.length === 0) {
+    errors.push(`${path}.argsPrefixes: at least one prefix is required`);
+  }
+
+  const prefixes = value.argsPrefixes.reduce<Array<Array<string>>>(
+    (result, candidate, index) => {
+      const prefixPath = `${path}.argsPrefixes[${index}]`;
+      const prefix = readStringList(candidate, prefixPath, errors, /^[^\s]+$/);
+      if (Array.isArray(candidate) && candidate.length === 0) {
+        errors.push(`${prefixPath}: at least one argument is required`);
+        return result;
+      }
+      if (prefix.length === 0) return result;
+      if (
+        result.some(
+          (existing) => JSON.stringify(existing) === JSON.stringify(prefix),
+        )
+      ) {
+        errors.push(`${prefixPath}: duplicate argument prefix`);
+        return result;
+      }
+      return [...result, prefix];
+    },
+    [],
+  );
+  return executable
+    ? prefixes.map((argsPrefix) => ({ executable, argsPrefix }))
+    : [];
+}
+
+function parseBashPermission(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): BashPermission {
+  if (value === undefined) {
+    return { ...EMPTY_PERMISSIONS.bash, allow: [] };
+  }
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return { ...EMPTY_PERMISSIONS.bash, allow: [] };
+  }
+  rejectUnknownKeys(
+    value,
+    ['mode', 'allow', 'approvedSources', 'handoffSources'],
+    path,
+    errors,
+  );
+
+  const mode = readString(value.mode, `${path}.mode`, errors);
+  const isValidMode =
+    mode === 'deny' ||
+    mode === 'read-only' ||
+    mode === 'allow-list' ||
+    mode === 'unrestricted';
+  if (!isValidMode) {
+    errors.push(
+      `${path}.mode: expected deny, read-only, allow-list, or unrestricted`,
+    );
+  }
+
+  const allow = Array.isArray(value.allow)
+    ? value.allow.flatMap((rule, index) =>
+        parseBashRule(rule, `${path}.allow[${index}]`, errors),
+      )
+    : [];
+  if (value.allow !== undefined && !Array.isArray(value.allow)) {
+    errors.push(`${path}.allow: expected an array`);
+  }
+
+  const approvedSources = (
+    value.approvedSources === undefined
+      ? []
+      : readStringList(
+          value.approvedSources,
+          `${path}.approvedSources`,
+          errors,
+          BASH_APPROVAL_SOURCE_PATTERN,
+        )
+  ).filter(isBashApprovalSource);
+  const handoffSources = (
+    value.handoffSources === undefined
+      ? []
+      : readStringList(
+          value.handoffSources,
+          `${path}.handoffSources`,
+          errors,
+          /^(verification-worker|verification-reviewer)$/,
+        )
+  ) as Array<'verification-worker' | 'verification-reviewer'>;
+
+  const normalizedMode: BashMode = isValidMode ? mode : 'deny';
+  if (normalizedMode !== 'allow-list' && allow.length > 0) {
+    errors.push(`${path}.allow: only valid when mode is "allow-list"`);
+  }
+  if (
+    normalizedMode === 'allow-list' &&
+    allow.length === 0 &&
+    approvedSources.length === 0
+  ) {
+    errors.push(
+      `${path}: allow-list mode requires an allow rule or an approved command source`,
+    );
+  }
+  if (normalizedMode !== 'allow-list' && approvedSources.length > 0) {
+    errors.push(
+      `${path}.approvedSources: only valid when mode is "allow-list"`,
+    );
+  }
+  if (normalizedMode !== 'allow-list' && handoffSources.length > 0) {
+    errors.push(`${path}.handoffSources: only valid when mode is "allow-list"`);
+  }
+
+  return {
+    mode: normalizedMode,
+    allow,
+    ...(approvedSources.length > 0 ? { approvedSources } : {}),
+    ...(handoffSources.length > 0 ? { handoffSources } : {}),
+  };
+}
+
+/** Parse the permission block shared by workflow steps and user ceilings. */
+export function parsePermissions(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): StepPermissions {
+  if (value === undefined) {
+    return emptyPermissions();
+  }
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return emptyPermissions();
+  }
+  rejectUnknownKeys(
+    value,
+    ['tools', 'mcp', 'extensions', 'skills', 'bash'],
+    path,
+    errors,
+  );
+
+  const permissions: StepPermissions = {
+    tools: readStringList(value.tools, `${path}.tools`, errors, TOOL_PATTERN),
+    mcp: readStringList(value.mcp, `${path}.mcp`, errors, MCP_SELECTOR_PATTERN),
+    extensions: readStringList(
+      value.extensions,
+      `${path}.extensions`,
+      errors,
+      RESOURCE_SELECTOR_PATTERN,
+    ),
+    skills: readStringList(
+      value.skills,
+      `${path}.skills`,
+      errors,
+      RESOURCE_SELECTOR_PATTERN,
+    ),
+    bash: parseBashPermission(value.bash, `${path}.bash`, errors),
+  };
+  if (permissions.bash.mode !== 'deny' && !permissions.tools.includes('bash')) {
+    errors.push(`${path}.tools: must include "bash" when Bash is enabled`);
+  }
+  return permissions;
+}
+
+/** Parse requirements and ensure every requirement is permitted by the step. */
+export function parseRequirements(
+  value: unknown,
+  permissions: StepPermissions,
+  path: string,
+  errors: ValidationErrors,
+): StepRequirements {
+  if (value === undefined) return emptyRequirements();
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return emptyRequirements();
+  }
+  rejectUnknownKeys(value, ['tools', 'extensions', 'skills'], path, errors);
+
+  const requirements: StepRequirements = {
+    tools: readStringList(value.tools, `${path}.tools`, errors, TOOL_PATTERN),
+    extensions: readStringList(
+      value.extensions,
+      `${path}.extensions`,
+      errors,
+      RESOURCE_SELECTOR_PATTERN,
+    ),
+    skills: readStringList(
+      value.skills,
+      `${path}.skills`,
+      errors,
+      RESOURCE_SELECTOR_PATTERN,
+    ),
+  };
+
+  requirements.tools
+    .filter(
+      (tool) =>
+        !permissions.tools.includes(tool) &&
+        !(tool === 'mcp' && permissions.mcp.length > 0),
+    )
+    .forEach((tool) =>
+      errors.push(
+        `${path}.tools: required tool "${tool}" is not allowed by this step`,
+      ),
+    );
+  requirements.extensions
+    .filter((extension) => !permissions.extensions.includes(extension))
+    .forEach((extension) =>
+      errors.push(
+        `${path}.extensions: required extension "${extension}" is not allowed by this step`,
+      ),
+    );
+  requirements.skills
+    .filter((skill) => !permissions.skills.includes(skill))
+    .forEach((skill) =>
+      errors.push(
+        `${path}.skills: required skill "${skill}" is not allowed by this step`,
+      ),
+    );
+  return requirements;
+}

package/src/config/validation/prompt.ts

@@ -0,0 +1,21 @@
+const PROMPT_VARIABLES = new Set([
+  'workflow.input',
+  'workflow.id',
+  'run.id',
+  'step.id',
+  'step.title',
+  'last.summary',
+  'reviewed.artifact',
+  'reviewed.feedback',
+  'gate.feedback',
+]);
+
+/** Validate template variables embedded in resolved prompt text. */
+export function validatePromptText(text: string, path: string): Array<string> {
+  return [...text.matchAll(/\{\{([^{}]+)\}\}/g)].flatMap((match) => {
+    const variable = match[1]?.trim() ?? '';
+    return PROMPT_VARIABLES.has(variable)
+      ? []
+      : [`${path}: unknown prompt variable "{{${variable}}}"`];
+  });
+}

package/src/config/validation/settings.ts

@@ -0,0 +1,122 @@
+import {
+  DEFAULT_SETTINGS,
+  WORKFLOW_SCHEMA_VERSION,
+  type PermissionCeiling,
+  type WorkflowSettings,
+} from '../types.ts';
+import { parsePermissions } from './permissions.ts';
+import {
+  isJsonObject,
+  rejectUnknownKeys,
+  type ValidationErrors,
+  type ValidationResult,
+} from './shared.ts';
+import { readStatusShortcut } from './shortcut.ts';
+import { parseSubagentPermissionCeiling } from './subagent.ts';
+
+function parsePermissionCeiling(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): PermissionCeiling | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    ['tools', 'mcp', 'extensions', 'skills', 'bash', 'subagent'],
+    path,
+    errors,
+  );
+  const permissions = parsePermissions(
+    {
+      ...(value.tools !== undefined ? { tools: value.tools } : {}),
+      ...(value.mcp !== undefined ? { mcp: value.mcp } : {}),
+      ...(value.extensions !== undefined
+        ? { extensions: value.extensions }
+        : {}),
+      ...(value.skills !== undefined ? { skills: value.skills } : {}),
+      ...(value.bash !== undefined ? { bash: value.bash } : {}),
+    },
+    path,
+    errors,
+  );
+  const subagent =
+    value.subagent === undefined
+      ? undefined
+      : parseSubagentPermissionCeiling(
+          value.subagent,
+          `${path}.subagent`,
+          errors,
+        );
+  return {
+    ...permissions,
+    ...(subagent ? { subagent } : {}),
+  };
+}
+
+/** Validate and normalize untrusted user workflow settings. */
+export function validateSettings(
+  value: unknown,
+): ValidationResult<WorkflowSettings> {
+  const errors: ValidationErrors = [];
+  if (!isJsonObject(value)) {
+    return { errors: ['settings: expected an object'] };
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      '$schema',
+      'version',
+      'allowProjectWorkflows',
+      'statusShortcut',
+      'permissionCeiling',
+    ],
+    'settings',
+    errors,
+  );
+  if (value.$schema !== undefined && typeof value.$schema !== 'string') {
+    errors.push('settings.$schema: expected a string');
+  }
+  if (value.version !== WORKFLOW_SCHEMA_VERSION) {
+    errors.push(`settings.version: expected ${WORKFLOW_SCHEMA_VERSION}`);
+  }
+  const allowProjectWorkflows =
+    typeof value.allowProjectWorkflows === 'boolean'
+      ? value.allowProjectWorkflows
+      : false;
+  if (
+    value.allowProjectWorkflows !== undefined &&
+    typeof value.allowProjectWorkflows !== 'boolean'
+  ) {
+    errors.push('settings.allowProjectWorkflows: expected a boolean');
+  }
+  const statusShortcut = readStatusShortcut(
+    value.statusShortcut,
+    'settings.statusShortcut',
+    errors,
+  );
+  const permissionCeiling = parsePermissionCeiling(
+    value.permissionCeiling,
+    'settings.permissionCeiling',
+    errors,
+  );
+  if (allowProjectWorkflows && !permissionCeiling) {
+    errors.push(
+      'settings.permissionCeiling: required when project workflows are enabled',
+    );
+  }
+  if (errors.length > 0) return { errors };
+
+  return {
+    value: {
+      ...DEFAULT_SETTINGS,
+      allowProjectWorkflows,
+      statusShortcut,
+      ...(permissionCeiling ? { permissionCeiling } : {}),
+    },
+    errors,
+  };
+}

package/src/config/validation/shared.ts

@@ -0,0 +1,129 @@
+export type ValidationResult<TValue> = {
+  readonly value?: TValue;
+  readonly errors: ReadonlyArray<string>;
+};
+
+export type JsonObject = Record<string, unknown>;
+export type ValidationErrors = Array<string>;
+
+export const IDENTIFIER_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+export const OUTCOME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+export const TOOL_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+export const RESOURCE_SELECTOR_PATTERN = /^[A-Za-z0-9_@./:+-]+$/;
+export const MCP_SELECTOR_PATTERN = /^[A-Za-z0-9_.:-]+(?:\/[A-Za-z0-9_.:-]+)?$/;
+export const EXECUTABLE_PATTERN = /^[A-Za-z0-9_./+-]+$/;
+export const BASH_APPROVAL_SOURCE_PATTERN =
+  /^(verification-worker|verification-reviewer|remote-actions|remote-push|remote-drafts)$/;
+
+type StringOptions = {
+  readonly pattern?: RegExp;
+};
+
+type IntegerLimits = {
+  readonly min: number;
+  readonly max: number;
+};
+
+/** Return whether an unknown value is a plain JSON-style object. */
+export function isJsonObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Append diagnostics for object properties outside the supplied allow-list. */
+export function rejectUnknownKeys(
+  value: JsonObject,
+  allowed: ReadonlyArray<string>,
+  path: string,
+  errors: ValidationErrors,
+): void {
+  const allowedKeys = new Set(allowed);
+  Object.keys(value)
+    .filter((key) => !allowedKeys.has(key))
+    .forEach((key) => errors.push(`${path}: unknown property "${key}"`));
+}
+
+/** Parse and normalize a string, collecting a diagnostic when it is invalid. */
+export function readString(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+  options: StringOptions = {},
+): string | undefined {
+  if (typeof value !== 'string') {
+    errors.push(`${path}: expected a string`);
+    return undefined;
+  }
+
+  const result = value.trim();
+  if (result.length === 0) {
+    errors.push(`${path}: must not be empty`);
+    return undefined;
+  }
+  if (options.pattern && !options.pattern.test(result)) {
+    errors.push(`${path}: invalid value "${result}"`);
+    return undefined;
+  }
+  return result;
+}
+
+/** Parse a bounded integer, returning the supplied fallback on invalid input. */
+export function readInteger(
+  value: unknown,
+  fallback: number,
+  path: string,
+  errors: ValidationErrors,
+  limits: IntegerLimits,
+): number {
+  if (value === undefined) return fallback;
+  if (
+    typeof value !== 'number' ||
+    !Number.isInteger(value) ||
+    value < limits.min ||
+    value > limits.max
+  ) {
+    errors.push(
+      `${path}: expected an integer from ${limits.min} to ${limits.max}`,
+    );
+    return fallback;
+  }
+  return value;
+}
+
+/** Parse a boolean, returning the supplied fallback on invalid input. */
+export function readBoolean(
+  value: unknown,
+  fallback: boolean,
+  path: string,
+  errors: ValidationErrors,
+): boolean {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'boolean') {
+    errors.push(`${path}: expected a boolean`);
+    return fallback;
+  }
+  return value;
+}
+
+/** Parse a duplicate-free array of patterned strings. */
+export function readStringList(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+  pattern: RegExp,
+): Array<string> {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: expected an array of strings`);
+    return [];
+  }
+
+  return value.reduce<Array<string>>((result, item, index) => {
+    const parsed = readString(item, `${path}[${index}]`, errors, { pattern });
+    if (!parsed) return result;
+    if (result.includes(parsed)) {
+      errors.push(`${path}[${index}]: duplicate value "${parsed}"`);
+      return result;
+    }
+    return [...result, parsed];
+  }, []);
+}

package/src/config/validation/shortcut.ts

@@ -0,0 +1,118 @@
+import type { WorkflowSettings } from '../types.ts';
+import { DEFAULT_STATUS_SHORTCUT } from '../types.ts';
+import { readString, type ValidationErrors } from './shared.ts';
+
+const SHORTCUT_MODIFIERS = new Set(['ctrl', 'shift', 'alt', 'super']);
+const SHORTCUT_NAMED_KEYS = new Map<string, string>([
+  ['escape', 'escape'],
+  ['esc', 'esc'],
+  ['enter', 'enter'],
+  ['return', 'return'],
+  ['tab', 'tab'],
+  ['space', 'space'],
+  ['backspace', 'backspace'],
+  ['delete', 'delete'],
+  ['insert', 'insert'],
+  ['clear', 'clear'],
+  ['home', 'home'],
+  ['end', 'end'],
+  ['pageup', 'pageUp'],
+  ['pagedown', 'pageDown'],
+  ['up', 'up'],
+  ['down', 'down'],
+  ['left', 'left'],
+  ['right', 'right'],
+]);
+const SHORTCUT_SYMBOL_KEYS = new Set([
+  '`',
+  '-',
+  '=',
+  '[',
+  ']',
+  '\\',
+  ';',
+  "'",
+  ',',
+  '.',
+  '/',
+  '!',
+  '@',
+  '#',
+  '$',
+  '%',
+  '^',
+  '&',
+  '*',
+  '(',
+  ')',
+  '_',
+  '|',
+  '~',
+  '{',
+  '}',
+  ':',
+  '<',
+  '>',
+  '?',
+]);
+const MAX_SHORTCUT_CHARS = 64;
+
+function canonicalShortcutKey(value: string): string | undefined {
+  if (/^[a-z0-9]$/.test(value) || SHORTCUT_SYMBOL_KEYS.has(value)) {
+    return value;
+  }
+  if (/^f(?:[1-9]|1[0-2])$/.test(value)) return value;
+  return SHORTCUT_NAMED_KEYS.get(value);
+}
+
+function isStatusShortcut(
+  value: string,
+): value is WorkflowSettings['statusShortcut'] {
+  const parts = value.split('+');
+  const key = parts.pop() ?? '';
+  return (
+    canonicalShortcutKey(key.toLowerCase()) === key &&
+    parts.every((modifier) => SHORTCUT_MODIFIERS.has(modifier))
+  );
+}
+
+/** Parse and normalize the configured workflow status shortcut. */
+export function readStatusShortcut(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): WorkflowSettings['statusShortcut'] {
+  if (value === undefined) return DEFAULT_STATUS_SHORTCUT;
+  const shortcut = readString(value, path, errors);
+  if (!shortcut) return DEFAULT_STATUS_SHORTCUT;
+  if (shortcut.length > MAX_SHORTCUT_CHARS) {
+    errors.push(`${path}: must be at most ${MAX_SHORTCUT_CHARS} characters`);
+    return DEFAULT_STATUS_SHORTCUT;
+  }
+
+  const parts = shortcut.toLowerCase().split('+');
+  const key = parts.pop() ?? '';
+  const modifiers = parts;
+  const uniqueModifiers = new Set(modifiers);
+  const canonicalKey = canonicalShortcutKey(key);
+  const isPlainTypingKey =
+    modifiers.length === 0 && (key.length === 1 || key === 'space');
+  const isUnmatchableModifiedKey =
+    modifiers.length > 0 &&
+    (key === 'escape' || key === 'esc' || /^f(?:[1-9]|1[0-2])$/.test(key));
+  const isInvalid =
+    !canonicalKey ||
+    modifiers.length > SHORTCUT_MODIFIERS.size ||
+    uniqueModifiers.size !== modifiers.length ||
+    modifiers.some((modifier) => !SHORTCUT_MODIFIERS.has(modifier)) ||
+    isPlainTypingKey ||
+    isUnmatchableModifiedKey;
+
+  if (isInvalid) {
+    errors.push(`${path}: expected a supported Pi key id such as "ctrl+alt+w"`);
+    return DEFAULT_STATUS_SHORTCUT;
+  }
+
+  const normalized = [...modifiers, canonicalKey].join('+');
+  return isStatusShortcut(normalized) ? normalized : DEFAULT_STATUS_SHORTCUT;
+}