feat: prototype CTA XP report automation flow

[lustsazeus-lab]

Summary

This PR adds a testable prototype for the call-to-action flow requested in #196:

• validates GitHub repository input (owner/repo or URL)
• enforces one free report per organization guardrail
• builds signed dispatch payloads (HMAC-SHA256) for secure workflow triggering
• formats deterministic report links + email copy for delayed delivery UX

What was added

• cta-xp-report/src/ctaReportService.js
  • normalizeRepository
  • canRunFreeReport / recordFreeReportRun
  • signDispatchPayload
  • buildReportLink
  • composeEmail
• cta-xp-report/test/ctaReportService.test.js
  • 4 tests covering parsing, one-org guardrail, signature determinism, and output shaping
• cta-xp-report/README.md
  • integration flow for landing page → dispatch → report/email delivery
• root README.MD updated with prototype entry

Validation

cd cta-xp-report
npm test

All tests pass (4/4).

Notes

• Designed to be dependency-free and easy to transplant into a Deno/Next API route.
• InMemoryKvStore is intentionally simple; production wiring should use Deno KV/Redis.

Closes #196

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 87d1ca9a61

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Enforce free-run guardrail with atomic reservation

The one-free-report gate can be bypassed under concurrent requests because eligibility (canRunFreeReport) and persistence (recordFreeReportRun) are split into separate operations: two requests for the same owner can both see no record and both proceed before either write lands. In the integration flow described in this commit (check, then dispatch, then store), this allows duplicate free runs for one org; use a transactional check-and-set (or reserve the key before dispatch) to close the race.

Useful? React with 👍 / 👎.

[nagiexplorer88]

The one-free-report-per-org guard is still race-prone in the current API shape.

canRunFreeReport() does a separate kv.get(key) check, and recordFreeReportRun() later does the kv.set(key, value). If two requests for the same org arrive at nearly the same time, both can observe no existing record, both dispatch the workflow, and then both record a run. That violates the Safety requirement in #196 that this should only work once per organization.

For the intended Deno KV integration, this should probably be a single atomic check-and-set operation, for example using a versionstamp check on the org key before dispatching. The service API could expose one claimFreeReportRun(...) function that atomically creates the org-level claim and only then allows the workflow dispatch, instead of requiring callers to remember to sequence separate read/write helpers safely.