Skip to content

Design — pinky-tools

Update date : 2026-05-31 12:10

Local dev CLI that covers the developer loop: run a stored procedure locally, generate the README from AST, compare outputs, and validate naming. Complements pinky-provider (which deploys) by handling everything before a deploy.

Vision

The CLI is the glue between the local dev environment and Snowflake — no GUI, no vendor portal, just pinky <command> from the project root.

All four commands are production-tested in a prior enterprise workspace and are being migrated clean (no enterprise-specific logic) to this repo.

Existing modules (migrated from legacy)

pinky run — local SP runner

Executes a Snowpark .py file directly against a real Snowflake connection (via connections.toml). The dev iterates locally without deploying to a stage first.

pinky readme — README generation via AST

  • lib_ast_parser.py extracts from Snowpark files: TableRead, TableWrite, FileWrite, FileRead, TelemetryEvent (dataclasses, AST walk, line numbers)
  • Optional live enrichment from Snowflake INFORMATION_SCHEMA
  • Smart merge: re-generates auto sections, preserves MANUAL sections
  • mdformat post-processing for consistent Markdown rendering

pinky regression — output comparator

Side-by-side diff between two output files (CSV / TXT / XLSX), cell-level delta. --sheet ALL for multi-tab XLSX. Used after a SP refactor to confirm output is identical.

pinky validate-name — naming convention validator

Pure Python, no Snowflake connection. Validates the schema/repo name format and derives: schema_name, dag_name, tags. Used by pinky-provider plan/apply and pinkysight.

Phase 0 — tooling (before code features)

Three items to implement before adding any command:

  1. PreToolUse hook — cross-domain isolation Blocks edits that mix deployment files (manifest.yml, resources/**/*.yml) and Snowpark files (resources/procedure/*.py) in the same session without explicit confirmation.

  2. /fewer-permission-prompts — generate a .claude/settings.json allowlist for repetitive safe bash commands.

  3. /careful + /freeze skills — on-demand safety guards.