Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
153 lines (110 loc) · 4.95 KB

CONTRIBUTING.md

File metadata and controls

153 lines (110 loc) · 4.95 KB

Contributing to LogSeq CLI

Thank you for your interest in contributing to LogSeq CLI! This document provides guidelines and information for contributors.

Getting Started

  1. Fork the repository
  2. Clone your fork locally
  3. Install dependencies: bun install
  4. Set up your environment: cp .env.template .env and configure your LogSeq API token
  5. Run tests to verify your setup: bun test

Development Workflow

Making Changes

  1. Create a branch for your changes: git checkout -b feature/your-feature-name
  2. Make your changes
  3. Add tests for new functionality
  4. Ensure all tests pass: bun test
  5. Commit your changes with a descriptive message
  6. Push to your fork and submit a pull request

Code Style

  • Use TypeScript for all new code
  • Follow existing patterns in the codebase
  • Keep functions focused and single-purpose
  • Add JSDoc comments for public APIs

Testing

Tests are written using Bun's built-in test runner. Run the test suite with:

bun test

When adding new commands or features:

  • Add unit tests that mock the LogSeq API client
  • Test both success and error cases
  • Test all flag combinations
  • Verify edge cases (empty results, missing arguments, invalid input)

Manual Testing with LogSeq

For manual testing against a running LogSeq instance:

  1. Ensure LogSeq is running with HTTP API enabled
  2. Set your API token in .env
  3. Run commands directly: bun logseq.ts <command> [options]

Note: Use bun logseq.ts directly rather than bun run logseq for proper argument handling with spaces and special characters.

AI-Assisted Development

This project welcomes contributions made in collaboration with AI coding assistants such as Claude, GitHub Copilot, or similar tools.

Pairing with AI Assistants

When working with an AI assistant:

  1. Provide context: Share relevant files and documentation with your AI assistant
  2. Iterate on solutions: Use the AI to explore different approaches before committing
  3. Review generated code: Always review and understand AI-generated code before committing
  4. Test thoroughly: AI-generated code should pass all existing tests and include new tests for new functionality

Guidelines for AI Assistants

If you are an AI assistant helping a contributor with this project:

Environment Setup

  • The project uses Bun as its runtime and package manager
  • Environment variables are stored in .env (copy from .env.template)
  • The main entry point is logseq.ts

Testing Commands

When testing CLI commands that interact with LogSeq:

  1. Use tmux for interactive testing: Create a tmux session to test commands against a running LogSeq instance:

    tmux new-session -d -s logseq-test -c /path/to/logseq-cli

  2. Load environment variables: Before running commands, load the environment:

    export $(grep -v '^#' .env | xargs)

  3. Run commands directly: Use bun logseq.ts (not bun run logseq) for proper argument parsing:

    bun logseq.ts list-pages
bun logseq.ts get-page "Page Name"
bun logseq.ts search "query" --limit 10

  4. Test systematically: For each command, test:

    • Basic functionality with positional arguments
    • Alternative flag syntax (e.g., --name vs positional)
    • All optional flags
    • Error cases (missing required args, invalid input)
    • Edge cases (empty results, special characters)

  5. Create regression tests: After manual testing, add unit tests to cli/commands.test.ts that mock the API client and verify behavior.

Project Structure

logseq-cli/
├── logseq.ts              # CLI entry point
├── cli/
│   ├── arg_parser.ts      # Argument parsing
│   ├── arg_parser.test.ts # Argument parser tests
│   ├── commands.ts        # Command implementations
│   ├── commands.test.ts   # Command tests
│   └── help.ts            # Help text
├── logseq/
│   └── http_client.ts     # LogSeq API client
├── .env.template          # Environment template
└── CONTRIBUTING.md        # This file

Common Patterns

  • Commands are exported functions in cli/commands.ts
  • Each command parses args with parseArgs() from cli/arg_parser.ts
  • The LogSeq client is instantiated via getClient() which reads from environment variables
  • Tests mock the LogSeq client methods and capture console output

Reporting Issues

When reporting bugs, please include:

  • Your operating system and version
  • Bun version (bun --version)
  • LogSeq version
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Any error messages

Pull Request Process

  1. Update documentation if you're changing functionality
  2. Add or update tests as needed
  3. Ensure the test suite passes
  4. Update the README if adding new commands or options
  5. Request review from maintainers

License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project (MIT).