[Refactor] Implement --serve flag and HTTP server endpoints

[github-actions[bot]]

Context

The current src/lib/main.js only logs the provided arguments and does not implement any CLI functionality. We need to transition from this placeholder behavior to a real HTTP server feature as defined in features/HTTP_SERVER.md.

Changes Required

1. Argument Parsing

   • Implement parseArgs(args: string[]): Record<string, boolean> that recognizes at least the --serve flag.
   • When --serve is provided, subsequent behavior should start the HTTP server.

2. HTTP Server Implementation

   • Add and export a function startHttpServer(options: Record<string, boolean>, port = process.env.PORT || 3000): http.Server in src/lib/main.js using Node's built-in http module:
     • GET /health → respond 200 OK with JSON { "status": "ok" }.
     • GET /options → respond 200 OK with a JSON object of the parsed CLI options.
     • Any other path → respond 404 Not Found with JSON { "error": "Not Found" }.
     • Set Content-Type: application/json on all responses.
     • Log Server listening on port <port> once the server starts.
   • Update main(args) to detect --serve and call startHttpServer(parsedOptions); ensure the process remains alive while the server runs.

3. Unit Tests

   • In tests/unit/main.test.js, add tests to verify:
     1. startHttpServer returns an instance of http.Server and logs the listening port.
     2. HTTP endpoints behavior using Vitest and Node's http.get or similar:
        • /health → status 200, application/json, body { "status": "ok" }.
        • /options → status 200, JSON body matching the parsed options object.
        • Unknown path → status 404, body { "error": "Not Found" }.

4. Documentation Updates

   • In README.md, add an HTTP Server section under Usage:

     ## HTTP Server
     To start the server:  
     ```bash
     npm run serve

     • Default port: 3000 (override with PORT environment variable).
     • Endpoints:

       curl http://localhost:3000/health    # { "status": "ok" }
       curl http://localhost:3000/options   # { /* parsed options */ }

Acceptance Criteria

• [ ] parseArgs returns { serve: true } when called with ['--serve'].
• [ ] startHttpServer returns an http.Server instance and logs Server listening on port 3000 (or custom port).
• [ ] GET /health returns 200 and JSON { "status": "ok" }.
• [ ] GET /options returns 200 and JSON matching parsed options.
• [ ] GET unknown path returns 404 and JSON { "error": "Not Found" }.
• [ ] All new and existing tests pass with npm test.
• [ ] README includes the HTTP Server usage section with working curl examples.

[github-actions[bot]]

Workflow name: flow-maintenance-activity-to-issue Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294357636 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/21ebbf2ef3563eb8c4050d7619c2205cfcfe75c9

[github-actions[bot]]

This issue has been reviewed and marked as 'ready'. The description has been updated with testable acceptance criteria, and relevant library documents ([], 0 in total) have been added as comments.

[github-actions[bot]]

Workflow name: flow-maintenance-activity-to-issue Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294357636 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/c99686dc2b315531a88426b01b899b629046cbc7

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294410989 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/c99686dc2b315531a88426b01b899b629046cbc7

[github-actions[bot]]

Workflow name: flow-maintenance-activity-to-issue Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294357636 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/c99686dc2b315531a88426b01b899b629046cbc7

[github-actions[bot]]

Workflow name: ci-publish-web Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294490701 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/c99686dc2b315531a88426b01b899b629046cbc7

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294636265 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/c99686dc2b315531a88426b01b899b629046cbc7

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15294659084 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/c99686dc2b315531a88426b01b899b629046cbc7

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295194188 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/8dace580345a71953142a52f7db8c93d6ca9b402

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295330247 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295398537 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295427695 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295508920 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295659271 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-update-readme Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295766962 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295896891 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15295918054 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15296450572 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0033d7e1bb720e6586f79140aa9be2a38b9cd29f

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15296592671 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15296633096 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15296659092 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15296895451 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15297120557 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15297143252 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15297673685 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/f4e9c59b27c1c8516834f157808f59eb73545a68

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15297804300 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15297861653 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15297886661 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15298116516 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15298313045 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15298334212 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15298812361 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/986d82b86f88a5549ffe4f200a2ea4cf3fcd42ca

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15298929340 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/e8dcef13992ca7f1eb800cc56afea2f10a5fc832

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15298947443 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/e8dcef13992ca7f1eb800cc56afea2f10a5fc832

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15299204692 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/e8dcef13992ca7f1eb800cc56afea2f10a5fc832

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15299443650 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/e8dcef13992ca7f1eb800cc56afea2f10a5fc832

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15299464102 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/e8dcef13992ca7f1eb800cc56afea2f10a5fc832

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300024679 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/0ac81eab7ae39e365efdd31a7b26badcd5fe874c

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300161243 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300229534 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300264466 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300412080 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300694089 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300891667 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15300918031 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15301330951 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/58fd770517bfe133780ee4abbdac142e3e1f58e0

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15301458583 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/41a0605d3e5a0efb69e66db0d2f5a3c6781577a5

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15301512835 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/41a0605d3e5a0efb69e66db0d2f5a3c6781577a5

[github-actions[bot]]

Workflow name: flow-publish-stats Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15301547310 Workflow event: workflow_run Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/41a0605d3e5a0efb69e66db0d2f5a3c6781577a5

[github-actions[bot]]

Workflow name: transformation-06-issue-to-code Workflow run URL: https://github.com/xn-intenton-z2a/repository0/actions/runs/15301813853 Workflow event: schedule Workflow inputs: null HEAD of main URL: https://github.com/xn-intenton-z2a/repository0/commit/41a0605d3e5a0efb69e66db0d2f5a3c6781577a5