Napseer CLI

Source import for the nap operator CLI.

This repository is intended to become the canonical source for:

• nap installer and update UX.
• Project bootstrap and status commands.
• Local authenticated MCP wrapper launch/update behavior.
• Gateway lifecycle commands such as nap gateway setup, repair, start, status, logs, terminal, schedule, and vault.

Current state:

• resources/scripts/nap_install.py owns the versioned, verified, atomic runtime bundle installer.
• resources/scripts/ contains the public runtime source embedded by the backend without behavioral rewrites.
• resources/scripts/napseer_mcp_supervisor.py is the recommended Codex stdio entrypoint. It keeps the client transport alive while restarting or reloading the generated napseer_mcp_server.py worker between requests.
• Gateway service compatibility remains in the worker while the standalone gateway image is built from the public gateway repository.
• nap mcp status and nap doctor run a fresh stdio initialization, tools/list, and authenticated read probe. They deliberately report an existing client connection as not_observable; a successful fresh probe does not claim that a previously opened Codex transport is connected.
• nap auth login stores the shared account session in the user data folder (~/.local/share/napseer/credentials/default.json on Linux; platform user data directories on macOS/Windows). NAPSEER_USER_DATA_DIR overrides that location. nap auth login --project selects a repository override shared by its Git worktrees. Separate repositories retain separate overrides.
• Private state lives entirely in user data. credentials/ holds login grants; repositories/<id>/ holds the shared signing key; workspaces/<id>/ holds each worktree's selection, gateway identity, vault, index, locks, and logs. Git common-directory identity groups related worktrees; each worktree's Git directory identifies its runtime state, including after git worktree move. Nested project locators keep their own namespace. Ordinary directories use their canonical absolute path. Separate clones do not share project overrides.
• .napseer/project.json is the commit-safe project locator. It contains only the schema, API origin, project UUID, and slug; it never contains tokens, account or worker identity, encryption state, keys, passphrases, or claim links. A fresh clone uses it to attach the intended project.
• CLI terminal and schedule operations call the running gateway's loopback-only, CSRF-protected control API. PTYs therefore live in the daemon instead of disappearing when a CLI subprocess exits.

Backend discovery publishes the release manifest and exact public source revision used for each bundle.

For an existing checkout, stop older MCP clients and local gateway/UI processes, update the runtime, and run nap auth migrate once from that checkout. This moves private files out of .napseer, preserving the public locator and ignore file. Migration checks running gateway PIDs, copies and verifies every file before removing originals, and refuses conflicting destinations. An interrupted copy can be retried; it never selects a different login to hide a conflict. Restart clients afterward. Migrate existing worktrees individually; conflicting older credentials or signing keys must be reconciled explicitly, never overwritten.

NAPSEER_USER_DATA_DIR and explicit credential files must point outside the checkout. There is no credential or private-state symlink inside the repository.

Configure Codex and other long-lived stdio clients to launch:

python3 ~/.local/share/napseer/napseer_mcp_supervisor.py

For repositories that may be resumed after Codex opened a different working directory, add a trusted project .codex/config.toml override with both cwd and NAPSEER_PROJECT_ROOT. MCP processes inherit their launch directory; they cannot infer a later client workspace switch over stdio.

If NAPSEER_MCP_WORKER_PATH points to a stable launcher that loads a separate, replaceable runtime, set NAPSEER_MCP_WORKER_WATCH_PATHS to the os.pathsep-separated runtime paths. The supervisor then reloads the launcher after any watched runtime is atomically replaced, preserving the same bounded, non-replaying request lifecycle used for direct workers.

MCP admits at most 32 unfinished requests by default, including cancelled work that is still cleaning up. -32097 means a request was rejected before execution; retry after capacity is available. -32098 means the result is uncertain: inspect current state before retrying a mutation. Cancellation prevents queued mutations from starting and attempts to release acquired locks. It cannot undo a mutation already accepted by the API.

The supervisor waits up to 60 seconds for a response, then requests cancellation. After 10 seconds without a cleanup acknowledgement, it terminates the worker and fails affected requests without replay. Worker input writes have a five-second deadline. Override these limits with NAPSEER_MCP_RESPONSE_TIMEOUT_SECONDS, NAPSEER_MCP_CANCEL_GRACE_SECONDS, NAPSEER_MCP_WRITE_TIMEOUT_SECONDS, and NAPSEER_MCP_MAX_IN_FLIGHT_REQUESTS. New source loads only after unfinished work has drained. nap_contract exposes the runtime's request lifecycle contract. These process recovery guarantees require the supervisor; the direct worker is for isolated protocol debugging. An already-running older supervisor needs a client reconnect after updating.

The public operator surface is intentionally small:

nap init | status | doctor | auth | project | files | export | mcp | gateway | update | version | help

Authentication has one recovery verb: nap auth repair. Normal refresh is automatic. nap gateway repair creates the separate worker identity once; --replace is required to replace an existing identity.

Agents start only after the user configures an account login or a delegated API key. With an account login, nap init creates a project owned by that account. A committed .napseer/project.json always selects the existing project; it never causes a replacement to be created. Concurrent refreshes share a bounded credential lock, while project overrides remain independent. Network failures preserve credentials and offer recovery through nap auth repair.

nap auth keys --help describes scoped API key issuance; nap auth api-key --env VARIABLE_NAME installs a delegated key privately. Keys can expire or be revoked and cannot approve agent decisions. Use separate keys when agents need separate identities or permissions.

Upgrading from 0.2.x to 0.3.0 requires the current bootstrap once because old installers have a fixed list of runtime files. nap update on those versions rejects the new bundle before changing the active installation. Run:

curl -fsSL https://api.napseer.com/install | python3 -

The bootstrap verifies every asset and switches the runtime atomically without changing credentials or project locators. Restart existing MCP client sessions after this upgrade; subsequent releases use nap update normally.

In Bash, run commands as nap update, nap auth login, and so on. A leading ! is shell history expansion: !nap update replays the most recent command whose text starts with nap and appends update; it does not invoke an alternate Napseer update mode.

The direct wrapper remains the nap CLI implementation and an isolated protocol-debugging entrypoint.