pi-python-helper 0.3.0 → 0.4.1

package/src/core/result.ts

@@ -1,129 +1,29 @@
-import { TOOL_VERSION } from './version.ts';
-
-export type DiagnosticSeverity = 'info' | 'warning' | 'error';
-
-export interface Diagnostic {
-  code?: string;
-  message: string;
-  severity: DiagnosticSeverity;
-  path?: string;
-  line?: number;
-}
-
-export interface Evidence {
-  kind: string;
-  message?: string;
-  [key: string]: unknown;
-}
-
-export interface Suggestion {
-  message: string;
-  confidence?: 'low' | 'medium' | 'high';
-  command?: string;
-}
-
-export interface CommandPreview {
-  executable: string;
-  args: string[];
-  cwd?: string;
-  /** Risk classification for the command; `read` commands never change project state. */
-  risk?: 'read' | 'mutating' | 'irreversible';
-}
-
-export interface ToolMetadata {
-  toolVersion: string;
-  cwd: string;
-  durationMs: number;
-  truncated: boolean;
-  projectRoot?: string;
-  pythonVersion?: string;
-}
-
 /**
- * Every tool in this package returns this shape so the agent can rely on a
- * single contract regardless of which diagnostic ran. Domain fields live in
- * `data`; everything the agent must reason about lives in the typed sections.
+ * Local shim over the shared `pi-helper-core` envelope.
+ *
+ * Every tool imports `result`/`failure` and the shared types from here, so the
+ * envelope is defined in exactly one place (`pi-helper-core`) while call sites
+ * stay unaware of that. `pythonVersion` moved into the ecosystem-neutral
+ * `metadata.toolchain` field.
  */
-export interface PyToolResult<T = unknown> {
-  /**
-   * The tool's own verdict, not "the tool ran". `true` means the question this
-   * tool asks was answered affirmatively: the project state is acceptable, the
-   * command succeeded, or the gate may proceed. A diagnostic tool that finds a
-   * problem therefore returns `ok: false` without the tool itself having
-   * failed. Read `attention` for "must the caller act".
-   */
-  ok: boolean;
-  /**
-   * `true` when the caller must act before proceeding: the tool failed, or it
-   * emitted a warning or an error. An `info` diagnostic is informational by
-   * definition and does not set this. Derived from `ok`, `warnings`, and
-   * `errors` unless a tool sets it explicitly, so `ok: false` always implies
-   * `attention: true` and no diagnostic is silently dropped. This is the field
-   * to read when the question is "do I need to do something".
-   */
-  attention: boolean;
-  summary: string;
-  data?: T;
-  evidence: Evidence[];
-  warnings: Diagnostic[];
-  errors: Diagnostic[];
-  suggestions: Suggestion[];
-  commands?: CommandPreview[];
-  metadata: ToolMetadata;
-}
+import { createResultFactory } from 'pi-helper-core';
+import { TOOL_VERSION } from './version.ts';
 
-/**
- * An `info` diagnostic records a fact; only a warning or an error asks the
- * caller to do something. Keeping them apart stops a purely informational note
- * from raising `attention`.
- */
-function isActionable(value: { warnings: Diagnostic[]; errors: Diagnostic[] }): boolean {
-  return [...value.warnings, ...value.errors].some((entry) => entry.severity !== 'info');
-}
+export const { result, failure } = createResultFactory(TOOL_VERSION);
 
-export function result<T>(
-  cwd: string,
-  startedAt: number,
-  value: Omit<PyToolResult<T>, 'metadata' | 'attention'> & {
-    attention?: boolean;
-    truncated?: boolean;
-    projectRoot?: string;
-    pythonVersion?: string;
-  },
-): PyToolResult<T> {
-  return {
-    ...value,
-    attention: value.attention ?? (!value.ok || isActionable(value)),
-    metadata: {
-      toolVersion: TOOL_VERSION,
-      cwd,
-      durationMs: Date.now() - startedAt,
-      truncated: value.truncated ?? false,
-      projectRoot: value.projectRoot,
-      pythonVersion: value.pythonVersion,
-    },
-  };
-}
+export { CORE_SCHEMA_VERSION, isActionable, note, warn } from 'pi-helper-core';
 
-export function failure(
-  cwd: string,
-  startedAt: number,
-  message: string,
-  code: string,
-  details?: Partial<PyToolResult>,
-): PyToolResult {
-  return result(cwd, startedAt, {
-    ok: false,
-    summary: message,
-    evidence: [],
-    warnings: [],
-    errors: [{ code, message, severity: 'error' }],
-    suggestions: [],
-    ...details,
-  });
-}
+export type {
+  CommandPreview,
+  CommandRisk,
+  Diagnostic,
+  Evidence,
+  Severity,
+  Suggestion,
+  ToolchainInfo,
+  ToolResult,
+} from 'pi-helper-core';
 
-/** Shared helper so diagnostics never lose their code when built inline. */
-export function warn(code: string, message: string, path?: string, line?: number): Diagnostic {
-  return { code, message, severity: 'warning', path, line };
-}
+/** The Python tools' view of the shared envelope. */
+export type PyToolResult<T = unknown> = import('pi-helper-core').ToolResult<T>;
+export type DiagnosticSeverity = import('pi-helper-core').Severity;

package/src/core/runner.ts

@@ -1,96 +1,5 @@
-import { spawn } from 'node:child_process';
-
-export interface RunOptions {
-  cwd: string;
-  env?: NodeJS.ProcessEnv;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  maxBytes?: number;
-  stdin?: string;
-}
-
-export interface RunResult {
-  code: number | null;
-  stdout: string;
-  stderr: string;
-  timedOut: boolean;
-  cancelled: boolean;
-  truncated: boolean;
-}
-
-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. 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.
+ * The bounded subprocess runner now lives in `pi-helper-core`; this module
+ * keeps the local import path so no call site has to change.
  */
-export async function runCommand(
-  executable: string,
-  args: string[],
-  options: RunOptions,
-): Promise<RunResult> {
-  const maxBytes = options.maxBytes ?? 100 * 1024;
-  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;
-
-  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 };
-}
-
-function terminate(child: ReturnType<typeof spawn>): void {
-  if (child.pid === undefined) return;
-  try {
-    if (process.platform !== 'win32') process.kill(-child.pid, 'SIGTERM');
-    else child.kill('SIGTERM');
-  } catch {
-    child.kill('SIGTERM');
-  }
-}
+export { isSpawnFailure, runCommand, type RunOptions, type RunResult } from 'pi-helper-core';

package/src/core/safety.ts

@@ -1,77 +1,56 @@
 /**
+ * Python's risk rules for the shared classifier.
+ *
  * Python has no equivalent of a `cmd_vel` topic that deterministically signals
- * actuation, so risk cannot be inferred from a domain name. Instead every
- * command is classified from its own text, and a compound command inherits the
- * highest risk of its segments.
+ * actuation, so risk is read from the command text. Segment splitting, safe
+ * override precedence, and the compound-command merge live in
+ * `pi-helper-core`; this module supplies only the package-manager, environment,
+ * and migration rules that are specific to Python. The universal rules (git
+ * history, file deletion, destructive SQL, containers, pipe-to-shell) are
+ * applied by the core and must not be repeated here.
  */
-export type CommandRisk = 'read' | 'mutating' | 'irreversible';
+import {
+  classifyCommand as coreClassifyCommand,
+  isMutatingCommand as coreIsMutatingCommand,
+  riskOf as coreRiskOf,
+  type CommandRisk,
+  type RiskRule,
+  type SafetyRules,
+} from 'pi-helper-core';
 
-const RISK_ORDER: Record<CommandRisk, number> = { read: 0, mutating: 1, irreversible: 2 };
-
-interface RiskPattern {
-  risk: Exclude<CommandRisk, 'read'>;
-  pattern: RegExp;
-  reason: string;
-}
+export { splitCommandSegments } from 'pi-helper-core';
+export type { CommandClassification, CommandRisk } from 'pi-helper-core';
 
 /**
- * Safe overrides are matched before risk patterns so a read-only flag does not
- * inherit the risk of the command it qualifies (`uv lock --check`, `-e .`).
+ * Safe overrides are matched before risk patterns so a read-only form does not
+ * inherit the risk of the command it qualifies. Only the Python-specific
+ * read-only forms live here; `--check`, `--dry-run`, and `--collect-only` are
+ * already universal overrides in the core.
  */
-const SAFE_OVERRIDES: RegExp[] = [
-  /\buv\s+lock\b[^&|;]*--check\b/,
-  /\buv\s+sync\b[^&|;]*--dry-run\b/,
+const PYTHON_SAFE_OVERRIDES: RegExp[] = [
   /\buv\s+(?:tree|export|version|help)\b/,
   /\buv\s+pip\s+(?:list|freeze|check)\b/,
-  /\bpytest\b[^&|;]*--collect-only\b/,
   /\bruff\s+(?:check|format)\b[^&|;]*(?:--diff|--check|--no-cache)\b/,
   /\bmypy\b[^&|;]*--no-incremental\b/,
-  /\bgit\s+(?:diff|log|status|show|rev-parse|ls-files|branch\s+--show-current)\b/,
 ];
 
-const RISK_PATTERNS: RiskPattern[] = [
+const PYTHON_RISK_PATTERNS: RiskRule[] = [
   // Irreversible: cannot be undone by a local revert.
   {
     risk: 'irreversible',
     pattern: /\b(?:uv|poetry|flit|hatch)\s+publish\b|\btwine\s+upload\b/,
     reason: 'Publishing to a package index is public and cannot be retracted.',
   },
-  {
-    risk: 'irreversible',
-    pattern: /\bgit\s+push\b[^&|;]*(?:--force(?:-with-lease)?|-f\b)/,
-    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: /\b(?:conda|mamba)\s+env\s+remove\b|\bconda\s+remove\b[^&|;]*--all\b/,
     reason: 'Removing an environment destroys installed state.',
   },
-  {
-    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: /\b(?:alembic|manage\.py)\b[^&|;]*(?:downgrade|\bzero\b)/,
     reason: 'Reversing a database migration can drop data.',
   },
-  {
-    risk: 'irreversible',
-    pattern: /\bdocker\s+(?:system|volume|image)\s+(?:prune|rm)\b/,
-    reason: 'Docker prune removes volumes or images outside the project.',
-  },
 
   // Mutating: changes project, environment, or remote state but is recoverable.
   {
@@ -104,78 +83,27 @@ const RISK_PATTERNS: RiskPattern[] = [
     pattern: /\bpre-commit\s+(?:install|autoupdate|run|clean)\b/,
     reason: 'Rewrites hook configuration or working tree files.',
   },
-  {
-    risk: 'mutating',
-    pattern: /\bgit\s+(?:commit|add|checkout|switch|restore|stash|merge|rebase|push|tag)\b/,
-    reason: 'Changes repository or remote state.',
-  },
-  {
-    risk: 'mutating',
-    pattern: /\b(?:rm|mv|chmod|chown|truncate)\b/,
-    reason: 'Changes files on disk.',
-  },
 ];
 
-/** 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 classifySegment(segment: string): { risk: CommandRisk; reason?: string } {
-  if (SAFE_OVERRIDES.some((pattern) => pattern.test(segment))) return { risk: 'read' };
-  for (const entry of RISK_PATTERNS) {
-    if (entry.pattern.test(segment)) return { risk: entry.risk, reason: entry.reason };
-  }
-  return { risk: 'read' };
-}
-
-export interface CommandClassification {
-  risk: CommandRisk;
-  reasons: { segment: string; risk: CommandRisk; reason: string }[];
-}
-
-/** `curl ... | sh` cannot be seen after segment splitting, so it is matched first. */
-const PIPE_TO_SHELL = /\b(?:curl|wget)\b[^;&\n]*\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b/;
+const PYTHON_RULES: Partial<SafetyRules> = {
+  safeOverrides: PYTHON_SAFE_OVERRIDES,
+  patterns: PYTHON_RISK_PATTERNS,
+};
 
 /**
  * Classify a shell command by the highest risk of its segments. Used to warn
  * before a tool runs something that cannot be undone, and to gate this
  * package's own environment-modifying commands behind explicit opt-in.
  */
-export function classifyCommand(command: string): CommandClassification {
-  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);
-    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 classifyCommand(command: string): import('pi-helper-core').CommandClassification {
+  return coreClassifyCommand(command, PYTHON_RULES);
 }
 
 export function isMutatingCommand(command: string): boolean {
-  return classifyCommand(command).risk !== 'read';
+  return coreIsMutatingCommand(command, PYTHON_RULES);
 }
 
 /** Commands that this package runs itself always carry a known risk class. */
 export function riskOf(args: string[]): CommandRisk {
-  return classifyCommand(args.join(' ')).risk;
+  return coreRiskOf(args, PYTHON_RULES);
 }

package/src/validation/bundle.ts

@@ -1,17 +1,16 @@
-export interface ValidationStep {
-  /** Step label, used for the quality checks (`ruff`, `pyright`). */
-  name?: string;
-  executed: boolean;
-  ok: boolean;
-  exitCode?: number | null;
-  failures?: number;
-  /**
-   * Why a step was not executed. A step that was skipped deliberately (the
-   * environment is missing the tool it needs) must say so, otherwise the run
-   * looks like an unexplained test failure.
-   */
-  skippedReason?: string;
-}
+/**
+ * Python's view of the shared validation-bundle gate.
+ *
+ * `pi-helper-core` owns the lock → preparation → test → quality → conformance
+ * sequence; this module names the Python steps (`uv lock --check`, `uv sync`)
+ * and preserves the local `sync` field name in the returned `checks` map.
+ */
+import {
+  summarizeValidation as coreSummarizeValidation,
+  type ValidationStep,
+} from 'pi-helper-core';
+
+export type { ValidationStep };
 
 export interface ValidationSummary {
   ok: boolean;
@@ -21,32 +20,12 @@ export interface ValidationSummary {
     sync: boolean;
     test: boolean;
     conformance: boolean;
-    /**
-     * True when every configured quality command passed. Vacuously true when the
-     * project declares none, so a project without lint/type tooling is not
-     * penalised.
-     */
     quality: boolean;
     staleArtifacts: boolean;
   };
 }
 
-const PREVIEW_REASON = 'Set execute=true to run the validation bundle.';
-
-/**
- * The bundle runs `uv lock --check`, then `uv sync --frozen`, then pytest, then
- * verifies that the resulting environment actually matches the lockfile and that
- * no stale coverage report is being quoted.
- *
- * Conformance must be proven, not merely not-failed: a test run that passed
- * against versions the lockfile does not describe is not evidence, so an
- * `unverifiable` verdict fails the gate exactly like drift does.
- *
- * A test step that was never executed is also not evidence, and when the reason
- * is known (the environment no longer provides pytest) that reason is reported
- * instead of a generic failure.
- */
-export function summarizeValidation(input: {
+export interface ValidationInput {
   lock: ValidationStep;
   sync: ValidationStep;
   test: ValidationStep;
@@ -56,47 +35,33 @@ export function summarizeValidation(input: {
   stale: boolean;
   /** True when nothing was executed because the caller only asked for a preview. */
   preview?: boolean;
-}): ValidationSummary {
-  const lock = input.lock.executed && input.lock.ok;
-  const sync = input.sync.executed && input.sync.ok;
-  const test = input.test.executed && input.test.ok && (input.test.failures ?? 0) === 0;
-  const qualitySteps = input.quality ?? [];
-  const quality = qualitySteps.every((step) => step.executed && step.ok);
-  const failedQuality = qualitySteps.filter((step) => !step.executed || !step.ok);
-  const conformance = input.conformance === 'consistent';
-  const staleArtifacts = input.stale;
+}
 
-  let reason = 'Lockfile, environment, tests, and installed versions all agree.';
-  if (input.preview) {
-    reason = PREVIEW_REASON;
-  } else if (!input.lock.executed || !input.sync.executed) {
-    reason = !input.lock.executed
-      ? 'uv lock --check was not executed, so lockfile agreement is unproven.'
-      : 'uv sync was not executed, so the environment the tests ran in is unknown.';
-  } else if (!lock) {
-    reason = 'uv.lock is out of date; run uv lock before trusting any test result.';
-  } else if (!sync) {
-    reason = 'The environment could not be synchronised from the lockfile.';
-  } else if (!input.test.executed) {
-    reason =
-      input.test.skippedReason ?? 'Tests were not executed, so no test result exists to report.';
-  } else if (!test) {
-    reason = 'Tests failed; inspect the first failing case and its project frame.';
-  } else if (input.conformance === 'drifted') {
-    reason =
-      'Tests passed, but the installed versions do not match uv.lock, so the run does not describe the locked environment.';
-  } else if (input.conformance === 'unverifiable') {
-    reason =
-      'The installed environment could not be compared with uv.lock, so the passing test run is not proven to be on the locked versions.';
-  } else if (failedQuality.length > 0) {
-    const names = failedQuality.map((step) => step.name ?? 'quality check').join(', ');
-    reason = `Tests passed, but the declared quality check(s) failed: ${names}.`;
-  } else if (staleArtifacts) {
-    reason = 'Tests passed, but a stale coverage report was detected; refresh it and rerun.';
-  }
+export function summarizeValidation(input: ValidationInput): ValidationSummary {
+  const summary = coreSummarizeValidation({
+    lock: input.lock,
+    preparation: input.sync,
+    test: input.test,
+    quality: input.quality,
+    conformance: input.conformance,
+    stale: input.stale,
+    preview: input.preview,
+    labels: {
+      lock: 'uv lock --check',
+      preparation: 'uv sync',
+      stale: 'a stale coverage report',
+    },
+  });
   return {
-    ok: lock && sync && test && conformance && quality && !staleArtifacts,
-    reason,
-    checks: { lock, sync, test, conformance, quality, staleArtifacts },
+    ok: summary.ok,
+    reason: summary.reason,
+    checks: {
+      lock: summary.checks.lock,
+      sync: summary.checks.preparation,
+      test: summary.checks.test,
+      conformance: summary.checks.conformance,
+      quality: summary.checks.quality,
+      staleArtifacts: summary.checks.staleArtifacts,
+    },
   };
 }

package/src/validation/evidence.ts

@@ -1,3 +1,15 @@
+/**
+ * Python's view of the shared completion-evidence gate.
+ *
+ * The gate itself lives in `pi-helper-core`; this module maps the Python
+ * wording ("environment sync") onto the core's preparation stage so call sites
+ * keep their existing input shape.
+ */
+import {
+  buildCompletionEvidence as coreBuildCompletionEvidence,
+  type CompletionEvidence,
+} from 'pi-helper-core';
+
 export interface CompletionEvidenceInput {
   syncExecuted: boolean;
   syncOk: boolean;
@@ -7,27 +19,19 @@ export interface CompletionEvidenceInput {
   changedPaths: string[];
 }
 
-export interface CompletionEvidence {
-  ok: boolean;
-  blockers: string[];
-  changedPaths: string[];
-}
+export type { CompletionEvidence };
 
-/**
- * Completion is only proven when the environment was synchronised and the tests
- * actually ran. Declaring completion on a partial run is treated as a blocker,
- * never as a warning.
- */
 export function buildCompletionEvidence(input: CompletionEvidenceInput): CompletionEvidence {
-  const blockers: string[] = [];
-  if (!input.syncExecuted)
-    blockers.push('The environment sync (uv sync/lock check) was not executed.');
-  else if (!input.syncOk) blockers.push('The environment sync did not pass.');
-  if (!input.testExecuted) blockers.push('Tests were not executed.');
-  else if (!input.testOk) blockers.push('Tests did not pass.');
-  if (input.stale)
-    blockers.push(
-      'Stale artifacts were detected, so the test result does not describe the current sources.',
-    );
-  return { ok: blockers.length === 0, blockers, changedPaths: input.changedPaths };
+  return coreBuildCompletionEvidence({
+    preparation: {
+      name: 'sync',
+      label: 'environment sync (uv sync/lock check)',
+      executed: input.syncExecuted,
+      ok: input.syncOk,
+    },
+    testExecuted: input.testExecuted,
+    testOk: input.testOk,
+    stale: input.stale,
+    changedPaths: input.changedPaths,
+  });
 }