fix: improve sf nodes ssh documentation and specification

[sigmachirality]

Update SSH command examples to consistently include a user prefix and remove redundant examples.

Previously, some SSH examples omitted the username prefix, which could lead to confusion about the default user or encourage behavior inconsistent with best practices. This change ensures all examples explicitly show root@ (or <account>@) for clarity and consistency with documentation.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
src/lib/nodes/ssh.ts	34% smaller
src/lib/nodes/index.ts	0% smaller
src/lib/vm/list.ts	0% smaller
src/lib/vm/ssh.ts	0% smaller

[greptile-apps]

Greptile Summary

This PR updates SSH command examples to consistently include username prefixes (root@ or jenson@) across help text and documentation. The intent is to improve clarity on how to properly use SSH commands.

However, the changes introduce a documentation-code mismatch: while all examples now show a username as required, the actual implementation still supports optional usernames (lines 54-56 in ssh.ts allow single-part destinations without a username). This misleads users into thinking the username prefix is mandatory when it's actually optional.

Confidence Score: 2/5

• This PR has logic issues that create misleading documentation and potential user confusion.
• The PR addresses a valid goal (consistency in examples) but creates a documentation-code mismatch. The examples now suggest usernames are required, while the code explicitly handles the case where no username is provided (see lines 54-56). This gap between documentation and implementation can confuse users and goes against best practices of keeping examples aligned with actual supported behavior. The code won't break, but users may unnecessarily struggle or believe features aren't available.
• Both src/lib/nodes/ssh.ts and src/lib/nodes/index.ts need attention to ensure examples accurately reflect all supported usage patterns, particularly that usernames are optional.

Important Files Changed

Filename	Overview
src/lib/nodes/ssh.ts	Updated SSH examples to always include username prefix (root@ or jenson@). However, this creates a misleading documentation where examples show the username as required, while the code logic at lines 54-56 still allows SSH calls without a username prefix. Users following only the examples won't know that sf nodes ssh my-node is still valid.
src/lib/nodes/index.ts	Updated help text examples to include root@ prefix for consistency with ssh.ts. Same issue as ssh.ts: examples now suggest username is required when the code still supports optional usernames (lines 74, 80).

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as sf nodes ssh
    participant Parser as Destination Parser
    participant API as Node/VM API
    participant SSH as SSH Client

    User->>CLI: sf nodes ssh [root@]my-node
    CLI->>Parser: Split destination by '@'
    
    alt Username provided
        Parser->>Parser: username = first part
        Parser->>Parser: nodeOrVmId = second part
    else No username provided
        Parser->>Parser: username = undefined
        Parser->>Parser: nodeOrVmId = full destination
    end
    
    Parser->>API: Fetch VM details (nodeOrVmId)
    API-->>Parser: SSH hostname, port, host keys
    
    Parser->>Parser: Build SSH destination
    alt If username defined
        Parser->>Parser: sshDestination = username@hostname:port
    else No username
        Parser->>Parser: sshDestination = hostname:port
    end
    
    Parser->>SSH: Execute ssh command
    SSH-->>User: SSH session established

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}