@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/policy/reviewed-artifact.ts

@@ -0,0 +1,97 @@
+export type ParsedJsonDocuments = {
+  readonly documents: ReadonlyArray<unknown>;
+  readonly hasMalformedCandidate: boolean;
+};
+
+/**
+ * Narrows an unknown value to a non-array record.
+ *
+ * @param value - Value to inspect.
+ * @returns `true` when the value is a record.
+ */
+export const isRecord = (
+  value: unknown,
+): value is Readonly<Record<string, unknown>> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Parses a complete JSON artifact and JSON fenced blocks while retaining
+ * whether any JSON-looking candidate was malformed.
+ *
+ * @param text - Reviewed artifact text.
+ * @returns Parsed documents and malformed-candidate state.
+ */
+export const parseJsonDocumentsWithValidity = (
+  text: string,
+): ParsedJsonDocuments => {
+  const documents: Array<unknown> = [];
+  let hasMalformedCandidate = false;
+  const addDocument = (candidate: string): void => {
+    try {
+      documents.push(JSON.parse(candidate));
+    } catch {
+      hasMalformedCandidate = true;
+    }
+  };
+
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    addDocument(trimmed);
+  }
+
+  const fences = /```(?:json)?[ \t]*\r?\n([\s\S]*?)```/giu;
+  for (const match of text.matchAll(fences)) {
+    const candidate = match[1]?.trim();
+    if (candidate) addDocument(candidate);
+  }
+  return { documents, hasMalformedCandidate };
+};
+
+/**
+ * Parses all valid JSON documents from a reviewed artifact.
+ *
+ * @param text - Reviewed artifact text.
+ * @returns Valid JSON documents in source order.
+ */
+export const parseJsonDocuments = (text: string): ReadonlyArray<unknown> =>
+  parseJsonDocumentsWithValidity(text).documents;
+
+/**
+ * Extracts verification commands for one role from a parsed artifact.
+ *
+ * @param value - Parsed artifact document.
+ * @param role - Verification role whose commands should be returned.
+ * @returns Command strings in artifact order.
+ */
+export const verificationCommands = (
+  value: unknown,
+  role: 'worker' | 'reviewer',
+): Array<string> => {
+  if (!isRecord(value) || !Array.isArray(value.repositories)) return [];
+  return value.repositories.flatMap((repository) => {
+    if (!isRecord(repository) || !Array.isArray(repository[role])) return [];
+    return repository[role].flatMap((check) =>
+      isRecord(check) && typeof check.command === 'string'
+        ? [check.command]
+        : [],
+    );
+  });
+};
+
+/**
+ * Extracts Bash command actions from a parsed remote-action artifact.
+ *
+ * @param value - Parsed artifact document.
+ * @returns Bash commands in artifact order.
+ */
+export const remoteActionCommands = (value: unknown): Array<string> => {
+  if (!isRecord(value) || !Array.isArray(value.actions)) return [];
+  return value.actions.flatMap((action) =>
+    isRecord(action) &&
+    action.toolName === 'bash' &&
+    isRecord(action.input) &&
+    typeof action.input.command === 'string'
+      ? [action.input.command]
+      : [],
+  );
+};

package/src/policy/reviewed-command-safety.ts

@@ -0,0 +1,150 @@
+import { basename } from 'node:path';
+import { tokenizeRestrictedCommand } from './restricted-command.ts';
+import { parseRestrictedGitCommand } from './restricted-git.ts';
+
+const SHELL_WRAPPERS: ReadonlySet<string> = new Set([
+  'bash',
+  'env',
+  'exec',
+  'fish',
+  'sh',
+  'xargs',
+  'zsh',
+]);
+const REMOTE_EXECUTABLES: ReadonlySet<string> = new Set([
+  'curl',
+  'scp',
+  'ssh',
+  'rsync',
+  'wget',
+]);
+const FORBIDDEN_LONG_PUSH_OPTIONS = [
+  '--force',
+  '--force-if-includes',
+  '--force-with-lease',
+  '--all',
+  '--delete',
+  '--mirror',
+  '--prune',
+  '--tags',
+] as const;
+const PUBLISH_EXECUTABLES: ReadonlySet<string> = new Set([
+  'bun',
+  'cargo',
+  'npm',
+  'pnpm',
+  'yarn',
+]);
+const LOCAL_VERIFICATION_GIT_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  'add',
+  'branch',
+  'commit',
+  'diff',
+  'grep',
+  'log',
+  'ls-files',
+  'rev-parse',
+  'show',
+  'status',
+  'worktree',
+]);
+
+const containsPublishOperation = (tokens: ReadonlyArray<string>): boolean =>
+  tokens
+    .slice(1)
+    .some((token) => token.length >= 3 && 'publish'.startsWith(token));
+
+const hasDestructivePushShortOption = (token: string): boolean =>
+  token.startsWith('-') &&
+  !token.startsWith('--') &&
+  (token.slice(1).includes('f') || token.slice(1).includes('d'));
+
+const hasForbiddenLongPushOption = (token: string): boolean => {
+  if (!token.startsWith('--') || token === '--') return false;
+  const optionName = token.split('=', 1)[0] ?? token;
+  return FORBIDDEN_LONG_PUSH_OPTIONS.some((option) =>
+    option.startsWith(optionName),
+  );
+};
+
+const hasEmptyPushRefspecSide = (token: string): boolean => {
+  const separator = token.indexOf(':');
+  return separator >= 0 && (separator === 0 || separator === token.length - 1);
+};
+
+/**
+ * Determines whether a reviewed verification command is safe to authorize.
+ *
+ * @param command - Exact command extracted from an approved artifact.
+ * @returns `true` for local, non-publishing verification commands.
+ */
+export const isSafeVerificationCommand = (command: string): boolean => {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens) return false;
+
+  const executable = basename(parsed.tokens[0] ?? '');
+  if (SHELL_WRAPPERS.has(executable) || REMOTE_EXECUTABLES.has(executable)) {
+    return false;
+  }
+
+  const subcommand =
+    executable === 'git'
+      ? parseRestrictedGitCommand(parsed.tokens)?.subcommand
+      : parsed.tokens[1];
+  if (
+    executable === 'git' &&
+    (!subcommand || !LOCAL_VERIFICATION_GIT_SUBCOMMANDS.has(subcommand))
+  ) {
+    return false;
+  }
+  if (executable === 'gh' || executable === 'glab') return false;
+  if (
+    PUBLISH_EXECUTABLES.has(executable) &&
+    containsPublishOperation(parsed.tokens)
+  ) {
+    return false;
+  }
+  return !(executable === 'docker' && parsed.tokens.slice(1).includes('push'));
+};
+
+const isHostedApiDelete = (tokens: ReadonlyArray<string>): boolean =>
+  tokens.slice(2).some((token, index, apiTokens) => {
+    const normalizedToken = token.toUpperCase();
+    return (
+      normalizedToken === '--METHOD=DELETE' ||
+      normalizedToken === '-XDELETE' ||
+      ((normalizedToken === '--METHOD' || normalizedToken === '-X') &&
+        apiTokens[index + 1]?.toUpperCase() === 'DELETE')
+    );
+  });
+
+/**
+ * Determines whether a reviewed remote action is narrowly safe to authorize.
+ *
+ * @param command - Exact command extracted from an approved artifact.
+ * @returns `true` for non-destructive Git pushes and hosted API writes.
+ */
+export const isSafeRemoteActionCommand = (command: string): boolean => {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens) return false;
+
+  const executable = parsed.tokens[0];
+  const subcommand =
+    executable === 'git'
+      ? parseRestrictedGitCommand(parsed.tokens)?.subcommand
+      : parsed.tokens[1];
+  if (executable === 'gh' || executable === 'glab') {
+    return subcommand === 'api' && !isHostedApiDelete(parsed.tokens);
+  }
+  if (executable !== 'git' || subcommand !== 'push') return false;
+
+  return !parsed.tokens
+    .slice(1)
+    .some(
+      (token) =>
+        hasForbiddenLongPushOption(token) ||
+        token.startsWith('+') ||
+        hasEmptyPushRefspecSide(token) ||
+        hasDestructivePushShortOption(token),
+    );
+};

package/src/policy/reviewed-command-shape.ts

@@ -0,0 +1,49 @@
+import { basename } from 'node:path';
+import { tokenizeRestrictedCommand } from './restricted-command.ts';
+import {
+  parseJsonDocuments,
+  verificationCommands,
+} from './reviewed-artifact.ts';
+
+const malformedBunInstallReason = (command: string): string | undefined => {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens || basename(parsed.tokens[0] ?? '') !== 'bun') {
+    return undefined;
+  }
+
+  const installIndex = parsed.tokens.indexOf('install', 1);
+  if (installIndex <= 1) return undefined;
+  const hasCwdBeforeInstall = parsed.tokens
+    .slice(1, installIndex)
+    .some((token) => token === '--cwd' || token.startsWith('--cwd='));
+  if (!hasCwdBeforeInstall) return undefined;
+
+  return [
+    `Invalid Bun install command: ${JSON.stringify(command)}.`,
+    '`--cwd` appears before `install`, so Bun interprets `install` as a package script.',
+    'Use `bun install --cwd <absolute-cwd> --frozen-lockfile`, preserving the reviewed path and any other intended install flags, then resubmit the plan.',
+  ].join(' ');
+};
+
+/**
+ * Rejects known command-shape mistakes before human approval.
+ *
+ * Deterministic checks prevent known parser traps from becoming approved
+ * capabilities while leaving arbitrary runtime diagnosis to the agent.
+ *
+ * @param artifact - Reviewed execution contract.
+ * @returns A corrective error message, or `undefined` when shapes are valid.
+ */
+export const reviewedCommandShapeError = (
+  artifact: string,
+): string | undefined => {
+  for (const document of parseJsonDocuments(artifact)) {
+    for (const role of ['worker', 'reviewer'] as const) {
+      for (const command of verificationCommands(document, role)) {
+        const reason = malformedBunInstallReason(command);
+        if (reason) return reason;
+      }
+    }
+  }
+  return undefined;
+};

package/src/policy/reviewed-repository-contract.ts

@@ -0,0 +1,138 @@
+import { isAbsolute } from 'node:path';
+import {
+  isRecord,
+  parseJsonDocumentsWithValidity,
+} from './reviewed-artifact.ts';
+
+export type ReviewedRepositoryContract =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'invalid'; readonly reason: string }
+  | {
+      readonly kind: 'valid';
+      readonly repositoryCwd: string;
+      readonly sourceCwd?: string;
+    };
+
+const invalidContract = (reason: string): ReviewedRepositoryContract => ({
+  kind: 'invalid',
+  reason,
+});
+
+const isAbsoluteSafePath = (value: unknown): value is string =>
+  typeof value === 'string' && isAbsolute(value) && !value.includes('\0');
+
+type RepositoryDirectories = {
+  readonly repositoryDirectories: ReadonlySet<string>;
+  readonly sourceDirectories: ReadonlySet<string>;
+};
+
+const addRepositoryDirectories = (
+  document: Readonly<Record<string, unknown>>,
+  repositoryDirectories: Set<string>,
+  sourceDirectories: Set<string>,
+): ReviewedRepositoryContract | undefined => {
+  if (
+    !Array.isArray(document.repositories) ||
+    document.repositories.length === 0
+  ) {
+    return invalidContract(
+      'Reviewed repository contract must contain a non-empty repositories array',
+    );
+  }
+
+  for (const repository of document.repositories) {
+    if (!isRecord(repository)) {
+      return invalidContract(
+        'Reviewed repository contract contains a malformed repository entry',
+      );
+    }
+    if (!isAbsoluteSafePath(repository.cwd)) {
+      return invalidContract(
+        'Reviewed repository contract repository cwd must be an absolute path',
+      );
+    }
+    repositoryDirectories.add(repository.cwd);
+
+    if ('sourceCwd' in repository) {
+      if (!isAbsoluteSafePath(repository.sourceCwd)) {
+        return invalidContract(
+          'Reviewed repository contract sourceCwd must be an absolute path',
+        );
+      }
+      sourceDirectories.add(repository.sourceCwd);
+    }
+  }
+  return undefined;
+};
+
+const collectRepositoryDirectories = (
+  documents: ReadonlyArray<unknown>,
+): RepositoryDirectories | ReviewedRepositoryContract => {
+  const repositoryDirectories = new Set<string>();
+  const sourceDirectories = new Set<string>();
+
+  for (const document of documents) {
+    if (!isRecord(document) || !('repositories' in document)) continue;
+    const error = addRepositoryDirectories(
+      document,
+      repositoryDirectories,
+      sourceDirectories,
+    );
+    if (error) return error;
+  }
+  return { repositoryDirectories, sourceDirectories };
+};
+
+/**
+ * Parses and validates the repository-directory portion of a reviewed artifact.
+ *
+ * This function is the pure validation core; filesystem availability is
+ * resolved separately.
+ *
+ * @param artifact - Human-reviewed artifact text.
+ * @returns A validated repository contract, absence, or validation error.
+ */
+export const parseReviewedRepositoryContract = (
+  artifact: string,
+): ReviewedRepositoryContract => {
+  const parsed = parseJsonDocumentsWithValidity(artifact);
+  const hasRepositoryContract = parsed.documents.some(
+    (document) => isRecord(document) && 'repositories' in document,
+  );
+  if (!hasRepositoryContract) {
+    return parsed.hasMalformedCandidate
+      ? invalidContract('Reviewed repository contract contains malformed JSON')
+      : { kind: 'none' };
+  }
+
+  const collected = collectRepositoryDirectories(parsed.documents);
+  if ('kind' in collected) return collected;
+  if (parsed.hasMalformedCandidate) {
+    return invalidContract(
+      'Reviewed repository contract contains malformed JSON',
+    );
+  }
+  if (collected.repositoryDirectories.size !== 1) {
+    return invalidContract(
+      'Reviewed repository contract is ambiguous: expected exactly one repository cwd',
+    );
+  }
+  if (collected.sourceDirectories.size > 1) {
+    return invalidContract(
+      'Reviewed repository contract is ambiguous: expected at most one sourceCwd',
+    );
+  }
+
+  const [repositoryCwd] = collected.repositoryDirectories;
+  if (!repositoryCwd) {
+    return invalidContract(
+      'Reviewed repository contract is ambiguous: expected exactly one repository cwd',
+    );
+  }
+  const [sourceCwd] = collected.sourceDirectories;
+  return {
+    kind: 'valid',
+    repositoryCwd,
+    ...(sourceCwd ? { sourceCwd } : {}),
+  };
+};

package/src/policy/reviewed-repository-cwd.ts

@@ -0,0 +1,102 @@
+import { statSync } from 'node:fs';
+import { isRecord } from './reviewed-artifact.ts';
+import { parseReviewedRepositoryContract } from './reviewed-repository-contract.ts';
+
+export type ReviewedRepositoryCwdResolution =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'invalid'; readonly reason: string }
+  | {
+      readonly kind: 'resolved';
+      readonly cwd: string;
+      readonly repositoryCwd: string;
+      readonly bootstrapping: boolean;
+    };
+
+export type DirectoryState = 'directory' | 'missing' | 'invalid';
+
+export type ReviewedRepositoryCwdDependencies = {
+  readonly readDirectoryState: (path: string) => DirectoryState;
+};
+
+export type ResolveReviewedRepositoryCwd = (
+  artifact: string,
+) => ReviewedRepositoryCwdResolution;
+
+const readDirectoryState = (path: string): DirectoryState => {
+  try {
+    return statSync(path).isDirectory() ? 'directory' : 'invalid';
+  } catch (error) {
+    const code = isRecord(error) ? error.code : undefined;
+    return code === 'ENOENT' || code === 'ENOTDIR' ? 'missing' : 'invalid';
+  }
+};
+
+const invalidResolution = (
+  reason: string,
+): ReviewedRepositoryCwdResolution => ({
+  kind: 'invalid',
+  reason,
+});
+
+/**
+ * Creates a reviewed-directory resolver with an injected filesystem reader.
+ *
+ * The injected boundary keeps contract parsing and launch-path selection
+ * deterministic and independently testable.
+ *
+ * @param dependencies - Filesystem operations used by the resolver.
+ * @returns A resolver bound to those dependencies.
+ */
+export const createReviewedRepositoryCwdResolver = (
+  dependencies: ReviewedRepositoryCwdDependencies,
+): ResolveReviewedRepositoryCwd => {
+  return (artifact): ReviewedRepositoryCwdResolution => {
+    const contract = parseReviewedRepositoryContract(artifact);
+    if (contract.kind !== 'valid') return contract;
+
+    const repositoryState = dependencies.readDirectoryState(
+      contract.repositoryCwd,
+    );
+    if (repositoryState === 'directory') {
+      return {
+        kind: 'resolved',
+        cwd: contract.repositoryCwd,
+        repositoryCwd: contract.repositoryCwd,
+        bootstrapping: false,
+      };
+    }
+    if (repositoryState === 'invalid') {
+      return invalidResolution(
+        `Reviewed repository cwd is not an accessible directory: ${contract.repositoryCwd}`,
+      );
+    }
+    if (!contract.sourceCwd) {
+      return invalidResolution(
+        'Reviewed repository target is missing and requires exactly one absolute sourceCwd',
+      );
+    }
+    if (dependencies.readDirectoryState(contract.sourceCwd) !== 'directory') {
+      return invalidResolution(
+        `Reviewed repository sourceCwd is not an existing directory: ${contract.sourceCwd}`,
+      );
+    }
+    return {
+      kind: 'resolved',
+      cwd: contract.sourceCwd,
+      repositoryCwd: contract.repositoryCwd,
+      bootstrapping: true,
+    };
+  };
+};
+
+/**
+ * Resolves the launch directory from a reviewed repository contract.
+ *
+ * Malformed, ambiguous, or incomplete contracts never fall back silently.
+ *
+ * @param artifact - Human-reviewed artifact text.
+ * @returns The resolved directory, absence, or a validation error.
+ */
+export const resolveReviewedRepositoryCwd = createReviewedRepositoryCwdResolver(
+  { readDirectoryState },
+);

package/src/policy/tool-call-authorization.ts

@@ -0,0 +1,58 @@
+import type { WorkflowStep } from '../config/types.ts';
+import { authorizeBash } from './bash.ts';
+import { authorizeMcpProxy } from './mcp-authorization.ts';
+import { isAllowedExtensionTool } from './tool-selection.ts';
+import type { ToolAuthorization, ToolInventoryItem } from './tool-types.ts';
+
+const reject = (reason: string): ToolAuthorization => ({
+  allowed: false,
+  reason,
+});
+
+/**
+ * Authorizes a tool call against the active workflow-step policy.
+ *
+ * MCP and Bash calls receive their additional protocol-specific validation
+ * after the tool itself has been selected.
+ *
+ * @param toolName - Requested tool name.
+ * @param input - Requested tool input.
+ * @param step - Active workflow step.
+ * @param inventory - Registered tool inventory.
+ * @param approvedBashCommands - Exact commands derived from human review.
+ * @returns The authorization decision.
+ */
+export const authorizeToolCall = (
+  toolName: string,
+  input: Readonly<Record<string, unknown>>,
+  step: WorkflowStep,
+  inventory: ReadonlyArray<ToolInventoryItem>,
+  approvedBashCommands: ReadonlyArray<string> = [],
+): ToolAuthorization => {
+  if (toolName === 'mcp') {
+    return authorizeMcpProxy(input, step.permissions.mcp);
+  }
+
+  const tool = inventory.find((candidate) => candidate.name === toolName);
+  const isAllowedByName = step.permissions.tools.includes(toolName);
+  const isAllowedByExtension =
+    tool !== undefined &&
+    isAllowedExtensionTool(tool, step.permissions.extensions);
+  if (!isAllowedByName && !isAllowedByExtension) {
+    return reject(`tool "${toolName}" is not allowed for this workflow step`);
+  }
+  if (toolName !== 'bash') return { allowed: true };
+
+  const command = input.command;
+  if (typeof command !== 'string') {
+    return reject('Bash call is missing command text');
+  }
+  const result = authorizeBash(
+    command,
+    step.permissions.bash,
+    approvedBashCommands,
+  );
+  return result.allowed
+    ? { allowed: true }
+    : reject(result.reason ?? 'Bash command is not allowed');
+};

package/src/policy/tool-selection.ts

@@ -0,0 +1,72 @@
+import type { WorkflowStep } from '../config/types.ts';
+import type { ToolInventoryItem } from './tool-types.ts';
+
+const sourceText = (tool: ToolInventoryItem): string =>
+  `${tool.sourceInfo?.source ?? ''}\n${tool.sourceInfo?.path ?? ''}`.toLowerCase();
+
+const isMcpAdapterTool = (tool: ToolInventoryItem): boolean =>
+  sourceText(tool).includes('pi-mcp-adapter');
+
+/**
+ * Determines whether a tool belongs to an allowed extension selector.
+ *
+ * Built-in and SDK tools are never treated as extension-provided tools.
+ *
+ * @param tool - Registered tool inventory item.
+ * @param selector - Case-insensitive source or path fragment.
+ * @returns `true` when the extension selector matches.
+ */
+export const matchesExtensionSelector = (
+  tool: ToolInventoryItem,
+  selector: string,
+): boolean => {
+  const source = tool.sourceInfo?.source;
+  return (
+    source !== 'builtin' &&
+    source !== 'sdk' &&
+    sourceText(tool).includes(selector.toLowerCase())
+  );
+};
+
+/**
+ * Selects tools available to the active workflow step.
+ *
+ * @param inventory - Registered tool inventory.
+ * @param step - Active workflow step.
+ * @param completionToolName - Completion tool that must always remain active.
+ * @returns Unique selected tool names in inventory order.
+ */
+export const resolveActiveTools = (
+  inventory: ReadonlyArray<ToolInventoryItem>,
+  step: WorkflowStep,
+  completionToolName: string,
+): Array<string> => {
+  const exactToolNames = new Set(step.permissions.tools);
+  const selectedToolNames = inventory
+    .filter(
+      (tool) =>
+        tool.name === completionToolName ||
+        exactToolNames.has(tool.name) ||
+        (tool.name === 'mcp' && step.permissions.mcp.length > 0) ||
+        (!isMcpAdapterTool(tool) &&
+          step.permissions.extensions.some((selector) =>
+            matchesExtensionSelector(tool, selector),
+          )),
+    )
+    .map((tool) => tool.name);
+  return [...new Set(selectedToolNames)];
+};
+
+/**
+ * Determines whether a tool can be authorized through an extension selector.
+ *
+ * @param tool - Registered tool inventory item.
+ * @param selectors - Allowed extension selectors.
+ * @returns `true` when a non-MCP-adapter extension selector matches.
+ */
+export const isAllowedExtensionTool = (
+  tool: ToolInventoryItem,
+  selectors: ReadonlyArray<string>,
+): boolean =>
+  !isMcpAdapterTool(tool) &&
+  selectors.some((selector) => matchesExtensionSelector(tool, selector));

package/src/policy/tool-types.ts

@@ -0,0 +1,14 @@
+export type ToolSourceInfo = {
+  readonly source?: string;
+  readonly path?: string;
+};
+
+export type ToolInventoryItem = {
+  readonly name: string;
+  readonly sourceInfo?: ToolSourceInfo;
+};
+
+export type ToolAuthorization = {
+  readonly allowed: boolean;
+  readonly reason?: string;
+};