@fidelizare/integrate

Interactive CLI that integrates the Fidelizare loyalty API into a management / POS codebase. It scans the project, finds where the register detects a scanned code, and proposes the integration as a reviewed diff, applied only after you confirm. Modeled on how mature setup wizards (PostHog) work: a deterministic harness around an optional coding agent, with strict permissions.

Run

# visual demo on a bundled sample POS (no key, nothing real touched)
npx fidelizare-integrate --demo

# on a real project (deterministic, works offline)
cd /path/to/soft-de-gestiune
npx fidelizare-integrate

# agentic mode: a real tool-use coding agent (Opus 4.8 via OpenRouter)
export OPENROUTER_API_KEY=sk-or-...
npx fidelizare-integrate --agent

Flags: --demo, --dir <path>, --agent, --model <id> (default anthropic/claude-opus-4.8), --yes, --no-anim.

Two modes

• Deterministic (default, no key): detect stack -> scan -> propose a helper + the call at the fidelity-card branch -> diff + confirm -> apply. Verified across Node, PHP, Python.
• Agentic (--agent, OpenRouter): a real tool-use loop (src/core/agent-loop.js) where the model autonomously calls list_files / read_file / grep / create_file / insert_code / check_syntax / finish. Every write is gated by an opencode-style permission harness (y / a=always / N), cwd-jailed, secret-redacted, .bak backups.

Tests

npm test runs the suite (node --test): integration across Node/PHP/Python (with node --check, php -l, python -m py_compile), vault redaction, and the cwd-jail. All green.

What it does

1. Hand-built ASCII intro + animations (logo sweep, codebase scan beam, spinners, progress) - all in src/ui/anim.js, zero animation libraries.
2. Takes the API key into a secret vault (src/core/vault.js): the raw key never enters a diff or the agent's context; it is written only to .env host-side.
3. Detects the stack (src/core/detect.js): C#/.NET, PHP, Delphi, Java, Python, Node.
4. Scans (src/core/scan.js) for the safest integration point: where a scanned code is handled / the sale is finalized / a fidelity card is detected.
5. Proposes a minimal change (src/core/propose.js, or agent.js with Opus): a helper file + the acumuleazaPuncte(codCard, items, total) call inserted exactly at the card-detection branch + the import.
6. Renders a colored diff, checks git state, asks to confirm.
7. Applies safely (src/core/apply.js): cwd-jailed, read-before-write, .bak backups, writes .env.

Safety (what it can and cannot do)

• Only edits files inside the target project (cwd jail; refuses paths outside).
• Read-before-write; .bak backup per edited file; warns if git is dirty / not a repo.
• The API key is never written into source (verified) - only into .env.
• The generated helper catches API errors so a failed call never blocks a sale.
• Nothing is written until you confirm; node --check on the result passes (no broken code).

Verified

node src/cli.js --demo --no-anim --yes produces: a fidelizare.js helper, the call inserted in the isCardFidelitate branch of pos.js, the import added, .env with the key (absent from source), both files pass node --check, and the integrated POS runs end to end with a graceful API failure.