feat(files): add 'ipfs files chroot' command

adds recovery command for corrupted MFS root (issue #10762):
- `ipfs files chroot [--confirm] [<cid>]` replaces the MFS root CID
- defaults to empty directory if no CID specified
- validates new CID exists locally and is a directory
- exports FilesRootDatastoreKey constant for reuse
- improved error message shows CID and suggests recovery

replaces the previous `replace-root` approach with renamed command
following the `ch*` pattern (chcid, chmod, chroot).

Author: lidel

core/commands/commands_test.go

@@ -90,6 +90,7 @@ func TestCommands(t *testing.T) {
 		"/files/stat",
 		"/files/write",
 		"/files/chmod",
+		"/files/chroot",
 		"/files/touch",
 		"/filestore",
 		"/filestore/dups",

core/commands/files.go

@@ -16,13 +16,15 @@ import (
 	"time"
 
 	humanize "github.com/dustin/go-humanize"
+	oldcmds "github.com/ipfs/kubo/commands"
 	"github.com/ipfs/kubo/config"
 	"github.com/ipfs/kubo/core"
 	"github.com/ipfs/kubo/core/commands/cmdenv"
 	"github.com/ipfs/kubo/core/node"
 	fsrepo "github.com/ipfs/kubo/repo/fsrepo"
 
 	bservice "github.com/ipfs/boxo/blockservice"
+	bstore "github.com/ipfs/boxo/blockstore"
 	offline "github.com/ipfs/boxo/exchange/offline"
 	dag "github.com/ipfs/boxo/ipld/merkledag"
 	ft "github.com/ipfs/boxo/ipld/unixfs"
@@ -31,7 +33,6 @@ import (
 	cid "github.com/ipfs/go-cid"
 	cidenc "github.com/ipfs/go-cidutil/cidenc"
 	"github.com/ipfs/go-datastore"
-	fslock "github.com/ipfs/go-fs-lock"
 	cmds "github.com/ipfs/go-ipfs-cmds"
 	ipld "github.com/ipfs/go-ipld-format"
 	logging "github.com/ipfs/go-log/v2"
@@ -124,19 +125,19 @@ performance.`,
 		cmds.BoolOption(filesFlushOptionName, "f", "Flush target and ancestors after write.").WithDefault(true),
 	},
 	Subcommands: map[string]*cmds.Command{
-		"read":         filesReadCmd,
-		"write":        filesWriteCmd,
-		"mv":           filesMvCmd,
-		"cp":           filesCpCmd,
-		"ls":           filesLsCmd,
-		"mkdir":        filesMkdirCmd,
-		"stat":         filesStatCmd,
-		"rm":           filesRmCmd,
-		"flush":        filesFlushCmd,
-		"chcid":        filesChcidCmd,
-		"chmod":        filesChmodCmd,
-		"touch":        filesTouchCmd,
-		"replace-root": filesReplaceRoot,
+		"read":   filesReadCmd,
+		"write":  filesWriteCmd,
+		"mv":     filesMvCmd,
+		"cp":     filesCpCmd,
+		"ls":     filesLsCmd,
+		"mkdir":  filesMkdirCmd,
+		"stat":   filesStatCmd,
+		"rm":     filesRmCmd,
+		"flush":  filesFlushCmd,
+		"chcid":  filesChcidCmd,
+		"chmod":  filesChmodCmd,
+		"chroot": filesChrootCmd,
+		"touch":  filesTouchCmd,
 	},
 }
 
@@ -1366,111 +1367,6 @@ Remove files or directories.
 	},
 }
 
-var filesReplaceRoot = &cmds.Command{
-	Helptext: cmds.HelpText{
-		Tagline: "Replace the MFS root.",
-		ShortDescription: `
-Replace the filesystem root with another CID when the filesystem. Usually used as recovery method if MFS has been corrupted.
-`,
-		LongDescription: `
-Replace the filesystem root with another CID.
-This command is meant to run in standalone mode when the daemon isn't running.
-It is an advanced command that you normally do *not* want to run except when
-the filesystem has been corrupted and the daemon refuses to run.
-
-FIXME: Add an example of the daemon not running once https://github.com/ipfs/go-ipfs/issues/7183
-is resolved.
-
-$ ipfs init
-[...]
-ipfs cat /ipfs/QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/readme # <- init dir
-[...] 
-$ ipfs files ls /
-[nothing; empty dir]
-$ ipfs files stat / --hash
-QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn
-# FIXME(BLOCKING): Need the following to somehow "start" the root dir, otherwise
-#  the replace-root will fail to find the '/local/filesroot' entry in the repo
-$ ipfs files cp /ipfs/QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/readme /file
-$ GOLOG_LOG_LEVEL="info" ipfs files replace-root QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc # init dir from before
-[...] replaced MFS files root QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc [...]
-[here we have the CID of the old root to "undo" in case of error]
-$ ipfs files ls /
-[contents from init dir now set as the root of the filesystem]
-about
-contact
-help
-ping
-quick-start
-readme
-security-notes
-$ ipfs files replace-root QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn # empty dir from init
-$ ipfs files ls /
-[nothing; empty dir]
-`,
-	},
-	Arguments: []cmds.Argument{
-		cmds.StringArg("new-root", true, false, "New root to use."),
-	},
-	// FIXME(BLOCKING): Can/should we do this with the repo running?
-	NoRemote: true,
-	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
-		if len(req.Arguments) < 1 {
-			return fmt.Errorf("new root not provided")
-		}
-		newFilesRootCid, err := cid.Parse(req.Arguments[0])
-		if err != nil {
-			return fmt.Errorf("files root argument provided %s is not a valid CID: %w", req.Arguments[0], err)
-
-		}
-		// FIXME(BLOCKING): Check (a) that this CID exists *locally* and (b)
-		//  that it's a dir.
-
-		cfgRoot, err := cmdenv.GetConfigRoot(env)
-		if err != nil {
-			return err
-		}
-
-		repo, err := fsrepo.Open(cfgRoot)
-		if err != nil {
-			if pathError, ok := err.(*os.PathError); ok {
-				if _, isLockError := pathError.Unwrap().(fslock.LockedError); isLockError {
-					return fmt.Errorf("aquiring the repo lock (make sure the daemon isn't running): %w", err)
-				}
-			}
-			return err
-		}
-		localDS := repo.Datastore()
-		defer repo.Close()
-
-		filesRootBytes, err := localDS.Get(req.Context, node.FilesRootDatastoreKey)
-		if err == datastore.ErrNotFound {
-			return fmt.Errorf("MFS files root %s not found in repo", node.FilesRootDatastoreKey)
-		} else if err != nil {
-			return fmt.Errorf("looking for MFS files root: %w", err)
-		}
-		filesRootCid, err := cid.Cast(filesRootBytes)
-		if err != nil {
-			return fmt.Errorf("casting MFS files root %s as CID: %w", filesRootBytes, err)
-		}
-
-		err = localDS.Put(req.Context, node.FilesRootDatastoreKey, newFilesRootCid.Bytes())
-		if err != nil {
-			return fmt.Errorf("storing new files root: %w", err)
-		}
-		// FIXME(BLOCKING): Do we need this if we're closing the repo at the end
-		//  of the command? Likely not.
-		err = localDS.Sync(req.Context, node.FilesRootDatastoreKey)
-		if err != nil {
-			return fmt.Errorf("syncing new files root: %w", err)
-		}
-
-		log.Infof("replaced MFS files root %s with %s", filesRootCid, newFilesRootCid)
-
-		return nil
-	},
-}
-
 func removePath(filesRoot *mfs.Root, path string, force bool, dashr bool) error {
 	if path == "/" {
 		return fmt.Errorf("cannot delete root")
@@ -1758,3 +1654,153 @@ Examples:
 		return mfs.Touch(nd.FilesRoot, path, ts)
 	},
 }
+
+const chrootConfirmOptionName = "confirm"
+
+var filesChrootCmd = &cmds.Command{
+	Status: cmds.Experimental,
+	Helptext: cmds.HelpText{
+		Tagline: "Change the MFS root CID.",
+		ShortDescription: `
+'ipfs files chroot' changes the root CID used by MFS (Mutable File System).
+This is a recovery command for when MFS becomes corrupted and prevents the
+daemon from starting.
+
+When run without a CID argument, resets MFS to an empty directory.
+
+WARNING: The old MFS root and its unpinned children will be removed during
+the next garbage collection. Pin the old root first if you want to preserve.
+
+This command can only run when the daemon is not running.
+`,
+		LongDescription: `
+'ipfs files chroot' changes the root CID used by MFS (Mutable File System).
+This is a recovery command for when MFS becomes corrupted and prevents the
+daemon from starting.
+
+When run without a CID argument, resets MFS to an empty directory.
+
+WARNING: The old MFS root and its unpinned children will be removed during
+the next garbage collection. Pin the old root first if you want to preserve.
+
+This command can only run when the daemon is not running.
+
+Examples:
+
+  # Reset MFS to empty directory (recovery from corruption)
+  $ ipfs files chroot --confirm
+
+  # Restore MFS to a known good directory CID
+  $ ipfs files chroot --confirm QmYourBackupCID
+`,
+	},
+	Arguments: []cmds.Argument{
+		cmds.StringArg("cid", false, false, "New root CID (defaults to empty directory if not specified)."),
+	},
+	Options: []cmds.Option{
+		cmds.BoolOption(chrootConfirmOptionName, "Confirm this potentially destructive operation."),
+	},
+	NoRemote: true,
+	Extra:    CreateCmdExtras(SetDoesNotUseRepo(true)),
+	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
+		confirm, _ := req.Options[chrootConfirmOptionName].(bool)
+		if !confirm {
+			return errors.New("this is a potentially destructive operation; pass --confirm to proceed")
+		}
+
+		// Determine new root CID
+		var newRootCid cid.Cid
+		if len(req.Arguments) > 0 {
+			var err error
+			newRootCid, err = cid.Decode(req.Arguments[0])
+			if err != nil {
+				return fmt.Errorf("invalid CID %q: %w", req.Arguments[0], err)
+			}
+		} else {
+			// Default to empty directory
+			newRootCid = ft.EmptyDirNode().Cid()
+		}
+
+		// Get config root to open repo directly
+		cctx := env.(*oldcmds.Context)
+		cfgRoot := cctx.ConfigRoot
+
+		// Open repo directly (daemon must not be running)
+		repo, err := fsrepo.Open(cfgRoot)
+		if err != nil {
+			return fmt.Errorf("opening repo (is the daemon running?): %w", err)
+		}
+		defer repo.Close()
+
+		localDS := repo.Datastore()
+		bs := bstore.NewBlockstore(localDS)
+
+		// Check new root exists locally and is a directory
+		hasBlock, err := bs.Has(req.Context, newRootCid)
+		if err != nil {
+			return fmt.Errorf("checking if new root exists: %w", err)
+		}
+		if !hasBlock {
+			// Special case: empty dir is always available (hardcoded in boxo)
+			emptyDirCid := ft.EmptyDirNode().Cid()
+			if !newRootCid.Equals(emptyDirCid) {
+				return fmt.Errorf("new root %s does not exist locally; fetch it first with 'ipfs block get'", newRootCid)
+			}
+		}
+
+		// Validate it's a directory (not a file)
+		if hasBlock {
+			blk, err := bs.Get(req.Context, newRootCid)
+			if err != nil {
+				return fmt.Errorf("reading new root block: %w", err)
+			}
+			pbNode, err := dag.DecodeProtobuf(blk.RawData())
+			if err != nil {
+				return fmt.Errorf("new root is not a valid dag-pb node: %w", err)
+			}
+			fsNode, err := ft.FSNodeFromBytes(pbNode.Data())
+			if err != nil {
+				return fmt.Errorf("new root is not a valid UnixFS node: %w", err)
+			}
+			if fsNode.Type() != ft.TDirectory && fsNode.Type() != ft.THAMTShard {
+				return fmt.Errorf("new root must be a directory, got %s", fsNode.Type())
+			}
+		}
+
+		// Get old root for display (if exists)
+		var oldRootStr string
+		oldRootBytes, err := localDS.Get(req.Context, node.FilesRootDatastoreKey)
+		if err == nil {
+			oldRootCid, err := cid.Cast(oldRootBytes)
+			if err == nil {
+				oldRootStr = oldRootCid.String()
+			}
+		} else if !errors.Is(err, datastore.ErrNotFound) {
+			return fmt.Errorf("reading current MFS root: %w", err)
+		}
+
+		// Write new root
+		err = localDS.Put(req.Context, node.FilesRootDatastoreKey, newRootCid.Bytes())
+		if err != nil {
+			return fmt.Errorf("writing new MFS root: %w", err)
+		}
+
+		// Build output message
+		var msg string
+		if oldRootStr != "" {
+			msg = fmt.Sprintf("MFS root changed from %s to %s\n", oldRootStr, newRootCid)
+			msg += fmt.Sprintf("The old root %s will be garbage collected unless pinned.\n", oldRootStr)
+		} else {
+			msg = fmt.Sprintf("MFS root set to %s\n", newRootCid)
+		}
+
+		return cmds.EmitOnce(res, &MessageOutput{Message: msg})
+	},
+	Type: MessageOutput{},
+	Encoders: cmds.EncoderMap{
+		cmds.Text: cmds.MakeTypedEncoder(func(req *cmds.Request, w io.Writer, out *MessageOutput) error {
+			_, err := fmt.Fprint(w, out.Message)
+			return err
+		}),
+	},
+}

core/node/core.go

@@ -30,6 +30,9 @@ import (
 	"github.com/ipfs/kubo/repo"
 )
 
+// FilesRootDatastoreKey is the datastore key for the MFS files root CID.
+var FilesRootDatastoreKey = datastore.NewKey("/local/filesroot")
+
 // BlockService creates new blockservice which provides an interface to fetch content-addressable blocks
 func BlockService(cfg *config.Config) func(lc fx.Lifecycle, bs blockstore.Blockstore, rem exchange.Interface) blockservice.BlockService {
 	return func(lc fx.Lifecycle, bs blockstore.Blockstore, rem exchange.Interface) blockservice.BlockService {
@@ -181,7 +184,6 @@ func Dag(bs blockservice.BlockService) format.DAGService {
 // Files loads persisted MFS root
 func Files(strategy string) func(mctx helpers.MetricsCtx, lc fx.Lifecycle, repo repo.Repo, dag format.DAGService, bs blockstore.Blockstore, prov DHTProvider) (*mfs.Root, error) {
 	return func(mctx helpers.MetricsCtx, lc fx.Lifecycle, repo repo.Repo, dag format.DAGService, bs blockstore.Blockstore, prov DHTProvider) (*mfs.Root, error) {
-		dsk := datastore.NewKey("/local/filesroot")
 		pf := func(ctx context.Context, c cid.Cid) error {
 			rootDS := repo.Datastore()
 			if err := rootDS.Sync(ctx, blockstore.BlockPrefix); err != nil {
@@ -191,15 +193,15 @@ func Files(strategy string) func(mctx helpers.MetricsCtx, lc fx.Lifecycle, repo
 				return err
 			}
 
-			if err := rootDS.Put(ctx, dsk, c.Bytes()); err != nil {
+			if err := rootDS.Put(ctx, FilesRootDatastoreKey, c.Bytes()); err != nil {
 				return err
 			}
-			return rootDS.Sync(ctx, dsk)
+			return rootDS.Sync(ctx, FilesRootDatastoreKey)
 		}
 
 		var nd *merkledag.ProtoNode
 		ctx := helpers.LifecycleCtx(mctx, lc)
-		val, err := repo.Datastore().Get(ctx, dsk)
+		val, err := repo.Datastore().Get(ctx, FilesRootDatastoreKey)
 
 		switch {
 		case errors.Is(err, datastore.ErrNotFound):
@@ -243,7 +245,8 @@ func Files(strategy string) func(mctx helpers.MetricsCtx, lc fx.Lifecycle, repo
 
 		root, err := mfs.NewRoot(ctx, dag, nd, pf, prov)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("failed to initialize MFS root from %s stored at %s: %w. "+
+				"If corrupted, use 'ipfs files chroot' to reset (see --help)", nd.Cid(), FilesRootDatastoreKey, err)
 		}
 
 		lc.Append(fx.Hook{