feat: add CLI support for local command and server mode #20

konard · 2025-12-09T04:56:53Z

Summary

This PR implements CLI support for web-capture, allowing it to work both as a local command for AI agents and as an HTTP API server. The implementation uses the lino-arguments pattern for unified configuration management.

Key Features

Server Mode: web-capture --serve starts the HTTP API server
Capture Mode: web-capture <url> captures a URL to file or stdout
Multiple Formats: Support for HTML, Markdown, and PNG screenshot output
Browser Engine Selection: Choose between Puppeteer and Playwright engines
Unified Configuration: Uses lino-arguments for CLI args, env vars, and .lenv files
Comprehensive CLI Options: --format, --output, --engine, --port, --configuration

Implementation Details

New Files

bin/web-capture.js - CLI entry point using lino-arguments pattern
.lenv - Default configuration file with PORT and BROWSER_ENGINE settings
tests/unit/cli.test.js - Unit tests for CLI functionality

Modified Files

package.json - Added bin field for CLI, added lino-arguments dependency, bumped version to 1.1.0
README.md - Added CLI usage documentation, configuration section, and examples

Configuration System

Uses lino-arguments with the following priority chain (highest to lowest):

CLI arguments: --port 8080
Environment variables: PORT=8080
Custom .lenv file: --configuration path/to/custom.lenv
Default .lenv file: .lenv in project root
Built-in defaults

.lenv File Format

# Server configuration
PORT: 3000

# Browser engine (puppeteer or playwright)
BROWSER_ENGINE: puppeteer

CLI Usage

Server Mode

# Start API server on default port 3000
web-capture --serve

# Start on custom port
web-capture --serve --port 8080

# Use custom configuration file
web-capture --serve --configuration /path/to/custom.lenv

Capture Mode

# Capture URL as HTML to stdout
web-capture https://example.com

# Capture as Markdown to file
web-capture https://example.com --format markdown --output page.md

# Take screenshot using Playwright engine
web-capture https://example.com --format png --engine playwright -o screenshot.png

# Use environment variable for configuration
PORT=8080 web-capture --serve

All Options

-c, --configuration  Path to .lenv configuration file
-s, --serve          Start as HTTP API server
-p, --port           Port for server mode (default: 3000)
-f, --format         Output format: html, markdown/md, image/png
-o, --output         Output file path
-e, --engine         Browser engine: puppeteer, playwright
-h, --help           Show help
-v, --version        Show version

Testing

All CLI tests pass (15 tests):

Help message display with --help and -h flags
Version display with --version and -v flags
URL validation and error handling
Format, engine, and output option documentation
Server mode option documentation
Configuration system integration

Unit tests verify the CLI argument parsing and help output work correctly with the lino-arguments/yargs integration.

Fixes

Fixes #19

🤖 Generated with Claude Code

Adding CLAUDE.md with task information for AI processing. This file will be removed when the task is complete. Issue: #19

- Add bin/web-capture.js CLI entry point supporting two modes: - Server mode: `web-capture --serve` starts HTTP API server - Capture mode: `web-capture <url>` captures URL to file/stdout - CLI options: --format (html/markdown/png), --output, --engine, --port - Add unit tests for CLI argument parsing and help/version commands - Update README with CLI usage documentation and examples - Bump version to 1.1.0 Fixes #19 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

konard · 2025-12-09T05:03:31Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $2.637984 USD
Calculated by Anthropic: $1.561243 USD
Difference: $-1.076741 (-40.82%)
📎 Log file uploaded as GitHub Gist (371KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

konard · 2025-12-09T05:03:37Z

🔄 Auto-restart 1/3

Detected uncommitted changes from previous run. Starting new session to review and commit them.

Uncommitted files:

M yarn.lock
?? package-lock.json

Auto-restart will stop after changes are committed or after 2 more iterations. Please wait until working session will end and give your feedback.

konard · 2025-12-09T05:06:31Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $1.759815 USD
Calculated by Anthropic: $0.780148 USD
Difference: $-0.979668 (-55.67%)
📎 Log file uploaded as GitHub Gist (635KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

konard · 2025-12-09T05:28:06Z

Please use https://github.com/link-foundation/lino-arguments pattern for arguments and configuration

konard · 2025-12-09T05:28:36Z

🤖 AI Work Session Started

Starting automated work session at 2025-12-09T05:28:34.064Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

- Install lino-arguments package for unified configuration management - Create .lenv file with default configuration (PORT, BROWSER_ENGINE) - Refactor bin/web-capture.js to use makeConfig from lino-arguments - Replace custom argument parsing with yargs-based configuration - Update CLI tests to work with new yargs output format - Add configuration documentation to README with priority chain Configuration priority (highest to lowest): 1. CLI arguments (--port 8080) 2. Environment variables (PORT=8080) 3. Custom .lenv file (--configuration path/to/custom.lenv) 4. Default .lenv file 5. Built-in defaults 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

konard · 2025-12-09T05:33:35Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $1.247949 USD
Calculated by Anthropic: $0.706584 USD
Difference: $-0.541365 (-43.38%)
📎 Log file uploaded as GitHub Gist (380KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

konard · 2025-12-11T00:18:14Z

Also make sure our Dockerfile and other files use new web-capture --serve.

konard · 2025-12-11T00:18:40Z

🤖 AI Work Session Started

Starting automated work session at 2025-12-11T00:18:38.313Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

Updated all references from direct node execution to use the new web-capture CLI command for consistency and better user experience. Changes: - Dockerfile: Changed ENTRYPOINT from "node src/index.js" to "node bin/web-capture.js --serve" - package.json: Updated dev script to use CLI command with nodemon - tests/e2e/process.test.js: Updated to spawn CLI command instead of direct node execution - ARCHITECTURE.md: Updated documentation to reflect new CLI usage in Dockerfile example This ensures the Dockerfile and all related files use the new unified CLI interface as requested in PR feedback. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

konard · 2025-12-11T00:24:15Z

✅ Updated to use new CLI command

I've updated all files to use the new web-capture --serve command as requested:

Changes Made

Dockerfile (line 45)
- Changed: ENTRYPOINT ["node", "src/index.js"]
- To: ENTRYPOINT ["node", "bin/web-capture.js", "--serve"]
package.json (line 11)
- Changed: "dev": "nodemon src/index.js"
- To: "dev": "nodemon bin/web-capture.js -- --serve"
tests/e2e/process.test.js (line 14)
- Changed: spawn('node', [path.resolve('src/index.js')])
- To: spawn('node', [path.resolve('bin/web-capture.js'), '--serve'])
ARCHITECTURE.md (line 518)
- Updated documentation example to reflect new CLI usage

Testing

✅ CLI help works correctly: node bin/web-capture.js --help
✅ Server starts successfully: node bin/web-capture.js --serve
✅ Unit tests passing (15 CLI tests, 11 conversion tests, 3 URL tests, 15 mock tests)
⚠️ E2E tests skipped (require Playwright browsers installation and Docker)

All files now consistently use the new unified CLI interface. The PR is ready for review.

konard · 2025-12-11T00:24:35Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $1.701392 USD
Calculated by Anthropic: $1.018824 USD
Difference: $-0.682568 (-40.12%)
📎 Log file uploaded as GitHub Gist (418KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

Initial commit with task details for issue #19

be69501

Adding CLAUDE.md with task information for AI processing. This file will be removed when the task is complete. Issue: #19

konard self-assigned this Dec 9, 2025

konard changed the title ~~[WIP] Add support for CLI that works in both like local command for AI agent to use and is able to be a server~~ feat: add CLI support for local command and server mode Dec 9, 2025

konard marked this pull request as ready for review December 9, 2025 05:02

chore: remove temporary task file

e56b7bb

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

konard marked this pull request as draft December 9, 2025 05:28

konard marked this pull request as ready for review December 9, 2025 05:33

konard marked this pull request as draft December 11, 2025 00:18

konard marked this pull request as ready for review December 11, 2025 00:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add CLI support for local command and server mode #20

feat: add CLI support for local command and server mode #20

Uh oh!

konard commented Dec 9, 2025 •

edited

Loading

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 11, 2025

Uh oh!

konard commented Dec 11, 2025

Uh oh!

konard commented Dec 11, 2025

Uh oh!

konard commented Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: add CLI support for local command and server mode #20

Are you sure you want to change the base?

feat: add CLI support for local command and server mode #20

Uh oh!

Conversation

konard commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Features

Implementation Details

New Files

Modified Files

Configuration System

.lenv File Format

CLI Usage

Server Mode

Capture Mode

All Options

Testing

Fixes

Uh oh!

konard commented Dec 9, 2025

🤖 Solution Draft Log

Uh oh!

konard commented Dec 9, 2025

🔄 Auto-restart 1/3

Uh oh!

konard commented Dec 9, 2025

🤖 Solution Draft Log

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

Uh oh!

konard commented Dec 9, 2025

🤖 Solution Draft Log

Uh oh!

konard commented Dec 11, 2025

Uh oh!

konard commented Dec 11, 2025

Uh oh!

konard commented Dec 11, 2025

✅ Updated to use new CLI command

Changes Made

Testing

Uh oh!

konard commented Dec 11, 2025

🤖 Solution Draft Log

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

konard commented Dec 9, 2025 •

edited

Loading