@punks/cli 1.0.1 → 1.0.3

package/dist/skills/languages/python/python-testing-patterns/references/advanced-patterns.md

@@ -0,0 +1,411 @@
+# Python Testing Patterns — Advanced Reference
+
+Advanced testing patterns including async code, monkeypatching, temporary files, conftest setup, property-based testing, database testing, CI/CD integration, and configuration.
+
+## Pattern 6: Testing Async Code
+
+```python
+# test_async.py
+import pytest
+import asyncio
+
+async def fetch_data(url: str) -> dict:
+    """Fetch data asynchronously."""
+    await asyncio.sleep(0.1)
+    return {"url": url, "data": "result"}
+
+
+@pytest.mark.asyncio
+async def test_fetch_data():
+    """Test async function."""
+    result = await fetch_data("https://api.example.com")
+    assert result["url"] == "https://api.example.com"
+    assert "data" in result
+
+
+@pytest.mark.asyncio
+async def test_concurrent_fetches():
+    """Test concurrent async operations."""
+    urls = ["url1", "url2", "url3"]
+    tasks = [fetch_data(url) for url in urls]
+    results = await asyncio.gather(*tasks)
+
+    assert len(results) == 3
+    assert all("data" in r for r in results)
+
+
+@pytest.fixture
+async def async_client():
+    """Async fixture."""
+    client = {"connected": True}
+    yield client
+    client["connected"] = False
+
+
+@pytest.mark.asyncio
+async def test_with_async_fixture(async_client):
+    """Test using async fixture."""
+    assert async_client["connected"] is True
+```
+
+## Pattern 7: Monkeypatch for Testing
+
+```python
+# test_environment.py
+import os
+import pytest
+
+def get_database_url() -> str:
+    """Get database URL from environment."""
+    return os.environ.get("DATABASE_URL", "sqlite:///:memory:")
+
+
+def test_database_url_default():
+    """Test default database URL."""
+    # Will use actual environment variable if set
+    url = get_database_url()
+    assert url
+
+
+def test_database_url_custom(monkeypatch):
+    """Test custom database URL with monkeypatch."""
+    monkeypatch.setenv("DATABASE_URL", "postgresql://localhost/test")
+    assert get_database_url() == "postgresql://localhost/test"
+
+
+def test_database_url_not_set(monkeypatch):
+    """Test when env var is not set."""
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    assert get_database_url() == "sqlite:///:memory:"
+
+
+class Config:
+    """Configuration class."""
+
+    def __init__(self):
+        self.api_key = "production-key"
+
+    def get_api_key(self):
+        return self.api_key
+
+
+def test_monkeypatch_attribute(monkeypatch):
+    """Test monkeypatching object attributes."""
+    config = Config()
+    monkeypatch.setattr(config, "api_key", "test-key")
+    assert config.get_api_key() == "test-key"
+```
+
+## Pattern 8: Temporary Files and Directories
+
+```python
+# test_file_operations.py
+import pytest
+from pathlib import Path
+
+def save_data(filepath: Path, data: str):
+    """Save data to file."""
+    filepath.write_text(data)
+
+
+def load_data(filepath: Path) -> str:
+    """Load data from file."""
+    return filepath.read_text()
+
+
+def test_file_operations(tmp_path):
+    """Test file operations with temporary directory."""
+    # tmp_path is a pathlib.Path object
+    test_file = tmp_path / "test_data.txt"
+
+    # Save data
+    save_data(test_file, "Hello, World!")
+
+    # Verify file exists
+    assert test_file.exists()
+
+    # Load and verify data
+    data = load_data(test_file)
+    assert data == "Hello, World!"
+
+
+def test_multiple_files(tmp_path):
+    """Test with multiple temporary files."""
+    files = {
+        "file1.txt": "Content 1",
+        "file2.txt": "Content 2",
+        "file3.txt": "Content 3"
+    }
+
+    for filename, content in files.items():
+        filepath = tmp_path / filename
+        save_data(filepath, content)
+
+    # Verify all files created
+    assert len(list(tmp_path.iterdir())) == 3
+
+    # Verify contents
+    for filename, expected_content in files.items():
+        filepath = tmp_path / filename
+        assert load_data(filepath) == expected_content
+```
+
+## Pattern 9: Custom Fixtures and Conftest
+
+```python
+# conftest.py
+"""Shared fixtures for all tests."""
+import pytest
+
+@pytest.fixture(scope="session")
+def database_url():
+    """Provide database URL for all tests."""
+    return "postgresql://localhost/test_db"
+
+
+@pytest.fixture(autouse=True)
+def reset_database(database_url):
+    """Auto-use fixture that runs before each test."""
+    # Setup: Clear database
+    print(f"Clearing database: {database_url}")
+    yield
+    # Teardown: Clean up
+    print("Test completed")
+
+
+@pytest.fixture
+def sample_user():
+    """Provide sample user data."""
+    return {
+        "id": 1,
+        "name": "Test User",
+        "email": "test@example.com"
+    }
+
+
+@pytest.fixture
+def sample_users():
+    """Provide list of sample users."""
+    return [
+        {"id": 1, "name": "User 1"},
+        {"id": 2, "name": "User 2"},
+        {"id": 3, "name": "User 3"},
+    ]
+
+
+# Parametrized fixture
+@pytest.fixture(params=["sqlite", "postgresql", "mysql"])
+def db_backend(request):
+    """Fixture that runs tests with different database backends."""
+    return request.param
+
+
+def test_with_db_backend(db_backend):
+    """This test will run 3 times with different backends."""
+    print(f"Testing with {db_backend}")
+    assert db_backend in ["sqlite", "postgresql", "mysql"]
+```
+
+## Pattern 10: Property-Based Testing
+
+```python
+# test_properties.py
+from hypothesis import given, strategies as st
+import pytest
+
+def reverse_string(s: str) -> str:
+    """Reverse a string."""
+    return s[::-1]
+
+
+@given(st.text())
+def test_reverse_twice_is_original(s):
+    """Property: reversing twice returns original."""
+    assert reverse_string(reverse_string(s)) == s
+
+
+@given(st.text())
+def test_reverse_length(s):
+    """Property: reversed string has same length."""
+    assert len(reverse_string(s)) == len(s)
+
+
+@given(st.integers(), st.integers())
+def test_addition_commutative(a, b):
+    """Property: addition is commutative."""
+    assert a + b == b + a
+
+
+@given(st.lists(st.integers()))
+def test_sorted_list_properties(lst):
+    """Property: sorted list is ordered."""
+    sorted_lst = sorted(lst)
+
+    # Same length
+    assert len(sorted_lst) == len(lst)
+
+    # All elements present
+    assert set(sorted_lst) == set(lst)
+
+    # Is ordered
+    for i in range(len(sorted_lst) - 1):
+        assert sorted_lst[i] <= sorted_lst[i + 1]
+```
+
+## Testing Database Code
+
+```python
+# test_database_models.py
+import pytest
+from sqlalchemy import create_engine, Column, Integer, String
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker, Session
+
+Base = declarative_base()
+
+
+class User(Base):
+    """User model."""
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(50))
+    email = Column(String(100), unique=True)
+
+
+@pytest.fixture(scope="function")
+def db_session() -> Session:
+    """Create in-memory database for testing."""
+    engine = create_engine("sqlite:///:memory:")
+    Base.metadata.create_all(engine)
+
+    SessionLocal = sessionmaker(bind=engine)
+    session = SessionLocal()
+
+    yield session
+
+    session.close()
+
+
+def test_create_user(db_session):
+    """Test creating a user."""
+    user = User(name="Test User", email="test@example.com")
+    db_session.add(user)
+    db_session.commit()
+
+    assert user.id is not None
+    assert user.name == "Test User"
+
+
+def test_query_user(db_session):
+    """Test querying users."""
+    user1 = User(name="User 1", email="user1@example.com")
+    user2 = User(name="User 2", email="user2@example.com")
+
+    db_session.add_all([user1, user2])
+    db_session.commit()
+
+    users = db_session.query(User).all()
+    assert len(users) == 2
+
+
+def test_unique_email_constraint(db_session):
+    """Test unique email constraint."""
+    from sqlalchemy.exc import IntegrityError
+
+    user1 = User(name="User 1", email="same@example.com")
+    user2 = User(name="User 2", email="same@example.com")
+
+    db_session.add(user1)
+    db_session.commit()
+
+    db_session.add(user2)
+
+    with pytest.raises(IntegrityError):
+        db_session.commit()
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/test.yml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+          pip install pytest pytest-cov
+
+      - name: Run tests
+        run: |
+          pytest --cov=myapp --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+```
+
+## Configuration Files
+
+```ini
+# pytest.ini
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    -v
+    --strict-markers
+    --tb=short
+    --cov=myapp
+    --cov-report=term-missing
+markers =
+    slow: marks tests as slow
+    integration: marks integration tests
+    unit: marks unit tests
+    e2e: marks end-to-end tests
+```
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = [
+    "-v",
+    "--cov=myapp",
+    "--cov-report=term-missing",
+]
+
+[tool.coverage.run]
+source = ["myapp"]
+omit = ["*/tests/*", "*/migrations/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+]
+```

package/dist/skills/languages/typescript/quality-types/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: quality-types
+description: Use when writing or reviewing TypeScript/full-stack code. Encodes principles for type safety (branded types, discriminated unions, end-to-end types), real tests over mocks, OpenTelemetry observability, and picking the right abstractions instead of premature ones.
+---
+
+# Writing quality full-stack TypeScript
+
+Apply these principles when writing or reviewing TypeScript code.
+
+## Make impossible states unrepresentable
+
+Use the type system to make invalid states fail at compile time. Fewer reachable states = easier code to read and change.
+
+### Branded types
+
+Brand primitives so they can't be mixed up. Validate once at the boundary; downstream code trusts the type.
+
+```ts
+type PhoneNumber = string & { __brand: "PhoneNumber" };
+
+function parsePhone(input: string): PhoneNumber {
+  if (!/^\+?\d{10,15}$/.test(input)) throw new Error(`Invalid: ${input}`);
+  return input as PhoneNumber;
+}
+
+function sendSMS(to: PhoneNumber, body: string) {
+  /* input is trusted */
+}
+```
+
+If the project already uses a library with native branded-type support (e.g. Effect), use their primitives instead of rolling your own.
+
+### Discriminated unions over flag bags
+
+```ts
+// Don't — invalid combos representable
+type State = { loading: boolean; user?: User; error?: string };
+
+// Do — only valid states exist
+type State =
+  | { status: "loading" }
+  | { status: "success"; user: User }
+  | { status: "error"; error: string };
+```
+
+## Let the types flow end-to-end
+
+DB schema → server → client should share types without manual duplication. Use whatever end-to-end type tool the project already has (tRPC, oRPC, Elysia, TanStack Start). A `users.email` branded as `Email` should arrive on the client still branded.
+
+Don't restate types you can derive. Reach for `Pick`, `Omit`, `Parameters`, `ReturnType`, `Awaited`, `typeof` etc. before writing a new interface. For function arguments, infer from the source instead of typing them by hand:
+
+```ts
+// Don't — duplicate shape, drifts when the row changes
+type UserSummary = { id: string; email: Email };
+function renderUser(u: UserSummary) {
+  /* ... */
+}
+
+// Do — derive from the source of truth
+type User = Awaited<ReturnType<typeof db.query.users.findFirst>>;
+function renderUser(u: Pick<User, "id" | "email">) {
+  /* ... */
+}
+```
+
+## Pass objects, not positional args
+
+```ts
+// Don't — swap two args, still compiles
+sendEmail("Welcome!", "Hi there");
+// Do — order-independent, self-documenting
+sendEmail({ to: "alice@x.com", body: "Hi there" });
+```
+
+Skip on hot perf-critical paths; use elsewhere by default.
+
+## Standard Schema for shared validation
+
+For libraries or code that doesn't want to pick a validator, accept `StandardSchemaV1<unknown, T>`.
+
+## Tests as real as possible
+
+Don't mock things you can run. Spin up real services:
+
+- LocalStack for AWS
+- Miniflare for Cloudflare Workers
+- Real Postgres/SQLite (e.g. `bun:sqlite`), not a mock DB
+
+Mock only third-party services that have no test environment.
+
+## OpenTelemetry, not print logging
+
+When adding observability, instrument with OTel spans. The setup cost pays back the first time a user sends a request ID and you can answer instead of guess.

package/docs/README.md

@@ -5,16 +5,26 @@
 
 Implementation notes:
 
-- canonical scaffold metadata and shared assets live in `src/data/`
+- canonical bundled scaffold metadata and shared assets live in `src/data/`
+- runtime scaffold content resolves from a `Baseline`: latest remote stable by default, bundled fallback when offline or forced with `--baseline bundled`
 - pack-owned lint asset metadata lives in `src/data/catalog/lint.ts`
 - distributed skill assets live in `skills/`
 - runtime projection/writing logic lives in `src/scaffold/`
 - `punks update` refreshes scaffold-managed assets from `.devpunks/scaffold-manifest.json`
+- CLI startup checks npm's `latest` dist-tag for `@punks/cli` and prints a self-update notice when the installed CLI is behind. Set `DP_NO_UPDATE_CHECK=1` to skip the check or `DP_UPDATE_TAG=next` to compare against another dist-tag.
+- CLI startup also checks for the `dp-cli` skill through the `skills` CLI, installing it globally when absent and updating it when present. Set `DP_NO_SKILL_UPDATE_CHECK=1` to skip this best-effort pass.
+- baseline releases use `baseline/stable/*` GitHub release tags, separate from npm executable tags such as `v1.0.1`
 - shared neutral hook and sync assets live in `src/data/hooks/` and `src/data/scripts/`
-- scaffolded required tools always include `portless` so generated guidance can standardize local dev origins and avoid worktree port collisions
+- scaffolded required tools always include `portless` and `skills` so generated guidance can standardize local dev origins and keep skill entrypoints up to date
+- `punks scaffold setup` checks the base required tools (`portless`, `skills`) before repo detection and checks selected-pack tools after pack confirmation.
+- Oxlint specs/starter config are scaffolded only when scanned manifests already declare `oxlint`; the auto format/lint hook is scaffolded only when manifests declare `oxfmt`. Other lint/format stacks are intentionally left untouched for now.
+- the default debug pack scaffolds the local `debug-agent` skill and installs/verifies the `debug-agent` CLI without running its agent-install wizard
 - scaffolded repos keep project-local skills in `.agents/skills/`; only `.claude/skills` is a compatibility symlink mirror
 - React scaffold surfaces include `async-react-patterns` alongside the existing React composition, structure, and Vercel guidance so agents avoid outdated manual async state patterns.
 - Next.js detection implies the React pack even when `react` / `react-dom` are not directly listed in scanned manifests.
 - Frontend surface detection scaffolds `frontend-domain-structure` with the frontend pack when React or Next.js is detected.
-- Backend surface detection scaffolds `backend-domain-structure` and `backend-recoverable-actions` when backend framework/data/auth packages are detected, or when workspace names/paths clearly identify API, backend, server, or service packages.
-- Non-surface agnostic skill groups are mandatory scaffold packs (`docs`, `planning`, `quality`, `research`, `requirements`, `subagents`); `frontend` and `backend` remain detection-driven.
+- Backend surface detection scaffolds `backend-domain-structure`, `backend-recoverable-actions`, and `logging-best-practices` when backend framework/data/auth packages are detected, or when workspace names/paths clearly identify API, backend, server, or service packages. Workspace prompt specs apply backend packs only to backend-looking workspaces, not frontend workspaces that happen to share repo-level backend/data detections.
+- Drizzle detection selects the `drizzle` pack for data-layer prompt/lint metadata, but does not imply Effect skills or Effect opensrc references unless `effect` / `@effect/*` is also detected.
+- Scaffold no longer preselects concrete opensrc repositories. Post-scaffold agents must choose and clone the core detected libraries whose source behavior matters before authoring final prompts or plans.
+- The default subagent manifest includes a read-only `code-review` template that uses `simplify` and `improve-codebase-architecture`; root prompt guidance routes review requests to findings-first review before broad refactor planning.
+- Non-surface agnostic skill groups are mandatory scaffold packs (`debug`, `docs`, `planning`, `quality`, `research`, `requirements`, `subagents`); `frontend` and `backend` remain detection-driven.

package/docs/reference/dp-requirements.md

@@ -67,7 +67,7 @@ That wiki tree is not the same thing as `docs/`. It owns specs, raw inputs, and
 It should:
 
 - detect repo facts, not ask the agent to invent them
-- resolve those facts to predefined DevPunks packs
+- resolve those facts to predefined Devpunks packs
 - scaffold the shared AI setup
 - emit instructions/specs the next agent can use to generate repo-scoped prompts and subagent config
 
@@ -106,6 +106,8 @@ Initial technology mapping:
 - `turbo` -> `turborepo`
 - `effect`, `@effect/*` -> `effect`
 
+`drizzle` is data-layer detection only. It must not imply Effect skills or Effect source references unless the `effect` pack is selected independently.
+
 ## Pack Contract
 
 Pack resolution happens at pack level only during `punks scaffold setup`.
@@ -147,6 +149,11 @@ Framework/data packs may layer on top of that surface:
 - `tanstack-query`
   `tanstack-query`
 
+Backend-oriented agnostic skills should be grouped into a single detected backend surface pack:
+
+- `backend`
+  `backend-domain-structure`, `backend-recoverable-actions`, `logging-best-practices`
+
 ## Prompt Contract
 
 Pre-boilerplate commands use fixed stdout operator prompts.
@@ -188,6 +195,10 @@ Current examples:
 
 The scaffold output should also record the resolved tool requirements in a machine-readable manifest.
 
+`punks scaffold setup` should check base required tools before repo detection so missing `skills` or `portless` is surfaced immediately. Tools required only by selected packs can be checked after pack confirmation.
+
+Scaffold output should not preselect concrete opensrc repositories. The generated post-scaffold instructions should require the next agent to identify the core detected libraries whose source behavior matters, ask the user when that set is ambiguous, and run `opensrc path <package>` or `opensrc path owner/repo` for only that focused set.
+
 ## Lint Scaffold Contract
 
 The shipped starter/root lint baseline should exclude generated and non-source surfaces by default, including:
@@ -196,6 +207,10 @@ The shipped starter/root lint baseline should exclude generated and non-source s
 - all dot-directories
 - generated agent/harness folders unless a target repo explicitly opts them back into lint scope
 
+When scaffold guidance leads an agent to adopt Oxlint or Oxfmt, it must tell the agent to replace existing lint/format entrypoints deliberately: package scripts, task pipelines, CI, editor/docs references, and agent hooks should agree on the new tools.
+
+Until additional lint/format stacks are supported, repo-aware setup should emit Oxlint specs/starter config only when `oxlint` is declared in scanned package manifests and emit the Oxfmt/Oxlint format hook only when `oxfmt` is declared. Repos without those packages should get no lint/format scaffold surfaces.
+
 ## Dedicated CLI Repo Contract
 
 The standalone private `wearedevpunks/cli` repo remains the source of truth for: