Pollyanna Project Development

Development assistant for the Pollyanna community platform repository (gulkily/pollyanna). This skill helps you work with Perl-based web applications focused on community spaces with strong emphasis on consent, privacy, and transparency.

What This Skill Does

This skill guides you through development tasks in the Pollyanna codebase, ensuring adherence to security best practices, proper use of the template system, and correct build/deployment procedures.

Instructions

Before Starting Any Task

1. **Read the project context**: Check if `CLAUDE.md` exists in the repository root for up-to-date guidance

2. **Understand the template system**: Files in `/default/` are originals; customizations go in `/config/`

3. **Never edit `/default/` directly**: Always work with `/config/` versions or use the refresh command

Common Development Tasks

#### Building and Running

1. **To build the project**:

- Use `./hike.sh build` or `./build.sh`

- Verify build completes without errors

2. **To clean build artifacts**:

- Use `./hike.sh clean html` for HTML only

- Use `./hike.sh clean all` for complete clean

3. **To start the development server**:

- Use `./hike.sh start` or `./hike.sh startpython`

- Access the application in your browser

4. **To run tests**:

- Basic test: `./hike.sh test`

- Selenium smoke test: `python3 test/test.py`

#### Database Operations

1. **To access database CLI**:

- Use `./hike.sh db` for sqlite3 CLI

- Use `./hike.sh guidb` for graphical SQLite browser

2. **To index data**:

- Specific file: `./hike.sh index [filename]`

- All data: `./hike.sh index`

3. **Database is located at**: `cache/b/index.sqlite3`

#### Template Management

1. **To update templates from defaults**:

- Use `./hike.sh refresh`

- This copies updates from `/default/` to `/config/`

2. **Template organization**:

- Templates are under `/template/` directories

- Organized by type: perl, js, html, etc.

- Themes live under `/default/theme/`

Code Style Requirements

When writing or modifying Perl code:

1. **Security First**:

- ALWAYS use taint mode: `#!/usr/bin/perl -T`

- Restrict PATH: `$ENV{PATH} = "/bin:/usr/bin";`

- Sanitize ALL paths and directories with regex before use

- Sanitize ALL SQL inputs properly

2. **Perl Pragmas**:

```perl

use strict;

use warnings;

use 5.010; # Specify minimum Perl version

```

3. **Subroutine Style**:

- Use named subroutines with clear comments

- Example:

```perl

sub BuildMessage {

# Implementation here

} # BuildMessage()

```

4. **Error Handling**:

- Use `die()` for fatal errors

- Use `WriteLog()` for non-fatal information

- Include verbose error messages

- Add sanity checks for critical operations

5. **Dependencies**:

- Use `require_once()` for dependency management

- Use `ensure_module()` for module loading

Database Best Practices

1. **Default to append-only pattern** for data storage

2. **Always sanitize SQL inputs** before queries

3. **Use proper error handling** for all database operations

4. **Maintain backward compatibility** with older browsers

File Organization

1. **Configuration Files**:

- `/config/` - Customized versions (edit these)

- `/default/` - Original templates (read-only)

- Missing `/config/` files auto-copy from `/default/`

2. **Templates**:

- `/template/` - Template files by type

- `/default/theme/` - Theme implementations

Examples

Example 1: Adding a new feature

```

User: Add a new community moderation feature

Assistant:

1. First, let me read the existing codebase structure

[Uses Read tool to examine relevant files]

2. I'll create the Perl script following security guidelines

- Using taint mode and restricted PATH

- Sanitizing all inputs

- Adding proper error handling

3. Update database schema if needed (append-only)

4. Add templates to /config/ (not /default/)

5. Run ./hike.sh test to verify

```

Example 2: Fixing a bug

```

User: There's a security issue with path handling in upload.pl

Assistant:

1. Reading the file to identify the issue

[Uses Read tool]

2. The path isn't sanitized - adding regex validation:

if ($path =~ m/^([a-zA-Z0-9_\-\.\/]+)$/) {

$safe_path = $1;

} else {

die("Invalid path characters detected");

}

3. Testing with ./hike.sh test

4. Running smoke tests with python3 test/test.py

```

Example 3: Database maintenance

```

User: Add a new table for user preferences

Assistant:

1. Using ./hike.sh db to access SQLite CLI

2. Creating table with append-only design

3. Adding proper indexes

4. Running ./hike.sh index to update search index

5. Testing database operations

```

Constraints and Important Notes

Project Values

This codebase emphasizes:

When developing features, keep these values in mind and ensure new code supports them.