feat(cli): wire shared status to the M2 ledger (spec 03)

- `shared status` [--json]: read-only projection of the shared-service ledger
  (alias, status, ref count, consuming projects) with a best-effort self-healing
  reconcile (skipped silently when the daemon is down — the ledger view stays
  truthful). Replaces the stub.
- buildManager helper: assembles a workspace.Manager from the CWD (config +
  read-only docker client keyed by context + state ledger + embedded templates),
  degrading to ledger-only when no daemon is reachable.
- `shared gc`/`doctor` remain stubs pending the up-saga (they stop/reconcile
  against the daemon); `up`/`down` likewise await the saga + the host
  provisioning-port design.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavobertoi

internal/cli/root.go

@@ -68,6 +68,7 @@ func NewRootCmd(opts Options) *cobra.Command {
 		newConfigCmd(g),
 		newGenerateCmd(g),
 		newTemplateCmd(g),
+		newSharedCmd(g),
 		newAliasCmd(g),
 		newVersionCmd(),
 	)

internal/cli/shared.go

@@ -0,0 +1,115 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/open-source-cloud/devstack/internal/config"
+	"github.com/open-source-cloud/devstack/internal/docker"
+	"github.com/open-source-cloud/devstack/internal/state"
+	"github.com/open-source-cloud/devstack/internal/workspace"
+	"github.com/open-source-cloud/devstack/internal/xdg"
+)
+
+// newSharedCmd wires `shared status|gc|doctor`. `status` is the M2 read-only
+// projection of the ledger (shared services + ref counts + consuming projects);
+// `gc`/`doctor` (which stop/reconcile against the daemon) land with the up saga.
+func newSharedCmd(g *GlobalOpts) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "shared",
+		Short: "Inspect and reclaim shared services",
+	}
+	cmd.AddCommand(
+		newSharedStatusCmd(g),
+		stub("gc", "Reclaim unused shared services", "M2 (up saga)"),
+		stub("doctor", "Reconcile the ledger against live containers", "M2 (up saga)"),
+	)
+	return cmd
+}
+
+func newSharedStatusCmd(g *GlobalOpts) *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Show shared-service ref counts and consuming projects",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			mgr, closeFn, err := buildManager(cmd)
+			if err != nil {
+				return err
+			}
+			defer closeFn()
+
+			// Best-effort self-healing reconcile: prune refs for projects whose
+			// containers are no longer live. Skipped silently if the daemon is down
+			// (the ledger view below is still truthful about recorded refs).
+			_, _ = mgr.Reconcile(cmd.Context())
+
+			rows, err := mgr.Status()
+			if err != nil {
+				return err
+			}
+			if g.JSON {
+				return writeJSON(cmd, map[string]any{"shared": rows})
+			}
+			w := cmd.OutOrStdout()
+			if len(rows) == 0 {
+				fmt.Fprintln(w, "no shared services recorded yet (run `devstack up`)")
+				return nil
+			}
+			for _, r := range rows {
+				fmt.Fprintf(w, "%-20s %-10s refs=%d  %v\n", r.Alias, r.Status, r.RefCount, r.Projects)
+			}
+			return nil
+		},
+	}
+}
+
+// buildManager assembles a workspace.Manager from the current directory: the
+// loaded workspace, the read-only docker client (context keys the ledger), the
+// machine-global state ledger, and the embedded template source. The returned
+// closer releases the ledger and the docker client.
+func buildManager(cmd *cobra.Command) (*workspace.Manager, func(), error) {
+	cwd, err := os.Getwd()
+	if err != nil {
+		return nil, nil, err
+	}
+	model, err := config.Load(cwd)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	ctx := cmd.Context()
+	ctxName := state.DefaultContext
+	var dockerClient docker.Client
+	if c, err := docker.NewClient(ctx); err == nil {
+		dockerClient = c
+		ctxName = c.ContextName()
+	} else {
+		// No daemon client: ledger reads still work; reconcile degrades to a no-op.
+		dockerClient = &docker.MockClient{Context: ctxName}
+	}
+
+	db, err := state.Open(ctx, xdg.DataHome(), ctxName)
+	if err != nil {
+		if c, ok := dockerClient.(interface{ Close() error }); ok {
+			_ = c.Close()
+		}
+		return nil, nil, err
+	}
+
+	mgr := &workspace.Manager{
+		Model:    model,
+		DB:       db,
+		Docker:   dockerClient,
+		Source:   builtinSource(),
+		LockPath: filepath.Join(xdg.RuntimeDir(), "devstack.lock"),
+	}
+	closeFn := func() {
+		db.Close()
+		_ = dockerClient.Close()
+	}
+	return mgr, closeFn, nil
+}

internal/cli/stubs.go

@@ -40,11 +40,6 @@ func addStubCommands(root *cobra.Command, _ *GlobalOpts) {
 			stub("sync", "Sync (fetch/pull) all workspace repos", "M3"),
 			stub("status", "Status table across all workspace repos", "M3"),
 		),
-		stub("shared", "Inspect and reclaim shared services", "M2",
-			stub("status", "Show shared-service ref counts and health", "M2"),
-			stub("gc", "Reclaim unused shared services", "M2"),
-			stub("doctor", "Reconcile the ledger against live containers", "M2"),
-		),
 		stub("secrets", "Secrets providers (login, keygen)", "M4",
 			stub("login", "Authenticate a secrets provider", "M4"),
 			stub("keygen", "Generate an age/SOPS key", "M4"),