func newAPIConnectionFromNames(
	c *gc.C,
	controller, account, model string,
	store jujuclient.ClientStore,
	apiOpen api.OpenFunc,
	getBootstrapConfig func(string) (*config.Config, error),
) (api.Connection, error) {
	params := juju.NewAPIConnectionParams{
		Store:           store,
		ControllerName:  controller,
		BootstrapConfig: getBootstrapConfig,
		DialOpts:        api.DefaultDialOpts(),
	}
	if account != "" {
		accountDetails, err := store.AccountByName(controller, account)
		c.Assert(err, jc.ErrorIsNil)
		params.AccountDetails = accountDetails
	}
	if model != "" {
		modelDetails, err := store.ModelByName(controller, account, model)
		c.Assert(err, jc.ErrorIsNil)
		params.ModelUUID = modelDetails.ModelUUID
	}
	return juju.NewAPIFromStore(params, apiOpen)
}

func (c *logoutCommand) logout(store jujuclient.ClientStore, controllerName string) error {
	accountDetails, err := store.AccountDetails(controllerName)
	if errors.IsNotFound(err) {
		// Not logged in; nothing else to do.
		return nil
	} else if err != nil {
		return errors.Trace(err)
	}

	// We first ensure that the user has a macaroon, which implies
	// they know their password. If they have just bootstrapped,
	// they will have a randomly generated password which they will
	// be unaware of.
	if accountDetails.Password != "" && !c.Force {
		return errors.New(`preventing account loss

It appears that you have not changed the password for
your account. If this is the case, change the password
first before logging out, so that you can log in again
afterwards. To change your password, run the command
"juju change-user-password".

If you are sure you want to log out, and it is safe to
clear the credentials from the client, then you can run
this command again with the "--force" flag.
`)
	}

	// Remove the account credentials.
	if err := store.RemoveAccount(controllerName); err != nil {
		return errors.Annotate(err, "failed to clear credentials")
	}
	return nil
}

// decorateAndWriteInfo decorates the info struct with information
// from the given cfg, and the writes that out to the filesystem.
func decorateAndWriteInfo(
	store jujuclient.ClientStore,
	details prepareDetails,
	controllerName, modelName string,
) error {
	qualifiedModelName := jujuclient.JoinOwnerModelName(
		names.NewUserTag(details.AccountDetails.User),
		modelName,
	)
	if err := store.AddController(controllerName, details.ControllerDetails); err != nil {
		return errors.Trace(err)
	}
	if err := store.UpdateBootstrapConfig(controllerName, details.BootstrapConfig); err != nil {
		return errors.Trace(err)
	}
	if err := store.UpdateAccount(controllerName, details.AccountDetails); err != nil {
		return errors.Trace(err)
	}
	if err := store.UpdateModel(controllerName, qualifiedModelName, details.ModelDetails); err != nil {
		return errors.Trace(err)
	}
	if err := store.SetCurrentModel(controllerName, qualifiedModelName); err != nil {
		return errors.Trace(err)
	}
	return nil
}

func (c *registerCommand) promptControllerName(store jujuclient.ClientStore, suggestedName string, stderr io.Writer, stdin io.Reader) (string, error) {
	_, err := store.ControllerByName(suggestedName)
	if err == nil {
		fmt.Fprintf(stderr, errControllerConflicts, suggestedName)
		suggestedName = ""
	}
	var setMsg string
	setMsg = "Enter a name for this controller: "
	if suggestedName != "" {
		setMsg = fmt.Sprintf("Enter a name for this controller [%s]: ",
			suggestedName)
	}
	fmt.Fprintf(stderr, setMsg)
	defer stderr.Write([]byte{'\n'})
	name, err := c.readLine(stdin)
	if err != nil {
		return "", errors.Trace(err)
	}
	name = strings.TrimSpace(name)
	if name == "" && suggestedName == "" {
		return "", errors.NewNotValid(nil, "you must specify a non-empty controller name")
	}
	if name == "" && suggestedName != "" {
		return suggestedName, nil
	}
	return name, nil
}

func (c *registerCommand) promptControllerName(store jujuclient.ClientStore, suggestedName string, stderr io.Writer, stdin io.Reader) (string, error) {
	if suggestedName != "" {
		if _, err := store.ControllerByName(suggestedName); err == nil {
			suggestedName = ""
		}
	}
	for {
		var setMsg string
		setMsg = "Enter a name for this controller: "
		if suggestedName != "" {
			setMsg = fmt.Sprintf("Enter a name for this controller [%s]: ", suggestedName)
		}
		fmt.Fprintf(stderr, setMsg)
		name, err := c.readLine(stdin)
		if err != nil {
			return "", errors.Trace(err)
		}
		name = strings.TrimSpace(name)
		if name == "" {
			if suggestedName == "" {
				fmt.Fprintln(stderr, "You must specify a non-empty controller name.")
				continue
			}
			name = suggestedName
		}
		_, err = store.ControllerByName(name)
		if err == nil {
			fmt.Fprintf(stderr, "Controller %q already exists.\n", name)
			continue
		}
		return name, nil
	}
}

// NewAPIRoot returns a new connection to the API server for the given
// model or controller.
func (c *JujuCommandBase) NewAPIRoot(
	store jujuclient.ClientStore,
	controllerName, modelName string,
) (api.Connection, error) {
	accountDetails, err := store.AccountDetails(controllerName)
	if err != nil && !errors.IsNotFound(err) {
		return nil, errors.Trace(err)
	}
	// If there are no account details or there's no logged-in
	// user or the user is external, then trigger macaroon authentication
	// by using an empty AccountDetails.
	if accountDetails == nil || accountDetails.User == "" {
		accountDetails = &jujuclient.AccountDetails{}
	} else {
		u := names.NewUserTag(accountDetails.User)
		if !u.IsLocal() {
			accountDetails = &jujuclient.AccountDetails{}
		}
	}
	param, err := c.NewAPIConnectionParams(
		store, controllerName, modelName, accountDetails,
	)
	if err != nil {
		return nil, errors.Trace(err)
	}
	conn, err := juju.NewAPIConnection(param)
	if modelName != "" && params.ErrCode(err) == params.CodeModelNotFound {
		return nil, c.missingModelError(store, controllerName, modelName)
	}
	return conn, err
}

// RefreshModels refreshes the local models cache for the current user
// on the specified controller.
func (c *JujuCommandBase) RefreshModels(store jujuclient.ClientStore, controllerName string) error {
	modelManager, err := c.modelAPI(store, controllerName)
	if err != nil {
		return errors.Trace(err)
	}
	defer modelManager.Close()

	accountDetails, err := store.AccountDetails(controllerName)
	if err != nil {
		return errors.Trace(err)
	}

	models, err := modelManager.ListModels(accountDetails.User)
	if err != nil {
		return errors.Trace(err)
	}
	for _, model := range models {
		modelDetails := jujuclient.ModelDetails{model.UUID}
		owner := names.NewUserTag(model.Owner)
		modelName := jujuclient.JoinOwnerModelName(owner, model.Name)
		if err := store.UpdateModel(controllerName, modelName, modelDetails); err != nil {
			return errors.Trace(err)
		}
	}
	return nil
}

func translateControllerError(store jujuclient.ClientStore, err error) error {
	if !errors.IsNotFound(err) {
		return err
	}
	controllers, err2 := store.AllControllers()
	if err2 != nil {
		return err2
	}
	if len(controllers) == 0 {
		return errors.Wrap(err, ErrNoControllersDefined)
	}
	return errors.Wrap(err, ErrNoCurrentController)
}

func (c *registerCommand) maybeSetCurrentModel(ctx *cmd.Context, store jujuclient.ClientStore, controllerName, userName string, models []base.UserModel) error {
	if len(models) == 0 {
		fmt.Fprintf(ctx.Stderr, "\n%s\n\n", errNoModels.Error())
		return nil
	}

	// If we get to here, there is at least one model.
	if len(models) == 1 {
		// There is exactly one model shared,
		// so set it as the current model.
		model := models[0]
		owner := names.NewUserTag(model.Owner)
		modelName := jujuclient.JoinOwnerModelName(owner, model.Name)
		err := store.SetCurrentModel(controllerName, modelName)
		if err != nil {
			return errors.Trace(err)
		}
		fmt.Fprintf(ctx.Stderr, "\nCurrent model set to %q.\n\n", modelName)
	} else {
		fmt.Fprintf(ctx.Stderr, `
There are %d models available. Use "juju switch" to select
one of them:
`, len(models))
		user := names.NewUserTag(userName)
		ownerModelNames := make(set.Strings)
		otherModelNames := make(set.Strings)
		for _, model := range models {
			if model.Owner == userName {
				ownerModelNames.Add(model.Name)
				continue
			}
			owner := names.NewUserTag(model.Owner)
			modelName := common.OwnerQualifiedModelName(model.Name, owner, user)
			otherModelNames.Add(modelName)
		}
		for _, modelName := range ownerModelNames.SortedValues() {
			fmt.Fprintf(ctx.Stderr, "  - juju switch %s\n", modelName)
		}
		for _, modelName := range otherModelNames.SortedValues() {
			fmt.Fprintf(ctx.Stderr, "  - juju switch %s\n", modelName)
		}
		fmt.Fprintln(ctx.Stderr)
	}
	return nil
}

// updateController prompts for a controller name and updates the
// controller and account details in the given client store.
// It returns the name of the updated controller.
func (c *registerCommand) updateController(
	ctx *cmd.Context,
	store jujuclient.ClientStore,
	defaultControllerName string,
	controllerDetails jujuclient.ControllerDetails,
	accountDetails jujuclient.AccountDetails,
) (string, error) {
	// Check that the same controller isn't already stored, so that we
	// can avoid needlessly asking for a controller name in that case.
	all, err := store.AllControllers()
	if err != nil {
		return "", errors.Trace(err)
	}
	for name, ctl := range all {
		if ctl.ControllerUUID == controllerDetails.ControllerUUID {
			// TODO(rogpeppe) lp#1614010 Succeed but override the account details in this case?
			return "", errors.Errorf("controller is already registered as %q", name)
		}
	}
	controllerName, err := c.promptControllerName(store, defaultControllerName, ctx.Stderr, ctx.Stdin)
	if err != nil {
		return "", errors.Trace(err)
	}

	if err := store.AddController(controllerName, controllerDetails); err != nil {
		return "", errors.Trace(err)
	}
	if err := store.UpdateAccount(controllerName, accountDetails); err != nil {
		return "", errors.Annotatef(err, "cannot update account information: %v", err)
	}
	return controllerName, nil
}

func newAPIConnectionParams(
	store jujuclient.ClientStore,
	controllerName,
	modelName string,
	accountDetails *jujuclient.AccountDetails,
	bakery *httpbakery.Client,
	apiOpen api.OpenFunc,
	getPassword func(string) (string, error),
) (juju.NewAPIConnectionParams, error) {
	if controllerName == "" {
		return juju.NewAPIConnectionParams{}, errors.Trace(errNoNameSpecified)
	}
	var modelUUID string
	if modelName != "" {
		modelDetails, err := store.ModelByName(controllerName, modelName)
		if err != nil {
			return juju.NewAPIConnectionParams{}, errors.Trace(err)
		}
		modelUUID = modelDetails.ModelUUID
	}
	dialOpts := api.DefaultDialOpts()
	dialOpts.BakeryClient = bakery

	if accountDetails != nil {
		bakery.WebPageVisitor = httpbakery.NewMultiVisitor(
			authentication.NewVisitor(accountDetails.User, getPassword),
			bakery.WebPageVisitor,
		)
	}

	return juju.NewAPIConnectionParams{
		Store:          store,
		ControllerName: controllerName,
		AccountDetails: accountDetails,
		ModelUUID:      modelUUID,
		DialOpts:       dialOpts,
		OpenAPI:        apiOpen,
	}, nil
}

// Prepare prepares a new controller based on the provided configuration.
// It is an error to prepare a controller if there already exists an
// entry in the client store with the same name.
//
// Upon success, Prepare will update the ClientStore with the details of
// the controller, admin account, and admin model.
func Prepare(
	ctx environs.BootstrapContext,
	store jujuclient.ClientStore,
	args PrepareParams,
) (environs.Environ, error) {

	if err := args.Validate(); err != nil {
		return nil, errors.Trace(err)
	}

	_, err := store.ControllerByName(args.ControllerName)
	if err == nil {
		return nil, errors.AlreadyExistsf("controller %q", args.ControllerName)
	} else if !errors.IsNotFound(err) {
		return nil, errors.Annotatef(err, "error reading controller %q info", args.ControllerName)
	}

	cloudType, ok := args.ModelConfig["type"].(string)
	if !ok {
		return nil, errors.NotFoundf("cloud type in base configuration")
	}

	p, err := environs.Provider(cloudType)
	if err != nil {
		return nil, errors.Trace(err)
	}

	env, details, err := prepare(ctx, p, args)
	if err != nil {
		return nil, errors.Trace(err)
	}

	if err := decorateAndWriteInfo(
		store, details, args.ControllerName, env.Config().Name(),
	); err != nil {
		return nil, errors.Annotatef(err, "cannot create controller %q info", args.ControllerName)
	}
	return env, nil
}

func newCacheStore(store jujuclient.ClientStore) (*cacheStore, error) {
	controllers, err := store.AllControllers()
	if err != nil {
		return nil, errors.Trace(err)
	}
	accounts := make(map[string]jujuclient.AccountDetails)
	for controller := range controllers {
		acct, err := store.AccountDetails(controller)
		if err != nil {
			if !errors.IsNotFound(err) {
				return nil, errors.Annotatef(err, "cannot get account details for %q", controller)
			}
		} else {
			accounts[controller] = *acct
		}
	}
	return &cacheStore{
		accounts:        accounts,
		origStore:       store,
		controllers:     controllers,
		updatedAccounts: make(map[string]bool),
	}, nil
}

func newAPIConnectionParams(
	store jujuclient.ClientStore,
	controllerName,
	accountName,
	modelName string,
	bakery *httpbakery.Client,
) (juju.NewAPIConnectionParams, error) {
	if controllerName == "" {
		return juju.NewAPIConnectionParams{}, errors.Trace(errNoNameSpecified)
	}
	var accountDetails *jujuclient.AccountDetails
	if accountName != "" {
		var err error
		accountDetails, err = store.AccountByName(controllerName, accountName)
		if err != nil {
			return juju.NewAPIConnectionParams{}, errors.Trace(err)
		}
	}
	var modelUUID string
	if modelName != "" {
		modelDetails, err := store.ModelByName(controllerName, accountName, modelName)
		if err != nil {
			return juju.NewAPIConnectionParams{}, errors.Trace(err)
		}
		modelUUID = modelDetails.ModelUUID
	}
	dialOpts := api.DefaultDialOpts()
	dialOpts.BakeryClient = bakery
	return juju.NewAPIConnectionParams{
		Store:           store,
		ControllerName:  controllerName,
		BootstrapConfig: NewGetBootstrapConfigFunc(store),
		AccountDetails:  accountDetails,
		ModelUUID:       modelUUID,
		DialOpts:        dialOpts,
	}, nil
}

func newAPIConnectionFromNames(
	c *gc.C,
	controller, model string,
	store jujuclient.ClientStore,
	apiOpen api.OpenFunc,
) (api.Connection, error) {
	params := juju.NewAPIConnectionParams{
		Store:          store,
		ControllerName: controller,
		DialOpts:       api.DefaultDialOpts(),
		OpenAPI:        apiOpen,
	}
	accountDetails, err := store.AccountDetails(controller)
	if !errors.IsNotFound(err) {
		c.Assert(err, jc.ErrorIsNil)
		params.AccountDetails = accountDetails
	}
	if model != "" {
		modelDetails, err := store.ModelByName(controller, model)
		c.Assert(err, jc.ErrorIsNil)
		params.ModelUUID = modelDetails.ModelUUID
	}
	return juju.NewAPIConnection(params)
}

func (c *JujuCommandBase) missingModelError(store jujuclient.ClientStore, controllerName, modelName string) error {
	// First, we'll try and clean up the missing model from the local cache.
	err := store.RemoveModel(controllerName, modelName)
	if err != nil {
		logger.Warningf("cannot remove unknown model from cache: %v", err)
	}
	currentModel, err := store.CurrentModel(controllerName)
	if err != nil {
		logger.Warningf("cannot read current model: %v", err)
	} else if currentModel == modelName {
		if err := store.SetCurrentModel(controllerName, ""); err != nil {
			logger.Warningf("cannot reset current model: %v", err)
		}
	}
	errorMessage := "model %q has been removed from the controller, run 'juju models' and switch to one of them."
	modelInfoMessage := "\nThere are %d accessible models on controller %q."
	models, err := store.AllModels(controllerName)
	if err == nil {
		modelInfoMessage = fmt.Sprintf(modelInfoMessage, len(models), controllerName)
	} else {
		modelInfoMessage = ""
	}
	return errors.Errorf(errorMessage+modelInfoMessage, modelName)
}

func checkModelRemovedFromStore(c *gc.C, name string, store jujuclient.ClientStore) {
	controller, model := modelcmd.SplitModelName(name)
	_, err := store.ModelByName(controller, model)
	c.Assert(err, jc.Satisfies, errors.IsNotFound)
}

func checkModelExistsInStore(c *gc.C, name string, store jujuclient.ClientStore) {
	controller, model := modelcmd.SplitModelName(name)
	_, err := store.ModelByName(controller, model)
	c.Assert(err, jc.ErrorIsNil)
}

// decorateAndWriteInfo decorates the info struct with information
// from the given cfg, and the writes that out to the filesystem.
func decorateAndWriteInfo(
	store jujuclient.ClientStore,
	details prepareDetails,
	controllerName, modelName string,
) error {
	accountName := details.User
	if err := store.UpdateController(controllerName, details.ControllerDetails); err != nil {
		return errors.Trace(err)
	}
	if err := store.UpdateBootstrapConfig(controllerName, details.BootstrapConfig); err != nil {
		return errors.Trace(err)
	}
	if err := store.UpdateAccount(controllerName, accountName, details.AccountDetails); err != nil {
		return errors.Trace(err)
	}
	if err := store.SetCurrentAccount(controllerName, accountName); err != nil {
		return errors.Trace(err)
	}
	if err := store.UpdateModel(controllerName, accountName, modelName, details.ModelDetails); err != nil {
		return errors.Trace(err)
	}
	if err := store.SetCurrentModel(controllerName, accountName, modelName); err != nil {
		return errors.Trace(err)
	}
	return nil
}