@sriinnu/runic 1.0.0

package/Packages/Helix/Sources/Helix/NameSpecification.swift

@@ -0,0 +1,98 @@
+import Foundation
+
+/// Represents a specific flag/option name (short or long).
+public enum HelixName: Equatable, Sendable {
+    case short(Character)
+    case long(String)
+}
+
+extension HelixName {
+    var longComponent: String? {
+        switch self {
+        case let .long(value): value
+        default: nil
+        }
+    }
+
+    var shortComponent: Character? {
+        switch self {
+        case let .short(value): value
+        default: nil
+        }
+    }
+}
+
+/// Mimics ArgumentParser's name specification convenience API.
+public enum NameSpecification: Sendable {
+    case automatic
+    case short(Character)
+    case longName(String)
+    case shortAndLong
+    case customShort(Character, allowingJoined: Bool)
+    case customLong(String)
+
+    public static var long: NameSpecification { .automatic }
+
+    public static func long(_ value: String) -> NameSpecification {
+        .longName(value)
+    }
+
+    func resolve(defaultLabel: String) -> [HelixName] {
+        switch self {
+        case .automatic:
+            [.long(Self.normalize(defaultLabel))]
+        case let .short(char):
+            [.short(char)]
+        case let .longName(name):
+            [.long(name)]
+        case .shortAndLong:
+            [.short(Self.firstCharacter(in: defaultLabel)), .long(Self.normalize(defaultLabel))]
+        case let .customShort(char, _):
+            [.short(char)]
+        case let .customLong(name):
+            [.long(name)]
+        }
+    }
+
+    private static func normalize(_ label: String) -> String {
+        guard !label.isEmpty else { return label }
+
+        let scalars = Array(label.unicodeScalars)
+        let uppercase = CharacterSet.uppercaseLetters
+        let lowercase = CharacterSet.lowercaseLetters
+        let digits = CharacterSet.decimalDigits
+
+        var output = ""
+        var lastWasUpper = false
+        var lastWasLower = false
+
+        for scalar in scalars {
+            let isUpper = uppercase.contains(scalar)
+            let isLower = lowercase.contains(scalar)
+            let isDigit = digits.contains(scalar)
+
+            if isUpper {
+                if lastWasLower || lastWasUpper {
+                    output.append("-")
+                }
+                output.append(Character(scalar).lowercased())
+                lastWasUpper = true
+                lastWasLower = false
+            } else if isLower || isDigit {
+                output.append(Character(scalar))
+                lastWasLower = true
+                lastWasUpper = false
+            } else {
+                output.append("-")
+                lastWasUpper = false
+                lastWasLower = false
+            }
+        }
+
+        return output.trimmingCharacters(in: CharacterSet(charactersIn: "-"))
+    }
+
+    private static func firstCharacter(in label: String) -> Character {
+        label.first ?? "x"
+    }
+}

package/Packages/Helix/Sources/Helix/ParsableCommand.swift

@@ -0,0 +1,204 @@
+import Foundation
+
+/// Protocol every Helix command adopts. Provide metadata via
+/// `commandDescription` and implement `run()` to perform the command's work.
+@MainActor
+public protocol ParsableCommand: Sendable {
+    init()
+    static var commandDescription: CommandDescription { get }
+    mutating func run() async throws
+
+    /// Optional validation method called after parsing but before run().
+    /// Throw `ValidationError` if validation fails.
+    mutating func validate() throws
+}
+
+extension ParsableCommand {
+    /// Default implementation - does nothing.
+    public mutating func validate() throws {
+        // Default: no validation
+    }
+
+    public static var commandDescription: CommandDescription {
+        CommandDescription()
+    }
+
+    /// Creates a command descriptor from this command type.
+    public static var descriptor: CommandDescriptor {
+        let signature = CommandSignature.describe(Self()).flattened()
+        let typeName = String(describing: Self.self)
+        let name: String
+        if let cmdName = commandDescription.commandName {
+            name = cmdName
+        } else {
+            // Remove "Command" suffix if present
+            name = typeName.hasSuffix("Command") ? String(typeName.dropLast(7)) : typeName
+        }
+        return CommandDescriptor(
+            name: name,
+            abstract: commandDescription.abstract,
+            discussion: commandDescription.discussion,
+            signature: signature,
+            subcommands: commandDescription.subcommands.map { $0.descriptor },
+            defaultSubcommandName: commandDescription.defaultSubcommand.map { $0.descriptor.name }
+        )
+    }
+
+    /// Runs the command with arguments from the current platform context.
+    public static func main() async throws {
+        try await main(arguments: DefaultPlatformContext.shared.arguments)
+    }
+
+    /// Runs the command with the specified arguments.
+    public static func main(arguments argv: [String]) async throws {
+        // Build descriptor
+        let descriptor = Self.descriptor
+
+        // Create program and resolve
+        let program = Program(descriptors: [descriptor])
+        let normalizedArguments = program.normalizedArguments(argv)
+        let (helpRequested, versionRequested) = parseHelpVersionFlags(from: normalizedArguments)
+
+        if normalizedArguments.isEmpty, commandDescription.showHelpOnEmptyInvocation {
+            print(HelixError.helpText(for: descriptor))
+            return
+        }
+
+        if helpRequested {
+            let helpDescriptor = (try? program.resolveDescriptorForHelp(arguments: normalizedArguments)) ?? descriptor
+            print(HelixError.helpText(for: helpDescriptor))
+            return
+        }
+
+        if versionRequested {
+            if let version = commandDescription.version {
+                print(version)
+            }
+            return
+        }
+
+        do {
+            let invocation = try program.resolve(argv: normalizedArguments)
+            let commandType = resolveCommandType(path: invocation.path)
+            var command = commandType.init()
+
+            try bindValues(from: invocation, to: &command)
+            try command.validate()
+            try await command.run()
+        } catch let error as HelixError {
+            switch error {
+            default:
+                throw error
+            }
+        }
+    }
+
+    private static func parseHelpVersionFlags(from arguments: [String]) -> (help: Bool, version: Bool) {
+        var helpRequested = false
+        var versionRequested = false
+        for argument in arguments {
+            if argument == "--" { break }
+            switch argument {
+            case "-h", "--help":
+                helpRequested = true
+            case "-V", "--version":
+                versionRequested = true
+            default:
+                break
+            }
+        }
+        return (helpRequested, versionRequested)
+    }
+
+    /// Binds parsed values from invocation to command properties using reflection.
+    /// This method uses Mirror to traverse command properties and set values from parsed arguments.
+    private static func bindValues(from invocation: CommandInvocation, to command: inout any ParsableCommand) throws {
+        try _HelixBinder.bindCommand(
+            &command,
+            parsed: invocation.parsedValues,
+            environment: DefaultPlatformContext.shared.environment
+        )
+    }
+
+    private static func resolveCommandType(path: [String]) -> any ParsableCommand.Type {
+        var current: any ParsableCommand.Type = Self.self
+        for component in path.dropFirst() {
+            guard let match = current.commandDescription.subcommands.first(where: { $0.descriptor.name == component }) else {
+                break
+            }
+            current = match
+        }
+        return current
+    }
+}
+
+/// Helper type for Option wrapper inspection
+public struct OptionWrapperHolder {
+    let storage: Any?
+    let nameSpecifications: [NameSpecification]
+}
+
+/// Helper type for Argument wrapper inspection
+public struct ArgumentWrapperHolder {
+    let storage: Any?
+}
+
+/// Helper type for Flag wrapper inspection
+public struct FlagWrapperHolder {
+    let wrappedValue: Bool
+}
+
+/// Declarative metadata describing a command built with `ParsableCommand`.
+public struct CommandDescription: Sendable {
+    public var commandName: String?
+    public var abstract: String
+    public var discussion: String?
+    public var version: String?
+    public var subcommands: [any ParsableCommand.Type]
+    public var defaultSubcommand: (any ParsableCommand.Type)?
+    public var showHelpOnEmptyInvocation: Bool
+
+    public init(
+        commandName: String? = nil,
+        abstract: String = "",
+        discussion: String? = nil,
+        version: String? = nil,
+        subcommands: [any ParsableCommand.Type] = [],
+        defaultSubcommand: (any ParsableCommand.Type)? = nil,
+        showHelpOnEmptyInvocation: Bool = false)
+    {
+        self.commandName = commandName
+        self.abstract = abstract
+        self.discussion = discussion
+        self.version = version
+        self.subcommands = subcommands
+        self.defaultSubcommand = defaultSubcommand
+        self.showHelpOnEmptyInvocation = showHelpOnEmptyInvocation
+    }
+}
+
+/// Thrown from `ParsableCommand/run()` when user input fails validation.
+public struct ValidationError: Error, LocalizedError, CustomStringConvertible, Sendable {
+    private let message: String
+
+    public init(_ message: String) {
+        self.message = message
+    }
+
+    public var errorDescription: String? { self.message }
+    public var description: String { self.message }
+}
+
+/// Exit sentinel understood by CLI harnesses.
+public struct ExitCode: Error, Equatable, CustomStringConvertible, Sendable {
+    public let rawValue: Int32
+
+    public init(_ rawValue: Int32) {
+        self.rawValue = rawValue
+    }
+
+    public static let success = ExitCode(0)
+    public static let failure = ExitCode(1)
+
+    public var description: String { "ExitCode(\(self.rawValue))" }
+}

package/Packages/Helix/Sources/Helix/Platform/DarwinPlatformContext.swift

@@ -0,0 +1,44 @@
+import Foundation
+
+#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS) || os(visionOS)
+
+import Darwin.C.stdlib
+
+/// Platform context implementation for Apple platforms (Darwin).
+public struct DarwinPlatformContext: PlatformContext {
+
+    /// Creates a new Darwin platform context.
+    public init() {}
+
+    public var arguments: [String] {
+        Array(CommandLine.arguments.dropFirst())
+    }
+
+    public func environmentVariable(_ name: String) -> String? {
+        guard let cString = getenv(name) else { return nil }
+        return String(validatingCString: cString)
+    }
+
+    public var stdin: StdioStream {
+        FileHandleStdioStream(.stdin)
+    }
+
+    public var stdout: StdioStream {
+        FileHandleStdioStream(.stdout)
+    }
+
+    public var stderr: StdioStream {
+        FileHandleStdioStream(.stderr)
+    }
+
+    public func exit(code: Int32) -> Never {
+        Darwin.exit(code)
+    }
+
+    public var currentWorkingDirectory: PlatformPath {
+        let cwd = FileManager.default.currentDirectoryPath
+        return PlatformPath(cwd)
+    }
+}
+
+#endif

package/Packages/Helix/Sources/Helix/Platform/LinuxPlatformContext.swift

@@ -0,0 +1,34 @@
+import Foundation
+
+#if os(Linux)
+
+import Glibc
+
+/// Platform context implementation for Linux.
+public struct LinuxPlatformContext: PlatformContext {
+    public init() {}
+
+    public var arguments: [String] {
+        Array(CommandLine.arguments.dropFirst())
+    }
+
+    public func environmentVariable(_ name: String) -> String? {
+        guard let cString = getenv(name) else { return nil }
+        return String(validatingCString: cString)
+    }
+
+    public var stdin: StdioStream { FileHandleStdioStream(.stdin) }
+    public var stdout: StdioStream { FileHandleStdioStream(.stdout) }
+    public var stderr: StdioStream { FileHandleStdioStream(.stderr) }
+
+    public func exit(code: Int32) -> Never {
+        Glibc.exit(code)
+    }
+
+    public var currentWorkingDirectory: PlatformPath {
+        PlatformPath(FileManager.default.currentDirectoryPath)
+    }
+}
+
+#endif
+

package/Packages/Helix/Sources/Helix/Platform/PlatformContext+Default.swift

@@ -0,0 +1,91 @@
+import Foundation
+
+#if canImport(Glibc)
+import Glibc
+#elseif canImport(Musl)
+import Musl
+#endif
+
+extension PlatformContext {
+    /// The current platform context based on the runtime platform.
+    /// Uses compile-time platform detection to select the appropriate implementation.
+    public static var current: any PlatformContext {
+        DefaultPlatformContext.shared
+    }
+}
+
+// MARK: - Default Platform Context
+
+/// Internal default platform context that selects the appropriate implementation.
+/// Thread-safe singleton using static let (lazy + thread-safe in Swift).
+public struct DefaultPlatformContext: PlatformContext {
+    public static let shared: DefaultPlatformContext = {
+        // Static let is already thread-safe in Swift (guaranteed by the language)
+        DefaultPlatformContext()
+    }()
+
+    private let context: any PlatformContext
+
+    public init() {
+        #if os(macOS) || os(iOS) || os(tvOS) || os(watchOS) || os(visionOS)
+        self.context = DarwinPlatformContext()
+        #elseif os(Linux)
+        self.context = LinuxPlatformContext()
+        #elseif os(Windows)
+        self.context = WindowsPlatformContext()
+        #elseif os(WASI)
+        self.context = WebPlatformContext()
+        #else
+        // Fallback for unknown platforms
+        self.context = FallbackPlatformContext()
+        #endif
+    }
+
+    public var arguments: [String] { context.arguments }
+    public func environmentVariable(_ name: String) -> String? { context.environmentVariable(name) }
+    public var stdin: StdioStream { context.stdin }
+    public var stdout: StdioStream { context.stdout }
+    public var stderr: StdioStream { context.stderr }
+    public func exit(code: Int32) -> Never { context.exit(code: code) }
+    public var currentWorkingDirectory: PlatformPath { context.currentWorkingDirectory }
+}
+
+// MARK: - Fallback Platform Context
+
+/// Fallback platform context for unknown platforms.
+struct FallbackPlatformContext: PlatformContext {
+    var arguments: [String] = []
+    var stdin: StdioStream = FileHandleStdioStream(.stdin)
+    var stdout: StdioStream = FileHandleStdioStream(.stdout)
+    var stderr: StdioStream = FileHandleStdioStream(.stderr)
+
+    func environmentVariable(_ name: String) -> String? {
+        #if canImport(Darwin) || canImport(Glibc) || canImport(Musl)
+        let value = getenv(name)
+        return value.flatMap { String(validatingCString: $0) }
+        #else
+        return nil
+        #endif
+    }
+
+    func exit(code: Int32) -> Never {
+        #if canImport(Darwin)
+        Darwin.exit(code)
+        #elseif canImport(Glibc)
+        Glibc.exit(code)
+        #elseif canImport(Musl)
+        Musl.exit(code)
+        #else
+        // Intentionally trap on platforms without a usable exit().
+        preconditionFailure("exit(code:) is not supported on this platform")
+        #endif
+    }
+
+    var currentWorkingDirectory: PlatformPath {
+        #if canImport(Foundation)
+        return PlatformPath(FileManager.default.currentDirectoryPath)
+        #else
+        return PlatformPath("")
+        #endif
+    }
+}

package/Packages/Helix/Sources/Helix/Platform/PlatformContext.swift

@@ -0,0 +1,94 @@
+import Foundation
+
+#if os(Windows)
+import WinSDK
+#endif
+
+#if canImport(Darwin)
+import Darwin
+#elseif canImport(Glibc)
+import Glibc
+#elseif canImport(Musl)
+import Musl
+#endif
+
+// MARK: - Platform Context Protocol
+
+/// Defines the interface for platform-specific operations.
+/// This protocol abstracts platform differences to enable cross-platform support.
+public protocol PlatformContext: Sendable {
+
+    /// The command-line arguments passed to the program.
+    var arguments: [String] { get }
+
+    /// Retrieves the value of an environment variable.
+    /// - Parameter name: The name of the environment variable.
+    /// - Returns: The value of the variable, or `nil` if not found.
+    func environmentVariable(_ name: String) -> String?
+
+    /// The standard input stream.
+    var stdin: StdioStream { get }
+
+    /// The standard output stream.
+    var stdout: StdioStream { get }
+
+    /// The standard error stream.
+    var stderr: StdioStream { get }
+
+    /// Terminates the program with the given exit code.
+    /// - Parameter code: The exit code to return.
+    func exit(code: Int32) -> Never
+
+    /// The current working directory.
+    var currentWorkingDirectory: PlatformPath { get }
+}
+
+// MARK: - PlatformContext Error
+
+extension PlatformContext {
+    /// Retrieves an environment variable, throwing if not found.
+    /// - Parameter name: The name of the environment variable.
+    /// - Returns: The value of the variable.
+    /// - Throws: `HelixError.missingEnvironmentVariable` if the variable is not set.
+    public func requireEnvironmentVariable(_ name: String) throws -> String {
+        guard let value = environmentVariable(name) else {
+            throw HelixError.missingEnvironmentVariable(name)
+        }
+        return value
+    }
+}
+
+// MARK: - Convenience Properties
+
+extension PlatformContext {
+    /// All environment variables as a dictionary.
+    public var environment: [String: String] {
+        var result: [String: String] = [:]
+        #if os(Windows)
+        guard let envBlock = GetEnvironmentStringsW() else { return result }
+        defer { FreeEnvironmentStringsW(envBlock) }
+        var current = envBlock
+        while current.pointee != 0 {
+            let length = Int(wcslen(current))
+            let entry = String(decoding: UnsafeBufferPointer(start: current, count: length), as: UTF16.self)
+            let parts = entry.split(separator: "=", maxSplits: 1)
+            if parts.count == 2 {
+                result[String(parts[0])] = String(parts[1])
+            }
+            current = current.advanced(by: length + 1)
+        }
+        #else
+        var current = environ
+        while let entry = current.pointee {
+            if let str = String(validatingCString: entry) {
+                let parts = str.split(separator: "=", maxSplits: 1)
+                if parts.count == 2 {
+                    result[String(parts[0])] = String(parts[1])
+                }
+            }
+            current = current.advanced(by: 1)
+        }
+        #endif
+        return result
+    }
+}