@sriinnu/runic 1.0.0

package/Packages/Helix/Sources/Helix/Program.swift

@@ -0,0 +1,204 @@
+import Foundation
+
+/// Describes a `ParsableCommand` so the lightweight `Program` router can
+/// resolve `argv` without instantiating the command immediately.
+public struct CommandDescriptor: Sendable {
+    public let name: String
+    public let abstract: String
+    public let discussion: String?
+    public let signature: CommandSignature
+    public let subcommands: [CommandDescriptor]
+    public let defaultSubcommandName: String?
+
+    public init(
+        name: String,
+        abstract: String,
+        discussion: String?,
+        signature: CommandSignature,
+        subcommands: [CommandDescriptor] = [],
+        defaultSubcommandName: String? = nil)
+    {
+        self.name = name
+        self.abstract = abstract
+        self.discussion = discussion
+        self.signature = signature
+        self.subcommands = subcommands
+        self.defaultSubcommandName = defaultSubcommandName
+    }
+}
+
+/// The fully resolved command plus the parsed values for the original `argv`.
+public struct CommandInvocation: Sendable {
+    public let descriptor: CommandDescriptor
+    public let parsedValues: ParsedValues
+    public let path: [String]
+
+    public init(descriptor: CommandDescriptor, parsedValues: ParsedValues, path: [String]) {
+        self.descriptor = descriptor
+        self.parsedValues = parsedValues
+        self.path = path
+    }
+}
+
+/// Errors surfaced while resolving a command path prior to running user code.
+public enum HelixError: Error, CustomStringConvertible, Sendable, Equatable {
+    case missingCommand
+    case unknownCommand(String)
+    case missingSubcommand(command: String)
+    case unknownSubcommand(command: String, name: String)
+    case parsingError(String)
+    case missingEnvironmentVariable(String)
+    case webAssemblyExit(Int32)
+    case optionNotBound(String)
+    case argumentNotBound(String)
+    case validationError(String)
+    case helpRequested
+    case versionRequested
+
+    public var description: String {
+        switch self {
+        case .missingCommand:
+            "No command specified"
+        case let .unknownCommand(name):
+            "Unknown command '\(name)'"
+        case let .missingSubcommand(command):
+            "Command '\(command)' requires a subcommand"
+        case let .unknownSubcommand(command, name):
+            "Unknown subcommand '\(name)' for command '\(command)'"
+        case let .parsingError(error):
+            error
+        case let .missingEnvironmentVariable(name):
+            "Missing environment variable '\(name)'"
+        case let .webAssemblyExit(code):
+            "WebAssembly exit with code \(code)"
+        case let .optionNotBound(type):
+            "Option of type '\(type)' was accessed before being parsed"
+        case let .argumentNotBound(type):
+            "Argument of type '\(type)' was accessed before being parsed"
+        case let .validationError(message):
+            "Validation error: \(message)"
+        case .helpRequested:
+            "Help was requested"
+        case .versionRequested:
+            "Version was requested"
+        }
+    }
+}
+
+/// Resolves `CommandLine.arguments` into concrete commands using descriptors.
+public struct Program: Sendable {
+    private let descriptorLookup: [String: CommandDescriptor]
+
+    public init(descriptors: [CommandDescriptor]) {
+        self.descriptorLookup = Dictionary(uniqueKeysWithValues: descriptors.map { ($0.name, $0) })
+    }
+
+    /// Walks the command tree, parses any remaining arguments, and returns a
+    /// `CommandInvocation` ready to `run()`.
+    public func resolve(argv: [String]) throws -> CommandInvocation {
+        var args = normalizedArguments(argv)
+
+        guard let command = try selectRootCommand(arguments: &args) else {
+            throw HelixError.missingCommand
+        }
+        var remainingArguments = args
+        var commandPath = [command.name]
+        let descriptor = try self.resolveDescriptor(command, arguments: &remainingArguments, path: &commandPath)
+        let parser = CommandParser(signature: descriptor.signature.flattened())
+        let parsed = try parser.parse(arguments: remainingArguments)
+        return CommandInvocation(descriptor: descriptor, parsedValues: parsed, path: commandPath)
+    }
+
+    private func resolveDescriptor(
+        _ descriptor: CommandDescriptor,
+        arguments: inout [String],
+        path: inout [String],
+        stopAtHelpOrVersion: Bool = false) throws -> CommandDescriptor
+    {
+        if stopAtHelpOrVersion, let nextToken = arguments.first, Self.isHelpOrVersionToken(nextToken) {
+            return descriptor
+        }
+
+        guard !descriptor.subcommands.isEmpty else {
+            return descriptor
+        }
+
+        if arguments.isEmpty {
+            if let defaultChild = lookupDefaultSubcommand(for: descriptor) {
+                path.append(defaultChild.name)
+                return try self.resolveDescriptor(defaultChild, arguments: &arguments, path: &path, stopAtHelpOrVersion: stopAtHelpOrVersion)
+            }
+            throw HelixError.missingSubcommand(command: descriptor.name)
+        }
+
+        let nextToken = arguments[0]
+        if nextToken.starts(with: "-") {
+            if stopAtHelpOrVersion, Self.isHelpOrVersionToken(nextToken) {
+                return descriptor
+            }
+            if let defaultChild = lookupDefaultSubcommand(for: descriptor) {
+                path.append(defaultChild.name)
+                return try self.resolveDescriptor(defaultChild, arguments: &arguments, path: &path, stopAtHelpOrVersion: stopAtHelpOrVersion)
+            }
+            throw HelixError.missingSubcommand(command: descriptor.name)
+        }
+
+        guard let match = descriptor.subcommands.first(where: { $0.name == nextToken }) else {
+            throw HelixError.unknownSubcommand(command: descriptor.name, name: nextToken)
+        }
+        arguments.removeFirst()
+        path.append(match.name)
+        return try self.resolveDescriptor(match, arguments: &arguments, path: &path, stopAtHelpOrVersion: stopAtHelpOrVersion)
+    }
+
+    private func lookupDefaultSubcommand(for descriptor: CommandDescriptor) -> CommandDescriptor? {
+        guard let name = descriptor.defaultSubcommandName else { return nil }
+        return descriptor.subcommands.first(where: { $0.name == name })
+    }
+
+    internal func resolveDescriptorForHelp(arguments: [String]) throws -> CommandDescriptor {
+        var args = arguments
+        guard let command = try selectRootCommand(arguments: &args) else {
+            throw HelixError.missingCommand
+        }
+        var commandPath = [command.name]
+        return try resolveDescriptor(command, arguments: &args, path: &commandPath, stopAtHelpOrVersion: true)
+    }
+
+    internal func normalizedArguments(_ argv: [String]) -> [String] {
+        var args = argv
+        guard let first = args.first else { return [] }
+        if descriptorLookup[first] != nil {
+            return args
+        }
+        let looksLikeExecutable = first.contains("/") || first.contains("\\") || first.hasSuffix(".exe")
+        let nextIsCommand = args.count > 1 && descriptorLookup[args[1]] != nil
+        if looksLikeExecutable || nextIsCommand {
+            args.removeFirst()
+        }
+        return args
+    }
+
+    private func selectRootCommand(arguments: inout [String]) throws -> CommandDescriptor? {
+        if let name = arguments.first, let match = descriptorLookup[name] {
+            arguments.removeFirst()
+            return match
+        }
+        if descriptorLookup.count == 1, let sole = descriptorLookup.values.first {
+            return sole
+        }
+        if let name = arguments.first {
+            throw HelixError.unknownCommand(name)
+        }
+        return nil
+    }
+
+    private static func isHelpOrVersionToken(_ token: String) -> Bool {
+        switch token {
+        case "-h", "--help", "-V", "--version":
+            return true
+        default:
+            return false
+        }
+    }
+}

package/Packages/Helix/Sources/Helix/PropertyWrappers.swift

@@ -0,0 +1,367 @@
+import Foundation
+
+/// Declares a named option (short/long) that can parse arbitrary value types.
+@propertyWrapper
+public struct Option<Value: ExpressibleFromArgument>: HelixMetadata {
+    final class _Box: @unchecked Sendable {
+        var value: Value?
+        var environmentValue: Value?
+        var parsedFromArgs: Bool
+        let hasDefault: Bool
+
+        init(value: Value?, environmentValue: Value?, parsedFromArgs: Bool, hasDefault: Bool) {
+            self.value = value
+            self.environmentValue = environmentValue
+            self.parsedFromArgs = parsedFromArgs
+            self.hasDefault = hasDefault
+        }
+    }
+
+    private var box: _Box
+    private let nameSpecifications: [NameSpecification]
+    private let help: String?
+    private let envVar: String?
+
+    /// Returns the stored value, environment value, or nil if optional.
+    /// Crashes with a helpful message if accessed before being bound and not optional.
+    public var wrappedValue: Value {
+        get {
+            if let value = box.value { return value }
+            if let envValue = box.environmentValue { return envValue }
+            // For optional types, return nil
+            if Value.self is OptionalProtocol.Type {
+                return (nil as Value?)!
+            }
+            // This should not happen in normal usage - options are bound during parsing
+            fatalError("Helix option '\(Value.self)' accessed before being parsed. This is a development error.")
+        }
+        set {
+            self.box.value = newValue
+            self.box.parsedFromArgs = true
+        }
+    }
+
+    public init(wrappedValue: Value, name: NameSpecification = .automatic, help: String? = nil, envVar: String? = nil) {
+        self.box = _Box(value: wrappedValue, environmentValue: nil, parsedFromArgs: false, hasDefault: true)
+        self.nameSpecifications = [name]
+        self.help = help
+        self.envVar = envVar
+    }
+
+    public init(name: NameSpecification = .automatic, help: String? = nil, envVar: String? = nil) {
+        self.box = _Box(value: nil, environmentValue: nil, parsedFromArgs: false, hasDefault: false)
+        self.nameSpecifications = [name]
+        self.help = help
+        self.envVar = envVar
+    }
+
+    public init(names: [NameSpecification], help: String? = nil, envVar: String? = nil) {
+        self.box = _Box(value: nil, environmentValue: nil, parsedFromArgs: false, hasDefault: false)
+        self.nameSpecifications = names
+        self.help = help
+        self.envVar = envVar
+    }
+
+    /// Sets the environment variable value to use as fallback.
+    /// This is called by the parser after binding.
+    mutating func setEnvironmentValue(_ value: Value?) {
+        self.box.environmentValue = value
+    }
+
+    /// Returns true if this option was parsed from arguments.
+    public var wasParsed: Bool {
+        box.parsedFromArgs || box.environmentValue != nil
+    }
+
+    public func register(label: String, signature: inout CommandSignature) {
+        let resolvedLabel = Self.sanitize(label)
+        let resolvedNames = self.nameSpecifications.flatMap { $0.resolve(defaultLabel: resolvedLabel) }
+        let definition = OptionDefinition(label: resolvedLabel, names: resolvedNames, help: help, envVar: envVar)
+        signature.append(.option(definition))
+    }
+
+    private static func sanitize(_ label: String) -> String {
+        label.hasPrefix("_") ? String(label.dropFirst()) : label
+    }
+}
+
+extension Option: Sendable where Value: Sendable {}
+
+/// Declares a positional argument, optionally optional.
+@propertyWrapper
+public struct Argument<Value: ExpressibleFromArgument>: HelixMetadata {
+    final class _Box: @unchecked Sendable {
+        var value: Value?
+        var parsedFromArgs: Bool
+        let hasDefault: Bool
+
+        init(value: Value?, parsedFromArgs: Bool, hasDefault: Bool) {
+            self.value = value
+            self.parsedFromArgs = parsedFromArgs
+            self.hasDefault = hasDefault
+        }
+    }
+
+    private var box: _Box
+    private let help: String?
+
+    /// Returns the stored value or nil if optional.
+    /// Crashes with a helpful message if accessed before being bound.
+    public var wrappedValue: Value {
+        get {
+            if let value = box.value { return value }
+            // For optional types, return nil
+            if Value.self is OptionalProtocol.Type {
+                return (nil as Value?)!
+            }
+            // This should not happen in normal usage
+            fatalError("Helix argument '\(Value.self)' accessed before being parsed. This is a development error.")
+        }
+        set {
+            self.box.value = newValue
+            self.box.parsedFromArgs = true
+        }
+    }
+
+    public init(wrappedValue: Value, help: String? = nil) {
+        self.box = _Box(value: wrappedValue, parsedFromArgs: false, hasDefault: true)
+        self.help = help
+    }
+
+    public init(help: String? = nil) {
+        self.box = _Box(value: nil, parsedFromArgs: false, hasDefault: false)
+        self.help = help
+    }
+
+    /// Returns true if this argument was parsed from arguments.
+    public var wasParsed: Bool {
+        box.parsedFromArgs
+    }
+
+    public func register(label: String, signature: inout CommandSignature) {
+        let resolvedLabel = Self.sanitize(label)
+        let definition = ArgumentDefinition(
+            label: resolvedLabel,
+            help: help,
+            isOptional: Value.self is OptionalProtocol.Type)
+        signature.append(.argument(definition))
+    }
+
+    private static func sanitize(_ label: String) -> String {
+        label.hasPrefix("_") ? String(label.dropFirst()) : label
+    }
+}
+
+extension Argument: Sendable where Value: Sendable {}
+
+/// Declares a boolean flag that defaults to `false` and toggles to `true` when present.
+@propertyWrapper
+public struct Flag: HelixMetadata, Sendable {
+    final class _Box: @unchecked Sendable {
+        var value: Bool
+        init(_ value: Bool) { self.value = value }
+    }
+
+    private var box: _Box
+    private let nameSpecifications: [NameSpecification]
+    private let help: String?
+
+    public init(wrappedValue: Bool = false, name: NameSpecification = .automatic, help: String? = nil) {
+        self.box = _Box(wrappedValue)
+        self.nameSpecifications = [name]
+        self.help = help
+    }
+
+    public init(wrappedValue: Bool = false, names: [NameSpecification], help: String? = nil) {
+        self.box = _Box(wrappedValue)
+        self.nameSpecifications = names
+        self.help = help
+    }
+
+    public var wrappedValue: Bool {
+        get { box.value }
+        set { box.value = newValue }
+    }
+
+    public func register(label: String, signature: inout CommandSignature) {
+        let resolvedLabel = Self.sanitize(label)
+        let definition = FlagDefinition(
+            label: resolvedLabel,
+            names: nameSpecifications.flatMap { $0.resolve(defaultLabel: resolvedLabel) },
+            help: self.help)
+        signature.append(.flag(definition))
+    }
+
+    private static func sanitize(_ label: String) -> String {
+        label.hasPrefix("_") ? String(label.dropFirst()) : label
+    }
+}
+
+/// Provides nested Helix metadata so you can keep related parameters together.
+@propertyWrapper
+public struct OptionGroup<Value: HelixParsable>: HelixOptionGroup {
+    final class _Box: @unchecked Sendable {
+        var value: Value
+        init(_ value: Value) { self.value = value }
+    }
+
+    private var box: _Box
+
+    public var wrappedValue: Value {
+        get { box.value }
+        set { box.value = newValue }
+    }
+
+    public init(wrappedValue: Value) {
+        self.box = _Box(wrappedValue)
+    }
+
+    public init() where Value: HelixParsable {
+        self.box = _Box(Value())
+    }
+
+    public func register(label: String, signature: inout CommandSignature) {
+        let groupSignature = CommandSignature.describe(self.wrappedValue)
+        signature.append(.group(groupSignature))
+    }
+}
+
+extension OptionGroup: Sendable where Value: Sendable {}
+
+/// Marker protocol for option-group structs.
+public protocol HelixParsable {
+    init()
+}
+
+protocol HelixMetadata {
+    func register(label: String, signature: inout CommandSignature)
+}
+
+protocol HelixOptionGroup {
+    func register(label: String, signature: inout CommandSignature)
+}
+
+protocol DefaultInitializable {
+    init()
+}
+
+/// Note: HelixParsable already requires init(), so no additional implementation is needed.
+/// This protocol exists for potential future use cases.
+
+protocol OptionalProtocol {}
+extension Optional: OptionalProtocol {}
+
+// MARK: - Binding conformance
+
+protocol _HelixOptionMultiValueParser {
+    static func _helixParseOption(values: [String]) -> Any?
+}
+
+protocol _HelixPositionalArrayParser {
+    static func _helixParsePositional(values: [String]) -> Any?
+}
+
+extension Array: _HelixOptionMultiValueParser where Element: ExpressibleFromArgument {
+    static func _helixParseOption(values: [String]) -> Any? {
+        var result: [Element] = []
+        for value in values {
+            let parts = value.split(separator: ",").map(String.init)
+            for part in parts {
+                guard let parsed = Element(argument: part) else { return nil }
+                result.append(parsed)
+            }
+        }
+        return result
+    }
+}
+
+extension Array: _HelixPositionalArrayParser where Element: ExpressibleFromArgument {
+    static func _helixParsePositional(values: [String]) -> Any? {
+        var result: [Element] = []
+        for value in values {
+            guard let parsed = Element(argument: value) else { return nil }
+            result.append(parsed)
+        }
+        return result
+    }
+}
+
+extension Option: _HelixOptionBinding {
+    mutating func _helixBindOption(label: String, values: [String]?, environment: [String: String]) throws {
+        if let values, !values.isEmpty {
+            if let parser = Value.self as? _HelixOptionMultiValueParser.Type {
+                guard let parsed = parser._helixParseOption(values: values) as? Value else {
+                    throw HelixError.parsingError("Invalid value for option \(label)")
+                }
+                box.value = parsed
+            } else {
+                guard let last = values.last, let parsed = Value(argument: last) else {
+                    throw HelixError.parsingError("Invalid value for option \(label)")
+                }
+                box.value = parsed
+            }
+            box.parsedFromArgs = true
+            return
+        }
+
+        if let envVar, let envValue = environment[envVar] {
+            guard let parsed = Value(argument: envValue) else {
+                throw HelixError.parsingError("Invalid value for environment variable \(envVar)")
+            }
+            box.environmentValue = parsed
+        }
+
+        let isOptional = Value.self is OptionalProtocol.Type
+        if !isOptional, !box.hasDefault, box.value == nil, box.environmentValue == nil {
+            throw HelixError.parsingError("Missing value for option \(label)")
+        }
+    }
+}
+
+extension Argument: _HelixArgumentBinding {
+    mutating func _helixBindArgument(label: String, positional: [String], index: inout Int, isLast: Bool) throws {
+        if let parser = Value.self as? _HelixPositionalArrayParser.Type {
+            guard isLast else {
+                throw HelixError.parsingError("Variadic argument \(label) must be last")
+            }
+            let remaining = index < positional.count ? Array(positional[index...]) : []
+            guard let parsed = parser._helixParsePositional(values: remaining) as? Value else {
+                throw HelixError.parsingError("Invalid value for argument \(label)")
+            }
+            box.value = parsed
+            box.parsedFromArgs = true
+            index = positional.count
+            return
+        }
+
+        if index >= positional.count {
+            let isOptional = Value.self is OptionalProtocol.Type
+            if isOptional || box.hasDefault {
+                return
+            }
+            throw HelixError.parsingError("Missing argument \(label)")
+        }
+
+        let raw = positional[index]
+        index += 1
+        guard let parsed = Value(argument: raw) else {
+            throw HelixError.parsingError("Invalid value for argument \(label)")
+        }
+        box.value = parsed
+        box.parsedFromArgs = true
+    }
+}
+
+extension Flag: _HelixFlagBinding {
+    mutating func _helixBindFlag(label: String, flags: Set<String>) {
+        if flags.contains(label) {
+            box.value = true
+        }
+    }
+}
+
+extension OptionGroup: _HelixOptionGroupBinding {
+    mutating func _helixBindGroup(parsed: ParsedValues, environment: [String: String]) throws {
+        try _HelixBinder.bindGroupValue(wrappedValue, parsed: parsed, environment: environment)
+    }
+}

package/Packages/Silo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Srinivas Pendela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Packages/Silo/Package.swift

@@ -0,0 +1,34 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "Silo",
+    platforms: [
+        .macOS(.v13),
+        .iOS(.v16),
+    ],
+    products: [
+        .library(name: "Silo", targets: ["Silo"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/krzyzanowskim/CryptoSwift.git", from: "1.8.4"),
+    ],
+    targets: [
+        .target(
+            name: "Silo",
+            dependencies: [
+                .product(name: "CryptoSwift", package: "CryptoSwift"),
+            ],
+            path: "Sources/Silo",
+            swiftSettings: [
+                .enableExperimentalFeature("StrictConcurrency"),
+            ]),
+        .testTarget(
+            name: "SiloTests",
+            dependencies: ["Silo"],
+            path: "Tests/SiloTests",
+            resources: [
+                .copy("Fixtures"),
+            ]),
+    ],
+    swiftLanguageModes: [.v6])