The command-line tool for creating and managing DBBasic apps: thin scripts over git, cp and sed.

0 downloads

dbbasic-cli-new/CLAUDE.md
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-cli-new.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-cli-new.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-cli-new.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 Prepare for PyPI publication 57213b9 1 year, 1 month ago History
CLAUDE.md · 9.8 KB · 337 lines

DBBasic CLI Project Context

Project Overview

dbbasic-cli is a command-line tool for creating and managing DBBasic applications. It follows the Unix philosophy: tools not frameworks, scripts not magic.

Philosophy

The design follows these principles:

  1. Optional - Can use dbbasic without the CLI (just use git, cp, python)
  2. Simple - Core CLI is ~200 lines
  3. Thin wrapper - Just automates Unix commands (git clone, cp, etc.)
  4. Extensible - Modules can add commands (like Django's manage.py)
  5. No Magic - Everything is visible and debuggable

Architecture

Core Components

  • dbbasic_cli/cli.py - Main CLI implementation (~200 lines)
  • Core commands: new, list, run, test
  • Module command discovery via discover_commands()
  • Uses pkg_resources to find installed dbbasic-* packages
  • dbbasic_cli/__init__.py - Package initialization
  • setup.py - Standard setuptools configuration
  • Entry point: dbbasic=dbbasic_cli.cli:main
  • No dependencies (pure Python)

Command Discovery Mechanism

The CLI automatically discovers commands from installed dbbasic modules:

# Any dbbasic module can provide commands by creating cli.py:
# dbbasic_queue/cli.py

def worker_command(args):
    """Run the queue worker"""
    # implementation here

COMMANDS = {
    'queue:worker': worker_command,
    'queue:stats': stats_command,
}

The discover_commands() function:

  1. Iterates through all installed packages using pkg_resources.working_set
  2. Finds packages starting with dbbasic-
  3. Converts package names to module names (dbbasic-queue → dbbasic_queue)
  4. Imports {module_name}.cli and looks for COMMANDS dict
  5. Merges all discovered commands into a single registry

Module CLI Extensions

dbbasic-queue CLI Commands

Located at: /Users/danq/dbbasic-queue/dbbasic_queue/cli.py

Commands:

  • queue:worker - Run the queue worker (looks for HANDLERS in app.py)
  • queue:stats - Show queue statistics (pending, processing, completed, failed, cancelled)
  • queue:failed - List all failed jobs with details
  • queue:retry <job_id> - Reset a failed job to pending
  • queue:clear - Remove completed/failed jobs, keep only pending/processing

dbbasic-logs CLI Commands

Located at: /Users/danq/dbbasic-logs/dbbasic_logs/cli.py

Commands:

  • logs:tail - Tail application logs (supports --type, -n)
  • logs:search <pattern> - Search logs with grep (supports --type, --days)
  • logs:compress - Compress logs older than N days (default 7)
  • logs:stats - Show log file statistics (size, count by type)

Directory Structure

dbbasic-cli-new/
├── dbbasic_cli/
│   ├── __init__.py          # Package init with version
│   └── cli.py               # Main CLI implementation
├── tmp/                     # Test directory (not committed)
├── setup.py                 # Package setup
├── README.md                # User documentation
├── LICENSE                  # MIT license
├── .gitignore              # Git ignore rules
└── CLAUDE.md               # This file (project context)

Testing

Manual Testing Done

  1. Installation: pip install -e . - ✓ Works
  2. Core commands:
  • dbbasic help - ✓ Shows all commands
  • dbbasic list - ✓ Lists templates (with fallback)
  • dbbasic new - ✓ Shows usage
  1. Module discovery: ✓ Finds dbbasic-queue and dbbasic-logs commands
  2. Module commands:
  • dbbasic queue:stats - ✓ Shows queue statistics
  • dbbasic logs:stats - ✓ Shows log statistics

Test Location

Temporary test directory: /Users/danq/dbbasic-cli-new/tmp/

  • Not committed to git
  • Used for integration testing
  • Safe to delete

Known Issues & Notes

pkg_resources Deprecation Warning

The CLI currently uses pkg_resources which shows a deprecation warning:

UserWarning: pkg_resources is deprecated as an API

Why it's used: It's the most reliable way to discover installed packages across different Python environments.

Future fix: Consider migrating to importlib.metadata (Python 3.8+) or packaging library. However, pkg_resources still works fine and will be supported through at least 2025.

Impact: None - just a warning, functionality is unaffected.

Template Repository

The CLI expects templates at: https://github.com/askrobots/dbbasic-examples

This repository doesn't exist yet. The CLI:

  • Will try to clone it on first dbbasic new or dbbasic list
  • Has fallback template descriptions built-in
  • Gracefully handles missing repo

Action needed: Create the examples repository with these templates:

  • blog (WordPress-like)
  • microblog (Twitter-like)
  • api (REST API)
  • shop (E-commerce)
  • intranet (Basecamp-like)

Integration with Other Modules

Module Requirements

For a dbbasic module to add CLI commands:

  1. Create {module_name}/cli.py
  2. Define command functions with signature: def cmd_name(args: list)
  3. Add docstrings to functions (first line appears in help)
  4. Export COMMANDS dict mapping command names to functions

Example:

# dbbasic_yourmodule/cli.py

def hello_command(args):
    """Say hello from your module"""
    print("Hello!")

COMMANDS = {
    'yourmodule:hello': hello_command,
}

Installed Modules with CLI Support

Currently implemented:

  • ✓ dbbasic-queue - 5 commands (worker, stats, failed, retry, clear)
  • ✓ dbbasic-logs - 4 commands (tail, search, compress, stats)

Ready to add:

  • dbbasic-accounts - Could add: accounts:create, accounts:list, accounts:reset-password
  • dbbasic-sessions - Could add: sessions:clean (remove expired)
  • dbbasic-tsv - Could add: tsv:export, tsv:import, tsv:optimize
  • dbbasic-web - Could add: web:routes (list all routes)

Standard Directory Structure (Apps Created by CLI)

When dbbasic new <type> <name> creates an app:

myapp/
├── app.py              # Main application file
├── data/               # TSV data files
│   └── *.tsv
├── templates/          # HTML templates
│   └── *.html
├── static/             # CSS, JS, images
│   ├── css/
│   ├── js/
│   └── img/
├── tests/              # Test files
│   └── test_*.py
├── requirements.txt    # Python dependencies
└── README.md          # Documentation

Development Workflow

Making Changes to CLI

  1. Edit files in /Users/danq/dbbasic-cli-new/
  2. Changes are immediately available (editable install)
  3. Test with dbbasic <command>

Adding New Commands

Core commands (edit cli.py):

  • Add cmd_<name>(args) function
  • Add command to main() function
  • Update print_help() if needed

Module commands (edit module's cli.py):

  • Add function to module's cli.py
  • Add to COMMANDS dict
  • Reinstall module: pip install -e .

Testing Checklist

Before release:

  • [ ] All core commands work
  • [ ] Module discovery finds all installed modules
  • [ ] Help text is clear and complete
  • [ ] Error messages are helpful
  • [ ] Works without any modules installed
  • [ ] Works with modules that don't have CLI
  • [ ] Examples repository exists and is accessible

Related Files & Projects

  • GitHub Repository: https://github.com/askrobots/dbbasic-cli-new.git
  • Specification: http://dbbasic.com/cli-spec
  • Main site: http://dbbasic.com/
  • Old CLI (different design): /Users/danq/websheet/dbbasic-cli/

Differences from Old CLI

The old CLI at /Users/danq/websheet/dbbasic-cli/:

  • Uses Typer framework (heavy dependency)
  • Has built-in app generators (crm, shop, blog)
  • Manages services (start, stop, status)
  • More opinionated and complex

The new CLI (this project):

  • Zero dependencies (pure Python)
  • Simpler (just templates + module commands)
  • More Unix-like (thin wrapper)
  • Follows the spec at dbbasic.com/cli-spec

Future Enhancements

Short Term

  1. ✓ Add CLI support to dbbasic-queue
  2. ✓ Add CLI support to dbbasic-logs
  3. Create dbbasic-examples repository
  4. Add CLI support to other modules

Medium Term

  1. Replace pkg_resources with importlib.metadata
  2. Add dbbasic scaffold generator (CRUD operations)
  3. Add completion support (bash, zsh)
  4. Better error handling for missing dependencies

Long Term

  1. Plugin system for third-party commands
  2. Configuration file support (~/.dbbasicrc)
  3. Template marketplace/registry
  4. Project initialization wizard

Contributing

When adding features:

  1. Keep it simple - follow Unix philosophy
  2. No heavy dependencies (prefer stdlib)
  3. Make everything optional
  4. Preserve backward compatibility
  5. Update this CLAUDE.md file

Package Publishing

Build Distribution

python setup.py sdist bdist_wheel

Upload to PyPI

pip install twine
twine upload dist/*

Version Bumping

Update version in:

  • dbbasic_cli/__init__.py
  • setup.py

Session Context for Claude

When working on this project:

  • Main code: /Users/danq/dbbasic-cli-new/
  • Test area: /Users/danq/dbbasic-cli-new/tmp/
  • Module examples: /Users/danq/dbbasic-queue/, /Users/danq/dbbasic-logs/
  • Spec reference: Use WebFetch to get http://dbbasic.com/cli-spec

Quick Commands for Testing

# Reinstall CLI
cd /Users/danq/dbbasic-cli-new && pip install -e .

# Test core
dbbasic help
dbbasic list

# Test module commands
dbbasic queue:stats
dbbasic logs:stats

# Test in clean environment
cd /Users/danq/dbbasic-cli-new/tmp

Summary

This is a working, spec-compliant implementation of dbbasic-cli that:

  • ✓ Implements core commands (new, list, run, test)
  • ✓ Auto-discovers module commands from installed packages
  • ✓ Has no dependencies
  • ✓ Is ~200 lines of code
  • ✓ Works with existing dbbasic modules
  • ✓ Includes working CLI extensions for queue and logs modules

The main outstanding item is creating the dbbasic-examples repository with template applications.