Merge pull request #7611 from obsidiansystems/structured-command-stabilization

Stuctured command stability

src/libutil/args.cc

@@ -236,8 +236,6 @@ nlohmann::json Args::toJSON()
     auto flags = nlohmann::json::object();
 
     for (auto & [name, flag] : longFlags) {
-        /* Skip experimental flags when listing flags. */
-        if (!experimentalFeatureSettings.isEnabled(flag->experimentalFeature)) continue;
         auto j = nlohmann::json::object();
         if (flag->aliases.count(name)) continue;
         if (flag->shortName)
@@ -249,6 +247,11 @@ nlohmann::json Args::toJSON()
             j["arity"] = flag->handler.arity;
         if (!flag->labels.empty())
             j["labels"] = flag->labels;
+        // TODO With C++23 use `std::optional::tranform`
+        if (auto & xp = flag->experimentalFeature)
+            j["experimental-feature"] = showExperimentalFeature(*xp);
+        else
+            j["experimental-feature"] = nullptr;
         flags[name] = std::move(j);
     }
 
@@ -345,6 +348,11 @@ Strings argvToStrings(int argc, char * * argv)
     return args;
 }
 
+std::optional<ExperimentalFeature> Command::experimentalFeature ()
+{
+    return { Xp::NixCommand };
+}
+
 MultiCommand::MultiCommand(const Commands & commands_)
     : commands(commands_)
 {
@@ -408,6 +416,11 @@ nlohmann::json MultiCommand::toJSON()
         cat["id"] = command->category();
         cat["description"] = trim(categories[command->category()]);
         j["category"] = std::move(cat);
+        // TODO With C++23 use `std::optional::tranform`
+        if (auto xp = command->experimentalFeature())
+            cat["experimental-feature"] = showExperimentalFeature(*xp);
+        else
+            cat["experimental-feature"] = nullptr;
         cmds[name] = std::move(j);
     }
 

src/libutil/args.hh

@@ -236,6 +236,8 @@ struct Command : virtual public Args
 
     static constexpr Category catDefault = 0;
 
+    virtual std::optional<ExperimentalFeature> experimentalFeature ();
+
     virtual Category category() { return catDefault; }
 };
 

src/nix/doctor.cc

@@ -39,6 +39,14 @@ struct CmdDoctor : StoreCommand
 {
     bool success = true;
 
+    /**
+     * This command is stable before the others
+     */
+    std::optional<ExperimentalFeature> experimentalFeature() override
+    {
+        return std::nullopt;
+    }
+
     std::string description() override
     {
         return "check your system for potential problems and print a PASS or FAIL for each check";

src/nix/main.cc

@@ -423,10 +423,8 @@ void mainWrapped(int argc, char * * argv)
     if (!args.command)
         throw UsageError("no subcommand specified");
 
-    if (args.command->first != "repl"
+    experimentalFeatureSettings.require(
-        && args.command->first != "doctor"
+        args.command->second->experimentalFeature());
-        && args.command->first != "upgrade-nix")
-        experimentalFeatureSettings.require(Xp::NixCommand);
 
     if (args.useNet && !haveInternet()) {
         warn("you don't have Internet access; disabling some network-dependent features");

src/nix/repl.cc

@@ -12,6 +12,14 @@ struct CmdRepl : RawInstallablesCommand
         evalSettings.pureEval = false;
     }
 
+    /**
+     * This command is stable before the others
+     */
+    std::optional<ExperimentalFeature> experimentalFeature() override
+    {
+        return std::nullopt;
+    }
+
     std::vector<std::string> files;
 
     Strings getDefaultFlakeAttrPaths() override

src/nix/upgrade-nix.cc

@@ -32,6 +32,14 @@ struct CmdUpgradeNix : MixDryRun, StoreCommand
         });
     }
 
+    /**
+     * This command is stable before the others
+     */
+    std::optional<ExperimentalFeature> experimentalFeature() override
+    {
+        return std::nullopt;
+    }
+
     std::string description() override
     {
         return "upgrade Nix to the stable version declared in Nixpkgs";

tests/experimental-features.sh

@@ -15,15 +15,20 @@ function both_ways {
 # Simple case, the configuration effects the running command
 both_ways show-config
 
-# Complicated case, earlier args effect later args
+# Skipping for now, because we actually *do* want these to show up in
+# the manual, just be marked experimental. Will reenable once the manual
+# generation takes advantage of the JSON metadata on this.
 
-both_ways store gc --help
+# both_ways store gc --help
 
 expect 1 nix --experimental-features 'nix-command' show-config --flake-registry 'https://no'
 nix --experimental-features 'nix-command flakes' show-config --flake-registry 'https://no'
 
-# Double check this is stable
+# Double check these are stable
 nix --experimental-features '' --help
+nix --experimental-features '' doctor --help
+nix --experimental-features '' repl --help
+nix --experimental-features '' upgrade-nix --help
 
 # These 3 arguments are currently given to all commands, which is wrong (as not
 # all care). To deal with fixing later, we simply make them require the