pi-python-helper 0.1.0

package/src/build/staleness.ts

@@ -0,0 +1,117 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface StaleArtifact {
+  code: 'STALE_COVERAGE_DATA';
+  message: string;
+  path: string;
+  artifactMtimeMs?: number;
+  newestSource?: { path: string; mtimeMs: number };
+}
+
+export interface PythonStalenessReport {
+  stale: boolean;
+  artifacts: StaleArtifact[];
+  /** Populated when the check could not be completed, so `stale: false` is not overclaimed. */
+  incompleteReason?: string;
+}
+
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.venv',
+  'venv',
+  '.tox',
+  '.nox',
+  '__pycache__',
+  '.mypy_cache',
+  '.ruff_cache',
+  '.pytest_cache',
+  'node_modules',
+  'build',
+  'dist',
+  '.eggs',
+]);
+
+const MAX_WALKED_FILES = 5000;
+
+async function mtimeMs(path: string): Promise<number | undefined> {
+  try {
+    return (await stat(path)).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+async function newestPythonSource(
+  root: string,
+): Promise<{ path: string; mtimeMs: number } | undefined> {
+  let newest: { path: string; mtimeMs: number } | undefined;
+  let visited = 0;
+  const stack = [root];
+  while (stack.length > 0) {
+    const directory = stack.pop() as string;
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (visited > MAX_WALKED_FILES) return newest;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+        stack.push(path);
+      } else if (entry.isFile() && entry.name.endsWith('.py')) {
+        visited += 1;
+        const modified = await mtimeMs(path);
+        if (modified === undefined) continue;
+        if (!newest || modified > newest.mtimeMs) newest = { path, mtimeMs: modified };
+      }
+    }
+  }
+  return newest;
+}
+
+/**
+ * Detect a coverage report that predates the sources it claims to describe.
+ *
+ * Python invalidates bytecode automatically and pytest installs nothing, so a
+ * stale report is the one artifact that can make a passing run describe the
+ * wrong code. Whether the project itself is installed as a stale copy is a
+ * structural question and is answered by the environment conformance check
+ * rather than by comparing mtimes here.
+ */
+export async function detectStaleArtifacts(root: string): Promise<PythonStalenessReport> {
+  const artifacts: StaleArtifact[] = [];
+  let newestSource: { path: string; mtimeMs: number } | undefined;
+  try {
+    newestSource = await newestPythonSource(root);
+  } catch (error) {
+    return {
+      stale: false,
+      artifacts,
+      incompleteReason: `Source scan failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (!newestSource) {
+    return { stale: false, artifacts, incompleteReason: 'No Python source files were found.' };
+  }
+
+  for (const name of ['.coverage', 'coverage.xml']) {
+    const path = join(root, name);
+    const modified = await mtimeMs(path);
+    if (modified === undefined) continue;
+    if (modified < newestSource.mtimeMs) {
+      artifacts.push({
+        code: 'STALE_COVERAGE_DATA',
+        message: `${name} was written before ${newestSource.path} changed; coverage results do not describe the current sources.`,
+        path,
+        artifactMtimeMs: modified,
+        newestSource,
+      });
+    }
+  }
+
+  return { stale: artifacts.length > 0, artifacts };
+}

package/src/core/result.ts

@@ -0,0 +1,102 @@
+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.
+ */
+export interface PyToolResult<T = unknown> {
+  ok: boolean;
+  summary: string;
+  data?: T;
+  evidence: Evidence[];
+  warnings: Diagnostic[];
+  errors: Diagnostic[];
+  suggestions: Suggestion[];
+  commands?: CommandPreview[];
+  metadata: ToolMetadata;
+}
+
+export function result<T>(
+  cwd: string,
+  startedAt: number,
+  value: Omit<PyToolResult<T>, 'metadata'> & {
+    truncated?: boolean;
+    projectRoot?: string;
+    pythonVersion?: string;
+  },
+): PyToolResult<T> {
+  return {
+    ...value,
+    metadata: {
+      toolVersion: TOOL_VERSION,
+      cwd,
+      durationMs: Date.now() - startedAt,
+      truncated: value.truncated ?? false,
+      projectRoot: value.projectRoot,
+      pythonVersion: value.pythonVersion,
+    },
+  };
+}
+
+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,
+  });
+}
+
+/** 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 };
+}

package/src/core/runner.ts

@@ -0,0 +1,96 @@
+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.
+ */
+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');
+  }
+}

package/src/core/safety.ts

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+export type CommandRisk = 'read' | 'mutating' | 'irreversible';
+
+const RISK_ORDER: Record<CommandRisk, number> = { read: 0, mutating: 1, irreversible: 2 };
+
+interface RiskPattern {
+  risk: Exclude<CommandRisk, 'read'>;
+  pattern: RegExp;
+  reason: string;
+}
+
+/**
+ * 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 .`).
+ */
+const SAFE_OVERRIDES: RegExp[] = [
+  /\buv\s+lock\b[^&|;]*--check\b/,
+  /\buv\s+sync\b[^&|;]*--dry-run\b/,
+  /\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[] = [
+  // 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.
+  {
+    risk: 'mutating',
+    pattern: /\b(?:uv|pdm|poetry)\s+(?:add|remove|sync|lock|update|venv)\b/,
+    reason: 'Modifies the environment or the lockfile.',
+  },
+  {
+    risk: 'mutating',
+    pattern: /\buv\s+pip\s+(?:install|uninstall|sync)\b/,
+    reason: 'Changes installed packages in the active environment.',
+  },
+  {
+    risk: 'mutating',
+    pattern: /\b(?:pip|pip3)\s+(?:install|uninstall)\b/,
+    reason: 'Changes installed packages in the active environment.',
+  },
+  {
+    risk: 'mutating',
+    pattern: /\b(?:conda|mamba)\s+(?:install|create|update|remove)\b/,
+    reason: 'Changes conda environment state.',
+  },
+  {
+    risk: 'mutating',
+    pattern: /\b(?:alembic|manage\.py)\b[^&|;]*\b(?:upgrade|migrate|makemigrations)\b/,
+    reason: 'Applies a schema change to a database.',
+  },
+  {
+    risk: 'mutating',
+    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/;
+
+/**
+ * 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 isMutatingCommand(command: string): boolean {
+  return classifyCommand(command).risk !== 'read';
+}
+
+/** Commands that this package runs itself always carry a known risk class. */
+export function riskOf(args: string[]): CommandRisk {
+  return classifyCommand(args.join(' ')).risk;
+}

package/src/core/version.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Report the version of the installed package so tool metadata does not drift
+ * from `package.json` across releases.
+ */
+function readPackageVersion(): string {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+    ) as { version?: unknown };
+    return typeof manifest.version === 'string' && manifest.version.length > 0
+      ? manifest.version
+      : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export const TOOL_VERSION = readPackageVersion();