Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
76 lines (54 loc) · 3.49 KB

CONTRIBUTING.md

File metadata and controls

76 lines (54 loc) · 3.49 KB

Contributing to podcli

Thank you for helping improve podcli. This project is AGPL-3.0 — contributions are welcome under the same license.

Architecture

podcli ships as a native Go launcher (cli/) that provisions hermetic runtimes and routes commands to the Python backend (backend/) and the Node studio/MCP server (src/). End users install a prebuilt binary; the source trees below are for development.

Development setup

Backend (Python) + studio (TypeScript):

./setup.sh        # venv + Python deps
npm install
npm run build     # tsc + studio bundle

Native launcher (Go 1.23+):

cd cli
go generate ./... # sync backend + PodStack commands for go:embed
go build -o podcli .

cli/internal/backend/files/ is generated by go generate (gitignored) — edit the canonical backend/ instead.

Project layout

Path Purpose
cli/ Go launcher — provisioning, self-update, command routing
backend/ Python engine (transcription, rendering, clip generation)
src/ TypeScript MCP server + Web UI
.podcli/ Config home (knowledge, presets, assets, settings) — gitignored
data/ Runtime data (cache, output, working) — gitignored
backend/config/paths.py Canonical path resolution (Python)
src/config/paths.ts Path resolution for Node (must stay aligned)
backend/config_bundle.py Portable profile export/import
backend/services/transcript_packer.py Transcript cache keys + packed markdown

Before you open a PR

  1. Python tests: python3 -m pytest tests/ -q
  2. TypeScript: npm run build and npx vitest run
  3. Go (if you touched cli/): cd cli && go build ./... && go test ./... && gofmt -l .
  4. If you change paths, env vars, or cache layout, update README.md and the config migration logic, and keep backend/config/paths.py and src/config/paths.ts aligned.
  5. Keep diffs focused — one feature or fix per PR when possible.

Path and cache conventions

  • Config home (PODCLI_HOME or .podcli-home marker): portable settings only.
  • Data dir (PODCLI_DATA or data/): transcripts cache, outputs, temp files.
  • Transcript cache: data/cache/transcripts/{16-char-hash}.json — same hash algorithm in Python (compute_cache_hash) and TypeScript (TranscriptCache).

Do not reintroduce a separate CLI-only cache path without updating both sides.

Adding an integration

  1. Create backend/services/integrations/<name>/ with IntegrationBase subclass.
  2. Register in that package’s __init__.py.
  3. Add MCP tool wiring in src/server.ts (or a thin handler) and optional UI toggle at /integrations.html.

Security

  • Config import uses zip path validation (_safe_extract_zip). Do not replace with raw extractall on untrusted archives.
  • Do not commit .env, API keys, or personal media under .podcli/ or data/.

Questions

Open a GitHub issue with reproduction steps for bugs, or a short design note for larger features.