Skip to content

Commit d4af0d5

Browse files
IanGordonOneclaude
IanGordonOne
and
claude
committed
Add tests, contributing guidelines, and fix API error handling
- Add comprehensive test suite for CLI commands (58 tests) - Create CONTRIBUTING.md with AI assistant guidelines and tmux testing docs - Add .env.template for easier environment setup - Add .gitignore for .env, node_modules, and .claude - Fix API error handling for error responses in body (e.g., MethodNotExist) - Add graceful handling for missing getPageProperties API method - Update README with setup instructions and contributing section - Add SETUP section to CLI help output Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 3849d58 commit d4af0d5

File tree

7 files changed

+916
-7
lines changed

7 files changed

+916
-7
lines changed

‎.env.template‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Logseq API Token
2+
# To generate this token:
3+
# 1. Open Logseq
4+
# 2. Go to Settings > Features
5+
# 3. Enable "Enable HTTP API"
6+
# 4. Set your token in "HTTP API Authentication Token"
7+
# 5. Copy that token here
8+
9+
LOGSEQ_API_TOKEN=your_token_here
10+
11+
# Optional: Configure how to reach the Logseq HTTP API
12+
# Defaults to http://127.0.0.1:12315/api if not set.
13+
# When running inside Docker on Windows/macOS, you can use host.docker.internal to reach the host.
14+
# On native Linux, you may need to add --add-host=host.docker.internal:host-gateway when running the container.
15+
16+
# LOGSEQ_HOST=127.0.0.1
17+
# LOGSEQ_PORT=12315
18+
# Alternatively, set the full API URL directly (overrides HOST/PORT if provided)
19+
# LOGSEQ_API_URL=http://127.0.0.1:12315/api

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.env
2+
node_modules/
3+
.claude/

‎CONTRIBUTING.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Contributing to LogSeq CLI
2+
3+
Thank you for your interest in contributing to LogSeq CLI! This document provides guidelines and information for contributors.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork locally
9+
3. Install dependencies: `bun install`
10+
4. Set up your environment: `cp .env.template .env` and configure your LogSeq API token
11+
5. Run tests to verify your setup: `bun test`
12+
13+
## Development Workflow
14+
15+
### Making Changes
16+
17+
1. Create a branch for your changes: `git checkout -b feature/your-feature-name`
18+
2. Make your changes
19+
3. Add tests for new functionality
20+
4. Ensure all tests pass: `bun test`
21+
5. Commit your changes with a descriptive message
22+
6. Push to your fork and submit a pull request
23+
24+
### Code Style
25+
26+
- Use TypeScript for all new code
27+
- Follow existing patterns in the codebase
28+
- Keep functions focused and single-purpose
29+
- Add JSDoc comments for public APIs
30+
31+
### Testing
32+
33+
Tests are written using Bun's built-in test runner. Run the test suite with:
34+
35+
```bash
36+
bun test
37+
```
38+
39+
When adding new commands or features:
40+
- Add unit tests that mock the LogSeq API client
41+
- Test both success and error cases
42+
- Test all flag combinations
43+
- Verify edge cases (empty results, missing arguments, invalid input)
44+
45+
#### Manual Testing with LogSeq
46+
47+
For manual testing against a running LogSeq instance:
48+
49+
1. Ensure LogSeq is running with HTTP API enabled
50+
2. Set your API token in `.env`
51+
3. Run commands directly: `bun logseq.ts <command> [options]`
52+
53+
**Note:** Use `bun logseq.ts` directly rather than `bun run logseq` for proper argument handling with spaces and special characters.
54+
55+
## AI-Assisted Development
56+
57+
This project welcomes contributions made in collaboration with AI coding assistants such as Claude, GitHub Copilot, or similar tools.
58+
59+
### Pairing with AI Assistants
60+
61+
When working with an AI assistant:
62+
63+
1. **Provide context**: Share relevant files and documentation with your AI assistant
64+
2. **Iterate on solutions**: Use the AI to explore different approaches before committing
65+
3. **Review generated code**: Always review and understand AI-generated code before committing
66+
4. **Test thoroughly**: AI-generated code should pass all existing tests and include new tests for new functionality
67+
68+
### Guidelines for AI Assistants
69+
70+
If you are an AI assistant helping a contributor with this project:
71+
72+
#### Environment Setup
73+
74+
- The project uses Bun as its runtime and package manager
75+
- Environment variables are stored in `.env` (copy from `.env.template`)
76+
- The main entry point is `logseq.ts`
77+
78+
#### Testing Commands
79+
80+
When testing CLI commands that interact with LogSeq:
81+
82+
1. **Use tmux for interactive testing**: Create a tmux session to test commands against a running LogSeq instance:
83+
```bash
84+
tmux new-session -d -s logseq-test -c /path/to/logseq-cli
85+
```
86+
87+
2. **Load environment variables**: Before running commands, load the environment:
88+
```bash
89+
export $(grep -v '^#' .env | xargs)
90+
```
91+
92+
3. **Run commands directly**: Use `bun logseq.ts` (not `bun run logseq`) for proper argument parsing:
93+
```bash
94+
bun logseq.ts list-pages
95+
bun logseq.ts get-page "Page Name"
96+
bun logseq.ts search "query" --limit 10
97+
```
98+
99+
4. **Test systematically**: For each command, test:
100+
- Basic functionality with positional arguments
101+
- Alternative flag syntax (e.g., `--name` vs positional)
102+
- All optional flags
103+
- Error cases (missing required args, invalid input)
104+
- Edge cases (empty results, special characters)
105+
106+
5. **Create regression tests**: After manual testing, add unit tests to `cli/commands.test.ts` that mock the API client and verify behavior.
107+
108+
#### Project Structure
109+
110+
```
111+
logseq-cli/
112+
├── logseq.ts # CLI entry point
113+
├── cli/
114+
│ ├── arg_parser.ts # Argument parsing
115+
│ ├── arg_parser.test.ts # Argument parser tests
116+
│ ├── commands.ts # Command implementations
117+
│ ├── commands.test.ts # Command tests
118+
│ └── help.ts # Help text
119+
├── logseq/
120+
│ └── http_client.ts # LogSeq API client
121+
├── .env.template # Environment template
122+
└── CONTRIBUTING.md # This file
123+
```
124+
125+
#### Common Patterns
126+
127+
- Commands are exported functions in `cli/commands.ts`
128+
- Each command parses args with `parseArgs()` from `cli/arg_parser.ts`
129+
- The LogSeq client is instantiated via `getClient()` which reads from environment variables
130+
- Tests mock the LogSeq client methods and capture console output
131+
132+
## Reporting Issues
133+
134+
When reporting bugs, please include:
135+
136+
- Your operating system and version
137+
- Bun version (`bun --version`)
138+
- LogSeq version
139+
- Steps to reproduce the issue
140+
- Expected vs actual behavior
141+
- Any error messages
142+
143+
## Pull Request Process
144+
145+
1. Update documentation if you're changing functionality
146+
2. Add or update tests as needed
147+
3. Ensure the test suite passes
148+
4. Update the README if adding new commands or options
149+
5. Request review from maintainers
150+
151+
## License
152+
153+
By contributing to this project, you agree that your contributions will be licensed under the same license as the project (MIT).

‎README.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,19 @@ cd tools_for_logseq
2727
# Install dependencies
2828
bun install
2929

30-
# Set your API token
31-
export LOGSEQ_API_TOKEN=your-token-here
30+
# Set up environment variables
31+
cp .env.template .env
32+
# Edit .env and set LOGSEQ_API_TOKEN to your token
3233
```
3334

35+
## Getting Your API Token
36+
37+
1. Open Logseq
38+
2. Go to Settings > Features
39+
3. Enable "HTTP APIs Server"
40+
4. Set your token in "Authorization tokens"
41+
5. Copy that token to your `.env` file as `LOGSEQ_API_TOKEN`
42+
3443
## Project Structure
3544

3645
```
@@ -436,6 +445,15 @@ The CLI will exit with code 1 and display an error message when:
436445
- The LogSeq API returns an error
437446
- A referenced page or block doesn't exist
438447

448+
## Contributing
449+
450+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including information about:
451+
452+
- Development workflow
453+
- Testing practices
454+
- AI-assisted development
455+
- Guidelines for AI coding assistants
456+
439457
## License
440458

441459
MIT

0 commit comments

Comments
 (0)