diff --git a/conductor/code_styleguides/general.md b/conductor/code_styleguides/general.md new file mode 100644 index 0000000..dfcc793 --- /dev/null +++ b/conductor/code_styleguides/general.md @@ -0,0 +1,23 @@ +# General Code Style Principles + +This document outlines general coding principles that apply across all languages and frameworks used in this project. + +## Readability +- Code should be easy to read and understand by humans. +- Avoid overly clever or obscure constructs. + +## Consistency +- Follow existing patterns in the codebase. +- Maintain consistent formatting, naming, and structure. + +## Simplicity +- Prefer simple solutions over complex ones. +- Break down complex problems into smaller, manageable parts. + +## Maintainability +- Write code that is easy to modify and extend. +- Minimize dependencies and coupling. + +## Documentation +- Document *why* something is done, not just *what*. +- Keep documentation up-to-date with code changes. diff --git a/conductor/code_styleguides/typescript.md b/conductor/code_styleguides/typescript.md new file mode 100644 index 0000000..c1dbf0b --- /dev/null +++ b/conductor/code_styleguides/typescript.md @@ -0,0 +1,43 @@ +# Google TypeScript Style Guide Summary + +This document summarizes key rules and best practices from the Google TypeScript Style Guide, which is enforced by the `gts` tool. + +## 1. Language Features +- **Variable Declarations:** Always use `const` or `let`. **`var` is forbidden.** Use `const` by default. +- **Modules:** Use ES6 modules (`import`/`export`). **Do not use `namespace`.** +- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.** +- **Classes:** + - **Do not use `#private` fields.** Use TypeScript's `private` visibility modifier. + - Mark properties never reassigned outside the constructor with `readonly`. + - **Never use the `public` modifier** (it's the default). Restrict visibility with `private` or `protected` where possible. +- **Functions:** Prefer function declarations for named functions. Use arrow functions for anonymous functions/callbacks. +- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for interpolation and multi-line strings. +- **Equality Checks:** Always use triple equals (`===`) and not equals (`!==`). +- **Type Assertions:** **Avoid type assertions (`x as SomeType`) and non-nullability assertions (`y!`)**. If you must use them, provide a clear justification. + +## 2. Disallowed Features +- **`any` Type:** **Avoid `any`**. Prefer `unknown` or a more specific type. +- **Wrapper Objects:** Do not instantiate `String`, `Boolean`, or `Number` wrapper classes. +- **Automatic Semicolon Insertion (ASI):** Do not rely on it. **Explicitly end all statements with a semicolon.** +- **`const enum`:** Do not use `const enum`. Use plain `enum` instead. +- **`eval()` and `Function(...string)`:** Forbidden. + +## 3. Naming +- **`UpperCamelCase`:** For classes, interfaces, types, enums, and decorators. +- **`lowerCamelCase`:** For variables, parameters, functions, methods, and properties. +- **`CONSTANT_CASE`:** For global constant values, including enum values. +- **`_` Prefix/Suffix:** **Do not use `_` as a prefix or suffix** for identifiers, including for private properties. + +## 4. Type System +- **Type Inference:** Rely on type inference for simple, obvious types. Be explicit for complex types. +- **`undefined` and `null`:** Both are supported. Be consistent within your project. +- **Optional vs. `|undefined`:** Prefer optional parameters and fields (`?`) over adding `|undefined` to the type. +- **`Array` Type:** Use `T[]` for simple types. Use `Array` for more complex union types (e.g., `Array`). +- **`{}` Type:** **Do not use `{}`**. Prefer `unknown`, `Record`, or `object`. + +## 5. Comments and Documentation +- **JSDoc:** Use `/** JSDoc */` for documentation, `//` for implementation comments. +- **Redundancy:** **Do not declare types in `@param` or `@return` blocks** (e.g., `/** @param {string} user */`). This is redundant in TypeScript. +- **Add Information:** Comments must add information, not just restate the code. + +*Source: [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)* diff --git a/conductor/index.md b/conductor/index.md new file mode 100644 index 0000000..ce6eea1 --- /dev/null +++ b/conductor/index.md @@ -0,0 +1,14 @@ +# Project Context + +## Definition +- [Product Definition](./product.md) +- [Product Guidelines](./product-guidelines.md) +- [Tech Stack](./tech-stack.md) + +## Workflow +- [Workflow](./workflow.md) +- [Code Style Guides](./code_styleguides/) + +## Management +- [Tracks Registry](./tracks.md) +- [Tracks Directory](./tracks/) diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md new file mode 100644 index 0000000..0ea521c --- /dev/null +++ b/conductor/product-guidelines.md @@ -0,0 +1,17 @@ +# Product Guidelines - SilverBullet iCalendar Plug + +## Documentation and Communication Style +- **Technical and Concise:** All documentation, configuration examples, and user-facing messages should be accurate, brief, and focused on providing high value to the user. Avoid unnecessary fluff or conversational filler. +- **Example-Driven:** Prioritize clear, copy-pasteable configuration snippets and query examples to help users get started quickly. + +## Visual Identity and User Interface +- **Native SilverBullet Integration:** The plug should feel like a core part of the SilverBullet experience. Commands, notifications, and any future UI elements must strictly adhere to SilverBullet's design patterns and aesthetic. +- **Informative and Actionable Feedback:** + - Notifications should provide immediate clarity on the outcome of actions (e.g., "Synced 194 events", "Sync failed: HTTP 404"). + - Error messages should be descriptive enough to aid in troubleshooting (e.g., specifying which source failed). +- **Subtle Consistency:** Use consistent naming conventions for commands (`iCalendar: Sync`, `iCalendar: Force Sync`, etc.) to maintain a professional and organized command palette. + +## Code and Maintenance Guidelines (Inferred) +- **Robust Error Handling:** Always catch and log errors during fetch and parse operations to prevent the entire sync process from crashing. +- **Performance First:** Efficiently process large `.ics` files and avoid redundant indexing operations. +- **Version Alignment:** Ensure the version number is synchronized across `deno.json`, `icalendar.plug.yaml`, `PLUG.md`, and the TypeScript source code. diff --git a/conductor/product.md b/conductor/product.md new file mode 100644 index 0000000..83466e9 --- /dev/null +++ b/conductor/product.md @@ -0,0 +1,23 @@ +# Initial Concept +`silverbullet-icalendar` is a Plug for SilverBullet that reads external iCalendar data (.ics format) and integrates it into the SilverBullet environment. + +# Product Definition - SilverBullet iCalendar Plug + +## Vision +A reliable and seamless bridge between external iCalendar services and the SilverBullet knowledge management environment, enabling users to consolidate their scheduling data within their personal workspace. + +## Target Audience +- SilverBullet users who need to integrate external calendars (Google, Nextcloud, Outlook, etc.) directly into their notes and queries. + +## Core Goals & Features +- **Reliable Multi-Source Synchronization:** Support for fetching and parsing `.ics` data from various providers like Google Calendar and Nextcloud. +- **SilverBullet Index Integration:** Seamlessly index calendar events using the `ical-event` tag, making them instantly queryable using SilverBullet's Lua Integrated Query (LIQ). +- **Robust Timezone Handling:** Accurate conversion and shifting of event times to ensure consistency regardless of the source provider's configuration. +- **Cache Management:** Efficient local caching of calendar data with user-configurable durations and force-sync capabilities. +- **Clean Indexing:** Sanitization of complex iCalendar objects into flat, query-friendly metadata. + +## Technology Stack (Inferred) +- **Language:** TypeScript +- **Runtime:** Deno +- **Platform:** SilverBullet Plug API +- **Parsing Library:** `ts-ics` diff --git a/conductor/setup_state.json b/conductor/setup_state.json new file mode 100644 index 0000000..137ed4f --- /dev/null +++ b/conductor/setup_state.json @@ -0,0 +1 @@ +{"last_successful_step": "2.5_workflow"} diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md new file mode 100644 index 0000000..6cfb9e1 --- /dev/null +++ b/conductor/tech-stack.md @@ -0,0 +1,18 @@ +# Technology Stack - SilverBullet iCalendar Plug + +## Core Runtime & Language +- **Language:** [TypeScript](https://www.typescriptlang.org/) - Provides type safety and modern JavaScript features for robust plug development. +- **Runtime:** [Deno](https://deno.com/) - A secure-by-default runtime for JavaScript and TypeScript, used for building and running the plug's development tasks. + +## Platform & API +- **Platform:** [SilverBullet Plug API](https://silverbullet.md/Plugs) - The official API for extending SilverBullet functionality. +- **Dependency Management:** [JSR](https://jsr.io/) and [ESM.sh](https://esm.sh/) - Used for importing the SilverBullet syscalls and external libraries like `ts-ics`. + +## Libraries +- **iCalendar Parsing:** [`ts-ics`](https://www.npmjs.com/package/ts-ics) (v2.4.0) - A library for parsing iCalendar data into structured JavaScript objects. + +## Build & Development Tools +- **Task Orchestration:** Deno Tasks (defined in `deno.json`) - Handles version synchronization and plug compilation. +- **Compiler:** `plug-compile.js` - The standard SilverBullet utility for bundling the TypeScript source and manifest into a `.plug.js` file. +- **Version Control:** Git - For source code management and integration with Gitea Actions. +- **CI/CD:** Gitea Actions - Automates the build and deployment process upon pushes to the repository. diff --git a/conductor/tracks.md b/conductor/tracks.md new file mode 100644 index 0000000..6176ba4 --- /dev/null +++ b/conductor/tracks.md @@ -0,0 +1,8 @@ +# Project Tracks + +This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder. + +--- + +- [ ] **Track: Upgrade the SilverBullet iCalendar plug to use DST-aware timezone resolution and add recurring event support using rrule.** + *Link: [./tracks/timezone_rrule_20260218/](./tracks/timezone_rrule_20260218/)* diff --git a/conductor/tracks/timezone_rrule_20260218/index.md b/conductor/tracks/timezone_rrule_20260218/index.md new file mode 100644 index 0000000..0ef3ac2 --- /dev/null +++ b/conductor/tracks/timezone_rrule_20260218/index.md @@ -0,0 +1,5 @@ +# Track timezone_rrule_20260218 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/tracks/timezone_rrule_20260218/metadata.json b/conductor/tracks/timezone_rrule_20260218/metadata.json new file mode 100644 index 0000000..1a4cc9c --- /dev/null +++ b/conductor/tracks/timezone_rrule_20260218/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "timezone_rrule_20260218", + "type": "feature", + "status": "new", + "created_at": "2026-02-18T11:20:00Z", + "updated_at": "2026-02-18T11:20:00Z", + "description": "Upgrade the SilverBullet iCalendar plug to use DST-aware timezone resolution and add recurring event support using rrule." +} diff --git a/conductor/tracks/timezone_rrule_20260218/plan.md b/conductor/tracks/timezone_rrule_20260218/plan.md new file mode 100644 index 0000000..87da6ff --- /dev/null +++ b/conductor/tracks/timezone_rrule_20260218/plan.md @@ -0,0 +1,40 @@ +# Implementation Plan: Proper Timezone Handling & Recurring Events + +## Phase 1: Foundation - Timezone Mapping & Resolver +- [ ] Task: Setup Timezone Map (WINDOWS_TO_IANA) + - [ ] Write failing tests for `resolveIanaName` + - [ ] Implement `WINDOWS_TO_IANA` mapping and `resolveIanaName` in `timezones.ts` +- [ ] Task: Implement UTC Offset Resolver using Intl + - [ ] Write failing tests for `getUtcOffsetMs` + - [ ] Implement `getUtcOffsetMs` in `timezones.ts` +- [ ] Task: Conductor - User Manual Verification 'Phase 1: Foundation' (Protocol in workflow.md) + +## Phase 2: Core Logic - Extraction & Shifting +- [ ] Task: Fix Wall-Clock Extraction logic + - [ ] Write failing tests for `resolveEventStart` (mocking `Intl` if necessary) + - [ ] Implement `resolveEventStart` in `icalendar.ts` to handle local time ground truth +- [ ] Task: Conductor - User Manual Verification 'Phase 2: Core Logic' (Protocol in workflow.md) + +## Phase 3: Features - Recurring Events & Filtering +- [ ] Task: Integrate `rrule` library + - [ ] Add `rrule` to `deno.json` imports + - [ ] Verify import works in a simple script +- [ ] Task: Implement Recurring Event Expansion + - [ ] Write failing tests for `expandRecurrences` + - [ ] Implement `expandRecurrences` in `icalendar.ts` +- [ ] Task: Implement EXDATE support + - [ ] Write failing tests for EXDATE exclusion + - [ ] Update `expandRecurrences` to handle `EXDATE` +- [ ] Task: Implement Status Filtering + - [ ] Write failing tests for filtering "CANCELLED" events + - [ ] Update sync logic to filter based on iCalendar status +- [ ] Task: Conductor - User Manual Verification 'Phase 3: Features' (Protocol in workflow.md) + +## Phase 4: Cleanup & Configuration +- [ ] Task: Remove obsolete configuration + - [ ] Write failing tests verifying `tzShift` is ignored/deprecated + - [ ] Remove `tzShift` and `hourShift` from `getSources` and `fetchAndParseCalendar` +- [ ] Task: Add `syncWindowDays` configuration + - [ ] Write failing tests for configurable expansion window + - [ ] Implement `syncWindowDays` in config and sync logic +- [ ] Task: Conductor - User Manual Verification 'Phase 4: Cleanup & Configuration' (Protocol in workflow.md) diff --git a/conductor/tracks/timezone_rrule_20260218/spec.md b/conductor/tracks/timezone_rrule_20260218/spec.md new file mode 100644 index 0000000..2e755e3 --- /dev/null +++ b/conductor/tracks/timezone_rrule_20260218/spec.md @@ -0,0 +1,36 @@ +# Specification: Proper Timezone Handling & Recurring Events + +## Overview +Upgrade the SilverBullet iCalendar plug to provide accurate, DST-aware timezone resolution and full support for recurring events (RRULE expansion). This replaces manual hour shifting with an automated, reliable system using IANA timezone standards and the `Intl` API. + +## Functional Requirements +- **IANA Timezone Mapping:** Implement a comprehensive mapping of 139 Windows timezone names to IANA identifiers using Unicode CLDR data. +- **DST-Aware Offsets:** Calculate UTC offsets at runtime for specific event dates using the built-in `Intl.DateTimeFormat` API, ensuring accuracy during Daylight Saving Time transitions. +- **Robust Date Extraction:** Correct the wall-clock extraction logic to prevent "double-shifting" of event times. +- **Recurring Event Expansion:** + - Integrate the `rrule` library to expand recurring events into individual occurrences. + - Support `EXDATE` for excluding specific instances of a recurring series. + - Implement a configurable `syncWindowDays` (default: 365) to limit the expansion range. +- **Advanced Filtering:** + - Filter out "CANCELLED" events based on the iCalendar status field. + - (Optional) Add `includeTransparent` and `includeDeclined` per-source flags. +- **Error Handling & Fallbacks:** + - If a timezone is unrecognized, fallback to UTC and append a warning to the event's description. +- **Configuration Cleanup:** + - Remove the redundant `tzShift` / `hourShift` parameters. + - Add `syncWindowDays` global config. + +## Non-Functional Requirements +- **Self-Contained:** Maintain the plug as a Deno-compatible project using `esm.sh` or `deno.json` imports. +- **Performance:** Ensure efficient expansion of recurrences, even for busy calendars. + +## Acceptance Criteria +1. Events from various providers (Google, O365, Nextcloud) appear at the correct local time in SilverBullet, regardless of DST. +2. All occurrences of a weekly recurring event within the sync window are indexed. +3. Excluded dates (`EXDATE`) are correctly omitted from the index. +4. Cancelled events are not indexed. +5. The manual `tzShift` configuration is no longer required for correct time display. + +## Out of Scope +- Full CalDAV synchronization (this remains a read-only `.ics` fetcher). +- UI for managing individual recurring instances (handled via SilverBullet queries). diff --git a/conductor/workflow.md b/conductor/workflow.md new file mode 100644 index 0000000..6f9cfd8 --- /dev/null +++ b/conductor/workflow.md @@ -0,0 +1,333 @@ +# Project Workflow + +## Guiding Principles + +1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md` +2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation +3. **Test-Driven Development:** Write unit tests before implementing functionality +4. **High Code Coverage:** Aim for >80% code coverage for all modules +5. **User Experience First:** Every decision should prioritize user experience +6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution. + +## Task Workflow + +All tasks follow a strict lifecycle: + +### Standard Task Workflow + +1. **Select Task:** Choose the next available task from `plan.md` in sequential order + +2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]` + +3. **Write Failing Tests (Red Phase):** + - Create a new test file for the feature or bug fix. + - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task. + - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests. + +4. **Implement to Pass Tests (Green Phase):** + - Write the minimum amount of application code necessary to make the failing tests pass. + - Run the test suite again and confirm that all tests now pass. This is the "Green" phase. + +5. **Refactor (Optional but Recommended):** + - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior. + - Rerun tests to ensure they still pass after refactoring. + +6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like: + ```bash + pytest --cov=app --cov-report=html + ``` + Target: >80% coverage for new code. The specific tools and commands will vary by language and framework. + +7. **Document Deviations:** If implementation differs from tech stack: + - **STOP** implementation + - Update `tech-stack.md` with new design + - Add dated note explaining the change + - Resume implementation + +8. **Commit Code Changes:** + - Stage all code changes related to the task. + - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`. + - Perform the commit. + +9. **Attach Task Summary with Git Notes:** + - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`). + - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change. + - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit. + ```bash + # The note content from the previous step is passed via the -m flag. + git notes add -m "" + ``` + +10. **Get and Record Task Commit SHA:** + - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash. + - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`. + +11. **Commit Plan Update:** + - **Action:** Stage the modified `plan.md` file. + - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`). + +### Phase Completion Verification and Checkpointing Protocol + +**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`. + +1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun. + +2. **Ensure Test Coverage for Phase Changes:** + - **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit. + - **Step 2.2: List Changed Files:** Execute `git diff --name-only HEAD` to get a precise list of all files modified during this phase. + - **Step 2.3: Verify and Create Tests:** For each file in the list: + - **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`). + - For each remaining code file, verify a corresponding test file exists. + - If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`). + +3. **Execute Automated Tests with Proactive Debugging:** + - Before execution, you **must** announce the exact shell command you will use to run the tests. + - **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`" + - Execute the announced command. + - If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance. + +4. **Propose a Detailed, Actionable Manual Verification Plan:** + - **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase. + - You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes. + - The plan you present to the user **must** follow this format: + + **For a Frontend Change:** + ``` + The automated tests have passed. For manual verification, please follow these steps: + + **Manual Verification Steps:** + 1. **Start the development server with the command:** `npm run dev` + 2. **Open your browser to:** `http://localhost:3000` + 3. **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly. + ``` + + **For a Backend Change:** + ``` + The automated tests have passed. For manual verification, please follow these steps: + + **Manual Verification Steps:** + 1. **Ensure the server is running.** + 2. **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'` + 3. **Confirm that you receive:** A JSON response with a status of `201 Created`. + ``` + +5. **Await Explicit User Feedback:** + - After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**" + - **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation. + +6. **Create Checkpoint Commit:** + - Stage all changes. If no changes occurred in this step, proceed with an empty commit. + - Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`). + +7. **Attach Auditable Verification Report using Git Notes:** + - **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation. + - **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit. + +8. **Get and Record Phase Checkpoint SHA:** + - **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`). + - **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: ]`. + - **Step 8.3: Write Plan:** Write the updated content back to `plan.md`. + +9. **Commit Plan Update:** + - **Action:** Stage the modified `plan.md` file. + - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '' as complete`. + +10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note. + +### Quality Gates + +Before marking any task complete, verify: + +- [ ] All tests pass +- [ ] Code coverage meets requirements (>80%) +- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`) +- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc) +- [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types) +- [ ] No linting or static analysis errors (using the project's configured tools) +- [ ] Works correctly on mobile (if applicable) +- [ ] Documentation updated if needed +- [ ] No security vulnerabilities introduced + +## Development Commands + +**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.** + +### Setup +```bash +# Example: Commands to set up the development environment (e.g., install dependencies, configure database) +# e.g., for a Node.js project: npm install +# e.g., for a Go project: go mod tidy +``` + +### Daily Development +```bash +# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format) +# e.g., for a Node.js project: npm run dev, npm test, npm run lint +# e.g., for a Go project: go run main.go, go test ./..., go fmt ./... +``` + +### Before Committing +```bash +# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests) +# e.g., for a Node.js project: npm run check +# e.g., for a Go project: make check (if a Makefile exists) +``` + +## Testing Requirements + +### Unit Testing +- Every module must have corresponding tests. +- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach). +- Mock external dependencies. +- Test both success and failure cases. + +### Integration Testing +- Test complete user flows +- Verify database transactions +- Test authentication and authorization +- Check form submissions + +### Mobile Testing +- Test on actual iPhone when possible +- Use Safari developer tools +- Test touch interactions +- Verify responsive layouts +- Check performance on 3G/4G + +## Code Review Process + +### Self-Review Checklist +Before requesting review: + +1. **Functionality** + - Feature works as specified + - Edge cases handled + - Error messages are user-friendly + +2. **Code Quality** + - Follows style guide + - DRY principle applied + - Clear variable/function names + - Appropriate comments + +3. **Testing** + - Unit tests comprehensive + - Integration tests pass + - Coverage adequate (>80%) + +4. **Security** + - No hardcoded secrets + - Input validation present + - SQL injection prevented + - XSS protection in place + +5. **Performance** + - Database queries optimized + - Images optimized + - Caching implemented where needed + +6. **Mobile Experience** + - Touch targets adequate (44x44px) + - Text readable without zooming + - Performance acceptable on mobile + - Interactions feel native + +## Commit Guidelines + +### Message Format +``` +(): + +[optional body] + +[optional footer] +``` + +### Types +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation only +- `style`: Formatting, missing semicolons, etc. +- `refactor`: Code change that neither fixes a bug nor adds a feature +- `test`: Adding missing tests +- `chore`: Maintenance tasks + +### Examples +```bash +git commit -m "feat(auth): Add remember me functionality" +git commit -m "fix(posts): Correct excerpt generation for short posts" +git commit -m "test(comments): Add tests for emoji reaction limits" +git commit -m "style(mobile): Improve button touch targets" +``` + +## Definition of Done + +A task is complete when: + +1. All code implemented to specification +2. Unit tests written and passing +3. Code coverage meets project requirements +4. Documentation complete (if applicable) +5. Code passes all configured linting and static analysis checks +6. Works beautifully on mobile (if applicable) +7. Implementation notes added to `plan.md` +8. Changes committed with proper message +9. Git note with task summary attached to the commit + +## Emergency Procedures + +### Critical Bug in Production +1. Create hotfix branch from main +2. Write failing test for bug +3. Implement minimal fix +4. Test thoroughly including mobile +5. Deploy immediately +6. Document in plan.md + +### Data Loss +1. Stop all write operations +2. Restore from latest backup +3. Verify data integrity +4. Document incident +5. Update backup procedures + +### Security Breach +1. Rotate all secrets immediately +2. Review access logs +3. Patch vulnerability +4. Notify affected users (if any) +5. Document and update security procedures + +## Deployment Workflow + +### Pre-Deployment Checklist +- [ ] All tests passing +- [ ] Coverage >80% +- [ ] No linting errors +- [ ] Mobile testing complete +- [ ] Environment variables configured +- [ ] Database migrations ready +- [ ] Backup created + +### Deployment Steps +1. Merge feature branch to main +2. Tag release with version +3. Push to deployment service +4. Run database migrations +5. Verify deployment +6. Test critical paths +7. Monitor for errors + +### Post-Deployment +1. Monitor analytics +2. Check error logs +3. Gather user feedback +4. Plan next iteration + +## Continuous Improvement + +- Review workflow weekly +- Update based on pain points +- Document lessons learned +- Optimize for user happiness +- Keep things simple and maintainable