@mercuryo-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:

• @mercuryo-ai/magicbrowse-cli — browser-only CLI; uses the shared MagicPay gateway config
• @mercuryo-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 @mercuryo-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 @mercuryo-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).

| Path | Purpose | Written by | | --- | --- | --- | | config.json | Shared config: MagicPay gateway (apiKey, apiUrl), browser defaults (profile, headless, proxy), updates policy. | init on any CLI. | | browser-session.json | CDP endpoint and browser-session pointer the payment-side CLI uses to remember an attach across processes. | magicpay-cli. | | workflow-state.json | In-flight product workflow state (Memory snapshot and current step). | 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: workflow-state.json. Any active magicpay session is lost; the next start-session begins clean.
• 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).
• Path helpers for every file and directory above (getMagicPayHomeDir, getMagicPayConfigPath, getMagicPayBrowserSessionPath, etc.).
• Workflow-state helpers for the active protected-form session (loadWorkflowContext, saveWorkflowContext, clearWorkflowState).
• 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