Skip to content

Bun/TypeScript reimplementation of Katana#73

Closed
JGillam wants to merge 19 commits intomainfrom
feature/bun-implementation
Closed

Bun/TypeScript reimplementation of Katana#73
JGillam wants to merge 19 commits intomainfrom
feature/bun-implementation

Conversation

@JGillam
Copy link
Copy Markdown
Member

@JGillam JGillam commented Dec 30, 2025

Summary

Complete reimplementation of Katana in Bun/TypeScript as a self-contained binary:

  • Single binary deployment - No Python or dependencies required on target systems
  • Module fetching from GitHub - Downloads module definitions at runtime
  • REST API server - Hono-based web server for remote management
  • Lock mode - Restrict operations to specific modules (acts as basic auth)
  • GitHub Actions release workflow - Automated Linux binary builds on tagged releases

Key Features

  • CLI commands: init, list, start, stop, status, serve
  • Plugin architecture with Docker and mock execution modes
  • Dependency resolution between modules
  • State persistence with --statedir option
  • TLS support for server mode

Test Coverage

  • 265 tests covering CLI, server, core logic, and plugins
  • All tests pass

Commits

  • Add GitHub Actions workflow for release builds
  • Strengthen server lock mode as auth mechanism
  • Add self-sufficient binary with module fetching from GitHub
  • Complete Phase 5: Web Server & REST API
  • Complete Phase 4: Dependency resolution and status checking
  • Complete Phase 3: Plugin architecture with mock mode support
  • Complete Phase 2: Config system, init command, list lock mode
  • Add StateManager for state persistence
  • Add CLI commands using Commander.js
  • Add module loader and Zod schemas
  • Initialize Bun/TypeScript project structure

Test plan

  • Review code changes
  • Tag a release (git tag v0.1.0 && git push origin v0.1.0) to test the GitHub Actions workflow
  • Verify binary runs on clean Linux system without Bun installed
  • Test katana init, katana list, katana serve commands

🤖 Generated with Claude Code

JGillam and others added 19 commits December 26, 2025 16:51
@JGillam @claude
Add Katana Bun/TypeScript reimplementation requirements
565c810 
- Comprehensive requirements document for modern Katana rewrite
- SSE-based real-time progress updates to solve timeout issues
- Flexible domain configuration (mydomain.internal support)
- React + shadcn UI + TailwindCSS for modern interface
- Compiled binary distribution via GitHub Actions
- YAML-based state management (backward compatible)
- Ubuntu 24.04 LTS as primary target platform

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@JGillam @claude
Change default TLS port from 8443 to 443
ca65f10 
- Use standard HTTPS port (443) instead of 8443
- Simplifies URLs: https://dvwa.wtf instead of https://dvwa.wtf:8443
- More intuitive for users and follows web standards
- tls_port remains configurable in config.yml

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@JGillam @claude
Enhance lock mode and add EC2 deployment guidance
7a46d99 
Lock Mode Enhancements:
- Document exact behavior: students can start/stop but not install/remove
- Enhanced lock file format with metadata and instructor message
- Bulk install support for provisioning scripts
- Class configuration file support
- Unlock protection (requires root or unlock code)

EC2 Deployment Section:
- Pre-configured student instance workflow
- Headless environment adaptations (skip desktop integration)
- AWS-specific features (Route53, CloudWatch, EC2 metadata)
- Security group requirements
- Resource sizing guidelines by lab count
- Multi-region deployment patterns

Use case: One EC2 instance per student with multiple pre-installed
labs, locked environment for classroom management.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@JGillam @claude
Add .CLAUDE_LAST_SESSION.md to .gitignore
73657a6 
Exclude Claude Code session summary file from version control.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@JGillam @claude
Add Bun/TypeScript implementation plan
22b18cb 
Create detailed phased implementation plan for reimplementing Katana in
Bun/TypeScript. The plan includes 6 phases covering project setup, configuration,
plugin architecture, dependency resolution, web server/API, and UI.

Key decisions documented:
- bun/ folder coexists with Python implementation during development
- Zod for YAML validation with katana validate command
- Mock plugin support for development without Docker/systemd
- Shared modules/ directory between implementations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Initialize Bun/TypeScript project structure (Phase 1.1)
9a87da8 
- Set up Bun project with TypeScript strict mode
- Configure dependencies: hono, yaml, zod, commander, pino
- Add Biome v2 for linting/formatting
- Create directory structure per implementation plan:
  - src/cli/commands/, src/core/, src/plugins/
  - src/server/routes/, src/types/, src/utils/
  - tests/unit/, tests/integration/, tests/fixtures/
- Add CLI entry point stub (src/cli.ts)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add Zod schemas and fix module YAML validation issues (Phase 1.2)
7d40e8a 
- Create Zod schemas in bun/src/types/:
  - status.ts: ModuleStatus enum
  - plugin.ts: IPlugin interface and BasePlugin class
  - events.ts: SSE event types for streaming
  - config.ts: Configuration schema with defaults
  - state.ts: installed.yml and lock file schemas
  - module.ts: Full module YAML schema (11 task types)
  - index.ts: Barrel export

- Fix module YAML files:
  - juice-shop.yml: Move installed: under status: (was at top-level)
  - Convert numeric mode values to strings in 10 files (18 occurrences)
    to avoid YAML octal parsing issues

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add module loader and missing task types (Phase 1.3)
9601446 
- Create ModuleLoader class with singleton pattern, caching, category filtering
- Add loadAll(), loadByName(), loadFromFile(), validateFile() methods
- Add human-readable error formatting utilities
- Add unarchive and desktop task types to schema
- Create 24 unit tests for module loader functionality
- All 25 module YAML files now load and validate successfully

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add CLI commands using Commander.js (Phase 1.4)
90cb0bf 
Implements three functional commands:
- list [category]: List modules with optional category filter
- validate <file>: Validate YAML module files with error details
- status <module>: Show module info (status check stubbed)

Also adds stub commands for future phases: init, install, remove,
start, stop, lock, unlock, update.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add CLI command tests (Phase 1.5)
79a5f8d 
Integration tests for all CLI commands using Bun subprocess spawning:
- list: all modules, category filtering, partial failure warning
- validate: valid/invalid files, YAML errors, schema errors
- status: module lookup, case-insensitive names, not found
- stub commands: verify "not implemented" messages
- help/version: verify usage info and version number

22 new tests (46 total across both test files)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add StateManager for state persistence (Phase 2)
96aea0b 
- Create StateManager class with singleton pattern
- Implement installed.yml tracking (install/remove modules)
- Implement katana.lock management (enable/disable lock mode)
- Support legacy lock file format (newline-separated)
- Add atomic writes (temp file + rename) for safety
- Update CLI commands: status, lock, unlock now functional
- Add 37 unit tests for StateManager
- Update CLI tests (86 total tests pass)

State files stored in ~/.local/share/katana/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Complete Phase 2: Config system, init command, list lock mode
dd47708 
- Add ConfigManager singleton for loading config from multiple paths
- Implement init command with interactive and non-interactive modes
- Update list command to respect lock mode (show only installed modules)
- Add 26 new tests (ConfigManager, init, list lock mode)
- Total: 112 tests passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Complete Phase 3: Plugin architecture with mock mode support
3d29947 
- Add MockState singleton for in-memory state during testing
- Add PluginRegistry for dynamic plugin discovery and registration
- Add TaskExecutor with EventEmitter for progress events
- Implement 13 plugins: docker, service, lineinfile, reverseproxy,
  file, copy, git, command, rm, get-url, unarchive, replace, desktop
- Wire install/remove/start/stop CLI commands to TaskExecutor
- Add --dry-run option for testing without making changes
- Add Operation type to ExecutionContext for section context
- Add 88 new tests (200 total tests pass)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Complete Phase 4: Dependency resolution and status checking
e8507c1 
- Add `depends-on` field to ModuleSchema for declaring dependencies
- Create DependencyResolver class with:
  - Dependency graph building
  - Circular dependency detection (DFS with 3-color marking)
  - Topological sort for installation order (Kahn's algorithm)
  - Reverse dependency lookup (getDependents)
- Create StatusChecker class with:
  - Real status checks via plugin exists()/started() methods
  - Result caching with configurable TTL (default 5 seconds)
  - Batch checking for multiple modules in parallel
  - Status format: "installed, running" / "installed, stopped" / "not installed"
- Wire up CLI commands:
  - `install` resolves and installs dependencies first (fail-fast)
  - `remove` warns if other modules depend on target
  - `status` shows real status via plugins
  - `list --status` shows real-time status column
- Add 43 new tests (28 for dependencies, 15 for status)
- Total: 243 tests passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Complete Phase 5: Web Server & REST API
4c2d6b5 
Implement HTTP server with REST endpoints and SSE streaming for module
management operations.

Server Components:
- Bun.serve() with native routing (no Express/Hono per project standards)
- OperationManager singleton for async operation tracking
- SSE streaming with heartbeat for real-time progress
- Pino logging with pretty format support
- CORS middleware for development

REST API Endpoints:
- GET /health - Health check
- GET /api/modules - List modules with category filter
- GET /api/modules/:name - Module details
- GET /api/modules/:name/status - Module status
- POST /api/modules/:name/{install,remove,start,stop} - Operations
- GET /api/operations/:id - Operation status
- GET /api/operations/:id/stream - SSE progress stream
- GET /api/config - Configuration
- GET/POST/DELETE /api/lock - Lock management

CLI:
- Add 'serve' command with --port, --host, --cors options

Tests:
- 21 new server tests covering all endpoints
- All 264 tests passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add self-sufficient binary with module fetching from GitHub
caa5723 
- Implement `katana update` command to fetch/update modules from GitHub
- Add runtime path resolution using Bun.main instead of compile-time import.meta.dir
- Support configurable git branch (--branch option) for dev/testing
- Use sparse checkout + shallow clone for efficient module fetching
- Add modulesRepo and modulesBranch config options
- Enhance `init` command with module fetch option
- Add helpful error handling when modules not found
- Update build output to bin/katana
- Add .claude/ to gitignore for Claude Code artifacts

Path resolution priority:
1. Config file modulesPath (if set and exists)
2. KATANA_HOME/modules environment variable
3. ~/.local/share/katana/modules (default user location)
4. ../modules relative to binary (git clone scenario)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Strengthen server lock mode as auth mechanism
b7e4118 
- Add lock check to getModule endpoint (404 for non-locked modules)
- Add lock check to getModuleStatus endpoint (404 for non-locked modules)
- Restrict start/stop operations to locked modules only when locked
- Add isModuleAccessibleWhenLocked helper to reduce duplication
- Clean up cli.ts: remove dead stubAction code, consolidate imports
- Update state-manager.ts comments to remove phase references
- Fix tests to use modules that load successfully (ffuf, trufflehog)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add GitHub Actions workflow for release builds
e97b087 
Creates Linux binary on tagged releases (v*) using Bun's compile feature.
Runs tests before building and uploads binary as release asset.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam @claude
Add certificate management and systemd service support
25e727d 
Certificate Management:
- New `katana cert init` command generates root CA + wildcard cert
- New `katana cert install-ca` installs root CA to system trust store
- New `katana cert status` shows certificate status
- Certs stored in <statePath>/certs/ with cert-state.yml tracking

Domain-Aware Reverse Proxy:
- Hostname transformation: juice-shop.wtf -> juice-shop.<domainBase>
- Uses wildcard cert from statePath instead of hardcoded paths
- HTTP->HTTPS redirect (port 80 -> 443)
- Automatic nginx reload after config changes

Server TLS Support:
- New `--tls` flag for `katana serve` uses wildcard cert
- Server shows https:// URL when TLS enabled

Systemd Service:
- New `katana service install` creates and enables systemd service
- New `katana service uninstall` removes service
- New `katana service status` shows service status
- Auto-restart on failure, security hardening

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JGillam JGillam closed this Jan 21, 2026
@JGillam JGillam deleted the feature/bun-implementation branch January 22, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@JGillam