@nuanu-ai/magicpay-home

Shared home directory and state contract for the MagicPay CLI family.

This package owns the MagicPay home directory: the on-disk home where MagicPay's CLIs keep their config, browser-session pointer, workflow state, and related files. It is not a CLI of its own — it is consumed as a dependency by:

• @nuanu-ai/magicbrowse-cli — browser-only CLI; uses the shared MagicPay gateway config
• @nuanu-ai/magicpay-cli — protected-form fills

Do I Need To Install This?

No. This package is pulled in automatically as a dependency of the CLIs above. You do not need to install or configure it directly.

Why This Package Exists

Each MagicPay CLI needs one place on disk for the shared API key, the current workflow state, the browser-session pointer, mock-mode files, and update-check state. Putting all of that under one named directory keeps configuration, debugging, and reset operations predictable across the whole CLI family.

magicpay-home is the owner of the MagicPay home and of the typed helpers the other packages call to read and write files there:

1. Defines the MagicPay home directory as ~/.magicpay/ by default, or as MAGICPAY_HOME when that environment variable is set.
2. Provides typed helpers for the MagicPay-specific files (config.json, workflow-state.json, browser-session.json, update-state.json, mock files).
3. Lets the CLIs share state across separate processes safely (atomic writes, single-workflow lock).

The browser library @nuanu-ai/magicbrowse keeps its own runtime diagnostics under MAGICBROWSE_HOME (default ~/.magicbrowse/) — current-session.json, runs/<runId>.json, run-index.json, named profiles. Those files are separate from the MagicPay home and are not redirected today. See @nuanu-ai/magicbrowse for that layout.

Directory Layout

All paths are relative to the active MagicPay home. By default this is ~/.magicpay/ (or the OS equivalent of homedir() + "/.magicpay/"). For isolated tests or parallel workflows, set MAGICPAY_HOME to a distinct directory:

MAGICPAY_HOME=/tmp/magicpay-test magicpay status

MAGICPAY_HOME is the MagicPay home root itself. With the value above, config.json is written to /tmp/magicpay-test/config.json, not to /tmp/magicpay-test/.magicpay/config.json.

All files in this table are owned and written by magicpay-home itself (or by CLIs through magicpay-home helpers). The browser library's own diagnostics live separately under MAGICBROWSE_HOME (see note above).

Session-lane selection is also owned here: resolveMagicPaySessionScope implements the shared precedence (--session > MAGICPAY_SESSION > the only live lane > legacy singleton) that magicpay-cli, magicsearch-cli, and the magicbrowse-cli timeline reporter all use, so every CLI in the family reads and writes the same lane for a given session.

| Path | Purpose | Written by | | --- | --- | --- | | config.json | Shared config: named MagicPay profiles (apiKey, apiUrl), browser defaults (profile, headless, proxy), updates policy. | init on any CLI. | | sessions/<sessionId>/ | Per-session lane holding that session's workflow-state.json and browser-session.json. Allocated by start-session, removed when the session ends and its browser closes. Enables parallel sessions with no shared mutable state. | magicpay-cli. | | browser-session.json | Legacy singleton browser pointer, used only by pre-lane state and unscoped flows. | magicpay-cli. | | workflow-state.json | Workflow state for the active scope. A session lane stores value-free request continuation metadata (requestId, poller, optional plan/capability/base URL), never the hosted approval URL or request values. The legacy root file seeds new sessions. | magicpay-cli only. | | update-state.json | Last CLI update-check timestamp and cached result. | Any CLI that runs the update check. | | profiles/ | Reserved directory for named browser-Memory data when a CLI chooses to root profiles under MagicPay home. | Currently unused by the live CLI set; reserved path. | | runs/ | Per-run telemetry and files captured by MagicPay CLIs. | Any MagicPay CLI run that records run telemetry. |

Rules of thumb when debugging:

• Safe to delete to reset auth: config.json. The next init re-creates it.
• Safe to delete to reset the browser session: browser-session.json. Next launch / attach starts fresh.
• Safe to delete to reset an active workflow: the session's directory under sessions/ (or magicpay reset-session --session <id>). Any active magicpay session in that lane is lost; the next start-session begins clean. The root workflow-state.json only seeds new sessions and is also safe to delete.
• Do not hand-edit any of these files — they are managed by the CLIs and may be rewritten at any moment.

What The Package Provides

• Typed helpers for reading and writing config.json (readMagicPayConfig, writeMagicPayConfig, doctorMagicPayConfig).
• One active named environment contract shared by the CLI family, so every CLI resolves the same API profile. Hosted links always point at the production web app; the backend owns that origin.
• Path helpers for every file and directory above (getMagicPayHomeDir, getMagicPayConfigPath, getMagicPayBrowserSessionPath, etc.).
• Workflow-state helpers for the active protected-form session (loadWorkflowContext, saveWorkflowContext, clearWorkflowState).
• Request-continuation helpers that keep exact session-scoped poll and resume commands recoverable across CLI processes without persisting hosted-link bearer tokens or protected request values.
• One value-free agent request-handoff builder shared by MagicPay and MagicSearch, including polling bounds and API-authoritative OTP guidance.
• Browser-session helpers (loadMagicPayBrowserSession, saveMagicPayBrowserSession, deleteMagicPayBrowserSession) for the CDP endpoint pointer that magicpay-cli persists across processes.
• CLI update-check helper (checkForPackageUpdate) with state persisted in update-state.json.
• Safe concurrent writes so several MagicPay CLIs can run in the same process or side-by-side without corrupting shared files.

License

MIT