added prompt to shell.getpassword thatwill not be redirected

doc/api/password.md

@@ -1,17 +1,21 @@
-### Password Agent
+## Password Cache
 
-The password agent controls a single password, and also coordinates any number of
-shell processes interested in that password.
+### Password Sharing in Site Configurations
 
-Internally, a shell automatically creates a password agent if none is
-provided. We can access such an agent and pass it on to new shells:
+A shell always creates its own internal password agent that talks
+to a password cache. By default the shell also creates its own password
+cache to handle a single login scenario. But the shell may use a shared
+password cache to participate in multiple login scenarios.
 
+Here we use the default cache of one shell named `host1` and passes it
+on to another shell named `host2`.
 
     shell = require('ploy').shell
-    host1 = shell('host1.example.com');
-    host2 = shell({ host: 'example.com', passwordCache: host.passwordCache });
+    var host1 = shell('host1.example.com');
+    var host2 = shell({ host: 'example.com', passwordCache: host1.passwordCache });
 
-or we can create an agent explicitly:
+We can also create a cache explicitly and pass it on to both hosts
+with equal effect:
 
     ploy = require('ploy');
     shell = ploy.shell
@@ -20,12 +24,6 @@ or we can create an agent explicitly:
     host1 = shell({ host: 'host1.example.com', passwordCache: pwc);
     host2 = shell({ host: 'host2.example.com', passwordCache: pwc);
 
-The explicit way can be useful in conjunction with the sites collection
-to set up a shared passwordCache property for multiple sites. See also
-`lib/password.coffee` if a custom password agent is needed - the interface
-is fairly simple.
-
 The hosts will in either case be sharing a password cache so the first `sudo`
 prompt will block all other prompts and have the shell wait for the first
 prompt to provide the answers.
-

doc/api/shell.md

@@ -213,9 +213,15 @@ the user unless the password is incorrect.
 
 Clears the password cache.
 
-### shell.promptPassword([callback(err)])
+### shell.promptPassword(prompt, [callback(err)])
 
-Prompts the user for a password without echoing the text to the
+`prompt`: optional string to display to the user, defaults to nothing,
+otherwise write prompt to `process.stdout`, also when shell output has
+been redirected.
+
+Waits for user input unless the password cache already has the password,
+or waits for another prompt if the cache says one is active.
+Prompts the user for a password without echoing the input text to the
 console. Callback makes it possible to wait for the user to complete
 the password entry. Issues the error string 'SIGINT' if the user types
 'Ctrl+C' and should normally be used to issue a

lib/password.coffee

@@ -93,7 +93,10 @@ class PasswordAgent
   setPassword: (pw) ->
     @cache.set(pw)
     @_log "setting password"
-  getPassword: (cb = ->) ->
+  getPassword: (prompt, cb = ->) ->
+    if typeof prompt == 'function'
+      cb = prompt
+      prompt = null
     @attempts++
     pw = @cache.get()
     if @attempts == 1 and pw
@@ -111,6 +114,8 @@ class PasswordAgent
           @setPassword pw unless err
           cb err, pw
         @cache.setPending(true)
+        if prompt
+          process.stdout.write prompt
         readSilentLine _cb
 
 helpers = {}

lib/shell.coffee

@@ -170,8 +170,8 @@ class Shell
 
   # prompt user for password to preload password cache
   # not strictly needed, but may be more userfriendly
-  promptPassword: (cb) ->
-    password.agent(@passwordCache).getPassword(cb)
+  promptPassword: (prompt, cb) ->
+    password.agent(@passwordCache).getPassword(prompt, cb)
 
   # like prompt password, but programmatically set password
   setPassword: (password) ->