cella: expose policy discovery

Author: changkun

internal/api/client.go

@@ -155,7 +155,9 @@ type APIError struct {
 func (e *APIError) Error() string {
 	if e.Code == "policy_sidecar_required" {
 		return "cannot create cella: the selected policy requires Cella's credential sidecar, but the server has no complete sidecar configuration for this CLI token.\n" +
-			"This is not a local command syntax problem. Re-run `latere auth login` with the latest CLI, then retry. If it still fails, ask your Latere admin/support to configure the CLI sidecar client or choose a policy that does not require a sidecar.\n" +
+			"This is not a local command syntax problem. Re-run `latere auth login` with the latest CLI, then retry.\n" +
+			"To choose another policy, run `latere cella policy list` and retry with `latere cella create --policy <name>` using a selectable policy where SIDECAR is `no`.\n" +
+			"If no such policy is available, ask your Latere admin/support to configure the CLI sidecar client or assign a non-sidecar policy.\n" +
 			"server code: policy_sidecar_required"
 	}
 	if e.Code != "" {

internal/api/client_test.go

@@ -17,6 +17,9 @@ func TestAPIErrorPolicySidecarRequiredIsActionable(t *testing.T) {
 		"server has no complete sidecar configuration for this CLI token",
 		"not a local command syntax problem",
 		"latere auth login",
+		"latere cella policy list",
+		"latere cella create --policy <name>",
+		"SIDECAR is `no`",
 		"server code: policy_sidecar_required",
 	} {
 		if !strings.Contains(err, want) {

internal/commands/cella.go

@@ -43,6 +43,20 @@ type sandboxDTO struct {
 	Workdir         string            `json:"workdir,omitempty"`
 }
 
+type policyDTO struct {
+	Name               string    `json:"name"`
+	Label              string    `json:"label"`
+	Description        string    `json:"description"`
+	CapabilityProfile  string    `json:"capability_profile"`
+	SidecarRequired    bool      `json:"sidecar_required"`
+	IsDefault          bool      `json:"is_default"`
+	Selectable         bool      `json:"selectable"`
+	AssignmentSource   string    `json:"assignment_source"`
+	NetworkEgressFQDNs []string  `json:"network_egress_fqdns,omitempty"`
+	CreatedAt          time.Time `json:"created_at,omitzero"`
+	UpdatedAt          time.Time `json:"updated_at,omitzero"`
+}
+
 // fallbackWorkdir is the path the MCP/CLI assume when a sandbox DTO
 // arrives without a workdir field (older sandboxd before the workdir
 // contract shipped).
@@ -94,13 +108,14 @@ func newCellaCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "cella",
 		Aliases: []string{"sandbox"},
-		Short:   "Manage cellas (create, list, rename, start, stop, delete, run).",
+		Short:   "Manage cellas (create, list, policy, start, stop, delete, run).",
 		Long: `Manage Cella sandboxes — per-user compute environments at cella.latere.ai.
 
 Each cella is a PVC-backed workspace plus a Pod for compute. Tier
 'ephemeral' auto-stops on idle and auto-deletes after a wall-clock
 window; tier 'persistent' stays until you delete it.`,
 		Example: `  latere cella list
+  latere cella policy list
   latere cella create --name dev --tier persistent --disk 10
   latere cella shell dev
   latere cella run dev -- python train.py
@@ -114,6 +129,7 @@ window; tier 'persistent' stays until you delete it.`,
 		newCeStartCmd(),
 		newCeStopCmd(),
 		newCeDeleteCmd(),
+		newCePolicyCmd(),
 		newCeExecCmd(),
 		newCeShellCmd(),
 		newCeRunCmd(),
@@ -185,6 +201,7 @@ image and account defaults for disk, CPU, memory, idle timeout, and
 policy. Use --tier persistent for a workspace that survives until
 explicitly deleted.`,
 		Example: `  latere cella create
+  latere cella policy list
   latere cella create --name dev --tier persistent --disk 10
   latere cella create --name gpu-test --cpu 2 --memory 8Gi
   latere cella create --name app --env NODE_ENV=development --credential github
@@ -301,6 +318,95 @@ cellas returned by the backend, including warm-pool cellas.`,
 	return cmd
 }
 
+func newCePolicyCmd() *cobra.Command {
+	var (
+		apiURL string
+		jsonF  bool
+	)
+	cmd := &cobra.Command{
+		Use:     "policy",
+		Aliases: []string{"policies"},
+		Short:   "List policy profiles available for new cellas.",
+		Long: `List Cella policy profiles visible to the current token.
+
+Policies control runtime capabilities such as network shape, workspace
+layout, and whether Cella's credential sidecar is required. The default
+policy is used when 'latere cella create' is run without --policy.
+
+Use a selectable policy with:
+
+  latere cella create --policy <name>
+
+If create fails because the selected policy requires the sidecar, list
+policies and choose a selectable policy where SIDECAR is "no", or ask
+an admin to configure the sidecar client for your token.`,
+		Example: `  latere cella policy
+  latere cella policy list
+  latere cella policies --json
+  latere cella create --policy restricted-network`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runPolicyList(cmd.Context(), apiURL, jsonF)
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&apiURL, "api-url", "", "override Cella API base URL")
+	f.BoolVar(&jsonF, "json", false, "JSON output")
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "List policy profiles available for new cellas.",
+		Long:  cmd.Long,
+		Example: `  latere cella policy list
+  latere cella policy list --json
+  latere cella create --policy restricted-network`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runPolicyList(cmd.Context(), apiURL, jsonF)
+		},
+	}
+	list.Flags().StringVar(&apiURL, "api-url", "", "override Cella API base URL")
+	list.Flags().BoolVar(&jsonF, "json", false, "JSON output")
+	cmd.AddCommand(list)
+	return cmd
+}
+
+func runPolicyList(ctx context.Context, apiURL string, jsonF bool) error {
+	c, err := authedClient(apiURL)
+	if err != nil {
+		return err
+	}
+	var policies []policyDTO
+	if err := c.GetJSON(ctx, "/v1/policies", &policies); err != nil {
+		return err
+	}
+	if jsonF {
+		return printJSON(policies)
+	}
+	if len(policies) == 0 {
+		fmt.Fprintln(os.Stdout, "No policy profiles are visible to this token.")
+		fmt.Fprintln(os.Stdout, "Ask your Latere admin to assign a selectable policy, then retry `latere cella create --policy <name>`.")
+		return nil
+	}
+	printPolicies(policies)
+	return nil
+}
+
+func printPolicies(policies []policyDTO) {
+	tw := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+	_, _ = fmt.Fprintln(tw, "NAME\tDEFAULT\tSELECTABLE\tSIDECAR\tCAPABILITY\tSOURCE\tDESCRIPTION")
+	for _, p := range policies {
+		_, _ = fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
+			p.Name,
+			yesNo(p.IsDefault),
+			yesNo(p.Selectable),
+			yesNo(p.SidecarRequired),
+			defaultStr(p.CapabilityProfile, "-"),
+			defaultStr(p.AssignmentSource, "-"),
+			oneLine(defaultStr(p.Description, p.Label)),
+		)
+	}
+	_ = tw.Flush()
+}
+
 func newCeGetCmd() *cobra.Command {
 	var apiURL string
 	cmd := &cobra.Command{
@@ -1447,6 +1553,17 @@ func defaultStr(s, fallback string) string {
 	return s
 }
 
+func yesNo(v bool) string {
+	if v {
+		return "yes"
+	}
+	return "no"
+}
+
+func oneLine(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
+
 func humanAge(t time.Time) string {
 	if t.IsZero() {
 		return "-"

internal/commands/policy_test.go

@@ -0,0 +1,131 @@
+package commands
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestPolicyListPrintsCreateGuidanceFields(t *testing.T) {
+	writeTestToken(t)
+	var authz string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authz = r.Header.Get("Authorization")
+		if r.URL.Path != "/v1/policies" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{
+				"name":"agent-default",
+				"label":"Agent Default",
+				"description":"Uses sidecar credentials",
+				"capability_profile":"restricted",
+				"sidecar_required":true,
+				"is_default":true,
+				"selectable":true,
+				"assignment_source":"default"
+			},
+			{
+				"name":"restricted-network",
+				"label":"Restricted Network",
+				"description":"No sidecar required",
+				"capability_profile":"restricted-no-network",
+				"sidecar_required":false,
+				"is_default":false,
+				"selectable":true,
+				"assignment_source":"client"
+			}
+		]`))
+	}))
+	defer srv.Close()
+
+	out := capturePolicyStdout(t, func() {
+		if err := runPolicyList(context.Background(), srv.URL, false); err != nil {
+			t.Fatalf("runPolicyList: %v", err)
+		}
+	})
+
+	if authz != "Bearer test-token" {
+		t.Fatalf("Authorization = %q, want bearer token", authz)
+	}
+	for _, want := range []string{
+		"NAME",
+		"DEFAULT",
+		"SELECTABLE",
+		"SIDECAR",
+		"agent-default",
+		"yes",
+		"restricted-network",
+		"restricted-no-network",
+		"client",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("policy list output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestPolicyListEmptyExplainsNextStep(t *testing.T) {
+	writeTestToken(t)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`[]`))
+	}))
+	defer srv.Close()
+
+	out := capturePolicyStdout(t, func() {
+		if err := runPolicyList(context.Background(), srv.URL, false); err != nil {
+			t.Fatalf("runPolicyList: %v", err)
+		}
+	})
+
+	for _, want := range []string{
+		"No policy profiles are visible",
+		"latere cella create --policy <name>",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("empty policy output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func writeTestToken(t *testing.T) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "token.json")
+	if err := os.WriteFile(path, []byte(`{"access_token":"test-token","token_type":"Bearer"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("LATERE_TOKEN_FILE", path)
+}
+
+func capturePolicyStdout(t *testing.T, fn func()) string {
+	t.Helper()
+	old := os.Stdout
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stdout = w
+	defer func() { os.Stdout = old }()
+
+	fn()
+
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+	var buf bytes.Buffer
+	if _, err := io.Copy(&buf, r); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return buf.String()
+}

internal/commands/root_test.go

@@ -79,11 +79,21 @@ func TestHelpIncludesUserExamples(t *testing.T) {
 			args: []string{"cella", "create", "--help"},
 			want: []string{
 				"Create a Cella workspace.",
+				"latere cella policy list",
 				"latere cella create --name dev --tier persistent --disk 10",
 				"idle timeout in minutes; omit for account default, 0 disables",
 				"named network policy",
 			},
 		},
+		{
+			name: "cella policy",
+			args: []string{"cella", "policy", "--help"},
+			want: []string{
+				"List Cella policy profiles visible to the current token.",
+				"latere cella create --policy <name>",
+				"choose a selectable policy where SIDECAR is \"no\"",
+			},
+		},
 		{
 			name: "cella run",
 			args: []string{"cella", "run", "--help"},