@sriinnu/runic 1.0.0

package/Packages/Helix/Sources/Helix/Binding.swift

@@ -0,0 +1,111 @@
+import Foundation
+
+// Internal binding layer that connects ParsedValues to property wrappers.
+// This intentionally avoids Swift SPI/private reflection by using box-backed
+// wrapper storage. Mirror copies can still mutate shared box instances.
+
+protocol _HelixOptionBinding {
+    mutating func _helixBindOption(label: String, values: [String]?, environment: [String: String]) throws
+}
+
+protocol _HelixArgumentBinding {
+    mutating func _helixBindArgument(label: String, positional: [String], index: inout Int, isLast: Bool) throws
+}
+
+protocol _HelixFlagBinding {
+    mutating func _helixBindFlag(label: String, flags: Set<String>)
+}
+
+protocol _HelixOptionGroupBinding {
+    mutating func _helixBindGroup(parsed: ParsedValues, environment: [String: String]) throws
+}
+
+enum _HelixBinder {
+    static func bindCommand<Command>(
+        _ command: inout Command,
+        parsed: ParsedValues,
+        environment: [String: String]
+    ) throws {
+        var argumentBinders: [(label: String, bind: (inout Int, Bool) throws -> Void)] = []
+
+        try walk(
+            command,
+            parsed: parsed,
+            environment: environment,
+            allowArguments: true,
+            argumentBinders: &argumentBinders
+        )
+
+        var index = 0
+        for i in 0..<argumentBinders.count {
+            let isLast = (i == argumentBinders.count - 1)
+            try argumentBinders[i].bind(&index, isLast)
+        }
+
+        if index < parsed.positional.count {
+            let extras = parsed.positional[index...].joined(separator: " ")
+            throw HelixError.parsingError("Unexpected arguments: \(extras)")
+        }
+    }
+
+    static func bindGroupValue<Group>(
+        _ group: Group,
+        parsed: ParsedValues,
+        environment: [String: String]
+    ) throws {
+        var argumentBinders: [(label: String, bind: (inout Int, Bool) throws -> Void)] = []
+        try walk(
+            group,
+            parsed: parsed,
+            environment: environment,
+            allowArguments: false,
+            argumentBinders: &argumentBinders
+        )
+    }
+
+    private static func walk<Value>(
+        _ value: Value,
+        parsed: ParsedValues,
+        environment: [String: String],
+        allowArguments: Bool,
+        argumentBinders: inout [(label: String, bind: (inout Int, Bool) throws -> Void)]
+    ) throws {
+        let mirror = Mirror(reflecting: value)
+        for child in mirror.children {
+            guard let rawLabel = child.label else { continue }
+            let label = sanitize(rawLabel)
+
+            if var option = child.value as? _HelixOptionBinding {
+                try option._helixBindOption(label: label, values: parsed.options[label], environment: environment)
+                continue
+            }
+
+            if var flag = child.value as? _HelixFlagBinding {
+                flag._helixBindFlag(label: label, flags: parsed.flags)
+                continue
+            }
+
+            if let argument = child.value as? _HelixArgumentBinding {
+                if !allowArguments {
+                    throw HelixError.parsingError("Positional arguments are not supported in option groups")
+                }
+                argumentBinders.append(
+                    (label: label, bind: { index, isLast in
+                        var local = argument
+                        try local._helixBindArgument(label: label, positional: parsed.positional, index: &index, isLast: isLast)
+                    })
+                )
+                continue
+            }
+
+            if var group = child.value as? _HelixOptionGroupBinding {
+                try group._helixBindGroup(parsed: parsed, environment: environment)
+                continue
+            }
+        }
+    }
+
+    private static func sanitize(_ label: String) -> String {
+        label.hasPrefix("_") ? String(label.dropFirst()) : label
+    }
+}

package/Packages/Helix/Sources/Helix/CommandParser.swift

@@ -0,0 +1,160 @@
+import Foundation
+
+/// Parsed representation of `argv` after running `CommandParser`.
+public struct ParsedValues: Sendable, Equatable {
+    public var positional: [String]
+    public var options: [String: [String]]
+    public var flags: Set<String>
+
+    public init(positional: [String], options: [String: [String]], flags: Set<String>) {
+        self.positional = positional
+        self.options = options
+        self.flags = flags
+    }
+}
+
+/// Consumes tokenized arguments using a `CommandSignature`.
+public struct CommandParser {
+    let signature: CommandSignature
+
+    public init(signature: CommandSignature) {
+        self.signature = signature
+    }
+
+    public func parse(arguments: [String]) throws -> ParsedValues {
+        let tokens = CommandLineTokenizer.tokenize(arguments)
+        var positional: [String] = []
+        var options: [String: [String]] = [:]
+        var flags = Set<String>()
+
+        let optionLookup = Self.buildOptionLookup(self.signature.options)
+        let flagLookup = Self.buildFlagLookup(self.signature.flags)
+
+        var index = 0
+        while index < tokens.count {
+            let token = tokens[index]
+            index += 1
+            switch token {
+            case let .option(name):
+                if let definition = optionLookup[name] {
+                    guard index < tokens.count else {
+                        throw HelixError.parsingError("Missing value for option \(name)")
+                    }
+                    if case let .argument(value) = tokens[index] {
+                        options[definition.label, default: []].append(value)
+                        index += 1
+                    } else {
+                        throw HelixError.parsingError("Missing value for option \(name)")
+                    }
+                } else if let flagLabel = flagLookup[name] {
+                    flags.insert(flagLabel)
+                } else {
+                    throw HelixError.parsingError("Unknown option --\(name)")
+                }
+            case let .optionWithValue(name, value):
+                if let definition = optionLookup[name] {
+                    options[definition.label, default: []].append(value)
+                } else {
+                    throw HelixError.parsingError("Unknown option --\(name)")
+                }
+            case let .flag(name):
+                guard let flagLabel = flagLookup[name] else {
+                    throw HelixError.parsingError("Unknown option -\(name)")
+                }
+                flags.insert(flagLabel)
+            case let .argument(value):
+                positional.append(value)
+            case .terminator:
+                while index < tokens.count {
+                    if case let .argument(value) = tokens[index] {
+                        positional.append(value)
+                    }
+                    index += 1
+                }
+            }
+        }
+
+        return ParsedValues(positional: positional, options: options, flags: flags)
+    }
+
+    private static func buildOptionLookup(_ definitions: [OptionDefinition]) -> [String: OptionDefinition] {
+        var lookup: [String: OptionDefinition] = [:]
+        for definition in definitions {
+            for name in definition.names {
+                if let longName = name.longComponent {
+                    lookup[longName] = definition
+                } else if let shortName = name.shortComponent {
+                    lookup[String(shortName)] = definition
+                }
+            }
+        }
+        return lookup
+    }
+
+    private static func buildFlagLookup(_ definitions: [FlagDefinition]) -> [String: String] {
+        var lookup: [String: String] = [:]
+        for definition in definitions {
+            for name in definition.names {
+                if let longName = name.longComponent {
+                    lookup[longName] = definition.label
+                } else if let shortName = name.shortComponent {
+                    lookup[String(shortName)] = definition.label
+                }
+            }
+        }
+        return lookup
+    }
+
+}
+
+enum Token: Equatable, Sendable {
+    case option(name: String)
+    case optionWithValue(name: String, value: String)
+    case flag(name: String)
+    case argument(String)
+    case terminator
+}
+
+enum CommandLineTokenizer {
+    static func tokenize(_ argv: [String]) -> [Token] {
+        var result: [Token] = []
+        var iterator = argv.makeIterator()
+        while let segment = iterator.next() {
+            if segment == "--" {
+                result.append(.terminator)
+                result.append(contentsOf: iterator.map { .argument($0) })
+                break
+            } else if segment.hasPrefix("--") {
+                let name = String(segment.dropFirst(2))
+                if let equalsIndex = name.firstIndex(of: "=") {
+                    let option = String(name[..<equalsIndex])
+                    let value = String(name[name.index(after: equalsIndex)...])
+                    result.append(.optionWithValue(name: option, value: value))
+                } else {
+                    result.append(.option(name: name))
+                }
+            } else if segment.hasPrefix("-"), segment.count > 1 {
+                let body = segment.dropFirst()
+                if body.count == 1 {
+                    result.append(.option(name: String(body)))
+                } else if let equalsIndex = body.firstIndex(of: "=") {
+                    let name = String(body[..<equalsIndex])
+                    let value = String(body[body.index(after: equalsIndex)...])
+                    if name.count == 1 {
+                        result.append(.optionWithValue(name: name, value: value))
+                    } else {
+                        // Not a supported form (only -o=value is supported).
+                        result.append(.argument(segment))
+                    }
+                } else {
+                    for char in body {
+                        result.append(.flag(name: String(char)))
+                    }
+                }
+            } else {
+                result.append(.argument(segment))
+            }
+        }
+        return result
+    }
+}

package/Packages/Helix/Sources/Helix/CommandSignature.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+/// Declarative description of all options, flags, and positional arguments.
+public struct CommandSignature: Sendable {
+    public private(set) var arguments: [ArgumentDefinition]
+    public private(set) var options: [OptionDefinition]
+    public private(set) var flags: [FlagDefinition]
+    public private(set) var optionGroups: [CommandSignature]
+
+    public init(
+        arguments: [ArgumentDefinition] = [],
+        options: [OptionDefinition] = [],
+        flags: [FlagDefinition] = [],
+        optionGroups: [CommandSignature] = [])
+    {
+        self.arguments = arguments
+        self.options = options
+        self.flags = flags
+        self.optionGroups = optionGroups
+    }
+
+    mutating func append(_ component: CommandComponent) {
+        switch component {
+        case let .argument(definition):
+            self.arguments.append(definition)
+        case let .option(definition):
+            self.options.append(definition)
+        case let .flag(definition):
+            self.flags.append(definition)
+        case let .group(signature):
+            self.optionGroups.append(signature)
+        }
+    }
+
+    /// Uses reflection to discover Helix property wrappers and build a signature.
+    public static func describe(_ command: some Any) -> CommandSignature {
+        var signature = CommandSignature()
+        Self.inspect(value: command, into: &signature)
+        return signature
+    }
+
+    private static func inspect(value: Any, into signature: inout CommandSignature) {
+        let mirror = Mirror(reflecting: value)
+        for child in mirror.children {
+            guard let label = child.label else { continue }
+            if let registrable = child.value as? HelixMetadata {
+                registrable.register(label: label, signature: &signature)
+            } else if let optionGroup = child.value as? HelixOptionGroup {
+                optionGroup.register(label: label, signature: &signature)
+            }
+        }
+    }
+
+    /// Returns a copy where nested option groups are merged into a single signature.
+    public func flattened() -> CommandSignature {
+        var combined = CommandSignature(
+            arguments: self.arguments,
+            options: self.options,
+            flags: self.flags)
+        for group in self.optionGroups {
+            let flattenedGroup = group.flattened()
+            combined.arguments.append(contentsOf: flattenedGroup.arguments)
+            combined.options.append(contentsOf: flattenedGroup.options)
+            combined.flags.append(contentsOf: flattenedGroup.flags)
+        }
+        return combined
+    }
+}
+
+/// Internal helper used by property wrappers.
+public enum CommandComponent: Sendable {
+    case argument(ArgumentDefinition)
+    case option(OptionDefinition)
+    case flag(FlagDefinition)
+    case group(CommandSignature)
+}
+
+/// Canonical description of an option.
+public struct OptionDefinition: Sendable, Equatable {
+    public let label: String
+    public let names: [HelixName]
+    public let help: String?
+    public let envVar: String?
+
+    public init(label: String, names: [HelixName], help: String?, envVar: String? = nil) {
+        self.label = label
+        self.names = names
+        self.help = help
+        self.envVar = envVar
+    }
+}
+
+/// Canonical description of a positional argument.
+public struct ArgumentDefinition: Sendable, Equatable {
+    public let label: String
+    public let help: String?
+    public let isOptional: Bool
+
+    public init(label: String, help: String?, isOptional: Bool) {
+        self.label = label
+        self.help = help
+        self.isOptional = isOptional
+    }
+}
+
+/// Canonical description of a boolean flag.
+public struct FlagDefinition: Sendable, Equatable {
+    public let label: String
+    public let names: [HelixName]
+    public let help: String?
+
+    public init(label: String, names: [HelixName], help: String?) {
+        self.label = label
+        self.names = names
+        self.help = help
+    }
+}

package/Packages/Helix/Sources/Helix/ExpressibleFromArgument.swift

@@ -0,0 +1,72 @@
+import Foundation
+
+/// Protocol used by Helix property wrappers to convert string arguments into typed values.
+public protocol ExpressibleFromArgument {
+    init?(argument: String)
+}
+
+extension String: ExpressibleFromArgument {
+    public init?(argument: String) { self = argument }
+}
+
+extension Substring: ExpressibleFromArgument {
+    public init?(argument: String) { self = Substring(argument) }
+}
+
+extension Int: ExpressibleFromArgument {
+    public init?(argument: String) { self.init(argument, radix: 10) }
+}
+
+extension Int32: ExpressibleFromArgument {
+    public init?(argument: String) { self.init(argument, radix: 10) }
+}
+
+extension Int64: ExpressibleFromArgument {
+    public init?(argument: String) { self.init(argument, radix: 10) }
+}
+
+extension Double: ExpressibleFromArgument {
+    public init?(argument: String) { self.init(argument) }
+}
+
+extension Float: ExpressibleFromArgument {
+    public init?(argument: String) { self.init(argument) }
+}
+
+extension Bool: ExpressibleFromArgument {
+    public init?(argument: String) {
+        let lowered = argument.lowercased()
+        switch lowered {
+        case "true", "t", "1", "yes", "y":
+            self = true
+        case "false", "f", "0", "no", "n":
+            self = false
+        default:
+            return nil
+        }
+    }
+}
+
+extension Optional: ExpressibleFromArgument where Wrapped: ExpressibleFromArgument {
+    public init?(argument: String) {
+        if let value = Wrapped(argument: argument) {
+            self = .some(value)
+        } else {
+            return nil
+        }
+    }
+}
+
+extension Array: ExpressibleFromArgument where Element: ExpressibleFromArgument {
+    public init?(argument: String) {
+        let parts = argument.split(separator: ",").map { String($0) }
+        var result: [Element] = []
+        for part in parts {
+            guard let value = Element(argument: part) else {
+                return nil
+            }
+            result.append(value)
+        }
+        self = result
+    }
+}

package/Packages/Helix/Sources/Helix/HelpGenerator.swift

@@ -0,0 +1,175 @@
+import Foundation
+
+/// Generates help text for commands.
+public struct HelpGenerator {
+    /// The command descriptor to generate help for.
+    public let descriptor: CommandDescriptor
+
+    /// Creates a new help generator.
+    public init(descriptor: CommandDescriptor) {
+        self.descriptor = descriptor
+    }
+
+    /// Generates the full help text.
+    public var output: String {
+        var result = ""
+
+        // Usage line
+        result += "USAGE: \(generateUsage())\n\n"
+
+        // Abstract
+        if !descriptor.abstract.isEmpty {
+            result += "\(descriptor.abstract)\n\n"
+        }
+
+        // Discussion
+        if let discussion = descriptor.discussion, !discussion.isEmpty {
+            result += "\(discussion)\n\n"
+        }
+
+        // Options
+        let flattened = descriptor.signature.flattened()
+        if !flattened.options.isEmpty || !flattened.flags.isEmpty {
+            result += "OPTIONS:\n"
+            for option in flattened.options {
+                result += "  \(formatOption(option))\n"
+            }
+            for flag in flattened.flags {
+                result += "  \(formatFlag(flag))\n"
+            }
+            result += "\n"
+        }
+
+        // Arguments
+        if !flattened.arguments.isEmpty {
+            result += "ARGUMENTS:\n"
+            for arg in flattened.arguments {
+                result += "  \(formatArgument(arg))\n"
+            }
+            result += "\n"
+        }
+
+        // Subcommands
+        if !descriptor.subcommands.isEmpty {
+            result += "SUBCOMMANDS:\n"
+            for subcommand in descriptor.subcommands {
+                result += "  \(subcommand.name)"
+                if !subcommand.abstract.isEmpty {
+                    result += " - \(subcommand.abstract)"
+                }
+                result += "\n"
+            }
+        }
+
+        return result
+    }
+
+    private func generateUsage() -> String {
+        var parts: [String] = [descriptor.name]
+
+        // Add subcommands hint
+        if !descriptor.subcommands.isEmpty {
+            parts.append("<subcommand>")
+        }
+
+        let flattened = descriptor.signature.flattened()
+
+        // Add flags
+        for flag in flattened.flags {
+            if let flagName = preferredFlagUsageName(flag.names) {
+                parts.append("[\(flagName)]")
+            }
+        }
+
+        // Add options (simplified - just shows placeholders)
+        for option in flattened.options {
+            let optionName = preferredOptionUsageName(option.names) ?? "--\(option.label)"
+            parts.append("[\(optionName) <\(option.label)>]")
+        }
+
+        // Add required arguments
+        for arg in flattened.arguments where !arg.isOptional {
+            parts.append("<\(arg.label)>")
+        }
+
+        // Add optional arguments
+        for arg in flattened.arguments where arg.isOptional {
+            parts.append("[\(arg.label)]")
+        }
+
+        return parts.joined(separator: " ")
+    }
+
+    private func formatOption(_ option: OptionDefinition) -> String {
+        var parts: [String] = []
+
+        for name in option.names {
+            if let short = name.shortComponent {
+                parts.append("-\(short) <\(option.label)>")
+            }
+            if let long = name.longComponent {
+                parts.append("--\(long) <\(option.label)>")
+            }
+        }
+
+        let joined = parts.joined(separator: ", ")
+        return formatHelpLine(joined, help: option.help)
+    }
+
+    private func formatFlag(_ flag: FlagDefinition) -> String {
+        var parts: [String] = []
+
+        for name in flag.names {
+            if let short = name.shortComponent {
+                parts.append("-\(short)")
+            }
+            if let long = name.longComponent {
+                parts.append("--\(long)")
+            }
+        }
+
+        let joined = parts.joined(separator: ", ")
+        return formatHelpLine(joined, help: flag.help)
+    }
+
+    private func formatArgument(_ arg: ArgumentDefinition) -> String {
+        let label = arg.isOptional ? "[\(arg.label)]" : "<\(arg.label)>"
+        return formatHelpLine(label, help: arg.help)
+    }
+
+    private func formatHelpLine(_ label: String, help: String?) -> String {
+        guard let help else { return label }
+        let width = 40
+        let paddingCount = max(1, width - label.count)
+        return label + String(repeating: " ", count: paddingCount) + help
+    }
+
+    private func preferredFlagUsageName(_ names: [HelixName]) -> String? {
+        if let short = names.first(where: { $0.shortComponent != nil })?.shortComponent {
+            return "-\(short)"
+        }
+        if let long = names.first(where: { $0.longComponent != nil })?.longComponent {
+            return "--\(long)"
+        }
+        return nil
+    }
+
+    private func preferredOptionUsageName(_ names: [HelixName]) -> String? {
+        if let long = names.first(where: { $0.longComponent != nil })?.longComponent {
+            return "--\(long)"
+        }
+        if let short = names.first(where: { $0.shortComponent != nil })?.shortComponent {
+            return "-\(short)"
+        }
+        return nil
+    }
+}
+
+// MARK: - Help Text Generation Helper
+
+extension HelixError {
+    /// Generates help text for the given descriptor.
+    public static func helpText(for descriptor: CommandDescriptor) -> String {
+        HelpGenerator(descriptor: descriptor).output
+    }
+}