Local Development Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• AGENTS.md
• CONTRIBUTING.md
• package.json
• README.md

The local development workflow for the putio-cli project is designed for high-velocity iteration using TypeScript and the Effect ecosystem. It focuses on maintaining a deterministic automation-first CLI while providing readable output for human developers. The project utilizes vite-plus (vp) as the primary task runner and development orchestrator to manage builds, tests, and repository guardrails.

Sources: README.md:1-10, CLAUDE.md:7-12, CONTRIBUTING.md:1-5

Environment Setup

Development requires Node.js version 24.14+ and pnpm as the package manager. The environment is initialized by installing dependencies and configuring local hooks.

Initial Initialization Steps

1. Install Dependencies: Use vp install (or pnpm install) to fetch required packages.
2. Hook Wiring: Execute vp config to install the stock VitePlus hook wiring for the local clone.

Sources: package.json:65-68, CONTRIBUTING.md:7-16

Development Lifecycle

The workflow categorizes commands into primary development loops, focused checks, and runtime proofs.

Continuous Development

For active coding, a local build watcher is used to provide immediate feedback on changes.

• Command: vp run dev (equivalent to vp pack --watch).
• Scope: Watches src/* for changes and rebuilds the distribution.

Sources: CONTRIBUTING.md:18-21, package.json:52

Build and Verification

The build process transforms TypeScript source into a standalone package.

• Standard Build: vp run build executes vp pack to generate the ./dist directory.
• Single Executable Application (SEA): Specialized builds exist for creating standalone binaries via node ./scripts/build-sea.mts.
• Verification: The "repository delivery gate" is the verify command, which combines type checking, smoke testing, and coverage analysis.

Sources: CONTRIBUTING.md:23-28, package.json:54-61

Workflow Diagram

The following diagram illustrates the standard progression from source code to a verified binary.

Primary Development Commands

The following table summarizes the key commands used during the local development lifecycle.

Task	Command	Description
Install	vp install	Installs project dependencies using pnpm.
Watch	vp run dev	Starts the local build watcher for rapid iteration.
Check	vp run check	Runs TypeScript type checks across the project.
Test	vp run test	Executes the test suite using VitePlus/Vitest.
Coverage	vp run coverage	Runs tests and generates a code coverage report.
Verify	vp run verify	The primary gate: runs check, smoke tests, and coverage.
Build SEA	vp run build:sea	Builds a Node.js Single Executable Application.

Sources: CLAUDE.md:22-30, package.json:48-61, CONTRIBUTING.md:30-33

Testing and Quality Assurance

The project enforces a "test-first" or "test-alongside" philosophy. Development guidance suggests preferring in-process tests unless testing a process boundary.

Testing Strategy

• Unit/Integration Tests: Standard tests are run with vp run test.
• Command-Path Coverage: Specific focus is placed on command-path coverage when the @effect/cli boundary is modified.
• Smoke Testing: vp run smoke:pack validates that the packed installation functions correctly in a clean environment.
• Runtime Proofs: Developers are encouraged to prove changes by running the built binary directly:
  • ./dist/bin.mjs describe
  • ./dist/bin.mjs whoami --fields auth --output json

Sources: CLAUDE.md:32-44, CONTRIBUTING.md:25-30, AGENTS.md:38-42

Coding Standards and Architecture

When working locally, developers must adhere to specific architectural patterns:

• Effect-Native: Move shared behavior into internal Effect-native helpers and services rather than keeping logic in command modules.
• Output Strategy: JSON output is treated as the machine contract, while terminal output is a separate adapter layer.
• Documentation: Updates to flags, command behavior, or architectural boundaries must be reflected in README.md and skills/putio-cli/SKILL.md simultaneously.

Sources: CLAUDE.md:37-43, AGENTS.md:32-37

Summary

The local development workflow for putio-cli is a structured process managed by vite-plus that ensures consistency between development, testing, and distribution. By utilizing vp run verify as a comprehensive quality gate and emphasizing Effect-native services, the workflow maintains the high standards required for an agent-first CLI.

Sources: CONTRIBUTING.md:46-50, CLAUDE.md:1-5