Conversation
Restores three CLI surfaces the e2e shell suites need:
(1) Top-level `sphere init` / `sphere status` / `sphere clear`
Pre-extraction, the in-tree sphere-sdk CLI exposed `init`,
`status`, `clear` as bare top-level commands. Phase 1 of the
extraction landed `wallet init` / `wallet status` / `wallet
clear` (legacy bridges) but dropped the unprefixed top-level
aliases, breaking every shell test that drove `sphere init
--profile --network testnet`. Re-adds them as legacy bridges
that map back to the same legacy switch/case so wire shape is
unchanged.
(2) Native `sphere pointer` namespace
The aggregator-pointer layer is implemented in sphere-sdk's
profile module (since the pointer-layer release). The in-tree
CLI never exposed it; tests have driven `sphere pointer
flush / status / recover` against a TODO surface that now
lands. Three subcommands:
sphere pointer status Reachable / Blocked / Probe FP
+ latest valid version
sphere pointer flush payments.sync() round-trip
(save → CAR pin → bundle ref →
pointer publish)
sphere pointer recover recoverLatest() — prints either
"Recovered v=N cid=…" or "No
pointer anchor published yet"
Native (not a legacy bridge) — implemented directly against
the SDK's ProfilePointerLayer methods.
SDK compatibility: the profile module ships in sphere-sdk
versions that include the pointer-layer work. To let this CLI
merge against older SDK releases, `pointer/sphere-init.ts`
runtime-imports `@unicitylabs/sphere-sdk/profile/node` via
dynamic `import()`. When the SDK predates that subpath,
pointer commands exit with code 2 and a precise diagnostic
("installed sphere-sdk does not export profile/node — upgrade
to a version that ships the Profile/aggregator-pointer
module"). The CLI typechecks against the older SDK; pointer
commands start working as soon as the SDK upgrade lands —
no second CLI release required.
New runtime dep: `multiformats` (^14) for the CID
decode in `pointer recover`. The SDK already pulls this in;
listing it explicitly in the CLI keeps the build hermetic if
a future SDK version drops the transitive.
(3) Non-TTY mnemonic emission opt-in
Legacy `init` suppresses the 24/12-word mnemonic on a
non-TTY stdout (security: prevents accidental persistence in
logs / CI). E2E harnesses that need to chain
init→recover-from-mnemonic across scripts blocked on this.
Adds `SPHERE_ALLOW_MNEMONIC_NON_TTY=1` opt-in: when set, emit
the mnemonic to stdout as a single line (so harness greps
match cleanly) plus a stderr note. Verbose name by design —
this is a footgun for production users and tests opt in
explicitly.
End-to-end verified against sphere-sdk's tests/e2e/pointer-N1.sh
on a local Docker relay + faucet stack:
PASS: pointer-N1 (5/5 assertions)
✓ init creates Profile-mode wallet, mnemonic captured
✓ pointer flush succeeds (publishes anchor)
✓ pointer status: reachable=yes
✓ pointer status: blocked=no
✓ pointer status: probe fingerprint present
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restores three CLI surfaces the sphere-sdk e2e shell suites need but
the
@unicity-sphere/cliextraction dropped:init/status/clear— legacy bridges added back soscripts driving
sphere init --profile --network testnet,sphere status,sphere clearkeep working. Thewallet initbridge stays — these are aliases.
sphere pointernamespace —status/flush/recoverfor the aggregator-pointer layer. Implemented directly against
ProfilePointerLayermethods on the SDK.SPHERE_ALLOW_MNEMONIC_NON_TTY=1— opt-in for the legacyinitcommand to emit the mnemonic on a non-TTY stdout, so e2e harnesses
that need to chain init→recover-from-mnemonic across scripts can
capture it.
Verified end-to-end against
sphere-sdk/tests/e2e/pointer-N1.shon alocal Docker Nostr relay + js-faucet stack —
PASS: pointer-N1with5/5 assertions.
Compatibility
pointer-commands.tsruntime-imports@unicitylabs/sphere-sdk/profile/nodevia dynamicimport(). When theinstalled SDK predates the Profile-module release,
pointer status/
flush/recoverexit with code 2 and a precise diagnostic("installed sphere-sdk does not export profile/node — upgrade to a
version that ships the Profile/aggregator-pointer module"). The CLI
typechecks against the older SDK; pointer commands start working
automatically as soon as the SDK upgrade lands.
init/status/clearare pure legacy bridges and start workingon day one against any SDK that has those legacy commands (i.e. every
SDK predating the legacy strip-out).
New dependency
multiformats@^14— used for the CID decode inpointer recover.The SDK already pulls this in transitively; listing it explicitly in
the CLI keeps the build hermetic against a future SDK that drops the
transitive.
Test plan
npm run typecheckclean against released SDK (no profile module).npm run typecheckclean against pointer-aware SDK(uxf branch with profile/node export).
npm run buildclean.sphere init --help,sphere pointer --help,sphere pointer status/flush/recover --helpall showcommand-specific Usage lines (the e2e
cli_supports_commandprobe matches them).+ faucet — PASS (5/5 assertions, 14s wall-clock).
Related
sphere-sdk's
tests/e2e/lib/resolve-cli.shalready searches theworktree paths (
sphere-cli-work/sphere-cli/bin/sphere.mjs) andprobes
<cli> <subcommand> --helpfor the commands this PR adds —no further coordination needed on that side.