156 lines
6.4 KiB
Markdown
156 lines
6.4 KiB
Markdown
|
# Plan: Update FissionPython Skill
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
The `fission-python-skill` plugin needs to be updated to meet new requirements for Fission Python projects:
|
||
|
|
|
||
|
|
1. **Build script**: `src/build.sh` must exist and be referenced correctly in `.fission/deployment.json`
|
||
|
|
2. **Dependencies**: `src/requirements.txt` must exist and contain necessary packages (pydantic, etc.)
|
||
|
|
3. **CI/CD**: All projects must include `.gitea/workflows/` directory with deployment workflows
|
||
|
|
4. **API Design**: HTTP trigger functions must use Pydantic models for request/response validation
|
||
|
|
5. **Documentation**: All functions must have proper docstrings and code comments
|
||
|
|
6. **Portability**: Remove hardcoded absolute paths - the plugin should work from any location
|
||
|
|
|
||
|
|
Current issues:
|
||
|
|
- `create-project.sh` uses hardcoded path `/workspaces/claude-marketplace/data/py-eom-quota`
|
||
|
|
- Template resides in `data/examples/` which is outside the plugin
|
||
|
|
- No validation of generated projects
|
||
|
|
- Documentation references incorrect paths
|
||
|
|
|
||
|
|
## Approach
|
||
|
|
|
||
|
|
**Step 1: Make Plugin Portable**
|
||
|
|
- Copy the `py-eom-quota` template into `fission-python-skill/template/`
|
||
|
|
- Update `create-project.sh` to find template relative to script location using `dirname "$0"`
|
||
|
|
- Remove all absolute path references
|
||
|
|
|
||
|
|
**Step 2: Add Project Validation**
|
||
|
|
Enhance `create-project.sh` with post-creation validation:
|
||
|
|
- Check `src/build.sh` exists and is executable
|
||
|
|
- Verify `.fission/deployment.json` references the correct build command (`./build.sh`)
|
||
|
|
- Check `src/requirements.txt` exists and contains required dependencies:
|
||
|
|
- `pydantic==2.x`
|
||
|
|
- `flask` (for HTTP handlers)
|
||
|
|
- `psycopg2-binary` or `psycopg2` (if database usage)
|
||
|
|
- Verify `.gitea/workflows/` directory exists with the 4 standard workflow files
|
||
|
|
- Validate that function files contain pydantic models (basic grep check)
|
||
|
|
- Warn if docstrings appear minimal or missing
|
||
|
|
|
||
|
|
**Step 3: Update Documentation**
|
||
|
|
- Fix `SKILL.md` and `reference.md` to reference the correct template path
|
||
|
|
- Document the new validation checks
|
||
|
|
- Update examples to show portable usage
|
||
|
|
|
||
|
|
**Step 4: Potentially Add New Tool**
|
||
|
|
Consider adding a separate validation tool (`validate-project.sh`) that can be run on existing projects to check compliance with standards.
|
||
|
|
|
||
|
|
## Critical Files to Modify
|
||
|
|
|
||
|
|
1. **`fission-python-skill/create-project.sh`**
|
||
|
|
- Change `TEMPLATE_DIR` to use relative path: `$(dirname "$0")/template`
|
||
|
|
- Add validation functions after project creation
|
||
|
|
- Improve error messages
|
||
|
|
- Add warnings for missing documentation
|
||
|
|
|
||
|
|
2. **`fission-python-skill/template/`** (new directory)
|
||
|
|
- Copy entire structure from `data/examples/py-eom-quota/`
|
||
|
|
- Ensure `build.sh` has correct permissions (755)
|
||
|
|
- Verify all configuration files
|
||
|
|
|
||
|
|
3. **`fission-python-skill/SKILL.md`** and **`reference.md`**
|
||
|
|
- Update template path references
|
||
|
|
- Document validation behavior
|
||
|
|
- Update examples
|
||
|
|
|
||
|
|
4. **`.claude-plugin/marketplace.json`**
|
||
|
|
- No changes needed (plugin registration OK)
|
||
|
|
|
||
|
|
## Implementation Details
|
||
|
|
|
||
|
|
### Template Structure
|
||
|
|
```
|
||
|
|
fission-python-skill/
|
||
|
|
└── template/
|
||
|
|
├── .fission/
|
||
|
|
│ ├── deployment.json
|
||
|
|
│ ├── dev-deployment.json
|
||
|
|
│ └── local-deployment.json
|
||
|
|
├── .gitea/
|
||
|
|
│ └── workflows/
|
||
|
|
│ ├── dev-deployment.yaml
|
||
|
|
│ ├── install-dispatch.yaml
|
||
|
|
│ ├── uninstall-dispatch.yaml
|
||
|
|
│ └── analystic-dispatch.yaml
|
||
|
|
├── src/
|
||
|
|
│ ├── build.sh (executable)
|
||
|
|
│ ├── requirements.txt (with pydantic, flask, etc.)
|
||
|
|
│ ├── models.py (with pydantic models)
|
||
|
|
│ ├── exceptions.py
|
||
|
|
│ ├── helpers.py
|
||
|
|
│ ├── vault.py
|
||
|
|
│ └── <example functions>.py (with docstrings and pydantic usage)
|
||
|
|
├── test/
|
||
|
|
├── manifests/
|
||
|
|
├── migrates/
|
||
|
|
├── specs/
|
||
|
|
├── dev-requirements.txt
|
||
|
|
├── README.md
|
||
|
|
├── .gitignore
|
||
|
|
└── .devcontainer/
|
||
|
|
```
|
||
|
|
|
||
|
|
### Validation Checklist in create-project.sh
|
||
|
|
After copying template and doing substitutions:
|
||
|
|
1. `[ -f "$PROJECT_PATH/src/build.sh" ]` || warning
|
||
|
|
2. `[ -x "$PROJECT_PATH/src/build.sh" ]` || chmod +x
|
||
|
|
3. Check `deployment.json` contains `"./build.sh"` in packages.buildcmd
|
||
|
|
4. `[ -f "$PROJECT_PATH/src/requirements.txt" ]` || error
|
||
|
|
5. Check requirements.txt contains `pydantic` (grep -q "pydantic")
|
||
|
|
6. Check requirements.txt contains `flask` (grep -q "flask")
|
||
|
|
7. `[ -d "$PROJECT_PATH/.gitea/workflows" ]` || warning/copy from template
|
||
|
|
8. Count workflow files: should have at least 4 .yaml files
|
||
|
|
9. Optional: Check that Python files have docstrings (grep for triple quotes)
|
||
|
|
10. Optional: Check for pydantic BaseModel usage in models.py
|
||
|
|
|
||
|
|
### Portable Path Resolution
|
||
|
|
```bash
|
||
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||
|
|
TEMPLATE_DIR="$SCRIPT_DIR/template"
|
||
|
|
```
|
||
|
|
|
||
|
|
This ensures the plugin works regardless of where it's invoked from.
|
||
|
|
|
||
|
|
## Verification Steps
|
||
|
|
|
||
|
|
1. **Test create-project**:
|
||
|
|
- Run `./fission-python-skill/create-project.sh test-project ./tmp/`
|
||
|
|
- Verify all expected directories/files exist
|
||
|
|
- Check that validation warnings/errors appear appropriately
|
||
|
|
|
||
|
|
2. **Test portability**:
|
||
|
|
- Move plugin to a different directory
|
||
|
|
- Run create-project from there
|
||
|
|
- Should still work without path adjustments
|
||
|
|
|
||
|
|
3. **Test validation**:
|
||
|
|
- Manually delete `src/requirements.txt` from template and create project → should error
|
||
|
|
- Remove pydantic from requirements.txt → should warn
|
||
|
|
- Remove .gitea/workflows → should warn
|
||
|
|
- Change build.sh buildcmd to something else → should warn
|
||
|
|
|
||
|
|
4. **Test generated project**:
|
||
|
|
- Verify functions have docstrings with fission config blocks
|
||
|
|
- Verify models.py uses pydantic BaseModel
|
||
|
|
- Verify HTTP triggers properly defined in deployment.json
|
||
|
|
|
||
|
|
## Risks and Considerations
|
||
|
|
|
||
|
|
- **Template duplication**: Moving template into plugin duplicates existing examples. That's acceptable - the examples in `data/examples/` are finished projects, while the template is a starter. Keep both.
|
||
|
|
- **Validation strictness**: Start with warnings for most checks, errors only for critical missing files (requirements.txt build.sh). Can tighten later.
|
||
|
|
- **Template maintenance**: When updating the template, only modify `fission-python-skill/template/`. The examples in `data/examples/` are independent and can diverge if needed.
|
||
|
|
|
||
|
|
## Post-Implementation
|
||
|
|
|
||
|
|
- Update any scripts or docs that reference the old template path
|
||
|
|
- Test the skill end-to-end through Claude Code
|
||
|
|
- Consider adding a `validate-project.sh` tool for existing projects
|