pi-python-helper 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "pi-python-helper",
+  "version": "0.1.0",
+  "description": "Python (uv) development tools for the pi coding agent",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "python",
+    "uv",
+    "pytest"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wkqco33/pi-python-helper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wkqco33/pi-python-helper/issues"
+  },
+  "homepage": "https://github.com/wkqco33/pi-python-helper#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "helpers",
+    "skills",
+    "docs/compatibility.md",
+    "docs/tools.md",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:coverage": "tsx --test --experimental-test-coverage test/*.test.ts",
+    "test:e2e": "tsx test/manual/e2e-uv.ts",
+    "docs": "tsx scripts/generate-api-surface.ts && tsx scripts/generate-tools-doc.ts",
+    "docs:check": "tsx scripts/check-docs.ts",
+    "format": "prettier --write \"extensions/**/*.ts\" \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.ts\"",
+    "format:check": "prettier --check \"extensions/**/*.ts\" \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.ts\"",
+    "pack-check": "npm pack --dry-run",
+    "check": "npm test && npm run typecheck && npm run format:check && npm run docs:check && npm run pack-check"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "prettier": "^3.9.8",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}

package/skills/python-development/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: python-development
+description: pi-python-helper를 활용한 uv 기반 Python 개발 워크플로. 인터프리터/가상환경 점검, pyproject.toml 및 uv.lock 분석, 의존성 드리프트 탐지, pytest 테스트 선별/실행, traceback 및 uv 실패 진단, 완료 게이트 검증 시 사용합니다.
+license: Apache-2.0
+---
+
+# pi-python-helper를 활용한 uv 기반 Python 개발 워크플로
+
+원시 쉘 명령어(`grep`, `python -c`, `pytest`)를 직접 실행하기 전에 Python 전용 도구를 우선 사용하세요.
+
+## 조사 및 작업 순서 (Investigation order)
+
+1. 인터프리터나 가상환경 상태가 불확실할 때는 `py_environment`를 실행하세요. 잘못된 Python으로 테스트를 실행하는 것이 가장 흔한 실패 원인입니다.
+2. `pyproject.toml`이나 `uv.lock`을 편집하기 전에 `py_project_inspect`로 레이아웃(src/flat), 의존성 그룹, lockfile 드리프트, **환경 정합성**(선언 ↔ lock ↔ 실제 설치본)을 확인하세요. 정합성은 `consistent` / `drifted` / `unverifiable` 중 하나이며, `unverifiable`을 일치로 해석하지 마세요.
+3. 의존성을 추가/이동하기 전에 `py_dependency_plan`을 사용하세요. `ast`로 실제 import를 스캔하여 다음을 구분합니다:
+   - 선언되지 않은 import (런타임 오류로 이어짐)
+   - `[project] dependencies`가 아니라 dev 그룹/extra에만 선언된 런타임 import
+   - `uv.lock`에 없거나 스펙을 만족하지 않는 버전
+4. import 이름과 배포 이름은 다를 수 있습니다(`PIL`/`pillow`, `yaml`/`PyYAML`). `py_dependency_plan`의 제안을 `uv add`로 적용하세요.
+5. 소스 코드를 수정한 후에는 `py_test_select`로 변경 파일과 연관된 테스트를 선별하세요. 매칭이 실패하면 전체 스위트가 범위가 되며, 선택 이유가 함께 반환됩니다.
+6. 테스트 실행은 `py_test`를 사용하세요. `execute=false`로 먼저 미리보기하고, 실제 실행 시에만 `execute=true`를 전달합니다.
+7. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다.
+8. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요.
+9. 재현이 어려운 실패는 `py_test`의 `lastFailed=true`(`--lf`)로 직전 실패만 다시 실행하세요.
+10. 작업 완료를 보고하기 전에 `py_validation_bundle`(lock 검사 → sync → pytest → 환경 정합성 → 오래된 아티팩트 검사)을 실행하고, `py_completion_evidence`로 근거가 충분한지 확인하세요. 정합성이 `drifted`나 `unverifiable`이면 테스트가 통과했어도 게이트는 실패합니다.
+11. `py_tdd_checkpoint`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
+
+## 안전 규칙 (Safety)
+
+- `py_sync`와 `py_validation_bundle`은 `execute: true`가 명시적으로 전달되기 전까지 명령을 실행하지 않고 미리보기만 반환합니다. `execute=true`는 `.venv`를 생성/갱신하므로 사용자 확인 없이 반복 실행하지 마세요.
+- Python에는 ROS의 `cmd_vel`처럼 위험을 결정론적으로 알려주는 이름이 없습니다. 다음은 되돌릴 수 없는 작업으로 취급하세요: `uv publish`/`twine upload`(공개 불가 회수), `git push --force`, `git reset --hard`/`git clean -fd`, `alembic downgrade`, `DROP`/`DELETE`(WHERE 없는), `rm -rf`, `conda env remove`.
+- 가상환경을 파괴하는 명령(`rm -rf .venv`, `uv venv --clear`)이나 전역 Python에 패키지를 설치하는 명령(`pip install` without a venv)을 임의로 실행하지 마세요.
+- 도구는 파일을 쓰지 않습니다. `pyproject.toml`/`uv.lock` 수정은 항상 명시적인 편집 도구로 수행하세요.
+
+## 해석 규칙 (Interpretation rules)
+
+- `PROJECT_INSTALLED_NOT_EDITABLE`는 프로젝트가 환경에 live link가 아니라 복사본으로 설치되어, 소스 변경이 테스트에 반영되지 않음을 의미합니다. `uv sync`로 해결하세요.
+- `PROJECT_NOT_INSTALLED`는 lock이 editable 설치를 기대하는데 `.venv`에 프로젝트가 없다는 뜻입니다. `uv sync`를 실행하고, 그래도 실패하면 빌드 백엔드가 패키지를 찾지 못한 것입니다(`[project] name`과 모듈 디렉터리 이름이 일치하는지 확인).
+- `INSTALLED_VERSION_MISMATCH`는 `uv add`/`uv lock` 후 `uv sync`를 잊은 상태입니다. `uv lock --check`는 이걸 잡지 못하니(락은 최신) 테스트를 신뢰하기 전에 `uv sync --frozen`을 실행하세요.
+- `INSTALLED_PACKAGE_UNTRACKED`는 `.venv`에만 있고 lock에 없는 패키지입니다. 에이전트가 `uv pip install`로 임의 설치했을 가능성을 의심하세요.
+- `CONDITIONAL_PACKAGES_ABSENT`는 정상입니다. `sys_platform == 'win32'`나 `python_version < '3.11'` 같은 마커 때문에 해당 플랫폼에 설치되지 않은 항목이며, 드리프트로 취급하지 마세요.
+- `STALE_COVERAGE_DATA`는 커버리지 결과가 현재 소스보다 오래되었음을 의미합니다. 커버리지 수치를 근거로 사용하지 마세요.
+- `RUNTIME_DEPENDENCY_IN_DEV_GROUP`은 프로덕션 코드가 dev 그룹 의존성을 import한다는 뜻이며, 배포 시 `ModuleNotFoundError`로 이어집니다.
+- `LOCKFILE_DRIFT`가 있으면 `uv lock` 전에는 어떤 테스트 결과도 신뢰하지 마세요.
+- `TYPE_CHECKING` 블록 안의 import는 런타임 의존성이 아니므로 dev 그룹 선언이 정상입니다.

package/src/build/commands.ts

@@ -0,0 +1,65 @@
+import type { CommandPreview } from '../core/result.ts';
+
+/**
+ * uv invocations are built as argument arrays rather than shell strings so user
+ * supplied paths can never be interpreted by a shell. `--frozen` is used
+ * everywhere a lockfile exists: it forbids implicit re-resolution so a test run
+ * cannot silently rewrite uv.lock.
+ */
+export function uvLockCheck(cwd: string, frozen = true): CommandPreview {
+  return {
+    executable: 'uv',
+    args: frozen ? ['lock', '--check', '--offline'] : ['lock', '--check'],
+    cwd,
+    risk: 'read',
+  };
+}
+
+export function uvLock(cwd: string): CommandPreview {
+  return { executable: 'uv', args: ['lock'], cwd, risk: 'mutating' };
+}
+
+export function uvSyncFrozen(cwd: string): CommandPreview {
+  return { executable: 'uv', args: ['sync', '--frozen', '--all-groups'], cwd, risk: 'mutating' };
+}
+
+export function uvRun(cwd: string, args: string[]): CommandPreview {
+  return { executable: 'uv', args: ['run', '--frozen', ...args], cwd, risk: 'read' };
+}
+
+export interface PytestOptions {
+  targets?: string[];
+  lastFailed?: boolean;
+  keyword?: string;
+  extraArgs?: string[];
+  maxFail?: number;
+}
+
+export const PYTEST_BASE_ARGS = ['-q', '--tb=short', '-rf', '--no-header'];
+
+/**
+ * pytest always runs through `uv run --frozen` so the project environment is
+ * used even when the shell was never activated.
+ */
+export function pytestCommand(cwd: string, options: PytestOptions = {}): CommandPreview {
+  const args = [...PYTEST_BASE_ARGS];
+  if (options.lastFailed) args.push('--lf');
+  if (options.keyword) args.push('-k', options.keyword);
+  if (options.maxFail !== undefined) args.push('--maxfail', String(options.maxFail));
+  args.push(...(options.extraArgs ?? []));
+  args.push(...(options.targets ?? []));
+  return uvRun(cwd, ['pytest', ...args]);
+}
+
+export function gitDiffNames(cwd: string, args: string[] = ['--name-only']): CommandPreview {
+  return { executable: 'git', args: ['diff', ...args, 'HEAD'], cwd, risk: 'read' };
+}
+
+export function gitStatusPorcelain(cwd: string): CommandPreview {
+  return {
+    executable: 'git',
+    args: ['status', '--porcelain', '--untracked-files=all'],
+    cwd,
+    risk: 'read',
+  };
+}

package/src/build/discover.ts

@@ -0,0 +1,98 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runCommand } from '../core/runner.ts';
+import { gitDiffNames, gitStatusPorcelain } from './commands.ts';
+
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.venv',
+  'venv',
+  '.tox',
+  '.nox',
+  '__pycache__',
+  '.mypy_cache',
+  '.ruff_cache',
+  '.pytest_cache',
+  'node_modules',
+  'build',
+  'dist',
+  '.eggs',
+  'site-packages',
+]);
+
+const MAX_WALKED_FILES = 5000;
+
+/** Walk the project for Python files, skipping environments and caches. */
+export async function listPythonFiles(root: string): Promise<string[]> {
+  const files: string[] = [];
+  const stack = [root];
+  while (stack.length > 0 && files.length < MAX_WALKED_FILES) {
+    const directory = stack.pop() as string;
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (files.length >= MAX_WALKED_FILES) break;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name) || entry.name.endsWith('.egg-info')) continue;
+        stack.push(path);
+      } else if (entry.isFile() && entry.name.endsWith('.py')) {
+        files.push(
+          path
+            .slice(root.length)
+            .replace(/^[/\\]/, '')
+            .replace(/\\/g, '/'),
+        );
+      }
+    }
+  }
+  return files.sort();
+}
+
+export async function listTestFiles(root: string): Promise<string[]> {
+  const { isTestFile } = await import('../project/paths.ts');
+  return (await listPythonFiles(root)).filter(isTestFile);
+}
+
+export interface ChangedPathsResult {
+  paths: string[];
+  source: 'git' | 'none';
+  error?: string;
+}
+
+/**
+ * Collect changed paths from git, including untracked files so a brand new test
+ * file is considered. Falls back to an empty list outside a repository.
+ */
+export async function changedPaths(cwd: string, signal?: AbortSignal): Promise<ChangedPathsResult> {
+  const diff = await runCommand('git', gitDiffNames(cwd).args, {
+    cwd,
+    signal,
+    timeoutMs: 10000,
+    maxBytes: 200_000,
+  });
+  if (diff.code !== 0) {
+    return { paths: [], source: 'none', error: diff.stderr.trim() || 'git diff failed' };
+  }
+  const status = await runCommand('git', gitStatusPorcelain(cwd).args, {
+    cwd,
+    signal,
+    timeoutMs: 10000,
+    maxBytes: 200_000,
+  });
+  const untracked =
+    status.code === 0
+      ? status.stdout
+          .split(/\r?\n/)
+          .filter((line) => line.startsWith('??'))
+          .map((line) => line.slice(3).trim())
+      : [];
+  const paths = [...diff.stdout.split(/\r?\n/), ...untracked]
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return { paths: [...new Set(paths)], source: 'git' };
+}