🐛 Critical Bugs Found in PostKit v1.0.4

Environment

• PostKit Version: 1.0.4
• Node.js: v24.13.0
• PostgreSQL: 16-alpine (Docker)
• Testing Date: 2026年04月03日
• Installation Method: npm install @appritech/postkit

🔴 Critical Bug #1: Corrupted State Files During Init

Severity: Critical
Impact: Blocks entire workflow

Description

When postkit init is run, it creates corrupted/empty state files that cause internal errors.

Expected Behavior

postkit init should create properly initialized state files with valid JSON structure.

Actual Behavior

Creates empty or malformed JSON files:

• .postkit/db/committed.json contains {} instead of {"migrations":[]}
• .postkit/db/session.json is completely empty
• .postkit/db/plan.sql and schema.sql are empty

Error Message

TypeError: Cannot read properties of undefined (reading 'filter')
File: node_modules/@appritech/postkit/dist/index.js
Line: ~1316 in getPendingCommittedMigrations()

Root Cause

The code expects state.migrations to exist, but when the file contains {}, state.migrations is undefined.

Workaround

Manually fix the corrupted file:

echo '{"migrations":[]}' > .postkit/db/committed.json

🔴 Critical Bug #2: Missing PostgreSQL Client Dependency

Severity: Critical
Impact: Cannot use core db commands

Description

PostKit requires pg_dump and pg_restore but doesn't check for their presence or document them as dependencies.

Expected Behavior

Either:

1. Document PostgreSQL client tools as required dependencies
2. Provide helpful error message with installation instructions
3. Include them as bundled dependencies

Actual Behavior

Failed to start migration session
Error: Failed to clone database: spawn pg_dump ENOENT

Missing Tools

• pg_dump (for database cloning)
• pg_restore (for database restoration)
• psql (likely needed for other operations)

Workaround

Install PostgreSQL client tools:

# Ubuntu/Debian
sudo apt-get install postgresql-client
# macOS
brew install postgresql
# Or use Docker aliases
alias pg_dump='docker exec postkit-test-db pg_dump'

🟠 Medium Bug #3: Incomplete Directory Structure

Severity: Medium
Impact: Commands fail or show confusing warnings

Description

postkit init doesn't create all required directories, causing confusing error messages.

Expected Behavior

Create all required directories during initialization.

Actual Behavior

Missing directories:

• schema/infra/ (required for db infra command)
• schema/grants/ (required for db grants command)
• schema/seeds/ (required for db seed command)

Error Messages

⚠ No infra files found
info Infra files should be placed in:
info - db/schema/infra/

Workaround

Manually create missing directories:

mkdir -p schema/infra schema/grants schema/seeds

🟡 Minor Bug #4: Path Resolution Issues

Severity: Minor
Impact: Installation usability

Description

Global npm installation fails due to permissions, requiring local installation workaround.

Error

EACCES: permission denied, mkdir '/usr/lib/node_modules/@appritech'

Workaround

# Local install workaround
npm install @appritech/postkit
node node_modules/@appritech/postkit/dist/index.js [command]
# Or create wrapper script
echo '#!/bin/bash
cd /path/to/project
node node_modules/@appritech/postkit/dist/index.js "$@"' > postkit.sh
chmod +x postkit.sh
./postkit.sh [command]

📊 Testing Results Summary

What Works ✅

• npm local installation
• postkit init (with manual fixes)
• postkit db remote add/list
• postkit db infra/grants/seed help and basic commands
• Database connection testing

What Doesn't Work ❌

• postkit db start (blocked by bugs Introduce command to populate a part of the stack #1 and Feature/db tool #2 )
• postkit db plan/apply/commit (require active session)
• postkit db migration (requires active session)
• postkit db deploy (requires committed migrations)
• Any end-to-end workflow

🎯 Recommended Fixes

Priority 1 (Critical)

1. Fix getCommittedState() to always return {migrations: []} structure
2. Add dependency check for pg_dump, pg_restore, psql
3. Document PostgreSQL client tools as required dependencies

Priority 2 (Important)

1. Create all required directories during postkit init
2. Improve installation process for global npm install
3. Add comprehensive health check command

Priority 3 (Nice to Have)

1. Better error messages with actionable solutions
2. Automatic dependency checking and suggestions
3. Recovery commands for corrupted state files

🧪 Testing Environment Setup

# Database Setup
docker run -d \
 --name postkit-test-db \
 -e POSTGRES_USER=postkit \
 -e POSTGRES_PASSWORD=postkit123 \
 -e POSTGRES_DB=postkit_test \
 -p 5432:5432 \
 postgres:16-alpine
# PostKit Setup
npm install @appritech/postkit
node node_modules/@appritech/postkit/dist/index.js init --force
node node_modules/@appritech/postkit/dist/index.js db remote add local "postgres://postkit:postkit123@localhost:5432/postkit_test"
# Manual fixes required
echo '{"migrations":[]}' > .postkit/db/committed.json
mkdir -p schema/infra schema/grants schema/seeds

📝 Additional Notes

• Documentation Gap: No mention of PostgreSQL client tool requirements
• Error Recovery: No documented recovery from corrupted state files
• Production Readiness: Currently NOT production-ready due to critical bugs
• Testing Coverage: Core workflow completely untestable without manual fixes

Overall Assessment: PostKit shows promise but requires immediate attention to these critical bugs before it can be recommended for production use.

Tested by: Claude Code Agent
Testing Duration: ~4 hours
Bugs Found: 4 (2 critical, 1 medium, 1 minor)
Production Ready: ❌ NO