pi-helper-core 0.1.0

package/src/core/runner.ts

@@ -0,0 +1,128 @@
+import { spawn } from 'node:child_process';
+
+export interface RunOptions {
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** Cap applied to stdout and stderr independently. */
+  maxBytes?: number;
+  stdin?: string;
+}
+
+export interface RunResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  cancelled: boolean;
+  truncated: boolean;
+  durationMs: number;
+}
+
+function appendLimited(current: string, chunk: string, maxBytes: number): [string, boolean] {
+  const next = current + chunk;
+  if (Buffer.byteLength(next, 'utf8') <= maxBytes) return [next, false];
+  return [Buffer.from(next, 'utf8').subarray(0, maxBytes).toString('utf8'), true];
+}
+
+/**
+ * Single bounded subprocess entry point for every helper.
+ *
+ * User-supplied paths and package names must always reach the process through
+ * `args`, never through a shell string, and every call must stay inside a
+ * timeout and an output cap. Killing the whole process group matters because a
+ * toolchain driver spawns compilers and linkers that would otherwise survive.
+ */
+export async function runCommand(
+  executable: string,
+  args: string[],
+  options: RunOptions,
+): Promise<RunResult> {
+  const maxBytes = options.maxBytes ?? 100 * 1024;
+  const startedAt = Date.now();
+  const child = spawn(executable, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env },
+    detached: process.platform !== 'win32',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  if (options.stdin !== undefined) child.stdin.write(options.stdin);
+  child.stdin.end();
+
+  let stdout = '';
+  let stderr = '';
+  let truncated = false;
+  let timedOut = false;
+  let cancelled = false;
+  let spawnError: Error | undefined;
+  const onAbort = () => {
+    cancelled = true;
+    terminate(child);
+  };
+  options.signal?.addEventListener('abort', onAbort, { once: true });
+  const timeout = options.timeoutMs
+    ? setTimeout(() => {
+        timedOut = true;
+        terminate(child);
+      }, options.timeoutMs)
+    : undefined;
+
+  // A missing executable arrives here rather than as a rejection, so the
+  // message is folded into stderr where a failure diagnosis already looks.
+  child.on('error', (error) => {
+    spawnError = error;
+  });
+  child.stdout.on('data', (chunk: Buffer) => {
+    const [next, wasTruncated] = appendLimited(stdout, chunk.toString(), maxBytes);
+    stdout = next;
+    truncated ||= wasTruncated;
+  });
+  child.stderr.on('data', (chunk: Buffer) => {
+    const [next, wasTruncated] = appendLimited(stderr, chunk.toString(), maxBytes);
+    stderr = next;
+    truncated ||= wasTruncated;
+  });
+  const code = await new Promise<number | null>((resolve) =>
+    child.once('close', (exitCode) => resolve(exitCode)),
+  );
+  if (timeout) clearTimeout(timeout);
+  options.signal?.removeEventListener('abort', onAbort);
+  if (spawnError) stderr = `${stderr}${stderr ? '\n' : ''}${spawnError.message}`;
+  return {
+    code,
+    stdout,
+    stderr,
+    timedOut,
+    cancelled,
+    truncated,
+    durationMs: Date.now() - startedAt,
+  };
+}
+
+function terminate(child: ReturnType<typeof spawn>): void {
+  if (child.pid === undefined) return;
+  try {
+    // The negative pid targets the process group, so child compilers die too.
+    if (process.platform !== 'win32') process.kill(-child.pid, 'SIGTERM');
+    else child.kill('SIGTERM');
+  } catch {
+    child.kill('SIGTERM');
+  }
+}
+
+/** A command failed to start at all, which is an environment problem.
+ *
+ * Node reports a spawn error through `error` and then closes the child with a
+ * negative code, so the exit code alone cannot identify this case; the message
+ * is the reliable signal.
+ */
+export function isSpawnFailure(result: RunResult): boolean {
+  return (
+    !result.timedOut &&
+    !result.cancelled &&
+    result.code !== 0 &&
+    /ENOENT|EACCES|not found|Failed to spawn|command not found/i.test(result.stderr)
+  );
+}

package/src/core/safety.ts

@@ -0,0 +1,167 @@
+import type { CommandRisk } from './result.ts';
+
+/**
+ * Risk is inferred from the command text, never from a domain name, because no
+ * toolchain has a deterministic signal like `cmd_vel`. A compound command
+ * inherits the highest risk of its segments so nothing hides behind a safe
+ * sibling.
+ */
+
+const RISK_ORDER: Record<CommandRisk, number> = { read: 0, mutating: 1, irreversible: 2 };
+
+export interface RiskRule {
+  pattern: RegExp;
+  risk: Exclude<CommandRisk, 'read'>;
+  reason: string;
+}
+
+export interface SafetyRules {
+  /**
+   * Matched before risk patterns so a read-only flag does not inherit the risk
+   * of the command it qualifies (`--check`, `--dry-run`, `--collect-only`).
+   */
+  safeOverrides: RegExp[];
+  patterns: RiskRule[];
+}
+
+/**
+ * Read-only forms that would otherwise inherit their command's risk.
+ * Ecosystem-neutral: these are generic flags, not tool names.
+ */
+export const UNIVERSAL_SAFE_OVERRIDES: RegExp[] = [
+  /\bgit\s+(?:diff|log|status|show|rev-parse|ls-files|cat-file|describe|rev-list)\b/,
+  /\bgit\s+branch\s+--show-current\b/,
+  /(?:^|\s)--(?:check|dry-run|collect-only|list|frozen|locked)\b/,
+];
+
+/**
+ * Risks that do not depend on the ecosystem: repository history, the file
+ * system, containers, and databases behave the same everywhere. Anything that
+ * names a package manager belongs to the adapter.
+ */
+export const UNIVERSAL_RISK_PATTERNS: RiskRule[] = [
+  // Irreversible: cannot be undone by a local revert.
+  {
+    risk: 'irreversible',
+    pattern: /\bgit\s+push\b[^&|;]*(?:--force(?:-with-lease)?|(?<![\w-])-f(?![a-z]))/,
+    reason: 'Force pushing rewrites shared remote history.',
+  },
+  {
+    risk: 'irreversible',
+    pattern: /\bgit\s+(?:reset\s+--hard|clean\b[^&|;]*-[a-z]*f)/,
+    reason: 'Hard reset or clean discards uncommitted work permanently.',
+  },
+  {
+    risk: 'irreversible',
+    pattern: /\brm\b[^&|;]*-[a-z]*[rf][a-z]*/,
+    reason: 'Recursive or forced deletion is not recoverable.',
+  },
+  {
+    risk: 'irreversible',
+    pattern:
+      /\b(?:drop|truncate)\s+(?:table|database|schema)\b|\bdelete\s+from\b(?![^&|;]*\bwhere\b)/i,
+    reason: 'Destructive SQL without a narrowing predicate.',
+  },
+  {
+    risk: 'irreversible',
+    pattern: /\bdocker\s+(?:system|volume|image)\s+(?:prune|rm)\b/,
+    reason: 'Docker prune removes volumes or images outside the project.',
+  },
+
+  // Mutating: recoverable, but changes project, repository, or remote state.
+  {
+    risk: 'mutating',
+    pattern: /\bgit\s+(?:commit|add|checkout|switch|restore|stash|merge|rebase|push|tag|init)\b/,
+    reason: 'Changes repository or remote state.',
+  },
+  {
+    risk: 'mutating',
+    pattern: /\b(?:rm|mv|chmod|chown|truncate)\b/,
+    reason: 'Changes files on disk.',
+  },
+];
+
+/**
+ * `curl ... | sh` is invisible after segment splitting because the pipe itself
+ * is the hazard, so it is matched against the whole command first.
+ */
+const PIPE_TO_SHELL = /\b(?:curl|wget)\b[^;&\n]*\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b/;
+
+export interface CommandClassification {
+  risk: CommandRisk;
+  reasons: { segment: string; risk: CommandRisk; reason: string }[];
+}
+
+/** Split a compound command so no segment can hide behind a safe sibling. */
+export function splitCommandSegments(command: string): string[] {
+  return command
+    .split(/&&|\|\||;|\n|\|/)
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+}
+
+function mergeRules(rules?: Partial<SafetyRules>): SafetyRules {
+  return {
+    safeOverrides: [...UNIVERSAL_SAFE_OVERRIDES, ...(rules?.safeOverrides ?? [])],
+    patterns: [...UNIVERSAL_RISK_PATTERNS, ...(rules?.patterns ?? [])],
+  };
+}
+
+function classifySegment(
+  segment: string,
+  rules: SafetyRules,
+): { risk: CommandRisk; reason?: string } {
+  if (rules.safeOverrides.some((pattern) => pattern.test(segment))) return { risk: 'read' };
+  for (const entry of rules.patterns) {
+    if (entry.pattern.test(segment)) return { risk: entry.risk, reason: entry.reason };
+  }
+  return { risk: 'read' };
+}
+
+/**
+ * Classify a shell command by the highest risk of its segments. Used to warn
+ * before running something that cannot be undone, and to gate a helper's own
+ * state-changing commands behind explicit opt-in.
+ *
+ * The adapter supplies only the ecosystem-specific rules; the universal ones
+ * are always applied, so a new helper cannot forget `git push --force`.
+ */
+export function classifyCommand(
+  command: string,
+  rules?: Partial<SafetyRules>,
+): CommandClassification {
+  const merged = mergeRules(rules);
+  const piped = command.match(PIPE_TO_SHELL);
+  if (piped) {
+    return {
+      risk: 'irreversible',
+      reasons: [
+        {
+          segment: piped[0].trim(),
+          risk: 'irreversible',
+          reason: 'Piping a download into a shell runs unreviewed code.',
+        },
+      ],
+    };
+  }
+
+  const reasons: CommandClassification['reasons'] = [];
+  let risk: CommandRisk = 'read';
+  for (const segment of splitCommandSegments(command)) {
+    const classified = classifySegment(segment, merged);
+    if (RISK_ORDER[classified.risk] > RISK_ORDER[risk]) risk = classified.risk;
+    if (classified.risk !== 'read' && classified.reason) {
+      reasons.push({ segment, risk: classified.risk, reason: classified.reason });
+    }
+  }
+  return { risk, reasons };
+}
+
+export function isMutatingCommand(command: string, rules?: Partial<SafetyRules>): boolean {
+  return classifyCommand(command, rules).risk !== 'read';
+}
+
+/** Commands a helper runs itself always carry a known risk class. */
+export function riskOf(args: string[], rules?: Partial<SafetyRules>): CommandRisk {
+  return classifyCommand(args.join(' '), rules).risk;
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Ecosystem-neutral core for pi language helper extensions.
+ *
+ * A helper keeps the ecosystem knowledge (command names, manifest formats,
+ * output parsers) and imports everything shared from here: the response
+ * envelope, the bounded command runner, risk classification, the completion
+ * gates, artifact staleness, and test selection.
+ *
+ * Nothing in this package may name an ecosystem. `test/purity.test.ts` enforces
+ * that, because the whole point of extracting the core is that a new helper
+ * only has to write its adapter.
+ */
+
+export {
+  CORE_SCHEMA_VERSION,
+  createResultFactory,
+  isActionable,
+  note,
+  warn,
+  type CommandPreview,
+  type CommandRisk,
+  type Diagnostic,
+  type Evidence,
+  type ResultFactory,
+  type ResultInput,
+  type Severity,
+  type Suggestion,
+  type ToolchainInfo,
+  type ToolMetadata,
+  type ToolResult,
+} from './core/result.ts';
+
+export { isSpawnFailure, runCommand, type RunOptions, type RunResult } from './core/runner.ts';
+
+export {
+  classifyCommand,
+  isMutatingCommand,
+  riskOf,
+  splitCommandSegments,
+  UNIVERSAL_RISK_PATTERNS,
+  UNIVERSAL_SAFE_OVERRIDES,
+  type CommandClassification,
+  type RiskRule,
+  type SafetyRules,
+} from './core/safety.ts';
+
+export {
+  buildCompletionEvidence,
+  type CompletionEvidence,
+  type CompletionEvidenceInput,
+  type PreparationStage,
+} from './validation/evidence.ts';
+
+export {
+  checkTdd,
+  type TddAssociation,
+  type TddCheckpoint,
+  type TddSignals,
+} from './validation/tdd.ts';
+
+export {
+  summarizeValidation,
+  type ValidationLabels,
+  type ValidationStep,
+  type ValidationSummary,
+} from './validation/bundle.ts';
+
+export {
+  detectStaleArtifacts,
+  UNIVERSAL_IGNORED_DIRECTORIES,
+  type StaleArtifact,
+  type StaleArtifactSpec,
+  type StalenessReport,
+  type StalenessSpec,
+} from './build/staleness.ts';
+
+export {
+  DEFAULT_SCORE,
+  normalizedStem,
+  selectTests,
+  type SelectionOptions,
+  type SelectionResult,
+  type SelectionSignals,
+  type TestImportMap,
+  type TestSelection,
+} from './selection/select.ts';
+
+export {
+  defineAdapter,
+  type AdapterContext,
+  type CheckCommandInput,
+  type DerivedArtifact,
+  type EcosystemAdapter,
+  type FailureDiagnosis,
+  type FailureFrame,
+  type ProjectModel,
+  type ProjectPackage,
+  type TestCommandInput,
+  type TestCounts,
+  type TestFailure,
+  type TestReport,
+} from './adapter.ts';