Swift & .NET CLI Frameworks

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "docsctl",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.8.0"),
    ],
    targets: [
        .executableTarget(
            name: "docsctl",
            dependencies: [.product(name: "ArgumentParser", package: "swift-argument-parser")]
        ),
    ]
)

import ArgumentParser
import Foundation

@main
struct Docsctl: ParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "docsctl",
        abstract: "Search and publish this site's documentation.",
        version: "0.1.0",
        subcommands: [Search.self, Publish.self]
    )

    // ArgumentParser reports usage errors with EX_USAGE (64); the docsctl contract says 2.
    static func main() {
        do {
            var command = try parseAsRoot()
            try command.run()
        } catch {
            let code = exitCode(for: error)
            let message = fullMessage(for: error)
            if !message.isEmpty {
                if code == .success {
                    print(message)                                   // --help and --version go to stdout
                } else {
                    FileHandle.standardError.write(Data((message + "\n").utf8))
                }
            }
            Foundation.exit(code == .validationFailure ? 2 : code.rawValue)
        }
    }

    struct GlobalOptions: ParsableArguments {
        @Flag(name: .long, help: "Emit JSON on stdout.")
        var json = false
    }

    struct Search: ParsableCommand {
        static let configuration = CommandConfiguration(
            abstract: "Search the documentation.",
            discussion: "Example: docsctl search kalman --component irurueta-statistics --json"
        )

        @OptionGroup var global: GlobalOptions

        @Argument(help: "Words to look for.")
        var query: String

        @Option(help: "Restrict to one component.")
        var component: String?

        func run() throws {
            if global.json {
                print(#"{"query":"\#(query)","results":[],"schemaVersion":1,"total":0}"#)
            } else {
                print("0 result(s) for \(query)")
            }
        }
    }

    struct Publish: ParsableCommand {
        static let configuration = CommandConfiguration(
            abstract: "Publish a component (destructive unless --dry-run)."
        )

        @Option(help: "Component to publish.")
        var component: String

        @Flag(name: .customLong("dry-run"), help: "Show the plan only.")
        var dryRun = false

        @Flag(name: [.customLong("yes"), .short], help: "Assume yes for confirmations.")
        var yes = false

        func run() throws {
            if dryRun {
                print(#"{"dryRun":true,"schemaVersion":1}"#)
                return
            }
            if !yes {
                FileHandle.standardError.write(
                    Data("docsctl: publish needs confirmation; re-run with --yes or use --dry-run.\n".utf8))
                throw ExitCode(5)   // CONFIRMATION_REQUIRED
            }
        }
    }
}

// swift-tools-version: 5.9
import PackageDescription
let package = Package(name: "tui", platforms: [.macOS(.v13)],
  dependencies: [.package(url: "https://github.com/rensbreur/SwiftTUI", from: "0.1.0")],
  targets: [.executableTarget(name: "tui", dependencies: [.product(name: "SwiftTUI", package: "SwiftTUI")])])

import Foundation
import SwiftTUI

struct ResultsView: View {
    var body: some View {
        VStack {
            Text("docsctl browse")
            Button("Quit") { exit(0) }
        }
    }
}

Application(rootView: ResultsView()).start()

using System.CommandLine;

const int ExitUsage = 2;
const int ExitConfirmationRequired = 5;

Option<bool> json = new("--json") { Description = "Emit JSON on stdout.", Recursive = true };

Argument<string> query = new("query") { Description = "Words to look for." };
Option<string?> component = new("--component") { Description = "Restrict to one component." };

Option<string> publishComponent = new("--component") { Description = "Component to publish.", Required = true };
Option<bool> dryRun = new("--dry-run") { Description = "Show the plan only." };
Option<bool> yes = new("--yes", "-y") { Description = "Assume yes for confirmations." };

Command search = new("search", "Search the documentation.") { query, component };
search.SetAction(parseResult =>
{
    string q = parseResult.GetValue(query)!;
    Console.Out.WriteLine(parseResult.GetValue(json)
        ? $"{{\"query\":\"{q}\",\"results\":[],\"schemaVersion\":1,\"total\":0}}"
        : $"0 result(s) for {q}");
    return 0;
});

Command publish = new("publish", "Publish a component (destructive unless --dry-run).")
{
    publishComponent, dryRun, yes
};
publish.SetAction(parseResult =>
{
    if (parseResult.GetValue(dryRun))
    {
        Console.Out.WriteLine("{\"dryRun\":true,\"schemaVersion\":1}");
        return 0;
    }
    if (!parseResult.GetValue(yes))
    {
        Console.Error.WriteLine("docsctl: publish needs confirmation; re-run with --yes or use --dry-run.");
        return ExitConfirmationRequired;
    }
    return 0;
});

RootCommand root = new("Search and publish this site's documentation.") { json, search, publish };

ParseResult result = root.Parse(args);
if (result.Errors.Count > 0)
{
    foreach (var error in result.Errors)
    {
        Console.Error.WriteLine(error.Message);
    }
    return ExitUsage;          // the library's own default would be 1
}
return result.Invoke();

using System.ComponentModel;
using Spectre.Console.Cli;

public sealed class SearchSettings : CommandSettings
{
    [CommandArgument(0, "<QUERY>")]
    [Description("Words to look for.")]
    public string Query { get; init; } = "";

    [CommandOption("--component <NAME>")]
    [Description("Restrict to one component.")]
    public string? Component { get; init; }
}

public sealed class SearchCommand : Command<SearchSettings>
{
    protected override int Execute(CommandContext context, SearchSettings settings, CancellationToken cancellationToken)
    {
        Console.Out.WriteLine($"0 result(s) for {settings.Query}");   // data on stdout
        return 0;
    }
}

<PropertyGroup>
  <PackAsTool>true</PackAsTool>
  <ToolCommandName>docsctl</ToolCommandName>
  <PackageOutputPath>./nupkg</PackageOutputPath>
</PropertyGroup>

dotnet tool install --global docsctl                 # per user, on the PATH
dotnet tool install docsctl --tool-path ~/bin        # custom location, not added to PATH automatically
dotnet new tool-manifest && dotnet tool install docsctl   # local tool, pinned per repository