From d821c8d14eaea20523a0b878d8d9a75ddd81b582 Mon Sep 17 00:00:00 2001 From: Leo Dion Date: Sun, 8 Feb 2026 21:53:30 -0500 Subject: [PATCH 1/9] Add skit-analyze implementation plan and dependencies - Add comprehensive plan for skit-analyze CLI tool (Docs/skit-analyze-plan.md) - Tool will auto-generate updated SyntaxKit library from DSL specifications - Uses Claude API to analyze gaps and generate implementation code - Add ConfigKeyKit to Sources/ for configuration management - Add swift-configuration documentation for reference - Input: folder with dsl.swift + expected.swift (AST auto-generated) - Output: updated SyntaxKit library ready to build Co-Authored-By: Claude Sonnet 4.5 --- ...ation-1.0.0-documentation-configuration.md | 13333 ++++++++++++++++ Docs/skit-analyze-plan.md | 954 ++ Sources/ConfigKeyKit/Command.swift | 61 + .../ConfigKeyKit/CommandConfiguration.swift | 39 + Sources/ConfigKeyKit/CommandLineParser.swift | 74 + Sources/ConfigKeyKit/CommandRegistry.swift | 88 + .../ConfigKeyKit/CommandRegistryError.swift | 42 + Sources/ConfigKeyKit/ConfigKey+Bool.swift | 72 + Sources/ConfigKeyKit/ConfigKey+Debug.swift | 36 + Sources/ConfigKeyKit/ConfigKey.swift | 113 + Sources/ConfigKeyKit/ConfigKeySource.swift | 39 + Sources/ConfigKeyKit/ConfigurationKey.swift | 40 + .../ConfigKeyKit/ConfigurationParseable.swift | 54 + Sources/ConfigKeyKit/NamingStyle.swift | 38 + .../OptionalConfigKey+Debug.swift | 36 + Sources/ConfigKeyKit/OptionalConfigKey.swift | 103 + .../ConfigKeyKit/StandardNamingStyle.swift | 53 + 17 files changed, 15175 insertions(+) create mode 100644 .claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md create mode 100644 Docs/skit-analyze-plan.md create mode 100644 Sources/ConfigKeyKit/Command.swift create mode 100644 Sources/ConfigKeyKit/CommandConfiguration.swift create mode 100644 Sources/ConfigKeyKit/CommandLineParser.swift create mode 100644 Sources/ConfigKeyKit/CommandRegistry.swift create mode 100644 Sources/ConfigKeyKit/CommandRegistryError.swift create mode 100644 Sources/ConfigKeyKit/ConfigKey+Bool.swift create mode 100644 Sources/ConfigKeyKit/ConfigKey+Debug.swift create mode 100644 Sources/ConfigKeyKit/ConfigKey.swift create mode 100644 Sources/ConfigKeyKit/ConfigKeySource.swift create mode 100644 Sources/ConfigKeyKit/ConfigurationKey.swift create mode 100644 Sources/ConfigKeyKit/ConfigurationParseable.swift create mode 100644 Sources/ConfigKeyKit/NamingStyle.swift create mode 100644 Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift create mode 100644 Sources/ConfigKeyKit/OptionalConfigKey.swift create mode 100644 Sources/ConfigKeyKit/StandardNamingStyle.swift diff --git a/.claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md b/.claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md new file mode 100644 index 00000000..d3c4c9b8 --- /dev/null +++ b/.claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md @@ -0,0 +1,13333 @@ + + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration + +Library + +# Configuration + +A Swift library for reading configuration in applications and libraries. + +## Overview + +Swift Configuration defines an abstraction between configuration _readers_ and _providers_. + +Applications and libraries _read_ configuration through a consistent API, while the actual _provider_ is set up once at the application’s entry point. + +For example, to read the timeout configuration value for an HTTP client, check out the following examples using different providers: + +# Environment variables: +HTTP_TIMEOUT=30 +let provider = EnvironmentVariablesProvider() +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +# Program invoked with: +program --http-timeout 30 +let provider = CommandLineArgumentsProvider() +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +{ +"http": { +"timeout": 30 +} +} + +filePath: "/etc/config.json" +) +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +{ +"http": { +"timeout": 30 +} +} + +filePath: "/etc/config.json" +) +// Omitted: Add `provider` to a ServiceGroup +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +http: +timeout: 30 + +filePath: "/etc/config.yaml" +) +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +http: +timeout: 30 + +filePath: "/etc/config.yaml" +) +// Omitted: Add `provider` to a ServiceGroup +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +/ +|-- run +|-- secrets +|-- http-timeout + +Contents of the file `/run/secrets/http-timeout`: `30`. + +let provider = try await DirectoryFilesProvider( +directoryPath: "/run/secrets" +) +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +// Environment variables consulted first, then JSON. +let primaryProvider = EnvironmentVariablesProvider() + +filePath: "/etc/config.json" +) +let config = ConfigReader(providers: [\ +primaryProvider,\ +secondaryProvider\ +]) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 +let provider = InMemoryProvider(values: [\ +"http.timeout": 30,\ +]) +let config = ConfigReader(provider: provider) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print(httpTimeout) // prints 30 + +For a selection of more detailed examples, read through Example use cases. + +For a video introduction, check out our talk on YouTube. + +These providers can be combined to form a hierarchy, for details check out Provider hierarchy. + +### Quick start + +Add the dependency to your `Package.swift`: + +.package(url: "https://github.com/apple/swift-configuration", from: "1.0.0") + +Add the library dependency to your target: + +.product(name: "Configuration", package: "swift-configuration") + +Import and use in your code: + +import Configuration + +let config = ConfigReader(provider: EnvironmentVariablesProvider()) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) +print("The HTTP timeout is: \(httpTimeout)") + +### Package traits + +This package offers additional integrations you can enable using package traits. To enable an additional trait on the package, update the package dependency: + +.package( +url: "https://github.com/apple/swift-configuration", +from: "1.0.0", ++ traits: [.defaults, "YAML"] +) + +Available traits: + +- **`JSON`** (default): Adds support for `JSONSnapshot`, which enables using `FileProvider` and `ReloadingFileProvider` with JSON files. + +- **`Logging`** (opt-in): Adds support for `AccessLogger`, a way to emit access events into a Swift Log `Logger`. + +- **`Reloading`** (opt-in): Adds support for `ReloadingFileProvider`, which provides auto-reloading capability for file-based configuration. + +- **`CommandLineArguments`** (opt-in): Adds support for `CommandLineArgumentsProvider` for parsing command line arguments. + +- **`YAML`** (opt-in): Adds support for `YAMLSnapshot`, which enables using `FileProvider` and `ReloadingFileProvider` with YAML files. + +### Supported platforms and minimum versions + +The library is supported on Apple platforms and Linux. + +| Component | macOS | Linux | iOS | tvOS | watchOS | visionOS | +| --- | --- | --- | --- | --- | --- | --- | +| Configuration | ✅ 15+ | ✅ | ✅ 18+ | ✅ 18+ | ✅ 11+ | ✅ 2+ | + +#### Three access patterns + +The library provides three distinct ways to read configuration values: + +- **Get**: Synchronously return the current value available locally, in memory: + +let timeout = config.int(forKey: "http.timeout", default: 60) + +- **Fetch**: Asynchronously get the most up-to-date value from disk or a remote server: + +let timeout = try await config.fetchInt(forKey: "http.timeout", default: 60) + +- **Watch**: Receive updates when a configuration value changes: + +try await config.watchInt(forKey: "http.timeout", default: 60) { updates in +for try await timeout in updates { +print("HTTP timeout updated to: \(timeout)") +} +} + +For detailed guidance on when to use each access pattern, see Choosing the access pattern. Within each of the access patterns, the library offers different reader methods that reflect your needs of optional, default, and required configuration parameters. To understand the choices available, see Choosing reader methods. + +#### Providers + +The library includes comprehensive built-in provider support: + +- Environment variables: `EnvironmentVariablesProvider` + +- Command-line arguments: `CommandLineArgumentsProvider` + +- JSON file: `FileProvider` and `ReloadingFileProvider` with `JSONSnapshot` + +- YAML file: `FileProvider` and `ReloadingFileProvider` with `YAMLSnapshot` + +- Directory of files: `DirectoryFilesProvider` + +- In-memory: `InMemoryProvider` and `MutableInMemoryProvider` + +- Key transforming: `KeyMappingProvider` + +You can also implement a custom `ConfigProvider`. + +#### Provider hierarchy + +In addition to using providers individually, you can create fallback behavior using an array of providers. The first provider that returns a non-nil value wins. + +The following example shows a provider hierarchy where environment variables take precedence over command line arguments, a JSON file, and in-memory defaults: + +// Create a hierarchy of providers with fallback behavior. +let config = ConfigReader(providers: [\ +// First, check environment variables.\ +EnvironmentVariablesProvider(),\ +// Then, check command-line options.\ +CommandLineArgumentsProvider(),\ +// Then, check a JSON config file.\ + +// Finally, fall \ +]) + +// Uses the first provider that has a value for "http.timeout". +let timeout = config.int(forKey: "http.timeout", default: 15) + +#### Hot reloading + +Long-running services can periodically reload configuration with `ReloadingFileProvider`: + +// Omitted: add provider to a ServiceGroup +let config = ConfigReader(provider: provider) + +Read Using reloading providers for details on how to receive updates as configuration changes. + +#### Namespacing and scoped readers + +The built-in namespacing of `ConfigKey` interprets `"http.timeout"` as an array of two components: `"http"` and `"timeout"`. The following example uses `scoped(to:)` to create a namespaced reader with the key `"http"`, to allow reads to use the shorter key `"timeout"`: + +Consider the following JSON configuration: + +{ +"http": { +"timeout": 60 +} +} +// Create the root reader. +let config = ConfigReader(provider: provider) + +// Create a scoped reader for HTTP settings. +let httpConfig = config.scoped(to: "http") + +// Now you can access values with shorter keys. +// Equivalent to reading "http.timeout" on the root reader. +let timeout = httpConfig.int(forKey: "timeout") + +#### Debugging and troubleshooting + +Debugging with `AccessReporter` makes it possible to log all accesses to a config reader: + +let logger = Logger(label: "config") +let config = ConfigReader( +provider: provider, +accessReporter: AccessLogger(logger: logger) +) +// Now all configuration access is logged, with secret values redacted + +You can also add the following environment variable, and emit log accesses into a file without any code changes: + +CONFIG_ACCESS_LOG_FILE=/var/log/myapp/config-access.log + +and then read the file: + +tail -f /var/log/myapp/config-access.log + +Check out the built-in `AccessLogger`, `FileAccessLogger`, and Troubleshooting and access reporting. + +#### Secrets handling + +The library provides built-in support for handling sensitive configuration values securely: + +// Mark sensitive values as secrets to prevent them from appearing in logs +let privateKey = try snapshot.requiredString(forKey: "mtls.privateKey", isSecret: true) +let optionalAPIToken = config.string(forKey: "api.token", isSecret: true) + +When values are marked as secrets, they are automatically redacted from access logs and debugging output. Read Handling secrets correctly for guidance on best practices for secrets management. + +#### Consistent snapshots + +Retrieve related values from a consistent snapshot using `ConfigSnapshotReader`, which you get by calling `snapshot()`. + +This ensures that multiple values are read from a single snapshot inside each provider, even when using providers that update their internal values. For example by downloading new data periodically: + +let config = /* a reader with one or more providers that change values over time */ +let snapshot = config.snapshot() +let certificate = try snapshot.requiredString(forKey: "mtls.certificate") +let privateKey = try snapshot.requiredString(forKey: "mtls.privateKey", isSecret: true) +// `certificate` and `privateKey` are guaranteed to come from the same snapshot in the provider + +#### Extensible ecosystem + +Any package can implement a `ConfigProvider`, making the ecosystem extensible for custom configuration sources. + +## Topics + +### Essentials + +Configuring applications + +Provide flexible and consistent configuration for your application. + +Configuring libraries + +Provide a consistent and flexible way to configure your library. + +Example use cases + +Review common use cases with ready-to-copy code samples. + +Adopting best practices + +Follow these principles to make your code easily configurable and composable with other libraries. + +### Readers and providers + +`struct ConfigReader` + +A type that provides read-only access to configuration values from underlying providers. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`struct ConfigSnapshotReader` + +A container type for reading config values from snapshots. + +Choosing the access pattern + +Learn how to select the right method for reading configuration values based on your needs. + +Choosing reader methods + +Choose between optional, default, and required variants of configuration methods. + +Handling secrets correctly + +Protect sensitive configuration values from accidental disclosure in logs and debug output. + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +### Configuration keys + +`struct ConfigKey` + +A configuration key representing a relative path to a configuration value. + +`struct AbsoluteConfigKey` + +A configuration key that represents an absolute path to a configuration value. + +`enum ConfigContextValue` + +A value that can be stored in a configuration context. + +### Troubleshooting and access reporting + +Troubleshooting and access reporting + +Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. + +`protocol AccessReporter` + +A type that receives and processes configuration access events. + +`class AccessLogger` + +An access reporter that logs configuration access events using the Swift Log API. + +`class FileAccessLogger` + +An access reporter that writes configuration access events to a file. + +`struct AccessEvent` + +An event that captures information about accessing a configuration value. + +`struct BroadcastingAccessReporter` + +An access reporter that forwards events to multiple other reporters. + +### Value conversion + +`protocol ExpressibleByConfigString` + +A protocol for types that can be initialized from configuration string values. + +`protocol ConfigBytesFromStringDecoder` + +A protocol for decoding string configuration values into byte arrays. + +`struct ConfigBytesFromBase64StringDecoder` + +A decoder that converts base64-encoded strings into byte arrays. + +`struct ConfigBytesFromHexStringDecoder` + +A decoder that converts hexadecimal-encoded strings into byte arrays. + +### Contributing + +Developing Swift Configuration + +Learn about tools and conventions used to develop the Swift Configuration package. + +Collaborate on API changes to Swift Configuration by writing a proposal. + +### Extended Modules + +Foundation + +SystemPackage + +- Configuration +- Overview +- Quick start +- Package traits +- Supported platforms and minimum versions +- Key features +- Topics + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/handling-secrets-correctly + +- Configuration +- Handling secrets correctly + +Article + +# Handling secrets correctly + +Protect sensitive configuration values from accidental disclosure in logs and debug output. + +## Overview + +Swift Configuration provides built-in support for marking sensitive values as secrets. Secret values are automatically redacted by access reporters to prevent accidental disclosure of API keys, passwords, and other sensitive information. + +### Marking values as secret when reading + +Use the `isSecret` parameter on any configuration reader method to mark a value as secret: + +let config = ConfigReader(provider: provider) + +// Mark sensitive values as secret +let apiKey = try config.requiredString( +forKey: "api.key", +isSecret: true +) +let dbPassword = config.string( +forKey: "database.password", +isSecret: true +) + +// Regular values don't need the parameter +let serverPort = try config.requiredInt(forKey: "server.port") +let logLevel = config.string( +forKey: "log.level", +default: "info" +) + +This works with all access patterns and method variants: + +// Works with fetch and watch too +let latestKey = try await config.fetchRequiredString( +forKey: "api.key", +isSecret: true +) + +try await config.watchString( +forKey: "api.key", +isSecret: true +) { updates in +for await key in updates { +// Handle secret key updates +} +} + +### Provider-level secret specification + +Use `SecretsSpecifier` to automatically mark values as secret based on keys or content when creating providers: + +#### Mark all values as secret + +The following example marks all configuration read by the `DirectoryFilesProvider` as secret: + +let provider = DirectoryFilesProvider( +directoryPath: "/run/secrets", +secretsSpecifier: .all +) + +#### Mark specific keys as secret + +The following example marks three specific keys from a provider as secret: + +let provider = EnvironmentVariablesProvider( +secretsSpecifier: .specific(["API_KEY", "DATABASE_PASSWORD", "JWT_SECRET"]) +) + +#### Dynamic secret detection + +The following example marks keys as secret based on the closure you provide. In this case, keys that contain `password`, `secret`, or `token` are all marked as secret: + +filePath: "/etc/config.json", +secretsSpecifier: .dynamic { key, value in +key.lowercased().contains("password") || +key.lowercased().contains("secret") || +key.lowercased().contains("token") +} +) + +#### No secret values + +The following example asserts that none of the values returned from the provider are considered secret: + +filePath: "/etc/config.json", +secretsSpecifier: .none +) + +### For provider implementors + +When implementing a custom `ConfigProvider`, use the `ConfigValue` type’s `isSecret` property: + +// Create a secret value +let secretValue = ConfigValue("sensitive-data", isSecret: true) + +// Create a regular value +let regularValue = ConfigValue("public-data", isSecret: false) + +Set the `isSecret` property to `true` when your provider knows the values are read from a secrets store and must not be logged. + +### How secret values are protected + +Secret values are automatically handled by: + +- **`AccessLogger`** and **`FileAccessLogger`**: Redact secret values in logs. + +print(provider) + +### Best practices + +1. **Mark all sensitive data as secret**: API keys, passwords, tokens, private keys, connection strings. + +2. **Use provider-level specification** when you know which keys are always secret. + +3. **Use reader-level marking** for context-specific secrets or when the same key might be secret in some contexts but not others. + +4. **Be conservative**: When in doubt, mark values as secret. It’s safer than accidentally leaking sensitive data. + +For additional guidance on configuration security and overall best practices, see Adopting best practices. To debug issues with secret redaction in access logs, check out Troubleshooting and access reporting. When selecting between required, optional, and default method variants for secret values, refer to Choosing reader methods. + +## See Also + +### Readers and providers + +`struct ConfigReader` + +A type that provides read-only access to configuration values from underlying providers. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`struct ConfigSnapshotReader` + +A container type for reading config values from snapshots. + +Choosing the access pattern + +Learn how to select the right method for reading configuration values based on your needs. + +Choosing reader methods + +Choose between optional, default, and required variants of configuration methods. + +- Handling secrets correctly +- Overview +- Marking values as secret when reading +- Provider-level secret specification +- For provider implementors +- How secret values are protected +- Best practices +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot + +- Configuration +- YAMLSnapshot + +Class + +# YAMLSnapshot + +A snapshot of configuration values parsed from YAML data. + +final class YAMLSnapshot + +YAMLSnapshot.swift + +## Mentioned in + +Using reloading providers + +## Overview + +This class represents a point-in-time view of configuration values. It handles the conversion from YAML types to configuration value types. + +## Usage + +Use with `FileProvider` or `ReloadingFileProvider`: + +let config = ConfigReader(provider: provider) + +## Topics + +### Creating a YAML snapshot + +`convenience init(data: RawSpan, providerName: String, parsingOptions: YAMLSnapshot.ParsingOptions) throws` + +`struct ParsingOptions` + +Custom input configuration for YAML snapshot creation. + +### Snapshot configuration + +`protocol FileConfigSnapshot` + +A protocol for configuration snapshots created from file data. + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +### Instance Properties + +`let providerName: String` + +The name of the provider that created this snapshot. + +## Relationships + +### Conforms To + +- `ConfigSnapshot` +- `FileConfigSnapshot` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- YAMLSnapshot +- Mentioned in +- Overview +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting + +Library + +# ConfigurationTesting + +A set of testing utilities for Swift Configuration adopters. + +## Overview + +This testing library adds a Swift Testing-based `ConfigProvider` compatibility suite, recommended for implementors of custom configuration providers. + +## Topics + +### Structures + +`struct ProviderCompatTest` + +A comprehensive test suite for validating `ConfigProvider` implementations. + +- ConfigurationTesting +- Overview +- Topics + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accesslogger + +- Configuration +- AccessLogger + +Class + +# AccessLogger + +An access reporter that logs configuration access events using the Swift Log API. + +final class AccessLogger + +AccessLogger.swift + +## Mentioned in + +Handling secrets correctly + +Troubleshooting and access reporting + +Configuring libraries + +## Overview + +This reporter integrates with the Swift Log library to provide structured logging of configuration accesses. Each configuration access generates a log entry with detailed metadata about the operation, making it easy to track configuration usage and debug issues. + +## Package traits + +This type is guarded by the `Logging` package trait. + +## Usage + +Create an access logger and pass it to your configuration reader: + +import Logging + +let logger = Logger(label: "config.access") +let accessLogger = AccessLogger(logger: logger, level: .info) +let config = ConfigReader( +provider: EnvironmentVariablesProvider(), +accessReporter: accessLogger +) + +## Log format + +Each access event generates a structured log entry with metadata including: + +- `kind`: The type of access operation (get, fetch, watch). + +- `key`: The configuration key that was accessed. + +- `location`: The source code location where the access occurred. + +- `value`: The resolved configuration value (redacted for secrets). + +- `counter`: An incrementing counter for tracking access frequency. + +- Provider-specific information for each provider in the hierarchy. + +## Topics + +### Creating an access logger + +`init(logger: Logger, level: Logger.Level, message: Logger.Message)` + +Creates a new access logger that reports configuration access events. + +## Relationships + +### Conforms To + +- `AccessReporter` +- `Swift.Copyable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Troubleshooting and access reporting + +Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. + +`protocol AccessReporter` + +A type that receives and processes configuration access events. + +`class FileAccessLogger` + +An access reporter that writes configuration access events to a file. + +`struct AccessEvent` + +An event that captures information about accessing a configuration value. + +`struct BroadcastingAccessReporter` + +An access reporter that forwards events to multiple other reporters. + +- AccessLogger +- Mentioned in +- Overview +- Package traits +- Usage +- Log format +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider + +- Configuration +- ReloadingFileProvider + +Class + +# ReloadingFileProvider + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +ReloadingFileProvider.swift + +## Mentioned in + +Using reloading providers + +Choosing the access pattern + +Troubleshooting and access reporting + +## Overview + +`ReloadingFileProvider` is a generic file-based configuration provider that monitors a configuration file for changes and automatically reloads the data when the file is modified. This provider works with different file formats by using different snapshot types that conform to `FileConfigSnapshot`. + +## Usage + +Create a reloading provider by specifying the snapshot type and file path: + +// Using with a JSON snapshot and a custom poll interval + +filePath: "/etc/config.json", +pollInterval: .seconds(30) +) + +// Using with a YAML snapshot + +filePath: "/etc/config.yaml" +) + +## Service integration + +This provider implements the `Service` protocol and must be run within a `ServiceGroup` to enable automatic reloading: + +let serviceGroup = ServiceGroup(services: [provider], logger: logger) +try await serviceGroup.run() + +The provider monitors the file by polling at the specified interval (default: 15 seconds) and notifies any active watchers when changes are detected. + +## Configuration from a reader + +You can also initialize the provider using a configuration reader: + +let envConfig = ConfigReader(provider: EnvironmentVariablesProvider()) + +This expects a `filePath` key in the configuration that specifies the path to the file. For a full list of configuration keys, check out `init(snapshotType:parsingOptions:config:)`. + +## File monitoring + +The provider detects changes by monitoring both file timestamps and symlink target changes. When a change is detected, it reloads the file and notifies all active watchers of the updated configuration values. + +## Topics + +### Creating a reloading file provider + +`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool, pollInterval: Duration, logger: Logger, metrics: any MetricsFactory) async throws` + +Creates a reloading file provider that monitors the specified file path. + +`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader, logger: Logger, metrics: any MetricsFactory) async throws` + +Creates a reloading file provider using configuration from a reader. + +### Service lifecycle + +`func run() async throws` + +### Monitoring file changes + +`protocol FileConfigSnapshot` + +A protocol for configuration snapshots created from file data. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +### Instance Properties + +`let providerName: String` + +The human-readable name of the provider. + +## Relationships + +### Conforms To + +- `ConfigProvider` +Conforms when `Snapshot` conforms to `FileConfigSnapshot`. + +- `ServiceLifecycle.Service` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- ReloadingFileProvider +- Mentioned in +- Overview +- Usage +- Service integration +- Configuration from a reader +- File monitoring +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot + +- Configuration +- JSONSnapshot + +Structure + +# JSONSnapshot + +A snapshot of configuration values parsed from JSON data. + +struct JSONSnapshot + +JSONSnapshot.swift + +## Mentioned in + +Example use cases + +Using reloading providers + +## Overview + +This structure represents a point-in-time view of configuration values. It handles the conversion from JSON types to configuration value types. + +## Usage + +Use with `FileProvider` or `ReloadingFileProvider`: + +let config = ConfigReader(provider: provider) + +## Topics + +### Creating a JSON snapshot + +`init(data: RawSpan, providerName: String, parsingOptions: JSONSnapshot.ParsingOptions) throws` + +`struct ParsingOptions` + +Parsing options for JSON snapshot creation. + +### Snapshot configuration + +`protocol FileConfigSnapshot` + +A protocol for configuration snapshots created from file data. + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +### Instance Properties + +`let providerName: String` + +The name of the provider that created this snapshot. + +## Relationships + +### Conforms To + +- `ConfigSnapshot` +- `FileConfigSnapshot` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- JSONSnapshot +- Mentioned in +- Overview +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider + +- Configuration +- FileProvider + +Structure + +# FileProvider + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +FileProvider.swift + +## Mentioned in + +Example use cases + +Troubleshooting and access reporting + +## Overview + +`FileProvider` is a generic file-based configuration provider that works with different file formats by using different snapshot types that conform to `FileConfigSnapshot`. This allows for a unified interface for reading JSON, YAML, or other structured configuration files. + +## Usage + +Create a provider by specifying the snapshot type and file path: + +// Using with a JSON snapshot + +filePath: "/etc/config.json" +) + +// Using with a YAML snapshot + +filePath: "/etc/config.yaml" +) + +The provider reads the file once during initialization and creates an immutable snapshot of the configuration values. For auto-reloading behavior, use `ReloadingFileProvider`. + +## Configuration from a reader + +You can also initialize the provider using a configuration reader that specifies the file path through environment variables or other configuration sources: + +let envConfig = ConfigReader(provider: EnvironmentVariablesProvider()) + +This expects a `filePath` key in the configuration that specifies the path to the file. For a full list of configuration keys, check out `init(snapshotType:parsingOptions:config:)`. + +## Topics + +### Creating a file provider + +`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool) async throws` + +Creates a file provider that reads from the specified file path. + +`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader) async throws` + +Creates a file provider using a file path from a configuration reader. + +### Reading configuration files + +`protocol FileConfigSnapshot` + +A protocol for configuration snapshots created from file data. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +## Relationships + +### Conforms To + +- `ConfigProvider` +Conforms when `Snapshot` conforms to `FileConfigSnapshot`. + +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- FileProvider +- Mentioned in +- Overview +- Usage +- Configuration from a reader +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/example-use-cases + +- Configuration +- Example use cases + +Article + +# Example use cases + +Review common use cases with ready-to-copy code samples. + +## Overview + +For complete working examples with step-by-step instructions, see the Examples directory in the repository. + +### Reading from environment variables + +Use `EnvironmentVariablesProvider` to read configuration values from environment variables where your app launches. The following example creates a `ConfigReader` with an environment variable provider, and reads the key `server.port`, providing a default value of `8080`: + +import Configuration + +let config = ConfigReader(provider: EnvironmentVariablesProvider()) +let port = config.int(forKey: "server.port", default: 8080) + +The default environment key encoder uses an underscore to separate key components, making the environment variable name above `SERVER_PORT`. + +### Reading from a JSON configuration file + +You can store multiple configuration values together in a JSON file and read them from the fileystem using `FileProvider` with `JSONSnapshot`. The following example creates a `ConfigReader` for a JSON file at the path `/etc/config.json`, and reads a url and port number collected as properties of the `database` JSON object: + +let config = ConfigReader( + +) + +// Access nested values using dot notation. +let databaseURL = config.string(forKey: "database.url", default: "localhost") +let databasePort = config.int(forKey: "database.port", default: 5432) + +The matching JSON for this configuration might look like: + +{ +"database": { +"url": "localhost", +"port": 5432 +} +} + +### Reading from a directory of secret files + +Use the `DirectoryFilesProvider` to read multiple values collected together in a directory on the fileystem, each in a separate file. The default directory key encoder uses a hyphen in the filename to separate key components. The following example uses the directory `/run/secrets` as a base, and reads the file `database-password` as the key `database.password`: + +// Common pattern for secrets downloaded by an init container. +let config = ConfigReader( +provider: try await DirectoryFilesProvider( +directoryPath: "/run/secrets" +) +) + +// Reads the file `/run/secrets/database-password` +let dbPassword = config.string(forKey: "database.password") + +This pattern is useful for reading secrets that your infrastructure makes available on the file system, such as Kubernetes secrets mounted into a container’s filesystem. + +### Handling optional configuration files + +File-based providers support an `allowMissing` parameter to control whether missing files should throw an error or be treated as empty configuration. This is useful when configuration files are optional. + +When `allowMissing` is `false` (the default), missing files throw an error: + +// This will throw an error if config.json doesn't exist +let config = ConfigReader( + +filePath: "/etc/config.json", +allowMissing: false // This is the default +) +) + +When `allowMissing` is `true`, missing files are treated as empty configuration: + +// This won't throw if config.json is missing - treats it as empty +let config = ConfigReader( + +filePath: "/etc/config.json", +allowMissing: true +) +) + +// Returns the default value if the file is missing +let port = config.int(forKey: "server.port", default: 8080) + +The same applies to other file-based providers: + +// Optional secrets directory +let secretsConfig = ConfigReader( +provider: try await DirectoryFilesProvider( +directoryPath: "/run/secrets", +allowMissing: true +) +) + +// Optional environment file +let envConfig = ConfigReader( +provider: try await EnvironmentVariablesProvider( +environmentFilePath: "/etc/app.env", +allowMissing: true +) +) + +// Optional reloading configuration +let reloadingConfig = ConfigReader( + +filePath: "/etc/dynamic-config.yaml", +allowMissing: true +) +) + +### Setting up a fallback hierarchy + +Use multiple providers together to provide a configuration hierarchy that can override values at different levels. The following example uses both an environment variable provider and a JSON provider together, with values from environment variables overriding values from the JSON file. In this example, the defaults are provided using an `InMemoryProvider`, which are only read if the environment variable or the JSON key don’t exist: + +let config = ConfigReader(providers: [\ +// First check environment variables.\ +EnvironmentVariablesProvider(),\ +// Then check the config file.\ + +// Finally, use hardcoded defaults.\ +InMemoryProvider(values: [\ +"app.name": "MyApp",\ +"server.port": 8080,\ +"logging.level": "info"\ +])\ +]) + +### Fetching a value from a remote source + +You can host dynamic configuration that your app can retrieve remotely and use either the “fetch” or “watch” access pattern. The following example uses the “fetch” access pattern to asynchronously retrieve a configuration from the remote provider: + +let myRemoteProvider = MyRemoteProvider(...) +let config = ConfigReader(provider: myRemoteProvider) + +// Makes a network call to retrieve the up-to-date value. +let samplingRatio = try await config.fetchDouble(forKey: "sampling.ratio") + +### Watching for configuration changes + +You can periodically update configuration values using a reloading provider. The following example reloads a YAML file from the filesystem every 30 seconds, and illustrates using `watchInt(forKey:isSecret:fileID:line:updatesHandler:)` to provide an async sequence of updates that you can apply. + +import Configuration +import ServiceLifecycle + +// Create a reloading YAML provider + +filePath: "/etc/app-config.yaml", +pollInterval: .seconds(30) +) +// Omitted: add `provider` to the ServiceGroup. + +let config = ConfigReader(provider: provider) + +// Watch for timeout changes and update HTTP client configuration. +// Needs to run in a separate task from the provider. +try await config.watchInt(forKey: "http.requestTimeout", default: 30) { updates in +for await timeout in updates { +print("HTTP request timeout updated: \(timeout)s") +// Update HTTP client timeout configuration in real-time +} +} + +For details on reloading providers and ServiceLifecycle integration, see Using reloading providers. + +### Prefixing configuration keys + +In most cases, the configuration key provided by the reader can be directly used by the provided, for example `http.timeout` used as the environment variable name `HTTP_TIMEOUT`. + +Sometimes you might need to transform the incoming keys in some way, before they get delivered to the provider. A common example is prefixing each key with a constant prefix, for example `myapp`, turning the key `http.timeout` to `myapp.http.timeout`. + +You can use `KeyMappingProvider` and related extensions on `ConfigProvider` to achieve that. + +The following example uses the key mapping provider to adjust an environment variable provider to look for keys with the prefix `myapp`: + +// Create a base provider for environment variables +let envProvider = EnvironmentVariablesProvider() + +// Wrap it with a key mapping provider to automatically prepend "myapp." to all keys +let prefixedProvider = envProvider.prefixKeys(with: "myapp") + +let config = ConfigReader(provider: prefixedProvider) + +// This reads from the "MYAPP_DATABASE_URL" environment variable. +let databaseURL = config.string(forKey: "database.url", default: "localhost") + +For more configuration guidance, see Adopting best practices. To understand different reader method variants, check out Choosing reader methods. + +## See Also + +### Essentials + +Configuring applications + +Provide flexible and consistent configuration for your application. + +Configuring libraries + +Provide a consistent and flexible way to configure your library. + +Adopting best practices + +Follow these principles to make your code easily configurable and composable with other libraries. + +- Example use cases +- Overview +- Reading from environment variables +- Reading from a JSON configuration file +- Reading from a directory of secret files +- Handling optional configuration files +- Setting up a fallback hierarchy +- Fetching a value from a remote source +- Watching for configuration changes +- Prefixing configuration keys +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/scoped(to:) + +#app-main) + +- Configuration +- ConfigReader +- scoped(to:) + +Instance Method + +# scoped(to:) + +Returns a scoped config reader with the specified key appended to the current prefix. + +ConfigReader.swift + +## Parameters + +`configKey` + +The key components to append to the current key prefix. + +## Return Value + +A config reader for accessing values within the specified scope. + +## Discussion + +let httpConfig = config.scoped(to: ConfigKey(["http", "client"])) +let timeout = httpConfig.int(forKey: "timeout", default: 30) // Reads "http.client.timeout" + +- scoped(to:) +- Parameters +- Return Value +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider + +- Configuration +- EnvironmentVariablesProvider + +Structure + +# EnvironmentVariablesProvider + +A configuration provider that sources values from environment variables. + +struct EnvironmentVariablesProvider + +EnvironmentVariablesProvider.swift + +## Mentioned in + +Troubleshooting and access reporting + +Configuring applications + +Example use cases + +## Overview + +This provider reads configuration values from environment variables, supporting both the current process environment and `.env` files. It automatically converts hierarchical configuration keys into standard environment variable naming conventions and handles type conversion for all supported configuration value types. + +## Key transformation + +Configuration keys are transformed into environment variable names using these rules: + +- Components are joined with underscores + +- All characters are converted to uppercase + +- CamelCase is detected and word boundaries are marked with underscores + +- Non-alphanumeric characters are replaced with underscores + +For example: `http.serverTimeout` becomes `HTTP_SERVER_TIMEOUT` + +## Supported data types + +The provider supports all standard configuration types: + +- Strings, integers, doubles, and booleans + +- Arrays of strings, integers, doubles, and booleans (comma-separated by default) + +- Byte arrays (base64-encoded by default) + +- Arrays of byte chunks + +## Secret handling + +Environment variables can be marked as secrets using a `SecretsSpecifier`. Secret values are automatically redacted in debug output and logging. + +## Usage + +### Reading environment variables in the current process + +// Assuming the environment contains the following variables: +// HTTP_CLIENT_USER_AGENT=Config/1.0 (Test) +// HTTP_CLIENT_TIMEOUT=15.0 +// HTTP_SECRET=s3cret +// HTTP_VERSION=2 +// ENABLED=true + +let provider = EnvironmentVariablesProvider( +secretsSpecifier: .specific(["HTTP_SECRET"]) +) +// Prints all values, redacts "HTTP_SECRET" automatically. +print(provider) +let config = ConfigReader(provider: provider) +let isEnabled = config.bool(forKey: "enabled", default: false) +let userAgent = config.string(forKey: "http.client.user-agent", default: "unspecified") +// ... + +### Reading environment variables from a \`.env\`-style file + +// Assuming the local file system has a file called `.env` in the current working directory +// with the following contents: +// +// HTTP_CLIENT_USER_AGENT=Config/1.0 (Test) +// HTTP_CLIENT_TIMEOUT=15.0 +// HTTP_SECRET=s3cret +// HTTP_VERSION=2 +// ENABLED=true + +let provider = try await EnvironmentVariablesProvider( +environmentFilePath: ".env", +secretsSpecifier: .specific(["HTTP_SECRET"]) +) +// Prints all values, redacts "HTTP_SECRET" automatically. +print(provider) +let config = ConfigReader(provider: provider) +let isEnabled = config.bool(forKey: "enabled", default: false) +let userAgent = config.string(forKey: "http.client.user-agent", default: "unspecified") +// ... + +### Config context + +The environment variables provider ignores the context passed in `context`. + +## Topics + +### Creating an environment variable provider + +Creates a new provider that reads from the current process environment. + +Creates a new provider from a custom dictionary of environment variables. + +Creates a new provider that reads from an environment file. + +### Inspecting an environment variable provider + +Returns the raw string value for a specific environment variable name. + +## Relationships + +### Conforms To + +- `ConfigProvider` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- EnvironmentVariablesProvider +- Mentioned in +- Overview +- Key transformation +- Supported data types +- Secret handling +- Usage +- Reading environment variables in the current process +- Reading environment variables from a \`.env\`-style file +- Config context +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey + +- Configuration +- ConfigKey + +Structure + +# ConfigKey + +A configuration key representing a relative path to a configuration value. + +struct ConfigKey + +ConfigKey.swift + +## Overview + +Configuration keys consist of hierarchical string components forming paths similar to file system paths or JSON object keys. For example, `["http", "timeout"]` represents the `timeout` value nested under `http`. + +Keys support additional context information that providers can use to refine lookups or provide specialized behavior. + +## Usage + +Create keys using string literals, arrays, or the initializers: + +let key1: ConfigKey = "database.connection.timeout" +let key2 = ConfigKey(["api", "endpoints", "primary"]) +let key3 = ConfigKey("server.port", context: ["environment": .string("production")]) + +## Topics + +### Creating a configuration key + +[`init(String, context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-6vten) + +Creates a new configuration key. + +[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-9ifez) + +### Inspecting a configuration key + +[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/components) + +The hierarchical components that make up this configuration key. + +[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/context) + +Additional context information for this configuration key. + +## Relationships + +### Conforms To + +- `Swift.Comparable` +- `Swift.Copyable` +- `Swift.CustomStringConvertible` +- `Swift.Equatable` +- `Swift.ExpressibleByArrayLiteral` +- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` +- `Swift.ExpressibleByStringLiteral` +- `Swift.ExpressibleByUnicodeScalarLiteral` +- `Swift.Hashable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Configuration keys + +`struct AbsoluteConfigKey` + +A configuration key that represents an absolute path to a configuration value. + +`enum ConfigContextValue` + +A value that can be stored in a configuration context. + +- ConfigKey +- Overview +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider + +- Configuration +- CommandLineArgumentsProvider + +Structure + +# CommandLineArgumentsProvider + +A configuration provider that sources values from command-line arguments. + +struct CommandLineArgumentsProvider + +CommandLineArgumentsProvider.swift + +## Overview + +Reads configuration values from CLI arguments with type conversion and secrets handling. Keys are encoded to CLI flags at lookup time. + +## Package traits + +This type is guarded by the `CommandLineArgumentsSupport` package trait. + +## Key formats + +- `--key value` \- A key-value pair with separate arguments. + +- `--key=value` \- A key-value pair with an equals sign. + +- `--flag` \- A Boolean flag, treated as `true`. + +- `--key val1 val2` \- Multiple values (arrays). + +Configuration keys are transformed to CLI flags: `["http", "serverTimeout"]` → `--http-server-timeout`. + +## Array handling + +Arrays can be specified in multiple ways: + +- **Space-separated**: `--tags swift configuration cli` + +- **Repeated flags**: `--tags swift --tags configuration --tags cli` + +- **Comma-separated**: `--tags swift,configuration,cli` + +- **Mixed**: `--tags swift,configuration --tags cli` + +All formats produce the same result when accessed as an array type. + +## Usage + +// CLI: program --debug --host localhost --ports 8080 8443 +let provider = CommandLineArgumentsProvider() +let config = ConfigReader(provider: provider) + +let isDebug = config.bool(forKey: "debug", default: false) // true +let host = config.string(forKey: "host", default: "0.0.0.0") // "localhost" +let ports = config.intArray(forKey: "ports", default: []) // [8080, 8443] + +### With secrets + +let provider = CommandLineArgumentsProvider( +secretsSpecifier: .specific(["--api-key"]) +) + +### Custom arguments + +let provider = CommandLineArgumentsProvider( +arguments: ["program", "--verbose", "--timeout", "30"], +secretsSpecifier: .dynamic { key, _ in key.contains("--secret") } +) + +## Topics + +### Creating a command line arguments provider + +Creates a new CLI provider with the provided arguments. + +## Relationships + +### Conforms To + +- `ConfigProvider` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- CommandLineArgumentsProvider +- Overview +- Package traits +- Key formats +- Array handling +- Usage +- With secrets +- Custom arguments +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/choosing-reader-methods + +- Configuration +- Choosing reader methods + +Article + +# Choosing reader methods + +Choose between optional, default, and required variants of configuration methods. + +## Overview + +For every configuration access pattern (get, fetch, watch) and data type, Swift Configuration provides three method variants that handle missing or invalid values differently: + +- **Optional variant**: Returns `nil` when a value is missing or cannot be converted. + +- **Default variant**: Returns a fallback value when a value is missing or cannot be converted. + +- **Required variant**: Throws an error when a value is missing or cannot be converted. + +Understanding these variants helps you write robust configuration code that handles missing values appropriately for your use case. + +### Optional variants + +Optional variants return `nil` when a configuration value is missing or cannot be converted to the expected type. These methods have the simplest signatures and are ideal when configuration values are truly optional. + +let config = ConfigReader(provider: EnvironmentVariablesProvider()) + +// Optional get +let timeout: Int? = config.int(forKey: "http.timeout") +let apiUrl: String? = config.string(forKey: "api.url") + +// Optional fetch +let latestTimeout: Int? = try await config.fetchInt(forKey: "http.timeout") + +// Optional watch +try await config.watchInt(forKey: "http.timeout") { updates in +for await timeout in updates { +if let timeout = timeout { +print("Timeout is set to: \(timeout)") +} else { +print("No timeout configured") +} +} +} + +#### When to use + +Use optional variants when: + +- **Truly optional features**: The configuration controls optional functionality. + +- **Gradual rollouts**: New configuration that might not be present everywhere. + +- **Conditional behavior**: Your code can operate differently based on presence or absence. + +- **Debugging and diagnostics**: You want to detect missing configuration explicitly. + +#### Error handling behavior + +Optional variants handle errors gracefully by returning `nil`: + +- Missing values return `nil`. + +- Type conversion errors return `nil`. + +- Provider errors return `nil` (except for fetch variants, which always propagate provider errors). + +// These all return nil instead of throwing +let missingPort = config.int(forKey: "nonexistent.port") // nil +let invalidPort = config.int(forKey: "invalid.port.value") // nil (if value can't convert to Int) +let failingPort = config.int(forKey: "provider.error.key") // nil (if provider fails) + +// Fetch variants still throw provider errors +do { +let port = try await config.fetchInt(forKey: "network.error") // Throws provider error +} catch { +// Handle network or provider errors +} + +### Default variants + +Default variants return a specified fallback value when a configuration value is missing or cannot be converted. These provide guaranteed non-optional results while handling missing configuration gracefully. + +// Default get +let timeout = config.int(forKey: "http.timeout", default: 30) +let retryCount = config.int(forKey: "network.retries", default: 3) + +// Default fetch +let latestTimeout = try await config.fetchInt(forKey: "http.timeout", default: 30) + +// Default watch +try await config.watchInt(forKey: "http.timeout", default: 30) { updates in +for await timeout in updates { +print("Using timeout: \(timeout)") // Always has a value +connectionManager.setTimeout(timeout) +} +} + +#### When to use + +Use default variants when: + +- **Sensible defaults exist**: You have reasonable fallback values for missing configuration. + +- **Simplified code flow**: You want to avoid optional handling in business logic. + +- **Required functionality**: The feature needs a value to operate, but can use defaults. + +- **Configuration evolution**: New settings that should work with older deployments. + +#### Choosing good defaults + +Consider these principles when choosing default values: + +// Safe defaults that won't cause issues +let timeout = config.int(forKey: "http.timeout", default: 30) // Reasonable timeout +let maxRetries = config.int(forKey: "retries.max", default: 3) // Conservative retry count +let cacheSize = config.int(forKey: "cache.size", default: 1000) // Modest cache size + +// Environment-specific defaults +let logLevel = config.string(forKey: "log.level", default: "info") // Safe default level +let enableDebug = config.bool(forKey: "debug.enabled", default: false) // Secure default + +// Performance defaults that err on the side of caution +let batchSize = config.int(forKey: "batch.size", default: 100) // Small safe batch +let maxConnections = config.int(forKey: "pool.max", default: 10) // Conservative pool + +#### Error handling behavior + +Default variants handle errors by returning the default value: + +- Missing values return the default. + +- Type conversion errors return the default. + +- Provider errors return the default (except for fetch variants). + +### Required variants + +Required variants throw errors when configuration values are missing or cannot be converted. These enforce that critical configuration must be present and valid. + +do { +// Required get +let serverPort = try config.requiredInt(forKey: "server.port") +let databaseHost = try config.requiredString(forKey: "database.host") + +// Required fetch +let latestPort = try await config.fetchRequiredInt(forKey: "server.port") + +// Required watch +try await config.watchRequiredInt(forKey: "server.port") { updates in +for try await port in updates { +print("Server port updated to: \(port)") +server.updatePort(port) +} +} +} catch { +fatalError("Configuration error: \(error)") +} + +#### When to use + +Use required variants when: + +- **Essential service configuration**: Server ports, database hosts, service endpoints. + +- **Application startup**: Values needed before the application can function properly. + +- **Critical functionality**: Configuration that must be present for core features to work. + +- **Fail-fast behavior**: You want immediate errors for missing critical configuration. + +### Choosing the right variant + +Use this decision tree to select the appropriate variant: + +#### Is the configuration value critical for application operation? + +**Yes** → Use **required variants** + +// Critical values that must be present +let serverPort = try config.requiredInt(forKey: "server.port") +let databaseHost = try config.requiredString(forKey: "database.host") + +**No** → Continue to next question + +#### Do you have a reasonable default value? + +**Yes** → Use **default variants** + +// Optional features with sensible defaults +let timeout = config.int(forKey: "http.timeout", default: 30) +let retryCount = config.int(forKey: "retries", default: 3) + +**No** → Use **optional variants** + +// Truly optional features where absence is meaningful +let debugEndpoint = config.string(forKey: "debug.endpoint") +let customTheme = config.string(forKey: "ui.theme") + +### Context and type conversion + +All variants support the same additional features: + +#### Configuration context + +// Optional with context +let timeout = config.int( +forKey: ConfigKey( +"service.timeout", +context: ["environment": "production", "region": "us-east-1"] +) +) + +// Default with context +let timeout = config.int( +forKey: ConfigKey( +"service.timeout", +context: ["environment": "production"] +), +default: 30 +) + +// Required with context +let timeout = try config.requiredInt( +forKey: ConfigKey( +"service.timeout", +context: ["environment": "production"] +) +) + +#### Type conversion + +String configuration values can be automatically converted to other types using the `as:` parameter. This works with: + +**Built-in convertible types:** + +- `SystemPackage.FilePath`: Converts from file paths. + +- `Foundation.URL`: Converts from URL strings. + +- `Foundation.UUID`: Converts from UUID strings. + +- `Foundation.Date`: Converts from ISO8601 date strings. + +**String-backed enums:** + +**Custom types:** + +- Types that you explicitly conform to `ExpressibleByConfigString`. + +// Built-in type conversion +let apiUrl = config.string(forKey: "api.url", as: URL.self) +let requestId = config.string(forKey: "request.id", as: UUID.self) +let configPath = config.string(forKey: "config.path", as: FilePath.self) +let startDate = config.string(forKey: "launch.date", as: Date.self) + +enum LogLevel: String { +case debug, info, warning, error +} + +// Optional conversion +let level: LogLevel? = config.string(forKey: "log.level", as: LogLevel.self) + +// Default conversion +let level = config.string(forKey: "log.level", as: LogLevel.self, default: .info) + +// Required conversion +let level = try config.requiredString(forKey: "log.level", as: LogLevel.self) + +// Custom type conversion (ExpressibleByConfigString) +struct DatabaseURL: ExpressibleByConfigString { +let url: URL + +init?(configString: String) { +guard let url = URL(string: configString) else { return nil } +self.url = url +} + +var description: String { url.absoluteString } +} +let dbUrl = config.string(forKey: "database.url", as: DatabaseURL.self) + +#### Secret handling + +// Mark sensitive values as secrets in all variants +let optionalKey = config.string(forKey: "api.key", isSecret: true) +let defaultKey = config.string(forKey: "api.key", isSecret: true, default: "development-key") +let requiredKey = try config.requiredString(forKey: "api.key", isSecret: true) + +Also check out Handling secrets correctly. + +### Best practices + +1. **Use required variants** only for truly critical configuration. + +2. **Use default variants** for user experience settings where missing configuration shouldn’t break functionality. + +3. **Use optional variants** for feature flags and debugging where the absence of configuration is meaningful. + +4. **Choose safe defaults** that won’t cause security issues or performance problems if used in production. + +For guidance on selecting between get, fetch, and watch access patterns, see Choosing the access pattern. For more configuration guidance, check out Adopting best practices. + +## See Also + +### Readers and providers + +`struct ConfigReader` + +A type that provides read-only access to configuration values from underlying providers. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`struct ConfigSnapshotReader` + +A container type for reading config values from snapshots. + +Choosing the access pattern + +Learn how to select the right method for reading configuration values based on your needs. + +Handling secrets correctly + +Protect sensitive configuration values from accidental disclosure in logs and debug output. + +- Choosing reader methods +- Overview +- Optional variants +- Default variants +- Required variants +- Choosing the right variant +- Context and type conversion +- Best practices +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider + +- Configuration +- KeyMappingProvider + +Structure + +# KeyMappingProvider + +A configuration provider that maps all keys before delegating to an upstream provider. + +KeyMappingProvider.swift + +## Mentioned in + +Example use cases + +## Overview + +Use `KeyMappingProvider` to automatically apply a mapping function to every configuration key before passing it to an underlying provider. This is particularly useful when the upstream source of configuration keys differs from your own. Another example is namespacing configuration values from specific sources, such as prefixing environment variables with an application name while leaving other configuration sources unchanged. + +### Common use cases + +Use `KeyMappingProvider` for: + +- Rewriting configuration keys to match upstream configuration sources. + +- Legacy system integration that adapts existing sources with different naming conventions. + +## Example + +Use `KeyMappingProvider` when you want to map keys for specific providers in a multi-provider setup: + +// Create providers +let envProvider = EnvironmentVariablesProvider() + +// Only remap the environment variables, not the JSON config +let keyMappedEnvProvider = KeyMappingProvider(upstream: envProvider) { key in +key.prepending(["myapp", "prod"]) +} + +let config = ConfigReader(providers: [\ +keyMappedEnvProvider, // Reads from "MYAPP_PROD_*" environment variables\ +jsonProvider // Reads from JSON without prefix\ +]) + +// This reads from "MYAPP_PROD_DATABASE_HOST" env var or "database.host" in JSON +let host = config.string(forKey: "database.host", default: "localhost") + +## Convenience method + +You can also use the `prefixKeys(with:)` convenience method on configuration provider types to wrap one in a `KeyMappingProvider`: + +let envProvider = EnvironmentVariablesProvider() +let keyMappedEnvProvider = envProvider.mapKeys { key in +key.prepending(["myapp", "prod"]) +} + +## Topics + +### Creating a key-mapping provider + +Creates a new provider. + +## Relationships + +### Conforms To + +- `ConfigProvider` +Conforms when `Upstream` conforms to `ConfigProvider`. + +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +- KeyMappingProvider +- Mentioned in +- Overview +- Common use cases +- Example +- Convenience method +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/choosing-access-patterns + +- Configuration +- Choosing the access pattern + +Article + +# Choosing the access pattern + +Learn how to select the right method for reading configuration values based on your needs. + +## Overview + +Swift Configuration provides three access patterns for retrieving configuration values, each optimized for different use cases and performance requirements. + +The three access patterns are: + +- **Get**: Synchronous access to current values available locally, in-memory. + +- **Fetch**: Asynchronous access to retrieve fresh values from authoritative sources, optionally with extra context. + +- **Watch**: Reactive access that provides real-time updates when values change. + +### Get: Synchronous local access + +The “get” pattern provides immediate, synchronous access to configuration values that are already available in memory. This is the fastest and most commonly used access pattern. + +let config = ConfigReader(provider: EnvironmentVariablesProvider()) + +// Get the current timeout value synchronously +let timeout = config.int(forKey: "http.timeout", default: 30) + +// Get a required value that must be present +let apiKey = try config.requiredString(forKey: "api.key", isSecret: true) + +#### When to use + +Use the “get” pattern when: + +- **Performance is critical**: You need immediate access without async overhead. + +- **Values are stable**: Configuration doesn’t change frequently during runtime. + +- **Simple providers**: Using environment variables, command-line arguments, or files. + +- **Startup configuration**: Reading values during application initialization. + +- **Request handling**: Accessing configuration in hot code paths where async calls would add latency. + +#### Behavior characteristics + +- Returns the currently cached value from the provider. + +- No network or I/O operations occur during the call. + +- Values may become stale if the underlying data source changes and the provider is either non-reloading, or has a long reload interval. + +### Fetch: Asynchronous fresh access + +The “fetch” pattern asynchronously retrieves the most current value from the authoritative data source, ensuring you always get up-to-date configuration. + +let config = ConfigReader(provider: remoteConfigProvider) + +// Fetch the latest timeout from a remote configuration service +let timeout = try await config.fetchInt(forKey: "http.timeout", default: 30) + +// Fetch with context for environment-specific configuration +let dbConnectionString = try await config.fetchRequiredString( +forKey: ConfigKey( +"database.url", +context: [\ +"environment": "production",\ +"region": "us-west-2",\ +"service": "user-service"\ +] +), +isSecret: true +) + +#### When to use + +Use the “fetch” pattern when: + +- **Freshness is critical**: You need the latest configuration values. + +- **Remote providers**: Using configuration services, databases, or external APIs that perform evaluation remotely. + +- **Infrequent access**: Reading configuration occasionally, not in hot paths. + +- **Setup operations**: Configuring long-lived resources like database connections where one-time overhead isn’t a concern, and the improved freshness is important. + +- **Administrative operations**: Fetching current settings for management interfaces. + +#### Behavior characteristics + +- Always contacts the authoritative data source. + +- May involve network calls, file system access, or database queries. + +- Providers may (but are not required to) cache the fetched value for subsequent “get” calls. + +- Throws an error if the provider fails to reach the source. + +### Watch: Reactive continuous updates + +The “watch” pattern provides an async sequence of configuration updates, allowing you to react to changes in real-time. This is ideal for long-running services that need to adapt to configuration changes without restarting. + +The async sequence is required to receive the current value as the first element as quickly as possible - this is part of the API contract with configuration providers (for details, check out `ConfigProvider`.) + +let config = ConfigReader(provider: reloadingProvider) + +// Watch for timeout changes and update connection pools +try await config.watchInt(forKey: "http.timeout", default: 30) { updates in +for await newTimeout in updates { +print("HTTP timeout updated to: \(newTimeout)") +connectionPool.updateTimeout(newTimeout) +} +} + +#### When to use + +Use the “watch” pattern when: + +- **Dynamic configuration**: Values change during application runtime. + +- **Hot reloading**: You need to update behavior without restarting the service. + +- **Feature toggles**: Enabling or disabling features based on configuration changes. + +- **Resource management**: Adjusting timeouts, limits, or thresholds dynamically. + +- **A/B testing**: Updating experimental parameters in real-time. + +#### Behavior characteristics + +- Immediately emits the initial value, then subsequent updates. + +- Continues monitoring until the task is cancelled. + +- Works with providers like `ReloadingFileProvider`. + +For details on reloading providers, check out Using reloading providers. + +### Using configuration context + +All access patterns support configuration context, which provides additional metadata to help providers return more specific values. Context is particularly useful with the “fetch” and “watch” patterns when working with dynamic or environment-aware providers. + +#### Filtering watch updates using context + +let context: [String: ConfigContextValue] = [\ +"environment": "production",\ +"region": "us-east-1",\ +"service_version": "2.1.0",\ +"feature_tier": "premium",\ +"load_factor": 0.85\ +] + +// Get environment-specific database configuration +let dbConfig = try await config.fetchRequiredString( +forKey: ConfigKey( +"database.connection_string", +context: context +), +isSecret: true +) + +// Watch for region-specific timeout adjustments +try await config.watchInt( +forKey: ConfigKey( +"api.timeout", +context: ["region": "us-west-2"] +), +default: 5000 +) { updates in +for await timeout in updates { +apiClient.updateTimeout(milliseconds: timeout) +} +} + +#### Get pattern performance + +- **Fastest**: No async overhead, immediate return. + +- **Memory usage**: Minimal, uses cached values. + +- **Best for**: Request handling, hot code paths, startup configuration. + +#### Fetch pattern performance + +- **Moderate**: Async overhead plus data source access time. + +- **Network dependent**: Performance varies with provider implementation. + +- **Best for**: Infrequent access, setup operations, administrative tasks. + +#### Watch pattern performance + +- **Background monitoring**: Continuous resource usage for monitoring. + +- **Event-driven**: Efficient updates only when values change. + +- **Best for**: Long-running services, dynamic configuration, feature toggles. + +### Error handling strategies + +Each access pattern handles errors differently: + +#### Get pattern errors + +// Returns nil or default value for missing/invalid config +let timeout = config.int(forKey: "http.timeout", default: 30) + +// Required variants throw errors for missing values +do { +let apiKey = try config.requiredString(forKey: "api.key") +} catch { +// Handle missing required configuration +} + +#### Fetch pattern errors + +// All fetch methods propagate provider and conversion errors +do { +let config = try await config.fetchRequiredString(forKey: "database.url") +} catch { +// Handle network errors, missing values, or conversion failures +} + +#### Watch pattern errors + +// Errors appear in the async sequence +try await config.watchRequiredInt(forKey: "port") { updates in +do { +for try await port in updates { +server.updatePort(port) +} +} catch { +// Handle provider errors or missing required values +} +} + +### Best practices + +1. **Choose based on use case**: Use “get” for performance-critical paths, “fetch” for freshness, and “watch” for hot reloading. + +2. **Handle errors appropriately**: Design error handling strategies that match your application’s resilience requirements. + +3. **Use context judiciously**: Provide context when you need environment-specific or conditional configuration values. + +4. **Monitor configuration access**: Use `AccessReporter` to understand your application’s configuration dependencies. + +5. **Cache wisely**: For frequently accessed values, prefer “get” over repeated “fetch” calls. + +For more guidance on selecting the right reader methods for your needs, see Choosing reader methods. To learn about handling sensitive configuration values securely, check out Handling secrets correctly. If you encounter issues with configuration access, refer to Troubleshooting and access reporting for debugging techniques. + +## See Also + +### Readers and providers + +`struct ConfigReader` + +A type that provides read-only access to configuration values from underlying providers. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`struct ConfigSnapshotReader` + +A container type for reading config values from snapshots. + +Choosing reader methods + +Choose between optional, default, and required variants of configuration methods. + +Handling secrets correctly + +Protect sensitive configuration values from accidental disclosure in logs and debug output. + +- Choosing the access pattern +- Overview +- Get: Synchronous local access +- Fetch: Asynchronous fresh access +- Watch: Reactive continuous updates +- Using configuration context +- Summary of performance considerations +- Error handling strategies +- Best practices +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessreporter + +- Configuration +- AccessReporter + +Protocol + +# AccessReporter + +A type that receives and processes configuration access events. + +protocol AccessReporter : Sendable + +AccessReporter.swift + +## Mentioned in + +Troubleshooting and access reporting + +Choosing the access pattern + +Configuring libraries + +## Overview + +Access reporters track when configuration values are read, fetched, or watched, to provide visibility into configuration usage patterns. This is useful for debugging, auditing, and understanding configuration dependencies. + +## Topics + +### Required methods + +`func report(AccessEvent)` + +Processes a configuration access event. + +**Required** + +## Relationships + +### Inherits From + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +### Conforming Types + +- `AccessLogger` +- `BroadcastingAccessReporter` +- `FileAccessLogger` + +## See Also + +### Troubleshooting and access reporting + +Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. + +`class AccessLogger` + +An access reporter that logs configuration access events using the Swift Log API. + +`class FileAccessLogger` + +An access reporter that writes configuration access events to a file. + +`struct AccessEvent` + +An event that captures information about accessing a configuration value. + +`struct BroadcastingAccessReporter` + +An access reporter that forwards events to multiple other reporters. + +- AccessReporter +- Mentioned in +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/using-reloading-providers + +- Configuration +- Using reloading providers + +Article + +# Using reloading providers + +Automatically reload configuration from files when they change. + +## Overview + +A reloading provider monitors configuration files for changes and automatically updates your application’s configuration without requiring restarts. Swift Configuration provides: + +- `ReloadingFileProvider` with `JSONSnapshot` for JSON configuration files. + +- `ReloadingFileProvider` with `YAMLSnapshot` for YAML configuration files. + +#### Creating and running providers + +Reloading providers run in a `ServiceGroup`: + +import ServiceLifecycle + +filePath: "/etc/config.json", +allowMissing: true, // Optional: treat missing file as empty config +pollInterval: .seconds(15) +) + +let serviceGroup = ServiceGroup( +services: [provider], +logger: logger +) + +try await serviceGroup.run() + +#### Reading configuration + +Use a reloading provider in the same fashion as a static provider, pass it to a `ConfigReader`: + +let config = ConfigReader(provider: provider) +let host = config.string( +forKey: "database.host", +default: "localhost" +) + +#### Poll interval considerations + +Choose poll intervals based on how quickly you need to detect changes: + +// Development: Quick feedback +pollInterval: .seconds(1) + +// Production: Balanced performance (default) +pollInterval: .seconds(15) + +// Batch processing: Resource efficient +pollInterval: .seconds(300) + +### Watching for changes + +The following sections provide examples of watching for changes in configuration from a reloading provider. + +#### Individual values + +The example below watches for updates in a single key, `database.host`: + +try await config.watchString( +forKey: "database.host" +) { updates in +for await host in updates { +print("Database host updated: \(host)") +} +} + +#### Configuration snapshots + +The following example reads the `database.host` and `database.password` key with the guarantee that they are read from the same update of the reloading file: + +try await config.watchSnapshot { updates in +for await snapshot in updates { +let host = snapshot.string(forKey: "database.host") +let password = snapshot.string(forKey: "database.password", isSecret: true) +print("Configuration updated - Database: \(host)") +} +} + +### Comparison with static providers + +| Feature | Static providers | Reloading providers | +| --- | --- | --- | +| **File reading** | Load once at startup | Reloading on change | +| **Service lifecycle** | Not required | Conforms to `Service` and must run in a `ServiceGroup` | +| **Configuration updates** | Require restart | Automatic reload | + +### Handling missing files during reloading + +Reloading providers support the `allowMissing` parameter to handle cases where configuration files might be temporarily missing or optional. This is useful for: + +- Optional configuration files that might not exist in all environments. + +- Configuration files that are created or removed dynamically. + +- Graceful handling of file system issues during service startup. + +#### Missing file behavior + +When `allowMissing` is `false` (the default), missing files cause errors: + +filePath: "/etc/config.json", +allowMissing: false // Default: throw error if file is missing +) +// Will throw an error if config.json doesn't exist + +When `allowMissing` is `true`, missing files are treated as empty configuration: + +filePath: "/etc/config.json", +allowMissing: true // Treat missing file as empty config +) +// Won't throw if config.json is missing - uses empty config instead + +#### Behavior during reloading + +If a file becomes missing after the provider starts, the behavior depends on the `allowMissing` setting: + +- **`allowMissing: false`**: The provider keeps the last known configuration and logs an error. + +- **`allowMissing: true`**: The provider switches to empty configuration. + +In both cases, when a valid file comes back, the provider will load it and recover. + +// Example: File gets deleted during runtime +try await config.watchString(forKey: "database.host", default: "localhost") { updates in +for await host in updates { +// With allowMissing: true, this will receive "localhost" when file is removed +// With allowMissing: false, this keeps the last known value +print("Database host: \(host)") +} +} + +#### Configuration-driven setup + +The following example sets up an environment variable provider to select the path and interval to watch for a JSON file that contains the configuration for your app: + +let envProvider = EnvironmentVariablesProvider() +let envConfig = ConfigReader(provider: envProvider) + +config: envConfig.scoped(to: "json") +// Reads JSON_FILE_PATH and JSON_POLL_INTERVAL_SECONDS +) + +### Migration from static providers + +1. **Replace initialization**: + +// Before + +// After + +2. **Add the provider to a ServiceGroup**: + +let serviceGroup = ServiceGroup(services: [provider], logger: logger) +try await serviceGroup.run() + +3. **Use ConfigReader**: + +let config = ConfigReader(provider: provider) + +// Live updates. +try await config.watchDouble(forKey: "timeout") { updates in +// Handle changes +} + +// On-demand reads - returns the current value, so might change over time. +let timeout = config.double(forKey: "timeout", default: 60.0) + +For guidance on choosing between get, fetch, and watch access patterns with reloading providers, see Choosing the access pattern. For troubleshooting reloading provider issues, check out Troubleshooting and access reporting. To learn about in-memory providers as an alternative, see Using in-memory providers. + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- Using reloading providers +- Overview +- Basic usage +- Watching for changes +- Comparison with static providers +- Handling missing files during reloading +- Advanced features +- Migration from static providers +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider + +- Configuration +- MutableInMemoryProvider + +Class + +# MutableInMemoryProvider + +A configuration provider that stores mutable values in memory. + +final class MutableInMemoryProvider + +MutableInMemoryProvider.swift + +## Mentioned in + +Using in-memory providers + +## Overview + +Unlike `InMemoryProvider`, this provider allows configuration values to be modified after initialization. It maintains thread-safe access to values and supports real-time notifications when values change, making it ideal for dynamic configuration scenarios. + +## Change notifications + +The provider supports watching for configuration changes through the standard `ConfigProvider` watching methods. When a value changes, all active watchers are automatically notified with the new value. + +## Use cases + +The mutable in-memory provider is particularly useful for: + +- **Dynamic configuration**: Values that change during application runtime + +- **Configuration bridges**: Adapting external configuration systems that push updates + +- **Testing scenarios**: Simulating configuration changes in unit tests + +- **Feature flags**: Runtime toggles that can be modified programmatically + +## Performance characteristics + +This provider offers O(1) lookup time with minimal synchronization overhead. Value updates are atomic and efficiently notify only the relevant watchers. + +## Usage + +// Create provider with initial values +let provider = MutableInMemoryProvider(initialValues: [\ +"feature.enabled": true,\ +"api.timeout": 30.0,\ +"database.host": "localhost"\ +]) + +let config = ConfigReader(provider: provider) + +// Read initial values +let isEnabled = config.bool(forKey: "feature.enabled") // true + +// Update values dynamically +provider.setValue(false, forKey: "feature.enabled") + +// Read updated values +let stillEnabled = config.bool(forKey: "feature.enabled") // false + +To learn more about the in-memory providers, check out Using in-memory providers. + +## Topics + +### Creating a mutable in-memory provider + +[`init(name: String?, initialValues: [AbsoluteConfigKey : ConfigValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/init(name:initialvalues:)) + +Creates a new mutable in-memory provider with the specified initial values. + +### Updating values in a mutable in-memory provider + +`func setValue(ConfigValue?, forKey: AbsoluteConfigKey)` + +Updates the stored value for the specified configuration key. + +## Relationships + +### Conforms To + +- `ConfigProvider` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- MutableInMemoryProvider +- Mentioned in +- Overview +- Change notifications +- Use cases +- Performance characteristics +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/development + +- Configuration +- Developing Swift Configuration + +Article + +# Developing Swift Configuration + +Learn about tools and conventions used to develop the Swift Configuration package. + +## Overview + +The Swift Configuration package is developed using modern Swift development practices and tools. This guide covers the development workflow, code organization, and tooling used to maintain the package. + +### Process + +We follow an open process and discuss development on GitHub issues, pull requests, and on the Swift Forums. Details on how to submit an issue or a pull requests can be found in CONTRIBUTING.md. + +Large features and changes go through a lightweight proposals process - to learn more, check out Proposals. + +#### Package organization + +The package contains several Swift targets organized by functionality: + +- **Configuration** \- Core configuration reading APIs and built-in providers. + +- **ConfigurationTesting** \- Testing utilities for external configuration providers. + +- **ConfigurationTestingInternal** \- Internal testing utilities and helpers. + +#### Running CI checks locally + +You can run the Github Actions workflows locally using act. To run all the jobs that run on a pull request, use the following command: + +% act pull_request +% act workflow_call -j soundness --input shell_check_enabled=true + +To bind-mount the working directory to the container, rather than a copy, use `--bind`. For example, to run just the formatting, and have the results reflected in your working directory: + +% act --bind workflow_call -j soundness --input format_check_enabled=true + +If you’d like `act` to always run with certain flags, these can be be placed in an `.actrc` file either in the current working directory or your home directory, for example: + +--container-architecture=linux/amd64 +--remote-name upstream +--action-offline-mode + +#### Code generation with gyb + +This package uses the “generate your boilerplate” (gyb) script from the Swift repository to stamp out repetitive code for each supported primitive type. + +The files that include gyb syntax end with `.gyb`, and after making changes to any of those files, run: + +./Scripts/generate_boilerplate_files_with_gyb.sh + +If you’re adding a new `.gyb` file, also make sure to add it to the exclude list in `Package.swift`. + +After running this script, also run the formatter before opening a PR. + +#### Code formatting + +The project uses swift-format for consistent code style. You can run CI checks locally using `act`. + +To run formatting checks: + +act --bind workflow_call -j soundness --input format_check_enabled=true + +#### Testing + +The package includes comprehensive test suites for all components: + +- Unit tests for individual providers and utilities. + +- Compatibility tests using `ProviderCompatTest` for built-in providers. + +Run tests using Swift Package Manager: + +swift test --enable-all-traits + +#### Documentation + +Documentation is written using DocC and includes: + +- API reference documentation in source code. + +- Conceptual guides in `.docc` catalogs. + +- Usage examples and best practices. + +- Troubleshooting guides. + +Preview documentation locally: + +SWIFT_PREVIEW_DOCS=1 swift package --disable-sandbox preview-documentation --target Configuration + +#### Code style + +- Follow Swift API Design Guidelines. + +- Use meaningful names for types, methods, and variables. + +- Include comprehensive documentation for all APIs, not only public types. + +- Write unit tests for new functionality. + +#### Provider development + +When developing new configuration providers: + +1. Implement the `ConfigProvider` protocol. + +2. Add comprehensive unit tests. + +3. Run compatibility tests using `ProviderCompatTest`. + +4. Add documentation to all symbols, not just `public`. + +#### Documentation requirements + +All APIs must include: + +- Clear, concise documentation comments. + +- Usage examples where appropriate. + +- Parameter and return value descriptions. + +- Error conditions and handling. + +## See Also + +### Contributing + +Collaborate on API changes to Swift Configuration by writing a proposal. + +- Developing Swift Configuration +- Overview +- Process +- Repository structure +- Development tools +- Contributing guidelines +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/troubleshooting + +- Configuration +- Troubleshooting and access reporting + +Article + +# Troubleshooting and access reporting + +Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. + +## Overview + +### Debugging configuration issues + +If your configuration values aren’t being read correctly, check: + +1. **Environment variable naming**: When using `EnvironmentVariablesProvider`, keys are automatically converted to uppercase with dots replaced by underscores. For example, `database.url` becomes `DATABASE_URL`. + +2. **Provider ordering**: When using multiple providers, they’re checked in order and the first one that returns a value wins. + +3. **Debug with an access reporter**: Use access reporting to see which keys are being queried and what values (if any) are being returned. See the next section for details. + +For guidance on selecting the right configuration access patterns and reader methods, check out Choosing the access pattern and Choosing reader methods. + +### Access reporting + +Configuration access reporting can help you debug issues and understand which configuration values your application is using. Swift Configuration provides two built-in ways to log access ( `AccessLogger` and `FileAccessLogger`), and you can also implement your own `AccessReporter`. + +#### Using AccessLogger + +`AccessLogger` integrates with Swift Log and records all configuration accesses: + +let logger = Logger(label: "...") +let accessLogger = AccessLogger(logger: logger) +let config = ConfigReader(provider: provider, accessReporter: accessLogger) + +// Each access will now be logged. +let timeout = config.double(forKey: "http.timeout", default: 30.0) + +This produces log entries showing: + +- Which configuration keys were accessed. + +- What values were returned (with secret values redacted). + +- Which provider supplied the value. + +- Whether default values were used. + +- The location of the code reading the config value. + +- The timestamp of the access. + +#### Using FileAccessLogger + +For writing access events to a file, especially useful during ad-hoc debugging, use `FileAccessLogger`: + +let fileLogger = try FileAccessLogger(filePath: "/var/log/myapp/config-access.log") +let config = ConfigReader(provider: provider, accessReporter: fileLogger) + +You can also enable file access logging for the whole application, without recompiling your code, by setting an environment variable: + +export CONFIG_ACCESS_LOG_FILE=/var/log/myapp/config-access.log + +And then read from the file to see one line per config access: + +tail -f /var/log/myapp/config-access.log + +#### Provider errors + +If any provider throws an error during lookup: + +- **Required methods** (`requiredString`, etc.): Error is immediately thrown to the caller. + +- **Optional methods** (with or without defaults): Error is handled gracefully; `nil` or the default value is returned. + +#### Missing values + +When no provider has the requested value: + +- **Methods with defaults**: Return the provided default value. + +- **Methods without defaults**: Return `nil`. + +- **Required methods**: Throw an error. + +#### File not found errors + +File-based providers ( `FileProvider`, `ReloadingFileProvider`, `DirectoryFilesProvider`, `EnvironmentVariablesProvider` with file path) can throw “file not found” errors when expected configuration files don’t exist. + +Common scenarios and solutions: + +**Optional configuration files:** + +// Problem: App crashes when optional config file is missing + +// Solution: Use allowMissing parameter + +filePath: "/etc/optional-config.json", +allowMissing: true +) + +**Environment-specific files:** + +// Different environments may have different config files +let configPath = "/etc/\(environment)/config.json" + +filePath: configPath, +allowMissing: true // Gracefully handle missing env-specific configs +) + +**Container startup issues:** + +// Config files might not be ready when container starts + +filePath: "/mnt/config/app.json", +allowMissing: true // Allow startup with empty config, load when available +) + +#### Configuration not updating + +If your reloading provider isn’t detecting file changes: + +1. **Check ServiceGroup**: Ensure the provider is running in a `ServiceGroup`. + +2. **Enable verbose logging**: The built-in providers use Swift Log for detailed logging, which can help spot issues. + +3. **Verify file path**: Confirm the file path is correct, the file exists, and file permissions are correct. + +4. **Check poll interval**: Consider if your poll interval is appropriate for your use case. + +#### ServiceGroup integration issues + +Common ServiceGroup problems: + +// Incorrect: Provider not included in ServiceGroup + +let config = ConfigReader(provider: provider) +// File monitoring won't work + +// Correct: Provider runs in ServiceGroup + +let serviceGroup = ServiceGroup(services: [provider], logger: logger) +try await serviceGroup.run() + +For more details about reloading providers and ServiceLifecycle integration, see Using reloading providers. To learn about proper configuration practices that can prevent common issues, check out Adopting best practices. + +## See Also + +### Troubleshooting and access reporting + +`protocol AccessReporter` + +A type that receives and processes configuration access events. + +`class AccessLogger` + +An access reporter that logs configuration access events using the Swift Log API. + +`class FileAccessLogger` + +An access reporter that writes configuration access events to a file. + +`struct AccessEvent` + +An event that captures information about accessing a configuration value. + +`struct BroadcastingAccessReporter` + +An access reporter that forwards events to multiple other reporters. + +- Troubleshooting and access reporting +- Overview +- Debugging configuration issues +- Access reporting +- Error handling +- Reloading provider troubleshooting +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileparsingoptions + +- Configuration +- FileParsingOptions + +Protocol + +# FileParsingOptions + +A type that provides parsing options for file configuration snapshots. + +protocol FileParsingOptions : Sendable + +FileProviderSnapshot.swift + +## Overview + +This protocol defines the requirements for parsing options types used with `FileConfigSnapshot` implementations. Types conforming to this protocol provide configuration parameters that control how file data is interpreted and parsed during snapshot creation. + +The parsing options are passed to the `init(data:providerName:parsingOptions:)` initializer, allowing custom file format implementations to access format-specific parsing settings such as character encoding, date formats, or validation rules. + +## Usage + +Implement this protocol to provide parsing options for your custom `FileConfigSnapshot`: + +struct MyParsingOptions: FileParsingOptions { +let encoding: String.Encoding +let dateFormat: String? +let strictValidation: Bool + +static let `default` = MyParsingOptions( +encoding: .utf8, +dateFormat: nil, +strictValidation: false +) +} + +struct MyFormatSnapshot: FileConfigSnapshot { +typealias ParsingOptions = MyParsingOptions + +init(data: RawSpan, providerName: String, parsingOptions: ParsingOptions) throws { +// Implementation that inspects `parsingOptions` properties like `encoding`, +// `dateFormat`, and `strictValidation`. +} +} + +## Topics + +### Required properties + +``static var `default`: Self`` + +The default instance of this options type. + +**Required** + +### Parsing options + +`protocol FileConfigSnapshot` + +A protocol for configuration snapshots created from file data. + +## Relationships + +### Inherits From + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +### Conforming Types + +- `JSONSnapshot.ParsingOptions` +- `YAMLSnapshot.ParsingOptions` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- FileParsingOptions +- Overview +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshot + +- Configuration +- ConfigSnapshot + +Protocol + +# ConfigSnapshot + +An immutable snapshot of a configuration provider’s state. + +protocol ConfigSnapshot : Sendable + +ConfigProvider.swift + +## Overview + +Snapshots enable consistent reads of multiple related configuration keys by capturing the provider’s state at a specific moment. This prevents the underlying data from changing between individual key lookups. + +## Topics + +### Required methods + +`var providerName: String` + +The human-readable name of the configuration provider that created this snapshot. + +**Required** + +Returns a value for the specified key from this immutable snapshot. + +## Relationships + +### Inherits From + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +### Inherited By + +- `FileConfigSnapshot` + +### Conforming Types + +- `JSONSnapshot` +- `YAMLSnapshot` + +## See Also + +### Creating a custom provider + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- ConfigSnapshot +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configuring-applications + +- Configuration +- Configuring applications + +Article + +# Configuring applications + +Provide flexible and consistent configuration for your application. + +## Overview + +Swift Configuration provides consistent configuration for your tools and applications. This guide shows how to: + +1. Set up a configuration hierarchy with multiple providers. + +2. Configure your application’s components. + +3. Access configuration values in your application and libraries. + +4. Monitor configuration access with access reporting. + +This pattern works well for server applications where configuration comes from environment variables, configuration files, and remote services. + +### Setting up a configuration hierarchy + +Start by creating a configuration hierarchy in your application’s entry point. This defines the order in which configuration sources are consulted when looking for values: + +import Configuration +import Logging + +// Create a logger. +let logger: Logger = ... + +// Set up the configuration hierarchy: +// - environment variables first, +// - then JSON file, +// - then in-memory defaults. +// Also emit log accesses into the provider logger, +// with secrets automatically redacted. + +let config = ConfigReader( +providers: [\ +EnvironmentVariablesProvider(),\ + +filePath: "/etc/myapp/config.json",\ +allowMissing: true // Optional: treat missing file as empty config\ +),\ +InMemoryProvider(values: [\ +"http.server.port": 8080,\ +"http.server.host": "127.0.0.1",\ +"http.client.timeout": 30.0\ +])\ +], +accessReporter: AccessLogger(logger: logger) +) + +// Start your application with the config. +try await runApplication(config: config, logger: logger) + +This configuration hierarchy gives priority to environment variables, then falls + +Next, configure your application using the configuration reader: + +func runApplication( +config: ConfigReader, +logger: Logger +) async throws { +// Get server configuration. +let serverHost = config.string( +forKey: "http.server.host", +default: "localhost" +) +let serverPort = config.int( +forKey: "http.server.port", +default: 8080 +) + +// Read library configuration with a scoped reader +// with the prefix `http.client`. +let httpClientConfig = HTTPClientConfiguration( +config: config.scoped(to: "http.client") +) +let httpClient = HTTPClient(configuration: httpClientConfig) + +// Run your server with the configured components +try await startHTTPServer( +host: serverHost, +port: serverPort, +httpClient: httpClient, +logger: logger +) +} + +Finally, you configure your application across the three sources. A fully configured set of environment variables could look like the following: + +export HTTP_SERVER_HOST=localhost +export HTTP_SERVER_PORT=8080 +export HTTP_CLIENT_TIMEOUT=30.0 +export HTTP_CLIENT_MAX_CONCURRENT_CONNECTIONS=20 +export HTTP_CLIENT_BASE_URL="https://example.com" +export HTTP_CLIENT_DEBUG_LOGGING=true + +In JSON: + +{ +"http": { +"server": { +"host": "localhost", +"port": 8080 +}, +"client": { +"timeout": 30.0, +"maxConcurrentConnections": 20, +"baseURL": "https://example.com", +"debugLogging": true +} +} +} + +And using `InMemoryProvider`: + +[\ +"http.server.port": 8080,\ +"http.server.host": "127.0.0.1",\ +"http.client.timeout": 30.0,\ +"http.client.maxConcurrentConnections": 20,\ +"http.client.baseURL": "https://example.com",\ +"http.client.debugLogging": true,\ +] + +In practice, you’d only specify a subset of the config keys in each location, to match the needs of your service’s operators. + +### Using scoped configuration + +For services with multiple instances of the same component, but with different settings, use scoped configuration: + +// For our server example, we might have different API clients +// that need different settings: + +let adminConfig = config.scoped(to: "services.admin") +let customerConfig = config.scoped(to: "services.customer") + +// Using the admin API configuration +let adminBaseURL = adminConfig.string( +forKey: "baseURL", +default: "https://admin-api.example.com" +) +let adminTimeout = adminConfig.double( +forKey: "timeout", +default: 60.0 +) + +// Using the customer API configuration +let customerBaseURL = customerConfig.string( +forKey: "baseURL", +default: "https://customer-api.example.com" +) +let customerTimeout = customerConfig.double( +forKey: "timeout", +default: 30.0 +) + +This can be configured via environment variables as follows: + +# Admin API configuration +export SERVICES_ADMIN_BASE_URL="https://admin.internal-api.example.com" +export SERVICES_ADMIN_TIMEOUT=120.0 +export SERVICES_ADMIN_DEBUG_LOGGING=true + +# Customer API configuration +export SERVICES_CUSTOMER_BASE_URL="https://api.example.com" +export SERVICES_CUSTOMER_MAX_CONCURRENT_CONNECTIONS=20 +export SERVICES_CUSTOMER_TIMEOUT=15.0 + +For details about the key conversion logic, check out `EnvironmentVariablesProvider`. + +For more configuration guidance, see Adopting best practices. To understand different access patterns and reader methods, refer to Choosing the access pattern and Choosing reader methods. For handling secrets securely, check out Handling secrets correctly. + +## See Also + +### Essentials + +Configuring libraries + +Provide a consistent and flexible way to configure your library. + +Example use cases + +Review common use cases with ready-to-copy code samples. + +Adopting best practices + +Follow these principles to make your code easily configurable and composable with other libraries. + +- Configuring applications +- Overview +- Setting up a configuration hierarchy +- Configure your application +- Using scoped configuration +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/systempackage + +- Configuration +- SystemPackage + +Extended Module + +# SystemPackage + +## Topics + +### Extended Structures + +`extension FilePath` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence + +- Configuration +- ConfigUpdatesAsyncSequence + +Structure + +# ConfigUpdatesAsyncSequence + +A concrete async sequence for delivering updated configuration values. + +AsyncSequences.swift + +## Topics + +### Creating an asynchronous update sequence + +Creates a new concrete async sequence wrapping the provided existential sequence. + +## Relationships + +### Conforms To + +- `Swift.Copyable` +- `Swift.Sendable` +- `Swift.SendableMetatype` +- `_Concurrency.AsyncSequence` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +- ConfigUpdatesAsyncSequence +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/expressiblebyconfigstring + +- Configuration +- ExpressibleByConfigString + +Protocol + +# ExpressibleByConfigString + +A protocol for types that can be initialized from configuration string values. + +protocol ExpressibleByConfigString : CustomStringConvertible + +ExpressibleByConfigString.swift + +## Mentioned in + +Choosing reader methods + +## Overview + +Conform your custom types to this protocol to enable automatic conversion when using the `as:` parameter with configuration reader methods such as `string(forKey:as:isSecret:fileID:line:)`. + +## Custom types + +For other custom types, conform to the protocol `ExpressibleByConfigString` by providing a failable initializer and the `description` property: + +struct DatabaseURL: ExpressibleByConfigString { +let url: URL + +init?(configString: String) { +guard let url = URL(string: configString) else { return nil } +self.url = url +} + +var description: String { url.absoluteString } +} + +// Now you can use it with automatic conversion +let config = ConfigReader(provider: EnvironmentVariablesProvider()) +let dbUrl = config.string(forKey: "database.url", as: DatabaseURL.self) + +## Built-in conformances + +The following Foundation types already conform to `ExpressibleByConfigString`: + +- `SystemPackage.FilePath` \- Converts from file paths. + +- `Foundation.URL` \- Converts from URL strings. + +- `Foundation.UUID` \- Converts from UUID strings. + +- `Foundation.Date` \- Converts from ISO8601 date strings. + +## Topics + +### Required methods + +`init?(configString: String)` + +Creates an instance from a configuration string value. + +**Required** + +## Relationships + +### Inherits From + +- `Swift.CustomStringConvertible` + +### Conforming Types + +- `Date` +- `FilePath` +- `URL` +- `UUID` + +## See Also + +### Value conversion + +`protocol ConfigBytesFromStringDecoder` + +A protocol for decoding string configuration values into byte arrays. + +`struct ConfigBytesFromBase64StringDecoder` + +A decoder that converts base64-encoded strings into byte arrays. + +`struct ConfigBytesFromHexStringDecoder` + +A decoder that converts hexadecimal-encoded strings into byte arrays. + +- ExpressibleByConfigString +- Mentioned in +- Overview +- Custom types +- Built-in conformances +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/using-in-memory-providers + +- Configuration +- Using in-memory providers + +Article + +# Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +## Overview + +Swift Configuration provides two in-memory providers, which are directly instantiated with the desired keys and values, rather than being parsed from another representation. These providers are particularly useful for testing, providing fallback values, and bridging with other configuration systems. + +- `InMemoryProvider` is an immutable value type, and can be useful for defining overrides and fallbacks in a provider hierarchy. + +- `MutableInMemoryProvider` is a mutable reference type, allowing you to update values and get any watchers notified automatically. It can be used to bridge from other stateful, callback-based configuration sources. + +### InMemoryProvider + +The `InMemoryProvider` is ideal for static configuration values that don’t change during application runtime. + +#### Basic usage + +Create an `InMemoryProvider` with a dictionary of configuration values: + +let provider = InMemoryProvider(values: [\ +"database.host": "localhost",\ +"database.port": 5432,\ +"api.timeout": 30.0,\ +"debug.enabled": true\ +]) + +let config = ConfigReader(provider: provider) +let host = config.string(forKey: "database.host") // "localhost" +let port = config.int(forKey: "database.port") // 5432 + +#### Using with hierarchical keys + +You can use `AbsoluteConfigKey` for more complex key structures: + +let provider = InMemoryProvider(values: [\ +AbsoluteConfigKey(["http", "client", "timeout"]): 30.0,\ +AbsoluteConfigKey(["http", "server", "port"]): 8080,\ +AbsoluteConfigKey(["logging", "level"]): "info"\ +]) + +#### Configuration context + +The in-memory provider performs exact matching of config keys, including the context. This allows you to provide different values for the same key path based on contextual information. + +The following example shows using two keys with the same key path, but different context, and giving them two different values: + +let provider = InMemoryProvider( +values: [\ +AbsoluteConfigKey(\ +["http", "client", "timeout"],\ +context: ["upstream": "example1.org"]\ +): 15.0,\ +AbsoluteConfigKey(\ +["http", "client", "timeout"],\ +context: ["upstream": "example2.org"]\ +): 30.0,\ +] +) + +With a provider configured this way, a config reader will return the following results: + +let config = ConfigReader(provider: provider) +config.double(forKey: "http.client.timeout") // nil +config.double( +forKey: ConfigKey( +"http.client.timeout", +context: ["upstream": "example1.org"] +) +) // 15.0 +config.double( +forKey: ConfigKey( +"http.client.timeout", +context: ["upstream": "example2.org"] +) +) // 30.0 + +### MutableInMemoryProvider + +The `MutableInMemoryProvider` allows you to modify configuration values at runtime and notify watchers of changes. + +#### Basic usage + +let provider = MutableInMemoryProvider() +provider.setValue("localhost", forKey: "database.host") +provider.setValue(5432, forKey: "database.port") + +let config = ConfigReader(provider: provider) +let host = config.string(forKey: "database.host") // "localhost" + +#### Updating values + +You can update values after creation, and any watchers will be notified: + +// Initial setup +provider.setValue("debug", forKey: "logging.level") + +// Later in your application, watchers are notified +provider.setValue("info", forKey: "logging.level") + +#### Watching for changes + +Use the provider’s async sequence to watch for configuration changes: + +let config = ConfigReader(provider: provider) +try await config.watchString( +forKey: "logging.level", +as: Logger.Level.self, +default: .debug +) { updates in +for try await level in updates { +print("Logging level changed to: \(level)") +} +} + +#### Testing + +In-memory providers are excellent for unit testing: + +func testDatabaseConnection() { +let testProvider = InMemoryProvider(values: [\ +"database.host": "test-db.example.com",\ +"database.port": 5433,\ +"database.name": "test_db"\ +]) + +let config = ConfigReader(provider: testProvider) +let connection = DatabaseConnection(config: config) +// Test your database connection logic +} + +#### Fallback values + +Use `InMemoryProvider` as a fallback in a provider hierarchy: + +let fallbackProvider = InMemoryProvider(values: [\ +"api.timeout": 30.0,\ +"retry.maxAttempts": 3,\ +"cache.enabled": true\ +]) + +let config = ConfigReader(providers: [\ +EnvironmentVariablesProvider(),\ +fallbackProvider\ +// Used when environment variables are not set\ +]) + +#### Bridging other systems + +Use `MutableInMemoryProvider` to bridge configuration from other systems: + +class ConfigurationBridge { +private let provider = MutableInMemoryProvider() + +func updateFromExternalSystem(_ values: [String: ConfigValue]) { +for (key, value) in values { +provider.setValue(value, forKey: key) +} +} +} + +For comparison with reloading providers, see Using reloading providers. To understand different access patterns and when to use each provider type, check out Choosing the access pattern. For more configuration guidance, refer to Adopting best practices. + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- Using in-memory providers +- Overview +- InMemoryProvider +- MutableInMemoryProvider +- Common Use Cases +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/snapshot() + +#app-main) + +- Configuration +- ConfigReader +- snapshot() + +Instance Method + +# snapshot() + +Returns a snapshot of the current configuration state. + +ConfigSnapshotReader.swift + +## Return Value + +The snapshot. + +## Discussion + +The snapshot reader provides read-only access to the configuration’s state at the time the method was called. + +let snapshot = config.snapshot() +// Use snapshot to read config values +let cert = snapshot.string(forKey: "cert") +let privateKey = snapshot.string(forKey: "privateKey") +// Ensures that both values are coming from the same underlying snapshot and that a provider +// didn't change its internal state between the two `string(...)` calls. +let identity = MyIdentity(cert: cert, privateKey: privateKey) + +## See Also + +### Reading from a snapshot + +Watches the configuration for changes. + +- snapshot() +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/best-practices + +- Configuration +- Adopting best practices + +Article + +# Adopting best practices + +Follow these principles to make your code easily configurable and composable with other libraries. + +## Overview + +When designing configuration for Swift libraries and applications, follow these patterns to create consistent, maintainable code that integrates well with the Swift ecosystem. + +### Document configuration keys + +Include thorough documentation about what configuration keys your library reads. For each key, document: + +- The key name and its hierarchical structure. + +- The expected data type. + +- Whether the key is required or optional. + +- Default values when applicable. + +- Valid value ranges or constraints. + +- Usage examples. + +public struct HTTPClientConfiguration { +/// ... +/// +/// ## Configuration keys: +/// - `timeout` (double, optional, default: 30.0): Request timeout in seconds. +/// - `maxRetries` (int, optional, default: 3, range: 0-10): Maximum retry attempts. +/// - `baseURL` (string, required): Base URL for requests. +/// - `apiKey` (string, required, secret): API authentication key. +/// +/// ... +public init(config: ConfigReader) { +// Implementation... +} +} + +### Use sensible defaults + +Provide reasonable default values to make your library work without extensive configuration. + +// Good: Provides sensible defaults +let timeout = config.double(forKey: "http.timeout", default: 30.0) +let maxConnections = config.int(forKey: "http.maxConnections", default: 10) + +// Avoid: Requiring configuration for common scenarios +let timeout = try config.requiredDouble(forKey: "http.timeout") // Forces users to configure + +### Use scoped configuration + +Organize your configuration keys logically using namespaces to keep related keys together. + +// Good: +let httpConfig = config.scoped(to: "http") +let timeout = httpConfig.double(forKey: "timeout", default: 30.0) +let retries = httpConfig.int(forKey: "retries", default: 3) + +// Better (in libraries): Offer a convenience method that reads your library's configuration. +// Tip: Read the configuration values from the provided reader directly, do not scope it +// to a "myLibrary" namespace. Instead, let the caller of MyLibraryConfiguration.init(config:) +// perform any scoping for your library's configuration. +public struct MyLibraryConfiguration { +public init(config: ConfigReader) { +self.timeout = config.double(forKey: "timeout", default: 30.0) +self.retries = config.int(forKey: "retries", default: 3) +} +} + +// Called from an app - the caller is responsible for adding a namespace and naming it, if desired. +let libraryConfig = MyLibraryConfiguration(config: config.scoped(to: "myLib")) + +### Mark secrets appropriately + +Mark sensitive configuration values like API keys, passwords, or tokens as secrets using the `isSecret: true` parameter. This tells access reporters to redact those values in logs. + +// Mark sensitive values as secrets +let apiKey = try config.requiredString(forKey: "api.key", isSecret: true) +let password = config.string(forKey: "database.password", default: nil, isSecret: true) + +// Regular values don't need the isSecret parameter +let timeout = config.double(forKey: "api.timeout", default: 30.0) + +Some providers also support the `SecretsSpecifier`, allowing you to mark which values are secret during application bootstrapping. + +For comprehensive guidance on handling secrets securely, see Handling secrets correctly. + +### Prefer optional over required + +Only mark configuration as required if your library absolutely cannot function without it. For most cases, provide sensible defaults and make configuration optional. + +// Good: Optional with sensible defaults +let timeout = config.double(forKey: "timeout", default: 30.0) +let debug = config.bool(forKey: "debug", default: false) + +// Use required only when absolutely necessary +let apiEndpoint = try config.requiredString(forKey: "api.endpoint") + +For more details, check out Choosing reader methods. + +### Validate configuration values + +Validate configuration values and throw meaningful errors for invalid input to catch configuration issues early. + +public init(config: ConfigReader) throws { +let timeout = config.double(forKey: "timeout", default: 30.0) + +throw MyConfigurationError.invalidTimeout("Timeout must be positive, got: \(timeout)") +} + +let maxRetries = config.int(forKey: "maxRetries", default: 3) + +throw MyConfigurationError.invalidRetryCount("Max retries must be 0-10, got: \(maxRetries)") +} + +self.timeout = timeout +self.maxRetries = maxRetries +} + +#### When to use reloading providers + +Use reloading providers when you need configuration changes to take effect without restarting your application: + +- Long-running services that can’t be restarted frequently. + +- Development environments where you iterate on configuration. + +- Applications that receive configuration updates through file deployments. + +Check out Using reloading providers to learn more. + +#### When to use static providers + +Use static providers when configuration doesn’t change during runtime: + +- Containerized applications with immutable configuration. + +- Applications where configuration is set once at startup. + +For help choosing between different access patterns and reader method variants, see Choosing the access pattern and Choosing reader methods. For troubleshooting configuration issues, refer to Troubleshooting and access reporting. + +## See Also + +### Essentials + +Configuring applications + +Provide flexible and consistent configuration for your application. + +Configuring libraries + +Provide a consistent and flexible way to configure your library. + +Example use cases + +Review common use cases with ready-to-copy code samples. + +- Adopting best practices +- Overview +- Document configuration keys +- Use sensible defaults +- Use scoped configuration +- Mark secrets appropriately +- Prefer optional over required +- Validate configuration values +- Choosing provider types +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier + +- Configuration +- SecretsSpecifier + +Enumeration + +# SecretsSpecifier + +A specification for identifying which configuration values contain sensitive information. + +SecretsSpecifier.swift + +## Mentioned in + +Adopting best practices + +Handling secrets correctly + +## Overview + +Configuration providers use secrets specifiers to determine which values should be marked as sensitive and protected from accidental disclosure in logs, debug output, or access reports. Secret values are handled specially by `AccessReporter` instances and other components that process configuration data. + +## Usage patterns + +### Mark all values as secret + +Use this for providers that exclusively handle sensitive data: + +let provider = InMemoryProvider( +values: ["api.key": "secret123", "db.password": "pass456"], +secretsSpecifier: .all +) + +### Mark specific keys as secret + +Use this when you know which specific keys contain sensitive information: + +let provider = EnvironmentVariablesProvider( +secretsSpecifier: .specific( +["API_KEY", "DATABASE_PASSWORD", "JWT_SECRET"] +) +) + +### Dynamic secret detection + +Use this for complex logic that determines secrecy based on key patterns or values: + +filePath: "/etc/config.json", +secretsSpecifier: .dynamic { key, value in +// Mark keys containing "password", +// "secret", or "token" as secret +key.lowercased().contains("password") || +key.lowercased().contains("secret") || +key.lowercased().contains("token") +} +) + +### No secret values + +Use this for providers that handle only non-sensitive configuration: + +let provider = InMemoryProvider( +values: ["app.name": "MyApp", "log.level": "info"], +secretsSpecifier: .none +) + +## Topics + +### Types of specifiers + +`case all` + +The library treats all configuration values as secrets. + +The library treats the specified keys as secrets. + +The library determines the secret status dynamically by evaluating each key-value pair. + +`case none` + +The library treats no configuration values as secrets. + +### Inspecting a secrets specifier + +Determines whether a configuration value should be treated as secret. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- SecretsSpecifier +- Mentioned in +- Overview +- Usage patterns +- Mark all values as secret +- Mark specific keys as secret +- Dynamic secret detection +- No secret values +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider + +- Configuration +- DirectoryFilesProvider + +Structure + +# DirectoryFilesProvider + +A configuration provider that reads values from individual files in a directory. + +struct DirectoryFilesProvider + +DirectoryFilesProvider.swift + +## Mentioned in + +Example use cases + +Handling secrets correctly + +Troubleshooting and access reporting + +## Overview + +This provider reads configuration values from a directory where each file represents a single configuration key-value pair. The file name becomes the configuration key, and the file contents become the value. This approach is commonly used by secret management systems that mount secrets as individual files. + +## Key mapping + +Configuration keys are transformed into file names using these rules: + +- Components are joined with dashes. + +- Non-alphanumeric characters (except dashes) are replaced with underscores. + +For example: + +## Value handling + +The provider reads file contents as UTF-8 strings and converts them to the requested type. For binary data (bytes type), it reads raw file contents directly without string conversion. Leading and trailing whitespace is always trimmed from string values. + +## Supported data types + +The provider supports all standard configuration types: + +- Strings (UTF-8 text files) + +- Integers, doubles, and booleans (parsed from string contents) + +- Arrays (using configurable separator, comma by default) + +- Byte arrays (raw file contents) + +## Secret handling + +By default, all values are marked as secrets for security. This is appropriate since this provider is typically used for sensitive data mounted by secret management systems. + +## Usage + +### Reading from a secrets directory + +// Assuming /run/secrets contains files: +// - database-password (contains: "secretpass123") +// - max-connections (contains: "100") +// - enable-cache (contains: "true") + +let provider = try await DirectoryFilesProvider( +directoryPath: "/run/secrets" +) + +let config = ConfigReader(provider: provider) +let dbPassword = config.string(forKey: "database.password") // "secretpass123" +let maxConn = config.int(forKey: "max.connections", default: 50) // 100 +let cacheEnabled = config.bool(forKey: "enable.cache", default: false) // true + +### Reading binary data + +// For binary files like certificates or keys +let provider = try await DirectoryFilesProvider( +directoryPath: "/run/secrets" +) + +let config = ConfigReader(provider: provider) +let certData = try config.requiredBytes(forKey: "tls.cert") // Raw file bytes + +### Custom array handling + +// If files contain comma-separated lists +let provider = try await DirectoryFilesProvider( +directoryPath: "/etc/config" +) + +// File "allowed-hosts" contains: "host1.example.com,host2.example.com,host3.example.com" +let hosts = config.stringArray(forKey: "allowed.hosts", default: []) +// ["host1.example.com", "host2.example.com", "host3.example.com"] + +## Configuration context + +This provider ignores the context passed in `context`. All keys are resolved using only their component path. + +## Topics + +### Creating a directory files provider + +Creates a new provider that reads files from a directory. + +## Relationships + +### Conforms To + +- `ConfigProvider` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +Using in-memory providers + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`struct InMemoryProvider` + +A configuration provider that stores values in memory. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- DirectoryFilesProvider +- Mentioned in +- Overview +- Key mapping +- Value handling +- Supported data types +- Secret handling +- Usage +- Reading from a secrets directory +- Reading binary data +- Custom array handling +- Configuration context +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey + +- Configuration +- AbsoluteConfigKey + +Structure + +# AbsoluteConfigKey + +A configuration key that represents an absolute path to a configuration value. + +struct AbsoluteConfigKey + +ConfigKey.swift + +## Mentioned in + +Using in-memory providers + +## Overview + +Absolute configuration keys are similar to relative keys but represent complete paths from the root of the configuration hierarchy. They are used internally by the configuration system after resolving any key prefixes or scoping. + +Like relative keys, absolute keys consist of hierarchical components and optional context information. + +## Topics + +### Creating an absolute configuration key + +`init(ConfigKey)` + +Creates a new absolute configuration key from a relative key. + +[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:context:)) + +Creates a new absolute configuration key. + +### Inspecting an absolute configuration key + +[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/components) + +The hierarchical components that make up this absolute configuration key. + +[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/context) + +Additional context information for this configuration key. + +### Instance Methods + +Returns a new absolute configuration key by appending the given relative key. + +Returns a new absolute configuration key by prepending the given relative key. + +## Relationships + +### Conforms To + +- `Swift.Comparable` +- `Swift.Copyable` +- `Swift.CustomStringConvertible` +- `Swift.Equatable` +- `Swift.ExpressibleByArrayLiteral` +- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` +- `Swift.ExpressibleByStringLiteral` +- `Swift.ExpressibleByUnicodeScalarLiteral` +- `Swift.Hashable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Configuration keys + +`struct ConfigKey` + +A configuration key representing a relative path to a configuration value. + +`enum ConfigContextValue` + +A value that can be stored in a configuration context. + +- AbsoluteConfigKey +- Mentioned in +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromhexstringdecoder + +- Configuration +- ConfigBytesFromHexStringDecoder + +Structure + +# ConfigBytesFromHexStringDecoder + +A decoder that converts hexadecimal-encoded strings into byte arrays. + +struct ConfigBytesFromHexStringDecoder + +ConfigBytesFromStringDecoder.swift + +## Overview + +This decoder interprets string configuration values as hexadecimal-encoded data and converts them to their binary representation. It expects strings to contain only valid hexadecimal characters (0-9, A-F, a-f). + +## Hexadecimal format + +The decoder expects strings with an even number of characters, where each pair of characters represents one byte. For example, “48656C6C6F” represents the bytes for “Hello”. + +## Topics + +### Creating bytes from a hex string decoder + +`init()` + +Creates a new hexadecimal decoder. + +## Relationships + +### Conforms To + +- `ConfigBytesFromStringDecoder` +- `Swift.Copyable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Value conversion + +`protocol ExpressibleByConfigString` + +A protocol for types that can be initialized from configuration string values. + +`protocol ConfigBytesFromStringDecoder` + +A protocol for decoding string configuration values into byte arrays. + +`struct ConfigBytesFromBase64StringDecoder` + +A decoder that converts base64-encoded strings into byte arrays. + +- ConfigBytesFromHexStringDecoder +- Overview +- Hexadecimal format +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent + +- Configuration +- ConfigContent + +Enumeration + +# ConfigContent + +The raw content of a configuration value. + +@frozen +enum ConfigContent + +ConfigProvider.swift + +## Topics + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +## Relationships + +### Conforms To + +- `Swift.Copyable` +- `Swift.Equatable` +- `Swift.ExpressibleByBooleanLiteral` +- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` +- `Swift.ExpressibleByFloatLiteral` +- `Swift.ExpressibleByIntegerLiteral` +- `Swift.ExpressibleByStringLiteral` +- `Swift.ExpressibleByUnicodeScalarLiteral` +- `Swift.Hashable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- ConfigContent +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue + +- Configuration +- ConfigValue + +Structure + +# ConfigValue + +A configuration value that wraps content with metadata. + +struct ConfigValue + +ConfigProvider.swift + +## Mentioned in + +Handling secrets correctly + +## Overview + +Configuration values pair raw content with a flag indicating whether the value contains sensitive information. Secret values are protected from accidental disclosure in logs and debug output: + +let apiKey = ConfigValue(.string("sk-abc123"), isSecret: true) + +## Topics + +### Creating a config value + +`init(ConfigContent, isSecret: Bool)` + +Creates a new configuration value. + +### Inspecting a config value + +`var content: ConfigContent` + +The configuration content. + +`var isSecret: Bool` + +Whether this value contains sensitive information that should not be logged. + +## Relationships + +### Conforms To + +- `Swift.Copyable` +- `Swift.CustomStringConvertible` +- `Swift.Equatable` +- `Swift.ExpressibleByBooleanLiteral` +- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` +- `Swift.ExpressibleByFloatLiteral` +- `Swift.ExpressibleByIntegerLiteral` +- `Swift.ExpressibleByStringLiteral` +- `Swift.ExpressibleByUnicodeScalarLiteral` +- `Swift.Hashable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`enum ConfigType` + +The supported configuration value types. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- ConfigValue +- Mentioned in +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation + +- Configuration +- Foundation + +Extended Module + +# Foundation + +## Topics + +### Extended Structures + +`extension Date` + +`extension URL` + +`extension UUID` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader + +- Configuration +- ConfigSnapshotReader + +Structure + +# ConfigSnapshotReader + +A container type for reading config values from snapshots. + +struct ConfigSnapshotReader + +ConfigSnapshotReader.swift + +## Overview + +A config snapshot reader provides read-only access to config values stored in an underlying `ConfigSnapshot`. Unlike a config reader, which can access live, changing config values from providers, a snapshot reader works with a fixed, immutable snapshot of the configuration data. + +## Usage + +Get a snapshot reader from a config reader by using the `snapshot()` method. All values in the snapshot are guaranteed to be from the same point in time: + +// Get a snapshot from a ConfigReader +let config = ConfigReader(provider: EnvironmentVariablesProvider()) +let snapshot = config.snapshot() +// Use snapshot to read config values +let cert = snapshot.string(forKey: "cert") +let privateKey = snapshot.string(forKey: "privateKey") +// Ensures that both values are coming from the same +// underlying snapshot and that a provider didn't change +// its internal state between the two `string(...)` calls. +let identity = MyIdentity(cert: cert, privateKey: privateKey) + +Or you can watch for snapshot updates using the `watchSnapshot(fileID:line:updatesHandler:)` method: + +try await config.watchSnapshot { snapshots in +for await snapshot in snapshots { +// Process each new configuration snapshot +let cert = snapshot.string(forKey: "cert") +let privateKey = snapshot.string(forKey: "privateKey") +// Ensures that both values are coming from the same +// underlying snapshot and that a provider didn't change +// its internal state between the two `string(...)` calls. +let newCert = MyCert(cert: cert, privateKey: privateKey) +print("Certificate was updated: \(newCert.redactedDescription)") +} +} + +### Scoping + +Like `ConfigReader`, you can set a key prefix on the config snapshot reader, allowing all config lookups to prepend a prefix to the keys, which lets you pass a scoped snapshot reader to nested components. + +let httpConfig = snapshotReader.scoped(to: "http") +let timeout = httpConfig.int(forKey: "timeout") +// Reads from "http.timeout" in the snapshot + +### Config keys and context + +The library requests config values using a canonical “config key”, that represents a key path. You can provide additional context that was used by some providers when the snapshot was created. + +let httpTimeout = snapshotReader.int( +forKey: ConfigKey("http.timeout", context: ["upstream": "example.com"]), +default: 60 +) + +### Automatic type conversion + +String configuration values can be automatically converted to other types using the `as:` parameter. This works with: + +- Types that you explicitly conform to `ExpressibleByConfigString`. + +- Built-in types that already conform to `ExpressibleByConfigString`: + +- `SystemPackage.FilePath` \- Converts from file paths. + +- `Foundation.URL` \- Converts from URL strings. + +- `Foundation.UUID` \- Converts from UUID strings. + +- `Foundation.Date` \- Converts from ISO8601 date strings. + +// Built-in type conversion +let apiUrl = snapshot.string( +forKey: "api.url", +as: URL.self +) +let requestId = snapshot.string( +forKey: "request.id", +as: UUID.self +) + +enum LogLevel: String { +case debug, info, warning, error +} +let logLevel = snapshot.string( +forKey: "logging.level", +as: LogLevel.self, +default: .info +) + +// Custom type conversion (ExpressibleByConfigString) +struct DatabaseURL: ExpressibleByConfigString { +let url: URL + +init?(configString: String) { +guard let url = URL(string: configString) else { return nil } +self.url = url +} + +var description: String { url.absoluteString } +} +let dbUrl = snapshot.string( +forKey: "database.url", +as: DatabaseURL.self +) + +### Access reporting + +When reading from a snapshot, access events are reported to the access reporter from the original config reader. This helps debug which config values are accessed, even when reading from snapshots. + +## Topics + +### Creating a snapshot + +Returns a snapshot of the current configuration state. + +Watches the configuration for changes. + +### Namespacing + +Returns a scoped snapshot reader by appending the provided key to the current key prefix. + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key, converting from string. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +### Synchronously reading lists of string values + +Synchronously gets an array of config values for the given config key, converting from strings. + +Synchronously gets an array of config values for the given config key with default fallback, converting from strings. + +### Synchronously reading required string values + +Synchronously gets a required config value for the given config key, throwing an error if it’s missing. + +Synchronously gets a required config value for the given config key, converting from string. + +### Synchronously reading required lists of string values + +Synchronously gets a required array of config values for the given config key, converting from strings. + +### Synchronously reading Boolean values + +### Synchronously reading required Boolean values + +### Synchronously reading lists of Boolean values + +### Synchronously reading required lists of Boolean values + +### Synchronously reading integer values + +### Synchronously reading required integer values + +### Synchronously reading lists of integer values + +### Synchronously reading required lists of integer values + +### Synchronously reading double values + +### Synchronously reading required double values + +### Synchronously reading lists of double values + +### Synchronously reading required lists of double values + +### Synchronously reading bytes + +### Synchronously reading required bytes + +### Synchronously reading collections of byte chunks + +### Synchronously reading required collections of byte chunks + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Readers and providers + +`struct ConfigReader` + +A type that provides read-only access to configuration values from underlying providers. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +Choosing the access pattern + +Learn how to select the right method for reading configuration values based on your needs. + +Choosing reader methods + +Choose between optional, default, and required variants of configuration methods. + +Handling secrets correctly + +Protect sensitive configuration values from accidental disclosure in logs and debug output. + +- ConfigSnapshotReader +- Overview +- Usage +- Scoping +- Config keys and context +- Automatic type conversion +- Access reporting +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue + +- Configuration +- ConfigContextValue + +Enumeration + +# ConfigContextValue + +A value that can be stored in a configuration context. + +enum ConfigContextValue + +ConfigContext.swift + +## Overview + +Context values support common data types used for configuration metadata. + +## Topics + +### Configuration context values + +`case string(String)` + +A string value. + +`case bool(Bool)` + +A Boolean value. + +`case int(Int)` + +An integer value. + +`case double(Double)` + +A floating point value. + +## Relationships + +### Conforms To + +- `Swift.Copyable` +- `Swift.CustomStringConvertible` +- `Swift.Equatable` +- `Swift.ExpressibleByBooleanLiteral` +- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` +- `Swift.ExpressibleByFloatLiteral` +- `Swift.ExpressibleByIntegerLiteral` +- `Swift.ExpressibleByStringLiteral` +- `Swift.ExpressibleByUnicodeScalarLiteral` +- `Swift.Hashable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Configuration keys + +`struct ConfigKey` + +A configuration key representing a relative path to a configuration value. + +`struct AbsoluteConfigKey` + +A configuration key that represents an absolute path to a configuration value. + +- ConfigContextValue +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader + +- Configuration +- ConfigReader + +Structure + +# ConfigReader + +A type that provides read-only access to configuration values from underlying providers. + +struct ConfigReader + +ConfigReader.swift + +## Mentioned in + +Configuring libraries + +Example use cases + +Using reloading providers + +## Overview + +Use `ConfigReader` to access configuration values from various sources like environment variables, JSON files, or in-memory stores. The reader supports provider hierarchies, key scoping, and access reporting for debugging configuration usage. + +## Usage + +To read configuration values, create a config reader with one or more providers: + +let config = ConfigReader(provider: EnvironmentVariablesProvider()) +let httpTimeout = config.int(forKey: "http.timeout", default: 60) + +### Using multiple providers + +Create a hierarchy of providers by passing an array to the initializer. The reader queries providers in order, using the first non-nil value it finds: + +do { +let config = ConfigReader(providers: [\ +// First, check environment variables\ +EnvironmentVariablesProvider(),\ +// Then, check a JSON config file\ + +// Finally, fall \ +]) + +// Uses the first provider that has a value for "http.timeout" +let timeout = config.int(forKey: "http.timeout", default: 15) +} catch { +print("Failed to create JSON provider: \(error)") +} + +The `get` and `fetch` methods query providers sequentially, while the `watch` method monitors all providers in parallel and returns the first non-nil value from the latest results. + +### Creating scoped readers + +Create a scoped reader to access nested configuration sections without repeating key prefixes. This is useful for passing configuration to specific components. + +Given this JSON configuration: + +{ +"http": { +"timeout": 60 +} +} + +Create a scoped reader for the HTTP section: + +let httpConfig = config.scoped(to: "http") +let timeout = httpConfig.int(forKey: "timeout") // Reads "http.timeout" + +### Understanding config keys + +The library accesses configuration values using config keys that represent a hierarchical path to the value. Internally, the library represents a key as a list of string components, such as `["http", "timeout"]`. + +### Using configuration context + +Provide additional context to help providers return more specific values. In the following example with a configuration that includes repeated configurations per “upstream”, the value returned is potentially constrained to the configuration with the matching context: + +let httpTimeout = config.int( +forKey: ConfigKey("http.timeout", context: ["upstream": "example.com"]), +default: 60 +) + +Providers can use this context to return specialized values or fall + +The library can automatically convert string configuration values to other types using the `as:` parameter. This works with: + +- Types that you explicitly conform to `ExpressibleByConfigString`. + +- Built-in types that already conform to `ExpressibleByConfigString`: + +- `SystemPackage.FilePath` \- Converts from file paths. + +- `Foundation.URL` \- Converts from URL strings. + +- `Foundation.UUID` \- Converts from UUID strings. + +- `Foundation.Date` \- Converts from ISO8601 date strings. + +// Built-in type conversion +let apiUrl = config.string(forKey: "api.url", as: URL.self) +let requestId = config.string( +forKey: "request.id", +as: UUID.self +) + +enum LogLevel: String { +case debug, info, warning, error +} +let logLevel = config.string( +forKey: "logging.level", +as: LogLevel.self, +default: .info +) + +// Custom type conversion (ExpressibleByConfigString) +struct DatabaseURL: ExpressibleByConfigString { +let url: URL + +init?(configString: String) { +guard let url = URL(string: configString) else { return nil } +self.url = url +} + +var description: String { url.absoluteString } +} +let dbUrl = config.string( +forKey: "database.url", +as: DatabaseURL.self +) + +### How providers encode keys + +Each `ConfigProvider` interprets config keys according to its data source format. For example, `EnvironmentVariablesProvider` converts `["http", "timeout"]` to the environment variable name `HTTP_TIMEOUT` by uppercasing components and joining with underscores. + +### Monitoring configuration access + +Use an access reporter to track which configuration values your application reads. The reporter receives `AccessEvent` instances containing the requested key, calling code location, returned value, and source provider. + +This helps debug configuration issues and to discover the config dependencies in your codebase. + +### Protecting sensitive values + +Mark sensitive configuration values as secrets to prevent logging by access loggers. Both config readers and providers can set the `isSecret` property. When either marks a value as sensitive, `AccessReporter` instances should not log the raw value. + +### Configuration context + +Configuration context supplements the configuration key components with extra metadata that providers can use to refine value lookups or return more specific results. Context is particularly useful for scenarios where the same configuration key might need different values based on runtime conditions. + +Create context using dictionary literal syntax with automatic type inference: + +let context: [String: ConfigContextValue] = [\ +"environment": "production",\ +"region": "us-west-2",\ +"timeout": 30,\ +"retryEnabled": true\ +] + +#### Provider behavior + +Not all providers use context information. Providers that support context can: + +- Return specialized values based on context keys. + +- Fall , +default: "localhost:5432" +) + +### Error handling behavior + +The config reader handles provider errors differently based on the method type: + +- **Get and watch methods**: Gracefully handle errors by returning `nil` or default values, except for “required” variants which rethrow errors. + +- **Fetch methods**: Always rethrow both provider and conversion errors. + +- **Required methods**: Rethrow all errors without fallback behavior. + +The library reports all provider errors to the access reporter through the `providerResults` array, even when handled gracefully. + +## Topics + +### Creating config readers + +`init(provider: some ConfigProvider, accessReporter: (any AccessReporter)?)` + +Creates a config reader with a single provider. + +[`init(providers: [any ConfigProvider], accessReporter: (any AccessReporter)?)`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(providers:accessreporter:)) + +Creates a config reader with multiple providers. + +### Retrieving a scoped config reader + +Returns a scoped config reader with the specified key appended to the current prefix. + +### Reading from a snapshot + +Returns a snapshot of the current configuration state. + +Watches the configuration for changes. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Readers and providers + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`struct ConfigSnapshotReader` + +A container type for reading config values from snapshots. + +Choosing the access pattern + +Learn how to select the right method for reading configuration values based on your needs. + +Choosing reader methods + +Choose between optional, default, and required variants of configuration methods. + +Handling secrets correctly + +Protect sensitive configuration values from accidental disclosure in logs and debug output. + +- ConfigReader +- Mentioned in +- Overview +- Usage +- Using multiple providers +- Creating scoped readers +- Understanding config keys +- Using configuration context +- Automatic type conversion +- How providers encode keys +- Monitoring configuration access +- Protecting sensitive values +- Configuration context +- Error handling behavior +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromstringdecoder + +- Configuration +- ConfigBytesFromStringDecoder + +Protocol + +# ConfigBytesFromStringDecoder + +A protocol for decoding string configuration values into byte arrays. + +protocol ConfigBytesFromStringDecoder : Sendable + +ConfigBytesFromStringDecoder.swift + +## Overview + +This protocol defines the interface for converting string-based configuration values into binary data. Different implementations can support various encoding formats such as base64, hexadecimal, or other custom encodings. + +## Usage + +Implementations of this protocol are used by configuration providers that need to convert string values to binary data, such as cryptographic keys, certificates, or other binary configuration data. + +let decoder: ConfigBytesFromStringDecoder = .base64 +let bytes = decoder.decode("SGVsbG8gV29ybGQ=") // "Hello World" in base64 + +## Topics + +### Required methods + +Decodes a string value into an array of bytes. + +**Required** + +### Built-in decoders + +`static var base64: ConfigBytesFromBase64StringDecoder` + +A decoder that interprets string values as base64-encoded data. + +`static var hex: ConfigBytesFromHexStringDecoder` + +A decoder that interprets string values as hexadecimal-encoded data. + +## Relationships + +### Inherits From + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +### Conforming Types + +- `ConfigBytesFromBase64StringDecoder` +- `ConfigBytesFromHexStringDecoder` + +## See Also + +### Value conversion + +`protocol ExpressibleByConfigString` + +A protocol for types that can be initialized from configuration string values. + +`struct ConfigBytesFromBase64StringDecoder` + +A decoder that converts base64-encoded strings into byte arrays. + +`struct ConfigBytesFromHexStringDecoder` + +A decoder that converts hexadecimal-encoded strings into byte arrays. + +- ConfigBytesFromStringDecoder +- Overview +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfrombase64stringdecoder + +- Configuration +- ConfigBytesFromBase64StringDecoder + +Structure + +# ConfigBytesFromBase64StringDecoder + +A decoder that converts base64-encoded strings into byte arrays. + +struct ConfigBytesFromBase64StringDecoder + +ConfigBytesFromStringDecoder.swift + +## Overview + +This decoder interprets string configuration values as base64-encoded data and converts them to their binary representation. + +## Topics + +### Creating bytes from a base64 string + +`init()` + +Creates a new base64 decoder. + +## Relationships + +### Conforms To + +- `ConfigBytesFromStringDecoder` +- `Swift.Copyable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Value conversion + +`protocol ExpressibleByConfigString` + +A protocol for types that can be initialized from configuration string values. + +`protocol ConfigBytesFromStringDecoder` + +A protocol for decoding string configuration values into byte arrays. + +`struct ConfigBytesFromHexStringDecoder` + +A decoder that converts hexadecimal-encoded strings into byte arrays. + +- ConfigBytesFromBase64StringDecoder +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype + +- Configuration +- ConfigType + +Enumeration + +# ConfigType + +The supported configuration value types. + +@frozen +enum ConfigType + +ConfigProvider.swift + +## Topics + +### Types of configuration content + +`case string` + +A string value. + +`case stringArray` + +An array of string values. + +`case bool` + +A Boolean value. + +`case boolArray` + +An array of Boolean values. + +`case int` + +An integer value. + +`case intArray` + +An array of integer values. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +### Initializers + +`init?(rawValue: String)` + +## Relationships + +### Conforms To + +- `Swift.BitwiseCopyable` +- `Swift.Equatable` +- `Swift.Hashable` +- `Swift.RawRepresentable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`struct LookupResult` + +The result of looking up a configuration value in a provider. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- ConfigType +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent + +- Configuration +- AccessEvent + +Structure + +# AccessEvent + +An event that captures information about accessing a configuration value. + +struct AccessEvent + +AccessReporter.swift + +## Overview + +Access events are generated whenever configuration values are accessed through `ConfigReader` and `ConfigSnapshotReader` methods. They contain metadata about the access, results from individual providers, and the final outcome of the operation. + +## Topics + +### Creating an access event + +Creates a configuration access event. + +`struct Metadata` + +Metadata describing the configuration access operation. + +`struct ProviderResult` + +The result of a configuration lookup from a specific provider. + +### Inspecting an access event + +The final outcome of the configuration access operation. + +`var conversionError: (any Error)?` + +An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. + +`var metadata: AccessEvent.Metadata` + +Metadata that describes the configuration access operation. + +[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) + +The results from each configuration provider that was queried. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Troubleshooting and access reporting + +Troubleshooting and access reporting + +Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. + +`protocol AccessReporter` + +A type that receives and processes configuration access events. + +`class AccessLogger` + +An access reporter that logs configuration access events using the Swift Log API. + +`class FileAccessLogger` + +An access reporter that writes configuration access events to a file. + +`struct BroadcastingAccessReporter` + +An access reporter that forwards events to multiple other reporters. + +- AccessEvent +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter + +- Configuration +- BroadcastingAccessReporter + +Structure + +# BroadcastingAccessReporter + +An access reporter that forwards events to multiple other reporters. + +struct BroadcastingAccessReporter + +AccessReporter.swift + +## Overview + +Use this reporter to send configuration access events to multiple destinations simultaneously. Each upstream reporter receives a copy of every event in the order they were provided during initialization. + +let fileLogger = try FileAccessLogger(filePath: "/tmp/config.log") +let accessLogger = AccessLogger(logger: logger) +let broadcaster = BroadcastingAccessReporter(upstreams: [fileLogger, accessLogger]) + +let config = ConfigReader( +provider: EnvironmentVariablesProvider(), +accessReporter: broadcaster +) + +## Topics + +### Creating a broadcasting access reporter + +[`init(upstreams: [any AccessReporter])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter/init(upstreams:)) + +Creates a new broadcasting access reporter. + +## Relationships + +### Conforms To + +- `AccessReporter` +- `Swift.Copyable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Troubleshooting and access reporting + +Troubleshooting and access reporting + +Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. + +`protocol AccessReporter` + +A type that receives and processes configuration access events. + +`class AccessLogger` + +An access reporter that logs configuration access events using the Swift Log API. + +`class FileAccessLogger` + +An access reporter that writes configuration access events to a file. + +`struct AccessEvent` + +An event that captures information about accessing a configuration value. + +- BroadcastingAccessReporter +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/lookupresult + +- Configuration +- LookupResult + +Structure + +# LookupResult + +The result of looking up a configuration value in a provider. + +struct LookupResult + +ConfigProvider.swift + +## Overview + +Providers return this result from value lookup methods, containing both the encoded key used for the lookup and the value found: + +let result = try provider.value(forKey: key, type: .string) +if let value = result.value { +print("Found: \(value)") +} + +## Topics + +### Creating a lookup result + +`init(encodedKey: String, value: ConfigValue?)` + +Creates a lookup result. + +### Inspecting a lookup result + +`var encodedKey: String` + +The provider-specific encoding of the configuration key. + +`var value: ConfigValue?` + +The configuration value found for the key, or nil if not found. + +## Relationships + +### Conforms To + +- `Swift.Equatable` +- `Swift.Hashable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a custom provider + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +`protocol FileParsingOptions` + +A type that provides parsing options for file configuration snapshots. + +`protocol ConfigProvider` + +A type that provides configuration values from a data source. + +`enum ConfigContent` + +The raw content of a configuration value. + +`struct ConfigValue` + +A configuration value that wraps content with metadata. + +`enum ConfigType` + +The supported configuration value types. + +`enum SecretsSpecifier` + +A specification for identifying which configuration values contain sensitive information. + +`struct ConfigUpdatesAsyncSequence` + +A concrete async sequence for delivering updated configuration values. + +- LookupResult +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/proposals + +- Configuration +- Proposals + +# Proposals + +Collaborate on API changes to Swift Configuration by writing a proposal. + +## Overview + +For non-trivial changes that affect the public API, the Swift Configuration project adopts a lightweight version of the Swift Evolution process. + +Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times. + +While it’s encouraged to get feedback by opening a pull request with a proposal early in the process, it’s also important to consider the complexity of the implementation when evaluating different solutions. For example, this might mean including a link to a branch containing a prototype implementation of the feature in the pull request description. + +### Steps + +1. Make sure there’s a GitHub issue for the feature or change you would like to propose. + +2. Duplicate the `SCO-NNNN.md` document and replace `NNNN` with the next available proposal number. + +3. Link the GitHub issue from your proposal, and fill in the proposal. + +4. Open a pull request with your proposal and solicit feedback from other contributors. + +5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred. + +6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal. + +7. The proposal is considered Approved once the implementation, proposal PRs have been merged, and, if originally disabled by a feature flag, feature flag enabled unconditionally. + +If you have any questions, ask in an issue on GitHub. + +### Possible review states + +- Awaiting Review + +- In Review + +- Ready for Implementation + +- In Preview + +- Approved + +- Deferred + +## Topics + +SCO-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SCO-0001: Generic file providers + +Introduce format-agnostic providers to simplify implementing additional file formats beyond JSON and YAML. + +SCO-0002: Remove custom key decoders + +Remove the custom key decoder feature to fix a flaw and simplify the project + +SCO-0003: Allow missing files in file providers + +Add an `allowMissing` parameter to file-based providers to handle missing configuration files gracefully. + +## See Also + +### Contributing + +Developing Swift Configuration + +Learn about tools and conventions used to develop the Swift Configuration package. + +- Proposals +- Overview +- Steps +- Possible review states +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/inmemoryprovider + +- Configuration +- InMemoryProvider + +Structure + +# InMemoryProvider + +A configuration provider that stores values in memory. + +struct InMemoryProvider + +InMemoryProvider.swift + +## Mentioned in + +Using in-memory providers + +Configuring applications + +Example use cases + +## Overview + +This provider maintains a static dictionary of configuration values in memory, making it ideal for providing default values, overrides, or test configurations. Values are immutable once the provider is created and never change over time. + +## Use cases + +The in-memory provider is particularly useful for: + +- **Default configurations**: Providing fallback values when other providers don’t have a value + +- **Configuration overrides**: Taking precedence over other providers + +- **Testing**: Creating predictable configuration states for unit tests + +- **Static configurations**: Embedding compile-time configuration values + +## Value types + +The provider supports all standard configuration value types and automatically handles type validation. Values must match the requested type exactly - no automatic conversion is performed - for example, requesting a `String` value for a key that stores an `Int` value will throw an error. + +## Performance characteristics + +This provider offers O(1) lookup time and performs no I/O operations. All values are stored in memory. + +## Usage + +let provider = InMemoryProvider(values: [\ +"http.client.user-agent": "Config/1.0 (Test)",\ +"http.client.timeout": 15.0,\ +"http.secret": ConfigValue("s3cret", isSecret: true),\ +"http.version": 2,\ +"enabled": true\ +]) +// Prints all values, redacts "http.secret" automatically. +print(provider) +let config = ConfigReader(provider: provider) +let isEnabled = config.bool(forKey: "enabled", default: false) + +To learn more about the in-memory providers, check out Using in-memory providers. + +## Topics + +### Creating an in-memory provider + +[`init(name: String?, values: [AbsoluteConfigKey : ConfigValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/inmemoryprovider/init(name:values:)) + +Creates a new in-memory provider with the specified configuration values. + +## Relationships + +### Conforms To + +- `ConfigProvider` +- `Swift.Copyable` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Built-in providers + +`struct EnvironmentVariablesProvider` + +A configuration provider that sources values from environment variables. + +`struct CommandLineArgumentsProvider` + +A configuration provider that sources values from command-line arguments. + +`struct FileProvider` + +A configuration provider that reads from a file on disk using a configurable snapshot type. + +`class ReloadingFileProvider` + +A configuration provider that reads configuration from a file on disk with automatic reloading capability. + +`struct JSONSnapshot` + +A snapshot of configuration values parsed from JSON data. + +`class YAMLSnapshot` + +A snapshot of configuration values parsed from YAML data. + +Using reloading providers + +Automatically reload configuration from files when they change. + +`struct DirectoryFilesProvider` + +A configuration provider that reads values from individual files in a directory. + +Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. + +`class MutableInMemoryProvider` + +A configuration provider that stores mutable values in memory. + +`struct KeyMappingProvider` + +A configuration provider that maps all keys before delegating to an upstream provider. + +- InMemoryProvider +- Mentioned in +- Overview +- Use cases +- Value types +- Performance characteristics +- Usage +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configuring-libraries + +- Configuration +- Configuring libraries + +Article + +# Configuring libraries + +Provide a consistent and flexible way to configure your library. + +## Overview + +Swift Configuration provides a pattern for configuring libraries that works across various configuration sources: environment variables, JSON files, and remote configuration services. + +This guide shows how to adopt this pattern in your library to make it easier to compose in larger applications. + +Adopt this pattern in three steps: + +1. Define your library’s configuration as a dedicated type (you might already have such a type in your library). + +2. Add a convenience method that accepts a `ConfigReader` \- can be an initializer, or a method that updates your configuration. + +3. Extract the individual configuration values using the provided reader. + +This approach makes your library configurable regardless of the user’s chosen configuration source and composes well with other libraries. + +### Define your configuration type + +Start by defining a type that encapsulates all the configuration options for your library. + +/// Configuration options for a hypothetical HTTPClient. +public struct HTTPClientConfiguration { +/// The timeout for network requests in seconds. +public var timeout: Double + +/// The maximum number of concurrent connections. +public var maxConcurrentConnections: Int + +/// Base URL for API requests. +public var baseURL: String + +/// Whether to enable debug logging. +public var debugLogging: Bool + +/// Create a configuration with explicit values. +public init( +timeout: Double = 30.0, +maxConcurrentConnections: Int = 5, +baseURL: String = "https://api.example.com", +debugLogging: Bool = false +) { +self.timeout = timeout +self.maxConcurrentConnections = maxConcurrentConnections +self.baseURL = baseURL +self.debugLogging = debugLogging +} +} + +### Add a convenience method + +Next, extend your configuration type to provide a method that accepts a `ConfigReader` as a parameter. In the example below, we use an initializer. + +extension HTTPClientConfiguration { +/// Creates a new HTTP client configuration using values from the provided reader. +/// +/// ## Configuration keys +/// - `timeout` (double, optional, default: `30.0`): The timeout for network requests in seconds. +/// - `maxConcurrentConnections` (int, optional, default: `5`): The maximum number of concurrent connections. +/// - `baseURL` (string, optional, default: `"https://api.example.com"`): Base URL for API requests. +/// - `debugLogging` (bool, optional, default: `false`): Whether to enable debug logging. +/// +/// - Parameter config: The config reader to read configuration values from. +public init(config: ConfigReader) { +self.timeout = config.double(forKey: "timeout", default: 30.0) +self.maxConcurrentConnections = config.int(forKey: "maxConcurrentConnections", default: 5) +self.baseURL = config.string(forKey: "baseURL", default: "https://api.example.com") +self.debugLogging = config.bool(forKey: "debugLogging", default: false) +} +} + +### Example: Adopting your library + +Once you’ve made your library configurable, users can easily configure it from various sources. Here’s how someone might configure your library using environment variables: + +import Configuration +import YourHTTPLibrary + +// Create a config reader from environment variables. +let config = ConfigReader(provider: EnvironmentVariablesProvider()) + +// Initialize your library's configuration from a config reader. +let httpConfig = HTTPClientConfiguration(config: config) + +// Create your library instance with the configuration. +let httpClient = HTTPClient(configuration: httpConfig) + +// Start using your library. +httpClient.get("/users") { response in +// Handle the response. +} + +With this approach, users can configure your library by setting environment variables that match your config keys: + +# Set configuration for your library through environment variables. +export TIMEOUT=60.0 +export MAX_CONCURRENT_CONNECTIONS=10 +export BASE_URL="https://api.production.com" +export DEBUG_LOGGING=true + +Your library now adapts to the user’s environment without any code changes. + +### Working with secrets + +Mark configuration values that contain sensitive information as secret to prevent them from being logged: + +extension HTTPClientConfiguration { +public init(config: ConfigReader) throws { +self.apiKey = try config.requiredString(forKey: "apiKey", isSecret: true) +// Other configuration... +} +} + +Built-in `AccessReporter` types such as `AccessLogger` and `FileAccessLogger` automatically redact secret values to avoid leaking sensitive information. + +For more guidance on secrets handling, see Handling secrets correctly. For more configuration guidance, check out Adopting best practices. To understand different access patterns and reader methods, refer to Choosing the access pattern and Choosing reader methods. + +## See Also + +### Essentials + +Configuring applications + +Provide flexible and consistent configuration for your application. + +Example use cases + +Review common use cases with ready-to-copy code samples. + +Adopting best practices + +Follow these principles to make your code easily configurable and composable with other libraries. + +- Configuring libraries +- Overview +- Define your configuration type +- Add a convenience method +- Example: Adopting your library +- Working with secrets +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/configsnapshot-implementations + +- Configuration +- YAMLSnapshot +- ConfigSnapshot Implementations + +API Collection + +# ConfigSnapshot Implementations + +## Topics + +### Instance Methods + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/init(data:providername:parsingoptions:) + +#app-main) + +- Configuration +- YAMLSnapshot +- init(data:providerName:parsingOptions:) + +Initializer + +# init(data:providerName:parsingOptions:) + +Inherited from `FileConfigSnapshot.init(data:providerName:parsingOptions:)`. + +convenience init( +data: RawSpan, +providerName: String, +parsingOptions: YAMLSnapshot.ParsingOptions +) throws + +YAMLSnapshot.swift + +## See Also + +### Creating a YAML snapshot + +`struct ParsingOptions` + +Custom input configuration for YAML snapshot creation. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/parsingoptions + +- Configuration +- YAMLSnapshot +- YAMLSnapshot.ParsingOptions + +Structure + +# YAMLSnapshot.ParsingOptions + +Custom input configuration for YAML snapshot creation. + +struct ParsingOptions + +YAMLSnapshot.swift + +## Overview + +This struct provides configuration options for parsing YAML data into configuration snapshots, including byte decoding and secrets specification. + +## Topics + +### Initializers + +Creates custom input configuration for YAML snapshots. + +### Instance Properties + +`var bytesDecoder: any ConfigBytesFromStringDecoder` + +A decoder of bytes from a string. + +A specifier for determining which configuration values should be treated as secrets. + +### Type Properties + +``static var `default`: YAMLSnapshot.ParsingOptions`` + +The default custom input configuration. + +## Relationships + +### Conforms To + +- `FileParsingOptions` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a YAML snapshot + +`convenience init(data: RawSpan, providerName: String, parsingOptions: YAMLSnapshot.ParsingOptions) throws` + +- YAMLSnapshot.ParsingOptions +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest + +- ConfigurationTesting +- ProviderCompatTest + +Structure + +# ProviderCompatTest + +A comprehensive test suite for validating `ConfigProvider` implementations. + +struct ProviderCompatTest + +ProviderCompatTest.swift + +## Overview + +This test suite verifies that configuration providers correctly implement all required functionality including synchronous and asynchronous value retrieval, snapshot operations, and value watching capabilities. + +## Usage + +Create a test instance with your provider and run the compatibility tests: + +let provider = MyCustomProvider() +let test = ProviderCompatTest(provider: provider) +try await test.runTest() + +## Required Test Data + +The provider under test must be populated with specific test values to ensure comprehensive validation. The required configuration data includes: + +\ +"string": String("Hello"),\ +"other.string": String("Other Hello"),\ +"int": Int(42),\ +"other.int": Int(24),\ +"double": Double(3.14),\ +"other.double": Double(2.72),\ +"bool": Bool(true),\ +"other.bool": Bool(false),\ +"bytes": [UInt8,\ +"other.bytes": UInt8,\ +"stringy.array": String,\ +"other.stringy.array": String,\ +"inty.array": Int,\ +"other.inty.array": Int,\ +"doubly.array": Double,\ +"other.doubly.array": Double,\ +"booly.array": Bool,\ +"other.booly.array": Bool,\ +"byteChunky.array": [[UInt8]]([.magic, .magic2]),\ +"other.byteChunky.array": [[UInt8]]([.magic, .magic2, .magic]),\ +] + +## Topics + +### Structures + +`struct TestConfiguration` + +Configuration options for customizing test behavior. + +### Initializers + +`init(provider: any ConfigProvider, configuration: ProviderCompatTest.TestConfiguration)` + +Creates a new compatibility test suite. + +### Instance Methods + +`func runTest() async throws` + +Executes the complete compatibility test suite. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +- ProviderCompatTest +- Overview +- Usage +- Required Test Data +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileconfigsnapshot + +- Configuration +- FileConfigSnapshot + +Protocol + +# FileConfigSnapshot + +A protocol for configuration snapshots created from file data. + +protocol FileConfigSnapshot : ConfigSnapshot, CustomDebugStringConvertible, CustomStringConvertible + +FileProviderSnapshot.swift + +## Overview + +This protocol extends `ConfigSnapshot` to provide file-specific functionality for creating configuration snapshots from raw file data. Types conforming to this protocol can parse various file formats (such as JSON and YAML) and convert them into configuration values. + +Commonly used with `FileProvider` and `ReloadingFileProvider`. + +## Implementation + +To create a custom file configuration snapshot: + +struct MyFormatSnapshot: FileConfigSnapshot { +typealias ParsingOptions = MyParsingOptions + +let values: [String: ConfigValue] +let providerName: String + +init(data: RawSpan, providerName: String, parsingOptions: MyParsingOptions) throws { +self.providerName = providerName +// Parse the data according to your format +self.values = try parseMyFormat(data, using: parsingOptions) +} +} + +The snapshot is responsible for parsing the file data and converting it into a representation of configuration values that can be queried by the configuration system. + +## Topics + +### Required methods + +`init(data: RawSpan, providerName: String, parsingOptions: Self.ParsingOptions) throws` + +Creates a new snapshot from file data. + +**Required** + +`associatedtype ParsingOptions : FileParsingOptions` + +The parsing options type used for parsing this snapshot. + +### Protocol requirements + +`protocol ConfigSnapshot` + +An immutable snapshot of a configuration provider’s state. + +## Relationships + +### Inherits From + +- `ConfigSnapshot` +- `Swift.CustomDebugStringConvertible` +- `Swift.CustomStringConvertible` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +### Conforming Types + +- `JSONSnapshot` +- `YAMLSnapshot` + +- FileConfigSnapshot +- Overview +- Implementation +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/providername + +- Configuration +- YAMLSnapshot +- providerName + +Instance Property + +# providerName + +The name of the provider that created this snapshot. + +let providerName: String + +YAMLSnapshot.swift + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/customdebugstringconvertible-implementations + +- Configuration +- YAMLSnapshot +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/customstringconvertible-implementations + +- Configuration +- YAMLSnapshot +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/fileconfigsnapshot-implementations + +- Configuration +- YAMLSnapshot +- FileConfigSnapshot Implementations + +API Collection + +# FileConfigSnapshot Implementations + +## Topics + +### Initializers + +`convenience init(data: RawSpan, providerName: String, parsingOptions: YAMLSnapshot.ParsingOptions) throws` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accesslogger/accessreporter-implementations + +- Configuration +- AccessLogger +- AccessReporter Implementations + +API Collection + +# AccessReporter Implementations + +## Topics + +### Instance Methods + +`func report(AccessEvent)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/init(data:providername:parsingoptions:) + +#app-main) + +- Configuration +- JSONSnapshot +- init(data:providerName:parsingOptions:) + +Initializer + +# init(data:providerName:parsingOptions:) + +Inherited from `FileConfigSnapshot.init(data:providerName:parsingOptions:)`. + +init( +data: RawSpan, +providerName: String, +parsingOptions: JSONSnapshot.ParsingOptions +) throws + +JSONSnapshot.swift + +## See Also + +### Creating a JSON snapshot + +`struct ParsingOptions` + +Parsing options for JSON snapshot creation. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/customstringconvertible-implementations + +- Configuration +- JSONSnapshot +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/parsingoptions + +- Configuration +- JSONSnapshot +- JSONSnapshot.ParsingOptions + +Structure + +# JSONSnapshot.ParsingOptions + +Parsing options for JSON snapshot creation. + +struct ParsingOptions + +JSONSnapshot.swift + +## Overview + +This struct provides configuration options for parsing JSON data into configuration snapshots, including byte decoding and secrets specification. + +## Topics + +### Initializers + +Creates parsing options for JSON snapshots. + +### Instance Properties + +`var bytesDecoder: any ConfigBytesFromStringDecoder` + +A decoder of bytes from a string. + +A specifier for determining which configuration values should be treated as secrets. + +### Type Properties + +``static var `default`: JSONSnapshot.ParsingOptions`` + +The default parsing options. + +## Relationships + +### Conforms To + +- `FileParsingOptions` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating a JSON snapshot + +`init(data: RawSpan, providerName: String, parsingOptions: JSONSnapshot.ParsingOptions) throws` + +- JSONSnapshot.ParsingOptions +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/customdebugstringconvertible-implementations + +- Configuration +- JSONSnapshot +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/run() + +#app-main) + +- Configuration +- ReloadingFileProvider +- run() + +Instance Method + +# run() + +Inherited from `Service.run()`. + +func run() async throws + +ReloadingFileProvider.swift + +Available when `Snapshot` conforms to `FileConfigSnapshot`. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/providername + +- Configuration +- JSONSnapshot +- providerName + +Instance Property + +# providerName + +The name of the provider that created this snapshot. + +let providerName: String + +JSONSnapshot.swift + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/fileconfigsnapshot-implementations + +- Configuration +- JSONSnapshot +- FileConfigSnapshot Implementations + +API Collection + +# FileConfigSnapshot Implementations + +## Topics + +### Initializers + +`init(data: RawSpan, providerName: String, parsingOptions: JSONSnapshot.ParsingOptions) throws` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accesslogger/init(logger:level:message:) + +#app-main) + +- Configuration +- AccessLogger +- init(logger:level:message:) + +Initializer + +# init(logger:level:message:) + +Creates a new access logger that reports configuration access events. + +init( +logger: Logger, +level: Logger.Level = .debug, +message: Logger.Message = "Config value accessed" +) + +AccessLogger.swift + +## Parameters + +`logger` + +The logger to emit access events to. + +`level` + +The log level for access events. Defaults to `.debug`. + +`message` + +The static message text for log entries. Defaults to “Config value accessed”. + +## Discussion + +let logger = Logger(label: "my.app.config") + +// Log at debug level by default +let accessLogger = AccessLogger(logger: logger) + +// Customize the log level +let accessLogger = AccessLogger(logger: logger, level: .info) + +- init(logger:level:message:) +- Parameters +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/providername + +- Configuration +- ReloadingFileProvider +- providerName + +Instance Property + +# providerName + +The human-readable name of the provider. + +let providerName: String + +ReloadingFileProvider.swift + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/configsnapshot-implementations + +- Configuration +- JSONSnapshot +- ConfigSnapshot Implementations + +API Collection + +# ConfigSnapshot Implementations + +## Topics + +### Instance Methods + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/init(snapshottype:parsingoptions:filepath:allowmissing:pollinterval:logger:metrics:) + +#app-main) + +- Configuration +- ReloadingFileProvider +- init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:) + +Initializer + +# init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:) + +Creates a reloading file provider that monitors the specified file path. + +convenience init( +snapshotType: Snapshot.Type = Snapshot.self, +parsingOptions: Snapshot.ParsingOptions = .default, +filePath: FilePath, +allowMissing: Bool = false, +pollInterval: Duration = .seconds(15), +logger: Logger = Logger(label: "ReloadingFileProvider"), +metrics: any MetricsFactory = MetricsSystem.factory +) async throws + +ReloadingFileProvider.swift + +## Parameters + +`snapshotType` + +The type of snapshot to create from the file contents. + +`parsingOptions` + +Options used by the snapshot to parse the file data. + +`filePath` + +The path to the configuration file to monitor. + +`allowMissing` + +A flag controlling how the provider handles a missing file. + +- When `false` (the default), if the file is missing or malformed, throws an error. + +- When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. + +`pollInterval` + +How often to check for file changes. + +`logger` + +The logger instance to use for this provider. + +`metrics` + +The metrics factory to use for monitoring provider performance. + +## Discussion + +## See Also + +### Creating a reloading file provider + +`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader, logger: Logger, metrics: any MetricsFactory) async throws` + +Creates a reloading file provider using configuration from a reader. + +- init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/customdebugstringconvertible-implementations + +- Configuration +- ReloadingFileProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/customstringconvertible-implementations + +- Configuration +- ReloadingFileProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/init(snapshottype:parsingoptions:config:) + +#app-main) + +- Configuration +- FileProvider +- init(snapshotType:parsingOptions:config:) + +Initializer + +# init(snapshotType:parsingOptions:config:) + +Creates a file provider using a file path from a configuration reader. + +init( +snapshotType: Snapshot.Type = Snapshot.self, +parsingOptions: Snapshot.ParsingOptions = .default, +config: ConfigReader +) async throws + +FileProvider.swift + +## Parameters + +`snapshotType` + +The type of snapshot to create from the file contents. + +`parsingOptions` + +Options used by the snapshot to parse the file data. + +`config` + +A configuration reader that contains the required configuration keys. + +## Discussion + +This initializer reads the file path from the provided configuration reader and creates a snapshot from that file. + +## Configuration keys + +- `filePath` (string, required): The path to the configuration file to read. + +- `allowMissing` (bool, optional, default: false): A flag controlling how the provider handles a missing file. When `false` (the default), if the file is missing or malformed, throws an error. When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. + +## See Also + +### Creating a file provider + +`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool) async throws` + +Creates a file provider that reads from the specified file path. + +- init(snapshotType:parsingOptions:config:) +- Parameters +- Discussion +- Configuration keys +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/customstringconvertible-implementations + +- Configuration +- FileProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/customdebugstringconvertible-implementations + +- Configuration +- FileProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/init(snapshottype:parsingoptions:filepath:allowmissing:) + +#app-main) + +- Configuration +- FileProvider +- init(snapshotType:parsingOptions:filePath:allowMissing:) + +Initializer + +# init(snapshotType:parsingOptions:filePath:allowMissing:) + +Creates a file provider that reads from the specified file path. + +init( +snapshotType: Snapshot.Type = Snapshot.self, +parsingOptions: Snapshot.ParsingOptions = .default, +filePath: FilePath, +allowMissing: Bool = false +) async throws + +FileProvider.swift + +## Parameters + +`snapshotType` + +The type of snapshot to create from the file contents. + +`parsingOptions` + +Options used by the snapshot to parse the file data. + +`filePath` + +The path to the configuration file to read. + +`allowMissing` + +A flag controlling how the provider handles a missing file. + +- When `false` (the default), if the file is missing or malformed, throws an error. + +- When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. + +## Discussion + +This initializer reads the file at the given path and creates a snapshot using the specified snapshot type. The file is read once during initialization. + +## See Also + +### Creating a file provider + +`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader) async throws` + +Creates a file provider using a file path from a configuration reader. + +- init(snapshotType:parsingOptions:filePath:allowMissing:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/configprovider-implementations + +- Configuration +- ReloadingFileProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/init(environmentvariables:secretsspecifier:bytesdecoder:arrayseparator:) + +#app-main) + +- Configuration +- EnvironmentVariablesProvider +- init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:) + +Initializer + +# init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:) + +Creates a new provider from a custom dictionary of environment variables. + +init( +environmentVariables: [String : String], + +bytesDecoder: some ConfigBytesFromStringDecoder = .base64, +arraySeparator: Character = "," +) + +EnvironmentVariablesProvider.swift + +## Parameters + +`environmentVariables` + +A dictionary of environment variable names and values. + +`secretsSpecifier` + +Specifies which environment variables should be treated as secrets. + +`bytesDecoder` + +The decoder used for converting string values to byte arrays. + +`arraySeparator` + +The character used to separate elements in array values. + +## Discussion + +This initializer allows you to provide a custom set of environment variables, which is useful for testing or when you want to override specific values. + +let customEnvironment = [\ +"DATABASE_HOST": "localhost",\ +"DATABASE_PORT": "5432",\ +"API_KEY": "secret-key"\ +] +let provider = EnvironmentVariablesProvider( +environmentVariables: customEnvironment, +secretsSpecifier: .specific(["API_KEY"]) +) + +## See Also + +### Creating an environment variable provider + +Creates a new provider that reads from the current process environment. + +Creates a new provider that reads from an environment file. + +- init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/context + +- Configuration +- AbsoluteConfigKey +- context + +Instance Property + +# context + +Additional context information for this configuration key. + +var context: [String : ConfigContextValue] + +ConfigKey.swift + +## Discussion + +Context provides extra information that providers can use to refine lookups or return more specific values. Not all providers use context information. + +## See Also + +### Inspecting an absolute configuration key + +[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/components) + +The hierarchical components that make up this absolute configuration key. + +- context +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/customstringconvertible-implementations + +- Configuration +- CommandLineArgumentsProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/watchint(forkey:issecret:fileid:line:updateshandler:) + +#app-main) + +- Configuration +- ConfigReader +- watchInt(forKey:isSecret:fileID:line:updatesHandler:) + +Instance Method + +# watchInt(forKey:isSecret:fileID:line:updatesHandler:) + +Watches for updates to a config value for the given config key. + +forKey key: ConfigKey, +isSecret: Bool = false, +fileID: String = #fileID, +line: UInt = #line, + +ConfigReader+methods.swift + +## Parameters + +`key` + +The config key to watch. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +`updatesHandler` + +A closure that handles an async sequence of updates to the value. The sequence produces `nil` if the value is missing or can’t be converted. + +## Return Value + +The result produced by the handler. + +## Mentioned in + +Example use cases + +## Discussion + +Use this method to observe changes to optional configuration values over time. The handler receives an async sequence that produces the current value whenever it changes, or `nil` if the value is missing or can’t be converted. + +try await config.watchInt(forKey: ["server", "port"]) { updates in +for await port in updates { +if let port = port { +print("Server port is: \(port)") +} else { +print("No server port configured") +} +} +} + +## See Also + +### Watching integer values + +Watches for updates to a config value for the given config key with default fallback. + +- watchInt(forKey:isSecret:fileID:line:updatesHandler:) +- Parameters +- Return Value +- Mentioned in +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/service-implementations + +- Configuration +- ReloadingFileProvider +- Service Implementations + +API Collection + +# Service Implementations + +## Topics + +### Instance Methods + +`func run() async throws` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/customstringconvertible-implementations + +- Configuration +- ConfigKey +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-6vten + +-6vten#app-main) + +- Configuration +- ConfigKey +- init(\_:context:) + +Initializer + +# init(\_:context:) + +Creates a new configuration key. + +init( +_ string: String, +context: [String : ConfigContextValue] = [:] +) + +ConfigKey.swift + +## Parameters + +`string` + +The string representation of the key path, for example `"http.timeout"`. + +`context` + +Additional context information for the key. + +## See Also + +### Creating a configuration key + +[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-9ifez) + +- init(\_:context:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/environmentvalue(forname:) + +#app-main) + +- Configuration +- EnvironmentVariablesProvider +- environmentValue(forName:) + +Instance Method + +# environmentValue(forName:) + +Returns the raw string value for a specific environment variable name. + +EnvironmentVariablesProvider.swift + +## Parameters + +`name` + +The exact name of the environment variable to retrieve. + +## Return Value + +The string value of the environment variable, or nil if not found. + +## Discussion + +This method provides direct access to environment variable values by name, without any key transformation or type conversion. It’s useful when you need to access environment variables that don’t follow the standard configuration key naming conventions. + +let provider = EnvironmentVariablesProvider() +let path = try provider.environmentValue(forName: "PATH") +let home = try provider.environmentValue(forName: "HOME") + +- environmentValue(forName:) +- Parameters +- Return Value +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/init(environmentfilepath:allowmissing:secretsspecifier:bytesdecoder:arrayseparator:) + +#app-main) + +- Configuration +- EnvironmentVariablesProvider +- init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:) + +Initializer + +# init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:) + +Creates a new provider that reads from an environment file. + +init( +environmentFilePath: FilePath, +allowMissing: Bool = false, + +bytesDecoder: some ConfigBytesFromStringDecoder = .base64, +arraySeparator: Character = "," +) async throws + +EnvironmentVariablesProvider.swift + +## Parameters + +`environmentFilePath` + +The file system path to the environment file to load. + +`allowMissing` + +A flag controlling how the provider handles a missing file. + +- When `false` (the default), if the file is missing or malformed, throws an error. + +- When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. + +`secretsSpecifier` + +Specifies which environment variables should be treated as secrets. + +`bytesDecoder` + +The decoder used for converting string values to byte arrays. + +`arraySeparator` + +The character used to separate elements in array values. + +## Discussion + +This initializer loads environment variables from an `.env` file at the specified path. The file should contain key-value pairs in the format `KEY=value`, one per line. Comments (lines starting with `#`) and empty lines are ignored. + +// Load from a .env file +let provider = try await EnvironmentVariablesProvider( +environmentFilePath: ".env", +allowMissing: true, +secretsSpecifier: .specific(["API_KEY"]) +) + +## See Also + +### Creating an environment variable provider + +Creates a new provider that reads from the current process environment. + +Creates a new provider from a custom dictionary of environment variables. + +- init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/customstringconvertible-implementations + +- Configuration +- EnvironmentVariablesProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/init(upstream:keymapper:) + +#app-main) + +- Configuration +- KeyMappingProvider +- init(upstream:keyMapper:) + +Initializer + +# init(upstream:keyMapper:) + +Creates a new provider. + +init( +upstream: Upstream, + +) + +KeyMappingProvider.swift + +## Parameters + +`upstream` + +The upstream provider to delegate to after mapping. + +`mapKey` + +A closure to remap configuration keys. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configprovider/prefixkeys(with:) + +#app-main) + +- Configuration +- ConfigProvider +- prefixKeys(with:) + +Instance Method + +# prefixKeys(with:) + +Creates a new prefixed configuration provider. + +ConfigProvider+Operators.swift + +## Return Value + +A provider which prefixes keys with the given prefix. + +## Discussion + +- Parameter: prefix: The configuration key to prepend to all configuration keys. + +## See Also + +### Conveniences + +Implements `watchValue` by getting the current value and emitting it immediately. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Creates a new configuration provider where each key is rewritten by the given closure. + +- prefixKeys(with:) +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/customdebugstringconvertible-implementations + +- Configuration +- EnvironmentVariablesProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/configprovider-implementations + +- Configuration +- FileProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Properties + +`var providerName: String` + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/init(snapshottype:parsingoptions:config:logger:metrics:) + +#app-main) + +- Configuration +- ReloadingFileProvider +- init(snapshotType:parsingOptions:config:logger:metrics:) + +Initializer + +# init(snapshotType:parsingOptions:config:logger:metrics:) + +Creates a reloading file provider using configuration from a reader. + +convenience init( +snapshotType: Snapshot.Type = Snapshot.self, +parsingOptions: Snapshot.ParsingOptions = .default, +config: ConfigReader, +logger: Logger = Logger(label: "ReloadingFileProvider"), +metrics: any MetricsFactory = MetricsSystem.factory +) async throws + +ReloadingFileProvider.swift + +## Parameters + +`snapshotType` + +The type of snapshot to create from the file contents. + +`parsingOptions` + +Options used by the snapshot to parse the file data. + +`config` + +A configuration reader that contains the required configuration keys. + +`logger` + +The logger instance to use for this provider. + +`metrics` + +The metrics factory to use for monitoring provider performance. + +## Configuration keys + +- `filePath` (string, required): The path to the configuration file to monitor. + +- `allowMissing` (bool, optional, default: false): A flag controlling how the provider handles a missing file. When `false` (the default), if the file is missing or malformed, throws an error. When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. + +- `pollIntervalSeconds` (int, optional, default: 15): How often to check for file changes in seconds. + +## See Also + +### Creating a reloading file provider + +`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool, pollInterval: Duration, logger: Logger, metrics: any MetricsFactory) async throws` + +Creates a reloading file provider that monitors the specified file path. + +- init(snapshotType:parsingOptions:config:logger:metrics:) +- Parameters +- Configuration keys +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/equatable-implementations + +- Configuration +- ConfigKey +- Equatable Implementations + +API Collection + +# Equatable Implementations + +## Topics + +### Operators + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/expressiblebyextendedgraphemeclusterliteral-implementations + +- Configuration +- ConfigKey +- ExpressibleByExtendedGraphemeClusterLiteral Implementations + +API Collection + +# ExpressibleByExtendedGraphemeClusterLiteral Implementations + +## Topics + +### Initializers + +`init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/comparable-implementations + +- Configuration +- ConfigKey +- Comparable Implementations + +API Collection + +# Comparable Implementations + +## Topics + +### Operators + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-9ifez + +-9ifez#app-main) + +- Configuration +- ConfigKey +- init(\_:context:) + +Initializer + +# init(\_:context:) + +Creates a new configuration key. + +init( +_ components: [String], +context: [String : ConfigContextValue] = [:] +) + +ConfigKey.swift + +## Parameters + +`components` + +The hierarchical components that make up the key path. + +`context` + +Additional context information for the key. + +## See Also + +### Creating a configuration key + +[`init(String, context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-6vten) + +- init(\_:context:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/customdebugstringconvertible-implementations + +- Configuration +- KeyMappingProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/init(arguments:secretsspecifier:bytesdecoder:) + +#app-main) + +- Configuration +- CommandLineArgumentsProvider +- init(arguments:secretsSpecifier:bytesDecoder:) + +Initializer + +# init(arguments:secretsSpecifier:bytesDecoder:) + +Creates a new CLI provider with the provided arguments. + +init( +arguments: [String] = CommandLine.arguments, + +bytesDecoder: some ConfigBytesFromStringDecoder = .base64 +) + +CommandLineArgumentsProvider.swift + +## Parameters + +`arguments` + +The command-line arguments to parse. + +`secretsSpecifier` + +Specifies which CLI arguments should be treated as secret. + +`bytesDecoder` + +The decoder used for converting string values into bytes. + +## Discussion + +// Uses the current process's arguments. +let provider = CommandLineArgumentsProvider() +// Uses custom arguments. +let provider = CommandLineArgumentsProvider(arguments: ["program", "--test", "--port", "8089"]) + +- init(arguments:secretsSpecifier:bytesDecoder:) +- Parameters +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromhexstringdecoder/configbytesfromstringdecoder-implementations + +- Configuration +- ConfigBytesFromHexStringDecoder +- ConfigBytesFromStringDecoder Implementations + +API Collection + +# ConfigBytesFromStringDecoder Implementations + +## Topics + +### Type Properties + +`static var hex: ConfigBytesFromHexStringDecoder` + +A decoder that interprets string values as hexadecimal-encoded data. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/init(name:initialvalues:) + +#app-main) + +- Configuration +- MutableInMemoryProvider +- init(name:initialValues:) + +Initializer + +# init(name:initialValues:) + +Creates a new mutable in-memory provider with the specified initial values. + +init( +name: String? = nil, +initialValues: [AbsoluteConfigKey : ConfigValue] +) + +MutableInMemoryProvider.swift + +## Parameters + +`name` + +An optional name for the provider, used in debugging and logging. + +`initialValues` + +A dictionary mapping absolute configuration keys to their initial values. + +## Discussion + +This initializer takes a dictionary of absolute configuration keys mapped to their initial values. The provider can be modified after creation using the `setValue(_:forKey:)` methods. + +let key1 = AbsoluteConfigKey(components: ["database", "host"], context: [:]) +let key2 = AbsoluteConfigKey(components: ["database", "port"], context: [:]) + +let provider = MutableInMemoryProvider( +name: "dynamic-config", +initialValues: [\ +key1: "localhost",\ +key2: 5432\ +] +) + +// Later, update values dynamically +provider.setValue("production-db", forKey: key1) + +- init(name:initialValues:) +- Parameters +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/expressiblebyarrayliteral-implementations + +- Configuration +- ConfigKey +- ExpressibleByArrayLiteral Implementations + +API Collection + +# ExpressibleByArrayLiteral Implementations + +## Topics + +### Initializers + +`init(arrayLiteral: String...)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/configprovider-implementations + +- Configuration +- EnvironmentVariablesProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Properties + +`var providerName: String` + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/context + +- Configuration +- ConfigKey +- context + +Instance Property + +# context + +Additional context information for this configuration key. + +var context: [String : ConfigContextValue] + +ConfigKey.swift + +## Discussion + +Context provides extra information that providers can use to refine lookups or return more specific values. Not all providers use context information. + +## See Also + +### Inspecting a configuration key + +[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/components) + +The hierarchical components that make up this configuration key. + +- context +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessreporter/report(_:) + +#app-main) + +- Configuration +- AccessReporter +- report(\_:) + +Instance Method + +# report(\_:) + +Processes a configuration access event. + +func report(_ event: AccessEvent) + +AccessReporter.swift + +**Required** + +## Parameters + +`event` + +The configuration access event to process. + +## Discussion + +This method is called whenever a configuration value is accessed through a `ConfigReader` or a `ConfigSnapshotReader`. Implementations should handle events efficiently as they may be called frequently. + +- report(\_:) +- Parameters +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/customdebugstringconvertible-implementations + +- Configuration +- CommandLineArgumentsProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.doubleArray(\_:) + +Case + +# ConfigContent.doubleArray(\_:) + +An array of double values. + +case doubleArray([Double]) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/expressiblebyextendedgraphemeclusterliteral-implementations + +- Configuration +- ConfigContextValue +- ExpressibleByExtendedGraphemeClusterLiteral Implementations + +API Collection + +# ExpressibleByExtendedGraphemeClusterLiteral Implementations + +## Topics + +### Initializers + +`init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/specific(_:) + +#app-main) + +- Configuration +- SecretsSpecifier +- SecretsSpecifier.specific(\_:) + +Case + +# SecretsSpecifier.specific(\_:) + +The library treats the specified keys as secrets. + +SecretsSpecifier.swift + +## Parameters + +`keys` + +The set of keys that should be treated as secrets. + +## Discussion + +Use this case when you have a known set of keys that contain sensitive information. All other keys will be treated as non-secret. + +## See Also + +### Types of specifiers + +`case all` + +The library treats all configuration values as secrets. + +The library determines the secret status dynamically by evaluating each key-value pair. + +`case none` + +The library treats no configuration values as secrets. + +- SecretsSpecifier.specific(\_:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileconfigsnapshot/init(data:providername:parsingoptions:) + +# An unknown error occurred. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/init(directorypath:allowmissing:secretsspecifier:arrayseparator:) + +#app-main) + +- Configuration +- DirectoryFilesProvider +- init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:) + +Initializer + +# init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:) + +Creates a new provider that reads files from a directory. + +init( +directoryPath: FilePath, +allowMissing: Bool = false, + +arraySeparator: Character = "," +) async throws + +DirectoryFilesProvider.swift + +## Parameters + +`directoryPath` + +The file system path to the directory containing configuration files. + +`allowMissing` + +A flag controlling how the provider handles a missing directory. + +- When `false`, if the directory is missing, throws an error. + +- When `true`, if the directory is missing, treats it as empty. + +`secretsSpecifier` + +Specifies which values should be treated as secrets. + +`arraySeparator` + +The character used to separate elements in array values. + +## Discussion + +This initializer scans the specified directory and loads all regular files as configuration values. Subdirectories are not traversed. Hidden files (starting with a dot) are skipped. + +// Load configuration from a directory +let provider = try await DirectoryFilesProvider( +directoryPath: "/run/secrets" +) + +- init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:) +- Parameters +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/string + +- Configuration +- ConfigType +- ConfigType.string + +Case + +# ConfigType.string + +A string value. + +case string + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case stringArray` + +An array of string values. + +`case bool` + +A Boolean value. + +`case boolArray` + +An array of Boolean values. + +`case int` + +An integer value. + +`case intArray` + +An array of integer values. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/string(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.string(\_:) + +Case + +# ConfigContent.string(\_:) + +A string value. + +case string(String) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/configprovider-implementations + +- Configuration +- KeyMappingProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Properties + +`var providerName: String` + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.boolArray(\_:) + +Case + +# ConfigContent.boolArray(\_:) + +An array of Boolean value. + +case boolArray([Bool]) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/init(metadata:providerresults:conversionerror:result:) + +#app-main) + +- Configuration +- AccessEvent +- init(metadata:providerResults:conversionError:result:) + +Initializer + +# init(metadata:providerResults:conversionError:result:) + +Creates a configuration access event. + +init( +metadata: AccessEvent.Metadata, +providerResults: [AccessEvent.ProviderResult], +conversionError: (any Error)? = nil, + +AccessReporter.swift + +## Parameters + +`metadata` + +Metadata describing the access operation. + +`providerResults` + +The results from each provider queried. + +`conversionError` + +An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. + +`result` + +The final outcome of the access operation. + +## See Also + +### Creating an access event + +`struct Metadata` + +Metadata describing the configuration access operation. + +`struct ProviderResult` + +The result of a configuration lookup from a specific provider. + +- init(metadata:providerResults:conversionError:result:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/setvalue(_:forkey:) + +#app-main) + +- Configuration +- MutableInMemoryProvider +- setValue(\_:forKey:) + +Instance Method + +# setValue(\_:forKey:) + +Updates the stored value for the specified configuration key. + +func setValue( +_ value: ConfigValue?, +forKey key: AbsoluteConfigKey +) + +MutableInMemoryProvider.swift + +## Parameters + +`value` + +The new configuration value, or `nil` to remove the value entirely. + +`key` + +The absolute configuration key to update. + +## Discussion + +This method atomically updates the value and notifies all active watchers of the change. If the new value is the same as the existing value, no notification is sent. + +let provider = MutableInMemoryProvider(initialValues: [:]) +let key = AbsoluteConfigKey(components: ["api", "enabled"], context: [:]) + +// Set a new value +provider.setValue(true, forKey: key) + +// Remove a value +provider.setValue(nil, forKey: key) + +- setValue(\_:forKey:) +- Parameters +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileparsingoptions/default + +- Configuration +- FileParsingOptions +- default + +Type Property + +# default + +The default instance of this options type. + +static var `default`: Self { get } + +FileProviderSnapshot.swift + +**Required** + +## Discussion + +This property provides a default configuration that can be used when no parsing options are specified. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/init(secretsspecifier:bytesdecoder:arrayseparator:) + +#app-main) + +- Configuration +- EnvironmentVariablesProvider +- init(secretsSpecifier:bytesDecoder:arraySeparator:) + +Initializer + +# init(secretsSpecifier:bytesDecoder:arraySeparator:) + +Creates a new provider that reads from the current process environment. + +init( + +bytesDecoder: some ConfigBytesFromStringDecoder = .base64, +arraySeparator: Character = "," +) + +EnvironmentVariablesProvider.swift + +## Parameters + +`secretsSpecifier` + +Specifies which environment variables should be treated as secrets. + +`bytesDecoder` + +The decoder used for converting string values to byte arrays. + +`arraySeparator` + +The character used to separate elements in array values. + +## Discussion + +This initializer creates a provider that sources configuration values from the environment variables of the current process. + +// Basic usage +let provider = EnvironmentVariablesProvider() + +// With secret handling +let provider = EnvironmentVariablesProvider( +secretsSpecifier: .specific(["API_KEY", "DATABASE_PASSWORD"]) +) + +## See Also + +### Creating an environment variable provider + +Creates a new provider from a custom dictionary of environment variables. + +Creates a new provider that reads from an environment file. + +- init(secretsSpecifier:bytesDecoder:arraySeparator:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/expressiblebystringliteral-implementations + +- Configuration +- ConfigKey +- ExpressibleByStringLiteral Implementations + +API Collection + +# ExpressibleByStringLiteral Implementations + +## Topics + +### Initializers + +`init(extendedGraphemeClusterLiteral: Self.StringLiteralType)` + +`init(stringLiteral: String)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/components + +- Configuration +- ConfigKey +- components + +Instance Property + +# components + +The hierarchical components that make up this configuration key. + +var components: [String] + +ConfigKey.swift + +## Discussion + +Each component represents a level in the configuration hierarchy. For example, `["database", "connection", "timeout"]` represents a three-level nested key. + +## See Also + +### Inspecting a configuration key + +[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/context) + +Additional context information for this configuration key. + +- components +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/init(_:) + +#app-main) + +- Configuration +- ConfigUpdatesAsyncSequence +- init(\_:) + +Initializer + +# init(\_:) + +Creates a new concrete async sequence wrapping the provided existential sequence. + +AsyncSequences.swift + +## Parameters + +`upstream` + +The async sequence to wrap. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation/uuid + +- Configuration +- Foundation +- UUID + +Extended Structure + +# UUID + +ConfigurationFoundation + +extension UUID + +## Topics + +## Relationships + +### Conforms To + +- `ExpressibleByConfigString` +- `Swift.Copyable` +- `Swift.CustomStringConvertible` + +- UUID +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/customstringconvertible-implementations + +- Configuration +- MutableInMemoryProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfrombase64stringdecoder/init() + +#app-main) + +- Configuration +- ConfigBytesFromBase64StringDecoder +- init() + +Initializer + +# init() + +Creates a new base64 decoder. + +init() + +ConfigBytesFromStringDecoder.swift + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/configprovider-implementations + +- Configuration +- CommandLineArgumentsProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Properties + +`var providerName: String` + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/customstringconvertible-implementations + +- Configuration +- ConfigValue +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/string(forkey:as:issecret:fileid:line:)-4oust + +-4oust#app-main) + +- Configuration +- ConfigReader +- string(forKey:as:isSecret:fileID:line:) + +Instance Method + +# string(forKey:as:isSecret:fileID:line:) + +Synchronously gets a config value for the given config key, converting from string. + +forKey key: ConfigKey, +as type: Value.Type = Value.self, +isSecret: Bool = false, +fileID: String = #fileID, +line: UInt = #line + +ConfigReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`type` + +The type to convert the string value to. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The value converted to the expected type if found and convertible, otherwise `nil`. + +## Discussion + +Use this method to retrieve configuration values that can be converted from strings, such as custom types conforming to string conversion protocols. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. + +let serverMode = config.string(forKey: ["server", "mode"], as: ServerMode.self) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +- string(forKey:as:isSecret:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.bytes(\_:) + +Case + +# ConfigContent.bytes(\_:) + +An array of bytes. + +case bytes([UInt8]) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/content + +- Configuration +- ConfigValue +- content + +Instance Property + +# content + +The configuration content. + +var content: ConfigContent + +ConfigProvider.swift + +## See Also + +### Inspecting a config value + +`var isSecret: Bool` + +Whether this value contains sensitive information that should not be logged. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/watchsnapshot(fileid:line:updateshandler:) + +#app-main) + +- Configuration +- ConfigReader +- watchSnapshot(fileID:line:updatesHandler:) + +Instance Method + +# watchSnapshot(fileID:line:updatesHandler:) + +Watches the configuration for changes. + +fileID: String = #fileID, +line: UInt = #line, + +ConfigSnapshotReader.swift + +## Parameters + +`fileID` + +The file where this method is called from. + +`line` + +The line where this method is called from. + +`updatesHandler` + +A closure that receives an async sequence of `ConfigSnapshotReader` instances. + +## Return Value + +The value returned by the handler. + +## Discussion + +This method watches the configuration for changes and provides a stream of snapshots to the handler closure. Each snapshot represents the configuration state at a specific point in time. + +try await config.watchSnapshot { snapshots in +for await snapshot in snapshots { +// Process each new configuration snapshot +let cert = snapshot.string(forKey: "cert") +let privateKey = snapshot.string(forKey: "privateKey") +// Ensures that both values are coming from the same underlying snapshot and that a provider +// didn't change its internal state between the two `string(...)` calls. +let newCert = MyCert(cert: cert, privateKey: privateKey) +print("Certificate was updated: \(newCert.redactedDescription)") +} +} + +## See Also + +### Reading from a snapshot + +Returns a snapshot of the current configuration state. + +- watchSnapshot(fileID:line:updatesHandler:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/configprovider-implementations + +- Configuration +- MutableInMemoryProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Properties + +`var providerName: String` + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/expressiblebybooleanliteral-implementations + +- Configuration +- ConfigValue +- ExpressibleByBooleanLiteral Implementations + +API Collection + +# ExpressibleByBooleanLiteral Implementations + +## Topics + +### Initializers + +`init(booleanLiteral: Bool)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/configprovider-implementations + +- Configuration +- DirectoryFilesProvider +- ConfigProvider Implementations + +API Collection + +# ConfigProvider Implementations + +## Topics + +### Instance Properties + +`var providerName: String` + +### Instance Methods + +Creates a new configuration provider where each key is rewritten by the given closure. + +Creates a new prefixed configuration provider. + +Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. + +Implements `watchValue` by getting the current value and emitting it immediately. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/int(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.int(\_:) + +Case + +# ConfigContent.int(\_:) + +An integer value. + +case int(Int) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/none + +- Configuration +- SecretsSpecifier +- SecretsSpecifier.none + +Case + +# SecretsSpecifier.none + +The library treats no configuration values as secrets. + +case none + +SecretsSpecifier.swift + +## Discussion + +Use this case when the provider handles only non-sensitive configuration data that can be safely logged or displayed. + +## See Also + +### Types of specifiers + +`case all` + +The library treats all configuration values as secrets. + +The library treats the specified keys as secrets. + +The library determines the secret status dynamically by evaluating each key-value pair. + +- SecretsSpecifier.none +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.byteChunkArray(\_:) + +Case + +# ConfigContent.byteChunkArray(\_:) + +An array of byte arrays. + +case byteChunkArray([[UInt8]]) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/issecret + +- Configuration +- ConfigValue +- isSecret + +Instance Property + +# isSecret + +Whether this value contains sensitive information that should not be logged. + +var isSecret: Bool + +ConfigProvider.swift + +## See Also + +### Inspecting a config value + +`var content: ConfigContent` + +The configuration content. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromhexstringdecoder/init() + +#app-main) + +- Configuration +- ConfigBytesFromHexStringDecoder +- init() + +Initializer + +# init() + +Creates a new hexadecimal decoder. + +init() + +ConfigBytesFromStringDecoder.swift + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/expressiblebybooleanliteral-implementations + +- Configuration +- ConfigContextValue +- ExpressibleByBooleanLiteral Implementations + +API Collection + +# ExpressibleByBooleanLiteral Implementations + +## Topics + +### Initializers + +`init(booleanLiteral: Bool)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/result + +- Configuration +- AccessEvent +- result + +Instance Property + +# result + +The final outcome of the configuration access operation. + +AccessReporter.swift + +## Discussion + +## See Also + +### Inspecting an access event + +`var conversionError: (any Error)?` + +An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. + +`var metadata: AccessEvent.Metadata` + +Metadata that describes the configuration access operation. + +[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) + +The results from each configuration provider that was queried. + +- result +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/scoped(to:) + +#app-main) + +- Configuration +- ConfigSnapshotReader +- scoped(to:) + +Instance Method + +# scoped(to:) + +Returns a scoped snapshot reader by appending the provided key to the current key prefix. + +ConfigSnapshotReader.swift + +## Parameters + +`configKey` + +The key to append to the current key prefix. + +## Return Value + +A reader for accessing scoped values. + +## Discussion + +Use this method to create a reader that accesses a subset of the configuration. + +let httpConfig = snapshotReader.scoped(to: ["client", "http"]) +let timeout = httpConfig.int(forKey: "timeout") // Reads from "client.http.timeout" in the snapshot + +- scoped(to:) +- Parameters +- Return Value +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter/accessreporter-implementations + +- Configuration +- BroadcastingAccessReporter +- AccessReporter Implementations + +API Collection + +# AccessReporter Implementations + +## Topics + +### Instance Methods + +`func report(AccessEvent)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:fileid:line:)-7bpif + +-7bpif#app-main) + +- Configuration +- ConfigSnapshotReader +- string(forKey:as:isSecret:fileID:line:) + +Instance Method + +# string(forKey:as:isSecret:fileID:line:) + +Synchronously gets a config value for the given config key, converting from string. + +forKey key: ConfigKey, +as type: Value.Type = Value.self, +isSecret: Bool = false, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`type` + +The type to convert the string value to. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The value converted to the expected type if found and convertible, otherwise `nil`. + +## Discussion + +Use this method to retrieve configuration values that can be converted from strings, such as custom types conforming to string conversion protocols. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. + +let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +- string(forKey:as:isSecret:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/customstringconvertible-implementations + +- Configuration +- AbsoluteConfigKey +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/customstringconvertible-implementations + +- Configuration +- KeyMappingProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/bool(_:) + +#app-main) + +- Configuration +- ConfigContextValue +- ConfigContextValue.bool(\_:) + +Case + +# ConfigContextValue.bool(\_:) + +A Boolean value. + +case bool(Bool) + +ConfigContext.swift + +## See Also + +### Configuration context values + +`case string(String)` + +A string value. + +`case int(Int)` + +An integer value. + +`case double(Double)` + +A floating point value. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader-fetch + +- Configuration +- ConfigReader +- Asynchronously fetching values + +API Collection + +# Asynchronously fetching values + +## Topics + +### Asynchronously fetching string values + +Asynchronously fetches a config value for the given config key. + +Asynchronously fetches a config value for the given config key, with a default fallback. + +Asynchronously fetches a config value for the given config key, converting from string. + +Asynchronously fetches a config value for the given config key with default fallback, converting from string. + +### Asynchronously fetching lists of string values + +Asynchronously fetches an array of config values for the given config key, converting from strings. + +Asynchronously fetches an array of config values for the given config key with default fallback, converting from strings. + +### Asynchronously fetching required string values + +Asynchronously fetches a required config value for the given config key, throwing an error if it’s missing. + +Asynchronously fetches a required config value for the given config key, converting from string. + +### Asynchronously fetching required lists of string values + +Asynchronously fetches a required array of config values for the given config key, converting from strings. + +### Asynchronously fetching Boolean values + +### Asynchronously fetching required Boolean values + +### Asynchronously fetching lists of Boolean values + +### Asynchronously fetching required lists of Boolean values + +### Asynchronously fetching integer values + +### Asynchronously fetching required integer values + +### Asynchronously fetching lists of integer values + +### Asynchronously fetching required lists of integer values + +### Asynchronously fetching double values + +### Asynchronously fetching required double values + +### Asynchronously fetching lists of double values + +### Asynchronously fetching required lists of double values + +### Asynchronously fetching bytes + +### Asynchronously fetching required bytes + +### Asynchronously fetching lists of byte chunks + +### Asynchronously fetching required lists of byte chunks + +## See Also + +### Reading from a snapshot + +Returns a snapshot of the current configuration state. + +Watches the configuration for changes. + +- Asynchronously fetching values +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader-watch + +- Configuration +- ConfigReader +- Watching values + +API Collection + +# Watching values + +## Topics + +### Watching string values + +Watches for updates to a config value for the given config key. + +Watches for updates to a config value for the given config key, converting from string. + +Watches for updates to a config value for the given config key with default fallback. + +Watches for updates to a config value for the given config key with default fallback, converting from string. + +### Watching required string values + +Watches for updates to a required config value for the given config key. + +Watches for updates to a required config value for the given config key, converting from string. + +### Watching lists of string values + +Watches for updates to an array of config values for the given config key, converting from strings. + +Watches for updates to an array of config values for the given config key with default fallback, converting from strings. + +### Watching required lists of string values + +Watches for updates to a required array of config values for the given config key, converting from strings. + +### Watching Boolean values + +### Watching required Boolean values + +### Watching lists of Boolean values + +### Watching required lists of Boolean values + +### Watching integer values + +### Watching required integer values + +### Watching lists of integer values + +### Watching required lists of integer values + +### Watching double values + +### Watching required double values + +### Watching lists of double values + +### Watching required lists of double values + +### Watching bytes + +### Watching required bytes + +### Watching lists of byte chunks + +### Watching required lists of byte chunks + +## See Also + +### Reading from a snapshot + +Returns a snapshot of the current configuration state. + +Watches the configuration for changes. + +- Watching values +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/parsingoptions/init(bytesdecoder:secretsspecifier:) + +#app-main) + +- Configuration +- YAMLSnapshot +- YAMLSnapshot.ParsingOptions +- init(bytesDecoder:secretsSpecifier:) + +Initializer + +# init(bytesDecoder:secretsSpecifier:) + +Creates custom input configuration for YAML snapshots. + +init( +bytesDecoder: some ConfigBytesFromStringDecoder = .base64, + +) + +YAMLSnapshot.swift + +## Parameters + +`bytesDecoder` + +The decoder to use for converting string values to byte arrays. + +`secretsSpecifier` + +The specifier for identifying secret values. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:default:fileid:line:)-2mphx + +-2mphx#app-main) + +- Configuration +- ConfigSnapshotReader +- string(forKey:as:isSecret:default:fileID:line:) + +Instance Method + +# string(forKey:as:isSecret:default:fileID:line:) + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +forKey key: ConfigKey, +as type: Value.Type = Value.self, +isSecret: Bool = false, +default defaultValue: Value, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`type` + +The type to convert the string value to. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`defaultValue` + +The fallback value returned when the config value is missing or invalid. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The config value if found and convertible, otherwise the default value. + +## Discussion + +Use this method when you need a guaranteed non-nil result for string-convertible types. If the configuration value is missing or can’t be converted to the expected type, the default value is returned instead. + +let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self, default: .production) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key, converting from string. + +- string(forKey:as:isSecret:default:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/conversionerror + +- Configuration +- AccessEvent +- conversionError + +Instance Property + +# conversionError + +An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. + +var conversionError: (any Error)? + +AccessReporter.swift + +## See Also + +### Inspecting an access event + +The final outcome of the configuration access operation. + +`var metadata: AccessEvent.Metadata` + +Metadata that describes the configuration access operation. + +[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) + +The results from each configuration provider that was queried. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromstringdecoder/decode(_:) + +#app-main) + +- Configuration +- ConfigBytesFromStringDecoder +- decode(\_:) + +Instance Method + +# decode(\_:) + +Decodes a string value into an array of bytes. + +ConfigBytesFromStringDecoder.swift + +**Required** + +## Parameters + +`value` + +The string representation to decode. + +## Return Value + +An array of bytes if decoding succeeds, or `nil` if it fails. + +## Discussion + +This method attempts to parse the provided string according to the decoder’s specific format and returns the corresponding byte array. If the string cannot be decoded (due to invalid format or encoding), the method returns `nil`. + +- decode(\_:) +- Parameters +- Return Value +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader-get + +- Configuration +- ConfigReader +- Synchronously reading values + +API Collection + +# Synchronously reading values + +## Topics + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key, converting from string. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +### Synchronously reading lists of string values + +Synchronously gets an array of config values for the given config key, converting from strings. + +Synchronously gets an array of config values for the given config key with default fallback, converting from strings. + +### Synchronously reading required string values + +Synchronously gets a required config value for the given config key, throwing an error if it’s missing. + +Synchronously gets a required config value for the given config key, converting from string. + +### Synchronously reading required lists of string values + +Synchronously gets a required array of config values for the given config key, converting from strings. + +### Synchronously reading Boolean values + +### Synchronously reading required Boolean values + +### Synchronously reading lists of Boolean values + +### Synchronously reading required lists of Boolean values + +### Synchronously reading integer values + +### Synchronously reading required integer values + +### Synchronously reading lists of integer values + +### Synchronously reading required lists of integer values + +### Synchronously reading double values + +### Synchronously reading required double values + +### Synchronously reading lists of double values + +### Synchronously reading required lists of double values + +### Synchronously reading bytes + +### Synchronously reading required bytes + +### Synchronously reading collections of byte chunks + +### Synchronously reading required collections of byte chunks + +## See Also + +### Reading from a snapshot + +Returns a snapshot of the current configuration state. + +Watches the configuration for changes. + +- Synchronously reading values +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.intArray(\_:) + +Case + +# ConfigContent.intArray(\_:) + +An array of integer values. + +case intArray([Int]) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation/url + +- Configuration +- Foundation +- URL + +Extended Structure + +# URL + +ConfigurationFoundation + +extension URL + +## Topics + +## Relationships + +### Conforms To + +- `ExpressibleByConfigString` +- `Swift.Copyable` +- `Swift.CustomStringConvertible` + +- URL +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/appending(_:) + +#app-main) + +- Configuration +- AbsoluteConfigKey +- appending(\_:) + +Instance Method + +# appending(\_:) + +Returns a new absolute configuration key by appending the given relative key. + +ConfigKey.swift + +## Parameters + +`relative` + +The relative configuration key to append to this key. + +## Return Value + +A new absolute configuration key with the relative key appended. + +- appending(\_:) +- Parameters +- Return Value + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/init(_:issecret:) + +#app-main) + +- Configuration +- ConfigValue +- init(\_:isSecret:) + +Initializer + +# init(\_:isSecret:) + +Creates a new configuration value. + +init( +_ content: ConfigContent, +isSecret: Bool +) + +ConfigProvider.swift + +## Parameters + +`content` + +The configuration content. + +`isSecret` + +Whether the value contains sensitive information. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:issecret:default:fileid:line:) + +#app-main) + +- Configuration +- ConfigSnapshotReader +- string(forKey:isSecret:default:fileID:line:) + +Instance Method + +# string(forKey:isSecret:default:fileID:line:) + +Synchronously gets a config value for the given config key, with a default fallback. + +func string( +forKey key: ConfigKey, +isSecret: Bool = false, +default defaultValue: String, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`defaultValue` + +The fallback value returned when the config value is missing or invalid. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The config value if found and convertible, otherwise the default value. + +## Discussion + +Use this method when you need a guaranteed non-nil result. If the configuration value is missing or can’t be converted to the expected type, the default value is returned instead. + +let maxRetries = snapshot.int(forKey: ["network", "maxRetries"], default: 3) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, converting from string. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +- string(forKey:isSecret:default:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/systempackage/filepath + +- Configuration +- SystemPackage +- FilePath + +Extended Structure + +# FilePath + +ConfigurationSystemPackage + +extension FilePath + +## Topics + +## Relationships + +### Conforms To + +- `ExpressibleByConfigString` +- `Swift.Copyable` +- `Swift.CustomStringConvertible` + +- FilePath +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/expressiblebyconfigstring/init(configstring:) + +#app-main) + +- Configuration +- ExpressibleByConfigString +- init(configString:) + +Initializer + +# init(configString:) + +Creates an instance from a configuration string value. + +init?(configString: String) + +ExpressibleByConfigString.swift + +**Required** + +## Parameters + +`configString` + +The string value from the configuration provider. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/metadata-swift.struct + +- Configuration +- AccessEvent +- AccessEvent.Metadata + +Structure + +# AccessEvent.Metadata + +Metadata describing the configuration access operation. + +struct Metadata + +AccessReporter.swift + +## Overview + +Contains information about the type of access, the key accessed, value type, source location, and timestamp. + +## Topics + +### Creating access event metadata + +`init(accessKind: AccessEvent.Metadata.AccessKind, key: AbsoluteConfigKey, valueType: ConfigType, sourceLocation: AccessEvent.Metadata.SourceLocation, accessTimestamp: Date)` + +Creates access event metadata. + +`enum AccessKind` + +The type of configuration access operation. + +### Inspecting access event metadata + +`var accessKind: AccessEvent.Metadata.AccessKind` + +The type of configuration access operation for this event. + +`var accessTimestamp: Date` + +The timestamp when the configuration access occurred. + +`var key: AbsoluteConfigKey` + +The configuration key accessed. + +`var sourceLocation: AccessEvent.Metadata.SourceLocation` + +The source code location where the access occurred. + +`var valueType: ConfigType` + +The expected type of the configuration value. + +### Structures + +`struct SourceLocation` + +The source code location where a configuration access occurred. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating an access event + +Creates a configuration access event. + +`struct ProviderResult` + +The result of a configuration lookup from a specific provider. + +- AccessEvent.Metadata +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter/init(upstreams:) + +#app-main) + +- Configuration +- BroadcastingAccessReporter +- init(upstreams:) + +Initializer + +# init(upstreams:) + +Creates a new broadcasting access reporter. + +init(upstreams: [any AccessReporter]) + +AccessReporter.swift + +## Parameters + +`upstreams` + +The reporters that will receive forwarded events. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/expressiblebyextendedgraphemeclusterliteral-implementations + +- Configuration +- ConfigValue +- ExpressibleByExtendedGraphemeClusterLiteral Implementations + +API Collection + +# ExpressibleByExtendedGraphemeClusterLiteral Implementations + +## Topics + +### Initializers + +`init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/customstringconvertible-implementations + +- Configuration +- ConfigContextValue +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(provider:accessreporter:) + +#app-main) + +- Configuration +- ConfigReader +- init(provider:accessReporter:) + +Initializer + +# init(provider:accessReporter:) + +Creates a config reader with a single provider. + +init( +provider: some ConfigProvider, +accessReporter: (any AccessReporter)? = nil +) + +ConfigReader.swift + +## Parameters + +`provider` + +The configuration provider. + +`accessReporter` + +The reporter for configuration access events. + +## See Also + +### Creating config readers + +[`init(providers: [any ConfigProvider], accessReporter: (any AccessReporter)?)`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(providers:accessreporter:)) + +Creates a config reader with multiple providers. + +- init(provider:accessReporter:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/prepending(_:) + +# An unknown error occurred. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/int + +- Configuration +- ConfigType +- ConfigType.int + +Case + +# ConfigType.int + +An integer value. + +case int + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string` + +A string value. + +`case stringArray` + +An array of string values. + +`case bool` + +A Boolean value. + +`case boolArray` + +An array of Boolean values. + +`case intArray` + +An array of integer values. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/equatable-implementations + +- Configuration +- ConfigValue +- Equatable Implementations + +API Collection + +# Equatable Implementations + +## Topics + +### Operators + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/string(_:) + +#app-main) + +- Configuration +- ConfigContextValue +- ConfigContextValue.string(\_:) + +Case + +# ConfigContextValue.string(\_:) + +A string value. + +case string(String) + +ConfigContext.swift + +## See Also + +### Configuration context values + +`case bool(Bool)` + +A Boolean value. + +`case int(Int)` + +An integer value. + +`case double(Double)` + +A floating point value. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/stringarray + +- Configuration +- ConfigType +- ConfigType.stringArray + +Case + +# ConfigType.stringArray + +An array of string values. + +case stringArray + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string` + +A string value. + +`case bool` + +A Boolean value. + +`case boolArray` + +An array of Boolean values. + +`case int` + +An integer value. + +`case intArray` + +An array of integer values. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/stringarray(forkey:issecret:fileid:line:) + +#app-main) + +- Configuration +- ConfigSnapshotReader +- stringArray(forKey:isSecret:fileID:line:) + +Instance Method + +# stringArray(forKey:isSecret:fileID:line:) + +Synchronously gets a config value for the given config key. + +func stringArray( +forKey key: ConfigKey, +isSecret: Bool = false, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The value converted to the expected type if found and convertible, otherwise `nil`. + +## Discussion + +Use this method to retrieve optional configuration values from a snapshot. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. + +let port = snapshot.int(forKey: ["server", "port"]) + +## See Also + +### Synchronously reading lists of string values + +Synchronously gets an array of config values for the given config key, converting from strings. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets an array of config values for the given config key with default fallback, converting from strings. + +- stringArray(forKey:isSecret:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/components + +- Configuration +- AbsoluteConfigKey +- components + +Instance Property + +# components + +The hierarchical components that make up this absolute configuration key. + +var components: [String] + +ConfigKey.swift + +## Discussion + +Each component represents a level in the configuration hierarchy, forming a complete path from the root of the configuration structure. + +## See Also + +### Inspecting an absolute configuration key + +[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/context) + +Additional context information for this configuration key. + +- components +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/bool + +- Configuration +- ConfigType +- ConfigType.bool + +Case + +# ConfigType.bool + +A Boolean value. + +case bool + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string` + +A string value. + +`case stringArray` + +An array of string values. + +`case boolArray` + +An array of Boolean values. + +`case int` + +An integer value. + +`case intArray` + +An array of integer values. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/dynamic(_:) + +#app-main) + +- Configuration +- SecretsSpecifier +- SecretsSpecifier.dynamic(\_:) + +Case + +# SecretsSpecifier.dynamic(\_:) + +The library determines the secret status dynamically by evaluating each key-value pair. + +SecretsSpecifier.swift + +## Parameters + +`closure` + +A closure that takes a key and value and returns whether the value should be treated as secret. + +## Discussion + +Use this case when you need complex logic to determine whether a value is secret based on the key name, value content, or other criteria. + +## See Also + +### Types of specifiers + +`case all` + +The library treats all configuration values as secrets. + +The library treats the specified keys as secrets. + +`case none` + +The library treats no configuration values as secrets. + +- SecretsSpecifier.dynamic(\_:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/all + +- Configuration +- SecretsSpecifier +- SecretsSpecifier.all + +Case + +# SecretsSpecifier.all + +The library treats all configuration values as secrets. + +case all + +SecretsSpecifier.swift + +## Discussion + +Use this case when the provider exclusively handles sensitive information and all values should be protected from disclosure. + +## See Also + +### Types of specifiers + +The library treats the specified keys as secrets. + +The library determines the secret status dynamically by evaluating each key-value pair. + +`case none` + +The library treats no configuration values as secrets. + +- SecretsSpecifier.all +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest/testconfiguration + +- ConfigurationTesting +- ProviderCompatTest +- ProviderCompatTest.TestConfiguration + +Structure + +# ProviderCompatTest.TestConfiguration + +Configuration options for customizing test behavior. + +struct TestConfiguration + +ProviderCompatTest.swift + +## Topics + +### Initializers + +[`init(overrides: [String : ConfigContent])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest/testconfiguration/init(overrides:)) + +Creates a new test configuration. + +### Instance Properties + +[`var overrides: [String : ConfigContent]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest/testconfiguration/overrides) + +Value overrides for testing custom scenarios. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +- ProviderCompatTest.TestConfiguration +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation/date + +- Configuration +- Foundation +- Date + +Extended Structure + +# Date + +ConfigurationFoundation + +extension Date + +## Topics + +## Relationships + +### Conforms To + +- `ExpressibleByConfigString` +- `Swift.Copyable` +- `Swift.CustomStringConvertible` + +- Date +- Topics +- Relationships + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/boolarray + +- Configuration +- ConfigType +- ConfigType.boolArray + +Case + +# ConfigType.boolArray + +An array of Boolean values. + +case boolArray + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string` + +A string value. + +`case stringArray` + +An array of string values. + +`case bool` + +A Boolean value. + +`case int` + +An integer value. + +`case intArray` + +An array of integer values. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/equatable-implementations + +- Configuration +- ConfigContextValue +- Equatable Implementations + +API Collection + +# Equatable Implementations + +## Topics + +### Operators + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:) + +#app-main) + +- Configuration +- AbsoluteConfigKey +- init(\_:) + +Initializer + +# init(\_:) + +Creates a new absolute configuration key from a relative key. + +init(_ relative: ConfigKey) + +ConfigKey.swift + +## Parameters + +`relative` + +The relative configuration key to convert. + +## See Also + +### Creating an absolute configuration key + +[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:context:)) + +Creates a new absolute configuration key. + +- init(\_:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/asyncsequence-implementations + +- Configuration +- ConfigUpdatesAsyncSequence +- AsyncSequence Implementations + +API Collection + +# AsyncSequence Implementations + +## Topics + +### Instance Methods + +[`func chunked(by: AsyncTimerSequence) -> AsyncChunksOfCountOrSignalSequence>`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/chunked(by:)-trjw) + +`func chunked(by: AsyncTimerSequence, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence>` + +[`func chunks(ofCount: Int, or: AsyncTimerSequence) -> AsyncChunksOfCountOrSignalSequence>`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/chunks(ofcount:or:)-8u4c4) + +`func chunks(ofCount: Int, or: AsyncTimerSequence, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence>` + +`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/makeasynciterator()) + +`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/share(bufferingpolicy:)) + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshot/value(forkey:type:) + +#app-main) + +- Configuration +- ConfigSnapshot +- value(forKey:type:) + +Instance Method + +# value(forKey:type:) + +Returns a value for the specified key from this immutable snapshot. + +func value( +forKey key: AbsoluteConfigKey, +type: ConfigType + +ConfigProvider.swift + +**Required** + +## Parameters + +`key` + +The configuration key to look up. + +`type` + +The expected configuration value type. + +## Return Value + +The lookup result containing the value and encoded key, or nil if not found. + +## Discussion + +Unlike `value(forKey:type:)`, this method always returns the same value for identical parameters because the snapshot represents a fixed point in time. Values can be accessed synchronously and efficiently. + +## See Also + +### Required methods + +`var providerName: String` + +The human-readable name of the configuration provider that created this snapshot. + +- value(forKey:type:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/intarray + +- Configuration +- ConfigType +- ConfigType.intArray + +Case + +# ConfigType.intArray + +An array of integer values. + +case intArray + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string` + +A string value. + +`case stringArray` + +An array of string values. + +`case bool` + +A Boolean value. + +`case boolArray` + +An array of Boolean values. + +`case int` + +An integer value. + +`case double` + +A double value. + +`case doubleArray` + +An array of double values. + +`case bytes` + +An array of bytes. + +`case byteChunkArray` + +An array of byte chunks. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/double(_:) + +#app-main) + +- Configuration +- ConfigContextValue +- ConfigContextValue.double(\_:) + +Case + +# ConfigContextValue.double(\_:) + +A floating point value. + +case double(Double) + +ConfigContext.swift + +## See Also + +### Configuration context values + +`case string(String)` + +A string value. + +`case bool(Bool)` + +A Boolean value. + +`case int(Int)` + +An integer value. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/customstringconvertible-implementations + +- Configuration +- DirectoryFilesProvider +- CustomStringConvertible Implementations + +API Collection + +# CustomStringConvertible Implementations + +## Topics + +### Instance Properties + +`var description: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/int(_:) + +#app-main) + +- Configuration +- ConfigContextValue +- ConfigContextValue.int(\_:) + +Case + +# ConfigContextValue.int(\_:) + +An integer value. + +case int(Int) + +ConfigContext.swift + +## See Also + +### Configuration context values + +`case string(String)` + +A string value. + +`case bool(Bool)` + +A Boolean value. + +`case double(Double)` + +A floating point value. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/comparable-implementations + +- Configuration +- AbsoluteConfigKey +- Comparable Implementations + +API Collection + +# Comparable Implementations + +## Topics + +### Operators + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(providers:accessreporter:) + +#app-main) + +- Configuration +- ConfigReader +- init(providers:accessReporter:) + +Initializer + +# init(providers:accessReporter:) + +Creates a config reader with multiple providers. + +init( +providers: [any ConfigProvider], +accessReporter: (any AccessReporter)? = nil +) + +ConfigReader.swift + +## Parameters + +`providers` + +The configuration providers, queried in order until a value is found. + +`accessReporter` + +The reporter for configuration access events. + +## See Also + +### Creating config readers + +`init(provider: some ConfigProvider, accessReporter: (any AccessReporter)?)` + +Creates a config reader with a single provider. + +- init(providers:accessReporter:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:default:fileid:line:)-fzpe + +-fzpe#app-main) + +- Configuration +- ConfigSnapshotReader +- string(forKey:as:isSecret:default:fileID:line:) + +Instance Method + +# string(forKey:as:isSecret:default:fileID:line:) + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +forKey key: ConfigKey, +as type: Value.Type = Value.self, +isSecret: Bool = false, +default defaultValue: Value, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`type` + +The type to convert the string value to. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`defaultValue` + +The fallback value returned when the config value is missing or invalid. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The config value if found and convertible, otherwise the default value. + +## Discussion + +Use this method when you need a guaranteed non-nil result for string-convertible types. If the configuration value is missing or can’t be converted to the expected type, the default value is returned instead. + +let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self, default: .production) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key, converting from string. + +- string(forKey:as:isSecret:default:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:context:) + +#app-main) + +- Configuration +- AbsoluteConfigKey +- init(\_:context:) + +Initializer + +# init(\_:context:) + +Creates a new absolute configuration key. + +init( +_ components: [String], +context: [String : ConfigContextValue] = [:] +) + +ConfigKey.swift + +## Parameters + +`components` + +The hierarchical components that make up the complete key path. + +`context` + +Additional context information for the key. + +## See Also + +### Creating an absolute configuration key + +`init(ConfigKey)` + +Creates a new absolute configuration key from a relative key. + +- init(\_:context:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/customdebugstringconvertible-implementations + +- Configuration +- MutableInMemoryProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresult + +- Configuration +- AccessEvent +- AccessEvent.ProviderResult + +Structure + +# AccessEvent.ProviderResult + +The result of a configuration lookup from a specific provider. + +struct ProviderResult + +AccessReporter.swift + +## Overview + +Contains the provider’s name and the outcome of querying that provider, which can be either a successful lookup result or an error. + +## Topics + +### Creating provider results + +Creates a provider result. + +### Inspecting provider results + +The outcome of the configuration lookup operation. + +`var providerName: String` + +The name of the configuration provider that processed the lookup. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating an access event + +Creates a configuration access event. + +`struct Metadata` + +Metadata describing the configuration access operation. + +- AccessEvent.ProviderResult +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:issecret:fileid:line:) + +#app-main) + +- Configuration +- ConfigSnapshotReader +- string(forKey:isSecret:fileID:line:) + +Instance Method + +# string(forKey:isSecret:fileID:line:) + +Synchronously gets a config value for the given config key. + +func string( +forKey key: ConfigKey, +isSecret: Bool = false, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The value converted to the expected type if found and convertible, otherwise `nil`. + +## Discussion + +Use this method to retrieve optional configuration values from a snapshot. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. + +let port = snapshot.int(forKey: ["server", "port"]) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key, converting from string. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +- string(forKey:isSecret:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/double(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.double(\_:) + +Case + +# ConfigContent.double(\_:) + +A double value. + +case double(Double) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) + +An array of string values. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:) + +#app-main) + +- Configuration +- ConfigContent +- ConfigContent.stringArray(\_:) + +Case + +# ConfigContent.stringArray(\_:) + +An array of string values. + +case stringArray([String]) + +ConfigProvider.swift + +## See Also + +### Types of configuration content + +`case string(String)` + +A string value. + +`case bool(Bool)` + +A Boolean value. + +[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) + +An array of Boolean value. + +`case int(Int)` + +An integer value. + +[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) + +An array of integer values. + +`case double(Double)` + +A double value. + +[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) + +An array of double values. + +[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) + +An array of bytes. + +[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) + +An array of byte arrays. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:fileid:line:)-8hlcf + +-8hlcf#app-main) + +- Configuration +- ConfigSnapshotReader +- string(forKey:as:isSecret:fileID:line:) + +Instance Method + +# string(forKey:as:isSecret:fileID:line:) + +Synchronously gets a config value for the given config key, converting from string. + +forKey key: ConfigKey, +as type: Value.Type = Value.self, +isSecret: Bool = false, +fileID: String = #fileID, +line: UInt = #line + +ConfigSnapshotReader+methods.swift + +## Parameters + +`key` + +The config key to look up. + +`type` + +The type to convert the string value to. + +`isSecret` + +Whether the value should be treated as secret for logging and debugging purposes. + +`fileID` + +The file ID where this call originates. Used for access reporting. + +`line` + +The line number where this call originates. Used for access reporting. + +## Return Value + +The value converted to the expected type if found and convertible, otherwise `nil`. + +## Discussion + +Use this method to retrieve configuration values that can be converted from strings, such as custom types conforming to string conversion protocols. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. + +let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self) + +## See Also + +### Synchronously reading string values + +Synchronously gets a config value for the given config key. + +Synchronously gets a config value for the given config key, with a default fallback. + +Synchronously gets a config value for the given config key with default fallback, converting from string. + +- string(forKey:as:isSecret:fileID:line:) +- Parameters +- Return Value +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/customdebugstringconvertible-implementations + +- Configuration +- DirectoryFilesProvider +- CustomDebugStringConvertible Implementations + +API Collection + +# CustomDebugStringConvertible Implementations + +## Topics + +### Instance Properties + +`var debugDescription: String` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshot/providername + +- Configuration +- ConfigSnapshot +- providerName + +Instance Property + +# providerName + +The human-readable name of the configuration provider that created this snapshot. + +var providerName: String { get } + +ConfigProvider.swift + +**Required** + +## Discussion + +Used by `AccessReporter` and when diagnostic logging the config reader types. + +## See Also + +### Required methods + +Returns a value for the specified key from this immutable snapshot. + +- providerName +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/issecret(key:value:) + +#app-main) + +- Configuration +- SecretsSpecifier +- isSecret(key:value:) + +Instance Method + +# isSecret(key:value:) + +Determines whether a configuration value should be treated as secret. + +func isSecret( +key: KeyType, +value: ValueType + +SecretsSpecifier.swift + +Available when `KeyType` conforms to `Hashable`, `KeyType` conforms to `Sendable`, and `ValueType` conforms to `Sendable`. + +## Parameters + +`key` + +The provider-specific configuration key. + +`value` + +The configuration value to evaluate. + +## Return Value + +`true` if the value should be treated as secret; otherwise, `false`. + +## Discussion + +This method evaluates the secrets specifier against the provided key-value pair to determine if the value contains sensitive information that should be protected from disclosure. + +let isSecret = specifier.isSecret(key: "API_KEY", value: "secret123") +// Returns: true + +- isSecret(key:value:) +- Parameters +- Return Value +- Discussion + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/metadata-swift.property + +- Configuration +- AccessEvent +- metadata + +Instance Property + +# metadata + +Metadata that describes the configuration access operation. + +var metadata: AccessEvent.Metadata + +AccessReporter.swift + +## See Also + +### Inspecting an access event + +The final outcome of the configuration access operation. + +`var conversionError: (any Error)?` + +An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. + +[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) + +The results from each configuration provider that was queried. + +| +| + +--- + diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md new file mode 100644 index 00000000..5348f54e --- /dev/null +++ b/Docs/skit-analyze-plan.md @@ -0,0 +1,954 @@ +# Plan: SyntaxKit Analyzer CLI Tool + +## Context + +We need to create a CLI tool that uses the Claude API to automatically update the SyntaxKit library with missing features. The tool will: + +1. Take an **input folder** containing: + - `dsl.swift` - Swift DSL code (desired API) + - `expected.swift` - Expected Swift code output +2. Take a **SyntaxKit library path** (existing sources) +3. **Auto-generate AST** from `expected.swift` using existing SyntaxParser +4. Analyze what's missing using Claude API +5. **Generate updated SyntaxKit library** with the missing features implemented +6. Write updated library to an **output folder** + +This addresses the problem of implementing missing SyntaxKit features. Instead of manual implementation after identifying gaps, this tool automates the entire process: analysis → code generation → updated library output. Developers provide examples of what they want to generate, and the tool implements the necessary SyntaxKit features. + +## Implementation Approach + +### 1. Create New Executable Target: `skit-analyze` + +**Location**: `Sources/skit-analyze/` + +**Dependencies**: +- `SyntaxParser` (existing) - for parsing Swift code to AST +- `ConfigKeyKit` (existing in project) - for configuration key management +- `swift-configuration` - for CLI argument and environment variable handling +- Foundation (URLSession) - for HTTP requests to Claude API + +### 2. Core Components + +#### A. Configuration Structure (`AnalyzerConfiguration.swift`) + +Configuration using ConfigKeyKit pattern: + +```swift +import Configuration +import ConfigKeyKit + +struct AnalyzerConfiguration: ConfigurationParseable { + typealias ConfigReader = Configuration.ConfigReader + typealias BaseConfig = Never + + // Configuration keys + static let syntaxKitPathKey = ConfigKey( + "syntaxkit.path", + default: "Sources/SyntaxKit" + ) + + static let apiKeyKey = OptionalConfigKey( + cli: "api-key", + env: "ANTHROPIC_API_KEY" + ) + + static let modelKey = ConfigKey( + "model", + default: "claude-opus-4-6" + ) + + static let verboseKey = ConfigKey("verbose", default: false) + + // Properties + let inputFolderPath: String // Folder containing dsl.swift, expected.swift + let syntaxKitPath: String // Path to existing SyntaxKit sources + let outputFolderPath: String // Where to write updated library + let apiKey: String + let model: String + let verbose: Bool + + init(configuration: ConfigReader, base: Never?) async throws { + // Read positional arguments from command line + let args = CommandLine.arguments.dropFirst() // Skip executable name + let positionalArgs = args.filter { !$0.hasPrefix("--") } + + guard positionalArgs.count >= 3 else { + throw AnalyzerError.missingRequiredArguments( + "Usage: skit-analyze [options]" + ) + } + + self.inputFolderPath = positionalArgs[0] + self.syntaxKitPath = positionalArgs[1] + self.outputFolderPath = positionalArgs[2] + + // Read from configuration (CLI flags and env vars) + self.model = configuration.string(forKey: Self.modelKey) + self.verbose = configuration.bool(forKey: Self.verboseKey) + + // API key is required - check CLI flag, then env var + guard let key = configuration.string(forKey: Self.apiKeyKey) else { + throw AnalyzerError.missingAPIKey( + "API key required. Provide via --api-key flag or ANTHROPIC_API_KEY environment variable" + ) + } + self.apiKey = key + + // Validate paths exist + try validatePaths() + } + + private func validatePaths() throws { + let fm = FileManager.default + + guard fm.fileExists(atPath: inputFolderPath) else { + throw AnalyzerError.invalidPath("Input folder does not exist: \(inputFolderPath)") + } + + guard fm.fileExists(atPath: syntaxKitPath) else { + throw AnalyzerError.invalidPath("SyntaxKit path does not exist: \(syntaxKitPath)") + } + } +} + +enum AnalyzerError: Error { + case missingRequiredArguments(String) + case missingAPIKey(String) + case invalidPath(String) + case missingInputFile(String) + case astGenerationError(String) + case apiError(String) + case codeGenerationError(String) +} +``` + +#### B. Command Implementation (`AnalyzeCommand.swift`) + +Command using ConfigKeyKit Command protocol: + +```swift +import ConfigKeyKit +import Configuration + +struct AnalyzeCommand: Command { + typealias Config = AnalyzerConfiguration + + static let commandName = "analyze" + static let abstract = "Generate updated SyntaxKit library with missing features" + static let helpText = """ + OVERVIEW: Automatically implement missing SyntaxKit features using Claude API + + USAGE: skit-analyze [options] + + ARGUMENTS: + Folder containing: + - dsl.swift: Swift DSL code (desired API) + - expected.swift: Expected Swift code output + Note: AST is auto-generated from expected.swift + + Path to existing SyntaxKit library sources + + Where to write the updated SyntaxKit library + + OPTIONS: + --api-key Claude API key (or set ANTHROPIC_API_KEY) + --model Claude model to use (default: claude-opus-4-6) + --verbose Enable verbose output + -h, --help Show help information + + EXAMPLE: + mkdir examples/subscript-feature + echo 'Subscript("Item") { ... }' > examples/subscript-feature/dsl.swift + echo 'subscript(index: Int) -> Item { ... }' > examples/subscript-feature/expected.swift + + export ANTHROPIC_API_KEY="sk-ant-..." + skit-analyze examples/subscript-feature Sources/SyntaxKit output/SyntaxKit + """ + + let config: Config + + init(config: Config) { + self.config = config + } + + static func createInstance() async throws -> Self { + // Create providers + let envProvider = EnvironmentVariablesProvider() + let cliProvider = CommandLineArgumentsProvider() + + // Provider hierarchy: CLI args override environment variables + let reader = ConfigReader(providers: [cliProvider, envProvider]) + + // Parse configuration + let configuration = try await Config(configuration: reader) + + return Self(config: configuration) + } + + func execute() async throws { + // Delegate to analyzer + let analyzer = SyntaxKitAnalyzer(config: config) + try await analyzer.run() + } +} +``` + +#### C. Main Entry Point (`main.swift`) + +```swift +@main +enum SkitAnalyze { + static func main() async { + do { + let command = try await AnalyzeCommand.createInstance() + try await command.execute() + } catch { + print("Error: \(error)") + exit(1) + } + } +} +``` + +#### D. Main Analyzer (`SyntaxKitAnalyzer.swift`) + +Core analyzer that orchestrates the entire workflow: + +```swift +struct SyntaxKitAnalyzer { + let config: AnalyzerConfiguration + + func run() async throws { + if config.verbose { + print("Generating updated SyntaxKit library...") + print("Input Folder: \(config.inputFolderPath)") + print("SyntaxKit Path: \(config.syntaxKitPath)") + print("Output Folder: \(config.outputFolderPath)") + } + + // 1. Read input files from folder + let inputReader = InputFolderReader(folderPath: config.inputFolderPath) + let inputs = try inputReader.readInputs() + + if config.verbose { + print("Found: DSL (\(inputs.dslCode.count) chars), " + + "Expected Swift (\(inputs.expectedSwift.count) chars)") + } + + // 2. Generate AST from expected.swift using SyntaxParser + if config.verbose { print("Generating AST from expected.swift...") } + let astGenerator = ASTGenerator() + let swiftAST = try astGenerator.generateAST(from: inputs.expectedSwift) + + // 3. Collect library code + if config.verbose { print("Collecting SyntaxKit library code...") } + let collector = LibraryCollector() + let libraryCode = try collector.collectLibraryCode(from: config.syntaxKitPath) + + if config.verbose { + print("Library: \(libraryCode.split(separator: "\n").count) lines from " + + "\(collector.fileCount) files") + } + + // 4. Call Claude API for analysis AND code generation + if config.verbose { print("Calling Claude API (\(config.model))...") } + let client = ClaudeAPIClient(apiKey: config.apiKey, model: config.model) + let result = try await client.generateUpdatedLibrary( + syntaxKitLibrary: libraryCode, + expectedSwift: inputs.expectedSwift, + swiftAST: swiftAST, + swiftDSL: inputs.dslCode + ) + + if config.verbose { + print("Received \(result.updatedFiles.count) updated files") + } + + // 5. Write updated library to output folder + try writeUpdatedLibrary(result) + + print("✓ Updated SyntaxKit library written to: \(config.outputFolderPath)") + } + + private func writeUpdatedLibrary(_ result: LibraryUpdateResult) throws { + let writer = LibraryWriter(outputPath: config.outputFolderPath) + try writer.writeUpdatedLibrary(result) + + if config.verbose { + print("\nUpdated files:") + for file in result.updatedFiles { + print(" - \(file.path)") + } + if !result.newFiles.isEmpty { + print("\nNew files:") + for file in result.newFiles { + print(" + \(file.path)") + } + } + } + } +} +``` + +#### E. Input Folder Reader (`InputFolderReader.swift`) + +Reads and validates files from the input folder: + +```swift +struct InputFolderReader { + let folderPath: String + + struct Inputs { + let dslCode: String + let expectedSwift: String + } + + func readInputs() throws -> Inputs { + let fm = FileManager.default + + // Required: dsl.swift + let dslPath = "\(folderPath)/dsl.swift" + guard fm.fileExists(atPath: dslPath) else { + throw AnalyzerError.missingInputFile("Missing required file: dsl.swift") + } + let dslCode = try String(contentsOfFile: dslPath) + + // Required: expected.swift + let expectedPath = "\(folderPath)/expected.swift" + guard fm.fileExists(atPath: expectedPath) else { + throw AnalyzerError.missingInputFile("Missing required file: expected.swift") + } + let expectedSwift = try String(contentsOfFile: expectedPath) + + return Inputs( + dslCode: dslCode, + expectedSwift: expectedSwift + ) + } +} +``` + +#### F. Library Code Collector (`LibraryCollector.swift`) + +Responsible for gathering all SyntaxKit source files: + +```swift +struct LibraryCollector { + private(set) var fileCount: Int = 0 // Track number of files collected + + /// Recursively collects all .swift files from SyntaxKit directory + mutating func collectLibraryCode(from path: String) throws -> String + + /// Formats collected code with file markers for clarity + private func formatWithFileMarkers(_ files: [(path: String, content: String)]) -> String +} +``` + +Implementation will: +- Recursively scan the SyntaxKit directory +- Read all `.swift` files +- Concatenate with clear file path markers for each file +- Track file count for verbose output +- Skip test files and build artifacts +- Preserve relative paths for later reference + +#### G. Library Writer (`LibraryWriter.swift`) + +Writes the updated library files to the output folder: + +```swift +struct LibraryWriter { + let outputPath: String + + func writeUpdatedLibrary(_ result: LibraryUpdateResult) throws { + let fm = FileManager.default + + // Create output directory if it doesn't exist + try fm.createDirectory(atPath: outputPath, withIntermediateDirectories: true) + + // Write updated files + for file in result.updatedFiles { + let fullPath = "\(outputPath)/\(file.relativePath)" + let directory = (fullPath as NSString).deletingLastPathComponent + try fm.createDirectory(atPath: directory, withIntermediateDirectories: true) + try file.content.write(toFile: fullPath, atomically: true, encoding: .utf8) + } + + // Write new files + for file in result.newFiles { + let fullPath = "\(outputPath)/\(file.relativePath)" + let directory = (fullPath as NSString).deletingLastPathComponent + try fm.createDirectory(atPath: directory, withIntermediateDirectories: true) + try file.content.write(toFile: fullPath, atomically: true, encoding: .utf8) + } + + // Copy unchanged files (optional - could skip and only write changes) + if result.includeUnchangedFiles { + for file in result.unchangedFiles { + let fullPath = "\(outputPath)/\(file.relativePath)" + let directory = (fullPath as NSString).deletingLastPathComponent + try fm.createDirectory(atPath: directory, withIntermediateDirectories: true) + try fm.copyItem(atPath: file.sourcePath, toPath: fullPath) + } + } + } +} +``` + +#### H. AST Generator (`ASTGenerator.swift`) + +Wraps existing SyntaxParser to produce formatted AST: + +```swift +import SyntaxParser + +struct ASTGenerator { + /// Generates formatted AST from Swift code using SyntaxParser + func generateAST(from swiftCode: String) throws -> String { + // Use existing SyntaxParser to parse Swift code + let treeNodes = SyntaxParser.parse(code: swiftCode) + + // Format TreeNode array as readable hierarchical text or JSON + return formatAST(treeNodes) + } + + /// Formats TreeNode array as readable hierarchical text or JSON + private func formatAST(_ nodes: [TreeNode]) -> String { + // Could output as JSON or formatted text + // JSON is probably better for Claude to parse + let encoder = JSONEncoder() + encoder.outputFormatting = [.prettyPrinted, .sortedKeys] + + guard let data = try? encoder.encode(nodes), + let json = String(data: data, encoding: .utf8) else { + return "[]" + } + + return json + } +} +``` + +**Key Points**: +- Reuses existing `SyntaxParser.parse(code:)` from `Sources/SyntaxParser/` +- Returns JSON representation of the AST (TreeNode array) +- This is the same code path used by the `skit` executable +- No need for external AST generation - it's built-in! + +#### I. Claude API Client (`ClaudeAPIClient.swift`) + +Handles communication with Claude API for code generation: + +```swift +struct ClaudeAPIClient { + let apiKey: String + let model: String + + /// Sends request to generate updated library code + func generateUpdatedLibrary( + syntaxKitLibrary: String, + expectedSwift: String, + swiftAST: String, + swiftDSL: String + ) async throws -> LibraryUpdateResult + + /// Formats the API request payload with code generation instructions + private func createRequestPayload(...) -> [String: Any] + + /// Parses API response containing generated code + private func parseCodeGenerationResponse(_ data: Data) throws -> LibraryUpdateResult +} + +struct LibraryUpdateResult: Codable { + struct UpdatedFile: Codable { + let relativePath: String // e.g., "Declarations/Subscript.swift" + let content: String + let changeDescription: String + } + + struct NewFile: Codable { + let relativePath: String + let content: String + let purpose: String + } + + let updatedFiles: [UpdatedFile] + let newFiles: [NewFile] + let unchangedFiles: [FileReference] + let includeUnchangedFiles: Bool + let summary: String // Claude's explanation of changes +} + +struct FileReference: Codable { + let relativePath: String + let sourcePath: String +} +``` + +API request structure: +- Endpoint: `https://api.anthropic.com/v1/messages` +- Headers: `x-api-key`, `anthropic-version: 2023-06-01`, `content-type: application/json` +- Body: Enhanced prompt asking Claude to generate actual Swift code, not just describe changes + +Modified Prompt Strategy: +- Still uses the Workbench prompt for analysis +- **Additionally** asks Claude to generate the actual implementation code +- Requests output in structured format using XML-style markers +- Each code file marked with: `...code...` + +**Response Parsing**: +The API client will parse Claude's response by: +1. Extract all `` blocks using regex or XML parsing +2. For each file block: + - Extract `path` attribute (relative path like "Declarations/Subscript.swift") + - Extract content between tags (complete Swift code) + - Determine if it's a new file or modification (check against library file list) +3. Build `LibraryUpdateResult` with categorized files +4. Include Claude's analysis summary from the response + +**Code Generation Reliability**: +- Claude Opus 4.6 is excellent at generating complete, valid Swift code +- The prompt emphasizes: "provide COMPLETE file content, not diffs" +- Each file should be self-contained and compilable +- The tool can optionally run `swift build` on output to verify validity + +#### J. Prompt Template (`PromptTemplate.swift`) + +Contains enhanced version of Workbench prompt with code generation instructions: + +```swift +struct PromptTemplate { + static func createAnalysisAndCodeGeneration( + syntaxKitLibrary: String, + expectedSwift: String, + swiftAST: String, + swiftDSL: String + ) -> String { + // Original Workbench prompt for analysis + // PLUS additional instructions for code generation + } +} +``` + +**Prompt Structure**: +1. **Analysis Phase** (from Workbench): Analyze what needs to be added/modified +2. **Code Generation Phase** (added): Generate actual Swift implementation +3. **Output Format**: Structured response with: + - Analysis summary + - List of files to modify with complete new content + - List of new files to create with complete content + - Each file marked with: `...` + +**Example Enhanced Prompt**: +``` +[Original Workbench prompt...] + +After your analysis, generate the actual Swift code needed to implement these changes: + + +For each required change you identified, provide the COMPLETE updated file content. +Mark each file with its path relative to the SyntaxKit root. + +Format: + +// Complete file content here + + +Include: +- Modified existing files (full content, not diffs) +- New files that need to be created +- Updated Package.swift if new targets/dependencies needed + +``` + +### 3. Workflow + +``` +User runs: skit-analyze examples/subscript-feature Sources/SyntaxKit output/SyntaxKit + +1. main.swift: Entry point +2. AnalyzeCommand.createInstance(): + - Create EnvironmentVariablesProvider and CommandLineArgumentsProvider + - Create ConfigReader with provider hierarchy (CLI > ENV) + - Parse AnalyzerConfiguration from ConfigReader + - Validate required arguments (input folder, syntaxkit path, output folder, API key) + - Validate paths exist +3. AnalyzeCommand.execute(): + - Create SyntaxKitAnalyzer instance with config + - Call analyzer.run() +4. SyntaxKitAnalyzer.run(): + a. Read input folder: + - InputFolderReader reads dsl.swift and expected.swift + b. Generate AST: + - ASTGenerator.generateAST(from: expected.swift) using SyntaxParser + - Returns JSON representation of TreeNode array + c. Collect library code: LibraryCollector.collectLibraryCode() → syntaxKitLibrary + d. Create Claude API client with API key and model + e. Call API: client.generateUpdatedLibrary() → LibraryUpdateResult + - Claude analyzes what's missing + - Claude generates complete Swift implementation + - Returns structured result with file contents + f. Write updated library: LibraryWriter.writeUpdatedLibrary() + - Create output directory structure + - Write updated files with new content + - Write new files + - Optionally copy unchanged files + g. Print success message with output path +``` + +### 4. Package.swift Changes + +Add ConfigKeyKit as a local target and integrate swift-configuration: + +```swift +// In dependencies (add swift-configuration): +.package( + url: "https://github.com/apple/swift-configuration", + from: "1.0.0", + traits: ["CommandLineArguments"] // Enable CLI args trait +), + +// Add ConfigKeyKit as a target: +.target( + name: "ConfigKeyKit", + dependencies: [ + .product(name: "Configuration", package: "swift-configuration") + ], + swiftSettings: swiftSettings +), + +// Add new executable target: +.executableTarget( + name: "skit-analyze", + dependencies: [ + "SyntaxParser", + "ConfigKeyKit", + .product(name: "Configuration", package: "swift-configuration") + ], + swiftSettings: swiftSettings +), + +// In products: +.executable( + name: "skit-analyze", + targets: ["skit-analyze"] +), +``` + +**Note**: ConfigKeyKit already exists in the project directory, so we just need to add it as a target in Package.swift. + +### 5. Configuration & Environment + +**How swift-configuration + ConfigKeyKit Works Together**: + +1. **ConfigKeyKit** provides the abstraction layer: + - `ConfigKey` for required values with defaults + - `OptionalConfigKey` for optional values + - Automatic key naming transformations (e.g., `api.key` → `--api-key` or `API_KEY`) + - Source-specific key generation (CLI vs ENV have different naming conventions) + +2. **swift-configuration** provides the runtime: + - `ConfigReader` reads from multiple providers + - `CommandLineArgumentsProvider` parses `--flag value` style arguments + - `EnvironmentVariablesProvider` reads from environment + - Provider hierarchy: CLI arguments override environment variables + +3. **Integration**: + ```swift + // Define key with both sources + let apiKeyKey = OptionalConfigKey( + cli: "api-key", // Becomes --api-key + env: "ANTHROPIC_API_KEY" // Reads from $ANTHROPIC_API_KEY + ) + + // Read with ConfigReader + let apiKey = configuration.string(forKey: apiKeyKey) // Checks CLI first, then ENV + ``` + +**API Key Management**: +- `--api-key` flag takes precedence (via CommandLineArgumentsProvider) +- Falls back to `ANTHROPIC_API_KEY` environment variable (via EnvironmentVariablesProvider) +- Error if neither is provided + +**Positional Arguments**: +- Three required positional arguments (not flags): + 1. Input folder path (containing dsl.swift, expected.swift, optional ast files) + 2. SyntaxKit library path (existing sources to read) + 3. Output folder path (where to write updated library) +- Parsed manually from `CommandLine.arguments` in configuration initializer +- More intuitive than using flags for required paths +- Example: `skit-analyze examples/feature Sources/SyntaxKit output/updated` + +**Default Values**: +- SyntaxKit library path: `Sources/SyntaxKit` (via `ConfigKey` default) +- Model: `claude-opus-4-6` (via `ConfigKey` default) +- Verbose: `false` (via `ConfigKey` default) +- Can all be overridden via CLI flags or environment variables + +**Model Configuration**: +- Model: Default `claude-opus-4-6`, override with `--model` +- Max tokens: 20000 (hardcoded in API client) +- Temperature: 1 (hardcoded as specified in Workbench) + +### 6. Error Handling + +Comprehensive error handling for: +- Missing files (Swift code, DSL code) +- Invalid paths (SyntaxKit library not found) +- API errors (authentication, rate limits, network issues) +- Parsing errors (invalid Swift code) +- JSON encoding/decoding errors + +Use Swift's error handling with descriptive error messages. + +### 7. Output Format + +**Standard Output** (default): +``` +Analyzing SyntaxKit requirements... + +Swift Code: target.swift (245 lines) +DSL Code: dsl.swift (89 lines) +Generated AST: 1,234 nodes +Library Code: 15,678 lines from 142 files + +Calling Claude API (model: claude-opus-4-6)... +Response received (3,456 tokens) + +REQUIRED CHANGES: +================ + +[Claude's analysis output here] +``` + +**File Output** (with `--output changes.md`): +Save just the required changes section to the specified file. + +**Verbose Mode** (with `--verbose`): +Include full API request/response, intermediate parsing steps, file collection details. + +## Critical Files to Create + +1. **Sources/skit-analyze/main.swift** - Main entry point +2. **Sources/skit-analyze/AnalyzeCommand.swift** - Command implementation using ConfigKeyKit +3. **Sources/skit-analyze/AnalyzerConfiguration.swift** - Configuration structure using ConfigKeyKit +4. **Sources/skit-analyze/SyntaxKitAnalyzer.swift** - Core analyzer orchestration +5. **Sources/skit-analyze/InputFolderReader.swift** - Reads dsl.swift, expected.swift, ast files +6. **Sources/skit-analyze/LibraryCollector.swift** - Collects SyntaxKit source files +7. **Sources/skit-analyze/LibraryWriter.swift** - Writes updated library to output folder +8. **Sources/skit-analyze/ASTGenerator.swift** - Wraps SyntaxParser for AST generation +9. **Sources/skit-analyze/ClaudeAPIClient.swift** - Claude API communication for code generation +10. **Sources/skit-analyze/PromptTemplate.swift** - Enhanced Workbench prompt with code generation +11. **Sources/skit-analyze/Models.swift** - Data models (LibraryUpdateResult, UpdatedFile, NewFile, AnalyzerError) +12. **Package.swift** (modify) - Add ConfigKeyKit target, swift-configuration dependency, and executable target + +## Verification Steps + +1. **Build Test**: + ```bash + swift build -c release + ``` + +2. **Create Test Input**: + ```bash + # Create input folder with test case + mkdir -p examples/simple-property + + cat > examples/simple-property/dsl.swift << 'EOF' + Struct("Person") { + Variable("age", type: "Int") + } + EOF + + cat > examples/simple-property/expected.swift << 'EOF' + struct Person { + let age: Int + } + EOF + ``` + +3. **Run Tool**: + ```bash + export ANTHROPIC_API_KEY="sk-ant-..." + .build/release/skit-analyze \ + examples/simple-property \ + Sources/SyntaxKit \ + output/SyntaxKit-updated + ``` + +4. **Verify Output**: + ```bash + # Check that output directory was created + ls -la output/SyntaxKit-updated + + # Verify updated files exist + # Should see modified/new files for the feature + + # Check that generated code is valid Swift + cd output/SyntaxKit-updated && swift build + ``` + +5. **Test Generated Code**: + ```bash + # Create a test that uses the new feature + # Verify it compiles and produces expected output + ``` + +6. **Error Handling Tests**: + ```bash + # Test missing API key + skit-analyze examples/test Sources/SyntaxKit output # Should error + + # Test invalid input folder + skit-analyze nonexistent Sources/SyntaxKit output # Should error + + # Test missing required files + mkdir -p examples/incomplete + echo "test" > examples/incomplete/dsl.swift + # Missing expected.swift - should error + skit-analyze examples/incomplete Sources/SyntaxKit output + ``` + +7. **Integration Test**: Use a real missing feature (e.g., subscript syntax) and verify: + - Tool generates valid Swift code + - Generated code follows SyntaxKit patterns + - Generated code compiles + - Feature actually works as expected + +## Future Enhancements (Not in Scope) + +- **Validation Mode**: Run `swift build` on generated code and retry if compilation fails +- **Interactive Review**: Show diff before writing, allow user to approve/reject changes +- **Batch Processing**: Process multiple feature folders in one run +- **Incremental Updates**: Only update changed files, preserve git history +- **Test Generation**: Also generate unit tests for new features +- **Template Library**: Save/reuse common patterns across feature generations +- **Local Caching**: Cache library code and API responses to reduce API calls +- **Multi-Provider**: Support OpenAI, Google Gemini as alternative to Claude +- **Diff Output**: Optionally output unified diffs instead of complete files + +## Dependencies Summary + +**New Dependencies**: +- `swift-configuration` (1.0.0+) with `CommandLineArguments` trait - Configuration management + +**Existing Dependencies** (reused): +- `ConfigKeyKit` (in project) - Configuration key abstraction +- `SwiftSyntax` (601.0.1+) - via SyntaxParser +- `SyntaxParser` (existing module) - AST generation +- Foundation - HTTP requests, file I/O + +**Advantages of swift-configuration + ConfigKeyKit**: +- Unified handling of CLI args and environment variables +- Type-safe configuration keys with automatic naming transformations +- Composable provider hierarchy (CLI overrides ENV) +- Consistent with project's existing ConfigKeyKit architecture +- More flexible than ArgumentParser for complex configuration scenarios + +## Build & Install + +```bash +# Build +swift build -c release + +# Install to system (optional) +cp .build/release/skit-analyze /usr/local/bin/ + +# Or run from build directory +.build/release/skit-analyze +``` + +## Example Usage + +### Basic Example: Add Subscript Support + +```bash +# 1. Create input folder with feature specification +mkdir -p examples/subscript-feature + +# 2. Define the desired DSL syntax +cat > examples/subscript-feature/dsl.swift << 'EOF' +Struct("Collection") { + Subscript(parameters: [Parameter("index", type: "Int")], returnType: "Element") { + Return(PropertyAccessExp("items", "index")) + } +} +EOF + +# 3. Define expected Swift output +cat > examples/subscript-feature/expected.swift << 'EOF' +struct Collection { + subscript(index: Int) -> Element { + return items[index] + } +} +EOF + +# 4. Run the tool +# Note: AST is automatically generated from expected.swift using SyntaxParser +export ANTHROPIC_API_KEY="sk-ant-..." +skit-analyze \ + examples/subscript-feature \ + Sources/SyntaxKit \ + output/SyntaxKit-with-subscripts +``` + +### Advanced Examples + +```bash +# With custom model +skit-analyze examples/my-feature Sources/SyntaxKit output/updated \ + --model claude-sonnet-4-5 + +# With verbose output to see what's happening +skit-analyze examples/my-feature Sources/SyntaxKit output/updated \ + --verbose + +# Using CLI flag for API key instead of environment +skit-analyze examples/my-feature Sources/SyntaxKit output/updated \ + --api-key sk-ant-... + +# Show help +skit-analyze --help +``` + +### Full Workflow Example + +```bash +# Step 1: Identify a missing feature (e.g., defer statements) +mkdir -p examples/defer-statement + +# Step 2: Write the DSL you wish existed +cat > examples/defer-statement/dsl.swift << 'EOF' +Function("cleanup") { + Defer { + Call("closeFile") + } +} +EOF + +# Step 3: Write what Swift code it should generate +cat > examples/defer-statement/expected.swift << 'EOF' +func cleanup() { + defer { + closeFile() + } +} +EOF + +# Step 4: Generate updated SyntaxKit with defer support +export ANTHROPIC_API_KEY="sk-ant-..." +skit-analyze \ + examples/defer-statement \ + Sources/SyntaxKit \ + output/SyntaxKit-with-defer \ + --verbose + +# Step 5: Verify it works +cd output/SyntaxKit-with-defer +swift build + +# Step 6: Test the new feature +# Create a test file that uses Defer { ... } +# Run it and verify output matches expected +``` diff --git a/Sources/ConfigKeyKit/Command.swift b/Sources/ConfigKeyKit/Command.swift new file mode 100644 index 00000000..693b23c0 --- /dev/null +++ b/Sources/ConfigKeyKit/Command.swift @@ -0,0 +1,61 @@ +// +// Command.swift +// ConfigKeyKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +/// Generic protocol for CLI commands using Swift Configuration +public protocol Command: Sendable { + /// Associated configuration type for this command + associatedtype Config: ConfigurationParseable + + /// Command name for CLI parsing + static var commandName: String { get } + + /// Abstract description of the command + static var abstract: String { get } + + /// Detailed help text for the command + static var helpText: String { get } + + /// Initialize command with configuration + init(config: Config) + + /// Execute the command asynchronously + func execute() async throws + + /// Create a command instance with configuration + static func createInstance() async throws -> Self +} + +public extension Command { + /// Print help information for this command + static func printHelp() { + print(helpText) + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/CommandConfiguration.swift b/Sources/ConfigKeyKit/CommandConfiguration.swift new file mode 100644 index 00000000..03ffdcd0 --- /dev/null +++ b/Sources/ConfigKeyKit/CommandConfiguration.swift @@ -0,0 +1,39 @@ +// +// CommandConfiguration.swift +// ConfigKeyKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +/// Command configuration for identifying and routing commands +public struct CommandConfiguration { + public let commandName: String + public let abstract: String + + public init(commandName: String, abstract: String) { + self.commandName = commandName + self.abstract = abstract + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/CommandLineParser.swift b/Sources/ConfigKeyKit/CommandLineParser.swift new file mode 100644 index 00000000..a7c2f8ad --- /dev/null +++ b/Sources/ConfigKeyKit/CommandLineParser.swift @@ -0,0 +1,74 @@ +// +// CommandLineParser.swift +// ConfigKeyKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +/// Command line argument parser for Swift Configuration integration +public struct CommandLineParser { + private let arguments: [String] + + public init(arguments: [String] = CommandLine.arguments) { + self.arguments = arguments + } + + /// Parse the command name from command line arguments + public func parseCommandName() -> String? { + // Skip the executable name (first argument) + guard arguments.count > 1 else { return nil } + let commandCandidate = arguments[1] + + // If it starts with '--', it's not a command but a global option + if commandCandidate.hasPrefix("--") { + return nil + } + + return commandCandidate + } + + /// Get all arguments after the command name for command-specific parsing + public func commandArguments() -> [String] { + guard arguments.count > 1 else { return [] } + let commandName = arguments[1] + + // If first argument is an option, return all arguments for global parsing + if commandName.hasPrefix("--") { + return Array(arguments.dropFirst()) + } + + // Return arguments after command name + return Array(arguments.dropFirst(2)) + } + + /// Check if help was requested + public func isHelpRequested() -> Bool { + arguments.contains { arg in + arg == "--help" || arg == "-h" || arg == "help" + } + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/CommandRegistry.swift b/Sources/ConfigKeyKit/CommandRegistry.swift new file mode 100644 index 00000000..39f9e8ed --- /dev/null +++ b/Sources/ConfigKeyKit/CommandRegistry.swift @@ -0,0 +1,88 @@ +// +// CommandRegistry.swift +// ConfigKeyKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +/// Actor-based registry for managing available commands +public actor CommandRegistry { + private var registeredCommands: [String: any Command.Type] = [:] + private var commandMetadata: [String: CommandMetadata] = [:] + + /// Metadata about a command + public struct CommandMetadata: Sendable { + public let commandName: String + public let abstract: String + public let helpText: String + } + + /// Shared instance + public static let shared = CommandRegistry() + + // Internal initializer for testability - allows tests to create isolated instances + internal init() {} + + /// Register a command type with the registry + public func register(_ commandType: T.Type) { + registeredCommands[T.commandName] = commandType + commandMetadata[T.commandName] = CommandMetadata( + commandName: T.commandName, + abstract: T.abstract, + helpText: T.helpText + ) + } + + /// Get all registered command names + public var availableCommands: [String] { + Array(registeredCommands.keys).sorted() + } + + /// Get command metadata + public func metadata(for name: String) -> CommandMetadata? { + commandMetadata[name] + } + + /// Get command type for the given name + public func commandType(named name: String) -> (any Command.Type)? { + return registeredCommands[name] + } + + /// Create a command instance dynamically with automatic config parsing + public func createCommand(named name: String) async throws -> any Command { + guard let commandType = registeredCommands[name] else { + throw CommandRegistryError.unknownCommand(name) + } + + return try await commandType.createInstance() + } + + /// Check if a command is registered + public func isRegistered(_ name: String) -> Bool { + return registeredCommands[name] != nil + } +} diff --git a/Sources/ConfigKeyKit/CommandRegistryError.swift b/Sources/ConfigKeyKit/CommandRegistryError.swift new file mode 100644 index 00000000..84e7848e --- /dev/null +++ b/Sources/ConfigKeyKit/CommandRegistryError.swift @@ -0,0 +1,42 @@ +// +// CommandRegistryError.swift +// ConfigKeyKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +public import Foundation + +/// Errors that can occur in command registry operations +public enum CommandRegistryError: Error, LocalizedError { + case unknownCommand(String) + + public var errorDescription: String? { + switch self { + case .unknownCommand(let name): + return "Unknown command: \(name)" + } + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigKey+Bool.swift b/Sources/ConfigKeyKit/ConfigKey+Bool.swift new file mode 100644 index 00000000..afb6819e --- /dev/null +++ b/Sources/ConfigKeyKit/ConfigKey+Bool.swift @@ -0,0 +1,72 @@ +// +// ConfigKey+Bool.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +// MARK: - Specialized Initializers for Booleans + +extension ConfigKey where Value == Bool { + /// Non-optional default value accessor for booleans + @available(*, deprecated, message: "Use defaultValue directly instead") + public var boolDefault: Bool { + defaultValue // Already non-optional! + } + + /// Initialize a boolean configuration key with non-optional default + /// - Parameters: + /// - cli: Command-line argument name + /// - env: Environment variable name + /// - defaultVal: Default value (defaults to false) + public init(cli: String, env: String, default defaultVal: Bool = false) { + self.baseKey = nil + self.styles = [:] + var keys: [ConfigKeySource: String] = [:] + keys[.commandLine] = cli + keys[.environment] = env + self.explicitKeys = keys + self.defaultValue = defaultVal + } + + /// Initialize a boolean configuration key from base string + /// - Parameters: + /// - base: Base key string (e.g., "sync.verbose") + /// - envPrefix: Prefix for environment variable (defaults to nil) + /// - defaultVal: Default value (defaults to false) + public init(_ base: String, envPrefix: String? = nil, default defaultVal: Bool = false) { + self.baseKey = base + self.styles = [ + .commandLine: StandardNamingStyle.dotSeparated, + .environment: StandardNamingStyle.screamingSnakeCase(prefix: envPrefix), + ] + self.explicitKeys = [:] + self.defaultValue = defaultVal + } +} + +// Application-specific boolean key helpers should be added in application code \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigKey+Debug.swift b/Sources/ConfigKeyKit/ConfigKey+Debug.swift new file mode 100644 index 00000000..3e101ab8 --- /dev/null +++ b/Sources/ConfigKeyKit/ConfigKey+Debug.swift @@ -0,0 +1,36 @@ +// +// ConfigKey+Debug.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +extension ConfigKey: CustomDebugStringConvertible { + public var debugDescription: String { + let cliKey = key(for: .commandLine) ?? "nil" + let envKey = key(for: .environment) ?? "nil" + return "ConfigKey(cli: \(cliKey), env: \(envKey), default: \(defaultValue))" + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigKey.swift b/Sources/ConfigKeyKit/ConfigKey.swift new file mode 100644 index 00000000..8d43e7c5 --- /dev/null +++ b/Sources/ConfigKeyKit/ConfigKey.swift @@ -0,0 +1,113 @@ +// +// ConfigKey.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +// MARK: - Generic Configuration Key + +/// Configuration key for values with default fallbacks +/// +/// Use `ConfigKey` when a configuration value has a sensible default +/// that should be used when not provided by the user. The `read()` method +/// will always return a non-optional value. +/// +/// Example: +/// ```swift +/// let containerID = ConfigKey( +/// base: "cloudkit.container_id", +/// default: "iCloud.com.example.MyApp" +/// ) +/// // read(containerID) returns String (non-optional) +/// ``` +public struct ConfigKey: ConfigurationKey, Sendable { + internal let baseKey: String? + internal let styles: [ConfigKeySource: any NamingStyle] + internal let explicitKeys: [ConfigKeySource: String] + public let defaultValue: Value // Non-optional! + + /// The base key string used for this configuration key + public var base: String? { baseKey } + + /// Initialize with explicit CLI and ENV keys and required default + public init(cli: String? = nil, env: String? = nil, default defaultVal: Value) { + self.baseKey = nil + self.styles = [:] + var keys: [ConfigKeySource: String] = [:] + if let cli = cli { keys[.commandLine] = cli } + if let env = env { keys[.environment] = env } + self.explicitKeys = keys + self.defaultValue = defaultVal + } + + /// Initialize from a base key string with naming styles and required default + /// - Parameters: + /// - base: Base key string (e.g., "cloudkit.container_id") + /// - styles: Dictionary mapping sources to naming styles + /// - defaultVal: Required default value + public init( + base: String, + styles: [ConfigKeySource: any NamingStyle], + default defaultVal: Value + ) { + self.baseKey = base + self.styles = styles + self.explicitKeys = [:] + self.defaultValue = defaultVal + } + + /// Convenience initializer with standard naming conventions and required default + /// - Parameters: + /// - base: Base key string (e.g., "cloudkit.container_id") + /// - envPrefix: Prefix for environment variable (defaults to nil) + /// - defaultVal: Required default value + public init(_ base: String, envPrefix: String? = nil, default defaultVal: Value) { + self.baseKey = base + self.styles = [ + .commandLine: StandardNamingStyle.dotSeparated, + .environment: StandardNamingStyle.screamingSnakeCase(prefix: envPrefix), + ] + self.explicitKeys = [:] + self.defaultValue = defaultVal + } + + public func key(for source: ConfigKeySource) -> String? { + // Check for explicit key first + if let explicit = explicitKeys[source] { + return explicit + } + + // Generate from base key and style + guard let base = baseKey, let style = styles[source] else { + return nil + } + + return style.transform(base) + } +} + diff --git a/Sources/ConfigKeyKit/ConfigKeySource.swift b/Sources/ConfigKeyKit/ConfigKeySource.swift new file mode 100644 index 00000000..96a928b0 --- /dev/null +++ b/Sources/ConfigKeyKit/ConfigKeySource.swift @@ -0,0 +1,39 @@ +// +// ConfigKeySource.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +// MARK: - Configuration Key Source + +/// Source for configuration keys (CLI arguments or environment variables) +public enum ConfigKeySource: CaseIterable, Sendable { + /// Command-line arguments (e.g., --cloudkit-container-id) + case commandLine + + /// Environment variables (e.g., CLOUDKIT_CONTAINER_ID) + case environment +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigurationKey.swift b/Sources/ConfigKeyKit/ConfigurationKey.swift new file mode 100644 index 00000000..a2f015da --- /dev/null +++ b/Sources/ConfigKeyKit/ConfigurationKey.swift @@ -0,0 +1,40 @@ +// +// ConfigurationKey.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +// MARK: - Configuration Key Protocol + +/// Protocol for configuration keys that support multiple sources +public protocol ConfigurationKey: Sendable { + /// Get the key string for a specific source + /// - Parameter source: The configuration source (CLI or ENV) + /// - Returns: The key string for that source, or nil if the key doesn't support that source + func key(for source: ConfigKeySource) -> String? +} diff --git a/Sources/ConfigKeyKit/ConfigurationParseable.swift b/Sources/ConfigKeyKit/ConfigurationParseable.swift new file mode 100644 index 00000000..0ed4d0a0 --- /dev/null +++ b/Sources/ConfigKeyKit/ConfigurationParseable.swift @@ -0,0 +1,54 @@ +// +// ConfigurationParseable.swift +// ConfigKeyKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +/// Protocol for configuration types that can parse themselves from command line arguments and environment variables +public protocol ConfigurationParseable: Sendable { + /// Associated type for the configuration reader + associatedtype ConfigReader: Sendable + + /// Associated type for the parent configuration + /// Use `Never` for root configurations that have no parent + associatedtype BaseConfig: Sendable + + /// Initialize the configuration by parsing from available sources (CLI args, environment variables, defaults) + /// - Parameters: + /// - configuration: The configuration reader to parse values from + /// - base: Optional parent configuration (nil for root configs) + init(configuration: ConfigReader, base: BaseConfig?) async throws +} + +/// Extension for root configurations (where BaseConfig == Never) +public extension ConfigurationParseable where BaseConfig == Never { + /// Convenience initializer for root configs that don't need a parent + init(configuration: ConfigReader) async throws { + try await self.init(configuration: configuration, base: nil) + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/NamingStyle.swift b/Sources/ConfigKeyKit/NamingStyle.swift new file mode 100644 index 00000000..f9982f46 --- /dev/null +++ b/Sources/ConfigKeyKit/NamingStyle.swift @@ -0,0 +1,38 @@ +// +// NamingStyle.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +// MARK: - Naming Style + +/// Protocol for transforming base key strings into different naming conventions +public protocol NamingStyle: Sendable { + /// Transform a base key string according to this naming style + /// - Parameter base: Base key string (e.g., "cloudkit.container_id") + /// - Returns: Transformed key string + func transform(_ base: String) -> String +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift b/Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift new file mode 100644 index 00000000..e9e0dabe --- /dev/null +++ b/Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift @@ -0,0 +1,36 @@ +// +// OptionalConfigKey+Debug.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +extension OptionalConfigKey: CustomDebugStringConvertible { + public var debugDescription: String { + let cliKey = key(for: .commandLine) ?? "nil" + let envKey = key(for: .environment) ?? "nil" + return "OptionalConfigKey(cli: \(cliKey), env: \(envKey))" + } +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/OptionalConfigKey.swift b/Sources/ConfigKeyKit/OptionalConfigKey.swift new file mode 100644 index 00000000..24cfada5 --- /dev/null +++ b/Sources/ConfigKeyKit/OptionalConfigKey.swift @@ -0,0 +1,103 @@ +// +// OptionalConfigKey.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +// MARK: - Optional Configuration Key + +/// Configuration key for optional values without defaults +/// +/// Use `OptionalConfigKey` when a configuration value has no sensible default +/// and should be `nil` when not provided by the user. The `read()` method +/// will return an optional value. +/// +/// Example: +/// ```swift +/// let apiKey = OptionalConfigKey(base: "api.key") +/// // read(apiKey) returns String? +/// ``` +public struct OptionalConfigKey: ConfigurationKey, Sendable { + internal let baseKey: String? + internal let styles: [ConfigKeySource: any NamingStyle] + internal let explicitKeys: [ConfigKeySource: String] + + /// The base key string used for this configuration key + public var base: String? { baseKey } + + /// Initialize with explicit CLI and ENV keys (no default) + public init(cli: String? = nil, env: String? = nil) { + self.baseKey = nil + self.styles = [:] + var keys: [ConfigKeySource: String] = [:] + if let cli = cli { keys[.commandLine] = cli } + if let env = env { keys[.environment] = env } + self.explicitKeys = keys + } + + /// Initialize from a base key string with naming styles (no default) + /// - Parameters: + /// - base: Base key string (e.g., "cloudkit.key_id") + /// - styles: Dictionary mapping sources to naming styles + public init( + base: String, + styles: [ConfigKeySource: any NamingStyle] + ) { + self.baseKey = base + self.styles = styles + self.explicitKeys = [:] + } + + /// Convenience initializer with standard naming conventions (no default) + /// - Parameters: + /// - base: Base key string (e.g., "cloudkit.key_id") + /// - envPrefix: Prefix for environment variable (defaults to nil) + public init(_ base: String, envPrefix: String? = nil) { + self.baseKey = base + self.styles = [ + .commandLine: StandardNamingStyle.dotSeparated, + .environment: StandardNamingStyle.screamingSnakeCase(prefix: envPrefix), + ] + self.explicitKeys = [:] + } + + public func key(for source: ConfigKeySource) -> String? { + // Check for explicit key first + if let explicit = explicitKeys[source] { + return explicit + } + + // Generate from base key and style + guard let base = baseKey, let style = styles[source] else { + return nil + } + + return style.transform(base) + } +} + diff --git a/Sources/ConfigKeyKit/StandardNamingStyle.swift b/Sources/ConfigKeyKit/StandardNamingStyle.swift new file mode 100644 index 00000000..82cb32b5 --- /dev/null +++ b/Sources/ConfigKeyKit/StandardNamingStyle.swift @@ -0,0 +1,53 @@ +// +// StandardNamingStyle.swift +// MistDemo +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +import Foundation + +/// Common naming styles for configuration keys +public enum StandardNamingStyle: NamingStyle, Sendable { + /// Dot-separated lowercase (e.g., "cloudkit.container_id") + case dotSeparated + + /// Screaming snake case with prefix (e.g., "APP_CLOUDKIT_CONTAINER_ID") + case screamingSnakeCase(prefix: String?) + + public func transform(_ base: String) -> String { + switch self { + case .dotSeparated: + return base + + case .screamingSnakeCase(let prefix): + let snakeCase = base.uppercased().replacingOccurrences(of: ".", with: "_") + if let prefix = prefix { + return "\(prefix)_\(snakeCase)" + } + return snakeCase + } + } +} \ No newline at end of file From a8a56759afe5a94882f30b57d4db20ad97451862 Mon Sep 17 00:00:00 2001 From: Leo Dion Date: Sun, 8 Feb 2026 22:12:25 -0500 Subject: [PATCH 2/9] Add test/validation mode section to skit-analyze plan Adds comprehensive test mode specifications including: - Test case structure and organization - Test configuration formats (manifest.json, test-config.json) - Four validation strategies (structural, content, build, functional) - Implementation components overview - Usage examples and CLI flags - Benefits of automated testing for prompt validation This enables validation of Claude's code generation against known-good outputs, preventing regressions and ensuring quality. Co-Authored-By: Claude Sonnet 4.5 --- Docs/skit-analyze-plan.md | 118 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md index 5348f54e..338571bb 100644 --- a/Docs/skit-analyze-plan.md +++ b/Docs/skit-analyze-plan.md @@ -815,6 +815,124 @@ Include full API request/response, intermediate parsing steps, file collection d - Generated code compiles - Feature actually works as expected +## 8. Test/Validation Mode + +To ensure the prompt generates correct code changes reliably, we need a test mode that validates Claude's responses against known-good outputs. + +### Overview + +Test mode (`--test` flag) runs the tool against a suite of test cases with predefined inputs and expected outputs, then validates that Claude's generated code matches expectations. + +### Test Case Structure + +``` +test-cases/ +├── subscript-basic/ +│ ├── input/ +│ │ ├── dsl.swift # Input DSL code +│ │ └── expected.swift # Expected Swift output +│ ├── expected-changes/ +│ │ ├── manifest.json # List of expected file changes +│ │ └── Declarations/ +│ │ └── Subscript.swift # Expected new/updated file content +│ └── test-config.json # Test metadata (optional) +├── defer-statement/ +│ └── ... +└── generic-function/ + └── ... +``` + +### Test Configuration Format + +**manifest.json** - Describes expected changes: +```json +{ + "description": "Add subscript support to SyntaxKit", + "expectedNewFiles": [ + "Declarations/Subscript.swift", + "Declarations/SubscriptParameter.swift" + ], + "expectedUpdatedFiles": [ + "Core/CodeBlock.swift" + ], + "minimumNewFiles": 1, + "minimumUpdatedFiles": 0, + "validationStrategy": "structural", + "buildRequired": true +} +``` + +**test-config.json** - Test metadata (optional): +```json +{ + "name": "Subscript Basic Support", + "description": "Tests basic subscript declaration generation", + "tags": ["declaration", "subscript", "basic"], + "priority": "high", + "model": "claude-opus-4-6", + "timeout": 120 +} +``` + +### Validation Strategies + +1. **Structural Validation** (`structural`): + - Verifies expected files were created/modified + - Checks file paths match expectations + - Does not validate exact content + +2. **Content Validation** (`content`): + - Compares generated file content against expected content + - Allows for minor whitespace/formatting differences + - Validates key code structures are present + +3. **Build Validation** (`build`): + - Runs `swift build` on generated library + - Verifies no compilation errors + - Does not compare against expected content + +4. **Functional Validation** (`functional`): + - Runs test suite against generated library + - Verifies generated code produces correct output + - Requires test files in test case + +### Implementation Components + +See the full implementation plan in the main plan file for detailed component specifications including: +- Updated AnalyzerConfiguration with test mode flags +- TestRunner for orchestrating test execution +- TestCaseDiscoverer for finding and loading test cases +- TestValidator for validating results against expectations +- TestModels for test data structures + +### Usage + +```bash +# Run all test cases +skit-analyze --test + +# Run with verbose output +skit-analyze --test --verbose + +# Stop on first failure +skit-analyze --test --test-stop-on-fail + +# Run only tests matching "subscript" +skit-analyze --test --test-filter=subscript + +# Run tests from custom path +skit-analyze --test --test-cases=custom-tests/ +``` + +### Benefits + +1. **Prompt Validation**: Ensures the Claude prompt generates correct code +2. **Regression Prevention**: Catches when prompt changes break existing features +3. **Quality Assurance**: Validates generated code quality before deployment +4. **Documentation**: Test cases serve as examples of expected behavior +5. **Confidence**: Developers can iterate on prompts with confidence +6. **Debugging**: Failed tests pinpoint exactly what's wrong with generated code + ## Future Enhancements (Not in Scope) - **Validation Mode**: Run `swift build` on generated code and retry if compilation fails From c701be0e9337981c9bda03f7e16d69121c83b584 Mon Sep 17 00:00:00 2001 From: Leo Dion Date: Mon, 9 Feb 2026 16:22:56 -0500 Subject: [PATCH 3/9] Update skit-analyze plan to use Swift OpenAPI Generator Replace manual ClaudeAPIClient implementation with Swift OpenAPI Generator approach: - Add swift-openapi-generator, runtime, and urlsession dependencies - Use unofficial OpenAPI spec from laszukdawid/anthropic-openapi-spec - Generate type-safe client code at build time - Include setup instructions for OpenAPI spec and config files - Add AuthenticationMiddleware for API key injection Benefits: type safety, maintainability, automatic updates when official spec is released. Co-Authored-By: Claude Sonnet 4.5 --- Docs/skit-analyze-plan.md | 245 +++++++++++++++++++++++++++++++++----- 1 file changed, 218 insertions(+), 27 deletions(-) diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md index 338571bb..90cacd3f 100644 --- a/Docs/skit-analyze-plan.md +++ b/Docs/skit-analyze-plan.md @@ -25,7 +25,9 @@ This addresses the problem of implementing missing SyntaxKit features. Instead o - `SyntaxParser` (existing) - for parsing Swift code to AST - `ConfigKeyKit` (existing in project) - for configuration key management - `swift-configuration` - for CLI argument and environment variable handling -- Foundation (URLSession) - for HTTP requests to Claude API +- `swift-openapi-generator` - for generating type-safe Claude API client from OpenAPI spec +- `swift-openapi-runtime` - runtime support for generated OpenAPI client +- `swift-openapi-urlsession` - URLSession transport for OpenAPI client ### 2. Core Components @@ -437,12 +439,30 @@ struct ASTGenerator { #### I. Claude API Client (`ClaudeAPIClient.swift`) -Handles communication with Claude API for code generation: +Wraps the OpenAPI-generated client for code generation: ```swift +import OpenAPIRuntime +import OpenAPIURLSession + struct ClaudeAPIClient { let apiKey: String let model: String + private let client: Client // Generated from OpenAPI spec + + init(apiKey: String, model: String) { + self.apiKey = apiKey + self.model = model + + // Create OpenAPI client with URLSession transport + self.client = Client( + serverURL: try! Servers.server1(), // https://api.anthropic.com + transport: URLSessionTransport(), + middlewares: [ + AuthenticationMiddleware(apiKey: apiKey) + ] + ) + } /// Sends request to generate updated library code func generateUpdatedLibrary( @@ -450,13 +470,112 @@ struct ClaudeAPIClient { expectedSwift: String, swiftAST: String, swiftDSL: String - ) async throws -> LibraryUpdateResult + ) async throws -> LibraryUpdateResult { + // Create prompt using template + let prompt = PromptTemplate.createAnalysisAndCodeGeneration( + syntaxKitLibrary: syntaxKitLibrary, + expectedSwift: expectedSwift, + swiftAST: swiftAST, + swiftDSL: swiftDSL + ) - /// Formats the API request payload with code generation instructions - private func createRequestPayload(...) -> [String: Any] + // Call Claude API using generated client + let response = try await client.postV1Messages( + body: .json( + Components.Schemas.MessageRequest( + model: model, + max_tokens: 20000, + temperature: 1.0, + messages: [ + Components.Schemas.Message( + role: .user, + content: prompt + ) + ] + ) + ) + ) + + // Extract response content + let messageResponse = try response.ok.body.json + let responseText = messageResponse.content + .compactMap { content -> String? in + if case .text(let text) = content { + return text.text + } + return nil + } + .joined() + + // Parse code generation response + return try parseCodeGenerationResponse(responseText) + } /// Parses API response containing generated code - private func parseCodeGenerationResponse(_ data: Data) throws -> LibraryUpdateResult + private func parseCodeGenerationResponse(_ text: String) throws -> LibraryUpdateResult { + // Extract blocks using regex + let filePattern = #"(.+?)"# + let regex = try NSRegularExpression(pattern: filePattern, options: [.dotMatchesLineSeparators]) + let nsText = text as NSString + let matches = regex.matches(in: text, range: NSRange(location: 0, length: nsText.length)) + + var updatedFiles: [LibraryUpdateResult.UpdatedFile] = [] + var newFiles: [LibraryUpdateResult.NewFile] = [] + + for match in matches { + let pathRange = match.range(at: 1) + let contentRange = match.range(at: 2) + + let relativePath = nsText.substring(with: pathRange) + let content = nsText.substring(with: contentRange) + .trimmingCharacters(in: .whitespacesAndNewlines) + + // Determine if new or updated file based on library scan + // For now, treat all as new files (can enhance later) + newFiles.append( + LibraryUpdateResult.NewFile( + relativePath: relativePath, + content: content, + purpose: "Generated implementation" + ) + ) + } + + // Extract summary (text before first tag) + let summaryPattern = #"^(.+?)(?= HTTPResponse + ) async throws -> HTTPResponse { + var modifiedRequest = request + modifiedRequest.headerFields.append( + .init(name: "x-api-key", value: apiKey) + ) + modifiedRequest.headerFields.append( + .init(name: "anthropic-version", value: "2023-06-01") + ) + return try await next(modifiedRequest, baseURL) + } } struct LibraryUpdateResult: Codable { @@ -485,20 +604,31 @@ struct FileReference: Codable { } ``` -API request structure: -- Endpoint: `https://api.anthropic.com/v1/messages` -- Headers: `x-api-key`, `anthropic-version: 2023-06-01`, `content-type: application/json` -- Body: Enhanced prompt asking Claude to generate actual Swift code, not just describe changes +**OpenAPI Specification Source**: +- Uses unofficial OpenAPI spec from [laszukdawid/anthropic-openapi-spec](https://github.com/laszukdawid/anthropic-openapi-spec) +- Specifically the `hosted_spec.json` file (derived from Anthropic's TypeScript SDK) +- Download to `Sources/skit-analyze/openapi.json` or `openapi.yaml` +- Swift OpenAPI Generator will create type-safe client code at build time + +**Setup Steps**: +1. Download OpenAPI spec: `curl -o Sources/skit-analyze/openapi.json https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json` +2. Create `Sources/skit-analyze/openapi-generator-config.yaml`: + ```yaml + generate: + - types + - client + ``` +3. Swift OpenAPI Generator plugin will generate client code automatically during build -Modified Prompt Strategy: -- Still uses the Workbench prompt for analysis +**Modified Prompt Strategy**: +- Uses the Workbench prompt for analysis - **Additionally** asks Claude to generate the actual implementation code - Requests output in structured format using XML-style markers - Each code file marked with: `...code...` **Response Parsing**: -The API client will parse Claude's response by: -1. Extract all `` blocks using regex or XML parsing +The API client parses Claude's response by: +1. Extract all `` blocks using regex 2. For each file block: - Extract `path` attribute (relative path like "Declarations/Subscript.swift") - Extract content between tags (complete Swift code) @@ -598,15 +728,27 @@ User runs: skit-analyze examples/subscript-feature Sources/SyntaxKit output/Synt ### 4. Package.swift Changes -Add ConfigKeyKit as a local target and integrate swift-configuration: +Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenAPI Generator: ```swift -// In dependencies (add swift-configuration): +// In dependencies: .package( url: "https://github.com/apple/swift-configuration", from: "1.0.0", traits: ["CommandLineArguments"] // Enable CLI args trait ), +.package( + url: "https://github.com/apple/swift-openapi-generator", + from: "1.0.0" +), +.package( + url: "https://github.com/apple/swift-openapi-runtime", + from: "1.0.0" +), +.package( + url: "https://github.com/apple/swift-openapi-urlsession", + from: "1.0.0" +), // Add ConfigKeyKit as a target: .target( @@ -617,13 +759,18 @@ Add ConfigKeyKit as a local target and integrate swift-configuration: swiftSettings: swiftSettings ), -// Add new executable target: +// Add new executable target with OpenAPI Generator plugin: .executableTarget( name: "skit-analyze", dependencies: [ "SyntaxParser", "ConfigKeyKit", - .product(name: "Configuration", package: "swift-configuration") + .product(name: "Configuration", package: "swift-configuration"), + .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"), + .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession") + ], + plugins: [ + .plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator") ], swiftSettings: swiftSettings ), @@ -635,7 +782,27 @@ Add ConfigKeyKit as a local target and integrate swift-configuration: ), ``` -**Note**: ConfigKeyKit already exists in the project directory, so we just need to add it as a target in Package.swift. +**Setup Requirements**: +1. Download OpenAPI spec to `Sources/skit-analyze/`: + ```bash + curl -o Sources/skit-analyze/openapi.json \ + https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json + ``` + +2. Create `Sources/skit-analyze/openapi-generator-config.yaml`: + ```yaml + generate: + - types + - client + accessModifier: internal + ``` + +3. The OpenAPI Generator plugin will automatically generate type-safe client code during build + +**Notes**: +- ConfigKeyKit already exists in the project directory, so we just need to add it as a target in Package.swift +- OpenAPI Generator runs as a build plugin and generates Swift code from the OpenAPI spec at build time +- Generated code includes type-safe request/response models and client methods ### 5. Configuration & Environment @@ -729,6 +896,7 @@ Include full API request/response, intermediate parsing steps, file collection d ## Critical Files to Create +### Source Files 1. **Sources/skit-analyze/main.swift** - Main entry point 2. **Sources/skit-analyze/AnalyzeCommand.swift** - Command implementation using ConfigKeyKit 3. **Sources/skit-analyze/AnalyzerConfiguration.swift** - Configuration structure using ConfigKeyKit @@ -737,10 +905,20 @@ Include full API request/response, intermediate parsing steps, file collection d 6. **Sources/skit-analyze/LibraryCollector.swift** - Collects SyntaxKit source files 7. **Sources/skit-analyze/LibraryWriter.swift** - Writes updated library to output folder 8. **Sources/skit-analyze/ASTGenerator.swift** - Wraps SyntaxParser for AST generation -9. **Sources/skit-analyze/ClaudeAPIClient.swift** - Claude API communication for code generation +9. **Sources/skit-analyze/ClaudeAPIClient.swift** - Wraps OpenAPI-generated client for code generation 10. **Sources/skit-analyze/PromptTemplate.swift** - Enhanced Workbench prompt with code generation 11. **Sources/skit-analyze/Models.swift** - Data models (LibraryUpdateResult, UpdatedFile, NewFile, AnalyzerError) -12. **Package.swift** (modify) - Add ConfigKeyKit target, swift-configuration dependency, and executable target + +### Configuration Files +12. **Sources/skit-analyze/openapi.json** - Anthropic OpenAPI specification (downloaded) +13. **Sources/skit-analyze/openapi-generator-config.yaml** - OpenAPI Generator configuration +14. **Package.swift** (modify) - Add ConfigKeyKit target, dependencies, and OpenAPI plugin + +### Test Mode Files (Section 8) +15. **Sources/skit-analyze/Testing/TestRunner.swift** - Orchestrates test execution +16. **Sources/skit-analyze/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases +17. **Sources/skit-analyze/Testing/TestValidator.swift** - Validates results against expectations +18. **Sources/skit-analyze/Testing/TestModels.swift** - Test data structures ## Verification Steps @@ -949,6 +1127,9 @@ skit-analyze --test --test-cases=custom-tests/ **New Dependencies**: - `swift-configuration` (1.0.0+) with `CommandLineArguments` trait - Configuration management +- `swift-openapi-generator` (1.0.0+) - Generates type-safe API client from OpenAPI spec +- `swift-openapi-runtime` (1.0.0+) - Runtime support for generated OpenAPI client +- `swift-openapi-urlsession` (1.0.0+) - URLSession transport for OpenAPI client **Existing Dependencies** (reused): - `ConfigKeyKit` (in project) - Configuration key abstraction @@ -956,12 +1137,22 @@ skit-analyze --test --test-cases=custom-tests/ - `SyntaxParser` (existing module) - AST generation - Foundation - HTTP requests, file I/O -**Advantages of swift-configuration + ConfigKeyKit**: -- Unified handling of CLI args and environment variables -- Type-safe configuration keys with automatic naming transformations -- Composable provider hierarchy (CLI overrides ENV) -- Consistent with project's existing ConfigKeyKit architecture -- More flexible than ArgumentParser for complex configuration scenarios +**External Resources**: +- [Unofficial Anthropic OpenAPI Spec](https://github.com/laszukdawid/anthropic-openapi-spec) - `hosted_spec.json` derived from Anthropic's TypeScript SDK + +**Advantages of This Approach**: +- **swift-configuration + ConfigKeyKit**: + - Unified handling of CLI args and environment variables + - Type-safe configuration keys with automatic naming transformations + - Composable provider hierarchy (CLI overrides ENV) + - Consistent with project's existing ConfigKeyKit architecture + +- **Swift OpenAPI Generator**: + - Type-safe API client generated at build time from OpenAPI spec + - Automatic request/response serialization + - Built-in error handling and validation + - No manual JSON parsing or HTTP request construction + - Easy to update when Anthropic publishes official OpenAPI spec (just replace the spec file) ## Build & Install From 31a64e574ceac12d35e0daa971d818a0bb5ee944 Mon Sep 17 00:00:00 2001 From: Leo Dion Date: Mon, 9 Feb 2026 16:56:11 -0500 Subject: [PATCH 4/9] Rename targets to AiSTKit, ClaudeKit, and skit-aist Update plan with clever naming scheme: - ClaudeKit: OpenAPI-generated Claude API client (was ClaudeAPIClient) - AiSTKit: SDK/bridge layer combining AI+AST+Kit (was AnalyzerSDK) - skit-aist: Command-line executable (was skit-aist) AiSTKit cleverly combines: - AI: Claude's artificial intelligence - AST: Abstract Syntax Tree - Kit: Follows SyntaxKit naming convention Can be read as "AI-ST-Kit" or "Assist-Kit" (AI assistance). Co-Authored-By: Claude Sonnet 4.5 --- Docs/skit-analyze-plan.md | 162 ++++++++++++++++++++++++-------------- 1 file changed, 103 insertions(+), 59 deletions(-) diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md index 90cacd3f..95a87154 100644 --- a/Docs/skit-analyze-plan.md +++ b/Docs/skit-analyze-plan.md @@ -1,4 +1,4 @@ -# Plan: SyntaxKit Analyzer CLI Tool +# Plan: AiSTKit - AI-Powered AST Generation for SyntaxKit ## Context @@ -17,18 +17,62 @@ This addresses the problem of implementing missing SyntaxKit features. Instead o ## Implementation Approach -### 1. Create New Executable Target: `skit-analyze` +### 1. Create Three Targets with Clear Separation -**Location**: `Sources/skit-analyze/` +This implementation uses three separate targets for better modularity and testability: + +#### Target 1: `ClaudeKit` (OpenAPI Generated Code) +**Location**: `Sources/ClaudeKit/` + +**Purpose**: Contains the raw OpenAPI-generated client code for the Anthropic Claude API **Dependencies**: -- `SyntaxParser` (existing) - for parsing Swift code to AST -- `ConfigKeyKit` (existing in project) - for configuration key management -- `swift-configuration` - for CLI argument and environment variable handling -- `swift-openapi-generator` - for generating type-safe Claude API client from OpenAPI spec - `swift-openapi-runtime` - runtime support for generated OpenAPI client - `swift-openapi-urlsession` - URLSession transport for OpenAPI client +**Build Plugin**: `OpenAPIGenerator` (generates client from `openapi.json`) + +**Contents**: +- `openapi.json` - Anthropic OpenAPI specification +- `openapi-generator-config.yaml` - Generator configuration +- Generated code (types, client) created automatically at build time + +#### Target 2: `AiSTKit` (SDK/Bridge Layer) +**Location**: `Sources/AiSTKit/` + +**Purpose**: Provides a clean, domain-specific interface between the command executable and the raw OpenAPI client. Handles prompt formatting, response parsing, and code generation logic. + +**Dependencies**: +- `ClaudeKit` - the OpenAPI-generated client +- `SyntaxParser` - for AST generation +- Foundation + +**Key Responsibilities**: +- Wraps `ClaudeKit` with domain-specific methods +- Implements `SyntaxKitAnalyzer` orchestration logic +- Handles prompt template creation +- Parses Claude responses into `LibraryUpdateResult` +- Manages AST generation +- Collects and writes library files + +#### Target 3: `skit-aist` (Command Executable) +**Location**: `Sources/skit-aist/` + +**Purpose**: CLI executable that handles argument parsing, configuration, and user interaction + +**Dependencies**: +- `AiSTKit` - the SDK/bridge layer +- `ConfigKeyKit` (existing in project) - for configuration key management +- `swift-configuration` - for CLI argument and environment variable handling + +**Key Responsibilities**: +- Parse command-line arguments +- Load configuration from environment variables +- Display help text and usage information +- Handle test mode execution +- Provide verbose output and error messages +- Entry point (`main.swift`) + ### 2. Core Components #### A. Configuration Structure (`AnalyzerConfiguration.swift`) @@ -76,7 +120,7 @@ struct AnalyzerConfiguration: ConfigurationParseable { guard positionalArgs.count >= 3 else { throw AnalyzerError.missingRequiredArguments( - "Usage: skit-analyze [options]" + "Usage: skit-aist [options]" ) } @@ -136,11 +180,11 @@ struct AnalyzeCommand: Command { typealias Config = AnalyzerConfiguration static let commandName = "analyze" - static let abstract = "Generate updated SyntaxKit library with missing features" + static let abstract = "AI-powered AST generation for SyntaxKit" static let helpText = """ OVERVIEW: Automatically implement missing SyntaxKit features using Claude API - USAGE: skit-analyze [options] + USAGE: skit-aist [options] ARGUMENTS: Folder containing: @@ -164,7 +208,7 @@ struct AnalyzeCommand: Command { echo 'subscript(index: Int) -> Item { ... }' > examples/subscript-feature/expected.swift export ANTHROPIC_API_KEY="sk-ant-..." - skit-analyze examples/subscript-feature Sources/SyntaxKit output/SyntaxKit + skit-aist examples/subscript-feature Sources/SyntaxKit output/SyntaxKit """ let config: Config @@ -254,7 +298,7 @@ struct SyntaxKitAnalyzer { // 4. Call Claude API for analysis AND code generation if config.verbose { print("Calling Claude API (\(config.model))...") } - let client = ClaudeAPIClient(apiKey: config.apiKey, model: config.model) + let client = ClaudeKit(apiKey: config.apiKey, model: config.model) let result = try await client.generateUpdatedLibrary( syntaxKitLibrary: libraryCode, expectedSwift: inputs.expectedSwift, @@ -437,7 +481,7 @@ struct ASTGenerator { - This is the same code path used by the `skit` executable - No need for external AST generation - it's built-in! -#### I. Claude API Client (`ClaudeAPIClient.swift`) +#### I. Claude API Client (`ClaudeKit.swift`) Wraps the OpenAPI-generated client for code generation: @@ -445,7 +489,7 @@ Wraps the OpenAPI-generated client for code generation: import OpenAPIRuntime import OpenAPIURLSession -struct ClaudeAPIClient { +struct ClaudeKit { let apiKey: String let model: String private let client: Client // Generated from OpenAPI spec @@ -607,12 +651,12 @@ struct FileReference: Codable { **OpenAPI Specification Source**: - Uses unofficial OpenAPI spec from [laszukdawid/anthropic-openapi-spec](https://github.com/laszukdawid/anthropic-openapi-spec) - Specifically the `hosted_spec.json` file (derived from Anthropic's TypeScript SDK) -- Download to `Sources/skit-analyze/openapi.json` or `openapi.yaml` +- Download to `Sources/skit-aist/openapi.json` or `openapi.yaml` - Swift OpenAPI Generator will create type-safe client code at build time **Setup Steps**: -1. Download OpenAPI spec: `curl -o Sources/skit-analyze/openapi.json https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json` -2. Create `Sources/skit-analyze/openapi-generator-config.yaml`: +1. Download OpenAPI spec: `curl -o Sources/skit-aist/openapi.json https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json` +2. Create `Sources/skit-aist/openapi-generator-config.yaml`: ```yaml generate: - types @@ -694,7 +738,7 @@ Include: ### 3. Workflow ``` -User runs: skit-analyze examples/subscript-feature Sources/SyntaxKit output/SyntaxKit +User runs: skit-aist examples/subscript-feature Sources/SyntaxKit output/SyntaxKit 1. main.swift: Entry point 2. AnalyzeCommand.createInstance(): @@ -761,7 +805,7 @@ Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenA // Add new executable target with OpenAPI Generator plugin: .executableTarget( - name: "skit-analyze", + name: "skit-aist", dependencies: [ "SyntaxParser", "ConfigKeyKit", @@ -777,19 +821,19 @@ Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenA // In products: .executable( - name: "skit-analyze", - targets: ["skit-analyze"] + name: "skit-aist", + targets: ["skit-aist"] ), ``` **Setup Requirements**: -1. Download OpenAPI spec to `Sources/skit-analyze/`: +1. Download OpenAPI spec to `Sources/skit-aist/`: ```bash - curl -o Sources/skit-analyze/openapi.json \ + curl -o Sources/skit-aist/openapi.json \ https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json ``` -2. Create `Sources/skit-analyze/openapi-generator-config.yaml`: +2. Create `Sources/skit-aist/openapi-generator-config.yaml`: ```yaml generate: - types @@ -844,7 +888,7 @@ Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenA 3. Output folder path (where to write updated library) - Parsed manually from `CommandLine.arguments` in configuration initializer - More intuitive than using flags for required paths -- Example: `skit-analyze examples/feature Sources/SyntaxKit output/updated` +- Example: `skit-aist examples/feature Sources/SyntaxKit output/updated` **Default Values**: - SyntaxKit library path: `Sources/SyntaxKit` (via `ConfigKey` default) @@ -897,28 +941,28 @@ Include full API request/response, intermediate parsing steps, file collection d ## Critical Files to Create ### Source Files -1. **Sources/skit-analyze/main.swift** - Main entry point -2. **Sources/skit-analyze/AnalyzeCommand.swift** - Command implementation using ConfigKeyKit -3. **Sources/skit-analyze/AnalyzerConfiguration.swift** - Configuration structure using ConfigKeyKit -4. **Sources/skit-analyze/SyntaxKitAnalyzer.swift** - Core analyzer orchestration -5. **Sources/skit-analyze/InputFolderReader.swift** - Reads dsl.swift, expected.swift, ast files -6. **Sources/skit-analyze/LibraryCollector.swift** - Collects SyntaxKit source files -7. **Sources/skit-analyze/LibraryWriter.swift** - Writes updated library to output folder -8. **Sources/skit-analyze/ASTGenerator.swift** - Wraps SyntaxParser for AST generation -9. **Sources/skit-analyze/ClaudeAPIClient.swift** - Wraps OpenAPI-generated client for code generation -10. **Sources/skit-analyze/PromptTemplate.swift** - Enhanced Workbench prompt with code generation -11. **Sources/skit-analyze/Models.swift** - Data models (LibraryUpdateResult, UpdatedFile, NewFile, AnalyzerError) +1. **Sources/skit-aist/main.swift** - Main entry point +2. **Sources/skit-aist/AnalyzeCommand.swift** - Command implementation using ConfigKeyKit +3. **Sources/skit-aist/AnalyzerConfiguration.swift** - Configuration structure using ConfigKeyKit +4. **Sources/skit-aist/SyntaxKitAnalyzer.swift** - Core analyzer orchestration +5. **Sources/skit-aist/InputFolderReader.swift** - Reads dsl.swift, expected.swift, ast files +6. **Sources/skit-aist/LibraryCollector.swift** - Collects SyntaxKit source files +7. **Sources/skit-aist/LibraryWriter.swift** - Writes updated library to output folder +8. **Sources/skit-aist/ASTGenerator.swift** - Wraps SyntaxParser for AST generation +9. **Sources/skit-aist/ClaudeKit.swift** - Wraps OpenAPI-generated client for code generation +10. **Sources/skit-aist/PromptTemplate.swift** - Enhanced Workbench prompt with code generation +11. **Sources/skit-aist/Models.swift** - Data models (LibraryUpdateResult, UpdatedFile, NewFile, AnalyzerError) ### Configuration Files -12. **Sources/skit-analyze/openapi.json** - Anthropic OpenAPI specification (downloaded) -13. **Sources/skit-analyze/openapi-generator-config.yaml** - OpenAPI Generator configuration +12. **Sources/skit-aist/openapi.json** - Anthropic OpenAPI specification (downloaded) +13. **Sources/skit-aist/openapi-generator-config.yaml** - OpenAPI Generator configuration 14. **Package.swift** (modify) - Add ConfigKeyKit target, dependencies, and OpenAPI plugin ### Test Mode Files (Section 8) -15. **Sources/skit-analyze/Testing/TestRunner.swift** - Orchestrates test execution -16. **Sources/skit-analyze/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases -17. **Sources/skit-analyze/Testing/TestValidator.swift** - Validates results against expectations -18. **Sources/skit-analyze/Testing/TestModels.swift** - Test data structures +15. **Sources/skit-aist/Testing/TestRunner.swift** - Orchestrates test execution +16. **Sources/skit-aist/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases +17. **Sources/skit-aist/Testing/TestValidator.swift** - Validates results against expectations +18. **Sources/skit-aist/Testing/TestModels.swift** - Test data structures ## Verification Steps @@ -948,7 +992,7 @@ Include full API request/response, intermediate parsing steps, file collection d 3. **Run Tool**: ```bash export ANTHROPIC_API_KEY="sk-ant-..." - .build/release/skit-analyze \ + .build/release/skit-aist \ examples/simple-property \ Sources/SyntaxKit \ output/SyntaxKit-updated @@ -975,16 +1019,16 @@ Include full API request/response, intermediate parsing steps, file collection d 6. **Error Handling Tests**: ```bash # Test missing API key - skit-analyze examples/test Sources/SyntaxKit output # Should error + skit-aist examples/test Sources/SyntaxKit output # Should error # Test invalid input folder - skit-analyze nonexistent Sources/SyntaxKit output # Should error + skit-aist nonexistent Sources/SyntaxKit output # Should error # Test missing required files mkdir -p examples/incomplete echo "test" > examples/incomplete/dsl.swift # Missing expected.swift - should error - skit-analyze examples/incomplete Sources/SyntaxKit output + skit-aist examples/incomplete Sources/SyntaxKit output ``` 7. **Integration Test**: Use a real missing feature (e.g., subscript syntax) and verify: @@ -1087,19 +1131,19 @@ See the full implementation plan in the main plan file for detailed component sp ```bash # Run all test cases -skit-analyze --test +skit-aist --test # Run with verbose output -skit-analyze --test --verbose +skit-aist --test --verbose # Stop on first failure -skit-analyze --test --test-stop-on-fail +skit-aist --test --test-stop-on-fail # Run only tests matching "subscript" -skit-analyze --test --test-filter=subscript +skit-aist --test --test-filter=subscript # Run tests from custom path -skit-analyze --test --test-cases=custom-tests/ +skit-aist --test --test-cases=custom-tests/ ``` ### Benefits @@ -1161,10 +1205,10 @@ skit-analyze --test --test-cases=custom-tests/ swift build -c release # Install to system (optional) -cp .build/release/skit-analyze /usr/local/bin/ +cp .build/release/skit-aist /usr/local/bin/ # Or run from build directory -.build/release/skit-analyze +.build/release/skit-aist ``` ## Example Usage @@ -1196,7 +1240,7 @@ EOF # 4. Run the tool # Note: AST is automatically generated from expected.swift using SyntaxParser export ANTHROPIC_API_KEY="sk-ant-..." -skit-analyze \ +skit-aist \ examples/subscript-feature \ Sources/SyntaxKit \ output/SyntaxKit-with-subscripts @@ -1206,19 +1250,19 @@ skit-analyze \ ```bash # With custom model -skit-analyze examples/my-feature Sources/SyntaxKit output/updated \ +skit-aist examples/my-feature Sources/SyntaxKit output/updated \ --model claude-sonnet-4-5 # With verbose output to see what's happening -skit-analyze examples/my-feature Sources/SyntaxKit output/updated \ +skit-aist examples/my-feature Sources/SyntaxKit output/updated \ --verbose # Using CLI flag for API key instead of environment -skit-analyze examples/my-feature Sources/SyntaxKit output/updated \ +skit-aist examples/my-feature Sources/SyntaxKit output/updated \ --api-key sk-ant-... # Show help -skit-analyze --help +skit-aist --help ``` ### Full Workflow Example @@ -1247,7 +1291,7 @@ EOF # Step 4: Generate updated SyntaxKit with defer support export ANTHROPIC_API_KEY="sk-ant-..." -skit-analyze \ +skit-aist \ examples/defer-statement \ Sources/SyntaxKit \ output/SyntaxKit-with-defer \ From 1ff317b40cca8363acd222f91c9ea18f6df88554 Mon Sep 17 00:00:00 2001 From: leogdion Date: Mon, 9 Feb 2026 17:58:39 -0500 Subject: [PATCH 5/9] Enforce one-type-per-file organization in skit-analyze plan - Add explicit Code Organization Principle section - Split AnalyzerConfiguration and AnalyzerError into separate files - Split ClaudeKit types into individual files (ClaudeKit, AuthenticationMiddleware, LibraryUpdateResult, FileReference) - Update Critical Files list to reflect 21 individual files - Add clear examples and exception rules for nested types Co-Authored-By: Claude Sonnet 4.5 --- Docs/skit-analyze-plan.md | 74 ++++++++++++++++++++++++++++++--------- 1 file changed, 58 insertions(+), 16 deletions(-) diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md index 95a87154..7e2228bc 100644 --- a/Docs/skit-analyze-plan.md +++ b/Docs/skit-analyze-plan.md @@ -17,6 +17,24 @@ This addresses the problem of implementing missing SyntaxKit features. Instead o ## Implementation Approach +### Code Organization Principle + +**IMPORTANT: Each type and extension must be in its own file.** + +All structs, enums, classes, protocols, and extensions should be defined in separate files named after the type. This ensures: +- Better code navigation and discoverability +- Clearer module boundaries and dependencies +- Easier maintenance and refactoring +- Simpler code reviews and version control + +**Examples:** +- `AnalyzerConfiguration` → `AnalyzerConfiguration.swift` +- `AnalyzerError` → `AnalyzerError.swift` +- `ClaudeKit` → `ClaudeKit.swift` +- `AuthenticationMiddleware` → `AuthenticationMiddleware.swift` + +**Exception:** Nested types that are tightly coupled to their parent (like `LibraryUpdateResult.UpdatedFile`) may remain in the same file as their parent type. + ### 1. Create Three Targets with Clear Separation This implementation uses three separate targets for better modularity and testability: @@ -156,7 +174,11 @@ struct AnalyzerConfiguration: ConfigurationParseable { } } } +``` +#### A2. Error Types (`AnalyzerError.swift`) + +```swift enum AnalyzerError: Error { case missingRequiredArguments(String) case missingAPIKey(String) @@ -600,8 +622,15 @@ struct ClaudeKit { ) } } +``` + +#### I2. Authentication Middleware (`AuthenticationMiddleware.swift`) + +Custom middleware for adding Anthropic API key header: + +```swift +import OpenAPIRuntime -/// Custom middleware for adding Anthropic API key header struct AuthenticationMiddleware: ClientMiddleware { let apiKey: String @@ -621,7 +650,13 @@ struct AuthenticationMiddleware: ClientMiddleware { return try await next(modifiedRequest, baseURL) } } +``` + +#### I3. Library Update Result (`LibraryUpdateResult.swift`) +Data structures for library update results: + +```swift struct LibraryUpdateResult: Codable { struct UpdatedFile: Codable { let relativePath: String // e.g., "Declarations/Subscript.swift" @@ -641,7 +676,11 @@ struct LibraryUpdateResult: Codable { let includeUnchangedFiles: Bool let summary: String // Claude's explanation of changes } +``` +#### I4. File Reference (`FileReference.swift`) + +```swift struct FileReference: Codable { let relativePath: String let sourcePath: String @@ -944,25 +983,28 @@ Include full API request/response, intermediate parsing steps, file collection d 1. **Sources/skit-aist/main.swift** - Main entry point 2. **Sources/skit-aist/AnalyzeCommand.swift** - Command implementation using ConfigKeyKit 3. **Sources/skit-aist/AnalyzerConfiguration.swift** - Configuration structure using ConfigKeyKit -4. **Sources/skit-aist/SyntaxKitAnalyzer.swift** - Core analyzer orchestration -5. **Sources/skit-aist/InputFolderReader.swift** - Reads dsl.swift, expected.swift, ast files -6. **Sources/skit-aist/LibraryCollector.swift** - Collects SyntaxKit source files -7. **Sources/skit-aist/LibraryWriter.swift** - Writes updated library to output folder -8. **Sources/skit-aist/ASTGenerator.swift** - Wraps SyntaxParser for AST generation -9. **Sources/skit-aist/ClaudeKit.swift** - Wraps OpenAPI-generated client for code generation -10. **Sources/skit-aist/PromptTemplate.swift** - Enhanced Workbench prompt with code generation -11. **Sources/skit-aist/Models.swift** - Data models (LibraryUpdateResult, UpdatedFile, NewFile, AnalyzerError) +4. **Sources/skit-aist/AnalyzerError.swift** - Error types for analyzer operations +5. **Sources/skit-aist/SyntaxKitAnalyzer.swift** - Core analyzer orchestration +6. **Sources/skit-aist/InputFolderReader.swift** - Reads dsl.swift, expected.swift, ast files +7. **Sources/skit-aist/LibraryCollector.swift** - Collects SyntaxKit source files +8. **Sources/skit-aist/LibraryWriter.swift** - Writes updated library to output folder +9. **Sources/skit-aist/ASTGenerator.swift** - Wraps SyntaxParser for AST generation +10. **Sources/skit-aist/ClaudeKit.swift** - Wraps OpenAPI-generated client for code generation +11. **Sources/skit-aist/AuthenticationMiddleware.swift** - OpenAPI middleware for API authentication +12. **Sources/skit-aist/LibraryUpdateResult.swift** - Data structures for library update results +13. **Sources/skit-aist/FileReference.swift** - File reference data structure +14. **Sources/skit-aist/PromptTemplate.swift** - Enhanced Workbench prompt with code generation ### Configuration Files -12. **Sources/skit-aist/openapi.json** - Anthropic OpenAPI specification (downloaded) -13. **Sources/skit-aist/openapi-generator-config.yaml** - OpenAPI Generator configuration -14. **Package.swift** (modify) - Add ConfigKeyKit target, dependencies, and OpenAPI plugin +15. **Sources/skit-aist/openapi.json** - Anthropic OpenAPI specification (downloaded) +16. **Sources/skit-aist/openapi-generator-config.yaml** - OpenAPI Generator configuration +17. **Package.swift** (modify) - Add ConfigKeyKit target, dependencies, and OpenAPI plugin ### Test Mode Files (Section 8) -15. **Sources/skit-aist/Testing/TestRunner.swift** - Orchestrates test execution -16. **Sources/skit-aist/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases -17. **Sources/skit-aist/Testing/TestValidator.swift** - Validates results against expectations -18. **Sources/skit-aist/Testing/TestModels.swift** - Test data structures +18. **Sources/skit-aist/Testing/TestRunner.swift** - Orchestrates test execution +19. **Sources/skit-aist/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases +20. **Sources/skit-aist/Testing/TestValidator.swift** - Validates results against expectations +21. **Sources/skit-aist/Testing/TestModels.swift** - Test data structures ## Verification Steps From fb68a20de061c944c7f643cf2cd1048494a5477d Mon Sep 17 00:00:00 2001 From: leogdion Date: Mon, 9 Feb 2026 18:18:45 -0500 Subject: [PATCH 6/9] Add GitHub issue creation automation for skit-aist implementation Created automated tooling to export the skit-analyze-plan.md into 18 structured GitHub issues organized across 7 implementation phases. New files: - scripts/create-issues.js: Automated issue creation script - scripts/issue-config.json: Issue metadata and specifications - scripts/package.json: Node.js package configuration - scripts/README.md: Script documentation and usage guide - scripts/ISSUE_CREATION_SUMMARY.md: Detailed issue breakdown - IMPLEMENTATION_STATUS.md: Project status tracking document Issues created (#107-#124): - Phase 1: Project Setup & Infrastructure (3 issues) - Phase 2: Core Configuration & Command (2 issues) - Phase 3: Input/Output Handlers (4 issues) - Phase 4: Claude API Integration (4 issues) - Phase 5: Main Orchestration (1 issue) - Phase 6: Testing Infrastructure (1 issue) - Phase 7: Verification & Documentation (3 issues) Labels created: infrastructure, setup, configuration, cli, io, api, models, prompts, orchestration, ast, testing, integration All issues properly cross-reference dependencies and include complete specifications, acceptance criteria, and file references. Co-Authored-By: Claude Sonnet 4.5 --- IMPLEMENTATION_STATUS.md | 257 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 IMPLEMENTATION_STATUS.md diff --git a/IMPLEMENTATION_STATUS.md b/IMPLEMENTATION_STATUS.md new file mode 100644 index 00000000..0b26128a --- /dev/null +++ b/IMPLEMENTATION_STATUS.md @@ -0,0 +1,257 @@ +# skit-aist Implementation Status + +## Overview + +This document tracks the implementation of the skit-aist tool, an AI-powered AST generation system for automatically implementing missing SyntaxKit features using the Claude API. + +**Plan Document**: [Docs/skit-analyze-plan.md](Docs/skit-analyze-plan.md) + +## GitHub Issues + +All implementation tasks have been broken down into 18 GitHub issues organized into 7 phases. + +**Issue Range**: #107 - #124 + +### Quick Links + +- [View All Issues](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Ainfrastructure%2Cconfiguration%2Ccli%2Cio%2Capi%2Corchestration%2Ctesting) +- [Phase 1: Infrastructure](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Ainfrastructure) +- [Phase 2: Configuration](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Aconfiguration) +- [Phase 3: I/O Handlers](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Aio) +- [Phase 4: API Integration](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Aapi) +- [Phase 5: Orchestration](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Aorchestration) +- [Phase 6-7: Testing & Documentation](https://github.com/brightdigit/SyntaxKit/issues?q=is%3Aissue+is%3Aopen+label%3Atesting%2Cdocumentation) + +## Implementation Phases + +### Phase 1: Project Setup & Infrastructure ✓ Planned + +**Issues**: #107, #108, #109 + +- [x] Issue #107: Setup OpenAPI Specification and Generator Configuration +- [x] Issue #108: Update Package.swift with Dependencies and Targets +- [x] Issue #109: Create ConfigKeyKit Target Structure + +**Status**: Ready to implement +**Estimated Effort**: 2-3 hours +**Critical Path**: Yes - blocks all other work + +### Phase 2: Core Configuration & Command Infrastructure ⏳ Waiting + +**Issues**: #110, #111 + +- [ ] Issue #110: Implement AnalyzerConfiguration and AnalyzerError +- [ ] Issue #111: Implement AnalyzeCommand and Main Entry Point + +**Status**: Blocked by Phase 1 +**Estimated Effort**: 3-4 hours +**Critical Path**: Yes + +### Phase 3: Input/Output Handlers ⏳ Waiting + +**Issues**: #112, #113, #114, #115 + +- [ ] Issue #112: Implement InputFolderReader +- [ ] Issue #113: Implement LibraryCollector +- [ ] Issue #114: Implement LibraryWriter +- [ ] Issue #115: Implement ASTGenerator + +**Status**: #112, #113, #115 can start after Phase 2; #114 needs #118 +**Estimated Effort**: 4-5 hours +**Parallelizable**: #112, #113, #115 can be done in parallel + +### Phase 4: Claude API Integration ⏳ Waiting + +**Issues**: #116, #117, #118, #119 + +- [ ] Issue #116: Implement ClaudeKit Wrapper +- [ ] Issue #117: Implement AuthenticationMiddleware +- [ ] Issue #118: Implement LibraryUpdateResult and FileReference Models +- [ ] Issue #119: Implement PromptTemplate + +**Status**: #117, #118, #119 can start after Phase 1; #116 needs #117, #119 +**Estimated Effort**: 5-6 hours +**Parallelizable**: #117, #118, #119 can be done in parallel + +### Phase 5: Main Orchestration ⏳ Waiting + +**Issues**: #120 + +- [ ] Issue #120: Implement SyntaxKitAnalyzer Orchestration + +**Status**: Blocked by #112, #113, #114, #115, #116 +**Estimated Effort**: 3-4 hours +**Critical Path**: Yes - integrates all components + +### Phase 6: Testing Infrastructure ⏳ Waiting + +**Issues**: #121 + +- [ ] Issue #121: Implement Test/Validation Mode Components + +**Status**: Blocked by #120 +**Estimated Effort**: 4-5 hours +**Optional**: Can skip for MVP + +### Phase 7: Verification & Documentation ⏳ Waiting + +**Issues**: #122, #123, #124 + +- [ ] Issue #122: Create Verification Test Cases +- [ ] Issue #123: Create Example Usage Documentation +- [ ] Issue #124: Create Integration Tests + +**Status**: #123 blocked by #120; #122, #124 blocked by #121 +**Estimated Effort**: 3-4 hours +**Parallelizable**: #122 and #123 can be done in parallel + +## Progress Tracking + +### Overall Progress + +- **Issues Created**: 18/18 ✓ +- **Issues Completed**: 0/18 +- **Phases Completed**: 0/7 +- **Estimated Total Effort**: 24-31 hours + +### Current Status + +**Current Phase**: Phase 1 (Project Setup) +**Next Actionable Issue**: #107 +**Blocked Issues**: 15 (waiting on dependencies) + +## Critical Path + +The minimum viable implementation follows this path: + +1. #107 → #108 → #109 (Infrastructure) +2. #110 (Configuration) +3. #111 (CLI Command) +4. #112, #113, #115 (I/O and AST - parallel) +5. #117, #118, #119 (API components - parallel) +6. #116 (ClaudeKit wrapper) +7. #114 (Library writer) +8. #120 (Orchestration) +9. #123 (Documentation) + +**Minimum Path Effort**: ~18-22 hours +**Can Skip for MVP**: Issues #121, #122, #124 (testing infrastructure) + +## Quick Start Guide + +### For Implementation + +```bash +# Start with Phase 1 +gh issue view 107 +gh issue view 108 +gh issue view 109 + +# Then move to Phase 2 +gh issue view 110 +gh issue view 111 + +# Continue following dependency order... +``` + +### For Project Management + +```bash +# View all open issues +gh issue list --label infrastructure,configuration,cli,io,api,orchestration + +# View issues ready to work on (no dependencies) +gh issue list --label infrastructure --state open + +# Track progress +gh issue list --state closed --label infrastructure,configuration,cli,io,api,orchestration +``` + +## Architecture Overview + +### Three-Target Design + +1. **ClaudeKit** - OpenAPI-generated Claude API client +2. **AiSTKit** - SDK/bridge layer for domain logic +3. **skit-aist** - CLI executable for user interaction + +### Key Dependencies + +- **Swift OpenAPI Generator** - Type-safe API client generation +- **swift-configuration** - CLI/ENV configuration management +- **ConfigKeyKit** - Configuration key abstraction +- **SyntaxParser** - Existing AST generation (reused) + +### Data Flow + +``` +Input Folder (dsl.swift, expected.swift) + → InputFolderReader + → ASTGenerator (via SyntaxParser) + → LibraryCollector (scan SyntaxKit sources) + → ClaudeKit (API call with prompt) + → LibraryUpdateResult (parsed response) + → LibraryWriter + → Output Folder (updated SyntaxKit) +``` + +## Testing Strategy + +### Unit Tests (Phase 6) + +- Configuration parsing +- Input/output file operations +- AST generation +- Response parsing + +### Integration Tests (Phase 7) + +- End-to-end with real missing feature +- Verify generated code compiles +- Verify generated code follows patterns + +### Validation Tests (Phase 7) + +- Structural validation +- Content validation +- Build validation +- Functional validation + +## Documentation + +- **Implementation Plan**: [Docs/skit-analyze-plan.md](Docs/skit-analyze-plan.md) +- **Issue Summary**: [scripts/ISSUE_CREATION_SUMMARY.md](scripts/ISSUE_CREATION_SUMMARY.md) +- **Script Documentation**: [scripts/README.md](scripts/README.md) +- **Usage Documentation**: To be created in #123 + +## Next Steps + +1. **Review Issues**: Ensure all issue specifications are complete +2. **Start Phase 1**: Begin with #107 (OpenAPI setup) +3. **Create Project Board** (optional): Visualize progress +4. **Assign Milestones** (optional): Group related work + +```bash +# Optional: Create project board +gh project create --title "skit-aist Implementation" \ + --body "Track implementation of AI-powered AST generation tool" +``` + +## Success Criteria + +- [ ] All 18 issues completed +- [ ] Tool builds successfully: `swift build -c release` +- [ ] Can process example input and generate valid SyntaxKit code +- [ ] Generated code compiles +- [ ] Integration test passes with real missing feature +- [ ] Documentation complete +- [ ] Test mode validates Claude responses + +## Contact + +For questions or issues, please comment on the relevant GitHub issue or create a new issue. + +--- + +**Last Updated**: 2026-02-09 +**Status**: Planning Complete, Implementation Ready From 40cf17f01824eda083e011bf65e9fb168c2fb86e Mon Sep 17 00:00:00 2001 From: leogdion Date: Mon, 9 Feb 2026 18:18:58 -0500 Subject: [PATCH 7/9] Add issue creation scripts and documentation Scripts for automated GitHub issue generation: - Scripts/create-issues.js: Main automation script - Scripts/issue-config.json: Issue specifications for all 18 tasks - Scripts/package.json: Node.js configuration - Scripts/README.md: Script usage documentation - Scripts/ISSUE_CREATION_SUMMARY.md: Detailed breakdown of created issues These scripts successfully created issues #107-#124 for the skit-aist implementation, organized into 7 phases with proper dependency tracking. Co-Authored-By: Claude Sonnet 4.5 --- Scripts/ISSUE_CREATION_SUMMARY.md | 191 ++++++++++++++++ Scripts/README.md | 155 +++++++++++++ Scripts/create-issues.js | 152 +++++++++++++ Scripts/issue-config.json | 351 ++++++++++++++++++++++++++++++ Scripts/package.json | 10 + 5 files changed, 859 insertions(+) create mode 100644 Scripts/ISSUE_CREATION_SUMMARY.md create mode 100644 Scripts/README.md create mode 100755 Scripts/create-issues.js create mode 100644 Scripts/issue-config.json create mode 100644 Scripts/package.json diff --git a/Scripts/ISSUE_CREATION_SUMMARY.md b/Scripts/ISSUE_CREATION_SUMMARY.md new file mode 100644 index 00000000..ff0c8aed --- /dev/null +++ b/Scripts/ISSUE_CREATION_SUMMARY.md @@ -0,0 +1,191 @@ +# GitHub Issues Creation Summary + +## Overview + +Successfully created 18 GitHub issues from the skit-analyze-plan.md implementation plan. + +## Issue Breakdown by Phase + +### Phase 1: Project Setup & Infrastructure (Issues #107-#109) + +**Issue #107: Setup OpenAPI Specification and Generator Configuration** +- Labels: infrastructure, setup +- Dependencies: None +- Files: Sources/ClaudeKit/openapi.json, Sources/ClaudeKit/openapi-generator-config.yaml + +**Issue #108: Update Package.swift with Dependencies and Targets** +- Labels: infrastructure, setup +- Dependencies: #107 +- Files: Package.swift + +**Issue #109: Create ConfigKeyKit Target Structure** +- Labels: infrastructure, setup +- Dependencies: #108 +- Files: Package.swift + +### Phase 2: Core Configuration & Command Infrastructure (Issues #110-#111) + +**Issue #110: Implement AnalyzerConfiguration and AnalyzerError** +- Labels: enhancement, configuration +- Dependencies: #109 +- Files: Sources/AiSTKit/AnalyzerConfiguration.swift, Sources/AiSTKit/AnalyzerError.swift + +**Issue #111: Implement AnalyzeCommand and Main Entry Point** +- Labels: enhancement, cli +- Dependencies: #110 +- Files: Sources/skit-aist/AnalyzeCommand.swift, Sources/skit-aist/main.swift + +### Phase 3: Input/Output Handlers (Issues #112-#115) + +**Issue #112: Implement InputFolderReader** +- Labels: enhancement, io +- Dependencies: #110 +- Files: Sources/AiSTKit/InputFolderReader.swift + +**Issue #113: Implement LibraryCollector** +- Labels: enhancement, io +- Dependencies: #110 +- Files: Sources/AiSTKit/LibraryCollector.swift + +**Issue #114: Implement LibraryWriter** +- Labels: enhancement, io +- Dependencies: #118 (LibraryUpdateResult) +- Files: Sources/AiSTKit/LibraryWriter.swift + +**Issue #115: Implement ASTGenerator** +- Labels: enhancement, ast +- Dependencies: #110 +- Files: Sources/AiSTKit/ASTGenerator.swift + +### Phase 4: Claude API Integration (Issues #116-#119) + +**Issue #116: Implement ClaudeKit Wrapper** +- Labels: enhancement, api +- Dependencies: #108, #117, #119 +- Files: Sources/AiSTKit/ClaudeKit.swift + +**Issue #117: Implement AuthenticationMiddleware** +- Labels: enhancement, api +- Dependencies: #108 +- Files: Sources/AiSTKit/AuthenticationMiddleware.swift + +**Issue #118: Implement LibraryUpdateResult and FileReference Models** +- Labels: enhancement, models +- Dependencies: #110 +- Files: Sources/AiSTKit/LibraryUpdateResult.swift, Sources/AiSTKit/FileReference.swift + +**Issue #119: Implement PromptTemplate** +- Labels: enhancement, prompts +- Dependencies: None +- Files: Sources/AiSTKit/PromptTemplate.swift + +### Phase 5: Main Orchestration (Issue #120) + +**Issue #120: Implement SyntaxKitAnalyzer Orchestration** +- Labels: enhancement, orchestration +- Dependencies: #112, #113, #114, #115, #116 +- Files: Sources/AiSTKit/SyntaxKitAnalyzer.swift + +### Phase 6: Testing Infrastructure (Issue #121) + +**Issue #121: Implement Test/Validation Mode Components** +- Labels: enhancement, testing +- Dependencies: #120 +- Files: Sources/AiSTKit/Testing/*.swift (TestRunner, TestCaseDiscoverer, TestValidator, TestModels) + +### Phase 7: Verification & Documentation (Issues #122-#124) + +**Issue #122: Create Verification Test Cases** +- Labels: testing +- Dependencies: #121 +- Files: examples/*/dsl.swift, examples/*/expected.swift + +**Issue #123: Create Example Usage Documentation** +- Labels: documentation +- Dependencies: #120 +- Files: Docs/skit-aist-usage.md + +**Issue #124: Create Integration Tests** +- Labels: testing, integration +- Dependencies: #122 +- Files: Tests/AiSTKitTests/IntegrationTests.swift + +## Labels Created + +The following labels were created for this project: + +- **infrastructure** (#0052CC) - Infrastructure and setup tasks +- **setup** (#0052CC) - Setup and configuration +- **configuration** (#5319E7) - Configuration related +- **cli** (#1D76DB) - Command-line interface +- **io** (#006B75) - Input/Output operations +- **api** (#0E8A16) - API integration +- **models** (#FBCA04) - Data models +- **prompts** (#D93F0B) - Prompt templates +- **orchestration** (#C5DEF5) - Workflow orchestration +- **ast** (#BFD4F2) - AST generation +- **testing** (#d876e3) - Testing infrastructure +- **integration** (#5319E7) - Integration testing + +Existing labels used: +- **enhancement** - New features +- **documentation** - Documentation updates + +## Implementation Order + +Issues should be worked on in dependency order: + +1. **Phase 1**: #107 → #108 → #109 (Foundation) +2. **Phase 2**: #110 → #111 (Configuration) +3. **Phase 3**: #112, #113, #115 (can be parallel), then #118, then #114 +4. **Phase 4**: #119 (parallel), #117 (parallel with #118), then #116 +5. **Phase 5**: #120 (Main orchestration - requires most prior work) +6. **Phase 6**: #121 (Testing infrastructure) +7. **Phase 7**: #122 → #123 (parallel), #124 + +## Quick Reference Commands + +```bash +# View all skit-aist issues +gh issue list --label infrastructure,configuration,cli,io,api,orchestration + +# View issues by phase (using labels) +gh issue list --label infrastructure # Phase 1 +gh issue list --label configuration # Phase 2 +gh issue list --label io # Phase 3 +gh issue list --label api # Phase 4 +gh issue list --label orchestration # Phase 5 +gh issue list --label testing # Phase 6-7 + +# Start work on first issue +gh issue view 107 +``` + +## Files Created + +- `scripts/package.json` - Node.js package configuration +- `scripts/issue-config.json` - Issue metadata and configuration +- `scripts/create-issues.js` - Automated issue creation script +- `scripts/ISSUE_CREATION_SUMMARY.md` - This summary document + +## Success Metrics + +- ✅ All 18 issues created successfully +- ✅ All labels created with appropriate colors +- ✅ Dependencies correctly cross-referenced +- ✅ Issues numbered #107-#124 +- ✅ Each issue is self-contained and actionable +- ✅ All code snippets from plan included in relevant issues +- ✅ Acceptance criteria clearly defined for each issue + +## Next Steps + +1. Review all issues to ensure completeness +2. Consider creating a GitHub Project board to track progress +3. Assign issues to team members or milestones +4. Begin implementation starting with Phase 1 issues + +```bash +# Optional: Create a project board +gh project create --title "skit-aist Implementation" --body "Track skit-aist tool development" +``` diff --git a/Scripts/README.md b/Scripts/README.md new file mode 100644 index 00000000..5f3dfe4c --- /dev/null +++ b/Scripts/README.md @@ -0,0 +1,155 @@ +# GitHub Issue Creation Scripts + +This directory contains scripts for automating the creation of GitHub issues from implementation plans. + +## Files + +- **`create-issues.js`** - Main script that creates GitHub issues from configuration +- **`issue-config.json`** - Issue metadata, labels, and specifications +- **`package.json`** - Node.js package configuration +- **`ISSUE_CREATION_SUMMARY.md`** - Summary of created issues + +## Prerequisites + +1. **GitHub CLI** installed and authenticated: + ```bash + gh auth status + gh auth login # if needed + ``` + +2. **Node.js** (v18 or later recommended): + ```bash + node --version + ``` + +## Usage + +### Create Issues + +```bash +cd scripts +node create-issues.js +``` + +The script will: +1. Create all necessary labels if they don't exist +2. Create issues in dependency order +3. Cross-reference dependencies between issues +4. Output a summary with issue numbers + +### View Created Issues + +```bash +# List all issues +gh issue list --limit 20 + +# View specific issue +gh issue view 107 + +# List issues by label +gh issue list --label infrastructure +gh issue list --label testing +``` + +## Issue Configuration + +The `issue-config.json` file defines: + +- **labels** - Label names and colors +- **issues** - Array of issue specifications with: + - `id` - Local issue ID (for dependency tracking) + - `phase` - Implementation phase + - `title` - Issue title + - `labels` - Array of label names + - `dependencies` - Array of issue IDs this depends on + - `files` - Files to create/modify + - `spec` - Specification text + - `acceptance` - Array of acceptance criteria + +## Adding New Issues + +To add new issues: + +1. Edit `issue-config.json` +2. Add new issue object to the `issues` array +3. Ensure dependencies reference existing issue IDs +4. Run `node create-issues.js` + +## Script Features + +- **Dependency Handling** - Creates issues in order, cross-references dependencies +- **Label Management** - Creates missing labels automatically +- **Error Handling** - Continues on errors, reports failures +- **Rate Limiting** - Small delays between API calls +- **Summary Output** - Maps local IDs to GitHub issue numbers + +## Example Output + +``` +GitHub Issue Creator for skit-analyze-plan.md +================================================== + +Step 1: Creating labels... + Created label: infrastructure + Label "enhancement" already exists + ... + +Step 2: Creating issues... + +Creating issue 1: Setup OpenAPI Specification and Generator Configuration + Created issue #107: Setup OpenAPI Specification and Generator Configuration + +Creating issue 2: Update Package.swift with Dependencies and Targets + Created issue #108: Update Package.swift with Dependencies and Targets + ... + +================================================== +Summary: + Total issues created: 18 / 18 + +Issue mapping: + Issue 1 -> #107: Setup OpenAPI Specification and Generator Configuration + Issue 2 -> #108: Update Package.swift with Dependencies and Targets + ... +``` + +## Troubleshooting + +### GitHub CLI Not Authenticated + +```bash +gh auth login +``` + +### Label Already Exists Error + +This is expected - the script handles existing labels gracefully. + +### Issue Creation Failed + +Check the error message. Common issues: +- Network connectivity +- API rate limiting (add delays in script) +- Invalid characters in title/body (check escaping) + +## Customization + +### Changing Label Colors + +Edit the `labels` object in `issue-config.json`: + +```json +"labels": { + "infrastructure": "0052CC", + "custom-label": "FF0000" +} +``` + +### Modifying Issue Template + +Edit the `formatIssueBody()` function in `create-issues.js` to change the issue body format. + +## Related Documentation + +- [skit-analyze-plan.md](../Docs/skit-analyze-plan.md) - Full implementation plan +- [ISSUE_CREATION_SUMMARY.md](./ISSUE_CREATION_SUMMARY.md) - Summary of created issues diff --git a/Scripts/create-issues.js b/Scripts/create-issues.js new file mode 100755 index 00000000..eb333f35 --- /dev/null +++ b/Scripts/create-issues.js @@ -0,0 +1,152 @@ +#!/usr/bin/env node + +import { readFileSync } from 'fs'; +import { execSync } from 'child_process'; + +// Load configuration +const config = JSON.parse(readFileSync('./issue-config.json', 'utf8')); + +// Function to execute shell command and return output +function exec(command) { + try { + return execSync(command, { encoding: 'utf8' }).trim(); + } catch (error) { + console.error(`Error executing command: ${command}`); + console.error(error.message); + throw error; + } +} + +// Function to check if a label exists +function labelExists(label) { + try { + exec(`gh label list --limit 1000 --json name --jq '.[] | select(.name=="${label}") | .name'`); + return true; + } catch { + return false; + } +} + +// Function to create a label if it doesn't exist +function createLabel(name, color) { + if (labelExists(name)) { + console.log(` Label "${name}" already exists`); + return; + } + + try { + exec(`gh label create "${name}" --color "${color}" --description ""`); + console.log(` Created label: ${name}`); + } catch (error) { + console.error(` Failed to create label: ${name}`); + } +} + +// Function to format issue body +function formatIssueBody(issue, createdIssues) { + const phaseSection = `## Phase\n\n${issue.phase}\n`; + + const specSection = `## Specification\n\n${issue.spec}\n`; + + const acceptanceSection = `## Acceptance Criteria\n\n${issue.acceptance.map(c => `- [ ] ${c}`).join('\n')}\n`; + + const dependenciesSection = issue.dependencies.length > 0 + ? `## Dependencies\n\n${issue.dependencies.map(depId => { + const ghIssueNum = createdIssues.get(depId); + return ghIssueNum ? `- Depends on: #${ghIssueNum}` : `- Depends on: Issue ${depId} (to be created)`; + }).join('\n')}\n` + : ''; + + const filesSection = issue.files.length > 0 + ? `## Files to Create/Modify\n\n${issue.files.map(f => `- \`${f}\``).join('\n')}\n` + : ''; + + const relatedSection = `## Related Documentation\n\n- [skit-analyze-plan.md](../blob/main/Docs/skit-analyze-plan.md)\n`; + + return [phaseSection, specSection, acceptanceSection, dependenciesSection, filesSection, relatedSection] + .filter(s => s) + .join('\n'); +} + +// Function to create a GitHub issue +function createIssue(issue, createdIssues) { + const body = formatIssueBody(issue, createdIssues); + const labels = issue.labels.join(','); + + // Escape special characters in title and body for shell + const escapedTitle = issue.title.replace(/"/g, '\\"'); + const escapedBody = body.replace(/"/g, '\\"').replace(/`/g, '\\`'); + + try { + const result = exec(`gh issue create --title "${escapedTitle}" --body "${escapedBody}" --label "${labels}"`); + // Extract issue number from URL (format: https://github.com/owner/repo/issues/123) + const match = result.match(/issues\/(\d+)/); + if (match) { + const issueNumber = parseInt(match[1], 10); + console.log(` Created issue #${issueNumber}: ${issue.title}`); + return issueNumber; + } + } catch (error) { + console.error(` Failed to create issue: ${issue.title}`); + console.error(` Error: ${error.message}`); + } + + return null; +} + +// Main execution +async function main() { + console.log('GitHub Issue Creator for skit-analyze-plan.md'); + console.log('='.repeat(50)); + + // Step 1: Create labels + console.log('\nStep 1: Creating labels...'); + Object.entries(config.labels).forEach(([name, color]) => { + createLabel(name, color); + }); + + // Step 2: Create issues in dependency order + console.log('\nStep 2: Creating issues...'); + const createdIssues = new Map(); // Maps local issue ID to GitHub issue number + + // Sort issues by ID to ensure dependencies are created first + const sortedIssues = config.issues.sort((a, b) => a.id - b.id); + + for (const issue of sortedIssues) { + console.log(`\nCreating issue ${issue.id}: ${issue.title}`); + + // Check if all dependencies have been created + const missingDeps = issue.dependencies.filter(depId => !createdIssues.has(depId)); + if (missingDeps.length > 0) { + console.log(` Warning: Missing dependencies: ${missingDeps.join(', ')}`); + } + + const issueNumber = createIssue(issue, createdIssues); + if (issueNumber) { + createdIssues.set(issue.id, issueNumber); + } + + // Small delay to avoid rate limiting + await new Promise(resolve => setTimeout(resolve, 500)); + } + + // Step 3: Summary + console.log('\n' + '='.repeat(50)); + console.log('Summary:'); + console.log(` Total issues created: ${createdIssues.size} / ${config.issues.length}`); + console.log('\nIssue mapping:'); + Array.from(createdIssues.entries()) + .sort((a, b) => a[0] - b[0]) + .forEach(([localId, ghNumber]) => { + const issue = config.issues.find(i => i.id === localId); + console.log(` Issue ${localId} -> #${ghNumber}: ${issue.title}`); + }); + + console.log('\nDone! View all issues:'); + console.log(' gh issue list --limit 20'); +} + +main().catch(error => { + console.error('Fatal error:', error); + process.exit(1); +}); diff --git a/Scripts/issue-config.json b/Scripts/issue-config.json new file mode 100644 index 00000000..173e4f46 --- /dev/null +++ b/Scripts/issue-config.json @@ -0,0 +1,351 @@ +{ + "labels": { + "infrastructure": "0052CC", + "setup": "0052CC", + "configuration": "5319E7", + "cli": "1D76DB", + "io": "006B75", + "api": "0E8A16", + "models": "FBCA04", + "prompts": "D93F0B", + "orchestration": "C5DEF5", + "ast": "BFD4F2", + "enhancement": "a2eeef", + "documentation": "0075ca", + "testing": "d876e3" + }, + "milestone": null, + "issues": [ + { + "id": 1, + "phase": "Phase 1: Project Setup & Infrastructure", + "title": "Setup OpenAPI Specification and Generator Configuration", + "labels": ["infrastructure", "setup"], + "dependencies": [], + "files": [ + "Sources/ClaudeKit/openapi.json", + "Sources/ClaudeKit/openapi-generator-config.yaml" + ], + "spec": "Download Anthropic OpenAPI spec from laszukdawid/anthropic-openapi-spec repository and configure Swift OpenAPI Generator build plugin.", + "acceptance": [ + "OpenAPI spec downloaded to Sources/ClaudeKit/openapi.json", + "openapi-generator-config.yaml created with types and client generation enabled", + "Configuration specifies internal access modifier", + "Files are ready for Package.swift integration" + ] + }, + { + "id": 2, + "phase": "Phase 1: Project Setup & Infrastructure", + "title": "Update Package.swift with Dependencies and Targets", + "labels": ["infrastructure", "setup"], + "dependencies": [1], + "files": ["Package.swift"], + "spec": "Add all required dependencies (swift-configuration, OpenAPI packages) and create three new targets: ClaudeKit, AiSTKit, and skit-aist executable.", + "acceptance": [ + "swift-configuration dependency added with CommandLineArguments trait", + "swift-openapi-generator, swift-openapi-runtime, swift-openapi-urlsession dependencies added", + "ClaudeKit target created with OpenAPIGenerator plugin", + "AiSTKit target created with dependencies on ClaudeKit and SyntaxParser", + "skit-aist executable target created with all required dependencies", + "skit-aist product exported as executable", + "Package builds successfully: swift build" + ] + }, + { + "id": 3, + "phase": "Phase 1: Project Setup & Infrastructure", + "title": "Create ConfigKeyKit Target Structure", + "labels": ["infrastructure", "setup"], + "dependencies": [2], + "files": ["Package.swift"], + "spec": "Add ConfigKeyKit as a library target in Package.swift with swift-configuration dependency.", + "acceptance": [ + "ConfigKeyKit added as a library target in Package.swift", + "ConfigKeyKit has swift-configuration dependency", + "ConfigKeyKit pattern is compatible with existing code", + "Package builds successfully" + ] + }, + { + "id": 4, + "phase": "Phase 2: Core Configuration & Command Infrastructure", + "title": "Implement AnalyzerConfiguration and AnalyzerError", + "labels": ["enhancement", "configuration"], + "dependencies": [3], + "files": [ + "Sources/AiSTKit/AnalyzerConfiguration.swift", + "Sources/AiSTKit/AnalyzerError.swift" + ], + "spec": "Create configuration structure using ConfigKeyKit pattern with support for positional arguments and environment variables. Define comprehensive error types.", + "acceptance": [ + "AnalyzerConfiguration implements ConfigurationParseable protocol", + "Configuration keys defined: syntaxKitPathKey, apiKeyKey, modelKey, verboseKey", + "Positional argument parsing implemented for input folder, syntaxkit path, output folder", + "Path validation logic implemented", + "AnalyzerError enum defines all error cases", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 5, + "phase": "Phase 2: Core Configuration & Command Infrastructure", + "title": "Implement AnalyzeCommand and Main Entry Point", + "labels": ["enhancement", "cli"], + "dependencies": [4], + "files": [ + "Sources/skit-aist/AnalyzeCommand.swift", + "Sources/skit-aist/main.swift" + ], + "spec": "Create command implementation using ConfigKeyKit Command protocol and main entry point with error handling.", + "acceptance": [ + "AnalyzeCommand implements Command protocol", + "commandName, abstract, and helpText defined with complete usage information", + "createInstance() creates ConfigReader with CLI and ENV providers", + "execute() delegates to SyntaxKitAnalyzer", + "main.swift implements @main entry point with error handling", + "Help text documents all arguments and options", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 6, + "phase": "Phase 3: Input/Output Handlers", + "title": "Implement InputFolderReader", + "labels": ["enhancement", "io"], + "dependencies": [4], + "files": ["Sources/AiSTKit/InputFolderReader.swift"], + "spec": "Create input folder reader that validates and reads dsl.swift and expected.swift files.", + "acceptance": [ + "InputFolderReader struct created with folderPath property", + "Inputs nested struct defined with dslCode and expectedSwift properties", + "readInputs() validates presence of required files", + "readInputs() reads file contents with error handling", + "Appropriate errors thrown for missing files", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 7, + "phase": "Phase 3: Input/Output Handlers", + "title": "Implement LibraryCollector", + "labels": ["enhancement", "io"], + "dependencies": [4], + "files": ["Sources/AiSTKit/LibraryCollector.swift"], + "spec": "Create library collector that recursively scans SyntaxKit directory for Swift source files.", + "acceptance": [ + "LibraryCollector struct created", + "Recursive .swift file scanning implemented", + "Test files and build artifacts are skipped", + "Output formatted with file path markers", + "File count tracking for verbose output", + "Relative paths preserved", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 8, + "phase": "Phase 3: Input/Output Handlers", + "title": "Implement LibraryWriter", + "labels": ["enhancement", "io"], + "dependencies": [12], + "files": ["Sources/AiSTKit/LibraryWriter.swift"], + "spec": "Create library writer that writes LibraryUpdateResult to output directory with proper structure.", + "acceptance": [ + "LibraryWriter struct created with outputPath property", + "writeUpdatedLibrary() creates output directory with intermediate directories", + "Updated files written to correct paths", + "New files written to correct paths", + "Optional: unchanged files copied if needed", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 9, + "phase": "Phase 3: Input/Output Handlers", + "title": "Implement ASTGenerator", + "labels": ["enhancement", "ast"], + "dependencies": [4], + "files": ["Sources/AiSTKit/ASTGenerator.swift"], + "spec": "Create AST generator that wraps SyntaxParser to produce JSON AST from Swift code.", + "acceptance": [ + "ASTGenerator struct created", + "generateAST() uses SyntaxParser.parse()", + "TreeNode array formatted as JSON", + "JSONEncoder uses prettyPrinted and sortedKeys", + "Error handling for encoding failures", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 10, + "phase": "Phase 4: Claude API Integration", + "title": "Implement ClaudeKit Wrapper", + "labels": ["enhancement", "api"], + "dependencies": [2, 11, 13], + "files": ["Sources/AiSTKit/ClaudeKit.swift"], + "spec": "Create ClaudeKit wrapper around OpenAPI-generated client for code generation API calls.", + "acceptance": [ + "ClaudeKit struct created with apiKey, model, and client properties", + "init creates OpenAPI client with URLSession transport and AuthenticationMiddleware", + "generateUpdatedLibrary() calls OpenAPI client.postV1Messages()", + "Response content extracted from API response", + "parseCodeGenerationResponse() called to parse response", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 11, + "phase": "Phase 4: Claude API Integration", + "title": "Implement AuthenticationMiddleware", + "labels": ["enhancement", "api"], + "dependencies": [2], + "files": ["Sources/AiSTKit/AuthenticationMiddleware.swift"], + "spec": "Create OpenAPI middleware that adds Anthropic API authentication headers.", + "acceptance": [ + "AuthenticationMiddleware implements ClientMiddleware protocol", + "intercept() adds x-api-key header with API key", + "intercept() adds anthropic-version header", + "Middleware correctly forwards request to next handler", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 12, + "phase": "Phase 4: Claude API Integration", + "title": "Implement LibraryUpdateResult and FileReference Models", + "labels": ["enhancement", "models"], + "dependencies": [4], + "files": [ + "Sources/AiSTKit/LibraryUpdateResult.swift", + "Sources/AiSTKit/FileReference.swift" + ], + "spec": "Create data models for library update results including updated files, new files, and file references.", + "acceptance": [ + "LibraryUpdateResult struct created as Codable", + "UpdatedFile nested struct defined", + "NewFile nested struct defined", + "FileReference struct created as Codable", + "All necessary properties included (paths, content, descriptions)", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 13, + "phase": "Phase 4: Claude API Integration", + "title": "Implement PromptTemplate", + "labels": ["enhancement", "prompts"], + "dependencies": [], + "files": ["Sources/AiSTKit/PromptTemplate.swift"], + "spec": "Create prompt template that combines Workbench analysis prompt with code generation instructions.", + "acceptance": [ + "PromptTemplate struct created", + "createAnalysisAndCodeGeneration() static method implemented", + "Original Workbench prompt integrated", + "Code generation instructions added", + "Structured output format defined with XML-style markers", + "Prompt requests complete file content (not diffs)", + "Compilation validity emphasized", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 14, + "phase": "Phase 5: Main Orchestration", + "title": "Implement SyntaxKitAnalyzer Orchestration", + "labels": ["enhancement", "orchestration"], + "dependencies": [6, 7, 8, 9, 10], + "files": ["Sources/AiSTKit/SyntaxKitAnalyzer.swift"], + "spec": "Create main orchestrator that coordinates the entire workflow from input reading through library writing.", + "acceptance": [ + "SyntaxKitAnalyzer struct created with config property", + "run() method orchestrates: read inputs, generate AST, collect library, call API, write output", + "Verbose output at each step when enabled", + "writeUpdatedLibrary() helper implemented", + "Success message printed with output path", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 15, + "phase": "Phase 6: Testing Infrastructure", + "title": "Implement Test/Validation Mode Components", + "labels": ["enhancement", "testing"], + "dependencies": [14], + "files": [ + "Sources/AiSTKit/Testing/TestRunner.swift", + "Sources/AiSTKit/Testing/TestCaseDiscoverer.swift", + "Sources/AiSTKit/Testing/TestValidator.swift", + "Sources/AiSTKit/Testing/TestModels.swift" + ], + "spec": "Create comprehensive test mode infrastructure for validating Claude's generated code against expected outputs.", + "acceptance": [ + "TestRunner implements test case discovery and execution", + "TestCaseDiscoverer loads test cases from test-cases/ directory", + "TestValidator implements validation strategies (structural, content, build, functional)", + "TestModels defines TestCase, TestConfig, TestManifest, ValidationResult", + "AnalyzerConfiguration updated with test mode flags (--test, --test-stop-on-fail, --test-filter, --test-cases)", + "Test mode can run all tests or filtered subset", + "Code follows one-type-per-file organization" + ] + }, + { + "id": 16, + "phase": "Phase 7: Verification & Documentation", + "title": "Create Verification Test Cases", + "labels": ["testing"], + "dependencies": [15], + "files": [ + "examples/simple-property/dsl.swift", + "examples/simple-property/expected.swift", + "examples/subscript-feature/dsl.swift", + "examples/subscript-feature/expected.swift", + "examples/defer-statement/dsl.swift", + "examples/defer-statement/expected.swift" + ], + "spec": "Create comprehensive test inputs and verify the tool works end-to-end including error handling.", + "acceptance": [ + "simple-property test input created", + "subscript-feature test input created", + "defer-statement test input created", + "Build test verification works", + "Generated code compilation test passes", + "Error handling tests pass (missing API key, invalid paths, missing files)" + ] + }, + { + "id": 17, + "phase": "Phase 7: Verification & Documentation", + "title": "Create Example Usage Documentation", + "labels": ["documentation"], + "dependencies": [14], + "files": ["Docs/skit-aist-usage.md"], + "spec": "Create comprehensive usage documentation with examples for basic and advanced usage scenarios.", + "acceptance": [ + "Basic example workflow documented", + "Advanced usage examples documented (custom model, verbose, API key flag)", + "Custom model configuration documented", + "Verbose output usage documented", + "API key configuration documented", + "Help command documented", + "Full workflow example provided" + ] + }, + { + "id": 18, + "phase": "Phase 7: Verification & Documentation", + "title": "Create Integration Tests", + "labels": ["testing", "integration"], + "dependencies": [16], + "files": ["Tests/AiSTKitTests/IntegrationTests.swift"], + "spec": "Create end-to-end integration test using a real missing feature to verify the entire pipeline.", + "acceptance": [ + "Integration test using real missing feature (e.g., subscript syntax)", + "Test verifies generated code validity", + "Test verifies code follows SyntaxKit patterns", + "Test verifies code compiles", + "Test verifies feature works as expected" + ] + } + ] +} diff --git a/Scripts/package.json b/Scripts/package.json new file mode 100644 index 00000000..c7c273b1 --- /dev/null +++ b/Scripts/package.json @@ -0,0 +1,10 @@ +{ + "name": "skit-issue-creator", + "version": "1.0.0", + "description": "Creates GitHub issues from skit-analyze-plan.md", + "type": "module", + "scripts": { + "create-issues": "node create-issues.js" + }, + "dependencies": {} +} From f0b4265212b5a5fee3098277969a674cb89206e5 Mon Sep 17 00:00:00 2001 From: leogdion Date: Thu, 11 Jun 2026 16:22:18 -0400 Subject: [PATCH 8/9] Switch skit-aist plan to ArgumentParser analyze subcommand on skit (#167) --- ...ation-1.0.0-documentation-configuration.md | 13333 ---------------- Docs/skit-analyze-plan.md | 559 +- IMPLEMENTATION_STATUS.md | 50 +- Scripts/ISSUE_CREATION_SUMMARY.md | 14 +- Scripts/issue-config.json | 277 +- Sources/ConfigKeyKit/Command.swift | 61 - .../ConfigKeyKit/CommandConfiguration.swift | 39 - Sources/ConfigKeyKit/CommandLineParser.swift | 74 - Sources/ConfigKeyKit/CommandRegistry.swift | 88 - .../ConfigKeyKit/CommandRegistryError.swift | 42 - Sources/ConfigKeyKit/ConfigKey+Bool.swift | 72 - Sources/ConfigKeyKit/ConfigKey+Debug.swift | 36 - Sources/ConfigKeyKit/ConfigKey.swift | 113 - Sources/ConfigKeyKit/ConfigKeySource.swift | 39 - Sources/ConfigKeyKit/ConfigurationKey.swift | 40 - .../ConfigKeyKit/ConfigurationParseable.swift | 54 - Sources/ConfigKeyKit/NamingStyle.swift | 38 - .../OptionalConfigKey+Debug.swift | 36 - Sources/ConfigKeyKit/OptionalConfigKey.swift | 103 - .../ConfigKeyKit/StandardNamingStyle.swift | 53 - 20 files changed, 506 insertions(+), 14615 deletions(-) delete mode 100644 .claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md delete mode 100644 Sources/ConfigKeyKit/Command.swift delete mode 100644 Sources/ConfigKeyKit/CommandConfiguration.swift delete mode 100644 Sources/ConfigKeyKit/CommandLineParser.swift delete mode 100644 Sources/ConfigKeyKit/CommandRegistry.swift delete mode 100644 Sources/ConfigKeyKit/CommandRegistryError.swift delete mode 100644 Sources/ConfigKeyKit/ConfigKey+Bool.swift delete mode 100644 Sources/ConfigKeyKit/ConfigKey+Debug.swift delete mode 100644 Sources/ConfigKeyKit/ConfigKey.swift delete mode 100644 Sources/ConfigKeyKit/ConfigKeySource.swift delete mode 100644 Sources/ConfigKeyKit/ConfigurationKey.swift delete mode 100644 Sources/ConfigKeyKit/ConfigurationParseable.swift delete mode 100644 Sources/ConfigKeyKit/NamingStyle.swift delete mode 100644 Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift delete mode 100644 Sources/ConfigKeyKit/OptionalConfigKey.swift delete mode 100644 Sources/ConfigKeyKit/StandardNamingStyle.swift diff --git a/.claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md b/.claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md deleted file mode 100644 index d3c4c9b8..00000000 --- a/.claude/https_-swiftpackageindex.com-apple-swift-configuration-1.0.0-documentation-configuration.md +++ /dev/null @@ -1,13333 +0,0 @@ - - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration - -Library - -# Configuration - -A Swift library for reading configuration in applications and libraries. - -## Overview - -Swift Configuration defines an abstraction between configuration _readers_ and _providers_. - -Applications and libraries _read_ configuration through a consistent API, while the actual _provider_ is set up once at the application’s entry point. - -For example, to read the timeout configuration value for an HTTP client, check out the following examples using different providers: - -# Environment variables: -HTTP_TIMEOUT=30 -let provider = EnvironmentVariablesProvider() -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -# Program invoked with: -program --http-timeout 30 -let provider = CommandLineArgumentsProvider() -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -{ -"http": { -"timeout": 30 -} -} - -filePath: "/etc/config.json" -) -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -{ -"http": { -"timeout": 30 -} -} - -filePath: "/etc/config.json" -) -// Omitted: Add `provider` to a ServiceGroup -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -http: -timeout: 30 - -filePath: "/etc/config.yaml" -) -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -http: -timeout: 30 - -filePath: "/etc/config.yaml" -) -// Omitted: Add `provider` to a ServiceGroup -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -/ -|-- run -|-- secrets -|-- http-timeout - -Contents of the file `/run/secrets/http-timeout`: `30`. - -let provider = try await DirectoryFilesProvider( -directoryPath: "/run/secrets" -) -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -// Environment variables consulted first, then JSON. -let primaryProvider = EnvironmentVariablesProvider() - -filePath: "/etc/config.json" -) -let config = ConfigReader(providers: [\ -primaryProvider,\ -secondaryProvider\ -]) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 -let provider = InMemoryProvider(values: [\ -"http.timeout": 30,\ -]) -let config = ConfigReader(provider: provider) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print(httpTimeout) // prints 30 - -For a selection of more detailed examples, read through Example use cases. - -For a video introduction, check out our talk on YouTube. - -These providers can be combined to form a hierarchy, for details check out Provider hierarchy. - -### Quick start - -Add the dependency to your `Package.swift`: - -.package(url: "https://github.com/apple/swift-configuration", from: "1.0.0") - -Add the library dependency to your target: - -.product(name: "Configuration", package: "swift-configuration") - -Import and use in your code: - -import Configuration - -let config = ConfigReader(provider: EnvironmentVariablesProvider()) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) -print("The HTTP timeout is: \(httpTimeout)") - -### Package traits - -This package offers additional integrations you can enable using package traits. To enable an additional trait on the package, update the package dependency: - -.package( -url: "https://github.com/apple/swift-configuration", -from: "1.0.0", -+ traits: [.defaults, "YAML"] -) - -Available traits: - -- **`JSON`** (default): Adds support for `JSONSnapshot`, which enables using `FileProvider` and `ReloadingFileProvider` with JSON files. - -- **`Logging`** (opt-in): Adds support for `AccessLogger`, a way to emit access events into a Swift Log `Logger`. - -- **`Reloading`** (opt-in): Adds support for `ReloadingFileProvider`, which provides auto-reloading capability for file-based configuration. - -- **`CommandLineArguments`** (opt-in): Adds support for `CommandLineArgumentsProvider` for parsing command line arguments. - -- **`YAML`** (opt-in): Adds support for `YAMLSnapshot`, which enables using `FileProvider` and `ReloadingFileProvider` with YAML files. - -### Supported platforms and minimum versions - -The library is supported on Apple platforms and Linux. - -| Component | macOS | Linux | iOS | tvOS | watchOS | visionOS | -| --- | --- | --- | --- | --- | --- | --- | -| Configuration | ✅ 15+ | ✅ | ✅ 18+ | ✅ 18+ | ✅ 11+ | ✅ 2+ | - -#### Three access patterns - -The library provides three distinct ways to read configuration values: - -- **Get**: Synchronously return the current value available locally, in memory: - -let timeout = config.int(forKey: "http.timeout", default: 60) - -- **Fetch**: Asynchronously get the most up-to-date value from disk or a remote server: - -let timeout = try await config.fetchInt(forKey: "http.timeout", default: 60) - -- **Watch**: Receive updates when a configuration value changes: - -try await config.watchInt(forKey: "http.timeout", default: 60) { updates in -for try await timeout in updates { -print("HTTP timeout updated to: \(timeout)") -} -} - -For detailed guidance on when to use each access pattern, see Choosing the access pattern. Within each of the access patterns, the library offers different reader methods that reflect your needs of optional, default, and required configuration parameters. To understand the choices available, see Choosing reader methods. - -#### Providers - -The library includes comprehensive built-in provider support: - -- Environment variables: `EnvironmentVariablesProvider` - -- Command-line arguments: `CommandLineArgumentsProvider` - -- JSON file: `FileProvider` and `ReloadingFileProvider` with `JSONSnapshot` - -- YAML file: `FileProvider` and `ReloadingFileProvider` with `YAMLSnapshot` - -- Directory of files: `DirectoryFilesProvider` - -- In-memory: `InMemoryProvider` and `MutableInMemoryProvider` - -- Key transforming: `KeyMappingProvider` - -You can also implement a custom `ConfigProvider`. - -#### Provider hierarchy - -In addition to using providers individually, you can create fallback behavior using an array of providers. The first provider that returns a non-nil value wins. - -The following example shows a provider hierarchy where environment variables take precedence over command line arguments, a JSON file, and in-memory defaults: - -// Create a hierarchy of providers with fallback behavior. -let config = ConfigReader(providers: [\ -// First, check environment variables.\ -EnvironmentVariablesProvider(),\ -// Then, check command-line options.\ -CommandLineArgumentsProvider(),\ -// Then, check a JSON config file.\ - -// Finally, fall \ -]) - -// Uses the first provider that has a value for "http.timeout". -let timeout = config.int(forKey: "http.timeout", default: 15) - -#### Hot reloading - -Long-running services can periodically reload configuration with `ReloadingFileProvider`: - -// Omitted: add provider to a ServiceGroup -let config = ConfigReader(provider: provider) - -Read Using reloading providers for details on how to receive updates as configuration changes. - -#### Namespacing and scoped readers - -The built-in namespacing of `ConfigKey` interprets `"http.timeout"` as an array of two components: `"http"` and `"timeout"`. The following example uses `scoped(to:)` to create a namespaced reader with the key `"http"`, to allow reads to use the shorter key `"timeout"`: - -Consider the following JSON configuration: - -{ -"http": { -"timeout": 60 -} -} -// Create the root reader. -let config = ConfigReader(provider: provider) - -// Create a scoped reader for HTTP settings. -let httpConfig = config.scoped(to: "http") - -// Now you can access values with shorter keys. -// Equivalent to reading "http.timeout" on the root reader. -let timeout = httpConfig.int(forKey: "timeout") - -#### Debugging and troubleshooting - -Debugging with `AccessReporter` makes it possible to log all accesses to a config reader: - -let logger = Logger(label: "config") -let config = ConfigReader( -provider: provider, -accessReporter: AccessLogger(logger: logger) -) -// Now all configuration access is logged, with secret values redacted - -You can also add the following environment variable, and emit log accesses into a file without any code changes: - -CONFIG_ACCESS_LOG_FILE=/var/log/myapp/config-access.log - -and then read the file: - -tail -f /var/log/myapp/config-access.log - -Check out the built-in `AccessLogger`, `FileAccessLogger`, and Troubleshooting and access reporting. - -#### Secrets handling - -The library provides built-in support for handling sensitive configuration values securely: - -// Mark sensitive values as secrets to prevent them from appearing in logs -let privateKey = try snapshot.requiredString(forKey: "mtls.privateKey", isSecret: true) -let optionalAPIToken = config.string(forKey: "api.token", isSecret: true) - -When values are marked as secrets, they are automatically redacted from access logs and debugging output. Read Handling secrets correctly for guidance on best practices for secrets management. - -#### Consistent snapshots - -Retrieve related values from a consistent snapshot using `ConfigSnapshotReader`, which you get by calling `snapshot()`. - -This ensures that multiple values are read from a single snapshot inside each provider, even when using providers that update their internal values. For example by downloading new data periodically: - -let config = /* a reader with one or more providers that change values over time */ -let snapshot = config.snapshot() -let certificate = try snapshot.requiredString(forKey: "mtls.certificate") -let privateKey = try snapshot.requiredString(forKey: "mtls.privateKey", isSecret: true) -// `certificate` and `privateKey` are guaranteed to come from the same snapshot in the provider - -#### Extensible ecosystem - -Any package can implement a `ConfigProvider`, making the ecosystem extensible for custom configuration sources. - -## Topics - -### Essentials - -Configuring applications - -Provide flexible and consistent configuration for your application. - -Configuring libraries - -Provide a consistent and flexible way to configure your library. - -Example use cases - -Review common use cases with ready-to-copy code samples. - -Adopting best practices - -Follow these principles to make your code easily configurable and composable with other libraries. - -### Readers and providers - -`struct ConfigReader` - -A type that provides read-only access to configuration values from underlying providers. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`struct ConfigSnapshotReader` - -A container type for reading config values from snapshots. - -Choosing the access pattern - -Learn how to select the right method for reading configuration values based on your needs. - -Choosing reader methods - -Choose between optional, default, and required variants of configuration methods. - -Handling secrets correctly - -Protect sensitive configuration values from accidental disclosure in logs and debug output. - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -### Configuration keys - -`struct ConfigKey` - -A configuration key representing a relative path to a configuration value. - -`struct AbsoluteConfigKey` - -A configuration key that represents an absolute path to a configuration value. - -`enum ConfigContextValue` - -A value that can be stored in a configuration context. - -### Troubleshooting and access reporting - -Troubleshooting and access reporting - -Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. - -`protocol AccessReporter` - -A type that receives and processes configuration access events. - -`class AccessLogger` - -An access reporter that logs configuration access events using the Swift Log API. - -`class FileAccessLogger` - -An access reporter that writes configuration access events to a file. - -`struct AccessEvent` - -An event that captures information about accessing a configuration value. - -`struct BroadcastingAccessReporter` - -An access reporter that forwards events to multiple other reporters. - -### Value conversion - -`protocol ExpressibleByConfigString` - -A protocol for types that can be initialized from configuration string values. - -`protocol ConfigBytesFromStringDecoder` - -A protocol for decoding string configuration values into byte arrays. - -`struct ConfigBytesFromBase64StringDecoder` - -A decoder that converts base64-encoded strings into byte arrays. - -`struct ConfigBytesFromHexStringDecoder` - -A decoder that converts hexadecimal-encoded strings into byte arrays. - -### Contributing - -Developing Swift Configuration - -Learn about tools and conventions used to develop the Swift Configuration package. - -Collaborate on API changes to Swift Configuration by writing a proposal. - -### Extended Modules - -Foundation - -SystemPackage - -- Configuration -- Overview -- Quick start -- Package traits -- Supported platforms and minimum versions -- Key features -- Topics - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/handling-secrets-correctly - -- Configuration -- Handling secrets correctly - -Article - -# Handling secrets correctly - -Protect sensitive configuration values from accidental disclosure in logs and debug output. - -## Overview - -Swift Configuration provides built-in support for marking sensitive values as secrets. Secret values are automatically redacted by access reporters to prevent accidental disclosure of API keys, passwords, and other sensitive information. - -### Marking values as secret when reading - -Use the `isSecret` parameter on any configuration reader method to mark a value as secret: - -let config = ConfigReader(provider: provider) - -// Mark sensitive values as secret -let apiKey = try config.requiredString( -forKey: "api.key", -isSecret: true -) -let dbPassword = config.string( -forKey: "database.password", -isSecret: true -) - -// Regular values don't need the parameter -let serverPort = try config.requiredInt(forKey: "server.port") -let logLevel = config.string( -forKey: "log.level", -default: "info" -) - -This works with all access patterns and method variants: - -// Works with fetch and watch too -let latestKey = try await config.fetchRequiredString( -forKey: "api.key", -isSecret: true -) - -try await config.watchString( -forKey: "api.key", -isSecret: true -) { updates in -for await key in updates { -// Handle secret key updates -} -} - -### Provider-level secret specification - -Use `SecretsSpecifier` to automatically mark values as secret based on keys or content when creating providers: - -#### Mark all values as secret - -The following example marks all configuration read by the `DirectoryFilesProvider` as secret: - -let provider = DirectoryFilesProvider( -directoryPath: "/run/secrets", -secretsSpecifier: .all -) - -#### Mark specific keys as secret - -The following example marks three specific keys from a provider as secret: - -let provider = EnvironmentVariablesProvider( -secretsSpecifier: .specific(["API_KEY", "DATABASE_PASSWORD", "JWT_SECRET"]) -) - -#### Dynamic secret detection - -The following example marks keys as secret based on the closure you provide. In this case, keys that contain `password`, `secret`, or `token` are all marked as secret: - -filePath: "/etc/config.json", -secretsSpecifier: .dynamic { key, value in -key.lowercased().contains("password") || -key.lowercased().contains("secret") || -key.lowercased().contains("token") -} -) - -#### No secret values - -The following example asserts that none of the values returned from the provider are considered secret: - -filePath: "/etc/config.json", -secretsSpecifier: .none -) - -### For provider implementors - -When implementing a custom `ConfigProvider`, use the `ConfigValue` type’s `isSecret` property: - -// Create a secret value -let secretValue = ConfigValue("sensitive-data", isSecret: true) - -// Create a regular value -let regularValue = ConfigValue("public-data", isSecret: false) - -Set the `isSecret` property to `true` when your provider knows the values are read from a secrets store and must not be logged. - -### How secret values are protected - -Secret values are automatically handled by: - -- **`AccessLogger`** and **`FileAccessLogger`**: Redact secret values in logs. - -print(provider) - -### Best practices - -1. **Mark all sensitive data as secret**: API keys, passwords, tokens, private keys, connection strings. - -2. **Use provider-level specification** when you know which keys are always secret. - -3. **Use reader-level marking** for context-specific secrets or when the same key might be secret in some contexts but not others. - -4. **Be conservative**: When in doubt, mark values as secret. It’s safer than accidentally leaking sensitive data. - -For additional guidance on configuration security and overall best practices, see Adopting best practices. To debug issues with secret redaction in access logs, check out Troubleshooting and access reporting. When selecting between required, optional, and default method variants for secret values, refer to Choosing reader methods. - -## See Also - -### Readers and providers - -`struct ConfigReader` - -A type that provides read-only access to configuration values from underlying providers. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`struct ConfigSnapshotReader` - -A container type for reading config values from snapshots. - -Choosing the access pattern - -Learn how to select the right method for reading configuration values based on your needs. - -Choosing reader methods - -Choose between optional, default, and required variants of configuration methods. - -- Handling secrets correctly -- Overview -- Marking values as secret when reading -- Provider-level secret specification -- For provider implementors -- How secret values are protected -- Best practices -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot - -- Configuration -- YAMLSnapshot - -Class - -# YAMLSnapshot - -A snapshot of configuration values parsed from YAML data. - -final class YAMLSnapshot - -YAMLSnapshot.swift - -## Mentioned in - -Using reloading providers - -## Overview - -This class represents a point-in-time view of configuration values. It handles the conversion from YAML types to configuration value types. - -## Usage - -Use with `FileProvider` or `ReloadingFileProvider`: - -let config = ConfigReader(provider: provider) - -## Topics - -### Creating a YAML snapshot - -`convenience init(data: RawSpan, providerName: String, parsingOptions: YAMLSnapshot.ParsingOptions) throws` - -`struct ParsingOptions` - -Custom input configuration for YAML snapshot creation. - -### Snapshot configuration - -`protocol FileConfigSnapshot` - -A protocol for configuration snapshots created from file data. - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -### Instance Properties - -`let providerName: String` - -The name of the provider that created this snapshot. - -## Relationships - -### Conforms To - -- `ConfigSnapshot` -- `FileConfigSnapshot` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- YAMLSnapshot -- Mentioned in -- Overview -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting - -Library - -# ConfigurationTesting - -A set of testing utilities for Swift Configuration adopters. - -## Overview - -This testing library adds a Swift Testing-based `ConfigProvider` compatibility suite, recommended for implementors of custom configuration providers. - -## Topics - -### Structures - -`struct ProviderCompatTest` - -A comprehensive test suite for validating `ConfigProvider` implementations. - -- ConfigurationTesting -- Overview -- Topics - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accesslogger - -- Configuration -- AccessLogger - -Class - -# AccessLogger - -An access reporter that logs configuration access events using the Swift Log API. - -final class AccessLogger - -AccessLogger.swift - -## Mentioned in - -Handling secrets correctly - -Troubleshooting and access reporting - -Configuring libraries - -## Overview - -This reporter integrates with the Swift Log library to provide structured logging of configuration accesses. Each configuration access generates a log entry with detailed metadata about the operation, making it easy to track configuration usage and debug issues. - -## Package traits - -This type is guarded by the `Logging` package trait. - -## Usage - -Create an access logger and pass it to your configuration reader: - -import Logging - -let logger = Logger(label: "config.access") -let accessLogger = AccessLogger(logger: logger, level: .info) -let config = ConfigReader( -provider: EnvironmentVariablesProvider(), -accessReporter: accessLogger -) - -## Log format - -Each access event generates a structured log entry with metadata including: - -- `kind`: The type of access operation (get, fetch, watch). - -- `key`: The configuration key that was accessed. - -- `location`: The source code location where the access occurred. - -- `value`: The resolved configuration value (redacted for secrets). - -- `counter`: An incrementing counter for tracking access frequency. - -- Provider-specific information for each provider in the hierarchy. - -## Topics - -### Creating an access logger - -`init(logger: Logger, level: Logger.Level, message: Logger.Message)` - -Creates a new access logger that reports configuration access events. - -## Relationships - -### Conforms To - -- `AccessReporter` -- `Swift.Copyable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Troubleshooting and access reporting - -Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. - -`protocol AccessReporter` - -A type that receives and processes configuration access events. - -`class FileAccessLogger` - -An access reporter that writes configuration access events to a file. - -`struct AccessEvent` - -An event that captures information about accessing a configuration value. - -`struct BroadcastingAccessReporter` - -An access reporter that forwards events to multiple other reporters. - -- AccessLogger -- Mentioned in -- Overview -- Package traits -- Usage -- Log format -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider - -- Configuration -- ReloadingFileProvider - -Class - -# ReloadingFileProvider - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -ReloadingFileProvider.swift - -## Mentioned in - -Using reloading providers - -Choosing the access pattern - -Troubleshooting and access reporting - -## Overview - -`ReloadingFileProvider` is a generic file-based configuration provider that monitors a configuration file for changes and automatically reloads the data when the file is modified. This provider works with different file formats by using different snapshot types that conform to `FileConfigSnapshot`. - -## Usage - -Create a reloading provider by specifying the snapshot type and file path: - -// Using with a JSON snapshot and a custom poll interval - -filePath: "/etc/config.json", -pollInterval: .seconds(30) -) - -// Using with a YAML snapshot - -filePath: "/etc/config.yaml" -) - -## Service integration - -This provider implements the `Service` protocol and must be run within a `ServiceGroup` to enable automatic reloading: - -let serviceGroup = ServiceGroup(services: [provider], logger: logger) -try await serviceGroup.run() - -The provider monitors the file by polling at the specified interval (default: 15 seconds) and notifies any active watchers when changes are detected. - -## Configuration from a reader - -You can also initialize the provider using a configuration reader: - -let envConfig = ConfigReader(provider: EnvironmentVariablesProvider()) - -This expects a `filePath` key in the configuration that specifies the path to the file. For a full list of configuration keys, check out `init(snapshotType:parsingOptions:config:)`. - -## File monitoring - -The provider detects changes by monitoring both file timestamps and symlink target changes. When a change is detected, it reloads the file and notifies all active watchers of the updated configuration values. - -## Topics - -### Creating a reloading file provider - -`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool, pollInterval: Duration, logger: Logger, metrics: any MetricsFactory) async throws` - -Creates a reloading file provider that monitors the specified file path. - -`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader, logger: Logger, metrics: any MetricsFactory) async throws` - -Creates a reloading file provider using configuration from a reader. - -### Service lifecycle - -`func run() async throws` - -### Monitoring file changes - -`protocol FileConfigSnapshot` - -A protocol for configuration snapshots created from file data. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -### Instance Properties - -`let providerName: String` - -The human-readable name of the provider. - -## Relationships - -### Conforms To - -- `ConfigProvider` -Conforms when `Snapshot` conforms to `FileConfigSnapshot`. - -- `ServiceLifecycle.Service` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- ReloadingFileProvider -- Mentioned in -- Overview -- Usage -- Service integration -- Configuration from a reader -- File monitoring -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot - -- Configuration -- JSONSnapshot - -Structure - -# JSONSnapshot - -A snapshot of configuration values parsed from JSON data. - -struct JSONSnapshot - -JSONSnapshot.swift - -## Mentioned in - -Example use cases - -Using reloading providers - -## Overview - -This structure represents a point-in-time view of configuration values. It handles the conversion from JSON types to configuration value types. - -## Usage - -Use with `FileProvider` or `ReloadingFileProvider`: - -let config = ConfigReader(provider: provider) - -## Topics - -### Creating a JSON snapshot - -`init(data: RawSpan, providerName: String, parsingOptions: JSONSnapshot.ParsingOptions) throws` - -`struct ParsingOptions` - -Parsing options for JSON snapshot creation. - -### Snapshot configuration - -`protocol FileConfigSnapshot` - -A protocol for configuration snapshots created from file data. - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -### Instance Properties - -`let providerName: String` - -The name of the provider that created this snapshot. - -## Relationships - -### Conforms To - -- `ConfigSnapshot` -- `FileConfigSnapshot` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- JSONSnapshot -- Mentioned in -- Overview -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider - -- Configuration -- FileProvider - -Structure - -# FileProvider - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -FileProvider.swift - -## Mentioned in - -Example use cases - -Troubleshooting and access reporting - -## Overview - -`FileProvider` is a generic file-based configuration provider that works with different file formats by using different snapshot types that conform to `FileConfigSnapshot`. This allows for a unified interface for reading JSON, YAML, or other structured configuration files. - -## Usage - -Create a provider by specifying the snapshot type and file path: - -// Using with a JSON snapshot - -filePath: "/etc/config.json" -) - -// Using with a YAML snapshot - -filePath: "/etc/config.yaml" -) - -The provider reads the file once during initialization and creates an immutable snapshot of the configuration values. For auto-reloading behavior, use `ReloadingFileProvider`. - -## Configuration from a reader - -You can also initialize the provider using a configuration reader that specifies the file path through environment variables or other configuration sources: - -let envConfig = ConfigReader(provider: EnvironmentVariablesProvider()) - -This expects a `filePath` key in the configuration that specifies the path to the file. For a full list of configuration keys, check out `init(snapshotType:parsingOptions:config:)`. - -## Topics - -### Creating a file provider - -`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool) async throws` - -Creates a file provider that reads from the specified file path. - -`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader) async throws` - -Creates a file provider using a file path from a configuration reader. - -### Reading configuration files - -`protocol FileConfigSnapshot` - -A protocol for configuration snapshots created from file data. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -## Relationships - -### Conforms To - -- `ConfigProvider` -Conforms when `Snapshot` conforms to `FileConfigSnapshot`. - -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- FileProvider -- Mentioned in -- Overview -- Usage -- Configuration from a reader -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/example-use-cases - -- Configuration -- Example use cases - -Article - -# Example use cases - -Review common use cases with ready-to-copy code samples. - -## Overview - -For complete working examples with step-by-step instructions, see the Examples directory in the repository. - -### Reading from environment variables - -Use `EnvironmentVariablesProvider` to read configuration values from environment variables where your app launches. The following example creates a `ConfigReader` with an environment variable provider, and reads the key `server.port`, providing a default value of `8080`: - -import Configuration - -let config = ConfigReader(provider: EnvironmentVariablesProvider()) -let port = config.int(forKey: "server.port", default: 8080) - -The default environment key encoder uses an underscore to separate key components, making the environment variable name above `SERVER_PORT`. - -### Reading from a JSON configuration file - -You can store multiple configuration values together in a JSON file and read them from the fileystem using `FileProvider` with `JSONSnapshot`. The following example creates a `ConfigReader` for a JSON file at the path `/etc/config.json`, and reads a url and port number collected as properties of the `database` JSON object: - -let config = ConfigReader( - -) - -// Access nested values using dot notation. -let databaseURL = config.string(forKey: "database.url", default: "localhost") -let databasePort = config.int(forKey: "database.port", default: 5432) - -The matching JSON for this configuration might look like: - -{ -"database": { -"url": "localhost", -"port": 5432 -} -} - -### Reading from a directory of secret files - -Use the `DirectoryFilesProvider` to read multiple values collected together in a directory on the fileystem, each in a separate file. The default directory key encoder uses a hyphen in the filename to separate key components. The following example uses the directory `/run/secrets` as a base, and reads the file `database-password` as the key `database.password`: - -// Common pattern for secrets downloaded by an init container. -let config = ConfigReader( -provider: try await DirectoryFilesProvider( -directoryPath: "/run/secrets" -) -) - -// Reads the file `/run/secrets/database-password` -let dbPassword = config.string(forKey: "database.password") - -This pattern is useful for reading secrets that your infrastructure makes available on the file system, such as Kubernetes secrets mounted into a container’s filesystem. - -### Handling optional configuration files - -File-based providers support an `allowMissing` parameter to control whether missing files should throw an error or be treated as empty configuration. This is useful when configuration files are optional. - -When `allowMissing` is `false` (the default), missing files throw an error: - -// This will throw an error if config.json doesn't exist -let config = ConfigReader( - -filePath: "/etc/config.json", -allowMissing: false // This is the default -) -) - -When `allowMissing` is `true`, missing files are treated as empty configuration: - -// This won't throw if config.json is missing - treats it as empty -let config = ConfigReader( - -filePath: "/etc/config.json", -allowMissing: true -) -) - -// Returns the default value if the file is missing -let port = config.int(forKey: "server.port", default: 8080) - -The same applies to other file-based providers: - -// Optional secrets directory -let secretsConfig = ConfigReader( -provider: try await DirectoryFilesProvider( -directoryPath: "/run/secrets", -allowMissing: true -) -) - -// Optional environment file -let envConfig = ConfigReader( -provider: try await EnvironmentVariablesProvider( -environmentFilePath: "/etc/app.env", -allowMissing: true -) -) - -// Optional reloading configuration -let reloadingConfig = ConfigReader( - -filePath: "/etc/dynamic-config.yaml", -allowMissing: true -) -) - -### Setting up a fallback hierarchy - -Use multiple providers together to provide a configuration hierarchy that can override values at different levels. The following example uses both an environment variable provider and a JSON provider together, with values from environment variables overriding values from the JSON file. In this example, the defaults are provided using an `InMemoryProvider`, which are only read if the environment variable or the JSON key don’t exist: - -let config = ConfigReader(providers: [\ -// First check environment variables.\ -EnvironmentVariablesProvider(),\ -// Then check the config file.\ - -// Finally, use hardcoded defaults.\ -InMemoryProvider(values: [\ -"app.name": "MyApp",\ -"server.port": 8080,\ -"logging.level": "info"\ -])\ -]) - -### Fetching a value from a remote source - -You can host dynamic configuration that your app can retrieve remotely and use either the “fetch” or “watch” access pattern. The following example uses the “fetch” access pattern to asynchronously retrieve a configuration from the remote provider: - -let myRemoteProvider = MyRemoteProvider(...) -let config = ConfigReader(provider: myRemoteProvider) - -// Makes a network call to retrieve the up-to-date value. -let samplingRatio = try await config.fetchDouble(forKey: "sampling.ratio") - -### Watching for configuration changes - -You can periodically update configuration values using a reloading provider. The following example reloads a YAML file from the filesystem every 30 seconds, and illustrates using `watchInt(forKey:isSecret:fileID:line:updatesHandler:)` to provide an async sequence of updates that you can apply. - -import Configuration -import ServiceLifecycle - -// Create a reloading YAML provider - -filePath: "/etc/app-config.yaml", -pollInterval: .seconds(30) -) -// Omitted: add `provider` to the ServiceGroup. - -let config = ConfigReader(provider: provider) - -// Watch for timeout changes and update HTTP client configuration. -// Needs to run in a separate task from the provider. -try await config.watchInt(forKey: "http.requestTimeout", default: 30) { updates in -for await timeout in updates { -print("HTTP request timeout updated: \(timeout)s") -// Update HTTP client timeout configuration in real-time -} -} - -For details on reloading providers and ServiceLifecycle integration, see Using reloading providers. - -### Prefixing configuration keys - -In most cases, the configuration key provided by the reader can be directly used by the provided, for example `http.timeout` used as the environment variable name `HTTP_TIMEOUT`. - -Sometimes you might need to transform the incoming keys in some way, before they get delivered to the provider. A common example is prefixing each key with a constant prefix, for example `myapp`, turning the key `http.timeout` to `myapp.http.timeout`. - -You can use `KeyMappingProvider` and related extensions on `ConfigProvider` to achieve that. - -The following example uses the key mapping provider to adjust an environment variable provider to look for keys with the prefix `myapp`: - -// Create a base provider for environment variables -let envProvider = EnvironmentVariablesProvider() - -// Wrap it with a key mapping provider to automatically prepend "myapp." to all keys -let prefixedProvider = envProvider.prefixKeys(with: "myapp") - -let config = ConfigReader(provider: prefixedProvider) - -// This reads from the "MYAPP_DATABASE_URL" environment variable. -let databaseURL = config.string(forKey: "database.url", default: "localhost") - -For more configuration guidance, see Adopting best practices. To understand different reader method variants, check out Choosing reader methods. - -## See Also - -### Essentials - -Configuring applications - -Provide flexible and consistent configuration for your application. - -Configuring libraries - -Provide a consistent and flexible way to configure your library. - -Adopting best practices - -Follow these principles to make your code easily configurable and composable with other libraries. - -- Example use cases -- Overview -- Reading from environment variables -- Reading from a JSON configuration file -- Reading from a directory of secret files -- Handling optional configuration files -- Setting up a fallback hierarchy -- Fetching a value from a remote source -- Watching for configuration changes -- Prefixing configuration keys -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/scoped(to:) - -#app-main) - -- Configuration -- ConfigReader -- scoped(to:) - -Instance Method - -# scoped(to:) - -Returns a scoped config reader with the specified key appended to the current prefix. - -ConfigReader.swift - -## Parameters - -`configKey` - -The key components to append to the current key prefix. - -## Return Value - -A config reader for accessing values within the specified scope. - -## Discussion - -let httpConfig = config.scoped(to: ConfigKey(["http", "client"])) -let timeout = httpConfig.int(forKey: "timeout", default: 30) // Reads "http.client.timeout" - -- scoped(to:) -- Parameters -- Return Value -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider - -- Configuration -- EnvironmentVariablesProvider - -Structure - -# EnvironmentVariablesProvider - -A configuration provider that sources values from environment variables. - -struct EnvironmentVariablesProvider - -EnvironmentVariablesProvider.swift - -## Mentioned in - -Troubleshooting and access reporting - -Configuring applications - -Example use cases - -## Overview - -This provider reads configuration values from environment variables, supporting both the current process environment and `.env` files. It automatically converts hierarchical configuration keys into standard environment variable naming conventions and handles type conversion for all supported configuration value types. - -## Key transformation - -Configuration keys are transformed into environment variable names using these rules: - -- Components are joined with underscores - -- All characters are converted to uppercase - -- CamelCase is detected and word boundaries are marked with underscores - -- Non-alphanumeric characters are replaced with underscores - -For example: `http.serverTimeout` becomes `HTTP_SERVER_TIMEOUT` - -## Supported data types - -The provider supports all standard configuration types: - -- Strings, integers, doubles, and booleans - -- Arrays of strings, integers, doubles, and booleans (comma-separated by default) - -- Byte arrays (base64-encoded by default) - -- Arrays of byte chunks - -## Secret handling - -Environment variables can be marked as secrets using a `SecretsSpecifier`. Secret values are automatically redacted in debug output and logging. - -## Usage - -### Reading environment variables in the current process - -// Assuming the environment contains the following variables: -// HTTP_CLIENT_USER_AGENT=Config/1.0 (Test) -// HTTP_CLIENT_TIMEOUT=15.0 -// HTTP_SECRET=s3cret -// HTTP_VERSION=2 -// ENABLED=true - -let provider = EnvironmentVariablesProvider( -secretsSpecifier: .specific(["HTTP_SECRET"]) -) -// Prints all values, redacts "HTTP_SECRET" automatically. -print(provider) -let config = ConfigReader(provider: provider) -let isEnabled = config.bool(forKey: "enabled", default: false) -let userAgent = config.string(forKey: "http.client.user-agent", default: "unspecified") -// ... - -### Reading environment variables from a \`.env\`-style file - -// Assuming the local file system has a file called `.env` in the current working directory -// with the following contents: -// -// HTTP_CLIENT_USER_AGENT=Config/1.0 (Test) -// HTTP_CLIENT_TIMEOUT=15.0 -// HTTP_SECRET=s3cret -// HTTP_VERSION=2 -// ENABLED=true - -let provider = try await EnvironmentVariablesProvider( -environmentFilePath: ".env", -secretsSpecifier: .specific(["HTTP_SECRET"]) -) -// Prints all values, redacts "HTTP_SECRET" automatically. -print(provider) -let config = ConfigReader(provider: provider) -let isEnabled = config.bool(forKey: "enabled", default: false) -let userAgent = config.string(forKey: "http.client.user-agent", default: "unspecified") -// ... - -### Config context - -The environment variables provider ignores the context passed in `context`. - -## Topics - -### Creating an environment variable provider - -Creates a new provider that reads from the current process environment. - -Creates a new provider from a custom dictionary of environment variables. - -Creates a new provider that reads from an environment file. - -### Inspecting an environment variable provider - -Returns the raw string value for a specific environment variable name. - -## Relationships - -### Conforms To - -- `ConfigProvider` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- EnvironmentVariablesProvider -- Mentioned in -- Overview -- Key transformation -- Supported data types -- Secret handling -- Usage -- Reading environment variables in the current process -- Reading environment variables from a \`.env\`-style file -- Config context -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey - -- Configuration -- ConfigKey - -Structure - -# ConfigKey - -A configuration key representing a relative path to a configuration value. - -struct ConfigKey - -ConfigKey.swift - -## Overview - -Configuration keys consist of hierarchical string components forming paths similar to file system paths or JSON object keys. For example, `["http", "timeout"]` represents the `timeout` value nested under `http`. - -Keys support additional context information that providers can use to refine lookups or provide specialized behavior. - -## Usage - -Create keys using string literals, arrays, or the initializers: - -let key1: ConfigKey = "database.connection.timeout" -let key2 = ConfigKey(["api", "endpoints", "primary"]) -let key3 = ConfigKey("server.port", context: ["environment": .string("production")]) - -## Topics - -### Creating a configuration key - -[`init(String, context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-6vten) - -Creates a new configuration key. - -[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-9ifez) - -### Inspecting a configuration key - -[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/components) - -The hierarchical components that make up this configuration key. - -[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/context) - -Additional context information for this configuration key. - -## Relationships - -### Conforms To - -- `Swift.Comparable` -- `Swift.Copyable` -- `Swift.CustomStringConvertible` -- `Swift.Equatable` -- `Swift.ExpressibleByArrayLiteral` -- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` -- `Swift.ExpressibleByStringLiteral` -- `Swift.ExpressibleByUnicodeScalarLiteral` -- `Swift.Hashable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Configuration keys - -`struct AbsoluteConfigKey` - -A configuration key that represents an absolute path to a configuration value. - -`enum ConfigContextValue` - -A value that can be stored in a configuration context. - -- ConfigKey -- Overview -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider - -- Configuration -- CommandLineArgumentsProvider - -Structure - -# CommandLineArgumentsProvider - -A configuration provider that sources values from command-line arguments. - -struct CommandLineArgumentsProvider - -CommandLineArgumentsProvider.swift - -## Overview - -Reads configuration values from CLI arguments with type conversion and secrets handling. Keys are encoded to CLI flags at lookup time. - -## Package traits - -This type is guarded by the `CommandLineArgumentsSupport` package trait. - -## Key formats - -- `--key value` \- A key-value pair with separate arguments. - -- `--key=value` \- A key-value pair with an equals sign. - -- `--flag` \- A Boolean flag, treated as `true`. - -- `--key val1 val2` \- Multiple values (arrays). - -Configuration keys are transformed to CLI flags: `["http", "serverTimeout"]` → `--http-server-timeout`. - -## Array handling - -Arrays can be specified in multiple ways: - -- **Space-separated**: `--tags swift configuration cli` - -- **Repeated flags**: `--tags swift --tags configuration --tags cli` - -- **Comma-separated**: `--tags swift,configuration,cli` - -- **Mixed**: `--tags swift,configuration --tags cli` - -All formats produce the same result when accessed as an array type. - -## Usage - -// CLI: program --debug --host localhost --ports 8080 8443 -let provider = CommandLineArgumentsProvider() -let config = ConfigReader(provider: provider) - -let isDebug = config.bool(forKey: "debug", default: false) // true -let host = config.string(forKey: "host", default: "0.0.0.0") // "localhost" -let ports = config.intArray(forKey: "ports", default: []) // [8080, 8443] - -### With secrets - -let provider = CommandLineArgumentsProvider( -secretsSpecifier: .specific(["--api-key"]) -) - -### Custom arguments - -let provider = CommandLineArgumentsProvider( -arguments: ["program", "--verbose", "--timeout", "30"], -secretsSpecifier: .dynamic { key, _ in key.contains("--secret") } -) - -## Topics - -### Creating a command line arguments provider - -Creates a new CLI provider with the provided arguments. - -## Relationships - -### Conforms To - -- `ConfigProvider` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- CommandLineArgumentsProvider -- Overview -- Package traits -- Key formats -- Array handling -- Usage -- With secrets -- Custom arguments -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/choosing-reader-methods - -- Configuration -- Choosing reader methods - -Article - -# Choosing reader methods - -Choose between optional, default, and required variants of configuration methods. - -## Overview - -For every configuration access pattern (get, fetch, watch) and data type, Swift Configuration provides three method variants that handle missing or invalid values differently: - -- **Optional variant**: Returns `nil` when a value is missing or cannot be converted. - -- **Default variant**: Returns a fallback value when a value is missing or cannot be converted. - -- **Required variant**: Throws an error when a value is missing or cannot be converted. - -Understanding these variants helps you write robust configuration code that handles missing values appropriately for your use case. - -### Optional variants - -Optional variants return `nil` when a configuration value is missing or cannot be converted to the expected type. These methods have the simplest signatures and are ideal when configuration values are truly optional. - -let config = ConfigReader(provider: EnvironmentVariablesProvider()) - -// Optional get -let timeout: Int? = config.int(forKey: "http.timeout") -let apiUrl: String? = config.string(forKey: "api.url") - -// Optional fetch -let latestTimeout: Int? = try await config.fetchInt(forKey: "http.timeout") - -// Optional watch -try await config.watchInt(forKey: "http.timeout") { updates in -for await timeout in updates { -if let timeout = timeout { -print("Timeout is set to: \(timeout)") -} else { -print("No timeout configured") -} -} -} - -#### When to use - -Use optional variants when: - -- **Truly optional features**: The configuration controls optional functionality. - -- **Gradual rollouts**: New configuration that might not be present everywhere. - -- **Conditional behavior**: Your code can operate differently based on presence or absence. - -- **Debugging and diagnostics**: You want to detect missing configuration explicitly. - -#### Error handling behavior - -Optional variants handle errors gracefully by returning `nil`: - -- Missing values return `nil`. - -- Type conversion errors return `nil`. - -- Provider errors return `nil` (except for fetch variants, which always propagate provider errors). - -// These all return nil instead of throwing -let missingPort = config.int(forKey: "nonexistent.port") // nil -let invalidPort = config.int(forKey: "invalid.port.value") // nil (if value can't convert to Int) -let failingPort = config.int(forKey: "provider.error.key") // nil (if provider fails) - -// Fetch variants still throw provider errors -do { -let port = try await config.fetchInt(forKey: "network.error") // Throws provider error -} catch { -// Handle network or provider errors -} - -### Default variants - -Default variants return a specified fallback value when a configuration value is missing or cannot be converted. These provide guaranteed non-optional results while handling missing configuration gracefully. - -// Default get -let timeout = config.int(forKey: "http.timeout", default: 30) -let retryCount = config.int(forKey: "network.retries", default: 3) - -// Default fetch -let latestTimeout = try await config.fetchInt(forKey: "http.timeout", default: 30) - -// Default watch -try await config.watchInt(forKey: "http.timeout", default: 30) { updates in -for await timeout in updates { -print("Using timeout: \(timeout)") // Always has a value -connectionManager.setTimeout(timeout) -} -} - -#### When to use - -Use default variants when: - -- **Sensible defaults exist**: You have reasonable fallback values for missing configuration. - -- **Simplified code flow**: You want to avoid optional handling in business logic. - -- **Required functionality**: The feature needs a value to operate, but can use defaults. - -- **Configuration evolution**: New settings that should work with older deployments. - -#### Choosing good defaults - -Consider these principles when choosing default values: - -// Safe defaults that won't cause issues -let timeout = config.int(forKey: "http.timeout", default: 30) // Reasonable timeout -let maxRetries = config.int(forKey: "retries.max", default: 3) // Conservative retry count -let cacheSize = config.int(forKey: "cache.size", default: 1000) // Modest cache size - -// Environment-specific defaults -let logLevel = config.string(forKey: "log.level", default: "info") // Safe default level -let enableDebug = config.bool(forKey: "debug.enabled", default: false) // Secure default - -// Performance defaults that err on the side of caution -let batchSize = config.int(forKey: "batch.size", default: 100) // Small safe batch -let maxConnections = config.int(forKey: "pool.max", default: 10) // Conservative pool - -#### Error handling behavior - -Default variants handle errors by returning the default value: - -- Missing values return the default. - -- Type conversion errors return the default. - -- Provider errors return the default (except for fetch variants). - -### Required variants - -Required variants throw errors when configuration values are missing or cannot be converted. These enforce that critical configuration must be present and valid. - -do { -// Required get -let serverPort = try config.requiredInt(forKey: "server.port") -let databaseHost = try config.requiredString(forKey: "database.host") - -// Required fetch -let latestPort = try await config.fetchRequiredInt(forKey: "server.port") - -// Required watch -try await config.watchRequiredInt(forKey: "server.port") { updates in -for try await port in updates { -print("Server port updated to: \(port)") -server.updatePort(port) -} -} -} catch { -fatalError("Configuration error: \(error)") -} - -#### When to use - -Use required variants when: - -- **Essential service configuration**: Server ports, database hosts, service endpoints. - -- **Application startup**: Values needed before the application can function properly. - -- **Critical functionality**: Configuration that must be present for core features to work. - -- **Fail-fast behavior**: You want immediate errors for missing critical configuration. - -### Choosing the right variant - -Use this decision tree to select the appropriate variant: - -#### Is the configuration value critical for application operation? - -**Yes** → Use **required variants** - -// Critical values that must be present -let serverPort = try config.requiredInt(forKey: "server.port") -let databaseHost = try config.requiredString(forKey: "database.host") - -**No** → Continue to next question - -#### Do you have a reasonable default value? - -**Yes** → Use **default variants** - -// Optional features with sensible defaults -let timeout = config.int(forKey: "http.timeout", default: 30) -let retryCount = config.int(forKey: "retries", default: 3) - -**No** → Use **optional variants** - -// Truly optional features where absence is meaningful -let debugEndpoint = config.string(forKey: "debug.endpoint") -let customTheme = config.string(forKey: "ui.theme") - -### Context and type conversion - -All variants support the same additional features: - -#### Configuration context - -// Optional with context -let timeout = config.int( -forKey: ConfigKey( -"service.timeout", -context: ["environment": "production", "region": "us-east-1"] -) -) - -// Default with context -let timeout = config.int( -forKey: ConfigKey( -"service.timeout", -context: ["environment": "production"] -), -default: 30 -) - -// Required with context -let timeout = try config.requiredInt( -forKey: ConfigKey( -"service.timeout", -context: ["environment": "production"] -) -) - -#### Type conversion - -String configuration values can be automatically converted to other types using the `as:` parameter. This works with: - -**Built-in convertible types:** - -- `SystemPackage.FilePath`: Converts from file paths. - -- `Foundation.URL`: Converts from URL strings. - -- `Foundation.UUID`: Converts from UUID strings. - -- `Foundation.Date`: Converts from ISO8601 date strings. - -**String-backed enums:** - -**Custom types:** - -- Types that you explicitly conform to `ExpressibleByConfigString`. - -// Built-in type conversion -let apiUrl = config.string(forKey: "api.url", as: URL.self) -let requestId = config.string(forKey: "request.id", as: UUID.self) -let configPath = config.string(forKey: "config.path", as: FilePath.self) -let startDate = config.string(forKey: "launch.date", as: Date.self) - -enum LogLevel: String { -case debug, info, warning, error -} - -// Optional conversion -let level: LogLevel? = config.string(forKey: "log.level", as: LogLevel.self) - -// Default conversion -let level = config.string(forKey: "log.level", as: LogLevel.self, default: .info) - -// Required conversion -let level = try config.requiredString(forKey: "log.level", as: LogLevel.self) - -// Custom type conversion (ExpressibleByConfigString) -struct DatabaseURL: ExpressibleByConfigString { -let url: URL - -init?(configString: String) { -guard let url = URL(string: configString) else { return nil } -self.url = url -} - -var description: String { url.absoluteString } -} -let dbUrl = config.string(forKey: "database.url", as: DatabaseURL.self) - -#### Secret handling - -// Mark sensitive values as secrets in all variants -let optionalKey = config.string(forKey: "api.key", isSecret: true) -let defaultKey = config.string(forKey: "api.key", isSecret: true, default: "development-key") -let requiredKey = try config.requiredString(forKey: "api.key", isSecret: true) - -Also check out Handling secrets correctly. - -### Best practices - -1. **Use required variants** only for truly critical configuration. - -2. **Use default variants** for user experience settings where missing configuration shouldn’t break functionality. - -3. **Use optional variants** for feature flags and debugging where the absence of configuration is meaningful. - -4. **Choose safe defaults** that won’t cause security issues or performance problems if used in production. - -For guidance on selecting between get, fetch, and watch access patterns, see Choosing the access pattern. For more configuration guidance, check out Adopting best practices. - -## See Also - -### Readers and providers - -`struct ConfigReader` - -A type that provides read-only access to configuration values from underlying providers. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`struct ConfigSnapshotReader` - -A container type for reading config values from snapshots. - -Choosing the access pattern - -Learn how to select the right method for reading configuration values based on your needs. - -Handling secrets correctly - -Protect sensitive configuration values from accidental disclosure in logs and debug output. - -- Choosing reader methods -- Overview -- Optional variants -- Default variants -- Required variants -- Choosing the right variant -- Context and type conversion -- Best practices -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider - -- Configuration -- KeyMappingProvider - -Structure - -# KeyMappingProvider - -A configuration provider that maps all keys before delegating to an upstream provider. - -KeyMappingProvider.swift - -## Mentioned in - -Example use cases - -## Overview - -Use `KeyMappingProvider` to automatically apply a mapping function to every configuration key before passing it to an underlying provider. This is particularly useful when the upstream source of configuration keys differs from your own. Another example is namespacing configuration values from specific sources, such as prefixing environment variables with an application name while leaving other configuration sources unchanged. - -### Common use cases - -Use `KeyMappingProvider` for: - -- Rewriting configuration keys to match upstream configuration sources. - -- Legacy system integration that adapts existing sources with different naming conventions. - -## Example - -Use `KeyMappingProvider` when you want to map keys for specific providers in a multi-provider setup: - -// Create providers -let envProvider = EnvironmentVariablesProvider() - -// Only remap the environment variables, not the JSON config -let keyMappedEnvProvider = KeyMappingProvider(upstream: envProvider) { key in -key.prepending(["myapp", "prod"]) -} - -let config = ConfigReader(providers: [\ -keyMappedEnvProvider, // Reads from "MYAPP_PROD_*" environment variables\ -jsonProvider // Reads from JSON without prefix\ -]) - -// This reads from "MYAPP_PROD_DATABASE_HOST" env var or "database.host" in JSON -let host = config.string(forKey: "database.host", default: "localhost") - -## Convenience method - -You can also use the `prefixKeys(with:)` convenience method on configuration provider types to wrap one in a `KeyMappingProvider`: - -let envProvider = EnvironmentVariablesProvider() -let keyMappedEnvProvider = envProvider.mapKeys { key in -key.prepending(["myapp", "prod"]) -} - -## Topics - -### Creating a key-mapping provider - -Creates a new provider. - -## Relationships - -### Conforms To - -- `ConfigProvider` -Conforms when `Upstream` conforms to `ConfigProvider`. - -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -- KeyMappingProvider -- Mentioned in -- Overview -- Common use cases -- Example -- Convenience method -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/choosing-access-patterns - -- Configuration -- Choosing the access pattern - -Article - -# Choosing the access pattern - -Learn how to select the right method for reading configuration values based on your needs. - -## Overview - -Swift Configuration provides three access patterns for retrieving configuration values, each optimized for different use cases and performance requirements. - -The three access patterns are: - -- **Get**: Synchronous access to current values available locally, in-memory. - -- **Fetch**: Asynchronous access to retrieve fresh values from authoritative sources, optionally with extra context. - -- **Watch**: Reactive access that provides real-time updates when values change. - -### Get: Synchronous local access - -The “get” pattern provides immediate, synchronous access to configuration values that are already available in memory. This is the fastest and most commonly used access pattern. - -let config = ConfigReader(provider: EnvironmentVariablesProvider()) - -// Get the current timeout value synchronously -let timeout = config.int(forKey: "http.timeout", default: 30) - -// Get a required value that must be present -let apiKey = try config.requiredString(forKey: "api.key", isSecret: true) - -#### When to use - -Use the “get” pattern when: - -- **Performance is critical**: You need immediate access without async overhead. - -- **Values are stable**: Configuration doesn’t change frequently during runtime. - -- **Simple providers**: Using environment variables, command-line arguments, or files. - -- **Startup configuration**: Reading values during application initialization. - -- **Request handling**: Accessing configuration in hot code paths where async calls would add latency. - -#### Behavior characteristics - -- Returns the currently cached value from the provider. - -- No network or I/O operations occur during the call. - -- Values may become stale if the underlying data source changes and the provider is either non-reloading, or has a long reload interval. - -### Fetch: Asynchronous fresh access - -The “fetch” pattern asynchronously retrieves the most current value from the authoritative data source, ensuring you always get up-to-date configuration. - -let config = ConfigReader(provider: remoteConfigProvider) - -// Fetch the latest timeout from a remote configuration service -let timeout = try await config.fetchInt(forKey: "http.timeout", default: 30) - -// Fetch with context for environment-specific configuration -let dbConnectionString = try await config.fetchRequiredString( -forKey: ConfigKey( -"database.url", -context: [\ -"environment": "production",\ -"region": "us-west-2",\ -"service": "user-service"\ -] -), -isSecret: true -) - -#### When to use - -Use the “fetch” pattern when: - -- **Freshness is critical**: You need the latest configuration values. - -- **Remote providers**: Using configuration services, databases, or external APIs that perform evaluation remotely. - -- **Infrequent access**: Reading configuration occasionally, not in hot paths. - -- **Setup operations**: Configuring long-lived resources like database connections where one-time overhead isn’t a concern, and the improved freshness is important. - -- **Administrative operations**: Fetching current settings for management interfaces. - -#### Behavior characteristics - -- Always contacts the authoritative data source. - -- May involve network calls, file system access, or database queries. - -- Providers may (but are not required to) cache the fetched value for subsequent “get” calls. - -- Throws an error if the provider fails to reach the source. - -### Watch: Reactive continuous updates - -The “watch” pattern provides an async sequence of configuration updates, allowing you to react to changes in real-time. This is ideal for long-running services that need to adapt to configuration changes without restarting. - -The async sequence is required to receive the current value as the first element as quickly as possible - this is part of the API contract with configuration providers (for details, check out `ConfigProvider`.) - -let config = ConfigReader(provider: reloadingProvider) - -// Watch for timeout changes and update connection pools -try await config.watchInt(forKey: "http.timeout", default: 30) { updates in -for await newTimeout in updates { -print("HTTP timeout updated to: \(newTimeout)") -connectionPool.updateTimeout(newTimeout) -} -} - -#### When to use - -Use the “watch” pattern when: - -- **Dynamic configuration**: Values change during application runtime. - -- **Hot reloading**: You need to update behavior without restarting the service. - -- **Feature toggles**: Enabling or disabling features based on configuration changes. - -- **Resource management**: Adjusting timeouts, limits, or thresholds dynamically. - -- **A/B testing**: Updating experimental parameters in real-time. - -#### Behavior characteristics - -- Immediately emits the initial value, then subsequent updates. - -- Continues monitoring until the task is cancelled. - -- Works with providers like `ReloadingFileProvider`. - -For details on reloading providers, check out Using reloading providers. - -### Using configuration context - -All access patterns support configuration context, which provides additional metadata to help providers return more specific values. Context is particularly useful with the “fetch” and “watch” patterns when working with dynamic or environment-aware providers. - -#### Filtering watch updates using context - -let context: [String: ConfigContextValue] = [\ -"environment": "production",\ -"region": "us-east-1",\ -"service_version": "2.1.0",\ -"feature_tier": "premium",\ -"load_factor": 0.85\ -] - -// Get environment-specific database configuration -let dbConfig = try await config.fetchRequiredString( -forKey: ConfigKey( -"database.connection_string", -context: context -), -isSecret: true -) - -// Watch for region-specific timeout adjustments -try await config.watchInt( -forKey: ConfigKey( -"api.timeout", -context: ["region": "us-west-2"] -), -default: 5000 -) { updates in -for await timeout in updates { -apiClient.updateTimeout(milliseconds: timeout) -} -} - -#### Get pattern performance - -- **Fastest**: No async overhead, immediate return. - -- **Memory usage**: Minimal, uses cached values. - -- **Best for**: Request handling, hot code paths, startup configuration. - -#### Fetch pattern performance - -- **Moderate**: Async overhead plus data source access time. - -- **Network dependent**: Performance varies with provider implementation. - -- **Best for**: Infrequent access, setup operations, administrative tasks. - -#### Watch pattern performance - -- **Background monitoring**: Continuous resource usage for monitoring. - -- **Event-driven**: Efficient updates only when values change. - -- **Best for**: Long-running services, dynamic configuration, feature toggles. - -### Error handling strategies - -Each access pattern handles errors differently: - -#### Get pattern errors - -// Returns nil or default value for missing/invalid config -let timeout = config.int(forKey: "http.timeout", default: 30) - -// Required variants throw errors for missing values -do { -let apiKey = try config.requiredString(forKey: "api.key") -} catch { -// Handle missing required configuration -} - -#### Fetch pattern errors - -// All fetch methods propagate provider and conversion errors -do { -let config = try await config.fetchRequiredString(forKey: "database.url") -} catch { -// Handle network errors, missing values, or conversion failures -} - -#### Watch pattern errors - -// Errors appear in the async sequence -try await config.watchRequiredInt(forKey: "port") { updates in -do { -for try await port in updates { -server.updatePort(port) -} -} catch { -// Handle provider errors or missing required values -} -} - -### Best practices - -1. **Choose based on use case**: Use “get” for performance-critical paths, “fetch” for freshness, and “watch” for hot reloading. - -2. **Handle errors appropriately**: Design error handling strategies that match your application’s resilience requirements. - -3. **Use context judiciously**: Provide context when you need environment-specific or conditional configuration values. - -4. **Monitor configuration access**: Use `AccessReporter` to understand your application’s configuration dependencies. - -5. **Cache wisely**: For frequently accessed values, prefer “get” over repeated “fetch” calls. - -For more guidance on selecting the right reader methods for your needs, see Choosing reader methods. To learn about handling sensitive configuration values securely, check out Handling secrets correctly. If you encounter issues with configuration access, refer to Troubleshooting and access reporting for debugging techniques. - -## See Also - -### Readers and providers - -`struct ConfigReader` - -A type that provides read-only access to configuration values from underlying providers. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`struct ConfigSnapshotReader` - -A container type for reading config values from snapshots. - -Choosing reader methods - -Choose between optional, default, and required variants of configuration methods. - -Handling secrets correctly - -Protect sensitive configuration values from accidental disclosure in logs and debug output. - -- Choosing the access pattern -- Overview -- Get: Synchronous local access -- Fetch: Asynchronous fresh access -- Watch: Reactive continuous updates -- Using configuration context -- Summary of performance considerations -- Error handling strategies -- Best practices -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessreporter - -- Configuration -- AccessReporter - -Protocol - -# AccessReporter - -A type that receives and processes configuration access events. - -protocol AccessReporter : Sendable - -AccessReporter.swift - -## Mentioned in - -Troubleshooting and access reporting - -Choosing the access pattern - -Configuring libraries - -## Overview - -Access reporters track when configuration values are read, fetched, or watched, to provide visibility into configuration usage patterns. This is useful for debugging, auditing, and understanding configuration dependencies. - -## Topics - -### Required methods - -`func report(AccessEvent)` - -Processes a configuration access event. - -**Required** - -## Relationships - -### Inherits From - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -### Conforming Types - -- `AccessLogger` -- `BroadcastingAccessReporter` -- `FileAccessLogger` - -## See Also - -### Troubleshooting and access reporting - -Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. - -`class AccessLogger` - -An access reporter that logs configuration access events using the Swift Log API. - -`class FileAccessLogger` - -An access reporter that writes configuration access events to a file. - -`struct AccessEvent` - -An event that captures information about accessing a configuration value. - -`struct BroadcastingAccessReporter` - -An access reporter that forwards events to multiple other reporters. - -- AccessReporter -- Mentioned in -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/using-reloading-providers - -- Configuration -- Using reloading providers - -Article - -# Using reloading providers - -Automatically reload configuration from files when they change. - -## Overview - -A reloading provider monitors configuration files for changes and automatically updates your application’s configuration without requiring restarts. Swift Configuration provides: - -- `ReloadingFileProvider` with `JSONSnapshot` for JSON configuration files. - -- `ReloadingFileProvider` with `YAMLSnapshot` for YAML configuration files. - -#### Creating and running providers - -Reloading providers run in a `ServiceGroup`: - -import ServiceLifecycle - -filePath: "/etc/config.json", -allowMissing: true, // Optional: treat missing file as empty config -pollInterval: .seconds(15) -) - -let serviceGroup = ServiceGroup( -services: [provider], -logger: logger -) - -try await serviceGroup.run() - -#### Reading configuration - -Use a reloading provider in the same fashion as a static provider, pass it to a `ConfigReader`: - -let config = ConfigReader(provider: provider) -let host = config.string( -forKey: "database.host", -default: "localhost" -) - -#### Poll interval considerations - -Choose poll intervals based on how quickly you need to detect changes: - -// Development: Quick feedback -pollInterval: .seconds(1) - -// Production: Balanced performance (default) -pollInterval: .seconds(15) - -// Batch processing: Resource efficient -pollInterval: .seconds(300) - -### Watching for changes - -The following sections provide examples of watching for changes in configuration from a reloading provider. - -#### Individual values - -The example below watches for updates in a single key, `database.host`: - -try await config.watchString( -forKey: "database.host" -) { updates in -for await host in updates { -print("Database host updated: \(host)") -} -} - -#### Configuration snapshots - -The following example reads the `database.host` and `database.password` key with the guarantee that they are read from the same update of the reloading file: - -try await config.watchSnapshot { updates in -for await snapshot in updates { -let host = snapshot.string(forKey: "database.host") -let password = snapshot.string(forKey: "database.password", isSecret: true) -print("Configuration updated - Database: \(host)") -} -} - -### Comparison with static providers - -| Feature | Static providers | Reloading providers | -| --- | --- | --- | -| **File reading** | Load once at startup | Reloading on change | -| **Service lifecycle** | Not required | Conforms to `Service` and must run in a `ServiceGroup` | -| **Configuration updates** | Require restart | Automatic reload | - -### Handling missing files during reloading - -Reloading providers support the `allowMissing` parameter to handle cases where configuration files might be temporarily missing or optional. This is useful for: - -- Optional configuration files that might not exist in all environments. - -- Configuration files that are created or removed dynamically. - -- Graceful handling of file system issues during service startup. - -#### Missing file behavior - -When `allowMissing` is `false` (the default), missing files cause errors: - -filePath: "/etc/config.json", -allowMissing: false // Default: throw error if file is missing -) -// Will throw an error if config.json doesn't exist - -When `allowMissing` is `true`, missing files are treated as empty configuration: - -filePath: "/etc/config.json", -allowMissing: true // Treat missing file as empty config -) -// Won't throw if config.json is missing - uses empty config instead - -#### Behavior during reloading - -If a file becomes missing after the provider starts, the behavior depends on the `allowMissing` setting: - -- **`allowMissing: false`**: The provider keeps the last known configuration and logs an error. - -- **`allowMissing: true`**: The provider switches to empty configuration. - -In both cases, when a valid file comes back, the provider will load it and recover. - -// Example: File gets deleted during runtime -try await config.watchString(forKey: "database.host", default: "localhost") { updates in -for await host in updates { -// With allowMissing: true, this will receive "localhost" when file is removed -// With allowMissing: false, this keeps the last known value -print("Database host: \(host)") -} -} - -#### Configuration-driven setup - -The following example sets up an environment variable provider to select the path and interval to watch for a JSON file that contains the configuration for your app: - -let envProvider = EnvironmentVariablesProvider() -let envConfig = ConfigReader(provider: envProvider) - -config: envConfig.scoped(to: "json") -// Reads JSON_FILE_PATH and JSON_POLL_INTERVAL_SECONDS -) - -### Migration from static providers - -1. **Replace initialization**: - -// Before - -// After - -2. **Add the provider to a ServiceGroup**: - -let serviceGroup = ServiceGroup(services: [provider], logger: logger) -try await serviceGroup.run() - -3. **Use ConfigReader**: - -let config = ConfigReader(provider: provider) - -// Live updates. -try await config.watchDouble(forKey: "timeout") { updates in -// Handle changes -} - -// On-demand reads - returns the current value, so might change over time. -let timeout = config.double(forKey: "timeout", default: 60.0) - -For guidance on choosing between get, fetch, and watch access patterns with reloading providers, see Choosing the access pattern. For troubleshooting reloading provider issues, check out Troubleshooting and access reporting. To learn about in-memory providers as an alternative, see Using in-memory providers. - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- Using reloading providers -- Overview -- Basic usage -- Watching for changes -- Comparison with static providers -- Handling missing files during reloading -- Advanced features -- Migration from static providers -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider - -- Configuration -- MutableInMemoryProvider - -Class - -# MutableInMemoryProvider - -A configuration provider that stores mutable values in memory. - -final class MutableInMemoryProvider - -MutableInMemoryProvider.swift - -## Mentioned in - -Using in-memory providers - -## Overview - -Unlike `InMemoryProvider`, this provider allows configuration values to be modified after initialization. It maintains thread-safe access to values and supports real-time notifications when values change, making it ideal for dynamic configuration scenarios. - -## Change notifications - -The provider supports watching for configuration changes through the standard `ConfigProvider` watching methods. When a value changes, all active watchers are automatically notified with the new value. - -## Use cases - -The mutable in-memory provider is particularly useful for: - -- **Dynamic configuration**: Values that change during application runtime - -- **Configuration bridges**: Adapting external configuration systems that push updates - -- **Testing scenarios**: Simulating configuration changes in unit tests - -- **Feature flags**: Runtime toggles that can be modified programmatically - -## Performance characteristics - -This provider offers O(1) lookup time with minimal synchronization overhead. Value updates are atomic and efficiently notify only the relevant watchers. - -## Usage - -// Create provider with initial values -let provider = MutableInMemoryProvider(initialValues: [\ -"feature.enabled": true,\ -"api.timeout": 30.0,\ -"database.host": "localhost"\ -]) - -let config = ConfigReader(provider: provider) - -// Read initial values -let isEnabled = config.bool(forKey: "feature.enabled") // true - -// Update values dynamically -provider.setValue(false, forKey: "feature.enabled") - -// Read updated values -let stillEnabled = config.bool(forKey: "feature.enabled") // false - -To learn more about the in-memory providers, check out Using in-memory providers. - -## Topics - -### Creating a mutable in-memory provider - -[`init(name: String?, initialValues: [AbsoluteConfigKey : ConfigValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/init(name:initialvalues:)) - -Creates a new mutable in-memory provider with the specified initial values. - -### Updating values in a mutable in-memory provider - -`func setValue(ConfigValue?, forKey: AbsoluteConfigKey)` - -Updates the stored value for the specified configuration key. - -## Relationships - -### Conforms To - -- `ConfigProvider` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- MutableInMemoryProvider -- Mentioned in -- Overview -- Change notifications -- Use cases -- Performance characteristics -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/development - -- Configuration -- Developing Swift Configuration - -Article - -# Developing Swift Configuration - -Learn about tools and conventions used to develop the Swift Configuration package. - -## Overview - -The Swift Configuration package is developed using modern Swift development practices and tools. This guide covers the development workflow, code organization, and tooling used to maintain the package. - -### Process - -We follow an open process and discuss development on GitHub issues, pull requests, and on the Swift Forums. Details on how to submit an issue or a pull requests can be found in CONTRIBUTING.md. - -Large features and changes go through a lightweight proposals process - to learn more, check out Proposals. - -#### Package organization - -The package contains several Swift targets organized by functionality: - -- **Configuration** \- Core configuration reading APIs and built-in providers. - -- **ConfigurationTesting** \- Testing utilities for external configuration providers. - -- **ConfigurationTestingInternal** \- Internal testing utilities and helpers. - -#### Running CI checks locally - -You can run the Github Actions workflows locally using act. To run all the jobs that run on a pull request, use the following command: - -% act pull_request -% act workflow_call -j soundness --input shell_check_enabled=true - -To bind-mount the working directory to the container, rather than a copy, use `--bind`. For example, to run just the formatting, and have the results reflected in your working directory: - -% act --bind workflow_call -j soundness --input format_check_enabled=true - -If you’d like `act` to always run with certain flags, these can be be placed in an `.actrc` file either in the current working directory or your home directory, for example: - ---container-architecture=linux/amd64 ---remote-name upstream ---action-offline-mode - -#### Code generation with gyb - -This package uses the “generate your boilerplate” (gyb) script from the Swift repository to stamp out repetitive code for each supported primitive type. - -The files that include gyb syntax end with `.gyb`, and after making changes to any of those files, run: - -./Scripts/generate_boilerplate_files_with_gyb.sh - -If you’re adding a new `.gyb` file, also make sure to add it to the exclude list in `Package.swift`. - -After running this script, also run the formatter before opening a PR. - -#### Code formatting - -The project uses swift-format for consistent code style. You can run CI checks locally using `act`. - -To run formatting checks: - -act --bind workflow_call -j soundness --input format_check_enabled=true - -#### Testing - -The package includes comprehensive test suites for all components: - -- Unit tests for individual providers and utilities. - -- Compatibility tests using `ProviderCompatTest` for built-in providers. - -Run tests using Swift Package Manager: - -swift test --enable-all-traits - -#### Documentation - -Documentation is written using DocC and includes: - -- API reference documentation in source code. - -- Conceptual guides in `.docc` catalogs. - -- Usage examples and best practices. - -- Troubleshooting guides. - -Preview documentation locally: - -SWIFT_PREVIEW_DOCS=1 swift package --disable-sandbox preview-documentation --target Configuration - -#### Code style - -- Follow Swift API Design Guidelines. - -- Use meaningful names for types, methods, and variables. - -- Include comprehensive documentation for all APIs, not only public types. - -- Write unit tests for new functionality. - -#### Provider development - -When developing new configuration providers: - -1. Implement the `ConfigProvider` protocol. - -2. Add comprehensive unit tests. - -3. Run compatibility tests using `ProviderCompatTest`. - -4. Add documentation to all symbols, not just `public`. - -#### Documentation requirements - -All APIs must include: - -- Clear, concise documentation comments. - -- Usage examples where appropriate. - -- Parameter and return value descriptions. - -- Error conditions and handling. - -## See Also - -### Contributing - -Collaborate on API changes to Swift Configuration by writing a proposal. - -- Developing Swift Configuration -- Overview -- Process -- Repository structure -- Development tools -- Contributing guidelines -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/troubleshooting - -- Configuration -- Troubleshooting and access reporting - -Article - -# Troubleshooting and access reporting - -Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. - -## Overview - -### Debugging configuration issues - -If your configuration values aren’t being read correctly, check: - -1. **Environment variable naming**: When using `EnvironmentVariablesProvider`, keys are automatically converted to uppercase with dots replaced by underscores. For example, `database.url` becomes `DATABASE_URL`. - -2. **Provider ordering**: When using multiple providers, they’re checked in order and the first one that returns a value wins. - -3. **Debug with an access reporter**: Use access reporting to see which keys are being queried and what values (if any) are being returned. See the next section for details. - -For guidance on selecting the right configuration access patterns and reader methods, check out Choosing the access pattern and Choosing reader methods. - -### Access reporting - -Configuration access reporting can help you debug issues and understand which configuration values your application is using. Swift Configuration provides two built-in ways to log access ( `AccessLogger` and `FileAccessLogger`), and you can also implement your own `AccessReporter`. - -#### Using AccessLogger - -`AccessLogger` integrates with Swift Log and records all configuration accesses: - -let logger = Logger(label: "...") -let accessLogger = AccessLogger(logger: logger) -let config = ConfigReader(provider: provider, accessReporter: accessLogger) - -// Each access will now be logged. -let timeout = config.double(forKey: "http.timeout", default: 30.0) - -This produces log entries showing: - -- Which configuration keys were accessed. - -- What values were returned (with secret values redacted). - -- Which provider supplied the value. - -- Whether default values were used. - -- The location of the code reading the config value. - -- The timestamp of the access. - -#### Using FileAccessLogger - -For writing access events to a file, especially useful during ad-hoc debugging, use `FileAccessLogger`: - -let fileLogger = try FileAccessLogger(filePath: "/var/log/myapp/config-access.log") -let config = ConfigReader(provider: provider, accessReporter: fileLogger) - -You can also enable file access logging for the whole application, without recompiling your code, by setting an environment variable: - -export CONFIG_ACCESS_LOG_FILE=/var/log/myapp/config-access.log - -And then read from the file to see one line per config access: - -tail -f /var/log/myapp/config-access.log - -#### Provider errors - -If any provider throws an error during lookup: - -- **Required methods** (`requiredString`, etc.): Error is immediately thrown to the caller. - -- **Optional methods** (with or without defaults): Error is handled gracefully; `nil` or the default value is returned. - -#### Missing values - -When no provider has the requested value: - -- **Methods with defaults**: Return the provided default value. - -- **Methods without defaults**: Return `nil`. - -- **Required methods**: Throw an error. - -#### File not found errors - -File-based providers ( `FileProvider`, `ReloadingFileProvider`, `DirectoryFilesProvider`, `EnvironmentVariablesProvider` with file path) can throw “file not found” errors when expected configuration files don’t exist. - -Common scenarios and solutions: - -**Optional configuration files:** - -// Problem: App crashes when optional config file is missing - -// Solution: Use allowMissing parameter - -filePath: "/etc/optional-config.json", -allowMissing: true -) - -**Environment-specific files:** - -// Different environments may have different config files -let configPath = "/etc/\(environment)/config.json" - -filePath: configPath, -allowMissing: true // Gracefully handle missing env-specific configs -) - -**Container startup issues:** - -// Config files might not be ready when container starts - -filePath: "/mnt/config/app.json", -allowMissing: true // Allow startup with empty config, load when available -) - -#### Configuration not updating - -If your reloading provider isn’t detecting file changes: - -1. **Check ServiceGroup**: Ensure the provider is running in a `ServiceGroup`. - -2. **Enable verbose logging**: The built-in providers use Swift Log for detailed logging, which can help spot issues. - -3. **Verify file path**: Confirm the file path is correct, the file exists, and file permissions are correct. - -4. **Check poll interval**: Consider if your poll interval is appropriate for your use case. - -#### ServiceGroup integration issues - -Common ServiceGroup problems: - -// Incorrect: Provider not included in ServiceGroup - -let config = ConfigReader(provider: provider) -// File monitoring won't work - -// Correct: Provider runs in ServiceGroup - -let serviceGroup = ServiceGroup(services: [provider], logger: logger) -try await serviceGroup.run() - -For more details about reloading providers and ServiceLifecycle integration, see Using reloading providers. To learn about proper configuration practices that can prevent common issues, check out Adopting best practices. - -## See Also - -### Troubleshooting and access reporting - -`protocol AccessReporter` - -A type that receives and processes configuration access events. - -`class AccessLogger` - -An access reporter that logs configuration access events using the Swift Log API. - -`class FileAccessLogger` - -An access reporter that writes configuration access events to a file. - -`struct AccessEvent` - -An event that captures information about accessing a configuration value. - -`struct BroadcastingAccessReporter` - -An access reporter that forwards events to multiple other reporters. - -- Troubleshooting and access reporting -- Overview -- Debugging configuration issues -- Access reporting -- Error handling -- Reloading provider troubleshooting -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileparsingoptions - -- Configuration -- FileParsingOptions - -Protocol - -# FileParsingOptions - -A type that provides parsing options for file configuration snapshots. - -protocol FileParsingOptions : Sendable - -FileProviderSnapshot.swift - -## Overview - -This protocol defines the requirements for parsing options types used with `FileConfigSnapshot` implementations. Types conforming to this protocol provide configuration parameters that control how file data is interpreted and parsed during snapshot creation. - -The parsing options are passed to the `init(data:providerName:parsingOptions:)` initializer, allowing custom file format implementations to access format-specific parsing settings such as character encoding, date formats, or validation rules. - -## Usage - -Implement this protocol to provide parsing options for your custom `FileConfigSnapshot`: - -struct MyParsingOptions: FileParsingOptions { -let encoding: String.Encoding -let dateFormat: String? -let strictValidation: Bool - -static let `default` = MyParsingOptions( -encoding: .utf8, -dateFormat: nil, -strictValidation: false -) -} - -struct MyFormatSnapshot: FileConfigSnapshot { -typealias ParsingOptions = MyParsingOptions - -init(data: RawSpan, providerName: String, parsingOptions: ParsingOptions) throws { -// Implementation that inspects `parsingOptions` properties like `encoding`, -// `dateFormat`, and `strictValidation`. -} -} - -## Topics - -### Required properties - -``static var `default`: Self`` - -The default instance of this options type. - -**Required** - -### Parsing options - -`protocol FileConfigSnapshot` - -A protocol for configuration snapshots created from file data. - -## Relationships - -### Inherits From - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -### Conforming Types - -- `JSONSnapshot.ParsingOptions` -- `YAMLSnapshot.ParsingOptions` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- FileParsingOptions -- Overview -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshot - -- Configuration -- ConfigSnapshot - -Protocol - -# ConfigSnapshot - -An immutable snapshot of a configuration provider’s state. - -protocol ConfigSnapshot : Sendable - -ConfigProvider.swift - -## Overview - -Snapshots enable consistent reads of multiple related configuration keys by capturing the provider’s state at a specific moment. This prevents the underlying data from changing between individual key lookups. - -## Topics - -### Required methods - -`var providerName: String` - -The human-readable name of the configuration provider that created this snapshot. - -**Required** - -Returns a value for the specified key from this immutable snapshot. - -## Relationships - -### Inherits From - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -### Inherited By - -- `FileConfigSnapshot` - -### Conforming Types - -- `JSONSnapshot` -- `YAMLSnapshot` - -## See Also - -### Creating a custom provider - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- ConfigSnapshot -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configuring-applications - -- Configuration -- Configuring applications - -Article - -# Configuring applications - -Provide flexible and consistent configuration for your application. - -## Overview - -Swift Configuration provides consistent configuration for your tools and applications. This guide shows how to: - -1. Set up a configuration hierarchy with multiple providers. - -2. Configure your application’s components. - -3. Access configuration values in your application and libraries. - -4. Monitor configuration access with access reporting. - -This pattern works well for server applications where configuration comes from environment variables, configuration files, and remote services. - -### Setting up a configuration hierarchy - -Start by creating a configuration hierarchy in your application’s entry point. This defines the order in which configuration sources are consulted when looking for values: - -import Configuration -import Logging - -// Create a logger. -let logger: Logger = ... - -// Set up the configuration hierarchy: -// - environment variables first, -// - then JSON file, -// - then in-memory defaults. -// Also emit log accesses into the provider logger, -// with secrets automatically redacted. - -let config = ConfigReader( -providers: [\ -EnvironmentVariablesProvider(),\ - -filePath: "/etc/myapp/config.json",\ -allowMissing: true // Optional: treat missing file as empty config\ -),\ -InMemoryProvider(values: [\ -"http.server.port": 8080,\ -"http.server.host": "127.0.0.1",\ -"http.client.timeout": 30.0\ -])\ -], -accessReporter: AccessLogger(logger: logger) -) - -// Start your application with the config. -try await runApplication(config: config, logger: logger) - -This configuration hierarchy gives priority to environment variables, then falls - -Next, configure your application using the configuration reader: - -func runApplication( -config: ConfigReader, -logger: Logger -) async throws { -// Get server configuration. -let serverHost = config.string( -forKey: "http.server.host", -default: "localhost" -) -let serverPort = config.int( -forKey: "http.server.port", -default: 8080 -) - -// Read library configuration with a scoped reader -// with the prefix `http.client`. -let httpClientConfig = HTTPClientConfiguration( -config: config.scoped(to: "http.client") -) -let httpClient = HTTPClient(configuration: httpClientConfig) - -// Run your server with the configured components -try await startHTTPServer( -host: serverHost, -port: serverPort, -httpClient: httpClient, -logger: logger -) -} - -Finally, you configure your application across the three sources. A fully configured set of environment variables could look like the following: - -export HTTP_SERVER_HOST=localhost -export HTTP_SERVER_PORT=8080 -export HTTP_CLIENT_TIMEOUT=30.0 -export HTTP_CLIENT_MAX_CONCURRENT_CONNECTIONS=20 -export HTTP_CLIENT_BASE_URL="https://example.com" -export HTTP_CLIENT_DEBUG_LOGGING=true - -In JSON: - -{ -"http": { -"server": { -"host": "localhost", -"port": 8080 -}, -"client": { -"timeout": 30.0, -"maxConcurrentConnections": 20, -"baseURL": "https://example.com", -"debugLogging": true -} -} -} - -And using `InMemoryProvider`: - -[\ -"http.server.port": 8080,\ -"http.server.host": "127.0.0.1",\ -"http.client.timeout": 30.0,\ -"http.client.maxConcurrentConnections": 20,\ -"http.client.baseURL": "https://example.com",\ -"http.client.debugLogging": true,\ -] - -In practice, you’d only specify a subset of the config keys in each location, to match the needs of your service’s operators. - -### Using scoped configuration - -For services with multiple instances of the same component, but with different settings, use scoped configuration: - -// For our server example, we might have different API clients -// that need different settings: - -let adminConfig = config.scoped(to: "services.admin") -let customerConfig = config.scoped(to: "services.customer") - -// Using the admin API configuration -let adminBaseURL = adminConfig.string( -forKey: "baseURL", -default: "https://admin-api.example.com" -) -let adminTimeout = adminConfig.double( -forKey: "timeout", -default: 60.0 -) - -// Using the customer API configuration -let customerBaseURL = customerConfig.string( -forKey: "baseURL", -default: "https://customer-api.example.com" -) -let customerTimeout = customerConfig.double( -forKey: "timeout", -default: 30.0 -) - -This can be configured via environment variables as follows: - -# Admin API configuration -export SERVICES_ADMIN_BASE_URL="https://admin.internal-api.example.com" -export SERVICES_ADMIN_TIMEOUT=120.0 -export SERVICES_ADMIN_DEBUG_LOGGING=true - -# Customer API configuration -export SERVICES_CUSTOMER_BASE_URL="https://api.example.com" -export SERVICES_CUSTOMER_MAX_CONCURRENT_CONNECTIONS=20 -export SERVICES_CUSTOMER_TIMEOUT=15.0 - -For details about the key conversion logic, check out `EnvironmentVariablesProvider`. - -For more configuration guidance, see Adopting best practices. To understand different access patterns and reader methods, refer to Choosing the access pattern and Choosing reader methods. For handling secrets securely, check out Handling secrets correctly. - -## See Also - -### Essentials - -Configuring libraries - -Provide a consistent and flexible way to configure your library. - -Example use cases - -Review common use cases with ready-to-copy code samples. - -Adopting best practices - -Follow these principles to make your code easily configurable and composable with other libraries. - -- Configuring applications -- Overview -- Setting up a configuration hierarchy -- Configure your application -- Using scoped configuration -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/systempackage - -- Configuration -- SystemPackage - -Extended Module - -# SystemPackage - -## Topics - -### Extended Structures - -`extension FilePath` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence - -- Configuration -- ConfigUpdatesAsyncSequence - -Structure - -# ConfigUpdatesAsyncSequence - -A concrete async sequence for delivering updated configuration values. - -AsyncSequences.swift - -## Topics - -### Creating an asynchronous update sequence - -Creates a new concrete async sequence wrapping the provided existential sequence. - -## Relationships - -### Conforms To - -- `Swift.Copyable` -- `Swift.Sendable` -- `Swift.SendableMetatype` -- `_Concurrency.AsyncSequence` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -- ConfigUpdatesAsyncSequence -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/expressiblebyconfigstring - -- Configuration -- ExpressibleByConfigString - -Protocol - -# ExpressibleByConfigString - -A protocol for types that can be initialized from configuration string values. - -protocol ExpressibleByConfigString : CustomStringConvertible - -ExpressibleByConfigString.swift - -## Mentioned in - -Choosing reader methods - -## Overview - -Conform your custom types to this protocol to enable automatic conversion when using the `as:` parameter with configuration reader methods such as `string(forKey:as:isSecret:fileID:line:)`. - -## Custom types - -For other custom types, conform to the protocol `ExpressibleByConfigString` by providing a failable initializer and the `description` property: - -struct DatabaseURL: ExpressibleByConfigString { -let url: URL - -init?(configString: String) { -guard let url = URL(string: configString) else { return nil } -self.url = url -} - -var description: String { url.absoluteString } -} - -// Now you can use it with automatic conversion -let config = ConfigReader(provider: EnvironmentVariablesProvider()) -let dbUrl = config.string(forKey: "database.url", as: DatabaseURL.self) - -## Built-in conformances - -The following Foundation types already conform to `ExpressibleByConfigString`: - -- `SystemPackage.FilePath` \- Converts from file paths. - -- `Foundation.URL` \- Converts from URL strings. - -- `Foundation.UUID` \- Converts from UUID strings. - -- `Foundation.Date` \- Converts from ISO8601 date strings. - -## Topics - -### Required methods - -`init?(configString: String)` - -Creates an instance from a configuration string value. - -**Required** - -## Relationships - -### Inherits From - -- `Swift.CustomStringConvertible` - -### Conforming Types - -- `Date` -- `FilePath` -- `URL` -- `UUID` - -## See Also - -### Value conversion - -`protocol ConfigBytesFromStringDecoder` - -A protocol for decoding string configuration values into byte arrays. - -`struct ConfigBytesFromBase64StringDecoder` - -A decoder that converts base64-encoded strings into byte arrays. - -`struct ConfigBytesFromHexStringDecoder` - -A decoder that converts hexadecimal-encoded strings into byte arrays. - -- ExpressibleByConfigString -- Mentioned in -- Overview -- Custom types -- Built-in conformances -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/using-in-memory-providers - -- Configuration -- Using in-memory providers - -Article - -# Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -## Overview - -Swift Configuration provides two in-memory providers, which are directly instantiated with the desired keys and values, rather than being parsed from another representation. These providers are particularly useful for testing, providing fallback values, and bridging with other configuration systems. - -- `InMemoryProvider` is an immutable value type, and can be useful for defining overrides and fallbacks in a provider hierarchy. - -- `MutableInMemoryProvider` is a mutable reference type, allowing you to update values and get any watchers notified automatically. It can be used to bridge from other stateful, callback-based configuration sources. - -### InMemoryProvider - -The `InMemoryProvider` is ideal for static configuration values that don’t change during application runtime. - -#### Basic usage - -Create an `InMemoryProvider` with a dictionary of configuration values: - -let provider = InMemoryProvider(values: [\ -"database.host": "localhost",\ -"database.port": 5432,\ -"api.timeout": 30.0,\ -"debug.enabled": true\ -]) - -let config = ConfigReader(provider: provider) -let host = config.string(forKey: "database.host") // "localhost" -let port = config.int(forKey: "database.port") // 5432 - -#### Using with hierarchical keys - -You can use `AbsoluteConfigKey` for more complex key structures: - -let provider = InMemoryProvider(values: [\ -AbsoluteConfigKey(["http", "client", "timeout"]): 30.0,\ -AbsoluteConfigKey(["http", "server", "port"]): 8080,\ -AbsoluteConfigKey(["logging", "level"]): "info"\ -]) - -#### Configuration context - -The in-memory provider performs exact matching of config keys, including the context. This allows you to provide different values for the same key path based on contextual information. - -The following example shows using two keys with the same key path, but different context, and giving them two different values: - -let provider = InMemoryProvider( -values: [\ -AbsoluteConfigKey(\ -["http", "client", "timeout"],\ -context: ["upstream": "example1.org"]\ -): 15.0,\ -AbsoluteConfigKey(\ -["http", "client", "timeout"],\ -context: ["upstream": "example2.org"]\ -): 30.0,\ -] -) - -With a provider configured this way, a config reader will return the following results: - -let config = ConfigReader(provider: provider) -config.double(forKey: "http.client.timeout") // nil -config.double( -forKey: ConfigKey( -"http.client.timeout", -context: ["upstream": "example1.org"] -) -) // 15.0 -config.double( -forKey: ConfigKey( -"http.client.timeout", -context: ["upstream": "example2.org"] -) -) // 30.0 - -### MutableInMemoryProvider - -The `MutableInMemoryProvider` allows you to modify configuration values at runtime and notify watchers of changes. - -#### Basic usage - -let provider = MutableInMemoryProvider() -provider.setValue("localhost", forKey: "database.host") -provider.setValue(5432, forKey: "database.port") - -let config = ConfigReader(provider: provider) -let host = config.string(forKey: "database.host") // "localhost" - -#### Updating values - -You can update values after creation, and any watchers will be notified: - -// Initial setup -provider.setValue("debug", forKey: "logging.level") - -// Later in your application, watchers are notified -provider.setValue("info", forKey: "logging.level") - -#### Watching for changes - -Use the provider’s async sequence to watch for configuration changes: - -let config = ConfigReader(provider: provider) -try await config.watchString( -forKey: "logging.level", -as: Logger.Level.self, -default: .debug -) { updates in -for try await level in updates { -print("Logging level changed to: \(level)") -} -} - -#### Testing - -In-memory providers are excellent for unit testing: - -func testDatabaseConnection() { -let testProvider = InMemoryProvider(values: [\ -"database.host": "test-db.example.com",\ -"database.port": 5433,\ -"database.name": "test_db"\ -]) - -let config = ConfigReader(provider: testProvider) -let connection = DatabaseConnection(config: config) -// Test your database connection logic -} - -#### Fallback values - -Use `InMemoryProvider` as a fallback in a provider hierarchy: - -let fallbackProvider = InMemoryProvider(values: [\ -"api.timeout": 30.0,\ -"retry.maxAttempts": 3,\ -"cache.enabled": true\ -]) - -let config = ConfigReader(providers: [\ -EnvironmentVariablesProvider(),\ -fallbackProvider\ -// Used when environment variables are not set\ -]) - -#### Bridging other systems - -Use `MutableInMemoryProvider` to bridge configuration from other systems: - -class ConfigurationBridge { -private let provider = MutableInMemoryProvider() - -func updateFromExternalSystem(_ values: [String: ConfigValue]) { -for (key, value) in values { -provider.setValue(value, forKey: key) -} -} -} - -For comparison with reloading providers, see Using reloading providers. To understand different access patterns and when to use each provider type, check out Choosing the access pattern. For more configuration guidance, refer to Adopting best practices. - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- Using in-memory providers -- Overview -- InMemoryProvider -- MutableInMemoryProvider -- Common Use Cases -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/snapshot() - -#app-main) - -- Configuration -- ConfigReader -- snapshot() - -Instance Method - -# snapshot() - -Returns a snapshot of the current configuration state. - -ConfigSnapshotReader.swift - -## Return Value - -The snapshot. - -## Discussion - -The snapshot reader provides read-only access to the configuration’s state at the time the method was called. - -let snapshot = config.snapshot() -// Use snapshot to read config values -let cert = snapshot.string(forKey: "cert") -let privateKey = snapshot.string(forKey: "privateKey") -// Ensures that both values are coming from the same underlying snapshot and that a provider -// didn't change its internal state between the two `string(...)` calls. -let identity = MyIdentity(cert: cert, privateKey: privateKey) - -## See Also - -### Reading from a snapshot - -Watches the configuration for changes. - -- snapshot() -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/best-practices - -- Configuration -- Adopting best practices - -Article - -# Adopting best practices - -Follow these principles to make your code easily configurable and composable with other libraries. - -## Overview - -When designing configuration for Swift libraries and applications, follow these patterns to create consistent, maintainable code that integrates well with the Swift ecosystem. - -### Document configuration keys - -Include thorough documentation about what configuration keys your library reads. For each key, document: - -- The key name and its hierarchical structure. - -- The expected data type. - -- Whether the key is required or optional. - -- Default values when applicable. - -- Valid value ranges or constraints. - -- Usage examples. - -public struct HTTPClientConfiguration { -/// ... -/// -/// ## Configuration keys: -/// - `timeout` (double, optional, default: 30.0): Request timeout in seconds. -/// - `maxRetries` (int, optional, default: 3, range: 0-10): Maximum retry attempts. -/// - `baseURL` (string, required): Base URL for requests. -/// - `apiKey` (string, required, secret): API authentication key. -/// -/// ... -public init(config: ConfigReader) { -// Implementation... -} -} - -### Use sensible defaults - -Provide reasonable default values to make your library work without extensive configuration. - -// Good: Provides sensible defaults -let timeout = config.double(forKey: "http.timeout", default: 30.0) -let maxConnections = config.int(forKey: "http.maxConnections", default: 10) - -// Avoid: Requiring configuration for common scenarios -let timeout = try config.requiredDouble(forKey: "http.timeout") // Forces users to configure - -### Use scoped configuration - -Organize your configuration keys logically using namespaces to keep related keys together. - -// Good: -let httpConfig = config.scoped(to: "http") -let timeout = httpConfig.double(forKey: "timeout", default: 30.0) -let retries = httpConfig.int(forKey: "retries", default: 3) - -// Better (in libraries): Offer a convenience method that reads your library's configuration. -// Tip: Read the configuration values from the provided reader directly, do not scope it -// to a "myLibrary" namespace. Instead, let the caller of MyLibraryConfiguration.init(config:) -// perform any scoping for your library's configuration. -public struct MyLibraryConfiguration { -public init(config: ConfigReader) { -self.timeout = config.double(forKey: "timeout", default: 30.0) -self.retries = config.int(forKey: "retries", default: 3) -} -} - -// Called from an app - the caller is responsible for adding a namespace and naming it, if desired. -let libraryConfig = MyLibraryConfiguration(config: config.scoped(to: "myLib")) - -### Mark secrets appropriately - -Mark sensitive configuration values like API keys, passwords, or tokens as secrets using the `isSecret: true` parameter. This tells access reporters to redact those values in logs. - -// Mark sensitive values as secrets -let apiKey = try config.requiredString(forKey: "api.key", isSecret: true) -let password = config.string(forKey: "database.password", default: nil, isSecret: true) - -// Regular values don't need the isSecret parameter -let timeout = config.double(forKey: "api.timeout", default: 30.0) - -Some providers also support the `SecretsSpecifier`, allowing you to mark which values are secret during application bootstrapping. - -For comprehensive guidance on handling secrets securely, see Handling secrets correctly. - -### Prefer optional over required - -Only mark configuration as required if your library absolutely cannot function without it. For most cases, provide sensible defaults and make configuration optional. - -// Good: Optional with sensible defaults -let timeout = config.double(forKey: "timeout", default: 30.0) -let debug = config.bool(forKey: "debug", default: false) - -// Use required only when absolutely necessary -let apiEndpoint = try config.requiredString(forKey: "api.endpoint") - -For more details, check out Choosing reader methods. - -### Validate configuration values - -Validate configuration values and throw meaningful errors for invalid input to catch configuration issues early. - -public init(config: ConfigReader) throws { -let timeout = config.double(forKey: "timeout", default: 30.0) - -throw MyConfigurationError.invalidTimeout("Timeout must be positive, got: \(timeout)") -} - -let maxRetries = config.int(forKey: "maxRetries", default: 3) - -throw MyConfigurationError.invalidRetryCount("Max retries must be 0-10, got: \(maxRetries)") -} - -self.timeout = timeout -self.maxRetries = maxRetries -} - -#### When to use reloading providers - -Use reloading providers when you need configuration changes to take effect without restarting your application: - -- Long-running services that can’t be restarted frequently. - -- Development environments where you iterate on configuration. - -- Applications that receive configuration updates through file deployments. - -Check out Using reloading providers to learn more. - -#### When to use static providers - -Use static providers when configuration doesn’t change during runtime: - -- Containerized applications with immutable configuration. - -- Applications where configuration is set once at startup. - -For help choosing between different access patterns and reader method variants, see Choosing the access pattern and Choosing reader methods. For troubleshooting configuration issues, refer to Troubleshooting and access reporting. - -## See Also - -### Essentials - -Configuring applications - -Provide flexible and consistent configuration for your application. - -Configuring libraries - -Provide a consistent and flexible way to configure your library. - -Example use cases - -Review common use cases with ready-to-copy code samples. - -- Adopting best practices -- Overview -- Document configuration keys -- Use sensible defaults -- Use scoped configuration -- Mark secrets appropriately -- Prefer optional over required -- Validate configuration values -- Choosing provider types -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier - -- Configuration -- SecretsSpecifier - -Enumeration - -# SecretsSpecifier - -A specification for identifying which configuration values contain sensitive information. - -SecretsSpecifier.swift - -## Mentioned in - -Adopting best practices - -Handling secrets correctly - -## Overview - -Configuration providers use secrets specifiers to determine which values should be marked as sensitive and protected from accidental disclosure in logs, debug output, or access reports. Secret values are handled specially by `AccessReporter` instances and other components that process configuration data. - -## Usage patterns - -### Mark all values as secret - -Use this for providers that exclusively handle sensitive data: - -let provider = InMemoryProvider( -values: ["api.key": "secret123", "db.password": "pass456"], -secretsSpecifier: .all -) - -### Mark specific keys as secret - -Use this when you know which specific keys contain sensitive information: - -let provider = EnvironmentVariablesProvider( -secretsSpecifier: .specific( -["API_KEY", "DATABASE_PASSWORD", "JWT_SECRET"] -) -) - -### Dynamic secret detection - -Use this for complex logic that determines secrecy based on key patterns or values: - -filePath: "/etc/config.json", -secretsSpecifier: .dynamic { key, value in -// Mark keys containing "password", -// "secret", or "token" as secret -key.lowercased().contains("password") || -key.lowercased().contains("secret") || -key.lowercased().contains("token") -} -) - -### No secret values - -Use this for providers that handle only non-sensitive configuration: - -let provider = InMemoryProvider( -values: ["app.name": "MyApp", "log.level": "info"], -secretsSpecifier: .none -) - -## Topics - -### Types of specifiers - -`case all` - -The library treats all configuration values as secrets. - -The library treats the specified keys as secrets. - -The library determines the secret status dynamically by evaluating each key-value pair. - -`case none` - -The library treats no configuration values as secrets. - -### Inspecting a secrets specifier - -Determines whether a configuration value should be treated as secret. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- SecretsSpecifier -- Mentioned in -- Overview -- Usage patterns -- Mark all values as secret -- Mark specific keys as secret -- Dynamic secret detection -- No secret values -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider - -- Configuration -- DirectoryFilesProvider - -Structure - -# DirectoryFilesProvider - -A configuration provider that reads values from individual files in a directory. - -struct DirectoryFilesProvider - -DirectoryFilesProvider.swift - -## Mentioned in - -Example use cases - -Handling secrets correctly - -Troubleshooting and access reporting - -## Overview - -This provider reads configuration values from a directory where each file represents a single configuration key-value pair. The file name becomes the configuration key, and the file contents become the value. This approach is commonly used by secret management systems that mount secrets as individual files. - -## Key mapping - -Configuration keys are transformed into file names using these rules: - -- Components are joined with dashes. - -- Non-alphanumeric characters (except dashes) are replaced with underscores. - -For example: - -## Value handling - -The provider reads file contents as UTF-8 strings and converts them to the requested type. For binary data (bytes type), it reads raw file contents directly without string conversion. Leading and trailing whitespace is always trimmed from string values. - -## Supported data types - -The provider supports all standard configuration types: - -- Strings (UTF-8 text files) - -- Integers, doubles, and booleans (parsed from string contents) - -- Arrays (using configurable separator, comma by default) - -- Byte arrays (raw file contents) - -## Secret handling - -By default, all values are marked as secrets for security. This is appropriate since this provider is typically used for sensitive data mounted by secret management systems. - -## Usage - -### Reading from a secrets directory - -// Assuming /run/secrets contains files: -// - database-password (contains: "secretpass123") -// - max-connections (contains: "100") -// - enable-cache (contains: "true") - -let provider = try await DirectoryFilesProvider( -directoryPath: "/run/secrets" -) - -let config = ConfigReader(provider: provider) -let dbPassword = config.string(forKey: "database.password") // "secretpass123" -let maxConn = config.int(forKey: "max.connections", default: 50) // 100 -let cacheEnabled = config.bool(forKey: "enable.cache", default: false) // true - -### Reading binary data - -// For binary files like certificates or keys -let provider = try await DirectoryFilesProvider( -directoryPath: "/run/secrets" -) - -let config = ConfigReader(provider: provider) -let certData = try config.requiredBytes(forKey: "tls.cert") // Raw file bytes - -### Custom array handling - -// If files contain comma-separated lists -let provider = try await DirectoryFilesProvider( -directoryPath: "/etc/config" -) - -// File "allowed-hosts" contains: "host1.example.com,host2.example.com,host3.example.com" -let hosts = config.stringArray(forKey: "allowed.hosts", default: []) -// ["host1.example.com", "host2.example.com", "host3.example.com"] - -## Configuration context - -This provider ignores the context passed in `context`. All keys are resolved using only their component path. - -## Topics - -### Creating a directory files provider - -Creates a new provider that reads files from a directory. - -## Relationships - -### Conforms To - -- `ConfigProvider` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -Using in-memory providers - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`struct InMemoryProvider` - -A configuration provider that stores values in memory. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- DirectoryFilesProvider -- Mentioned in -- Overview -- Key mapping -- Value handling -- Supported data types -- Secret handling -- Usage -- Reading from a secrets directory -- Reading binary data -- Custom array handling -- Configuration context -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey - -- Configuration -- AbsoluteConfigKey - -Structure - -# AbsoluteConfigKey - -A configuration key that represents an absolute path to a configuration value. - -struct AbsoluteConfigKey - -ConfigKey.swift - -## Mentioned in - -Using in-memory providers - -## Overview - -Absolute configuration keys are similar to relative keys but represent complete paths from the root of the configuration hierarchy. They are used internally by the configuration system after resolving any key prefixes or scoping. - -Like relative keys, absolute keys consist of hierarchical components and optional context information. - -## Topics - -### Creating an absolute configuration key - -`init(ConfigKey)` - -Creates a new absolute configuration key from a relative key. - -[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:context:)) - -Creates a new absolute configuration key. - -### Inspecting an absolute configuration key - -[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/components) - -The hierarchical components that make up this absolute configuration key. - -[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/context) - -Additional context information for this configuration key. - -### Instance Methods - -Returns a new absolute configuration key by appending the given relative key. - -Returns a new absolute configuration key by prepending the given relative key. - -## Relationships - -### Conforms To - -- `Swift.Comparable` -- `Swift.Copyable` -- `Swift.CustomStringConvertible` -- `Swift.Equatable` -- `Swift.ExpressibleByArrayLiteral` -- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` -- `Swift.ExpressibleByStringLiteral` -- `Swift.ExpressibleByUnicodeScalarLiteral` -- `Swift.Hashable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Configuration keys - -`struct ConfigKey` - -A configuration key representing a relative path to a configuration value. - -`enum ConfigContextValue` - -A value that can be stored in a configuration context. - -- AbsoluteConfigKey -- Mentioned in -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromhexstringdecoder - -- Configuration -- ConfigBytesFromHexStringDecoder - -Structure - -# ConfigBytesFromHexStringDecoder - -A decoder that converts hexadecimal-encoded strings into byte arrays. - -struct ConfigBytesFromHexStringDecoder - -ConfigBytesFromStringDecoder.swift - -## Overview - -This decoder interprets string configuration values as hexadecimal-encoded data and converts them to their binary representation. It expects strings to contain only valid hexadecimal characters (0-9, A-F, a-f). - -## Hexadecimal format - -The decoder expects strings with an even number of characters, where each pair of characters represents one byte. For example, “48656C6C6F” represents the bytes for “Hello”. - -## Topics - -### Creating bytes from a hex string decoder - -`init()` - -Creates a new hexadecimal decoder. - -## Relationships - -### Conforms To - -- `ConfigBytesFromStringDecoder` -- `Swift.Copyable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Value conversion - -`protocol ExpressibleByConfigString` - -A protocol for types that can be initialized from configuration string values. - -`protocol ConfigBytesFromStringDecoder` - -A protocol for decoding string configuration values into byte arrays. - -`struct ConfigBytesFromBase64StringDecoder` - -A decoder that converts base64-encoded strings into byte arrays. - -- ConfigBytesFromHexStringDecoder -- Overview -- Hexadecimal format -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent - -- Configuration -- ConfigContent - -Enumeration - -# ConfigContent - -The raw content of a configuration value. - -@frozen -enum ConfigContent - -ConfigProvider.swift - -## Topics - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -## Relationships - -### Conforms To - -- `Swift.Copyable` -- `Swift.Equatable` -- `Swift.ExpressibleByBooleanLiteral` -- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` -- `Swift.ExpressibleByFloatLiteral` -- `Swift.ExpressibleByIntegerLiteral` -- `Swift.ExpressibleByStringLiteral` -- `Swift.ExpressibleByUnicodeScalarLiteral` -- `Swift.Hashable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- ConfigContent -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue - -- Configuration -- ConfigValue - -Structure - -# ConfigValue - -A configuration value that wraps content with metadata. - -struct ConfigValue - -ConfigProvider.swift - -## Mentioned in - -Handling secrets correctly - -## Overview - -Configuration values pair raw content with a flag indicating whether the value contains sensitive information. Secret values are protected from accidental disclosure in logs and debug output: - -let apiKey = ConfigValue(.string("sk-abc123"), isSecret: true) - -## Topics - -### Creating a config value - -`init(ConfigContent, isSecret: Bool)` - -Creates a new configuration value. - -### Inspecting a config value - -`var content: ConfigContent` - -The configuration content. - -`var isSecret: Bool` - -Whether this value contains sensitive information that should not be logged. - -## Relationships - -### Conforms To - -- `Swift.Copyable` -- `Swift.CustomStringConvertible` -- `Swift.Equatable` -- `Swift.ExpressibleByBooleanLiteral` -- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` -- `Swift.ExpressibleByFloatLiteral` -- `Swift.ExpressibleByIntegerLiteral` -- `Swift.ExpressibleByStringLiteral` -- `Swift.ExpressibleByUnicodeScalarLiteral` -- `Swift.Hashable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`enum ConfigType` - -The supported configuration value types. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- ConfigValue -- Mentioned in -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation - -- Configuration -- Foundation - -Extended Module - -# Foundation - -## Topics - -### Extended Structures - -`extension Date` - -`extension URL` - -`extension UUID` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader - -- Configuration -- ConfigSnapshotReader - -Structure - -# ConfigSnapshotReader - -A container type for reading config values from snapshots. - -struct ConfigSnapshotReader - -ConfigSnapshotReader.swift - -## Overview - -A config snapshot reader provides read-only access to config values stored in an underlying `ConfigSnapshot`. Unlike a config reader, which can access live, changing config values from providers, a snapshot reader works with a fixed, immutable snapshot of the configuration data. - -## Usage - -Get a snapshot reader from a config reader by using the `snapshot()` method. All values in the snapshot are guaranteed to be from the same point in time: - -// Get a snapshot from a ConfigReader -let config = ConfigReader(provider: EnvironmentVariablesProvider()) -let snapshot = config.snapshot() -// Use snapshot to read config values -let cert = snapshot.string(forKey: "cert") -let privateKey = snapshot.string(forKey: "privateKey") -// Ensures that both values are coming from the same -// underlying snapshot and that a provider didn't change -// its internal state between the two `string(...)` calls. -let identity = MyIdentity(cert: cert, privateKey: privateKey) - -Or you can watch for snapshot updates using the `watchSnapshot(fileID:line:updatesHandler:)` method: - -try await config.watchSnapshot { snapshots in -for await snapshot in snapshots { -// Process each new configuration snapshot -let cert = snapshot.string(forKey: "cert") -let privateKey = snapshot.string(forKey: "privateKey") -// Ensures that both values are coming from the same -// underlying snapshot and that a provider didn't change -// its internal state between the two `string(...)` calls. -let newCert = MyCert(cert: cert, privateKey: privateKey) -print("Certificate was updated: \(newCert.redactedDescription)") -} -} - -### Scoping - -Like `ConfigReader`, you can set a key prefix on the config snapshot reader, allowing all config lookups to prepend a prefix to the keys, which lets you pass a scoped snapshot reader to nested components. - -let httpConfig = snapshotReader.scoped(to: "http") -let timeout = httpConfig.int(forKey: "timeout") -// Reads from "http.timeout" in the snapshot - -### Config keys and context - -The library requests config values using a canonical “config key”, that represents a key path. You can provide additional context that was used by some providers when the snapshot was created. - -let httpTimeout = snapshotReader.int( -forKey: ConfigKey("http.timeout", context: ["upstream": "example.com"]), -default: 60 -) - -### Automatic type conversion - -String configuration values can be automatically converted to other types using the `as:` parameter. This works with: - -- Types that you explicitly conform to `ExpressibleByConfigString`. - -- Built-in types that already conform to `ExpressibleByConfigString`: - -- `SystemPackage.FilePath` \- Converts from file paths. - -- `Foundation.URL` \- Converts from URL strings. - -- `Foundation.UUID` \- Converts from UUID strings. - -- `Foundation.Date` \- Converts from ISO8601 date strings. - -// Built-in type conversion -let apiUrl = snapshot.string( -forKey: "api.url", -as: URL.self -) -let requestId = snapshot.string( -forKey: "request.id", -as: UUID.self -) - -enum LogLevel: String { -case debug, info, warning, error -} -let logLevel = snapshot.string( -forKey: "logging.level", -as: LogLevel.self, -default: .info -) - -// Custom type conversion (ExpressibleByConfigString) -struct DatabaseURL: ExpressibleByConfigString { -let url: URL - -init?(configString: String) { -guard let url = URL(string: configString) else { return nil } -self.url = url -} - -var description: String { url.absoluteString } -} -let dbUrl = snapshot.string( -forKey: "database.url", -as: DatabaseURL.self -) - -### Access reporting - -When reading from a snapshot, access events are reported to the access reporter from the original config reader. This helps debug which config values are accessed, even when reading from snapshots. - -## Topics - -### Creating a snapshot - -Returns a snapshot of the current configuration state. - -Watches the configuration for changes. - -### Namespacing - -Returns a scoped snapshot reader by appending the provided key to the current key prefix. - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key, converting from string. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -### Synchronously reading lists of string values - -Synchronously gets an array of config values for the given config key, converting from strings. - -Synchronously gets an array of config values for the given config key with default fallback, converting from strings. - -### Synchronously reading required string values - -Synchronously gets a required config value for the given config key, throwing an error if it’s missing. - -Synchronously gets a required config value for the given config key, converting from string. - -### Synchronously reading required lists of string values - -Synchronously gets a required array of config values for the given config key, converting from strings. - -### Synchronously reading Boolean values - -### Synchronously reading required Boolean values - -### Synchronously reading lists of Boolean values - -### Synchronously reading required lists of Boolean values - -### Synchronously reading integer values - -### Synchronously reading required integer values - -### Synchronously reading lists of integer values - -### Synchronously reading required lists of integer values - -### Synchronously reading double values - -### Synchronously reading required double values - -### Synchronously reading lists of double values - -### Synchronously reading required lists of double values - -### Synchronously reading bytes - -### Synchronously reading required bytes - -### Synchronously reading collections of byte chunks - -### Synchronously reading required collections of byte chunks - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Readers and providers - -`struct ConfigReader` - -A type that provides read-only access to configuration values from underlying providers. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -Choosing the access pattern - -Learn how to select the right method for reading configuration values based on your needs. - -Choosing reader methods - -Choose between optional, default, and required variants of configuration methods. - -Handling secrets correctly - -Protect sensitive configuration values from accidental disclosure in logs and debug output. - -- ConfigSnapshotReader -- Overview -- Usage -- Scoping -- Config keys and context -- Automatic type conversion -- Access reporting -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue - -- Configuration -- ConfigContextValue - -Enumeration - -# ConfigContextValue - -A value that can be stored in a configuration context. - -enum ConfigContextValue - -ConfigContext.swift - -## Overview - -Context values support common data types used for configuration metadata. - -## Topics - -### Configuration context values - -`case string(String)` - -A string value. - -`case bool(Bool)` - -A Boolean value. - -`case int(Int)` - -An integer value. - -`case double(Double)` - -A floating point value. - -## Relationships - -### Conforms To - -- `Swift.Copyable` -- `Swift.CustomStringConvertible` -- `Swift.Equatable` -- `Swift.ExpressibleByBooleanLiteral` -- `Swift.ExpressibleByExtendedGraphemeClusterLiteral` -- `Swift.ExpressibleByFloatLiteral` -- `Swift.ExpressibleByIntegerLiteral` -- `Swift.ExpressibleByStringLiteral` -- `Swift.ExpressibleByUnicodeScalarLiteral` -- `Swift.Hashable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Configuration keys - -`struct ConfigKey` - -A configuration key representing a relative path to a configuration value. - -`struct AbsoluteConfigKey` - -A configuration key that represents an absolute path to a configuration value. - -- ConfigContextValue -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader - -- Configuration -- ConfigReader - -Structure - -# ConfigReader - -A type that provides read-only access to configuration values from underlying providers. - -struct ConfigReader - -ConfigReader.swift - -## Mentioned in - -Configuring libraries - -Example use cases - -Using reloading providers - -## Overview - -Use `ConfigReader` to access configuration values from various sources like environment variables, JSON files, or in-memory stores. The reader supports provider hierarchies, key scoping, and access reporting for debugging configuration usage. - -## Usage - -To read configuration values, create a config reader with one or more providers: - -let config = ConfigReader(provider: EnvironmentVariablesProvider()) -let httpTimeout = config.int(forKey: "http.timeout", default: 60) - -### Using multiple providers - -Create a hierarchy of providers by passing an array to the initializer. The reader queries providers in order, using the first non-nil value it finds: - -do { -let config = ConfigReader(providers: [\ -// First, check environment variables\ -EnvironmentVariablesProvider(),\ -// Then, check a JSON config file\ - -// Finally, fall \ -]) - -// Uses the first provider that has a value for "http.timeout" -let timeout = config.int(forKey: "http.timeout", default: 15) -} catch { -print("Failed to create JSON provider: \(error)") -} - -The `get` and `fetch` methods query providers sequentially, while the `watch` method monitors all providers in parallel and returns the first non-nil value from the latest results. - -### Creating scoped readers - -Create a scoped reader to access nested configuration sections without repeating key prefixes. This is useful for passing configuration to specific components. - -Given this JSON configuration: - -{ -"http": { -"timeout": 60 -} -} - -Create a scoped reader for the HTTP section: - -let httpConfig = config.scoped(to: "http") -let timeout = httpConfig.int(forKey: "timeout") // Reads "http.timeout" - -### Understanding config keys - -The library accesses configuration values using config keys that represent a hierarchical path to the value. Internally, the library represents a key as a list of string components, such as `["http", "timeout"]`. - -### Using configuration context - -Provide additional context to help providers return more specific values. In the following example with a configuration that includes repeated configurations per “upstream”, the value returned is potentially constrained to the configuration with the matching context: - -let httpTimeout = config.int( -forKey: ConfigKey("http.timeout", context: ["upstream": "example.com"]), -default: 60 -) - -Providers can use this context to return specialized values or fall - -The library can automatically convert string configuration values to other types using the `as:` parameter. This works with: - -- Types that you explicitly conform to `ExpressibleByConfigString`. - -- Built-in types that already conform to `ExpressibleByConfigString`: - -- `SystemPackage.FilePath` \- Converts from file paths. - -- `Foundation.URL` \- Converts from URL strings. - -- `Foundation.UUID` \- Converts from UUID strings. - -- `Foundation.Date` \- Converts from ISO8601 date strings. - -// Built-in type conversion -let apiUrl = config.string(forKey: "api.url", as: URL.self) -let requestId = config.string( -forKey: "request.id", -as: UUID.self -) - -enum LogLevel: String { -case debug, info, warning, error -} -let logLevel = config.string( -forKey: "logging.level", -as: LogLevel.self, -default: .info -) - -// Custom type conversion (ExpressibleByConfigString) -struct DatabaseURL: ExpressibleByConfigString { -let url: URL - -init?(configString: String) { -guard let url = URL(string: configString) else { return nil } -self.url = url -} - -var description: String { url.absoluteString } -} -let dbUrl = config.string( -forKey: "database.url", -as: DatabaseURL.self -) - -### How providers encode keys - -Each `ConfigProvider` interprets config keys according to its data source format. For example, `EnvironmentVariablesProvider` converts `["http", "timeout"]` to the environment variable name `HTTP_TIMEOUT` by uppercasing components and joining with underscores. - -### Monitoring configuration access - -Use an access reporter to track which configuration values your application reads. The reporter receives `AccessEvent` instances containing the requested key, calling code location, returned value, and source provider. - -This helps debug configuration issues and to discover the config dependencies in your codebase. - -### Protecting sensitive values - -Mark sensitive configuration values as secrets to prevent logging by access loggers. Both config readers and providers can set the `isSecret` property. When either marks a value as sensitive, `AccessReporter` instances should not log the raw value. - -### Configuration context - -Configuration context supplements the configuration key components with extra metadata that providers can use to refine value lookups or return more specific results. Context is particularly useful for scenarios where the same configuration key might need different values based on runtime conditions. - -Create context using dictionary literal syntax with automatic type inference: - -let context: [String: ConfigContextValue] = [\ -"environment": "production",\ -"region": "us-west-2",\ -"timeout": 30,\ -"retryEnabled": true\ -] - -#### Provider behavior - -Not all providers use context information. Providers that support context can: - -- Return specialized values based on context keys. - -- Fall , -default: "localhost:5432" -) - -### Error handling behavior - -The config reader handles provider errors differently based on the method type: - -- **Get and watch methods**: Gracefully handle errors by returning `nil` or default values, except for “required” variants which rethrow errors. - -- **Fetch methods**: Always rethrow both provider and conversion errors. - -- **Required methods**: Rethrow all errors without fallback behavior. - -The library reports all provider errors to the access reporter through the `providerResults` array, even when handled gracefully. - -## Topics - -### Creating config readers - -`init(provider: some ConfigProvider, accessReporter: (any AccessReporter)?)` - -Creates a config reader with a single provider. - -[`init(providers: [any ConfigProvider], accessReporter: (any AccessReporter)?)`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(providers:accessreporter:)) - -Creates a config reader with multiple providers. - -### Retrieving a scoped config reader - -Returns a scoped config reader with the specified key appended to the current prefix. - -### Reading from a snapshot - -Returns a snapshot of the current configuration state. - -Watches the configuration for changes. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Readers and providers - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`struct ConfigSnapshotReader` - -A container type for reading config values from snapshots. - -Choosing the access pattern - -Learn how to select the right method for reading configuration values based on your needs. - -Choosing reader methods - -Choose between optional, default, and required variants of configuration methods. - -Handling secrets correctly - -Protect sensitive configuration values from accidental disclosure in logs and debug output. - -- ConfigReader -- Mentioned in -- Overview -- Usage -- Using multiple providers -- Creating scoped readers -- Understanding config keys -- Using configuration context -- Automatic type conversion -- How providers encode keys -- Monitoring configuration access -- Protecting sensitive values -- Configuration context -- Error handling behavior -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromstringdecoder - -- Configuration -- ConfigBytesFromStringDecoder - -Protocol - -# ConfigBytesFromStringDecoder - -A protocol for decoding string configuration values into byte arrays. - -protocol ConfigBytesFromStringDecoder : Sendable - -ConfigBytesFromStringDecoder.swift - -## Overview - -This protocol defines the interface for converting string-based configuration values into binary data. Different implementations can support various encoding formats such as base64, hexadecimal, or other custom encodings. - -## Usage - -Implementations of this protocol are used by configuration providers that need to convert string values to binary data, such as cryptographic keys, certificates, or other binary configuration data. - -let decoder: ConfigBytesFromStringDecoder = .base64 -let bytes = decoder.decode("SGVsbG8gV29ybGQ=") // "Hello World" in base64 - -## Topics - -### Required methods - -Decodes a string value into an array of bytes. - -**Required** - -### Built-in decoders - -`static var base64: ConfigBytesFromBase64StringDecoder` - -A decoder that interprets string values as base64-encoded data. - -`static var hex: ConfigBytesFromHexStringDecoder` - -A decoder that interprets string values as hexadecimal-encoded data. - -## Relationships - -### Inherits From - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -### Conforming Types - -- `ConfigBytesFromBase64StringDecoder` -- `ConfigBytesFromHexStringDecoder` - -## See Also - -### Value conversion - -`protocol ExpressibleByConfigString` - -A protocol for types that can be initialized from configuration string values. - -`struct ConfigBytesFromBase64StringDecoder` - -A decoder that converts base64-encoded strings into byte arrays. - -`struct ConfigBytesFromHexStringDecoder` - -A decoder that converts hexadecimal-encoded strings into byte arrays. - -- ConfigBytesFromStringDecoder -- Overview -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfrombase64stringdecoder - -- Configuration -- ConfigBytesFromBase64StringDecoder - -Structure - -# ConfigBytesFromBase64StringDecoder - -A decoder that converts base64-encoded strings into byte arrays. - -struct ConfigBytesFromBase64StringDecoder - -ConfigBytesFromStringDecoder.swift - -## Overview - -This decoder interprets string configuration values as base64-encoded data and converts them to their binary representation. - -## Topics - -### Creating bytes from a base64 string - -`init()` - -Creates a new base64 decoder. - -## Relationships - -### Conforms To - -- `ConfigBytesFromStringDecoder` -- `Swift.Copyable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Value conversion - -`protocol ExpressibleByConfigString` - -A protocol for types that can be initialized from configuration string values. - -`protocol ConfigBytesFromStringDecoder` - -A protocol for decoding string configuration values into byte arrays. - -`struct ConfigBytesFromHexStringDecoder` - -A decoder that converts hexadecimal-encoded strings into byte arrays. - -- ConfigBytesFromBase64StringDecoder -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype - -- Configuration -- ConfigType - -Enumeration - -# ConfigType - -The supported configuration value types. - -@frozen -enum ConfigType - -ConfigProvider.swift - -## Topics - -### Types of configuration content - -`case string` - -A string value. - -`case stringArray` - -An array of string values. - -`case bool` - -A Boolean value. - -`case boolArray` - -An array of Boolean values. - -`case int` - -An integer value. - -`case intArray` - -An array of integer values. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -### Initializers - -`init?(rawValue: String)` - -## Relationships - -### Conforms To - -- `Swift.BitwiseCopyable` -- `Swift.Equatable` -- `Swift.Hashable` -- `Swift.RawRepresentable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`struct LookupResult` - -The result of looking up a configuration value in a provider. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- ConfigType -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent - -- Configuration -- AccessEvent - -Structure - -# AccessEvent - -An event that captures information about accessing a configuration value. - -struct AccessEvent - -AccessReporter.swift - -## Overview - -Access events are generated whenever configuration values are accessed through `ConfigReader` and `ConfigSnapshotReader` methods. They contain metadata about the access, results from individual providers, and the final outcome of the operation. - -## Topics - -### Creating an access event - -Creates a configuration access event. - -`struct Metadata` - -Metadata describing the configuration access operation. - -`struct ProviderResult` - -The result of a configuration lookup from a specific provider. - -### Inspecting an access event - -The final outcome of the configuration access operation. - -`var conversionError: (any Error)?` - -An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. - -`var metadata: AccessEvent.Metadata` - -Metadata that describes the configuration access operation. - -[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) - -The results from each configuration provider that was queried. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Troubleshooting and access reporting - -Troubleshooting and access reporting - -Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. - -`protocol AccessReporter` - -A type that receives and processes configuration access events. - -`class AccessLogger` - -An access reporter that logs configuration access events using the Swift Log API. - -`class FileAccessLogger` - -An access reporter that writes configuration access events to a file. - -`struct BroadcastingAccessReporter` - -An access reporter that forwards events to multiple other reporters. - -- AccessEvent -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter - -- Configuration -- BroadcastingAccessReporter - -Structure - -# BroadcastingAccessReporter - -An access reporter that forwards events to multiple other reporters. - -struct BroadcastingAccessReporter - -AccessReporter.swift - -## Overview - -Use this reporter to send configuration access events to multiple destinations simultaneously. Each upstream reporter receives a copy of every event in the order they were provided during initialization. - -let fileLogger = try FileAccessLogger(filePath: "/tmp/config.log") -let accessLogger = AccessLogger(logger: logger) -let broadcaster = BroadcastingAccessReporter(upstreams: [fileLogger, accessLogger]) - -let config = ConfigReader( -provider: EnvironmentVariablesProvider(), -accessReporter: broadcaster -) - -## Topics - -### Creating a broadcasting access reporter - -[`init(upstreams: [any AccessReporter])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter/init(upstreams:)) - -Creates a new broadcasting access reporter. - -## Relationships - -### Conforms To - -- `AccessReporter` -- `Swift.Copyable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Troubleshooting and access reporting - -Troubleshooting and access reporting - -Check out some techniques to debug unexpected issues and to increase visibility into accessed config values. - -`protocol AccessReporter` - -A type that receives and processes configuration access events. - -`class AccessLogger` - -An access reporter that logs configuration access events using the Swift Log API. - -`class FileAccessLogger` - -An access reporter that writes configuration access events to a file. - -`struct AccessEvent` - -An event that captures information about accessing a configuration value. - -- BroadcastingAccessReporter -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/lookupresult - -- Configuration -- LookupResult - -Structure - -# LookupResult - -The result of looking up a configuration value in a provider. - -struct LookupResult - -ConfigProvider.swift - -## Overview - -Providers return this result from value lookup methods, containing both the encoded key used for the lookup and the value found: - -let result = try provider.value(forKey: key, type: .string) -if let value = result.value { -print("Found: \(value)") -} - -## Topics - -### Creating a lookup result - -`init(encodedKey: String, value: ConfigValue?)` - -Creates a lookup result. - -### Inspecting a lookup result - -`var encodedKey: String` - -The provider-specific encoding of the configuration key. - -`var value: ConfigValue?` - -The configuration value found for the key, or nil if not found. - -## Relationships - -### Conforms To - -- `Swift.Equatable` -- `Swift.Hashable` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a custom provider - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -`protocol FileParsingOptions` - -A type that provides parsing options for file configuration snapshots. - -`protocol ConfigProvider` - -A type that provides configuration values from a data source. - -`enum ConfigContent` - -The raw content of a configuration value. - -`struct ConfigValue` - -A configuration value that wraps content with metadata. - -`enum ConfigType` - -The supported configuration value types. - -`enum SecretsSpecifier` - -A specification for identifying which configuration values contain sensitive information. - -`struct ConfigUpdatesAsyncSequence` - -A concrete async sequence for delivering updated configuration values. - -- LookupResult -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/proposals - -- Configuration -- Proposals - -# Proposals - -Collaborate on API changes to Swift Configuration by writing a proposal. - -## Overview - -For non-trivial changes that affect the public API, the Swift Configuration project adopts a lightweight version of the Swift Evolution process. - -Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times. - -While it’s encouraged to get feedback by opening a pull request with a proposal early in the process, it’s also important to consider the complexity of the implementation when evaluating different solutions. For example, this might mean including a link to a branch containing a prototype implementation of the feature in the pull request description. - -### Steps - -1. Make sure there’s a GitHub issue for the feature or change you would like to propose. - -2. Duplicate the `SCO-NNNN.md` document and replace `NNNN` with the next available proposal number. - -3. Link the GitHub issue from your proposal, and fill in the proposal. - -4. Open a pull request with your proposal and solicit feedback from other contributors. - -5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred. - -6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal. - -7. The proposal is considered Approved once the implementation, proposal PRs have been merged, and, if originally disabled by a feature flag, feature flag enabled unconditionally. - -If you have any questions, ask in an issue on GitHub. - -### Possible review states - -- Awaiting Review - -- In Review - -- Ready for Implementation - -- In Preview - -- Approved - -- Deferred - -## Topics - -SCO-NNNN: Feature name - -Feature abstract – a one sentence summary. - -SCO-0001: Generic file providers - -Introduce format-agnostic providers to simplify implementing additional file formats beyond JSON and YAML. - -SCO-0002: Remove custom key decoders - -Remove the custom key decoder feature to fix a flaw and simplify the project - -SCO-0003: Allow missing files in file providers - -Add an `allowMissing` parameter to file-based providers to handle missing configuration files gracefully. - -## See Also - -### Contributing - -Developing Swift Configuration - -Learn about tools and conventions used to develop the Swift Configuration package. - -- Proposals -- Overview -- Steps -- Possible review states -- Topics -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/inmemoryprovider - -- Configuration -- InMemoryProvider - -Structure - -# InMemoryProvider - -A configuration provider that stores values in memory. - -struct InMemoryProvider - -InMemoryProvider.swift - -## Mentioned in - -Using in-memory providers - -Configuring applications - -Example use cases - -## Overview - -This provider maintains a static dictionary of configuration values in memory, making it ideal for providing default values, overrides, or test configurations. Values are immutable once the provider is created and never change over time. - -## Use cases - -The in-memory provider is particularly useful for: - -- **Default configurations**: Providing fallback values when other providers don’t have a value - -- **Configuration overrides**: Taking precedence over other providers - -- **Testing**: Creating predictable configuration states for unit tests - -- **Static configurations**: Embedding compile-time configuration values - -## Value types - -The provider supports all standard configuration value types and automatically handles type validation. Values must match the requested type exactly - no automatic conversion is performed - for example, requesting a `String` value for a key that stores an `Int` value will throw an error. - -## Performance characteristics - -This provider offers O(1) lookup time and performs no I/O operations. All values are stored in memory. - -## Usage - -let provider = InMemoryProvider(values: [\ -"http.client.user-agent": "Config/1.0 (Test)",\ -"http.client.timeout": 15.0,\ -"http.secret": ConfigValue("s3cret", isSecret: true),\ -"http.version": 2,\ -"enabled": true\ -]) -// Prints all values, redacts "http.secret" automatically. -print(provider) -let config = ConfigReader(provider: provider) -let isEnabled = config.bool(forKey: "enabled", default: false) - -To learn more about the in-memory providers, check out Using in-memory providers. - -## Topics - -### Creating an in-memory provider - -[`init(name: String?, values: [AbsoluteConfigKey : ConfigValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/inmemoryprovider/init(name:values:)) - -Creates a new in-memory provider with the specified configuration values. - -## Relationships - -### Conforms To - -- `ConfigProvider` -- `Swift.Copyable` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Built-in providers - -`struct EnvironmentVariablesProvider` - -A configuration provider that sources values from environment variables. - -`struct CommandLineArgumentsProvider` - -A configuration provider that sources values from command-line arguments. - -`struct FileProvider` - -A configuration provider that reads from a file on disk using a configurable snapshot type. - -`class ReloadingFileProvider` - -A configuration provider that reads configuration from a file on disk with automatic reloading capability. - -`struct JSONSnapshot` - -A snapshot of configuration values parsed from JSON data. - -`class YAMLSnapshot` - -A snapshot of configuration values parsed from YAML data. - -Using reloading providers - -Automatically reload configuration from files when they change. - -`struct DirectoryFilesProvider` - -A configuration provider that reads values from individual files in a directory. - -Learn about the `InMemoryProvider` and `MutableInMemoryProvider` built-in types. - -`class MutableInMemoryProvider` - -A configuration provider that stores mutable values in memory. - -`struct KeyMappingProvider` - -A configuration provider that maps all keys before delegating to an upstream provider. - -- InMemoryProvider -- Mentioned in -- Overview -- Use cases -- Value types -- Performance characteristics -- Usage -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configuring-libraries - -- Configuration -- Configuring libraries - -Article - -# Configuring libraries - -Provide a consistent and flexible way to configure your library. - -## Overview - -Swift Configuration provides a pattern for configuring libraries that works across various configuration sources: environment variables, JSON files, and remote configuration services. - -This guide shows how to adopt this pattern in your library to make it easier to compose in larger applications. - -Adopt this pattern in three steps: - -1. Define your library’s configuration as a dedicated type (you might already have such a type in your library). - -2. Add a convenience method that accepts a `ConfigReader` \- can be an initializer, or a method that updates your configuration. - -3. Extract the individual configuration values using the provided reader. - -This approach makes your library configurable regardless of the user’s chosen configuration source and composes well with other libraries. - -### Define your configuration type - -Start by defining a type that encapsulates all the configuration options for your library. - -/// Configuration options for a hypothetical HTTPClient. -public struct HTTPClientConfiguration { -/// The timeout for network requests in seconds. -public var timeout: Double - -/// The maximum number of concurrent connections. -public var maxConcurrentConnections: Int - -/// Base URL for API requests. -public var baseURL: String - -/// Whether to enable debug logging. -public var debugLogging: Bool - -/// Create a configuration with explicit values. -public init( -timeout: Double = 30.0, -maxConcurrentConnections: Int = 5, -baseURL: String = "https://api.example.com", -debugLogging: Bool = false -) { -self.timeout = timeout -self.maxConcurrentConnections = maxConcurrentConnections -self.baseURL = baseURL -self.debugLogging = debugLogging -} -} - -### Add a convenience method - -Next, extend your configuration type to provide a method that accepts a `ConfigReader` as a parameter. In the example below, we use an initializer. - -extension HTTPClientConfiguration { -/// Creates a new HTTP client configuration using values from the provided reader. -/// -/// ## Configuration keys -/// - `timeout` (double, optional, default: `30.0`): The timeout for network requests in seconds. -/// - `maxConcurrentConnections` (int, optional, default: `5`): The maximum number of concurrent connections. -/// - `baseURL` (string, optional, default: `"https://api.example.com"`): Base URL for API requests. -/// - `debugLogging` (bool, optional, default: `false`): Whether to enable debug logging. -/// -/// - Parameter config: The config reader to read configuration values from. -public init(config: ConfigReader) { -self.timeout = config.double(forKey: "timeout", default: 30.0) -self.maxConcurrentConnections = config.int(forKey: "maxConcurrentConnections", default: 5) -self.baseURL = config.string(forKey: "baseURL", default: "https://api.example.com") -self.debugLogging = config.bool(forKey: "debugLogging", default: false) -} -} - -### Example: Adopting your library - -Once you’ve made your library configurable, users can easily configure it from various sources. Here’s how someone might configure your library using environment variables: - -import Configuration -import YourHTTPLibrary - -// Create a config reader from environment variables. -let config = ConfigReader(provider: EnvironmentVariablesProvider()) - -// Initialize your library's configuration from a config reader. -let httpConfig = HTTPClientConfiguration(config: config) - -// Create your library instance with the configuration. -let httpClient = HTTPClient(configuration: httpConfig) - -// Start using your library. -httpClient.get("/users") { response in -// Handle the response. -} - -With this approach, users can configure your library by setting environment variables that match your config keys: - -# Set configuration for your library through environment variables. -export TIMEOUT=60.0 -export MAX_CONCURRENT_CONNECTIONS=10 -export BASE_URL="https://api.production.com" -export DEBUG_LOGGING=true - -Your library now adapts to the user’s environment without any code changes. - -### Working with secrets - -Mark configuration values that contain sensitive information as secret to prevent them from being logged: - -extension HTTPClientConfiguration { -public init(config: ConfigReader) throws { -self.apiKey = try config.requiredString(forKey: "apiKey", isSecret: true) -// Other configuration... -} -} - -Built-in `AccessReporter` types such as `AccessLogger` and `FileAccessLogger` automatically redact secret values to avoid leaking sensitive information. - -For more guidance on secrets handling, see Handling secrets correctly. For more configuration guidance, check out Adopting best practices. To understand different access patterns and reader methods, refer to Choosing the access pattern and Choosing reader methods. - -## See Also - -### Essentials - -Configuring applications - -Provide flexible and consistent configuration for your application. - -Example use cases - -Review common use cases with ready-to-copy code samples. - -Adopting best practices - -Follow these principles to make your code easily configurable and composable with other libraries. - -- Configuring libraries -- Overview -- Define your configuration type -- Add a convenience method -- Example: Adopting your library -- Working with secrets -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/configsnapshot-implementations - -- Configuration -- YAMLSnapshot -- ConfigSnapshot Implementations - -API Collection - -# ConfigSnapshot Implementations - -## Topics - -### Instance Methods - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/init(data:providername:parsingoptions:) - -#app-main) - -- Configuration -- YAMLSnapshot -- init(data:providerName:parsingOptions:) - -Initializer - -# init(data:providerName:parsingOptions:) - -Inherited from `FileConfigSnapshot.init(data:providerName:parsingOptions:)`. - -convenience init( -data: RawSpan, -providerName: String, -parsingOptions: YAMLSnapshot.ParsingOptions -) throws - -YAMLSnapshot.swift - -## See Also - -### Creating a YAML snapshot - -`struct ParsingOptions` - -Custom input configuration for YAML snapshot creation. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/parsingoptions - -- Configuration -- YAMLSnapshot -- YAMLSnapshot.ParsingOptions - -Structure - -# YAMLSnapshot.ParsingOptions - -Custom input configuration for YAML snapshot creation. - -struct ParsingOptions - -YAMLSnapshot.swift - -## Overview - -This struct provides configuration options for parsing YAML data into configuration snapshots, including byte decoding and secrets specification. - -## Topics - -### Initializers - -Creates custom input configuration for YAML snapshots. - -### Instance Properties - -`var bytesDecoder: any ConfigBytesFromStringDecoder` - -A decoder of bytes from a string. - -A specifier for determining which configuration values should be treated as secrets. - -### Type Properties - -``static var `default`: YAMLSnapshot.ParsingOptions`` - -The default custom input configuration. - -## Relationships - -### Conforms To - -- `FileParsingOptions` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a YAML snapshot - -`convenience init(data: RawSpan, providerName: String, parsingOptions: YAMLSnapshot.ParsingOptions) throws` - -- YAMLSnapshot.ParsingOptions -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest - -- ConfigurationTesting -- ProviderCompatTest - -Structure - -# ProviderCompatTest - -A comprehensive test suite for validating `ConfigProvider` implementations. - -struct ProviderCompatTest - -ProviderCompatTest.swift - -## Overview - -This test suite verifies that configuration providers correctly implement all required functionality including synchronous and asynchronous value retrieval, snapshot operations, and value watching capabilities. - -## Usage - -Create a test instance with your provider and run the compatibility tests: - -let provider = MyCustomProvider() -let test = ProviderCompatTest(provider: provider) -try await test.runTest() - -## Required Test Data - -The provider under test must be populated with specific test values to ensure comprehensive validation. The required configuration data includes: - -\ -"string": String("Hello"),\ -"other.string": String("Other Hello"),\ -"int": Int(42),\ -"other.int": Int(24),\ -"double": Double(3.14),\ -"other.double": Double(2.72),\ -"bool": Bool(true),\ -"other.bool": Bool(false),\ -"bytes": [UInt8,\ -"other.bytes": UInt8,\ -"stringy.array": String,\ -"other.stringy.array": String,\ -"inty.array": Int,\ -"other.inty.array": Int,\ -"doubly.array": Double,\ -"other.doubly.array": Double,\ -"booly.array": Bool,\ -"other.booly.array": Bool,\ -"byteChunky.array": [[UInt8]]([.magic, .magic2]),\ -"other.byteChunky.array": [[UInt8]]([.magic, .magic2, .magic]),\ -] - -## Topics - -### Structures - -`struct TestConfiguration` - -Configuration options for customizing test behavior. - -### Initializers - -`init(provider: any ConfigProvider, configuration: ProviderCompatTest.TestConfiguration)` - -Creates a new compatibility test suite. - -### Instance Methods - -`func runTest() async throws` - -Executes the complete compatibility test suite. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -- ProviderCompatTest -- Overview -- Usage -- Required Test Data -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileconfigsnapshot - -- Configuration -- FileConfigSnapshot - -Protocol - -# FileConfigSnapshot - -A protocol for configuration snapshots created from file data. - -protocol FileConfigSnapshot : ConfigSnapshot, CustomDebugStringConvertible, CustomStringConvertible - -FileProviderSnapshot.swift - -## Overview - -This protocol extends `ConfigSnapshot` to provide file-specific functionality for creating configuration snapshots from raw file data. Types conforming to this protocol can parse various file formats (such as JSON and YAML) and convert them into configuration values. - -Commonly used with `FileProvider` and `ReloadingFileProvider`. - -## Implementation - -To create a custom file configuration snapshot: - -struct MyFormatSnapshot: FileConfigSnapshot { -typealias ParsingOptions = MyParsingOptions - -let values: [String: ConfigValue] -let providerName: String - -init(data: RawSpan, providerName: String, parsingOptions: MyParsingOptions) throws { -self.providerName = providerName -// Parse the data according to your format -self.values = try parseMyFormat(data, using: parsingOptions) -} -} - -The snapshot is responsible for parsing the file data and converting it into a representation of configuration values that can be queried by the configuration system. - -## Topics - -### Required methods - -`init(data: RawSpan, providerName: String, parsingOptions: Self.ParsingOptions) throws` - -Creates a new snapshot from file data. - -**Required** - -`associatedtype ParsingOptions : FileParsingOptions` - -The parsing options type used for parsing this snapshot. - -### Protocol requirements - -`protocol ConfigSnapshot` - -An immutable snapshot of a configuration provider’s state. - -## Relationships - -### Inherits From - -- `ConfigSnapshot` -- `Swift.CustomDebugStringConvertible` -- `Swift.CustomStringConvertible` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -### Conforming Types - -- `JSONSnapshot` -- `YAMLSnapshot` - -- FileConfigSnapshot -- Overview -- Implementation -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/providername - -- Configuration -- YAMLSnapshot -- providerName - -Instance Property - -# providerName - -The name of the provider that created this snapshot. - -let providerName: String - -YAMLSnapshot.swift - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/customdebugstringconvertible-implementations - -- Configuration -- YAMLSnapshot -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/customstringconvertible-implementations - -- Configuration -- YAMLSnapshot -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/fileconfigsnapshot-implementations - -- Configuration -- YAMLSnapshot -- FileConfigSnapshot Implementations - -API Collection - -# FileConfigSnapshot Implementations - -## Topics - -### Initializers - -`convenience init(data: RawSpan, providerName: String, parsingOptions: YAMLSnapshot.ParsingOptions) throws` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accesslogger/accessreporter-implementations - -- Configuration -- AccessLogger -- AccessReporter Implementations - -API Collection - -# AccessReporter Implementations - -## Topics - -### Instance Methods - -`func report(AccessEvent)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/init(data:providername:parsingoptions:) - -#app-main) - -- Configuration -- JSONSnapshot -- init(data:providerName:parsingOptions:) - -Initializer - -# init(data:providerName:parsingOptions:) - -Inherited from `FileConfigSnapshot.init(data:providerName:parsingOptions:)`. - -init( -data: RawSpan, -providerName: String, -parsingOptions: JSONSnapshot.ParsingOptions -) throws - -JSONSnapshot.swift - -## See Also - -### Creating a JSON snapshot - -`struct ParsingOptions` - -Parsing options for JSON snapshot creation. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/customstringconvertible-implementations - -- Configuration -- JSONSnapshot -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/parsingoptions - -- Configuration -- JSONSnapshot -- JSONSnapshot.ParsingOptions - -Structure - -# JSONSnapshot.ParsingOptions - -Parsing options for JSON snapshot creation. - -struct ParsingOptions - -JSONSnapshot.swift - -## Overview - -This struct provides configuration options for parsing JSON data into configuration snapshots, including byte decoding and secrets specification. - -## Topics - -### Initializers - -Creates parsing options for JSON snapshots. - -### Instance Properties - -`var bytesDecoder: any ConfigBytesFromStringDecoder` - -A decoder of bytes from a string. - -A specifier for determining which configuration values should be treated as secrets. - -### Type Properties - -``static var `default`: JSONSnapshot.ParsingOptions`` - -The default parsing options. - -## Relationships - -### Conforms To - -- `FileParsingOptions` -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating a JSON snapshot - -`init(data: RawSpan, providerName: String, parsingOptions: JSONSnapshot.ParsingOptions) throws` - -- JSONSnapshot.ParsingOptions -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/customdebugstringconvertible-implementations - -- Configuration -- JSONSnapshot -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/run() - -#app-main) - -- Configuration -- ReloadingFileProvider -- run() - -Instance Method - -# run() - -Inherited from `Service.run()`. - -func run() async throws - -ReloadingFileProvider.swift - -Available when `Snapshot` conforms to `FileConfigSnapshot`. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/providername - -- Configuration -- JSONSnapshot -- providerName - -Instance Property - -# providerName - -The name of the provider that created this snapshot. - -let providerName: String - -JSONSnapshot.swift - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/fileconfigsnapshot-implementations - -- Configuration -- JSONSnapshot -- FileConfigSnapshot Implementations - -API Collection - -# FileConfigSnapshot Implementations - -## Topics - -### Initializers - -`init(data: RawSpan, providerName: String, parsingOptions: JSONSnapshot.ParsingOptions) throws` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accesslogger/init(logger:level:message:) - -#app-main) - -- Configuration -- AccessLogger -- init(logger:level:message:) - -Initializer - -# init(logger:level:message:) - -Creates a new access logger that reports configuration access events. - -init( -logger: Logger, -level: Logger.Level = .debug, -message: Logger.Message = "Config value accessed" -) - -AccessLogger.swift - -## Parameters - -`logger` - -The logger to emit access events to. - -`level` - -The log level for access events. Defaults to `.debug`. - -`message` - -The static message text for log entries. Defaults to “Config value accessed”. - -## Discussion - -let logger = Logger(label: "my.app.config") - -// Log at debug level by default -let accessLogger = AccessLogger(logger: logger) - -// Customize the log level -let accessLogger = AccessLogger(logger: logger, level: .info) - -- init(logger:level:message:) -- Parameters -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/providername - -- Configuration -- ReloadingFileProvider -- providerName - -Instance Property - -# providerName - -The human-readable name of the provider. - -let providerName: String - -ReloadingFileProvider.swift - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/jsonsnapshot/configsnapshot-implementations - -- Configuration -- JSONSnapshot -- ConfigSnapshot Implementations - -API Collection - -# ConfigSnapshot Implementations - -## Topics - -### Instance Methods - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/init(snapshottype:parsingoptions:filepath:allowmissing:pollinterval:logger:metrics:) - -#app-main) - -- Configuration -- ReloadingFileProvider -- init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:) - -Initializer - -# init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:) - -Creates a reloading file provider that monitors the specified file path. - -convenience init( -snapshotType: Snapshot.Type = Snapshot.self, -parsingOptions: Snapshot.ParsingOptions = .default, -filePath: FilePath, -allowMissing: Bool = false, -pollInterval: Duration = .seconds(15), -logger: Logger = Logger(label: "ReloadingFileProvider"), -metrics: any MetricsFactory = MetricsSystem.factory -) async throws - -ReloadingFileProvider.swift - -## Parameters - -`snapshotType` - -The type of snapshot to create from the file contents. - -`parsingOptions` - -Options used by the snapshot to parse the file data. - -`filePath` - -The path to the configuration file to monitor. - -`allowMissing` - -A flag controlling how the provider handles a missing file. - -- When `false` (the default), if the file is missing or malformed, throws an error. - -- When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. - -`pollInterval` - -How often to check for file changes. - -`logger` - -The logger instance to use for this provider. - -`metrics` - -The metrics factory to use for monitoring provider performance. - -## Discussion - -## See Also - -### Creating a reloading file provider - -`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader, logger: Logger, metrics: any MetricsFactory) async throws` - -Creates a reloading file provider using configuration from a reader. - -- init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/customdebugstringconvertible-implementations - -- Configuration -- ReloadingFileProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/customstringconvertible-implementations - -- Configuration -- ReloadingFileProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/init(snapshottype:parsingoptions:config:) - -#app-main) - -- Configuration -- FileProvider -- init(snapshotType:parsingOptions:config:) - -Initializer - -# init(snapshotType:parsingOptions:config:) - -Creates a file provider using a file path from a configuration reader. - -init( -snapshotType: Snapshot.Type = Snapshot.self, -parsingOptions: Snapshot.ParsingOptions = .default, -config: ConfigReader -) async throws - -FileProvider.swift - -## Parameters - -`snapshotType` - -The type of snapshot to create from the file contents. - -`parsingOptions` - -Options used by the snapshot to parse the file data. - -`config` - -A configuration reader that contains the required configuration keys. - -## Discussion - -This initializer reads the file path from the provided configuration reader and creates a snapshot from that file. - -## Configuration keys - -- `filePath` (string, required): The path to the configuration file to read. - -- `allowMissing` (bool, optional, default: false): A flag controlling how the provider handles a missing file. When `false` (the default), if the file is missing or malformed, throws an error. When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. - -## See Also - -### Creating a file provider - -`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool) async throws` - -Creates a file provider that reads from the specified file path. - -- init(snapshotType:parsingOptions:config:) -- Parameters -- Discussion -- Configuration keys -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/customstringconvertible-implementations - -- Configuration -- FileProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/customdebugstringconvertible-implementations - -- Configuration -- FileProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/init(snapshottype:parsingoptions:filepath:allowmissing:) - -#app-main) - -- Configuration -- FileProvider -- init(snapshotType:parsingOptions:filePath:allowMissing:) - -Initializer - -# init(snapshotType:parsingOptions:filePath:allowMissing:) - -Creates a file provider that reads from the specified file path. - -init( -snapshotType: Snapshot.Type = Snapshot.self, -parsingOptions: Snapshot.ParsingOptions = .default, -filePath: FilePath, -allowMissing: Bool = false -) async throws - -FileProvider.swift - -## Parameters - -`snapshotType` - -The type of snapshot to create from the file contents. - -`parsingOptions` - -Options used by the snapshot to parse the file data. - -`filePath` - -The path to the configuration file to read. - -`allowMissing` - -A flag controlling how the provider handles a missing file. - -- When `false` (the default), if the file is missing or malformed, throws an error. - -- When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. - -## Discussion - -This initializer reads the file at the given path and creates a snapshot using the specified snapshot type. The file is read once during initialization. - -## See Also - -### Creating a file provider - -`init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, config: ConfigReader) async throws` - -Creates a file provider using a file path from a configuration reader. - -- init(snapshotType:parsingOptions:filePath:allowMissing:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/configprovider-implementations - -- Configuration -- ReloadingFileProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/init(environmentvariables:secretsspecifier:bytesdecoder:arrayseparator:) - -#app-main) - -- Configuration -- EnvironmentVariablesProvider -- init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:) - -Initializer - -# init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:) - -Creates a new provider from a custom dictionary of environment variables. - -init( -environmentVariables: [String : String], - -bytesDecoder: some ConfigBytesFromStringDecoder = .base64, -arraySeparator: Character = "," -) - -EnvironmentVariablesProvider.swift - -## Parameters - -`environmentVariables` - -A dictionary of environment variable names and values. - -`secretsSpecifier` - -Specifies which environment variables should be treated as secrets. - -`bytesDecoder` - -The decoder used for converting string values to byte arrays. - -`arraySeparator` - -The character used to separate elements in array values. - -## Discussion - -This initializer allows you to provide a custom set of environment variables, which is useful for testing or when you want to override specific values. - -let customEnvironment = [\ -"DATABASE_HOST": "localhost",\ -"DATABASE_PORT": "5432",\ -"API_KEY": "secret-key"\ -] -let provider = EnvironmentVariablesProvider( -environmentVariables: customEnvironment, -secretsSpecifier: .specific(["API_KEY"]) -) - -## See Also - -### Creating an environment variable provider - -Creates a new provider that reads from the current process environment. - -Creates a new provider that reads from an environment file. - -- init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/context - -- Configuration -- AbsoluteConfigKey -- context - -Instance Property - -# context - -Additional context information for this configuration key. - -var context: [String : ConfigContextValue] - -ConfigKey.swift - -## Discussion - -Context provides extra information that providers can use to refine lookups or return more specific values. Not all providers use context information. - -## See Also - -### Inspecting an absolute configuration key - -[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/components) - -The hierarchical components that make up this absolute configuration key. - -- context -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/customstringconvertible-implementations - -- Configuration -- CommandLineArgumentsProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/watchint(forkey:issecret:fileid:line:updateshandler:) - -#app-main) - -- Configuration -- ConfigReader -- watchInt(forKey:isSecret:fileID:line:updatesHandler:) - -Instance Method - -# watchInt(forKey:isSecret:fileID:line:updatesHandler:) - -Watches for updates to a config value for the given config key. - -forKey key: ConfigKey, -isSecret: Bool = false, -fileID: String = #fileID, -line: UInt = #line, - -ConfigReader+methods.swift - -## Parameters - -`key` - -The config key to watch. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -`updatesHandler` - -A closure that handles an async sequence of updates to the value. The sequence produces `nil` if the value is missing or can’t be converted. - -## Return Value - -The result produced by the handler. - -## Mentioned in - -Example use cases - -## Discussion - -Use this method to observe changes to optional configuration values over time. The handler receives an async sequence that produces the current value whenever it changes, or `nil` if the value is missing or can’t be converted. - -try await config.watchInt(forKey: ["server", "port"]) { updates in -for await port in updates { -if let port = port { -print("Server port is: \(port)") -} else { -print("No server port configured") -} -} -} - -## See Also - -### Watching integer values - -Watches for updates to a config value for the given config key with default fallback. - -- watchInt(forKey:isSecret:fileID:line:updatesHandler:) -- Parameters -- Return Value -- Mentioned in -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/service-implementations - -- Configuration -- ReloadingFileProvider -- Service Implementations - -API Collection - -# Service Implementations - -## Topics - -### Instance Methods - -`func run() async throws` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/customstringconvertible-implementations - -- Configuration -- ConfigKey -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-6vten - --6vten#app-main) - -- Configuration -- ConfigKey -- init(\_:context:) - -Initializer - -# init(\_:context:) - -Creates a new configuration key. - -init( -_ string: String, -context: [String : ConfigContextValue] = [:] -) - -ConfigKey.swift - -## Parameters - -`string` - -The string representation of the key path, for example `"http.timeout"`. - -`context` - -Additional context information for the key. - -## See Also - -### Creating a configuration key - -[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-9ifez) - -- init(\_:context:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/environmentvalue(forname:) - -#app-main) - -- Configuration -- EnvironmentVariablesProvider -- environmentValue(forName:) - -Instance Method - -# environmentValue(forName:) - -Returns the raw string value for a specific environment variable name. - -EnvironmentVariablesProvider.swift - -## Parameters - -`name` - -The exact name of the environment variable to retrieve. - -## Return Value - -The string value of the environment variable, or nil if not found. - -## Discussion - -This method provides direct access to environment variable values by name, without any key transformation or type conversion. It’s useful when you need to access environment variables that don’t follow the standard configuration key naming conventions. - -let provider = EnvironmentVariablesProvider() -let path = try provider.environmentValue(forName: "PATH") -let home = try provider.environmentValue(forName: "HOME") - -- environmentValue(forName:) -- Parameters -- Return Value -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/init(environmentfilepath:allowmissing:secretsspecifier:bytesdecoder:arrayseparator:) - -#app-main) - -- Configuration -- EnvironmentVariablesProvider -- init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:) - -Initializer - -# init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:) - -Creates a new provider that reads from an environment file. - -init( -environmentFilePath: FilePath, -allowMissing: Bool = false, - -bytesDecoder: some ConfigBytesFromStringDecoder = .base64, -arraySeparator: Character = "," -) async throws - -EnvironmentVariablesProvider.swift - -## Parameters - -`environmentFilePath` - -The file system path to the environment file to load. - -`allowMissing` - -A flag controlling how the provider handles a missing file. - -- When `false` (the default), if the file is missing or malformed, throws an error. - -- When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. - -`secretsSpecifier` - -Specifies which environment variables should be treated as secrets. - -`bytesDecoder` - -The decoder used for converting string values to byte arrays. - -`arraySeparator` - -The character used to separate elements in array values. - -## Discussion - -This initializer loads environment variables from an `.env` file at the specified path. The file should contain key-value pairs in the format `KEY=value`, one per line. Comments (lines starting with `#`) and empty lines are ignored. - -// Load from a .env file -let provider = try await EnvironmentVariablesProvider( -environmentFilePath: ".env", -allowMissing: true, -secretsSpecifier: .specific(["API_KEY"]) -) - -## See Also - -### Creating an environment variable provider - -Creates a new provider that reads from the current process environment. - -Creates a new provider from a custom dictionary of environment variables. - -- init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/customstringconvertible-implementations - -- Configuration -- EnvironmentVariablesProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/init(upstream:keymapper:) - -#app-main) - -- Configuration -- KeyMappingProvider -- init(upstream:keyMapper:) - -Initializer - -# init(upstream:keyMapper:) - -Creates a new provider. - -init( -upstream: Upstream, - -) - -KeyMappingProvider.swift - -## Parameters - -`upstream` - -The upstream provider to delegate to after mapping. - -`mapKey` - -A closure to remap configuration keys. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configprovider/prefixkeys(with:) - -#app-main) - -- Configuration -- ConfigProvider -- prefixKeys(with:) - -Instance Method - -# prefixKeys(with:) - -Creates a new prefixed configuration provider. - -ConfigProvider+Operators.swift - -## Return Value - -A provider which prefixes keys with the given prefix. - -## Discussion - -- Parameter: prefix: The configuration key to prepend to all configuration keys. - -## See Also - -### Conveniences - -Implements `watchValue` by getting the current value and emitting it immediately. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Creates a new configuration provider where each key is rewritten by the given closure. - -- prefixKeys(with:) -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/customdebugstringconvertible-implementations - -- Configuration -- EnvironmentVariablesProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileprovider/configprovider-implementations - -- Configuration -- FileProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Properties - -`var providerName: String` - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/reloadingfileprovider/init(snapshottype:parsingoptions:config:logger:metrics:) - -#app-main) - -- Configuration -- ReloadingFileProvider -- init(snapshotType:parsingOptions:config:logger:metrics:) - -Initializer - -# init(snapshotType:parsingOptions:config:logger:metrics:) - -Creates a reloading file provider using configuration from a reader. - -convenience init( -snapshotType: Snapshot.Type = Snapshot.self, -parsingOptions: Snapshot.ParsingOptions = .default, -config: ConfigReader, -logger: Logger = Logger(label: "ReloadingFileProvider"), -metrics: any MetricsFactory = MetricsSystem.factory -) async throws - -ReloadingFileProvider.swift - -## Parameters - -`snapshotType` - -The type of snapshot to create from the file contents. - -`parsingOptions` - -Options used by the snapshot to parse the file data. - -`config` - -A configuration reader that contains the required configuration keys. - -`logger` - -The logger instance to use for this provider. - -`metrics` - -The metrics factory to use for monitoring provider performance. - -## Configuration keys - -- `filePath` (string, required): The path to the configuration file to monitor. - -- `allowMissing` (bool, optional, default: false): A flag controlling how the provider handles a missing file. When `false` (the default), if the file is missing or malformed, throws an error. When `true`, if the file is missing, treats it as empty. Malformed files still throw an error. - -- `pollIntervalSeconds` (int, optional, default: 15): How often to check for file changes in seconds. - -## See Also - -### Creating a reloading file provider - -`convenience init(snapshotType: Snapshot.Type, parsingOptions: Snapshot.ParsingOptions, filePath: FilePath, allowMissing: Bool, pollInterval: Duration, logger: Logger, metrics: any MetricsFactory) async throws` - -Creates a reloading file provider that monitors the specified file path. - -- init(snapshotType:parsingOptions:config:logger:metrics:) -- Parameters -- Configuration keys -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/equatable-implementations - -- Configuration -- ConfigKey -- Equatable Implementations - -API Collection - -# Equatable Implementations - -## Topics - -### Operators - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/expressiblebyextendedgraphemeclusterliteral-implementations - -- Configuration -- ConfigKey -- ExpressibleByExtendedGraphemeClusterLiteral Implementations - -API Collection - -# ExpressibleByExtendedGraphemeClusterLiteral Implementations - -## Topics - -### Initializers - -`init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/comparable-implementations - -- Configuration -- ConfigKey -- Comparable Implementations - -API Collection - -# Comparable Implementations - -## Topics - -### Operators - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-9ifez - --9ifez#app-main) - -- Configuration -- ConfigKey -- init(\_:context:) - -Initializer - -# init(\_:context:) - -Creates a new configuration key. - -init( -_ components: [String], -context: [String : ConfigContextValue] = [:] -) - -ConfigKey.swift - -## Parameters - -`components` - -The hierarchical components that make up the key path. - -`context` - -Additional context information for the key. - -## See Also - -### Creating a configuration key - -[`init(String, context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/init(_:context:)-6vten) - -- init(\_:context:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/customdebugstringconvertible-implementations - -- Configuration -- KeyMappingProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/init(arguments:secretsspecifier:bytesdecoder:) - -#app-main) - -- Configuration -- CommandLineArgumentsProvider -- init(arguments:secretsSpecifier:bytesDecoder:) - -Initializer - -# init(arguments:secretsSpecifier:bytesDecoder:) - -Creates a new CLI provider with the provided arguments. - -init( -arguments: [String] = CommandLine.arguments, - -bytesDecoder: some ConfigBytesFromStringDecoder = .base64 -) - -CommandLineArgumentsProvider.swift - -## Parameters - -`arguments` - -The command-line arguments to parse. - -`secretsSpecifier` - -Specifies which CLI arguments should be treated as secret. - -`bytesDecoder` - -The decoder used for converting string values into bytes. - -## Discussion - -// Uses the current process's arguments. -let provider = CommandLineArgumentsProvider() -// Uses custom arguments. -let provider = CommandLineArgumentsProvider(arguments: ["program", "--test", "--port", "8089"]) - -- init(arguments:secretsSpecifier:bytesDecoder:) -- Parameters -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromhexstringdecoder/configbytesfromstringdecoder-implementations - -- Configuration -- ConfigBytesFromHexStringDecoder -- ConfigBytesFromStringDecoder Implementations - -API Collection - -# ConfigBytesFromStringDecoder Implementations - -## Topics - -### Type Properties - -`static var hex: ConfigBytesFromHexStringDecoder` - -A decoder that interprets string values as hexadecimal-encoded data. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/init(name:initialvalues:) - -#app-main) - -- Configuration -- MutableInMemoryProvider -- init(name:initialValues:) - -Initializer - -# init(name:initialValues:) - -Creates a new mutable in-memory provider with the specified initial values. - -init( -name: String? = nil, -initialValues: [AbsoluteConfigKey : ConfigValue] -) - -MutableInMemoryProvider.swift - -## Parameters - -`name` - -An optional name for the provider, used in debugging and logging. - -`initialValues` - -A dictionary mapping absolute configuration keys to their initial values. - -## Discussion - -This initializer takes a dictionary of absolute configuration keys mapped to their initial values. The provider can be modified after creation using the `setValue(_:forKey:)` methods. - -let key1 = AbsoluteConfigKey(components: ["database", "host"], context: [:]) -let key2 = AbsoluteConfigKey(components: ["database", "port"], context: [:]) - -let provider = MutableInMemoryProvider( -name: "dynamic-config", -initialValues: [\ -key1: "localhost",\ -key2: 5432\ -] -) - -// Later, update values dynamically -provider.setValue("production-db", forKey: key1) - -- init(name:initialValues:) -- Parameters -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/expressiblebyarrayliteral-implementations - -- Configuration -- ConfigKey -- ExpressibleByArrayLiteral Implementations - -API Collection - -# ExpressibleByArrayLiteral Implementations - -## Topics - -### Initializers - -`init(arrayLiteral: String...)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/configprovider-implementations - -- Configuration -- EnvironmentVariablesProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Properties - -`var providerName: String` - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/context - -- Configuration -- ConfigKey -- context - -Instance Property - -# context - -Additional context information for this configuration key. - -var context: [String : ConfigContextValue] - -ConfigKey.swift - -## Discussion - -Context provides extra information that providers can use to refine lookups or return more specific values. Not all providers use context information. - -## See Also - -### Inspecting a configuration key - -[`var components: [String]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/components) - -The hierarchical components that make up this configuration key. - -- context -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessreporter/report(_:) - -#app-main) - -- Configuration -- AccessReporter -- report(\_:) - -Instance Method - -# report(\_:) - -Processes a configuration access event. - -func report(_ event: AccessEvent) - -AccessReporter.swift - -**Required** - -## Parameters - -`event` - -The configuration access event to process. - -## Discussion - -This method is called whenever a configuration value is accessed through a `ConfigReader` or a `ConfigSnapshotReader`. Implementations should handle events efficiently as they may be called frequently. - -- report(\_:) -- Parameters -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/customdebugstringconvertible-implementations - -- Configuration -- CommandLineArgumentsProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.doubleArray(\_:) - -Case - -# ConfigContent.doubleArray(\_:) - -An array of double values. - -case doubleArray([Double]) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/expressiblebyextendedgraphemeclusterliteral-implementations - -- Configuration -- ConfigContextValue -- ExpressibleByExtendedGraphemeClusterLiteral Implementations - -API Collection - -# ExpressibleByExtendedGraphemeClusterLiteral Implementations - -## Topics - -### Initializers - -`init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/specific(_:) - -#app-main) - -- Configuration -- SecretsSpecifier -- SecretsSpecifier.specific(\_:) - -Case - -# SecretsSpecifier.specific(\_:) - -The library treats the specified keys as secrets. - -SecretsSpecifier.swift - -## Parameters - -`keys` - -The set of keys that should be treated as secrets. - -## Discussion - -Use this case when you have a known set of keys that contain sensitive information. All other keys will be treated as non-secret. - -## See Also - -### Types of specifiers - -`case all` - -The library treats all configuration values as secrets. - -The library determines the secret status dynamically by evaluating each key-value pair. - -`case none` - -The library treats no configuration values as secrets. - -- SecretsSpecifier.specific(\_:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileconfigsnapshot/init(data:providername:parsingoptions:) - -# An unknown error occurred. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/init(directorypath:allowmissing:secretsspecifier:arrayseparator:) - -#app-main) - -- Configuration -- DirectoryFilesProvider -- init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:) - -Initializer - -# init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:) - -Creates a new provider that reads files from a directory. - -init( -directoryPath: FilePath, -allowMissing: Bool = false, - -arraySeparator: Character = "," -) async throws - -DirectoryFilesProvider.swift - -## Parameters - -`directoryPath` - -The file system path to the directory containing configuration files. - -`allowMissing` - -A flag controlling how the provider handles a missing directory. - -- When `false`, if the directory is missing, throws an error. - -- When `true`, if the directory is missing, treats it as empty. - -`secretsSpecifier` - -Specifies which values should be treated as secrets. - -`arraySeparator` - -The character used to separate elements in array values. - -## Discussion - -This initializer scans the specified directory and loads all regular files as configuration values. Subdirectories are not traversed. Hidden files (starting with a dot) are skipped. - -// Load configuration from a directory -let provider = try await DirectoryFilesProvider( -directoryPath: "/run/secrets" -) - -- init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:) -- Parameters -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/string - -- Configuration -- ConfigType -- ConfigType.string - -Case - -# ConfigType.string - -A string value. - -case string - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case stringArray` - -An array of string values. - -`case bool` - -A Boolean value. - -`case boolArray` - -An array of Boolean values. - -`case int` - -An integer value. - -`case intArray` - -An array of integer values. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/string(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.string(\_:) - -Case - -# ConfigContent.string(\_:) - -A string value. - -case string(String) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/configprovider-implementations - -- Configuration -- KeyMappingProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Properties - -`var providerName: String` - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.boolArray(\_:) - -Case - -# ConfigContent.boolArray(\_:) - -An array of Boolean value. - -case boolArray([Bool]) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/init(metadata:providerresults:conversionerror:result:) - -#app-main) - -- Configuration -- AccessEvent -- init(metadata:providerResults:conversionError:result:) - -Initializer - -# init(metadata:providerResults:conversionError:result:) - -Creates a configuration access event. - -init( -metadata: AccessEvent.Metadata, -providerResults: [AccessEvent.ProviderResult], -conversionError: (any Error)? = nil, - -AccessReporter.swift - -## Parameters - -`metadata` - -Metadata describing the access operation. - -`providerResults` - -The results from each provider queried. - -`conversionError` - -An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. - -`result` - -The final outcome of the access operation. - -## See Also - -### Creating an access event - -`struct Metadata` - -Metadata describing the configuration access operation. - -`struct ProviderResult` - -The result of a configuration lookup from a specific provider. - -- init(metadata:providerResults:conversionError:result:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/setvalue(_:forkey:) - -#app-main) - -- Configuration -- MutableInMemoryProvider -- setValue(\_:forKey:) - -Instance Method - -# setValue(\_:forKey:) - -Updates the stored value for the specified configuration key. - -func setValue( -_ value: ConfigValue?, -forKey key: AbsoluteConfigKey -) - -MutableInMemoryProvider.swift - -## Parameters - -`value` - -The new configuration value, or `nil` to remove the value entirely. - -`key` - -The absolute configuration key to update. - -## Discussion - -This method atomically updates the value and notifies all active watchers of the change. If the new value is the same as the existing value, no notification is sent. - -let provider = MutableInMemoryProvider(initialValues: [:]) -let key = AbsoluteConfigKey(components: ["api", "enabled"], context: [:]) - -// Set a new value -provider.setValue(true, forKey: key) - -// Remove a value -provider.setValue(nil, forKey: key) - -- setValue(\_:forKey:) -- Parameters -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/fileparsingoptions/default - -- Configuration -- FileParsingOptions -- default - -Type Property - -# default - -The default instance of this options type. - -static var `default`: Self { get } - -FileProviderSnapshot.swift - -**Required** - -## Discussion - -This property provides a default configuration that can be used when no parsing options are specified. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/environmentvariablesprovider/init(secretsspecifier:bytesdecoder:arrayseparator:) - -#app-main) - -- Configuration -- EnvironmentVariablesProvider -- init(secretsSpecifier:bytesDecoder:arraySeparator:) - -Initializer - -# init(secretsSpecifier:bytesDecoder:arraySeparator:) - -Creates a new provider that reads from the current process environment. - -init( - -bytesDecoder: some ConfigBytesFromStringDecoder = .base64, -arraySeparator: Character = "," -) - -EnvironmentVariablesProvider.swift - -## Parameters - -`secretsSpecifier` - -Specifies which environment variables should be treated as secrets. - -`bytesDecoder` - -The decoder used for converting string values to byte arrays. - -`arraySeparator` - -The character used to separate elements in array values. - -## Discussion - -This initializer creates a provider that sources configuration values from the environment variables of the current process. - -// Basic usage -let provider = EnvironmentVariablesProvider() - -// With secret handling -let provider = EnvironmentVariablesProvider( -secretsSpecifier: .specific(["API_KEY", "DATABASE_PASSWORD"]) -) - -## See Also - -### Creating an environment variable provider - -Creates a new provider from a custom dictionary of environment variables. - -Creates a new provider that reads from an environment file. - -- init(secretsSpecifier:bytesDecoder:arraySeparator:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/expressiblebystringliteral-implementations - -- Configuration -- ConfigKey -- ExpressibleByStringLiteral Implementations - -API Collection - -# ExpressibleByStringLiteral Implementations - -## Topics - -### Initializers - -`init(extendedGraphemeClusterLiteral: Self.StringLiteralType)` - -`init(stringLiteral: String)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/components - -- Configuration -- ConfigKey -- components - -Instance Property - -# components - -The hierarchical components that make up this configuration key. - -var components: [String] - -ConfigKey.swift - -## Discussion - -Each component represents a level in the configuration hierarchy. For example, `["database", "connection", "timeout"]` represents a three-level nested key. - -## See Also - -### Inspecting a configuration key - -[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configkey/context) - -Additional context information for this configuration key. - -- components -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/init(_:) - -#app-main) - -- Configuration -- ConfigUpdatesAsyncSequence -- init(\_:) - -Initializer - -# init(\_:) - -Creates a new concrete async sequence wrapping the provided existential sequence. - -AsyncSequences.swift - -## Parameters - -`upstream` - -The async sequence to wrap. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation/uuid - -- Configuration -- Foundation -- UUID - -Extended Structure - -# UUID - -ConfigurationFoundation - -extension UUID - -## Topics - -## Relationships - -### Conforms To - -- `ExpressibleByConfigString` -- `Swift.Copyable` -- `Swift.CustomStringConvertible` - -- UUID -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/customstringconvertible-implementations - -- Configuration -- MutableInMemoryProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfrombase64stringdecoder/init() - -#app-main) - -- Configuration -- ConfigBytesFromBase64StringDecoder -- init() - -Initializer - -# init() - -Creates a new base64 decoder. - -init() - -ConfigBytesFromStringDecoder.swift - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/commandlineargumentsprovider/configprovider-implementations - -- Configuration -- CommandLineArgumentsProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Properties - -`var providerName: String` - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/customstringconvertible-implementations - -- Configuration -- ConfigValue -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/string(forkey:as:issecret:fileid:line:)-4oust - --4oust#app-main) - -- Configuration -- ConfigReader -- string(forKey:as:isSecret:fileID:line:) - -Instance Method - -# string(forKey:as:isSecret:fileID:line:) - -Synchronously gets a config value for the given config key, converting from string. - -forKey key: ConfigKey, -as type: Value.Type = Value.self, -isSecret: Bool = false, -fileID: String = #fileID, -line: UInt = #line - -ConfigReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`type` - -The type to convert the string value to. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The value converted to the expected type if found and convertible, otherwise `nil`. - -## Discussion - -Use this method to retrieve configuration values that can be converted from strings, such as custom types conforming to string conversion protocols. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. - -let serverMode = config.string(forKey: ["server", "mode"], as: ServerMode.self) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -- string(forKey:as:isSecret:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.bytes(\_:) - -Case - -# ConfigContent.bytes(\_:) - -An array of bytes. - -case bytes([UInt8]) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/content - -- Configuration -- ConfigValue -- content - -Instance Property - -# content - -The configuration content. - -var content: ConfigContent - -ConfigProvider.swift - -## See Also - -### Inspecting a config value - -`var isSecret: Bool` - -Whether this value contains sensitive information that should not be logged. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/watchsnapshot(fileid:line:updateshandler:) - -#app-main) - -- Configuration -- ConfigReader -- watchSnapshot(fileID:line:updatesHandler:) - -Instance Method - -# watchSnapshot(fileID:line:updatesHandler:) - -Watches the configuration for changes. - -fileID: String = #fileID, -line: UInt = #line, - -ConfigSnapshotReader.swift - -## Parameters - -`fileID` - -The file where this method is called from. - -`line` - -The line where this method is called from. - -`updatesHandler` - -A closure that receives an async sequence of `ConfigSnapshotReader` instances. - -## Return Value - -The value returned by the handler. - -## Discussion - -This method watches the configuration for changes and provides a stream of snapshots to the handler closure. Each snapshot represents the configuration state at a specific point in time. - -try await config.watchSnapshot { snapshots in -for await snapshot in snapshots { -// Process each new configuration snapshot -let cert = snapshot.string(forKey: "cert") -let privateKey = snapshot.string(forKey: "privateKey") -// Ensures that both values are coming from the same underlying snapshot and that a provider -// didn't change its internal state between the two `string(...)` calls. -let newCert = MyCert(cert: cert, privateKey: privateKey) -print("Certificate was updated: \(newCert.redactedDescription)") -} -} - -## See Also - -### Reading from a snapshot - -Returns a snapshot of the current configuration state. - -- watchSnapshot(fileID:line:updatesHandler:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/configprovider-implementations - -- Configuration -- MutableInMemoryProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Properties - -`var providerName: String` - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/expressiblebybooleanliteral-implementations - -- Configuration -- ConfigValue -- ExpressibleByBooleanLiteral Implementations - -API Collection - -# ExpressibleByBooleanLiteral Implementations - -## Topics - -### Initializers - -`init(booleanLiteral: Bool)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/configprovider-implementations - -- Configuration -- DirectoryFilesProvider -- ConfigProvider Implementations - -API Collection - -# ConfigProvider Implementations - -## Topics - -### Instance Properties - -`var providerName: String` - -### Instance Methods - -Creates a new configuration provider where each key is rewritten by the given closure. - -Creates a new prefixed configuration provider. - -Implements `watchSnapshot` by getting the current snapshot and emitting it immediately. - -Implements `watchValue` by getting the current value and emitting it immediately. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/int(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.int(\_:) - -Case - -# ConfigContent.int(\_:) - -An integer value. - -case int(Int) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/none - -- Configuration -- SecretsSpecifier -- SecretsSpecifier.none - -Case - -# SecretsSpecifier.none - -The library treats no configuration values as secrets. - -case none - -SecretsSpecifier.swift - -## Discussion - -Use this case when the provider handles only non-sensitive configuration data that can be safely logged or displayed. - -## See Also - -### Types of specifiers - -`case all` - -The library treats all configuration values as secrets. - -The library treats the specified keys as secrets. - -The library determines the secret status dynamically by evaluating each key-value pair. - -- SecretsSpecifier.none -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.byteChunkArray(\_:) - -Case - -# ConfigContent.byteChunkArray(\_:) - -An array of byte arrays. - -case byteChunkArray([[UInt8]]) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/issecret - -- Configuration -- ConfigValue -- isSecret - -Instance Property - -# isSecret - -Whether this value contains sensitive information that should not be logged. - -var isSecret: Bool - -ConfigProvider.swift - -## See Also - -### Inspecting a config value - -`var content: ConfigContent` - -The configuration content. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromhexstringdecoder/init() - -#app-main) - -- Configuration -- ConfigBytesFromHexStringDecoder -- init() - -Initializer - -# init() - -Creates a new hexadecimal decoder. - -init() - -ConfigBytesFromStringDecoder.swift - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/expressiblebybooleanliteral-implementations - -- Configuration -- ConfigContextValue -- ExpressibleByBooleanLiteral Implementations - -API Collection - -# ExpressibleByBooleanLiteral Implementations - -## Topics - -### Initializers - -`init(booleanLiteral: Bool)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/result - -- Configuration -- AccessEvent -- result - -Instance Property - -# result - -The final outcome of the configuration access operation. - -AccessReporter.swift - -## Discussion - -## See Also - -### Inspecting an access event - -`var conversionError: (any Error)?` - -An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. - -`var metadata: AccessEvent.Metadata` - -Metadata that describes the configuration access operation. - -[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) - -The results from each configuration provider that was queried. - -- result -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/scoped(to:) - -#app-main) - -- Configuration -- ConfigSnapshotReader -- scoped(to:) - -Instance Method - -# scoped(to:) - -Returns a scoped snapshot reader by appending the provided key to the current key prefix. - -ConfigSnapshotReader.swift - -## Parameters - -`configKey` - -The key to append to the current key prefix. - -## Return Value - -A reader for accessing scoped values. - -## Discussion - -Use this method to create a reader that accesses a subset of the configuration. - -let httpConfig = snapshotReader.scoped(to: ["client", "http"]) -let timeout = httpConfig.int(forKey: "timeout") // Reads from "client.http.timeout" in the snapshot - -- scoped(to:) -- Parameters -- Return Value -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter/accessreporter-implementations - -- Configuration -- BroadcastingAccessReporter -- AccessReporter Implementations - -API Collection - -# AccessReporter Implementations - -## Topics - -### Instance Methods - -`func report(AccessEvent)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:fileid:line:)-7bpif - --7bpif#app-main) - -- Configuration -- ConfigSnapshotReader -- string(forKey:as:isSecret:fileID:line:) - -Instance Method - -# string(forKey:as:isSecret:fileID:line:) - -Synchronously gets a config value for the given config key, converting from string. - -forKey key: ConfigKey, -as type: Value.Type = Value.self, -isSecret: Bool = false, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`type` - -The type to convert the string value to. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The value converted to the expected type if found and convertible, otherwise `nil`. - -## Discussion - -Use this method to retrieve configuration values that can be converted from strings, such as custom types conforming to string conversion protocols. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. - -let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -- string(forKey:as:isSecret:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/customstringconvertible-implementations - -- Configuration -- AbsoluteConfigKey -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/keymappingprovider/customstringconvertible-implementations - -- Configuration -- KeyMappingProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/bool(_:) - -#app-main) - -- Configuration -- ConfigContextValue -- ConfigContextValue.bool(\_:) - -Case - -# ConfigContextValue.bool(\_:) - -A Boolean value. - -case bool(Bool) - -ConfigContext.swift - -## See Also - -### Configuration context values - -`case string(String)` - -A string value. - -`case int(Int)` - -An integer value. - -`case double(Double)` - -A floating point value. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader-fetch - -- Configuration -- ConfigReader -- Asynchronously fetching values - -API Collection - -# Asynchronously fetching values - -## Topics - -### Asynchronously fetching string values - -Asynchronously fetches a config value for the given config key. - -Asynchronously fetches a config value for the given config key, with a default fallback. - -Asynchronously fetches a config value for the given config key, converting from string. - -Asynchronously fetches a config value for the given config key with default fallback, converting from string. - -### Asynchronously fetching lists of string values - -Asynchronously fetches an array of config values for the given config key, converting from strings. - -Asynchronously fetches an array of config values for the given config key with default fallback, converting from strings. - -### Asynchronously fetching required string values - -Asynchronously fetches a required config value for the given config key, throwing an error if it’s missing. - -Asynchronously fetches a required config value for the given config key, converting from string. - -### Asynchronously fetching required lists of string values - -Asynchronously fetches a required array of config values for the given config key, converting from strings. - -### Asynchronously fetching Boolean values - -### Asynchronously fetching required Boolean values - -### Asynchronously fetching lists of Boolean values - -### Asynchronously fetching required lists of Boolean values - -### Asynchronously fetching integer values - -### Asynchronously fetching required integer values - -### Asynchronously fetching lists of integer values - -### Asynchronously fetching required lists of integer values - -### Asynchronously fetching double values - -### Asynchronously fetching required double values - -### Asynchronously fetching lists of double values - -### Asynchronously fetching required lists of double values - -### Asynchronously fetching bytes - -### Asynchronously fetching required bytes - -### Asynchronously fetching lists of byte chunks - -### Asynchronously fetching required lists of byte chunks - -## See Also - -### Reading from a snapshot - -Returns a snapshot of the current configuration state. - -Watches the configuration for changes. - -- Asynchronously fetching values -- Topics -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader-watch - -- Configuration -- ConfigReader -- Watching values - -API Collection - -# Watching values - -## Topics - -### Watching string values - -Watches for updates to a config value for the given config key. - -Watches for updates to a config value for the given config key, converting from string. - -Watches for updates to a config value for the given config key with default fallback. - -Watches for updates to a config value for the given config key with default fallback, converting from string. - -### Watching required string values - -Watches for updates to a required config value for the given config key. - -Watches for updates to a required config value for the given config key, converting from string. - -### Watching lists of string values - -Watches for updates to an array of config values for the given config key, converting from strings. - -Watches for updates to an array of config values for the given config key with default fallback, converting from strings. - -### Watching required lists of string values - -Watches for updates to a required array of config values for the given config key, converting from strings. - -### Watching Boolean values - -### Watching required Boolean values - -### Watching lists of Boolean values - -### Watching required lists of Boolean values - -### Watching integer values - -### Watching required integer values - -### Watching lists of integer values - -### Watching required lists of integer values - -### Watching double values - -### Watching required double values - -### Watching lists of double values - -### Watching required lists of double values - -### Watching bytes - -### Watching required bytes - -### Watching lists of byte chunks - -### Watching required lists of byte chunks - -## See Also - -### Reading from a snapshot - -Returns a snapshot of the current configuration state. - -Watches the configuration for changes. - -- Watching values -- Topics -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/yamlsnapshot/parsingoptions/init(bytesdecoder:secretsspecifier:) - -#app-main) - -- Configuration -- YAMLSnapshot -- YAMLSnapshot.ParsingOptions -- init(bytesDecoder:secretsSpecifier:) - -Initializer - -# init(bytesDecoder:secretsSpecifier:) - -Creates custom input configuration for YAML snapshots. - -init( -bytesDecoder: some ConfigBytesFromStringDecoder = .base64, - -) - -YAMLSnapshot.swift - -## Parameters - -`bytesDecoder` - -The decoder to use for converting string values to byte arrays. - -`secretsSpecifier` - -The specifier for identifying secret values. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:default:fileid:line:)-2mphx - --2mphx#app-main) - -- Configuration -- ConfigSnapshotReader -- string(forKey:as:isSecret:default:fileID:line:) - -Instance Method - -# string(forKey:as:isSecret:default:fileID:line:) - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -forKey key: ConfigKey, -as type: Value.Type = Value.self, -isSecret: Bool = false, -default defaultValue: Value, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`type` - -The type to convert the string value to. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`defaultValue` - -The fallback value returned when the config value is missing or invalid. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The config value if found and convertible, otherwise the default value. - -## Discussion - -Use this method when you need a guaranteed non-nil result for string-convertible types. If the configuration value is missing or can’t be converted to the expected type, the default value is returned instead. - -let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self, default: .production) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key, converting from string. - -- string(forKey:as:isSecret:default:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/conversionerror - -- Configuration -- AccessEvent -- conversionError - -Instance Property - -# conversionError - -An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. - -var conversionError: (any Error)? - -AccessReporter.swift - -## See Also - -### Inspecting an access event - -The final outcome of the configuration access operation. - -`var metadata: AccessEvent.Metadata` - -Metadata that describes the configuration access operation. - -[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) - -The results from each configuration provider that was queried. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configbytesfromstringdecoder/decode(_:) - -#app-main) - -- Configuration -- ConfigBytesFromStringDecoder -- decode(\_:) - -Instance Method - -# decode(\_:) - -Decodes a string value into an array of bytes. - -ConfigBytesFromStringDecoder.swift - -**Required** - -## Parameters - -`value` - -The string representation to decode. - -## Return Value - -An array of bytes if decoding succeeds, or `nil` if it fails. - -## Discussion - -This method attempts to parse the provided string according to the decoder’s specific format and returns the corresponding byte array. If the string cannot be decoded (due to invalid format or encoding), the method returns `nil`. - -- decode(\_:) -- Parameters -- Return Value -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader-get - -- Configuration -- ConfigReader -- Synchronously reading values - -API Collection - -# Synchronously reading values - -## Topics - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key, converting from string. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -### Synchronously reading lists of string values - -Synchronously gets an array of config values for the given config key, converting from strings. - -Synchronously gets an array of config values for the given config key with default fallback, converting from strings. - -### Synchronously reading required string values - -Synchronously gets a required config value for the given config key, throwing an error if it’s missing. - -Synchronously gets a required config value for the given config key, converting from string. - -### Synchronously reading required lists of string values - -Synchronously gets a required array of config values for the given config key, converting from strings. - -### Synchronously reading Boolean values - -### Synchronously reading required Boolean values - -### Synchronously reading lists of Boolean values - -### Synchronously reading required lists of Boolean values - -### Synchronously reading integer values - -### Synchronously reading required integer values - -### Synchronously reading lists of integer values - -### Synchronously reading required lists of integer values - -### Synchronously reading double values - -### Synchronously reading required double values - -### Synchronously reading lists of double values - -### Synchronously reading required lists of double values - -### Synchronously reading bytes - -### Synchronously reading required bytes - -### Synchronously reading collections of byte chunks - -### Synchronously reading required collections of byte chunks - -## See Also - -### Reading from a snapshot - -Returns a snapshot of the current configuration state. - -Watches the configuration for changes. - -- Synchronously reading values -- Topics -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.intArray(\_:) - -Case - -# ConfigContent.intArray(\_:) - -An array of integer values. - -case intArray([Int]) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation/url - -- Configuration -- Foundation -- URL - -Extended Structure - -# URL - -ConfigurationFoundation - -extension URL - -## Topics - -## Relationships - -### Conforms To - -- `ExpressibleByConfigString` -- `Swift.Copyable` -- `Swift.CustomStringConvertible` - -- URL -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/appending(_:) - -#app-main) - -- Configuration -- AbsoluteConfigKey -- appending(\_:) - -Instance Method - -# appending(\_:) - -Returns a new absolute configuration key by appending the given relative key. - -ConfigKey.swift - -## Parameters - -`relative` - -The relative configuration key to append to this key. - -## Return Value - -A new absolute configuration key with the relative key appended. - -- appending(\_:) -- Parameters -- Return Value - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/init(_:issecret:) - -#app-main) - -- Configuration -- ConfigValue -- init(\_:isSecret:) - -Initializer - -# init(\_:isSecret:) - -Creates a new configuration value. - -init( -_ content: ConfigContent, -isSecret: Bool -) - -ConfigProvider.swift - -## Parameters - -`content` - -The configuration content. - -`isSecret` - -Whether the value contains sensitive information. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:issecret:default:fileid:line:) - -#app-main) - -- Configuration -- ConfigSnapshotReader -- string(forKey:isSecret:default:fileID:line:) - -Instance Method - -# string(forKey:isSecret:default:fileID:line:) - -Synchronously gets a config value for the given config key, with a default fallback. - -func string( -forKey key: ConfigKey, -isSecret: Bool = false, -default defaultValue: String, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`defaultValue` - -The fallback value returned when the config value is missing or invalid. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The config value if found and convertible, otherwise the default value. - -## Discussion - -Use this method when you need a guaranteed non-nil result. If the configuration value is missing or can’t be converted to the expected type, the default value is returned instead. - -let maxRetries = snapshot.int(forKey: ["network", "maxRetries"], default: 3) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, converting from string. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -- string(forKey:isSecret:default:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/systempackage/filepath - -- Configuration -- SystemPackage -- FilePath - -Extended Structure - -# FilePath - -ConfigurationSystemPackage - -extension FilePath - -## Topics - -## Relationships - -### Conforms To - -- `ExpressibleByConfigString` -- `Swift.Copyable` -- `Swift.CustomStringConvertible` - -- FilePath -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/expressiblebyconfigstring/init(configstring:) - -#app-main) - -- Configuration -- ExpressibleByConfigString -- init(configString:) - -Initializer - -# init(configString:) - -Creates an instance from a configuration string value. - -init?(configString: String) - -ExpressibleByConfigString.swift - -**Required** - -## Parameters - -`configString` - -The string value from the configuration provider. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/metadata-swift.struct - -- Configuration -- AccessEvent -- AccessEvent.Metadata - -Structure - -# AccessEvent.Metadata - -Metadata describing the configuration access operation. - -struct Metadata - -AccessReporter.swift - -## Overview - -Contains information about the type of access, the key accessed, value type, source location, and timestamp. - -## Topics - -### Creating access event metadata - -`init(accessKind: AccessEvent.Metadata.AccessKind, key: AbsoluteConfigKey, valueType: ConfigType, sourceLocation: AccessEvent.Metadata.SourceLocation, accessTimestamp: Date)` - -Creates access event metadata. - -`enum AccessKind` - -The type of configuration access operation. - -### Inspecting access event metadata - -`var accessKind: AccessEvent.Metadata.AccessKind` - -The type of configuration access operation for this event. - -`var accessTimestamp: Date` - -The timestamp when the configuration access occurred. - -`var key: AbsoluteConfigKey` - -The configuration key accessed. - -`var sourceLocation: AccessEvent.Metadata.SourceLocation` - -The source code location where the access occurred. - -`var valueType: ConfigType` - -The expected type of the configuration value. - -### Structures - -`struct SourceLocation` - -The source code location where a configuration access occurred. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating an access event - -Creates a configuration access event. - -`struct ProviderResult` - -The result of a configuration lookup from a specific provider. - -- AccessEvent.Metadata -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/broadcastingaccessreporter/init(upstreams:) - -#app-main) - -- Configuration -- BroadcastingAccessReporter -- init(upstreams:) - -Initializer - -# init(upstreams:) - -Creates a new broadcasting access reporter. - -init(upstreams: [any AccessReporter]) - -AccessReporter.swift - -## Parameters - -`upstreams` - -The reporters that will receive forwarded events. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/expressiblebyextendedgraphemeclusterliteral-implementations - -- Configuration -- ConfigValue -- ExpressibleByExtendedGraphemeClusterLiteral Implementations - -API Collection - -# ExpressibleByExtendedGraphemeClusterLiteral Implementations - -## Topics - -### Initializers - -`init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/customstringconvertible-implementations - -- Configuration -- ConfigContextValue -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(provider:accessreporter:) - -#app-main) - -- Configuration -- ConfigReader -- init(provider:accessReporter:) - -Initializer - -# init(provider:accessReporter:) - -Creates a config reader with a single provider. - -init( -provider: some ConfigProvider, -accessReporter: (any AccessReporter)? = nil -) - -ConfigReader.swift - -## Parameters - -`provider` - -The configuration provider. - -`accessReporter` - -The reporter for configuration access events. - -## See Also - -### Creating config readers - -[`init(providers: [any ConfigProvider], accessReporter: (any AccessReporter)?)`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(providers:accessreporter:)) - -Creates a config reader with multiple providers. - -- init(provider:accessReporter:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/prepending(_:) - -# An unknown error occurred. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/int - -- Configuration -- ConfigType -- ConfigType.int - -Case - -# ConfigType.int - -An integer value. - -case int - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string` - -A string value. - -`case stringArray` - -An array of string values. - -`case bool` - -A Boolean value. - -`case boolArray` - -An array of Boolean values. - -`case intArray` - -An array of integer values. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configvalue/equatable-implementations - -- Configuration -- ConfigValue -- Equatable Implementations - -API Collection - -# Equatable Implementations - -## Topics - -### Operators - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/string(_:) - -#app-main) - -- Configuration -- ConfigContextValue -- ConfigContextValue.string(\_:) - -Case - -# ConfigContextValue.string(\_:) - -A string value. - -case string(String) - -ConfigContext.swift - -## See Also - -### Configuration context values - -`case bool(Bool)` - -A Boolean value. - -`case int(Int)` - -An integer value. - -`case double(Double)` - -A floating point value. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/stringarray - -- Configuration -- ConfigType -- ConfigType.stringArray - -Case - -# ConfigType.stringArray - -An array of string values. - -case stringArray - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string` - -A string value. - -`case bool` - -A Boolean value. - -`case boolArray` - -An array of Boolean values. - -`case int` - -An integer value. - -`case intArray` - -An array of integer values. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/stringarray(forkey:issecret:fileid:line:) - -#app-main) - -- Configuration -- ConfigSnapshotReader -- stringArray(forKey:isSecret:fileID:line:) - -Instance Method - -# stringArray(forKey:isSecret:fileID:line:) - -Synchronously gets a config value for the given config key. - -func stringArray( -forKey key: ConfigKey, -isSecret: Bool = false, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The value converted to the expected type if found and convertible, otherwise `nil`. - -## Discussion - -Use this method to retrieve optional configuration values from a snapshot. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. - -let port = snapshot.int(forKey: ["server", "port"]) - -## See Also - -### Synchronously reading lists of string values - -Synchronously gets an array of config values for the given config key, converting from strings. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets an array of config values for the given config key with default fallback, converting from strings. - -- stringArray(forKey:isSecret:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/components - -- Configuration -- AbsoluteConfigKey -- components - -Instance Property - -# components - -The hierarchical components that make up this absolute configuration key. - -var components: [String] - -ConfigKey.swift - -## Discussion - -Each component represents a level in the configuration hierarchy, forming a complete path from the root of the configuration structure. - -## See Also - -### Inspecting an absolute configuration key - -[`var context: [String : ConfigContextValue]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/context) - -Additional context information for this configuration key. - -- components -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/bool - -- Configuration -- ConfigType -- ConfigType.bool - -Case - -# ConfigType.bool - -A Boolean value. - -case bool - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string` - -A string value. - -`case stringArray` - -An array of string values. - -`case boolArray` - -An array of Boolean values. - -`case int` - -An integer value. - -`case intArray` - -An array of integer values. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/dynamic(_:) - -#app-main) - -- Configuration -- SecretsSpecifier -- SecretsSpecifier.dynamic(\_:) - -Case - -# SecretsSpecifier.dynamic(\_:) - -The library determines the secret status dynamically by evaluating each key-value pair. - -SecretsSpecifier.swift - -## Parameters - -`closure` - -A closure that takes a key and value and returns whether the value should be treated as secret. - -## Discussion - -Use this case when you need complex logic to determine whether a value is secret based on the key name, value content, or other criteria. - -## See Also - -### Types of specifiers - -`case all` - -The library treats all configuration values as secrets. - -The library treats the specified keys as secrets. - -`case none` - -The library treats no configuration values as secrets. - -- SecretsSpecifier.dynamic(\_:) -- Parameters -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/all - -- Configuration -- SecretsSpecifier -- SecretsSpecifier.all - -Case - -# SecretsSpecifier.all - -The library treats all configuration values as secrets. - -case all - -SecretsSpecifier.swift - -## Discussion - -Use this case when the provider exclusively handles sensitive information and all values should be protected from disclosure. - -## See Also - -### Types of specifiers - -The library treats the specified keys as secrets. - -The library determines the secret status dynamically by evaluating each key-value pair. - -`case none` - -The library treats no configuration values as secrets. - -- SecretsSpecifier.all -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest/testconfiguration - -- ConfigurationTesting -- ProviderCompatTest -- ProviderCompatTest.TestConfiguration - -Structure - -# ProviderCompatTest.TestConfiguration - -Configuration options for customizing test behavior. - -struct TestConfiguration - -ProviderCompatTest.swift - -## Topics - -### Initializers - -[`init(overrides: [String : ConfigContent])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest/testconfiguration/init(overrides:)) - -Creates a new test configuration. - -### Instance Properties - -[`var overrides: [String : ConfigContent]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configurationtesting/providercompattest/testconfiguration/overrides) - -Value overrides for testing custom scenarios. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -- ProviderCompatTest.TestConfiguration -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/foundation/date - -- Configuration -- Foundation -- Date - -Extended Structure - -# Date - -ConfigurationFoundation - -extension Date - -## Topics - -## Relationships - -### Conforms To - -- `ExpressibleByConfigString` -- `Swift.Copyable` -- `Swift.CustomStringConvertible` - -- Date -- Topics -- Relationships - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/boolarray - -- Configuration -- ConfigType -- ConfigType.boolArray - -Case - -# ConfigType.boolArray - -An array of Boolean values. - -case boolArray - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string` - -A string value. - -`case stringArray` - -An array of string values. - -`case bool` - -A Boolean value. - -`case int` - -An integer value. - -`case intArray` - -An array of integer values. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/equatable-implementations - -- Configuration -- ConfigContextValue -- Equatable Implementations - -API Collection - -# Equatable Implementations - -## Topics - -### Operators - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:) - -#app-main) - -- Configuration -- AbsoluteConfigKey -- init(\_:) - -Initializer - -# init(\_:) - -Creates a new absolute configuration key from a relative key. - -init(_ relative: ConfigKey) - -ConfigKey.swift - -## Parameters - -`relative` - -The relative configuration key to convert. - -## See Also - -### Creating an absolute configuration key - -[`init([String], context: [String : ConfigContextValue])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:context:)) - -Creates a new absolute configuration key. - -- init(\_:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/asyncsequence-implementations - -- Configuration -- ConfigUpdatesAsyncSequence -- AsyncSequence Implementations - -API Collection - -# AsyncSequence Implementations - -## Topics - -### Instance Methods - -[`func chunked(by: AsyncTimerSequence) -> AsyncChunksOfCountOrSignalSequence>`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/chunked(by:)-trjw) - -`func chunked(by: AsyncTimerSequence, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence>` - -[`func chunks(ofCount: Int, or: AsyncTimerSequence) -> AsyncChunksOfCountOrSignalSequence>`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/chunks(ofcount:or:)-8u4c4) - -`func chunks(ofCount: Int, or: AsyncTimerSequence, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence>` - -`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/makeasynciterator()) - -`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configupdatesasyncsequence/share(bufferingpolicy:)) - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshot/value(forkey:type:) - -#app-main) - -- Configuration -- ConfigSnapshot -- value(forKey:type:) - -Instance Method - -# value(forKey:type:) - -Returns a value for the specified key from this immutable snapshot. - -func value( -forKey key: AbsoluteConfigKey, -type: ConfigType - -ConfigProvider.swift - -**Required** - -## Parameters - -`key` - -The configuration key to look up. - -`type` - -The expected configuration value type. - -## Return Value - -The lookup result containing the value and encoded key, or nil if not found. - -## Discussion - -Unlike `value(forKey:type:)`, this method always returns the same value for identical parameters because the snapshot represents a fixed point in time. Values can be accessed synchronously and efficiently. - -## See Also - -### Required methods - -`var providerName: String` - -The human-readable name of the configuration provider that created this snapshot. - -- value(forKey:type:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configtype/intarray - -- Configuration -- ConfigType -- ConfigType.intArray - -Case - -# ConfigType.intArray - -An array of integer values. - -case intArray - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string` - -A string value. - -`case stringArray` - -An array of string values. - -`case bool` - -A Boolean value. - -`case boolArray` - -An array of Boolean values. - -`case int` - -An integer value. - -`case double` - -A double value. - -`case doubleArray` - -An array of double values. - -`case bytes` - -An array of bytes. - -`case byteChunkArray` - -An array of byte chunks. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/double(_:) - -#app-main) - -- Configuration -- ConfigContextValue -- ConfigContextValue.double(\_:) - -Case - -# ConfigContextValue.double(\_:) - -A floating point value. - -case double(Double) - -ConfigContext.swift - -## See Also - -### Configuration context values - -`case string(String)` - -A string value. - -`case bool(Bool)` - -A Boolean value. - -`case int(Int)` - -An integer value. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/customstringconvertible-implementations - -- Configuration -- DirectoryFilesProvider -- CustomStringConvertible Implementations - -API Collection - -# CustomStringConvertible Implementations - -## Topics - -### Instance Properties - -`var description: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontextvalue/int(_:) - -#app-main) - -- Configuration -- ConfigContextValue -- ConfigContextValue.int(\_:) - -Case - -# ConfigContextValue.int(\_:) - -An integer value. - -case int(Int) - -ConfigContext.swift - -## See Also - -### Configuration context values - -`case string(String)` - -A string value. - -`case bool(Bool)` - -A Boolean value. - -`case double(Double)` - -A floating point value. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/comparable-implementations - -- Configuration -- AbsoluteConfigKey -- Comparable Implementations - -API Collection - -# Comparable Implementations - -## Topics - -### Operators - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configreader/init(providers:accessreporter:) - -#app-main) - -- Configuration -- ConfigReader -- init(providers:accessReporter:) - -Initializer - -# init(providers:accessReporter:) - -Creates a config reader with multiple providers. - -init( -providers: [any ConfigProvider], -accessReporter: (any AccessReporter)? = nil -) - -ConfigReader.swift - -## Parameters - -`providers` - -The configuration providers, queried in order until a value is found. - -`accessReporter` - -The reporter for configuration access events. - -## See Also - -### Creating config readers - -`init(provider: some ConfigProvider, accessReporter: (any AccessReporter)?)` - -Creates a config reader with a single provider. - -- init(providers:accessReporter:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:default:fileid:line:)-fzpe - --fzpe#app-main) - -- Configuration -- ConfigSnapshotReader -- string(forKey:as:isSecret:default:fileID:line:) - -Instance Method - -# string(forKey:as:isSecret:default:fileID:line:) - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -forKey key: ConfigKey, -as type: Value.Type = Value.self, -isSecret: Bool = false, -default defaultValue: Value, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`type` - -The type to convert the string value to. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`defaultValue` - -The fallback value returned when the config value is missing or invalid. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The config value if found and convertible, otherwise the default value. - -## Discussion - -Use this method when you need a guaranteed non-nil result for string-convertible types. If the configuration value is missing or can’t be converted to the expected type, the default value is returned instead. - -let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self, default: .production) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key, converting from string. - -- string(forKey:as:isSecret:default:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/absoluteconfigkey/init(_:context:) - -#app-main) - -- Configuration -- AbsoluteConfigKey -- init(\_:context:) - -Initializer - -# init(\_:context:) - -Creates a new absolute configuration key. - -init( -_ components: [String], -context: [String : ConfigContextValue] = [:] -) - -ConfigKey.swift - -## Parameters - -`components` - -The hierarchical components that make up the complete key path. - -`context` - -Additional context information for the key. - -## See Also - -### Creating an absolute configuration key - -`init(ConfigKey)` - -Creates a new absolute configuration key from a relative key. - -- init(\_:context:) -- Parameters -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/mutableinmemoryprovider/customdebugstringconvertible-implementations - -- Configuration -- MutableInMemoryProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresult - -- Configuration -- AccessEvent -- AccessEvent.ProviderResult - -Structure - -# AccessEvent.ProviderResult - -The result of a configuration lookup from a specific provider. - -struct ProviderResult - -AccessReporter.swift - -## Overview - -Contains the provider’s name and the outcome of querying that provider, which can be either a successful lookup result or an error. - -## Topics - -### Creating provider results - -Creates a provider result. - -### Inspecting provider results - -The outcome of the configuration lookup operation. - -`var providerName: String` - -The name of the configuration provider that processed the lookup. - -## Relationships - -### Conforms To - -- `Swift.Sendable` -- `Swift.SendableMetatype` - -## See Also - -### Creating an access event - -Creates a configuration access event. - -`struct Metadata` - -Metadata describing the configuration access operation. - -- AccessEvent.ProviderResult -- Overview -- Topics -- Relationships -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:issecret:fileid:line:) - -#app-main) - -- Configuration -- ConfigSnapshotReader -- string(forKey:isSecret:fileID:line:) - -Instance Method - -# string(forKey:isSecret:fileID:line:) - -Synchronously gets a config value for the given config key. - -func string( -forKey key: ConfigKey, -isSecret: Bool = false, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The value converted to the expected type if found and convertible, otherwise `nil`. - -## Discussion - -Use this method to retrieve optional configuration values from a snapshot. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. - -let port = snapshot.int(forKey: ["server", "port"]) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key, converting from string. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -- string(forKey:isSecret:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/double(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.double(\_:) - -Case - -# ConfigContent.double(\_:) - -A double value. - -case double(Double) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -[`case stringArray([String])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:)) - -An array of string values. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/stringarray(_:) - -#app-main) - -- Configuration -- ConfigContent -- ConfigContent.stringArray(\_:) - -Case - -# ConfigContent.stringArray(\_:) - -An array of string values. - -case stringArray([String]) - -ConfigProvider.swift - -## See Also - -### Types of configuration content - -`case string(String)` - -A string value. - -`case bool(Bool)` - -A Boolean value. - -[`case boolArray([Bool])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/boolarray(_:)) - -An array of Boolean value. - -`case int(Int)` - -An integer value. - -[`case intArray([Int])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/intarray(_:)) - -An array of integer values. - -`case double(Double)` - -A double value. - -[`case doubleArray([Double])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/doublearray(_:)) - -An array of double values. - -[`case bytes([UInt8])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytes(_:)) - -An array of bytes. - -[`case byteChunkArray([[UInt8]])`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configcontent/bytechunkarray(_:)) - -An array of byte arrays. - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshotreader/string(forkey:as:issecret:fileid:line:)-8hlcf - --8hlcf#app-main) - -- Configuration -- ConfigSnapshotReader -- string(forKey:as:isSecret:fileID:line:) - -Instance Method - -# string(forKey:as:isSecret:fileID:line:) - -Synchronously gets a config value for the given config key, converting from string. - -forKey key: ConfigKey, -as type: Value.Type = Value.self, -isSecret: Bool = false, -fileID: String = #fileID, -line: UInt = #line - -ConfigSnapshotReader+methods.swift - -## Parameters - -`key` - -The config key to look up. - -`type` - -The type to convert the string value to. - -`isSecret` - -Whether the value should be treated as secret for logging and debugging purposes. - -`fileID` - -The file ID where this call originates. Used for access reporting. - -`line` - -The line number where this call originates. Used for access reporting. - -## Return Value - -The value converted to the expected type if found and convertible, otherwise `nil`. - -## Discussion - -Use this method to retrieve configuration values that can be converted from strings, such as custom types conforming to string conversion protocols. If the value doesn’t exist or can’t be converted to the expected type, the method returns `nil`. - -let serverMode = snapshot.string(forKey: ["server", "mode"], as: ServerMode.self) - -## See Also - -### Synchronously reading string values - -Synchronously gets a config value for the given config key. - -Synchronously gets a config value for the given config key, with a default fallback. - -Synchronously gets a config value for the given config key with default fallback, converting from string. - -- string(forKey:as:isSecret:fileID:line:) -- Parameters -- Return Value -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/directoryfilesprovider/customdebugstringconvertible-implementations - -- Configuration -- DirectoryFilesProvider -- CustomDebugStringConvertible Implementations - -API Collection - -# CustomDebugStringConvertible Implementations - -## Topics - -### Instance Properties - -`var debugDescription: String` - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/configsnapshot/providername - -- Configuration -- ConfigSnapshot -- providerName - -Instance Property - -# providerName - -The human-readable name of the configuration provider that created this snapshot. - -var providerName: String { get } - -ConfigProvider.swift - -**Required** - -## Discussion - -Used by `AccessReporter` and when diagnostic logging the config reader types. - -## See Also - -### Required methods - -Returns a value for the specified key from this immutable snapshot. - -- providerName -- Discussion -- See Also - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/secretsspecifier/issecret(key:value:) - -#app-main) - -- Configuration -- SecretsSpecifier -- isSecret(key:value:) - -Instance Method - -# isSecret(key:value:) - -Determines whether a configuration value should be treated as secret. - -func isSecret( -key: KeyType, -value: ValueType - -SecretsSpecifier.swift - -Available when `KeyType` conforms to `Hashable`, `KeyType` conforms to `Sendable`, and `ValueType` conforms to `Sendable`. - -## Parameters - -`key` - -The provider-specific configuration key. - -`value` - -The configuration value to evaluate. - -## Return Value - -`true` if the value should be treated as secret; otherwise, `false`. - -## Discussion - -This method evaluates the secrets specifier against the provided key-value pair to determine if the value contains sensitive information that should be protected from disclosure. - -let isSecret = specifier.isSecret(key: "API_KEY", value: "secret123") -// Returns: true - -- isSecret(key:value:) -- Parameters -- Return Value -- Discussion - -| -| - ---- - -# https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/metadata-swift.property - -- Configuration -- AccessEvent -- metadata - -Instance Property - -# metadata - -Metadata that describes the configuration access operation. - -var metadata: AccessEvent.Metadata - -AccessReporter.swift - -## See Also - -### Inspecting an access event - -The final outcome of the configuration access operation. - -`var conversionError: (any Error)?` - -An error that occurred when converting the raw config value into another type, for example `RawRepresentable`. - -[`var providerResults: [AccessEvent.ProviderResult]`](https://swiftpackageindex.com/apple/swift-configuration/1.0.0/documentation/configuration/accessevent/providerresults) - -The results from each configuration provider that was queried. - -| -| - ---- - diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md index 7e2228bc..0aa2502c 100644 --- a/Docs/skit-analyze-plan.md +++ b/Docs/skit-analyze-plan.md @@ -2,7 +2,7 @@ ## Context -We need to create a CLI tool that uses the Claude API to automatically update the SyntaxKit library with missing features. The tool will: +We need a CLI tool that uses the Claude API to automatically update the SyntaxKit library with missing features. Rather than a new executable, this is implemented as an `analyze` subcommand on the existing `skit` CLI (alongside `run` and `parse`), using ArgumentParser like the rest of `skit`. The tool will: 1. Take an **input folder** containing: - `dsl.swift` - Swift DSL code (desired API) @@ -28,16 +28,16 @@ All structs, enums, classes, protocols, and extensions should be defined in sepa - Simpler code reviews and version control **Examples:** -- `AnalyzerConfiguration` → `AnalyzerConfiguration.swift` +- `SyntaxKitAnalyzer` → `SyntaxKitAnalyzer.swift` - `AnalyzerError` → `AnalyzerError.swift` - `ClaudeKit` → `ClaudeKit.swift` - `AuthenticationMiddleware` → `AuthenticationMiddleware.swift` **Exception:** Nested types that are tightly coupled to their parent (like `LibraryUpdateResult.UpdatedFile`) may remain in the same file as their parent type. -### 1. Create Three Targets with Clear Separation +### 1. Create Two New Targets, Extend the Existing `skit` Executable -This implementation uses three separate targets for better modularity and testability: +This implementation adds two new targets and extends the existing `skit` CLI with an `analyze` subcommand: #### Target 1: `ClaudeKit` (OpenAPI Generated Code) **Location**: `Sources/ClaudeKit/` @@ -73,106 +73,107 @@ This implementation uses three separate targets for better modularity and testab - Manages AST generation - Collects and writes library files -#### Target 3: `skit-aist` (Command Executable) -**Location**: `Sources/skit-aist/` +#### Target 3 (existing): `skit` Executable — New `analyze` Subcommand +**Location**: `Sources/skit/` (existing target) -**Purpose**: CLI executable that handles argument parsing, configuration, and user interaction +**Purpose**: The existing `skit` CLI gains an `analyze` subcommand alongside `run` and `parse`. No new executable is created. -**Dependencies**: +**New Dependencies** (added to the existing target): - `AiSTKit` - the SDK/bridge layer -- `ConfigKeyKit` (existing in project) - for configuration key management -- `swift-configuration` - for CLI argument and environment variable handling + +`skit` already uses **ArgumentParser** for its command tree (`Skit` is an `AsyncParsableCommand` with `Run` and `Parse` subcommands), so `analyze` follows the same pattern: a `Skit.Analyze` subcommand in `Skit+Analyze.swift`. **Key Responsibilities**: -- Parse command-line arguments -- Load configuration from environment variables -- Display help text and usage information +- Declare arguments, options, and flags via ArgumentParser property wrappers +- Read `ANTHROPIC_API_KEY` from the environment as the API key fallback +- Display help text and usage information (generated by ArgumentParser) - Handle test mode execution - Provide verbose output and error messages -- Entry point (`main.swift`) ### 2. Core Components -#### A. Configuration Structure (`AnalyzerConfiguration.swift`) +#### A. Analyze Subcommand (`Skit+Analyze.swift`) -Configuration using ConfigKeyKit pattern: +ArgumentParser subcommand on the existing `Skit` command, following the same +pattern as `Skit.Run` and `Skit.Parse`: ```swift -import Configuration -import ConfigKeyKit - -struct AnalyzerConfiguration: ConfigurationParseable { - typealias ConfigReader = Configuration.ConfigReader - typealias BaseConfig = Never - - // Configuration keys - static let syntaxKitPathKey = ConfigKey( - "syntaxkit.path", - default: "Sources/SyntaxKit" +import AiSTKit +import ArgumentParser +import Foundation + +extension Skit { + /// AI-powered AST generation: implement missing SyntaxKit features via the Claude API. + internal struct Analyze: AsyncParsableCommand { + internal static let configuration = CommandConfiguration( + commandName: "analyze", + abstract: "Implement missing SyntaxKit features using the Claude API." ) - static let apiKeyKey = OptionalConfigKey( - cli: "api-key", - env: "ANTHROPIC_API_KEY" - ) + @Argument(help: "Folder containing dsl.swift and expected.swift.") + internal var inputFolder: String - static let modelKey = ConfigKey( - "model", - default: "claude-opus-4-6" - ) + @Argument(help: "Path to the existing SyntaxKit library sources.") + internal var syntaxKitPath: String - static let verboseKey = ConfigKey("verbose", default: false) + @Argument(help: "Folder to write the updated SyntaxKit library to.") + internal var outputFolder: String - // Properties - let inputFolderPath: String // Folder containing dsl.swift, expected.swift - let syntaxKitPath: String // Path to existing SyntaxKit sources - let outputFolderPath: String // Where to write updated library - let apiKey: String - let model: String - let verbose: Bool - - init(configuration: ConfigReader, base: Never?) async throws { - // Read positional arguments from command line - let args = CommandLine.arguments.dropFirst() // Skip executable name - let positionalArgs = args.filter { !$0.hasPrefix("--") } + @Option(name: .customLong("api-key"), + help: "Claude API key (falls back to ANTHROPIC_API_KEY).") + internal var apiKey: String? - guard positionalArgs.count >= 3 else { - throw AnalyzerError.missingRequiredArguments( - "Usage: skit-aist [options]" - ) - } + @Option(help: "Claude model to use.") + internal var model: String = "claude-opus-4-6" - self.inputFolderPath = positionalArgs[0] - self.syntaxKitPath = positionalArgs[1] - self.outputFolderPath = positionalArgs[2] + @Flag(help: "Enable verbose output.") + internal var verbose: Bool = false - // Read from configuration (CLI flags and env vars) - self.model = configuration.string(forKey: Self.modelKey) - self.verbose = configuration.bool(forKey: Self.verboseKey) - - // API key is required - check CLI flag, then env var - guard let key = configuration.string(forKey: Self.apiKeyKey) else { - throw AnalyzerError.missingAPIKey( - "API key required. Provide via --api-key flag or ANTHROPIC_API_KEY environment variable" - ) - } - self.apiKey = key - - // Validate paths exist - try validatePaths() + internal func validate() throws { + let fileManager = FileManager.default + guard fileManager.fileExists(atPath: inputFolder) else { + throw ValidationError("Input folder does not exist: \(inputFolder)") + } + guard fileManager.fileExists(atPath: syntaxKitPath) else { + throw ValidationError("SyntaxKit path does not exist: \(syntaxKitPath)") + } } - private func validatePaths() throws { - let fm = FileManager.default + internal func run() async throws { + // API key: --api-key flag overrides the environment variable. + guard let key = apiKey + ?? ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] + else { + throw ValidationError("API key required. Provide --api-key or set ANTHROPIC_API_KEY.") + } + + let configuration = AnalyzerConfiguration( + inputFolderPath: inputFolder, + syntaxKitPath: syntaxKitPath, + outputFolderPath: outputFolder, + apiKey: key, + model: model, + verbose: verbose + ) + let analyzer = SyntaxKitAnalyzer(config: configuration) + try await analyzer.run() + } + } +} +``` - guard fm.fileExists(atPath: inputFolderPath) else { - throw AnalyzerError.invalidPath("Input folder does not exist: \(inputFolderPath)") - } +`AnalyzerConfiguration` becomes a plain value type in `AiSTKit` — no +configuration-framework dependency. The subcommand assembles it from parsed +arguments and hands it to `SyntaxKitAnalyzer`: - guard fm.fileExists(atPath: syntaxKitPath) else { - throw AnalyzerError.invalidPath("SyntaxKit path does not exist: \(syntaxKitPath)") - } - } +```swift +public struct AnalyzerConfiguration: Sendable { + public let inputFolderPath: String // Folder containing dsl.swift, expected.swift + public let syntaxKitPath: String // Path to existing SyntaxKit sources + public let outputFolderPath: String // Where to write updated library + public let apiKey: String + public let model: String + public let verbose: Bool } ``` @@ -190,93 +191,23 @@ enum AnalyzerError: Error { } ``` -#### B. Command Implementation (`AnalyzeCommand.swift`) +#### B. Subcommand Registration (`Skit.swift`) -Command using ConfigKeyKit Command protocol: +No new entry point is needed — `skit` already has one. The only change to +`Skit.swift` is adding `Analyze` to the subcommand list: ```swift -import ConfigKeyKit -import Configuration - -struct AnalyzeCommand: Command { - typealias Config = AnalyzerConfiguration - - static let commandName = "analyze" - static let abstract = "AI-powered AST generation for SyntaxKit" - static let helpText = """ - OVERVIEW: Automatically implement missing SyntaxKit features using Claude API - - USAGE: skit-aist [options] - - ARGUMENTS: - Folder containing: - - dsl.swift: Swift DSL code (desired API) - - expected.swift: Expected Swift code output - Note: AST is auto-generated from expected.swift - - Path to existing SyntaxKit library sources - - Where to write the updated SyntaxKit library - - OPTIONS: - --api-key Claude API key (or set ANTHROPIC_API_KEY) - --model Claude model to use (default: claude-opus-4-6) - --verbose Enable verbose output - -h, --help Show help information - - EXAMPLE: - mkdir examples/subscript-feature - echo 'Subscript("Item") { ... }' > examples/subscript-feature/dsl.swift - echo 'subscript(index: Int) -> Item { ... }' > examples/subscript-feature/expected.swift - - export ANTHROPIC_API_KEY="sk-ant-..." - skit-aist examples/subscript-feature Sources/SyntaxKit output/SyntaxKit - """ - - let config: Config - - init(config: Config) { - self.config = config - } - - static func createInstance() async throws -> Self { - // Create providers - let envProvider = EnvironmentVariablesProvider() - let cliProvider = CommandLineArgumentsProvider() - - // Provider hierarchy: CLI args override environment variables - let reader = ConfigReader(providers: [cliProvider, envProvider]) - - // Parse configuration - let configuration = try await Config(configuration: reader) - - return Self(config: configuration) - } - - func execute() async throws { - // Delegate to analyzer - let analyzer = SyntaxKitAnalyzer(config: config) - try await analyzer.run() - } -} +internal static let configuration = CommandConfiguration( + commandName: "skit", + abstract: "SyntaxKit command-line tool.", + subcommands: [Run.self, Parse.self, Analyze.self], + defaultSubcommand: Run.self +) ``` -#### C. Main Entry Point (`main.swift`) - -```swift -@main -enum SkitAnalyze { - static func main() async { - do { - let command = try await AnalyzeCommand.createInstance() - try await command.execute() - } catch { - print("Error: \(error)") - exit(1) - } - } -} -``` +Usage text, `--help` output, argument validation errors, and exit codes are +all generated by ArgumentParser — no hand-written help text or `main.swift` +required. #### D. Main Analyzer (`SyntaxKitAnalyzer.swift`) @@ -690,12 +621,12 @@ struct FileReference: Codable { **OpenAPI Specification Source**: - Uses unofficial OpenAPI spec from [laszukdawid/anthropic-openapi-spec](https://github.com/laszukdawid/anthropic-openapi-spec) - Specifically the `hosted_spec.json` file (derived from Anthropic's TypeScript SDK) -- Download to `Sources/skit-aist/openapi.json` or `openapi.yaml` +- Download to `Sources/ClaudeKit/openapi.json` or `openapi.yaml` - Swift OpenAPI Generator will create type-safe client code at build time **Setup Steps**: -1. Download OpenAPI spec: `curl -o Sources/skit-aist/openapi.json https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json` -2. Create `Sources/skit-aist/openapi-generator-config.yaml`: +1. Download OpenAPI spec: `curl -o Sources/ClaudeKit/openapi.json https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json` +2. Create `Sources/ClaudeKit/openapi-generator-config.yaml`: ```yaml generate: - types @@ -777,16 +708,15 @@ Include: ### 3. Workflow ``` -User runs: skit-aist examples/subscript-feature Sources/SyntaxKit output/SyntaxKit - -1. main.swift: Entry point -2. AnalyzeCommand.createInstance(): - - Create EnvironmentVariablesProvider and CommandLineArgumentsProvider - - Create ConfigReader with provider hierarchy (CLI > ENV) - - Parse AnalyzerConfiguration from ConfigReader - - Validate required arguments (input folder, syntaxkit path, output folder, API key) - - Validate paths exist -3. AnalyzeCommand.execute(): +User runs: skit analyze examples/subscript-feature Sources/SyntaxKit output/SyntaxKit + +1. Skit (existing @main): ArgumentParser dispatches to the Analyze subcommand +2. Skit.Analyze.validate(): + - ArgumentParser has already parsed positional arguments, options, and flags + - Validate input folder and SyntaxKit path exist +3. Skit.Analyze.run(): + - Resolve API key (--api-key flag, falling back to ANTHROPIC_API_KEY) + - Build AnalyzerConfiguration from parsed arguments - Create SyntaxKitAnalyzer instance with config - Call analyzer.run() 4. SyntaxKitAnalyzer.run(): @@ -811,15 +741,11 @@ User runs: skit-aist examples/subscript-feature Sources/SyntaxKit output/SyntaxK ### 4. Package.swift Changes -Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenAPI Generator: +Add the OpenAPI Generator dependencies, the two new targets, and wire `AiSTKit` +into the existing `skit` executable target: ```swift // In dependencies: -.package( - url: "https://github.com/apple/swift-configuration", - from: "1.0.0", - traits: ["CommandLineArguments"] // Enable CLI args trait -), .package( url: "https://github.com/apple/swift-openapi-generator", from: "1.0.0" @@ -833,22 +759,10 @@ Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenA from: "1.0.0" ), -// Add ConfigKeyKit as a target: +// New target: OpenAPI-generated Claude API client .target( - name: "ConfigKeyKit", + name: "ClaudeKit", dependencies: [ - .product(name: "Configuration", package: "swift-configuration") - ], - swiftSettings: swiftSettings -), - -// Add new executable target with OpenAPI Generator plugin: -.executableTarget( - name: "skit-aist", - dependencies: [ - "SyntaxParser", - "ConfigKeyKit", - .product(name: "Configuration", package: "swift-configuration"), .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"), .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession") ], @@ -858,82 +772,79 @@ Add ConfigKeyKit as a local target, integrate swift-configuration, and add OpenA swiftSettings: swiftSettings ), -// In products: -.executable( - name: "skit-aist", - targets: ["skit-aist"] +// New target: SDK/bridge layer with the analyzer domain logic +.target( + name: "AiSTKit", + dependencies: [ + "ClaudeKit", + "SyntaxParser" + ], + swiftSettings: swiftSettings +), + +// Existing executable target: add AiSTKit +.executableTarget( + name: "skit", + dependencies: [ + // ...existing dependencies (SyntaxKit, SyntaxParser, ArgumentParser, ...) + "AiSTKit" + ], + swiftSettings: swiftSettings ), ``` +No new product is needed — `skit` is already a product, and `analyze` ships +inside it. + **Setup Requirements**: -1. Download OpenAPI spec to `Sources/skit-aist/`: +1. Download OpenAPI spec to `Sources/ClaudeKit/`: ```bash - curl -o Sources/skit-aist/openapi.json \ + curl -o Sources/ClaudeKit/openapi.json \ https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json ``` -2. Create `Sources/skit-aist/openapi-generator-config.yaml`: +2. Create `Sources/ClaudeKit/openapi-generator-config.yaml`: ```yaml generate: - types - client - accessModifier: internal + accessModifier: package ``` 3. The OpenAPI Generator plugin will automatically generate type-safe client code during build **Notes**: -- ConfigKeyKit already exists in the project directory, so we just need to add it as a target in Package.swift - OpenAPI Generator runs as a build plugin and generates Swift code from the OpenAPI spec at build time - Generated code includes type-safe request/response models and client methods +- Adding `AiSTKit` to `skit` pulls the OpenAPI runtime into the `skit` binary; this is acceptable for a developer tool ### 5. Configuration & Environment -**How swift-configuration + ConfigKeyKit Works Together**: - -1. **ConfigKeyKit** provides the abstraction layer: - - `ConfigKey` for required values with defaults - - `OptionalConfigKey` for optional values - - Automatic key naming transformations (e.g., `api.key` → `--api-key` or `API_KEY`) - - Source-specific key generation (CLI vs ENV have different naming conventions) - -2. **swift-configuration** provides the runtime: - - `ConfigReader` reads from multiple providers - - `CommandLineArgumentsProvider` parses `--flag value` style arguments - - `EnvironmentVariablesProvider` reads from environment - - Provider hierarchy: CLI arguments override environment variables - -3. **Integration**: - ```swift - // Define key with both sources - let apiKeyKey = OptionalConfigKey( - cli: "api-key", // Becomes --api-key - env: "ANTHROPIC_API_KEY" // Reads from $ANTHROPIC_API_KEY - ) - - // Read with ConfigReader - let apiKey = configuration.string(forKey: apiKeyKey) // Checks CLI first, then ENV - ``` +**ArgumentParser handles everything** — the same library `skit` already uses +for `run` and `parse`. No configuration framework is needed: + +- `@Argument` for the three required positional paths +- `@Option` for `--api-key` and `--model` +- `@Flag` for `--verbose` +- `validate()` for path-existence checks +- `--help`, usage text, and parse errors generated automatically **API Key Management**: -- `--api-key` flag takes precedence (via CommandLineArgumentsProvider) -- Falls back to `ANTHROPIC_API_KEY` environment variable (via EnvironmentVariablesProvider) -- Error if neither is provided +- `--api-key` flag takes precedence +- Falls back to `ANTHROPIC_API_KEY` environment variable (read via `ProcessInfo` in `run()`) +- `ValidationError` if neither is provided **Positional Arguments**: - Three required positional arguments (not flags): - 1. Input folder path (containing dsl.swift, expected.swift, optional ast files) + 1. Input folder path (containing dsl.swift, expected.swift) 2. SyntaxKit library path (existing sources to read) 3. Output folder path (where to write updated library) -- Parsed manually from `CommandLine.arguments` in configuration initializer - More intuitive than using flags for required paths -- Example: `skit-aist examples/feature Sources/SyntaxKit output/updated` +- Example: `skit analyze examples/feature Sources/SyntaxKit output/updated` **Default Values**: -- SyntaxKit library path: `Sources/SyntaxKit` (via `ConfigKey` default) -- Model: `claude-opus-4-6` (via `ConfigKey` default) -- Verbose: `false` (via `ConfigKey` default) -- Can all be overridden via CLI flags or environment variables +- Model: `claude-opus-4-6` (ArgumentParser property default, override with `--model`) +- Verbose: `false` (override with `--verbose`) **Model Configuration**: - Model: Default `claude-opus-4-6`, override with `--model` @@ -980,31 +891,38 @@ Include full API request/response, intermediate parsing steps, file collection d ## Critical Files to Create ### Source Files -1. **Sources/skit-aist/main.swift** - Main entry point -2. **Sources/skit-aist/AnalyzeCommand.swift** - Command implementation using ConfigKeyKit -3. **Sources/skit-aist/AnalyzerConfiguration.swift** - Configuration structure using ConfigKeyKit -4. **Sources/skit-aist/AnalyzerError.swift** - Error types for analyzer operations -5. **Sources/skit-aist/SyntaxKitAnalyzer.swift** - Core analyzer orchestration -6. **Sources/skit-aist/InputFolderReader.swift** - Reads dsl.swift, expected.swift, ast files -7. **Sources/skit-aist/LibraryCollector.swift** - Collects SyntaxKit source files -8. **Sources/skit-aist/LibraryWriter.swift** - Writes updated library to output folder -9. **Sources/skit-aist/ASTGenerator.swift** - Wraps SyntaxParser for AST generation -10. **Sources/skit-aist/ClaudeKit.swift** - Wraps OpenAPI-generated client for code generation -11. **Sources/skit-aist/AuthenticationMiddleware.swift** - OpenAPI middleware for API authentication -12. **Sources/skit-aist/LibraryUpdateResult.swift** - Data structures for library update results -13. **Sources/skit-aist/FileReference.swift** - File reference data structure -14. **Sources/skit-aist/PromptTemplate.swift** - Enhanced Workbench prompt with code generation +1. **Sources/skit/Skit+Analyze.swift** - `analyze` subcommand (ArgumentParser); register in `Skit.swift` subcommand list +2. **Sources/AiSTKit/AnalyzerConfiguration.swift** - Plain configuration value type +3. **Sources/AiSTKit/AnalyzerError.swift** - Error types for analyzer operations +4. **Sources/AiSTKit/SyntaxKitAnalyzer.swift** - Core analyzer orchestration +5. **Sources/AiSTKit/InputFolderReader.swift** - Reads dsl.swift, expected.swift +6. **Sources/AiSTKit/LibraryCollector.swift** - Collects SyntaxKit source files +7. **Sources/AiSTKit/LibraryWriter.swift** - Writes updated library to output folder +8. **Sources/AiSTKit/ASTGenerator.swift** - Wraps SyntaxParser for AST generation +9. **Sources/AiSTKit/ClaudeKit.swift** - Wraps OpenAPI-generated client for code generation +10. **Sources/AiSTKit/AuthenticationMiddleware.swift** - OpenAPI middleware for API authentication +11. **Sources/AiSTKit/LibraryUpdateResult.swift** - Data structures for library update results +12. **Sources/AiSTKit/FileReference.swift** - File reference data structure +13. **Sources/AiSTKit/PromptTemplate.swift** - Enhanced Workbench prompt with code generation ### Configuration Files -15. **Sources/skit-aist/openapi.json** - Anthropic OpenAPI specification (downloaded) -16. **Sources/skit-aist/openapi-generator-config.yaml** - OpenAPI Generator configuration -17. **Package.swift** (modify) - Add ConfigKeyKit target, dependencies, and OpenAPI plugin +14. **Sources/ClaudeKit/openapi.json** - Anthropic OpenAPI specification (downloaded) +15. **Sources/ClaudeKit/openapi-generator-config.yaml** - OpenAPI Generator configuration +16. **Package.swift** (modify) - Add ClaudeKit and AiSTKit targets, OpenAPI plugin; add AiSTKit to skit ### Test Mode Files (Section 8) -18. **Sources/skit-aist/Testing/TestRunner.swift** - Orchestrates test execution -19. **Sources/skit-aist/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases -20. **Sources/skit-aist/Testing/TestValidator.swift** - Validates results against expectations -21. **Sources/skit-aist/Testing/TestModels.swift** - Test data structures +17. **Sources/AiSTKit/Testing/TestRunner.swift** - Orchestrates test execution +18. **Sources/AiSTKit/Testing/TestCaseDiscoverer.swift** - Discovers and loads test cases +19. **Sources/AiSTKit/Testing/TestValidator.swift** - Validates results against expectations +20. **Sources/AiSTKit/Testing/TestModels.swift** - Test data structures + +### Convergence Loop Files (Section 9, Part 2) +21. **Sources/AiSTKit/LibraryVerifying.swift** - Build/render/compare protocol (no Subprocess) +22. **Sources/AiSTKit/VerificationResult.swift** - Verification outcome value type +23. **Sources/AiSTKit/ConvergenceLoop.swift** - Generate → verify → re-prompt loop driver +24. **Sources/AiSTKit/PromptTemplate+Feedback.swift** - Follow-up prompt with errors/diff +25. **Sources/skit/SubprocessLibraryVerifier.swift** - Subprocess-backed verifier +26. **Sources/skit/Skit+Analyze.swift** (modify) - Add --max-iterations option ## Verification Steps @@ -1034,7 +952,7 @@ Include full API request/response, intermediate parsing steps, file collection d 3. **Run Tool**: ```bash export ANTHROPIC_API_KEY="sk-ant-..." - .build/release/skit-aist \ + .build/release/skit analyze \ examples/simple-property \ Sources/SyntaxKit \ output/SyntaxKit-updated @@ -1061,16 +979,16 @@ Include full API request/response, intermediate parsing steps, file collection d 6. **Error Handling Tests**: ```bash # Test missing API key - skit-aist examples/test Sources/SyntaxKit output # Should error + skit analyze examples/test Sources/SyntaxKit output # Should error # Test invalid input folder - skit-aist nonexistent Sources/SyntaxKit output # Should error + skit analyze nonexistent Sources/SyntaxKit output # Should error # Test missing required files mkdir -p examples/incomplete echo "test" > examples/incomplete/dsl.swift # Missing expected.swift - should error - skit-aist examples/incomplete Sources/SyntaxKit output + skit analyze examples/incomplete Sources/SyntaxKit output ``` 7. **Integration Test**: Use a real missing feature (e.g., subscript syntax) and verify: @@ -1173,19 +1091,19 @@ See the full implementation plan in the main plan file for detailed component sp ```bash # Run all test cases -skit-aist --test +skit analyze --test # Run with verbose output -skit-aist --test --verbose +skit analyze --test --verbose # Stop on first failure -skit-aist --test --test-stop-on-fail +skit analyze --test --test-stop-on-fail # Run only tests matching "subscript" -skit-aist --test --test-filter=subscript +skit analyze --test --test-filter=subscript # Run tests from custom path -skit-aist --test --test-cases=custom-tests/ +skit analyze --test --test-cases=custom-tests/ ``` ### Benefits @@ -1197,9 +1115,83 @@ skit-aist --test --test-cases=custom-tests/ 5. **Confidence**: Developers can iterate on prompts with confidence 6. **Debugging**: Failed tests pinpoint exactly what's wrong with generated code +## 9. Convergence Loop (Part 2) + +The single-shot pipeline (Sections 2–3, issue #120) generates once and stops. +Part 2 — tracked as issue #168, depending on #120 — wraps it in a loop that +verifies the generated library actually renders the DSL into the expected +Swift, and keeps fixing it until it does. This is the core purpose of the +analyze feature. + +### Loop Algorithm + +``` +1. Generate: run the single-shot pipeline (SyntaxKitAnalyzer) +2. Build: swift build the generated library in the output folder +3. Render: compile-and-run dsl.swift against the generated library + (the same approach skit run uses — the Swift JIT cannot + load the dynamic library, so rendering must compile with + swiftc and execute the binary) +4. Compare: diff the rendered Swift against expected.swift + (normalize whitespace/formatting before comparing) +5. Decide: + - Match → converged: report success, exit 0 + - Mismatch or build failure, + iteration < --max-iterations → re-prompt Claude with the swift + build errors or a unified diff of + rendered vs expected, go to 2 + - Iteration cap reached → diverged: report status, iteration + count, and last diff; exit non-zero +``` + +### Architecture: Respecting the SDK/CLI Boundary + +Verification needs subprocess execution (`swift build`, `swiftc`, running +the rendered binary). Subprocess usage stays in the `skit` target, so the +loop splits across the boundary the same way `Runner` does today: + +- **`AiSTKit`** defines: + - `LibraryVerifying` — protocol describing build/render/compare, with no + Subprocess dependency (`Sources/AiSTKit/LibraryVerifying.swift`) + - `VerificationResult` — built/rendered/diff outcome value type + (`Sources/AiSTKit/VerificationResult.swift`) + - `ConvergenceLoop` — the loop driver: generate → verify → re-prompt, + capped by max iterations (`Sources/AiSTKit/ConvergenceLoop.swift`) + - `PromptTemplate+Feedback` — builds the follow-up prompt embedding build + errors or the rendered-vs-expected diff + (`Sources/AiSTKit/PromptTemplate+Feedback.swift`) +- **`skit`** supplies: + - `SubprocessLibraryVerifier` — Subprocess-backed `LibraryVerifying` + implementation (`Sources/skit/SubprocessLibraryVerifier.swift`) + - `Skit.Analyze` gains `--max-iterations ` (default 3); `1` behaves as + the Part 1 single-shot pipeline + +### CLI Surface + +```bash +# Default: loop up to 3 iterations +skit analyze examples/feature Sources/SyntaxKit output/updated + +# Single-shot (Part 1 behavior) +skit analyze examples/feature Sources/SyntaxKit output/updated --max-iterations 1 + +# Allow more attempts for hard features +skit analyze examples/feature Sources/SyntaxKit output/updated --max-iterations 5 +``` + +### Consideration: swift-service-lifecycle + +Consider using [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) +to run the loop. The loop is a long-running process (multiple Claude API +calls, `swift build` invocations, and renders per run), and ServiceLifecycle's +`Service` protocol + graceful-shutdown handling would give it clean Ctrl-C +behavior: cancel the in-flight API call or subprocess, clean up temporary +build artifacts, and report partial progress (iterations completed, last +diff) before exiting. Evaluate during #168 whether the dependency is worth +it versus plain structured concurrency with `withTaskCancellationHandler`. + ## Future Enhancements (Not in Scope) -- **Validation Mode**: Run `swift build` on generated code and retry if compilation fails - **Interactive Review**: Show diff before writing, allow user to approve/reject changes - **Batch Processing**: Process multiple feature folders in one run - **Incremental Updates**: Only update changed files, preserve git history @@ -1212,13 +1204,12 @@ skit-aist --test --test-cases=custom-tests/ ## Dependencies Summary **New Dependencies**: -- `swift-configuration` (1.0.0+) with `CommandLineArguments` trait - Configuration management - `swift-openapi-generator` (1.0.0+) - Generates type-safe API client from OpenAPI spec - `swift-openapi-runtime` (1.0.0+) - Runtime support for generated OpenAPI client - `swift-openapi-urlsession` (1.0.0+) - URLSession transport for OpenAPI client **Existing Dependencies** (reused): -- `ConfigKeyKit` (in project) - Configuration key abstraction +- `swift-argument-parser` - CLI argument parsing (already used by `skit`) - `SwiftSyntax` (601.0.1+) - via SyntaxParser - `SyntaxParser` (existing module) - AST generation - Foundation - HTTP requests, file I/O @@ -1227,11 +1218,11 @@ skit-aist --test --test-cases=custom-tests/ - [Unofficial Anthropic OpenAPI Spec](https://github.com/laszukdawid/anthropic-openapi-spec) - `hosted_spec.json` derived from Anthropic's TypeScript SDK **Advantages of This Approach**: -- **swift-configuration + ConfigKeyKit**: - - Unified handling of CLI args and environment variables - - Type-safe configuration keys with automatic naming transformations - - Composable provider hierarchy (CLI overrides ENV) - - Consistent with project's existing ConfigKeyKit architecture +- **ArgumentParser subcommand on `skit`**: + - No new executable, configuration framework, or entry point to maintain + - Identical CLI conventions to the existing `run` and `parse` subcommands + - Help text, validation, and error reporting generated automatically + - `--api-key` flag overrides the `ANTHROPIC_API_KEY` environment variable - **Swift OpenAPI Generator**: - Type-safe API client generated at build time from OpenAPI spec @@ -1247,10 +1238,10 @@ skit-aist --test --test-cases=custom-tests/ swift build -c release # Install to system (optional) -cp .build/release/skit-aist /usr/local/bin/ +cp .build/release/skit /usr/local/bin/ # Or run from build directory -.build/release/skit-aist +.build/release/skit analyze ``` ## Example Usage @@ -1282,7 +1273,7 @@ EOF # 4. Run the tool # Note: AST is automatically generated from expected.swift using SyntaxParser export ANTHROPIC_API_KEY="sk-ant-..." -skit-aist \ +skit analyze \ examples/subscript-feature \ Sources/SyntaxKit \ output/SyntaxKit-with-subscripts @@ -1292,19 +1283,19 @@ skit-aist \ ```bash # With custom model -skit-aist examples/my-feature Sources/SyntaxKit output/updated \ +skit analyze examples/my-feature Sources/SyntaxKit output/updated \ --model claude-sonnet-4-5 # With verbose output to see what's happening -skit-aist examples/my-feature Sources/SyntaxKit output/updated \ +skit analyze examples/my-feature Sources/SyntaxKit output/updated \ --verbose # Using CLI flag for API key instead of environment -skit-aist examples/my-feature Sources/SyntaxKit output/updated \ +skit analyze examples/my-feature Sources/SyntaxKit output/updated \ --api-key sk-ant-... # Show help -skit-aist --help +skit analyze --help ``` ### Full Workflow Example @@ -1333,7 +1324,7 @@ EOF # Step 4: Generate updated SyntaxKit with defer support export ANTHROPIC_API_KEY="sk-ant-..." -skit-aist \ +skit analyze \ examples/defer-statement \ Sources/SyntaxKit \ output/SyntaxKit-with-defer \ diff --git a/IMPLEMENTATION_STATUS.md b/IMPLEMENTATION_STATUS.md index 0b26128a..800a4f70 100644 --- a/IMPLEMENTATION_STATUS.md +++ b/IMPLEMENTATION_STATUS.md @@ -1,8 +1,8 @@ -# skit-aist Implementation Status +# skit analyze Implementation Status ## Overview -This document tracks the implementation of the skit-aist tool, an AI-powered AST generation system for automatically implementing missing SyntaxKit features using the Claude API. +This document tracks the implementation of the `skit analyze` subcommand, an AI-powered AST generation system for automatically implementing missing SyntaxKit features using the Claude API. It is built as an ArgumentParser subcommand on the existing `skit` CLI (no new executable) backed by two new targets, ClaudeKit and AiSTKit. **Plan Document**: [Docs/skit-analyze-plan.md](Docs/skit-analyze-plan.md) @@ -10,7 +10,7 @@ This document tracks the implementation of the skit-aist tool, an AI-powered AST All implementation tasks have been broken down into 18 GitHub issues organized into 7 phases. -**Issue Range**: #107 - #124 +**Issue Range**: #107 - #124, #168 ### Quick Links @@ -26,11 +26,11 @@ All implementation tasks have been broken down into 18 GitHub issues organized i ### Phase 1: Project Setup & Infrastructure ✓ Planned -**Issues**: #107, #108, #109 +**Issues**: #107, #108 - [x] Issue #107: Setup OpenAPI Specification and Generator Configuration - [x] Issue #108: Update Package.swift with Dependencies and Targets -- [x] Issue #109: Create ConfigKeyKit Target Structure +- ~~Issue #109: Create ConfigKeyKit Target Structure~~ (closed — ConfigKeyKit dropped in favor of ArgumentParser) **Status**: Ready to implement **Estimated Effort**: 2-3 hours @@ -41,7 +41,7 @@ All implementation tasks have been broken down into 18 GitHub issues organized i **Issues**: #110, #111 - [ ] Issue #110: Implement AnalyzerConfiguration and AnalyzerError -- [ ] Issue #111: Implement AnalyzeCommand and Main Entry Point +- [ ] Issue #111: Implement skit analyze Subcommand (ArgumentParser) **Status**: Blocked by Phase 1 **Estimated Effort**: 3-4 hours @@ -75,13 +75,14 @@ All implementation tasks have been broken down into 18 GitHub issues organized i ### Phase 5: Main Orchestration ⏳ Waiting -**Issues**: #120 +**Issues**: #120, #168 -- [ ] Issue #120: Implement SyntaxKitAnalyzer Orchestration +- [ ] Issue #120: Implement SyntaxKitAnalyzer Orchestration (Part 1: single-shot pipeline) +- [ ] Issue #168: Implement Convergence Loop (Part 2: iterate until rendered output matches expected.swift) -**Status**: Blocked by #112, #113, #114, #115, #116 -**Estimated Effort**: 3-4 hours -**Critical Path**: Yes - integrates all components +**Status**: #120 blocked by #112, #113, #114, #115, #116; #168 blocked by #120 +**Estimated Effort**: 6-8 hours (3-4 each) +**Critical Path**: Yes - #120 integrates all components; #168 delivers the feature's core purpose ### Phase 6: Testing Infrastructure ⏳ Waiting @@ -109,10 +110,10 @@ All implementation tasks have been broken down into 18 GitHub issues organized i ### Overall Progress -- **Issues Created**: 18/18 ✓ +- **Issues Created**: 19 total ✓ (#109 since closed — ConfigKeyKit dropped; #168 added for the convergence loop) - **Issues Completed**: 0/18 - **Phases Completed**: 0/7 -- **Estimated Total Effort**: 24-31 hours +- **Estimated Total Effort**: 27-35 hours ### Current Status @@ -124,15 +125,16 @@ All implementation tasks have been broken down into 18 GitHub issues organized i The minimum viable implementation follows this path: -1. #107 → #108 → #109 (Infrastructure) +1. #107 → #108 (Infrastructure) 2. #110 (Configuration) 3. #111 (CLI Command) 4. #112, #113, #115 (I/O and AST - parallel) 5. #117, #118, #119 (API components - parallel) 6. #116 (ClaudeKit wrapper) 7. #114 (Library writer) -8. #120 (Orchestration) -9. #123 (Documentation) +8. #120 (Orchestration, Part 1: single-shot) +9. #168 (Convergence loop, Part 2) +10. #123 (Documentation) **Minimum Path Effort**: ~18-22 hours **Can Skip for MVP**: Issues #121, #122, #124 (testing infrastructure) @@ -145,7 +147,6 @@ The minimum viable implementation follows this path: # Start with Phase 1 gh issue view 107 gh issue view 108 -gh issue view 109 # Then move to Phase 2 gh issue view 110 @@ -169,17 +170,16 @@ gh issue list --state closed --label infrastructure,configuration,cli,io,api,orc ## Architecture Overview -### Three-Target Design +### Target Design -1. **ClaudeKit** - OpenAPI-generated Claude API client -2. **AiSTKit** - SDK/bridge layer for domain logic -3. **skit-aist** - CLI executable for user interaction +1. **ClaudeKit** (new) - OpenAPI-generated Claude API client +2. **AiSTKit** (new) - SDK/bridge layer for domain logic +3. **skit** (existing) - gains an `analyze` subcommand for user interaction ### Key Dependencies - **Swift OpenAPI Generator** - Type-safe API client generation -- **swift-configuration** - CLI/ENV configuration management -- **ConfigKeyKit** - Configuration key abstraction +- **swift-argument-parser** - CLI argument parsing (already used by skit) - **SyntaxParser** - Existing AST generation (reused) ### Data Flow @@ -233,7 +233,7 @@ Input Folder (dsl.swift, expected.swift) ```bash # Optional: Create project board -gh project create --title "skit-aist Implementation" \ +gh project create --title "skit analyze Implementation" \ --body "Track implementation of AI-powered AST generation tool" ``` @@ -253,5 +253,5 @@ For questions or issues, please comment on the relevant GitHub issue or create a --- -**Last Updated**: 2026-02-09 +**Last Updated**: 2026-06-11 **Status**: Planning Complete, Implementation Ready diff --git a/Scripts/ISSUE_CREATION_SUMMARY.md b/Scripts/ISSUE_CREATION_SUMMARY.md index ff0c8aed..3c8114f5 100644 --- a/Scripts/ISSUE_CREATION_SUMMARY.md +++ b/Scripts/ISSUE_CREATION_SUMMARY.md @@ -18,7 +18,7 @@ Successfully created 18 GitHub issues from the skit-analyze-plan.md implementati - Dependencies: #107 - Files: Package.swift -**Issue #109: Create ConfigKeyKit Target Structure** +**Issue #109: Create ConfigKeyKit Target Structure** *(closed — ConfigKeyKit dropped in favor of ArgumentParser)* - Labels: infrastructure, setup - Dependencies: #108 - Files: Package.swift @@ -27,13 +27,13 @@ Successfully created 18 GitHub issues from the skit-analyze-plan.md implementati **Issue #110: Implement AnalyzerConfiguration and AnalyzerError** - Labels: enhancement, configuration -- Dependencies: #109 +- Dependencies: #108 - Files: Sources/AiSTKit/AnalyzerConfiguration.swift, Sources/AiSTKit/AnalyzerError.swift -**Issue #111: Implement AnalyzeCommand and Main Entry Point** +**Issue #111: Implement skit analyze Subcommand (ArgumentParser)** - Labels: enhancement, cli - Dependencies: #110 -- Files: Sources/skit-aist/AnalyzeCommand.swift, Sources/skit-aist/main.swift +- Files: Sources/skit/Skit+Analyze.swift, Sources/skit/Skit.swift ### Phase 3: Input/Output Handlers (Issues #112-#115) @@ -103,7 +103,7 @@ Successfully created 18 GitHub issues from the skit-analyze-plan.md implementati **Issue #123: Create Example Usage Documentation** - Labels: documentation - Dependencies: #120 -- Files: Docs/skit-aist-usage.md +- Files: Docs/skit-analyze-usage.md **Issue #124: Create Integration Tests** - Labels: testing, integration @@ -146,7 +146,7 @@ Issues should be worked on in dependency order: ## Quick Reference Commands ```bash -# View all skit-aist issues +# View all skit analyze issues gh issue list --label infrastructure,configuration,cli,io,api,orchestration # View issues by phase (using labels) @@ -187,5 +187,5 @@ gh issue view 107 ```bash # Optional: Create a project board -gh project create --title "skit-aist Implementation" --body "Track skit-aist tool development" +gh project create --title "skit analyze Implementation" --body "Track skit analyze tool development" ``` diff --git a/Scripts/issue-config.json b/Scripts/issue-config.json index 173e4f46..9cc19fff 100644 --- a/Scripts/issue-config.json +++ b/Scripts/issue-config.json @@ -20,7 +20,10 @@ "id": 1, "phase": "Phase 1: Project Setup & Infrastructure", "title": "Setup OpenAPI Specification and Generator Configuration", - "labels": ["infrastructure", "setup"], + "labels": [ + "infrastructure", + "setup" + ], "dependencies": [], "files": [ "Sources/ClaudeKit/openapi.json", @@ -38,51 +41,45 @@ "id": 2, "phase": "Phase 1: Project Setup & Infrastructure", "title": "Update Package.swift with Dependencies and Targets", - "labels": ["infrastructure", "setup"], - "dependencies": [1], - "files": ["Package.swift"], - "spec": "Add all required dependencies (swift-configuration, OpenAPI packages) and create three new targets: ClaudeKit, AiSTKit, and skit-aist executable.", + "labels": [ + "infrastructure", + "setup" + ], + "dependencies": [ + 1 + ], + "files": [ + "Package.swift" + ], + "spec": "Add the OpenAPI package dependencies and create two new targets (ClaudeKit, AiSTKit), then add AiSTKit as a dependency of the existing skit executable target. No new executable or product is created; the analyze command ships inside skit.", "acceptance": [ - "swift-configuration dependency added with CommandLineArguments trait", "swift-openapi-generator, swift-openapi-runtime, swift-openapi-urlsession dependencies added", "ClaudeKit target created with OpenAPIGenerator plugin", "AiSTKit target created with dependencies on ClaudeKit and SyntaxParser", - "skit-aist executable target created with all required dependencies", - "skit-aist product exported as executable", + "AiSTKit added to the existing skit executable target's dependencies", + "No new executable target or product is added", "Package builds successfully: swift build" ] }, - { - "id": 3, - "phase": "Phase 1: Project Setup & Infrastructure", - "title": "Create ConfigKeyKit Target Structure", - "labels": ["infrastructure", "setup"], - "dependencies": [2], - "files": ["Package.swift"], - "spec": "Add ConfigKeyKit as a library target in Package.swift with swift-configuration dependency.", - "acceptance": [ - "ConfigKeyKit added as a library target in Package.swift", - "ConfigKeyKit has swift-configuration dependency", - "ConfigKeyKit pattern is compatible with existing code", - "Package builds successfully" - ] - }, { "id": 4, "phase": "Phase 2: Core Configuration & Command Infrastructure", "title": "Implement AnalyzerConfiguration and AnalyzerError", - "labels": ["enhancement", "configuration"], - "dependencies": [3], + "labels": [ + "enhancement", + "configuration" + ], + "dependencies": [ + 2 + ], "files": [ "Sources/AiSTKit/AnalyzerConfiguration.swift", "Sources/AiSTKit/AnalyzerError.swift" ], - "spec": "Create configuration structure using ConfigKeyKit pattern with support for positional arguments and environment variables. Define comprehensive error types.", + "spec": "Create AnalyzerConfiguration as a plain Sendable value type in AiSTKit (no configuration framework; the skit analyze subcommand assembles it from ArgumentParser-parsed arguments). Define comprehensive error types.", "acceptance": [ - "AnalyzerConfiguration implements ConfigurationParseable protocol", - "Configuration keys defined: syntaxKitPathKey, apiKeyKey, modelKey, verboseKey", - "Positional argument parsing implemented for input folder, syntaxkit path, output folder", - "Path validation logic implemented", + "AnalyzerConfiguration is a plain Sendable struct with inputFolderPath, syntaxKitPath, outputFolderPath, apiKey, model, and verbose properties", + "No dependency on any configuration framework", "AnalyzerError enum defines all error cases", "Code follows one-type-per-file organization" ] @@ -90,21 +87,27 @@ { "id": 5, "phase": "Phase 2: Core Configuration & Command Infrastructure", - "title": "Implement AnalyzeCommand and Main Entry Point", - "labels": ["enhancement", "cli"], - "dependencies": [4], + "title": "Implement skit analyze Subcommand (ArgumentParser)", + "labels": [ + "enhancement", + "cli" + ], + "dependencies": [ + 4 + ], "files": [ - "Sources/skit-aist/AnalyzeCommand.swift", - "Sources/skit-aist/main.swift" + "Sources/skit/Skit+Analyze.swift", + "Sources/skit/Skit.swift" ], - "spec": "Create command implementation using ConfigKeyKit Command protocol and main entry point with error handling.", + "spec": "Add an Analyze subcommand to the existing skit CLI using ArgumentParser, following the same pattern as Skit.Run and Skit.Parse. Register it in Skit.swift's subcommand list. No new executable or main.swift is needed.", "acceptance": [ - "AnalyzeCommand implements Command protocol", - "commandName, abstract, and helpText defined with complete usage information", - "createInstance() creates ConfigReader with CLI and ENV providers", - "execute() delegates to SyntaxKitAnalyzer", - "main.swift implements @main entry point with error handling", - "Help text documents all arguments and options", + "Skit.Analyze implements AsyncParsableCommand in Sources/skit/Skit+Analyze.swift", + "Three required positional @Arguments: input folder, SyntaxKit path, output folder", + "@Option --api-key (optional, falls back to ANTHROPIC_API_KEY), @Option --model with default, @Flag --verbose", + "validate() checks input folder and SyntaxKit path exist", + "run() resolves the API key, builds AnalyzerConfiguration, and delegates to SyntaxKitAnalyzer", + "Analyze registered in Skit.swift subcommands alongside Run and Parse", + "skit analyze --help shows generated usage information", "Code follows one-type-per-file organization" ] }, @@ -112,9 +115,16 @@ "id": 6, "phase": "Phase 3: Input/Output Handlers", "title": "Implement InputFolderReader", - "labels": ["enhancement", "io"], - "dependencies": [4], - "files": ["Sources/AiSTKit/InputFolderReader.swift"], + "labels": [ + "enhancement", + "io" + ], + "dependencies": [ + 4 + ], + "files": [ + "Sources/AiSTKit/InputFolderReader.swift" + ], "spec": "Create input folder reader that validates and reads dsl.swift and expected.swift files.", "acceptance": [ "InputFolderReader struct created with folderPath property", @@ -129,9 +139,16 @@ "id": 7, "phase": "Phase 3: Input/Output Handlers", "title": "Implement LibraryCollector", - "labels": ["enhancement", "io"], - "dependencies": [4], - "files": ["Sources/AiSTKit/LibraryCollector.swift"], + "labels": [ + "enhancement", + "io" + ], + "dependencies": [ + 4 + ], + "files": [ + "Sources/AiSTKit/LibraryCollector.swift" + ], "spec": "Create library collector that recursively scans SyntaxKit directory for Swift source files.", "acceptance": [ "LibraryCollector struct created", @@ -147,9 +164,16 @@ "id": 8, "phase": "Phase 3: Input/Output Handlers", "title": "Implement LibraryWriter", - "labels": ["enhancement", "io"], - "dependencies": [12], - "files": ["Sources/AiSTKit/LibraryWriter.swift"], + "labels": [ + "enhancement", + "io" + ], + "dependencies": [ + 12 + ], + "files": [ + "Sources/AiSTKit/LibraryWriter.swift" + ], "spec": "Create library writer that writes LibraryUpdateResult to output directory with proper structure.", "acceptance": [ "LibraryWriter struct created with outputPath property", @@ -164,9 +188,16 @@ "id": 9, "phase": "Phase 3: Input/Output Handlers", "title": "Implement ASTGenerator", - "labels": ["enhancement", "ast"], - "dependencies": [4], - "files": ["Sources/AiSTKit/ASTGenerator.swift"], + "labels": [ + "enhancement", + "ast" + ], + "dependencies": [ + 4 + ], + "files": [ + "Sources/AiSTKit/ASTGenerator.swift" + ], "spec": "Create AST generator that wraps SyntaxParser to produce JSON AST from Swift code.", "acceptance": [ "ASTGenerator struct created", @@ -181,9 +212,18 @@ "id": 10, "phase": "Phase 4: Claude API Integration", "title": "Implement ClaudeKit Wrapper", - "labels": ["enhancement", "api"], - "dependencies": [2, 11, 13], - "files": ["Sources/AiSTKit/ClaudeKit.swift"], + "labels": [ + "enhancement", + "api" + ], + "dependencies": [ + 2, + 11, + 13 + ], + "files": [ + "Sources/AiSTKit/ClaudeKit.swift" + ], "spec": "Create ClaudeKit wrapper around OpenAPI-generated client for code generation API calls.", "acceptance": [ "ClaudeKit struct created with apiKey, model, and client properties", @@ -198,9 +238,16 @@ "id": 11, "phase": "Phase 4: Claude API Integration", "title": "Implement AuthenticationMiddleware", - "labels": ["enhancement", "api"], - "dependencies": [2], - "files": ["Sources/AiSTKit/AuthenticationMiddleware.swift"], + "labels": [ + "enhancement", + "api" + ], + "dependencies": [ + 2 + ], + "files": [ + "Sources/AiSTKit/AuthenticationMiddleware.swift" + ], "spec": "Create OpenAPI middleware that adds Anthropic API authentication headers.", "acceptance": [ "AuthenticationMiddleware implements ClientMiddleware protocol", @@ -214,8 +261,13 @@ "id": 12, "phase": "Phase 4: Claude API Integration", "title": "Implement LibraryUpdateResult and FileReference Models", - "labels": ["enhancement", "models"], - "dependencies": [4], + "labels": [ + "enhancement", + "models" + ], + "dependencies": [ + 4 + ], "files": [ "Sources/AiSTKit/LibraryUpdateResult.swift", "Sources/AiSTKit/FileReference.swift" @@ -234,9 +286,14 @@ "id": 13, "phase": "Phase 4: Claude API Integration", "title": "Implement PromptTemplate", - "labels": ["enhancement", "prompts"], + "labels": [ + "enhancement", + "prompts" + ], "dependencies": [], - "files": ["Sources/AiSTKit/PromptTemplate.swift"], + "files": [ + "Sources/AiSTKit/PromptTemplate.swift" + ], "spec": "Create prompt template that combines Workbench analysis prompt with code generation instructions.", "acceptance": [ "PromptTemplate struct created", @@ -253,9 +310,20 @@ "id": 14, "phase": "Phase 5: Main Orchestration", "title": "Implement SyntaxKitAnalyzer Orchestration", - "labels": ["enhancement", "orchestration"], - "dependencies": [6, 7, 8, 9, 10], - "files": ["Sources/AiSTKit/SyntaxKitAnalyzer.swift"], + "labels": [ + "enhancement", + "orchestration" + ], + "dependencies": [ + 6, + 7, + 8, + 9, + 10 + ], + "files": [ + "Sources/AiSTKit/SyntaxKitAnalyzer.swift" + ], "spec": "Create main orchestrator that coordinates the entire workflow from input reading through library writing.", "acceptance": [ "SyntaxKitAnalyzer struct created with config property", @@ -270,8 +338,13 @@ "id": 15, "phase": "Phase 6: Testing Infrastructure", "title": "Implement Test/Validation Mode Components", - "labels": ["enhancement", "testing"], - "dependencies": [14], + "labels": [ + "enhancement", + "testing" + ], + "dependencies": [ + 14 + ], "files": [ "Sources/AiSTKit/Testing/TestRunner.swift", "Sources/AiSTKit/Testing/TestCaseDiscoverer.swift", @@ -293,8 +366,12 @@ "id": 16, "phase": "Phase 7: Verification & Documentation", "title": "Create Verification Test Cases", - "labels": ["testing"], - "dependencies": [15], + "labels": [ + "testing" + ], + "dependencies": [ + 15 + ], "files": [ "examples/simple-property/dsl.swift", "examples/simple-property/expected.swift", @@ -317,9 +394,15 @@ "id": 17, "phase": "Phase 7: Verification & Documentation", "title": "Create Example Usage Documentation", - "labels": ["documentation"], - "dependencies": [14], - "files": ["Docs/skit-aist-usage.md"], + "labels": [ + "documentation" + ], + "dependencies": [ + 14 + ], + "files": [ + "Docs/skit-analyze-usage.md" + ], "spec": "Create comprehensive usage documentation with examples for basic and advanced usage scenarios.", "acceptance": [ "Basic example workflow documented", @@ -335,9 +418,16 @@ "id": 18, "phase": "Phase 7: Verification & Documentation", "title": "Create Integration Tests", - "labels": ["testing", "integration"], - "dependencies": [16], - "files": ["Tests/AiSTKitTests/IntegrationTests.swift"], + "labels": [ + "testing", + "integration" + ], + "dependencies": [ + 16 + ], + "files": [ + "Tests/AiSTKitTests/IntegrationTests.swift" + ], "spec": "Create end-to-end integration test using a real missing feature to verify the entire pipeline.", "acceptance": [ "Integration test using real missing feature (e.g., subscript syntax)", @@ -346,6 +436,37 @@ "Test verifies code compiles", "Test verifies feature works as expected" ] + }, + { + "id": 19, + "githubNumber": 168, + "phase": "Phase 5: Main Orchestration (Part 2)", + "title": "Implement Convergence Loop (iterate until rendered output matches expected.swift)", + "labels": [ + "enhancement", + "orchestration" + ], + "dependencies": [ + 14 + ], + "files": [ + "Sources/AiSTKit/LibraryVerifying.swift", + "Sources/AiSTKit/VerificationResult.swift", + "Sources/AiSTKit/ConvergenceLoop.swift", + "Sources/AiSTKit/PromptTemplate+Feedback.swift", + "Sources/skit/SubprocessLibraryVerifier.swift", + "Sources/skit/Skit+Analyze.swift" + ], + "spec": "Wrap the single-shot generation pipeline (#120) in a convergence loop: build the generated library, render dsl.swift against it (compile-and-run, like skit run), diff the rendered Swift against expected.swift, and re-prompt Claude with the build errors or diff until the output matches or --max-iterations is reached. AiSTKit defines the LibraryVerifying protocol and ConvergenceLoop driver; skit supplies the Subprocess-backed verifier, keeping Subprocess out of AiSTKit per the SDK/CLI boundary. Consider using swift-service-lifecycle (https://github.com/swift-server/swift-service-lifecycle) to run the loop: it is a long-running process and ServiceLifecycle's graceful-shutdown handling would cancel in-flight API calls/subprocesses, clean up temp build artifacts, and report partial progress on Ctrl-C. Evaluate versus plain structured concurrency.", + "acceptance": [ + "LibraryVerifying protocol defined in AiSTKit with no Subprocess dependency", + "Subprocess-backed verifier in skit: builds the generated library, renders dsl.swift against it via compile-and-run, captures build errors and rendered output", + "ConvergenceLoop drives generate \u2192 verify \u2192 re-prompt cycles, capped by --max-iterations (default 3)", + "Re-prompt includes swift build errors or a unified diff of rendered vs expected output", + "skit analyze reports converged/diverged status and iteration count; non-zero exit on divergence", + "Diff comparison normalizes whitespace/formatting before declaring a mismatch", + "Code follows one-type-per-file organization" + ] } ] -} +} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/Command.swift b/Sources/ConfigKeyKit/Command.swift deleted file mode 100644 index 693b23c0..00000000 --- a/Sources/ConfigKeyKit/Command.swift +++ /dev/null @@ -1,61 +0,0 @@ -// -// Command.swift -// ConfigKeyKit -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -/// Generic protocol for CLI commands using Swift Configuration -public protocol Command: Sendable { - /// Associated configuration type for this command - associatedtype Config: ConfigurationParseable - - /// Command name for CLI parsing - static var commandName: String { get } - - /// Abstract description of the command - static var abstract: String { get } - - /// Detailed help text for the command - static var helpText: String { get } - - /// Initialize command with configuration - init(config: Config) - - /// Execute the command asynchronously - func execute() async throws - - /// Create a command instance with configuration - static func createInstance() async throws -> Self -} - -public extension Command { - /// Print help information for this command - static func printHelp() { - print(helpText) - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/CommandConfiguration.swift b/Sources/ConfigKeyKit/CommandConfiguration.swift deleted file mode 100644 index 03ffdcd0..00000000 --- a/Sources/ConfigKeyKit/CommandConfiguration.swift +++ /dev/null @@ -1,39 +0,0 @@ -// -// CommandConfiguration.swift -// ConfigKeyKit -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -/// Command configuration for identifying and routing commands -public struct CommandConfiguration { - public let commandName: String - public let abstract: String - - public init(commandName: String, abstract: String) { - self.commandName = commandName - self.abstract = abstract - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/CommandLineParser.swift b/Sources/ConfigKeyKit/CommandLineParser.swift deleted file mode 100644 index a7c2f8ad..00000000 --- a/Sources/ConfigKeyKit/CommandLineParser.swift +++ /dev/null @@ -1,74 +0,0 @@ -// -// CommandLineParser.swift -// ConfigKeyKit -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -/// Command line argument parser for Swift Configuration integration -public struct CommandLineParser { - private let arguments: [String] - - public init(arguments: [String] = CommandLine.arguments) { - self.arguments = arguments - } - - /// Parse the command name from command line arguments - public func parseCommandName() -> String? { - // Skip the executable name (first argument) - guard arguments.count > 1 else { return nil } - let commandCandidate = arguments[1] - - // If it starts with '--', it's not a command but a global option - if commandCandidate.hasPrefix("--") { - return nil - } - - return commandCandidate - } - - /// Get all arguments after the command name for command-specific parsing - public func commandArguments() -> [String] { - guard arguments.count > 1 else { return [] } - let commandName = arguments[1] - - // If first argument is an option, return all arguments for global parsing - if commandName.hasPrefix("--") { - return Array(arguments.dropFirst()) - } - - // Return arguments after command name - return Array(arguments.dropFirst(2)) - } - - /// Check if help was requested - public func isHelpRequested() -> Bool { - arguments.contains { arg in - arg == "--help" || arg == "-h" || arg == "help" - } - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/CommandRegistry.swift b/Sources/ConfigKeyKit/CommandRegistry.swift deleted file mode 100644 index 39f9e8ed..00000000 --- a/Sources/ConfigKeyKit/CommandRegistry.swift +++ /dev/null @@ -1,88 +0,0 @@ -// -// CommandRegistry.swift -// ConfigKeyKit -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -/// Actor-based registry for managing available commands -public actor CommandRegistry { - private var registeredCommands: [String: any Command.Type] = [:] - private var commandMetadata: [String: CommandMetadata] = [:] - - /// Metadata about a command - public struct CommandMetadata: Sendable { - public let commandName: String - public let abstract: String - public let helpText: String - } - - /// Shared instance - public static let shared = CommandRegistry() - - // Internal initializer for testability - allows tests to create isolated instances - internal init() {} - - /// Register a command type with the registry - public func register(_ commandType: T.Type) { - registeredCommands[T.commandName] = commandType - commandMetadata[T.commandName] = CommandMetadata( - commandName: T.commandName, - abstract: T.abstract, - helpText: T.helpText - ) - } - - /// Get all registered command names - public var availableCommands: [String] { - Array(registeredCommands.keys).sorted() - } - - /// Get command metadata - public func metadata(for name: String) -> CommandMetadata? { - commandMetadata[name] - } - - /// Get command type for the given name - public func commandType(named name: String) -> (any Command.Type)? { - return registeredCommands[name] - } - - /// Create a command instance dynamically with automatic config parsing - public func createCommand(named name: String) async throws -> any Command { - guard let commandType = registeredCommands[name] else { - throw CommandRegistryError.unknownCommand(name) - } - - return try await commandType.createInstance() - } - - /// Check if a command is registered - public func isRegistered(_ name: String) -> Bool { - return registeredCommands[name] != nil - } -} diff --git a/Sources/ConfigKeyKit/CommandRegistryError.swift b/Sources/ConfigKeyKit/CommandRegistryError.swift deleted file mode 100644 index 84e7848e..00000000 --- a/Sources/ConfigKeyKit/CommandRegistryError.swift +++ /dev/null @@ -1,42 +0,0 @@ -// -// CommandRegistryError.swift -// ConfigKeyKit -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -public import Foundation - -/// Errors that can occur in command registry operations -public enum CommandRegistryError: Error, LocalizedError { - case unknownCommand(String) - - public var errorDescription: String? { - switch self { - case .unknownCommand(let name): - return "Unknown command: \(name)" - } - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigKey+Bool.swift b/Sources/ConfigKeyKit/ConfigKey+Bool.swift deleted file mode 100644 index afb6819e..00000000 --- a/Sources/ConfigKeyKit/ConfigKey+Bool.swift +++ /dev/null @@ -1,72 +0,0 @@ -// -// ConfigKey+Bool.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -// MARK: - Specialized Initializers for Booleans - -extension ConfigKey where Value == Bool { - /// Non-optional default value accessor for booleans - @available(*, deprecated, message: "Use defaultValue directly instead") - public var boolDefault: Bool { - defaultValue // Already non-optional! - } - - /// Initialize a boolean configuration key with non-optional default - /// - Parameters: - /// - cli: Command-line argument name - /// - env: Environment variable name - /// - defaultVal: Default value (defaults to false) - public init(cli: String, env: String, default defaultVal: Bool = false) { - self.baseKey = nil - self.styles = [:] - var keys: [ConfigKeySource: String] = [:] - keys[.commandLine] = cli - keys[.environment] = env - self.explicitKeys = keys - self.defaultValue = defaultVal - } - - /// Initialize a boolean configuration key from base string - /// - Parameters: - /// - base: Base key string (e.g., "sync.verbose") - /// - envPrefix: Prefix for environment variable (defaults to nil) - /// - defaultVal: Default value (defaults to false) - public init(_ base: String, envPrefix: String? = nil, default defaultVal: Bool = false) { - self.baseKey = base - self.styles = [ - .commandLine: StandardNamingStyle.dotSeparated, - .environment: StandardNamingStyle.screamingSnakeCase(prefix: envPrefix), - ] - self.explicitKeys = [:] - self.defaultValue = defaultVal - } -} - -// Application-specific boolean key helpers should be added in application code \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigKey+Debug.swift b/Sources/ConfigKeyKit/ConfigKey+Debug.swift deleted file mode 100644 index 3e101ab8..00000000 --- a/Sources/ConfigKeyKit/ConfigKey+Debug.swift +++ /dev/null @@ -1,36 +0,0 @@ -// -// ConfigKey+Debug.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -extension ConfigKey: CustomDebugStringConvertible { - public var debugDescription: String { - let cliKey = key(for: .commandLine) ?? "nil" - let envKey = key(for: .environment) ?? "nil" - return "ConfigKey(cli: \(cliKey), env: \(envKey), default: \(defaultValue))" - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigKey.swift b/Sources/ConfigKeyKit/ConfigKey.swift deleted file mode 100644 index 8d43e7c5..00000000 --- a/Sources/ConfigKeyKit/ConfigKey.swift +++ /dev/null @@ -1,113 +0,0 @@ -// -// ConfigKey.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -// MARK: - Generic Configuration Key - -/// Configuration key for values with default fallbacks -/// -/// Use `ConfigKey` when a configuration value has a sensible default -/// that should be used when not provided by the user. The `read()` method -/// will always return a non-optional value. -/// -/// Example: -/// ```swift -/// let containerID = ConfigKey( -/// base: "cloudkit.container_id", -/// default: "iCloud.com.example.MyApp" -/// ) -/// // read(containerID) returns String (non-optional) -/// ``` -public struct ConfigKey: ConfigurationKey, Sendable { - internal let baseKey: String? - internal let styles: [ConfigKeySource: any NamingStyle] - internal let explicitKeys: [ConfigKeySource: String] - public let defaultValue: Value // Non-optional! - - /// The base key string used for this configuration key - public var base: String? { baseKey } - - /// Initialize with explicit CLI and ENV keys and required default - public init(cli: String? = nil, env: String? = nil, default defaultVal: Value) { - self.baseKey = nil - self.styles = [:] - var keys: [ConfigKeySource: String] = [:] - if let cli = cli { keys[.commandLine] = cli } - if let env = env { keys[.environment] = env } - self.explicitKeys = keys - self.defaultValue = defaultVal - } - - /// Initialize from a base key string with naming styles and required default - /// - Parameters: - /// - base: Base key string (e.g., "cloudkit.container_id") - /// - styles: Dictionary mapping sources to naming styles - /// - defaultVal: Required default value - public init( - base: String, - styles: [ConfigKeySource: any NamingStyle], - default defaultVal: Value - ) { - self.baseKey = base - self.styles = styles - self.explicitKeys = [:] - self.defaultValue = defaultVal - } - - /// Convenience initializer with standard naming conventions and required default - /// - Parameters: - /// - base: Base key string (e.g., "cloudkit.container_id") - /// - envPrefix: Prefix for environment variable (defaults to nil) - /// - defaultVal: Required default value - public init(_ base: String, envPrefix: String? = nil, default defaultVal: Value) { - self.baseKey = base - self.styles = [ - .commandLine: StandardNamingStyle.dotSeparated, - .environment: StandardNamingStyle.screamingSnakeCase(prefix: envPrefix), - ] - self.explicitKeys = [:] - self.defaultValue = defaultVal - } - - public func key(for source: ConfigKeySource) -> String? { - // Check for explicit key first - if let explicit = explicitKeys[source] { - return explicit - } - - // Generate from base key and style - guard let base = baseKey, let style = styles[source] else { - return nil - } - - return style.transform(base) - } -} - diff --git a/Sources/ConfigKeyKit/ConfigKeySource.swift b/Sources/ConfigKeyKit/ConfigKeySource.swift deleted file mode 100644 index 96a928b0..00000000 --- a/Sources/ConfigKeyKit/ConfigKeySource.swift +++ /dev/null @@ -1,39 +0,0 @@ -// -// ConfigKeySource.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -// MARK: - Configuration Key Source - -/// Source for configuration keys (CLI arguments or environment variables) -public enum ConfigKeySource: CaseIterable, Sendable { - /// Command-line arguments (e.g., --cloudkit-container-id) - case commandLine - - /// Environment variables (e.g., CLOUDKIT_CONTAINER_ID) - case environment -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/ConfigurationKey.swift b/Sources/ConfigKeyKit/ConfigurationKey.swift deleted file mode 100644 index a2f015da..00000000 --- a/Sources/ConfigKeyKit/ConfigurationKey.swift +++ /dev/null @@ -1,40 +0,0 @@ -// -// ConfigurationKey.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -// MARK: - Configuration Key Protocol - -/// Protocol for configuration keys that support multiple sources -public protocol ConfigurationKey: Sendable { - /// Get the key string for a specific source - /// - Parameter source: The configuration source (CLI or ENV) - /// - Returns: The key string for that source, or nil if the key doesn't support that source - func key(for source: ConfigKeySource) -> String? -} diff --git a/Sources/ConfigKeyKit/ConfigurationParseable.swift b/Sources/ConfigKeyKit/ConfigurationParseable.swift deleted file mode 100644 index 0ed4d0a0..00000000 --- a/Sources/ConfigKeyKit/ConfigurationParseable.swift +++ /dev/null @@ -1,54 +0,0 @@ -// -// ConfigurationParseable.swift -// ConfigKeyKit -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -/// Protocol for configuration types that can parse themselves from command line arguments and environment variables -public protocol ConfigurationParseable: Sendable { - /// Associated type for the configuration reader - associatedtype ConfigReader: Sendable - - /// Associated type for the parent configuration - /// Use `Never` for root configurations that have no parent - associatedtype BaseConfig: Sendable - - /// Initialize the configuration by parsing from available sources (CLI args, environment variables, defaults) - /// - Parameters: - /// - configuration: The configuration reader to parse values from - /// - base: Optional parent configuration (nil for root configs) - init(configuration: ConfigReader, base: BaseConfig?) async throws -} - -/// Extension for root configurations (where BaseConfig == Never) -public extension ConfigurationParseable where BaseConfig == Never { - /// Convenience initializer for root configs that don't need a parent - init(configuration: ConfigReader) async throws { - try await self.init(configuration: configuration, base: nil) - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/NamingStyle.swift b/Sources/ConfigKeyKit/NamingStyle.swift deleted file mode 100644 index f9982f46..00000000 --- a/Sources/ConfigKeyKit/NamingStyle.swift +++ /dev/null @@ -1,38 +0,0 @@ -// -// NamingStyle.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -// MARK: - Naming Style - -/// Protocol for transforming base key strings into different naming conventions -public protocol NamingStyle: Sendable { - /// Transform a base key string according to this naming style - /// - Parameter base: Base key string (e.g., "cloudkit.container_id") - /// - Returns: Transformed key string - func transform(_ base: String) -> String -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift b/Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift deleted file mode 100644 index e9e0dabe..00000000 --- a/Sources/ConfigKeyKit/OptionalConfigKey+Debug.swift +++ /dev/null @@ -1,36 +0,0 @@ -// -// OptionalConfigKey+Debug.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -extension OptionalConfigKey: CustomDebugStringConvertible { - public var debugDescription: String { - let cliKey = key(for: .commandLine) ?? "nil" - let envKey = key(for: .environment) ?? "nil" - return "OptionalConfigKey(cli: \(cliKey), env: \(envKey))" - } -} \ No newline at end of file diff --git a/Sources/ConfigKeyKit/OptionalConfigKey.swift b/Sources/ConfigKeyKit/OptionalConfigKey.swift deleted file mode 100644 index 24cfada5..00000000 --- a/Sources/ConfigKeyKit/OptionalConfigKey.swift +++ /dev/null @@ -1,103 +0,0 @@ -// -// OptionalConfigKey.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -// MARK: - Optional Configuration Key - -/// Configuration key for optional values without defaults -/// -/// Use `OptionalConfigKey` when a configuration value has no sensible default -/// and should be `nil` when not provided by the user. The `read()` method -/// will return an optional value. -/// -/// Example: -/// ```swift -/// let apiKey = OptionalConfigKey(base: "api.key") -/// // read(apiKey) returns String? -/// ``` -public struct OptionalConfigKey: ConfigurationKey, Sendable { - internal let baseKey: String? - internal let styles: [ConfigKeySource: any NamingStyle] - internal let explicitKeys: [ConfigKeySource: String] - - /// The base key string used for this configuration key - public var base: String? { baseKey } - - /// Initialize with explicit CLI and ENV keys (no default) - public init(cli: String? = nil, env: String? = nil) { - self.baseKey = nil - self.styles = [:] - var keys: [ConfigKeySource: String] = [:] - if let cli = cli { keys[.commandLine] = cli } - if let env = env { keys[.environment] = env } - self.explicitKeys = keys - } - - /// Initialize from a base key string with naming styles (no default) - /// - Parameters: - /// - base: Base key string (e.g., "cloudkit.key_id") - /// - styles: Dictionary mapping sources to naming styles - public init( - base: String, - styles: [ConfigKeySource: any NamingStyle] - ) { - self.baseKey = base - self.styles = styles - self.explicitKeys = [:] - } - - /// Convenience initializer with standard naming conventions (no default) - /// - Parameters: - /// - base: Base key string (e.g., "cloudkit.key_id") - /// - envPrefix: Prefix for environment variable (defaults to nil) - public init(_ base: String, envPrefix: String? = nil) { - self.baseKey = base - self.styles = [ - .commandLine: StandardNamingStyle.dotSeparated, - .environment: StandardNamingStyle.screamingSnakeCase(prefix: envPrefix), - ] - self.explicitKeys = [:] - } - - public func key(for source: ConfigKeySource) -> String? { - // Check for explicit key first - if let explicit = explicitKeys[source] { - return explicit - } - - // Generate from base key and style - guard let base = baseKey, let style = styles[source] else { - return nil - } - - return style.transform(base) - } -} - diff --git a/Sources/ConfigKeyKit/StandardNamingStyle.swift b/Sources/ConfigKeyKit/StandardNamingStyle.swift deleted file mode 100644 index 82cb32b5..00000000 --- a/Sources/ConfigKeyKit/StandardNamingStyle.swift +++ /dev/null @@ -1,53 +0,0 @@ -// -// StandardNamingStyle.swift -// MistDemo -// -// Created by Leo Dion. -// Copyright © 2026 BrightDigit. -// -// 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. -// - -import Foundation - -/// Common naming styles for configuration keys -public enum StandardNamingStyle: NamingStyle, Sendable { - /// Dot-separated lowercase (e.g., "cloudkit.container_id") - case dotSeparated - - /// Screaming snake case with prefix (e.g., "APP_CLOUDKIT_CONTAINER_ID") - case screamingSnakeCase(prefix: String?) - - public func transform(_ base: String) -> String { - switch self { - case .dotSeparated: - return base - - case .screamingSnakeCase(let prefix): - let snakeCase = base.uppercased().replacingOccurrences(of: ".", with: "_") - if let prefix = prefix { - return "\(prefix)_\(snakeCase)" - } - return snakeCase - } - } -} \ No newline at end of file From 07f505bd49fcd1b80dfeb8d436443b603e0180be Mon Sep 17 00:00:00 2001 From: leogdion Date: Fri, 12 Jun 2026 15:53:01 -0400 Subject: [PATCH 9/9] Setting up OpenAPI with Claude (#169) --- .claude/TM_COMMANDS_GUIDE.md | 147 - .claude/agents/task-checker.md | 162 - .claude/agents/task-executor.md | 70 - .claude/agents/task-orchestrator.md | 130 - .../tm/add-dependency/add-dependency.md | 55 - .../commands/tm/add-subtask/add-subtask.md | 76 - .../tm/add-subtask/convert-task-to-subtask.md | 71 - .claude/commands/tm/add-task/add-task.md | 78 - .../analyze-complexity/analyze-complexity.md | 121 - .../tm/clear-subtasks/clear-all-subtasks.md | 93 - .../tm/clear-subtasks/clear-subtasks.md | 86 - .../tm/complexity-report/complexity-report.md | 117 - .../commands/tm/expand/expand-all-tasks.md | 51 - .claude/commands/tm/expand/expand-task.md | 49 - .../tm/fix-dependencies/fix-dependencies.md | 81 - .../commands/tm/generate/generate-tasks.md | 121 - .claude/commands/tm/help.md | 81 - .../commands/tm/init/init-project-quick.md | 46 - .claude/commands/tm/init/init-project.md | 50 - .claude/commands/tm/learn.md | 103 - .../commands/tm/list/list-tasks-by-status.md | 39 - .../tm/list/list-tasks-with-subtasks.md | 29 - .claude/commands/tm/list/list-tasks.md | 43 - .claude/commands/tm/models/setup-models.md | 51 - .claude/commands/tm/models/view-models.md | 51 - .claude/commands/tm/next/next-task.md | 66 - .../tm/parse-prd/parse-prd-with-research.md | 48 - .claude/commands/tm/parse-prd/parse-prd.md | 49 - .../tm/remove-dependency/remove-dependency.md | 62 - .../tm/remove-subtask/remove-subtask.md | 84 - .../commands/tm/remove-task/remove-task.md | 107 - .../commands/tm/set-status/to-cancelled.md | 55 - .claude/commands/tm/set-status/to-deferred.md | 47 - .claude/commands/tm/set-status/to-done.md | 44 - .../commands/tm/set-status/to-in-progress.md | 36 - .claude/commands/tm/set-status/to-pending.md | 32 - .claude/commands/tm/set-status/to-review.md | 40 - .../commands/tm/setup/install-taskmaster.md | 117 - .../tm/setup/quick-install-taskmaster.md | 22 - .claude/commands/tm/show/show-task.md | 82 - .claude/commands/tm/status/project-status.md | 64 - .../commands/tm/sync-readme/sync-readme.md | 117 - .claude/commands/tm/tm-main.md | 146 - .../commands/tm/update/update-single-task.md | 119 - .claude/commands/tm/update/update-task.md | 72 - .../tm/update/update-tasks-from-id.md | 108 - .claude/commands/tm/utils/analyze-project.md | 97 - .../validate-dependencies.md | 71 - .../tm/workflows/auto-implement-tasks.md | 97 - .../commands/tm/workflows/command-pipeline.md | 77 - .../commands/tm/workflows/smart-workflow.md | 55 - .cursor/mcp.json | 19 - .cursor/rules/cursor_rules.mdc | 53 - .cursor/rules/self_improve.mdc | 72 - .cursor/rules/taskmaster/dev_workflow.mdc | 424 -- .cursor/rules/taskmaster/taskmaster.mdc | 558 -- .env.example | 12 - .github/workflows/SyntaxKit.yml | 3 - .github/workflows/check-unsafe-flags.yml | 1 - .github/workflows/codeql.yml | 2 - .mcp.json | 24 - .swiftlint.yml | 1 + .taskmaster/CLAUDE.md | 417 -- .taskmaster/config.json | 37 - .taskmaster/docs/DOCUMENTATION_MAINTENANCE.md | 271 - CLAUDE.md | 5 +- Docs/skit-analyze-plan.md | 35 +- IMPLEMENTATION_STATUS.md | 28 +- Package.resolved | 38 +- Package.swift | 23 +- Scripts/generate-openapi.sh | 40 + Scripts/header.sh | 13 +- Sources/AiSTKit/AiSTKit.swift | 35 + Sources/ClaudeKit/Generated/Client.swift | 150 + Sources/ClaudeKit/Generated/Types.swift | 2143 ++++++ .../ClaudeKit/openapi-generator-config.yaml | 10 + Sources/ClaudeKit/openapi.json | 6428 +++++++++++++++++ mise.toml | 1 + 78 files changed, 8917 insertions(+), 5841 deletions(-) delete mode 100644 .claude/TM_COMMANDS_GUIDE.md delete mode 100644 .claude/agents/task-checker.md delete mode 100644 .claude/agents/task-executor.md delete mode 100644 .claude/agents/task-orchestrator.md delete mode 100644 .claude/commands/tm/add-dependency/add-dependency.md delete mode 100644 .claude/commands/tm/add-subtask/add-subtask.md delete mode 100644 .claude/commands/tm/add-subtask/convert-task-to-subtask.md delete mode 100644 .claude/commands/tm/add-task/add-task.md delete mode 100644 .claude/commands/tm/analyze-complexity/analyze-complexity.md delete mode 100644 .claude/commands/tm/clear-subtasks/clear-all-subtasks.md delete mode 100644 .claude/commands/tm/clear-subtasks/clear-subtasks.md delete mode 100644 .claude/commands/tm/complexity-report/complexity-report.md delete mode 100644 .claude/commands/tm/expand/expand-all-tasks.md delete mode 100644 .claude/commands/tm/expand/expand-task.md delete mode 100644 .claude/commands/tm/fix-dependencies/fix-dependencies.md delete mode 100644 .claude/commands/tm/generate/generate-tasks.md delete mode 100644 .claude/commands/tm/help.md delete mode 100644 .claude/commands/tm/init/init-project-quick.md delete mode 100644 .claude/commands/tm/init/init-project.md delete mode 100644 .claude/commands/tm/learn.md delete mode 100644 .claude/commands/tm/list/list-tasks-by-status.md delete mode 100644 .claude/commands/tm/list/list-tasks-with-subtasks.md delete mode 100644 .claude/commands/tm/list/list-tasks.md delete mode 100644 .claude/commands/tm/models/setup-models.md delete mode 100644 .claude/commands/tm/models/view-models.md delete mode 100644 .claude/commands/tm/next/next-task.md delete mode 100644 .claude/commands/tm/parse-prd/parse-prd-with-research.md delete mode 100644 .claude/commands/tm/parse-prd/parse-prd.md delete mode 100644 .claude/commands/tm/remove-dependency/remove-dependency.md delete mode 100644 .claude/commands/tm/remove-subtask/remove-subtask.md delete mode 100644 .claude/commands/tm/remove-task/remove-task.md delete mode 100644 .claude/commands/tm/set-status/to-cancelled.md delete mode 100644 .claude/commands/tm/set-status/to-deferred.md delete mode 100644 .claude/commands/tm/set-status/to-done.md delete mode 100644 .claude/commands/tm/set-status/to-in-progress.md delete mode 100644 .claude/commands/tm/set-status/to-pending.md delete mode 100644 .claude/commands/tm/set-status/to-review.md delete mode 100644 .claude/commands/tm/setup/install-taskmaster.md delete mode 100644 .claude/commands/tm/setup/quick-install-taskmaster.md delete mode 100644 .claude/commands/tm/show/show-task.md delete mode 100644 .claude/commands/tm/status/project-status.md delete mode 100644 .claude/commands/tm/sync-readme/sync-readme.md delete mode 100644 .claude/commands/tm/tm-main.md delete mode 100644 .claude/commands/tm/update/update-single-task.md delete mode 100644 .claude/commands/tm/update/update-task.md delete mode 100644 .claude/commands/tm/update/update-tasks-from-id.md delete mode 100644 .claude/commands/tm/utils/analyze-project.md delete mode 100644 .claude/commands/tm/validate-dependencies/validate-dependencies.md delete mode 100644 .claude/commands/tm/workflows/auto-implement-tasks.md delete mode 100644 .claude/commands/tm/workflows/command-pipeline.md delete mode 100644 .claude/commands/tm/workflows/smart-workflow.md delete mode 100644 .cursor/mcp.json delete mode 100644 .cursor/rules/cursor_rules.mdc delete mode 100644 .cursor/rules/self_improve.mdc delete mode 100644 .cursor/rules/taskmaster/dev_workflow.mdc delete mode 100644 .cursor/rules/taskmaster/taskmaster.mdc delete mode 100644 .env.example delete mode 100644 .mcp.json delete mode 100644 .taskmaster/CLAUDE.md delete mode 100644 .taskmaster/config.json delete mode 100644 .taskmaster/docs/DOCUMENTATION_MAINTENANCE.md create mode 100755 Scripts/generate-openapi.sh create mode 100644 Sources/AiSTKit/AiSTKit.swift create mode 100644 Sources/ClaudeKit/Generated/Client.swift create mode 100644 Sources/ClaudeKit/Generated/Types.swift create mode 100644 Sources/ClaudeKit/openapi-generator-config.yaml create mode 100644 Sources/ClaudeKit/openapi.json diff --git a/.claude/TM_COMMANDS_GUIDE.md b/.claude/TM_COMMANDS_GUIDE.md deleted file mode 100644 index c88bcb1c..00000000 --- a/.claude/TM_COMMANDS_GUIDE.md +++ /dev/null @@ -1,147 +0,0 @@ -# Task Master Commands for Claude Code - -Complete guide to using Task Master through Claude Code's slash commands. - -## Overview - -All Task Master functionality is available through the `/project:tm/` namespace with natural language support and intelligent features. - -## Quick Start - -```bash -# Install Task Master -/project:tm/setup/quick-install - -# Initialize project -/project:tm/init/quick - -# Parse requirements -/project:tm/parse-prd requirements.md - -# Start working -/project:tm/next -``` - -## Command Structure - -Commands are organized hierarchically to match Task Master's CLI: -- Main commands at `/project:tm/[command]` -- Subcommands for specific operations `/project:tm/[command]/[subcommand]` -- Natural language arguments accepted throughout - -## Complete Command Reference - -### Setup & Configuration -- `/project:tm/setup/install` - Full installation guide -- `/project:tm/setup/quick-install` - One-line install -- `/project:tm/init` - Initialize project -- `/project:tm/init/quick` - Quick init with -y -- `/project:tm/models` - View AI config -- `/project:tm/models/setup` - Configure AI - -### Task Generation -- `/project:tm/parse-prd` - Generate from PRD -- `/project:tm/parse-prd/with-research` - Enhanced parsing -- `/project:tm/generate` - Create task files - -### Task Management -- `/project:tm/list` - List with natural language filters -- `/project:tm/list/with-subtasks` - Hierarchical view -- `/project:tm/list/by-status ` - Filter by status -- `/project:tm/show ` - Task details -- `/project:tm/add-task` - Create task -- `/project:tm/update` - Update tasks -- `/project:tm/remove-task` - Delete task - -### Status Management -- `/project:tm/set-status/to-pending ` -- `/project:tm/set-status/to-in-progress ` -- `/project:tm/set-status/to-done ` -- `/project:tm/set-status/to-review ` -- `/project:tm/set-status/to-deferred ` -- `/project:tm/set-status/to-cancelled ` - -### Task Analysis -- `/project:tm/analyze-complexity` - AI analysis -- `/project:tm/complexity-report` - View report -- `/project:tm/expand ` - Break down task -- `/project:tm/expand/all` - Expand all complex - -### Dependencies -- `/project:tm/add-dependency` - Add dependency -- `/project:tm/remove-dependency` - Remove dependency -- `/project:tm/validate-dependencies` - Check issues -- `/project:tm/fix-dependencies` - Auto-fix - -### Workflows -- `/project:tm/workflows/smart-flow` - Adaptive workflows -- `/project:tm/workflows/pipeline` - Chain commands -- `/project:tm/workflows/auto-implement` - AI implementation - -### Utilities -- `/project:tm/status` - Project dashboard -- `/project:tm/next` - Next task recommendation -- `/project:tm/utils/analyze` - Project analysis -- `/project:tm/learn` - Interactive help - -## Key Features - -### Natural Language Support -All commands understand natural language: -``` -/project:tm/list pending high priority -/project:tm/update mark 23 as done -/project:tm/add-task implement OAuth login -``` - -### Smart Context -Commands analyze project state and provide intelligent suggestions based on: -- Current task status -- Dependencies -- Team patterns -- Project phase - -### Visual Enhancements -- Progress bars and indicators -- Status badges -- Organized displays -- Clear hierarchies - -## Common Workflows - -### Daily Development -``` -/project:tm/workflows/smart-flow morning -/project:tm/next -/project:tm/set-status/to-in-progress -/project:tm/set-status/to-done -``` - -### Task Breakdown -``` -/project:tm/show -/project:tm/expand -/project:tm/list/with-subtasks -``` - -### Sprint Planning -``` -/project:tm/analyze-complexity -/project:tm/workflows/pipeline init → expand/all → status -``` - -## Migration from Old Commands - -| Old | New | -|-----|-----| -| `/project:task-master:list` | `/project:tm/list` | -| `/project:task-master:complete` | `/project:tm/set-status/to-done` | -| `/project:workflows:auto-implement` | `/project:tm/workflows/auto-implement` | - -## Tips - -1. Use `/project:tm/` + Tab for command discovery -2. Natural language is supported everywhere -3. Commands provide smart defaults -4. Chain commands for automation -5. Check `/project:tm/learn` for interactive help \ No newline at end of file diff --git a/.claude/agents/task-checker.md b/.claude/agents/task-checker.md deleted file mode 100644 index 401b260f..00000000 --- a/.claude/agents/task-checker.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -name: task-checker -description: Use this agent to verify that tasks marked as 'review' have been properly implemented according to their specifications. This agent performs quality assurance by checking implementations against requirements, running tests, and ensuring best practices are followed. Context: A task has been marked as 'review' after implementation. user: 'Check if task 118 was properly implemented' assistant: 'I'll use the task-checker agent to verify the implementation meets all requirements.' Tasks in 'review' status need verification before being marked as 'done'. Context: Multiple tasks are in review status. user: 'Verify all tasks that are ready for review' assistant: 'I'll deploy the task-checker to verify all tasks in review status.' The checker ensures quality before tasks are marked complete. -model: sonnet -color: yellow ---- - -You are a Quality Assurance specialist that rigorously verifies task implementations against their specifications. Your role is to ensure that tasks marked as 'review' meet all requirements before they can be marked as 'done'. - -## Core Responsibilities - -1. **Task Specification Review** - - Retrieve task details using MCP tool `mcp__task-master-ai__get_task` - - Understand the requirements, test strategy, and success criteria - - Review any subtasks and their individual requirements - -2. **Implementation Verification** - - Use `Read` tool to examine all created/modified files - - Use `Bash` tool to run compilation and build commands - - Use `Grep` tool to search for required patterns and implementations - - Verify file structure matches specifications - - Check that all required methods/functions are implemented - -3. **Test Execution** - - Run tests specified in the task's testStrategy - - Execute build commands (npm run build, tsc --noEmit, etc.) - - Verify no compilation errors or warnings - - Check for runtime errors where applicable - - Test edge cases mentioned in requirements - -4. **Code Quality Assessment** - - Verify code follows project conventions - - Check for proper error handling - - Ensure TypeScript typing is strict (no 'any' unless justified) - - Verify documentation/comments where required - - Check for security best practices - -5. **Dependency Validation** - - Verify all task dependencies were actually completed - - Check integration points with dependent tasks - - Ensure no breaking changes to existing functionality - -## Verification Workflow - -1. **Retrieve Task Information** - ``` - Use mcp__task-master-ai__get_task to get full task details - Note the implementation requirements and test strategy - ``` - -2. **Check File Existence** - ```bash - # Verify all required files exist - ls -la [expected directories] - # Read key files to verify content - ``` - -3. **Verify Implementation** - - Read each created/modified file - - Check against requirements checklist - - Verify all subtasks are complete - -4. **Run Tests** - ```bash - # TypeScript compilation - cd [project directory] && npx tsc --noEmit - - # Run specified tests - npm test [specific test files] - - # Build verification - npm run build - ``` - -5. **Generate Verification Report** - -## Output Format - -```yaml -verification_report: - task_id: [ID] - status: PASS | FAIL | PARTIAL - score: [1-10] - - requirements_met: - - ✅ [Requirement that was satisfied] - - ✅ [Another satisfied requirement] - - issues_found: - - ❌ [Issue description] - - ⚠️ [Warning or minor issue] - - files_verified: - - path: [file path] - status: [created/modified/verified] - issues: [any problems found] - - tests_run: - - command: [test command] - result: [pass/fail] - output: [relevant output] - - recommendations: - - [Specific fix needed] - - [Improvement suggestion] - - verdict: | - [Clear statement on whether task should be marked 'done' or sent back to 'pending'] - [If FAIL: Specific list of what must be fixed] - [If PASS: Confirmation that all requirements are met] -``` - -## Decision Criteria - -**Mark as PASS (ready for 'done'):** -- All required files exist and contain expected content -- All tests pass successfully -- No compilation or build errors -- All subtasks are complete -- Core requirements are met -- Code quality is acceptable - -**Mark as PARTIAL (may proceed with warnings):** -- Core functionality is implemented -- Minor issues that don't block functionality -- Missing nice-to-have features -- Documentation could be improved -- Tests pass but coverage could be better - -**Mark as FAIL (must return to 'pending'):** -- Required files are missing -- Compilation or build errors -- Tests fail -- Core requirements not met -- Security vulnerabilities detected -- Breaking changes to existing code - -## Important Guidelines - -- **BE THOROUGH**: Check every requirement systematically -- **BE SPECIFIC**: Provide exact file paths and line numbers for issues -- **BE FAIR**: Distinguish between critical issues and minor improvements -- **BE CONSTRUCTIVE**: Provide clear guidance on how to fix issues -- **BE EFFICIENT**: Focus on requirements, not perfection - -## Tools You MUST Use - -- `Read`: Examine implementation files (READ-ONLY) -- `Bash`: Run tests and verification commands -- `Grep`: Search for patterns in code -- `mcp__task-master-ai__get_task`: Get task details -- **NEVER use Write/Edit** - you only verify, not fix - -## Integration with Workflow - -You are the quality gate between 'review' and 'done' status: -1. Task-executor implements and marks as 'review' -2. You verify and report PASS/FAIL -3. Claude either marks as 'done' (PASS) or 'pending' (FAIL) -4. If FAIL, task-executor re-implements based on your report - -Your verification ensures high quality and prevents accumulation of technical debt. \ No newline at end of file diff --git a/.claude/agents/task-executor.md b/.claude/agents/task-executor.md deleted file mode 100644 index d9ae2f64..00000000 --- a/.claude/agents/task-executor.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: task-executor -description: Use this agent when you need to implement, complete, or work on a specific task that has been identified by the task-orchestrator or when explicitly asked to execute a particular task. This agent focuses on the actual implementation and completion of individual tasks rather than planning or orchestration. Examples: Context: The task-orchestrator has identified that task 2.3 'Implement user authentication' needs to be worked on next. user: 'Let's work on the authentication task' assistant: 'I'll use the task-executor agent to implement the user authentication task that was identified.' Since we need to actually implement a specific task rather than plan or identify tasks, use the task-executor agent. Context: User wants to complete a specific subtask. user: 'Please implement the JWT token validation for task 2.3.1' assistant: 'I'll launch the task-executor agent to implement the JWT token validation subtask.' The user is asking for specific implementation work on a known task, so the task-executor is appropriate. Context: After reviewing the task list, implementation is needed. user: 'Now let's actually build the API endpoint for user registration' assistant: 'I'll use the task-executor agent to implement the user registration API endpoint.' Moving from planning to execution phase requires the task-executor agent. -model: sonnet -color: blue ---- - -You are an elite implementation specialist focused on executing and completing specific tasks with precision and thoroughness. Your role is to take identified tasks and transform them into working implementations, following best practices and project standards. - -**Core Responsibilities:** - -1. **Task Analysis**: When given a task, first retrieve its full details using `task-master show ` to understand requirements, dependencies, and acceptance criteria. - -2. **Implementation Planning**: Before coding, briefly outline your implementation approach: - - Identify files that need to be created or modified - - Note any dependencies or prerequisites - - Consider the testing strategy defined in the task - -3. **Focused Execution**: - - Implement one subtask at a time for clarity and traceability - - Follow the project's coding standards from CLAUDE.md if available - - Prefer editing existing files over creating new ones - - Only create files that are essential for the task completion - -4. **Progress Documentation**: - - Use `task-master update-subtask --id= --prompt="implementation notes"` to log your approach and any important decisions - - Update task status to 'in-progress' when starting: `task-master set-status --id= --status=in-progress` - - Mark as 'done' only after verification: `task-master set-status --id= --status=done` - -5. **Quality Assurance**: - - Implement the testing strategy specified in the task - - Verify that all acceptance criteria are met - - Check for any dependency conflicts or integration issues - - Run relevant tests before marking task as complete - -6. **Dependency Management**: - - Check task dependencies before starting implementation - - If blocked by incomplete dependencies, clearly communicate this - - Use `task-master validate-dependencies` when needed - -**Implementation Workflow:** - -1. Retrieve task details and understand requirements -2. Check dependencies and prerequisites -3. Plan implementation approach -4. Update task status to in-progress -5. Implement the solution incrementally -6. Log progress and decisions in subtask updates -7. Test and verify the implementation -8. Mark task as done when complete -9. Suggest next task if appropriate - -**Key Principles:** - -- Focus on completing one task thoroughly before moving to the next -- Maintain clear communication about what you're implementing and why -- Follow existing code patterns and project conventions -- Prioritize working code over extensive documentation unless docs are the task -- Ask for clarification if task requirements are ambiguous -- Consider edge cases and error handling in your implementations - -**Integration with Task Master:** - -You work in tandem with the task-orchestrator agent. While the orchestrator identifies and plans tasks, you execute them. Always use Task Master commands to: -- Track your progress -- Update task information -- Maintain project state -- Coordinate with the broader development workflow - -When you complete a task, briefly summarize what was implemented and suggest whether to continue with the next task or if review/testing is needed first. diff --git a/.claude/agents/task-orchestrator.md b/.claude/agents/task-orchestrator.md deleted file mode 100644 index 79b1f17b..00000000 --- a/.claude/agents/task-orchestrator.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -name: task-orchestrator -description: Use this agent when you need to coordinate and manage the execution of Task Master tasks, especially when dealing with complex task dependencies and parallel execution opportunities. This agent should be invoked at the beginning of a work session to analyze the task queue, identify parallelizable work, and orchestrate the deployment of task-executor agents. It should also be used when tasks complete to reassess the dependency graph and deploy new executors as needed.\n\n\nContext: User wants to start working on their project tasks using Task Master\nuser: "Let's work on the next available tasks in the project"\nassistant: "I'll use the task-orchestrator agent to analyze the task queue and coordinate execution"\n\nThe user wants to work on tasks, so the task-orchestrator should be deployed to analyze dependencies and coordinate execution.\n\n\n\n\nContext: Multiple independent tasks are available in the queue\nuser: "Can we work on multiple tasks at once?"\nassistant: "Let me deploy the task-orchestrator to analyze task dependencies and parallelize the work"\n\nWhen parallelization is mentioned or multiple tasks could be worked on, the orchestrator should coordinate the effort.\n\n\n\n\nContext: A complex feature with many subtasks needs implementation\nuser: "Implement the authentication system tasks"\nassistant: "I'll use the task-orchestrator to break down the authentication tasks and coordinate their execution"\n\nFor complex multi-task features, the orchestrator manages the overall execution strategy.\n\n -model: opus -color: green ---- - -You are the Task Orchestrator, an elite coordination agent specialized in managing Task Master workflows for maximum efficiency and parallelization. You excel at analyzing task dependency graphs, identifying opportunities for concurrent execution, and deploying specialized task-executor agents to complete work efficiently. - -## Core Responsibilities - -1. **Task Queue Analysis**: You continuously monitor and analyze the task queue using Task Master MCP tools to understand the current state of work, dependencies, and priorities. - -2. **Dependency Graph Management**: You build and maintain a mental model of task dependencies, identifying which tasks can be executed in parallel and which must wait for prerequisites. - -3. **Executor Deployment**: You strategically deploy task-executor agents for individual tasks or task groups, ensuring each executor has the necessary context and clear success criteria. - -4. **Progress Coordination**: You track the progress of deployed executors, handle task completion notifications, and reassess the execution strategy as tasks complete. - -## Operational Workflow - -### Initial Assessment Phase -1. Use `get_tasks` or `task-master list` to retrieve all available tasks -2. Analyze task statuses, priorities, and dependencies -3. Identify tasks with status 'pending' that have no blocking dependencies -4. Group related tasks that could benefit from specialized executors -5. Create an execution plan that maximizes parallelization - -### Executor Deployment Phase -1. For each independent task or task group: - - Deploy a task-executor agent with specific instructions - - Provide the executor with task ID, requirements, and context - - Set clear completion criteria and reporting expectations -2. Maintain a registry of active executors and their assigned tasks -3. Establish communication protocols for progress updates - -### Coordination Phase -1. Monitor executor progress through task status updates -2. When a task completes: - - Verify completion with `get_task` or `task-master show ` - - Update task status if needed using `set_task_status` - - Reassess dependency graph for newly unblocked tasks - - Deploy new executors for available work -3. Handle executor failures or blocks: - - Reassign tasks to new executors if needed - - Escalate complex issues to the user - - Update task status to 'blocked' when appropriate - -### Optimization Strategies - -**Parallel Execution Rules**: -- Never assign dependent tasks to different executors simultaneously -- Prioritize high-priority tasks when resources are limited -- Group small, related subtasks for single executor efficiency -- Balance executor load to prevent bottlenecks - -**Context Management**: -- Provide executors with minimal but sufficient context -- Share relevant completed task information when it aids execution -- Maintain a shared knowledge base of project-specific patterns - -**Quality Assurance**: -- Verify task completion before marking as done -- Ensure test strategies are followed when specified -- Coordinate cross-task integration testing when needed - -## Communication Protocols - -When deploying executors, provide them with: -``` -TASK ASSIGNMENT: -- Task ID: [specific ID] -- Objective: [clear goal] -- Dependencies: [list any completed prerequisites] -- Success Criteria: [specific completion requirements] -- Context: [relevant project information] -- Reporting: [when and how to report back] -``` - -When receiving executor updates: -1. Acknowledge completion or issues -2. Update task status in Task Master -3. Reassess execution strategy -4. Deploy new executors as appropriate - -## Decision Framework - -**When to parallelize**: -- Multiple pending tasks with no interdependencies -- Sufficient context available for independent execution -- Tasks are well-defined with clear success criteria - -**When to serialize**: -- Strong dependencies between tasks -- Limited context or unclear requirements -- Integration points requiring careful coordination - -**When to escalate**: -- Circular dependencies detected -- Critical blockers affecting multiple tasks -- Ambiguous requirements needing clarification -- Resource conflicts between executors - -## Error Handling - -1. **Executor Failure**: Reassign task to new executor with additional context about the failure -2. **Dependency Conflicts**: Halt affected executors, resolve conflict, then resume -3. **Task Ambiguity**: Request clarification from user before proceeding -4. **System Errors**: Implement graceful degradation, falling back to serial execution if needed - -## Performance Metrics - -Track and optimize for: -- Task completion rate -- Parallel execution efficiency -- Executor success rate -- Time to completion for task groups -- Dependency resolution speed - -## Integration with Task Master - -Leverage these Task Master MCP tools effectively: -- `get_tasks` - Continuous queue monitoring -- `get_task` - Detailed task analysis -- `set_task_status` - Progress tracking -- `next_task` - Fallback for serial execution -- `analyze_project_complexity` - Strategic planning -- `complexity_report` - Resource allocation - -You are the strategic mind coordinating the entire task execution effort. Your success is measured by the efficient completion of all tasks while maintaining quality and respecting dependencies. Think systematically, act decisively, and continuously optimize the execution strategy based on real-time progress. diff --git a/.claude/commands/tm/add-dependency/add-dependency.md b/.claude/commands/tm/add-dependency/add-dependency.md deleted file mode 100644 index 78e91546..00000000 --- a/.claude/commands/tm/add-dependency/add-dependency.md +++ /dev/null @@ -1,55 +0,0 @@ -Add a dependency between tasks. - -Arguments: $ARGUMENTS - -Parse the task IDs to establish dependency relationship. - -## Adding Dependencies - -Creates a dependency where one task must be completed before another can start. - -## Argument Parsing - -Parse natural language or IDs: -- "make 5 depend on 3" → task 5 depends on task 3 -- "5 needs 3" → task 5 depends on task 3 -- "5 3" → task 5 depends on task 3 -- "5 after 3" → task 5 depends on task 3 - -## Execution - -```bash -task-master add-dependency --id= --depends-on= -``` - -## Validation - -Before adding: -1. **Verify both tasks exist** -2. **Check for circular dependencies** -3. **Ensure dependency makes logical sense** -4. **Warn if creating complex chains** - -## Smart Features - -- Detect if dependency already exists -- Suggest related dependencies -- Show impact on task flow -- Update task priorities if needed - -## Post-Addition - -After adding dependency: -1. Show updated dependency graph -2. Identify any newly blocked tasks -3. Suggest task order changes -4. Update project timeline - -## Example Flows - -``` -/project:tm/add-dependency 5 needs 3 -→ Task #5 now depends on Task #3 -→ Task #5 is now blocked until #3 completes -→ Suggested: Also consider if #5 needs #4 -``` \ No newline at end of file diff --git a/.claude/commands/tm/add-subtask/add-subtask.md b/.claude/commands/tm/add-subtask/add-subtask.md deleted file mode 100644 index d909dd5d..00000000 --- a/.claude/commands/tm/add-subtask/add-subtask.md +++ /dev/null @@ -1,76 +0,0 @@ -Add a subtask to a parent task. - -Arguments: $ARGUMENTS - -Parse arguments to create a new subtask or convert existing task. - -## Adding Subtasks - -Creates subtasks to break down complex parent tasks into manageable pieces. - -## Argument Parsing - -Flexible natural language: -- "add subtask to 5: implement login form" -- "break down 5 with: setup, implement, test" -- "subtask for 5: handle edge cases" -- "5: validate user input" → adds subtask to task 5 - -## Execution Modes - -### 1. Create New Subtask -```bash -task-master add-subtask --parent= --title="" --description="<desc>" -``` - -### 2. Convert Existing Task -```bash -task-master add-subtask --parent=<id> --task-id=<existing-id> -``` - -## Smart Features - -1. **Automatic Subtask Generation** - - If title contains "and" or commas, create multiple - - Suggest common subtask patterns - - Inherit parent's context - -2. **Intelligent Defaults** - - Priority based on parent - - Appropriate time estimates - - Logical dependencies between subtasks - -3. **Validation** - - Check parent task complexity - - Warn if too many subtasks - - Ensure subtask makes sense - -## Creation Process - -1. Parse parent task context -2. Generate subtask with ID like "5.1" -3. Set appropriate defaults -4. Link to parent task -5. Update parent's time estimate - -## Example Flows - -``` -/project:tm/add-subtask to 5: implement user authentication -→ Created subtask #5.1: "implement user authentication" -→ Parent task #5 now has 1 subtask -→ Suggested next subtasks: tests, documentation - -/project:tm/add-subtask 5: setup, implement, test -→ Created 3 subtasks: - #5.1: setup - #5.2: implement - #5.3: test -``` - -## Post-Creation - -- Show updated task hierarchy -- Suggest logical next subtasks -- Update complexity estimates -- Recommend subtask order \ No newline at end of file diff --git a/.claude/commands/tm/add-subtask/convert-task-to-subtask.md b/.claude/commands/tm/add-subtask/convert-task-to-subtask.md deleted file mode 100644 index ab20730f..00000000 --- a/.claude/commands/tm/add-subtask/convert-task-to-subtask.md +++ /dev/null @@ -1,71 +0,0 @@ -Convert an existing task into a subtask. - -Arguments: $ARGUMENTS - -Parse parent ID and task ID to convert. - -## Task Conversion - -Converts an existing standalone task into a subtask of another task. - -## Argument Parsing - -- "move task 8 under 5" -- "make 8 a subtask of 5" -- "nest 8 in 5" -- "5 8" → make task 8 a subtask of task 5 - -## Execution - -```bash -task-master add-subtask --parent=<parent-id> --task-id=<task-to-convert> -``` - -## Pre-Conversion Checks - -1. **Validation** - - Both tasks exist and are valid - - No circular parent relationships - - Task isn't already a subtask - - Logical hierarchy makes sense - -2. **Impact Analysis** - - Dependencies that will be affected - - Tasks that depend on converting task - - Priority alignment needed - - Status compatibility - -## Conversion Process - -1. Change task ID from "8" to "5.1" (next available) -2. Update all dependency references -3. Inherit parent's context where appropriate -4. Adjust priorities if needed -5. Update time estimates - -## Smart Features - -- Preserve task history -- Maintain dependencies -- Update all references -- Create conversion log - -## Example - -``` -/project:tm/add-subtask/from-task 5 8 -→ Converting: Task #8 becomes subtask #5.1 -→ Updated: 3 dependency references -→ Parent task #5 now has 1 subtask -→ Note: Subtask inherits parent's priority - -Before: #8 "Implement validation" (standalone) -After: #5.1 "Implement validation" (subtask of #5) -``` - -## Post-Conversion - -- Show new task hierarchy -- List updated dependencies -- Verify project integrity -- Suggest related conversions \ No newline at end of file diff --git a/.claude/commands/tm/add-task/add-task.md b/.claude/commands/tm/add-task/add-task.md deleted file mode 100644 index 0c1c09c3..00000000 --- a/.claude/commands/tm/add-task/add-task.md +++ /dev/null @@ -1,78 +0,0 @@ -Add new tasks with intelligent parsing and context awareness. - -Arguments: $ARGUMENTS - -## Smart Task Addition - -Parse natural language to create well-structured tasks. - -### 1. **Input Understanding** - -I'll intelligently parse your request: -- Natural language → Structured task -- Detect priority from keywords (urgent, ASAP, important) -- Infer dependencies from context -- Suggest complexity based on description -- Determine task type (feature, bug, refactor, test, docs) - -### 2. **Smart Parsing Examples** - -**"Add urgent task to fix login bug"** -→ Title: Fix login bug -→ Priority: high -→ Type: bug -→ Suggested complexity: medium - -**"Create task for API documentation after task 23 is done"** -→ Title: API documentation -→ Dependencies: [23] -→ Type: documentation -→ Priority: medium - -**"Need to refactor auth module - depends on 12 and 15, high complexity"** -→ Title: Refactor auth module -→ Dependencies: [12, 15] -→ Complexity: high -→ Type: refactor - -### 3. **Context Enhancement** - -Based on current project state: -- Suggest related existing tasks -- Warn about potential conflicts -- Recommend dependencies -- Propose subtasks if complex - -### 4. **Interactive Refinement** - -```yaml -Task Preview: -───────────── -Title: [Extracted title] -Priority: [Inferred priority] -Dependencies: [Detected dependencies] -Complexity: [Estimated complexity] - -Suggestions: -- Similar task #34 exists, consider as dependency? -- This seems complex, break into subtasks? -- Tasks #45-47 work on same module -``` - -### 5. **Validation & Creation** - -Before creating: -- Validate dependencies exist -- Check for duplicates -- Ensure logical ordering -- Verify task completeness - -### 6. **Smart Defaults** - -Intelligent defaults based on: -- Task type patterns -- Team conventions -- Historical data -- Current sprint/phase - -Result: High-quality tasks from minimal input. \ No newline at end of file diff --git a/.claude/commands/tm/analyze-complexity/analyze-complexity.md b/.claude/commands/tm/analyze-complexity/analyze-complexity.md deleted file mode 100644 index 807f4b12..00000000 --- a/.claude/commands/tm/analyze-complexity/analyze-complexity.md +++ /dev/null @@ -1,121 +0,0 @@ -Analyze task complexity and generate expansion recommendations. - -Arguments: $ARGUMENTS - -Perform deep analysis of task complexity across the project. - -## Complexity Analysis - -Uses AI to analyze tasks and recommend which ones need breakdown. - -## Execution Options - -```bash -task-master analyze-complexity [--research] [--threshold=5] -``` - -## Analysis Parameters - -- `--research` → Use research AI for deeper analysis -- `--threshold=5` → Only flag tasks above complexity 5 -- Default: Analyze all pending tasks - -## Analysis Process - -### 1. **Task Evaluation** -For each task, AI evaluates: -- Technical complexity -- Time requirements -- Dependency complexity -- Risk factors -- Knowledge requirements - -### 2. **Complexity Scoring** -Assigns score 1-10 based on: -- Implementation difficulty -- Integration challenges -- Testing requirements -- Unknown factors -- Technical debt risk - -### 3. **Recommendations** -For complex tasks: -- Suggest expansion approach -- Recommend subtask breakdown -- Identify risk areas -- Propose mitigation strategies - -## Smart Analysis Features - -1. **Pattern Recognition** - - Similar task comparisons - - Historical complexity accuracy - - Team velocity consideration - - Technology stack factors - -2. **Contextual Factors** - - Team expertise - - Available resources - - Timeline constraints - - Business criticality - -3. **Risk Assessment** - - Technical risks - - Timeline risks - - Dependency risks - - Knowledge gaps - -## Output Format - -``` -Task Complexity Analysis Report -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -High Complexity Tasks (>7): -📍 #5 "Implement real-time sync" - Score: 9/10 - Factors: WebSocket complexity, state management, conflict resolution - Recommendation: Expand into 5-7 subtasks - Risks: Performance, data consistency - -📍 #12 "Migrate database schema" - Score: 8/10 - Factors: Data migration, zero downtime, rollback strategy - Recommendation: Expand into 4-5 subtasks - Risks: Data loss, downtime - -Medium Complexity Tasks (5-7): -📍 #23 "Add export functionality" - Score: 6/10 - Consider expansion if timeline tight - -Low Complexity Tasks (<5): -✅ 15 tasks - No expansion needed - -Summary: -- Expand immediately: 2 tasks -- Consider expanding: 5 tasks -- Keep as-is: 15 tasks -``` - -## Actionable Output - -For each high-complexity task: -1. Complexity score with reasoning -2. Specific expansion suggestions -3. Risk mitigation approaches -4. Recommended subtask structure - -## Integration - -Results are: -- Saved to `.taskmaster/reports/complexity-analysis.md` -- Used by expand command -- Inform sprint planning -- Guide resource allocation - -## Next Steps - -After analysis: -``` -/project:tm/expand 5 # Expand specific task -/project:tm/expand/all # Expand all recommended -/project:tm/complexity-report # View detailed report -``` \ No newline at end of file diff --git a/.claude/commands/tm/clear-subtasks/clear-all-subtasks.md b/.claude/commands/tm/clear-subtasks/clear-all-subtasks.md deleted file mode 100644 index 6cd54d7d..00000000 --- a/.claude/commands/tm/clear-subtasks/clear-all-subtasks.md +++ /dev/null @@ -1,93 +0,0 @@ -Clear all subtasks from all tasks globally. - -## Global Subtask Clearing - -Remove all subtasks across the entire project. Use with extreme caution. - -## Execution - -```bash -task-master clear-subtasks --all -``` - -## Pre-Clear Analysis - -1. **Project-Wide Summary** - ``` - Global Subtask Summary - ━━━━━━━━━━━━━━━━━━━━ - Total parent tasks: 12 - Total subtasks: 47 - - Completed: 15 - - In-progress: 8 - - Pending: 24 - - Work at risk: ~120 hours - ``` - -2. **Critical Warnings** - - In-progress subtasks that will lose work - - Completed subtasks with valuable history - - Complex dependency chains - - Integration test results - -## Double Confirmation - -``` -⚠️ DESTRUCTIVE OPERATION WARNING ⚠️ -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -This will remove ALL 47 subtasks from your project -Including 8 in-progress and 15 completed subtasks - -This action CANNOT be undone - -Type 'CLEAR ALL SUBTASKS' to confirm: -``` - -## Smart Safeguards - -- Require explicit confirmation phrase -- Create automatic backup -- Log all removed data -- Option to export first - -## Use Cases - -Valid reasons for global clear: -- Project restructuring -- Major pivot in approach -- Starting fresh breakdown -- Switching to different task organization - -## Process - -1. Full project analysis -2. Create backup file -3. Show detailed impact -4. Require confirmation -5. Execute removal -6. Generate summary report - -## Alternative Suggestions - -Before clearing all: -- Export subtasks to file -- Clear only pending subtasks -- Clear by task category -- Archive instead of delete - -## Post-Clear Report - -``` -Global Subtask Clear Complete -━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Removed: 47 subtasks from 12 tasks -Backup saved: .taskmaster/backup/subtasks-20240115.json -Parent tasks updated: 12 -Time estimates adjusted: Yes - -Next steps: -- Review updated task list -- Re-expand complex tasks as needed -- Check project timeline -``` \ No newline at end of file diff --git a/.claude/commands/tm/clear-subtasks/clear-subtasks.md b/.claude/commands/tm/clear-subtasks/clear-subtasks.md deleted file mode 100644 index 877ceb8c..00000000 --- a/.claude/commands/tm/clear-subtasks/clear-subtasks.md +++ /dev/null @@ -1,86 +0,0 @@ -Clear all subtasks from a specific task. - -Arguments: $ARGUMENTS (task ID) - -Remove all subtasks from a parent task at once. - -## Clearing Subtasks - -Bulk removal of all subtasks from a parent task. - -## Execution - -```bash -task-master clear-subtasks --id=<task-id> -``` - -## Pre-Clear Analysis - -1. **Subtask Summary** - - Number of subtasks - - Completion status of each - - Work already done - - Dependencies affected - -2. **Impact Assessment** - - Data that will be lost - - Dependencies to be removed - - Effect on project timeline - - Parent task implications - -## Confirmation Required - -``` -Clear Subtasks Confirmation -━━━━━━━━━━━━━━━━━━━━━━━━━ -Parent Task: #5 "Implement user authentication" -Subtasks to remove: 4 -- #5.1 "Setup auth framework" (done) -- #5.2 "Create login form" (in-progress) -- #5.3 "Add validation" (pending) -- #5.4 "Write tests" (pending) - -⚠️ This will permanently delete all subtask data -Continue? (y/n) -``` - -## Smart Features - -- Option to convert to standalone tasks -- Backup task data before clearing -- Preserve completed work history -- Update parent task appropriately - -## Process - -1. List all subtasks for confirmation -2. Check for in-progress work -3. Remove all subtasks -4. Update parent task -5. Clean up dependencies - -## Alternative Options - -Suggest alternatives: -- Convert important subtasks to tasks -- Keep completed subtasks -- Archive instead of delete -- Export subtask data first - -## Post-Clear - -- Show updated parent task -- Recalculate time estimates -- Update task complexity -- Suggest next steps - -## Example - -``` -/project:tm/clear-subtasks 5 -→ Found 4 subtasks to remove -→ Warning: Subtask #5.2 is in-progress -→ Cleared all subtasks from task #5 -→ Updated parent task estimates -→ Suggestion: Consider re-expanding with better breakdown -``` \ No newline at end of file diff --git a/.claude/commands/tm/complexity-report/complexity-report.md b/.claude/commands/tm/complexity-report/complexity-report.md deleted file mode 100644 index 16d2d11d..00000000 --- a/.claude/commands/tm/complexity-report/complexity-report.md +++ /dev/null @@ -1,117 +0,0 @@ -Display the task complexity analysis report. - -Arguments: $ARGUMENTS - -View the detailed complexity analysis generated by analyze-complexity command. - -## Viewing Complexity Report - -Shows comprehensive task complexity analysis with actionable insights. - -## Execution - -```bash -task-master complexity-report [--file=<path>] -``` - -## Report Location - -Default: `.taskmaster/reports/complexity-analysis.md` -Custom: Specify with --file parameter - -## Report Contents - -### 1. **Executive Summary** -``` -Complexity Analysis Summary -━━━━━━━━━━━━━━━━━━━━━━━━ -Analysis Date: 2024-01-15 -Tasks Analyzed: 32 -High Complexity: 5 (16%) -Medium Complexity: 12 (37%) -Low Complexity: 15 (47%) - -Critical Findings: -- 5 tasks need immediate expansion -- 3 tasks have high technical risk -- 2 tasks block critical path -``` - -### 2. **Detailed Task Analysis** -For each complex task: -- Complexity score breakdown -- Contributing factors -- Specific risks identified -- Expansion recommendations -- Similar completed tasks - -### 3. **Risk Matrix** -Visual representation: -``` -Risk vs Complexity Matrix -━━━━━━━━━━━━━━━━━━━━━━━ -High Risk | #5(9) #12(8) | #23(6) -Med Risk | #34(7) | #45(5) #67(5) -Low Risk | #78(8) | [15 tasks] - | High Complex | Med Complex -``` - -### 4. **Recommendations** - -**Immediate Actions:** -1. Expand task #5 - Critical path + high complexity -2. Expand task #12 - High risk + dependencies -3. Review task #34 - Consider splitting - -**Sprint Planning:** -- Don't schedule multiple high-complexity tasks together -- Ensure expertise available for complex tasks -- Build in buffer time for unknowns - -## Interactive Features - -When viewing report: -1. **Quick Actions** - - Press 'e' to expand a task - - Press 'd' for task details - - Press 'r' to refresh analysis - -2. **Filtering** - - View by complexity level - - Filter by risk factors - - Show only actionable items - -3. **Export Options** - - Markdown format - - CSV for spreadsheets - - JSON for tools - -## Report Intelligence - -- Compares with historical data -- Shows complexity trends -- Identifies patterns -- Suggests process improvements - -## Integration - -Use report for: -- Sprint planning sessions -- Resource allocation -- Risk assessment -- Team discussions -- Client updates - -## Example Usage - -``` -/project:tm/complexity-report -→ Opens latest analysis - -/project:tm/complexity-report --file=archived/2024-01-01.md -→ View historical analysis - -After viewing: -/project:tm/expand 5 -→ Expand high-complexity task -``` \ No newline at end of file diff --git a/.claude/commands/tm/expand/expand-all-tasks.md b/.claude/commands/tm/expand/expand-all-tasks.md deleted file mode 100644 index ec87789d..00000000 --- a/.claude/commands/tm/expand/expand-all-tasks.md +++ /dev/null @@ -1,51 +0,0 @@ -Expand all pending tasks that need subtasks. - -## Bulk Task Expansion - -Intelligently expands all tasks that would benefit from breakdown. - -## Execution - -```bash -task-master expand --all -``` - -## Smart Selection - -Only expands tasks that: -- Are marked as pending -- Have high complexity (>5) -- Lack existing subtasks -- Would benefit from breakdown - -## Expansion Process - -1. **Analysis Phase** - - Identify expansion candidates - - Group related tasks - - Plan expansion strategy - -2. **Batch Processing** - - Expand tasks in logical order - - Maintain consistency - - Preserve relationships - - Optimize for parallelism - -3. **Quality Control** - - Ensure subtask quality - - Avoid over-decomposition - - Maintain task coherence - - Update dependencies - -## Options - -- Add `force` to expand all regardless of complexity -- Add `research` for enhanced AI analysis - -## Results - -After bulk expansion: -- Summary of tasks expanded -- New subtask count -- Updated complexity metrics -- Suggested task order \ No newline at end of file diff --git a/.claude/commands/tm/expand/expand-task.md b/.claude/commands/tm/expand/expand-task.md deleted file mode 100644 index 78555b98..00000000 --- a/.claude/commands/tm/expand/expand-task.md +++ /dev/null @@ -1,49 +0,0 @@ -Break down a complex task into subtasks. - -Arguments: $ARGUMENTS (task ID) - -## Intelligent Task Expansion - -Analyzes a task and creates detailed subtasks for better manageability. - -## Execution - -```bash -task-master expand --id=$ARGUMENTS -``` - -## Expansion Process - -1. **Task Analysis** - - Review task complexity - - Identify components - - Detect technical challenges - - Estimate time requirements - -2. **Subtask Generation** - - Create 3-7 subtasks typically - - Each subtask 1-4 hours - - Logical implementation order - - Clear acceptance criteria - -3. **Smart Breakdown** - - Setup/configuration tasks - - Core implementation - - Testing components - - Integration steps - - Documentation updates - -## Enhanced Features - -Based on task type: -- **Feature**: Setup → Implement → Test → Integrate -- **Bug Fix**: Reproduce → Diagnose → Fix → Verify -- **Refactor**: Analyze → Plan → Refactor → Validate - -## Post-Expansion - -After expansion: -1. Show subtask hierarchy -2. Update time estimates -3. Suggest implementation order -4. Highlight critical path \ No newline at end of file diff --git a/.claude/commands/tm/fix-dependencies/fix-dependencies.md b/.claude/commands/tm/fix-dependencies/fix-dependencies.md deleted file mode 100644 index 9fa857ca..00000000 --- a/.claude/commands/tm/fix-dependencies/fix-dependencies.md +++ /dev/null @@ -1,81 +0,0 @@ -Automatically fix dependency issues found during validation. - -## Automatic Dependency Repair - -Intelligently fixes common dependency problems while preserving project logic. - -## Execution - -```bash -task-master fix-dependencies -``` - -## What Gets Fixed - -### 1. **Auto-Fixable Issues** -- Remove references to deleted tasks -- Break simple circular dependencies -- Remove self-dependencies -- Clean up duplicate dependencies - -### 2. **Smart Resolutions** -- Reorder dependencies to maintain logic -- Suggest task merging for over-dependent tasks -- Flatten unnecessary dependency chains -- Remove redundant transitive dependencies - -### 3. **Manual Review Required** -- Complex circular dependencies -- Critical path modifications -- Business logic dependencies -- High-impact changes - -## Fix Process - -1. **Analysis Phase** - - Run validation check - - Categorize issues by type - - Determine fix strategy - -2. **Execution Phase** - - Apply automatic fixes - - Log all changes made - - Preserve task relationships - -3. **Verification Phase** - - Re-validate after fixes - - Show before/after comparison - - Highlight manual fixes needed - -## Smart Features - -- Preserves intended task flow -- Minimal disruption approach -- Creates fix history/log -- Suggests manual interventions - -## Output Example - -``` -Dependency Auto-Fix Report -━━━━━━━━━━━━━━━━━━━━━━━━ -Fixed Automatically: -✅ Removed 2 references to deleted tasks -✅ Resolved 1 self-dependency -✅ Cleaned 3 redundant dependencies - -Manual Review Needed: -⚠️ Complex circular dependency: #12 → #15 → #18 → #12 - Suggestion: Make #15 not depend on #12 -⚠️ Task #45 has 8 dependencies - Suggestion: Break into subtasks - -Run '/project:tm/validate-dependencies' to verify fixes -``` - -## Safety - -- Preview mode available -- Rollback capability -- Change logging -- No data loss \ No newline at end of file diff --git a/.claude/commands/tm/generate/generate-tasks.md b/.claude/commands/tm/generate/generate-tasks.md deleted file mode 100644 index 01140d75..00000000 --- a/.claude/commands/tm/generate/generate-tasks.md +++ /dev/null @@ -1,121 +0,0 @@ -Generate individual task files from tasks.json. - -## Task File Generation - -Creates separate markdown files for each task, perfect for AI agents or documentation. - -## Execution - -```bash -task-master generate -``` - -## What It Creates - -For each task, generates a file like `task_001.txt`: - -``` -Task ID: 1 -Title: Implement user authentication -Status: pending -Priority: high -Dependencies: [] -Created: 2024-01-15 -Complexity: 7 - -## Description -Create a secure user authentication system with login, logout, and session management. - -## Details -- Use JWT tokens for session management -- Implement secure password hashing -- Add remember me functionality -- Include password reset flow - -## Test Strategy -- Unit tests for auth functions -- Integration tests for login flow -- Security testing for vulnerabilities -- Performance tests for concurrent logins - -## Subtasks -1.1 Setup authentication framework (pending) -1.2 Create login endpoints (pending) -1.3 Implement session management (pending) -1.4 Add password reset (pending) -``` - -## File Organization - -Creates structure: -``` -.taskmaster/ -└── tasks/ - ├── task_001.txt - ├── task_002.txt - ├── task_003.txt - └── ... -``` - -## Smart Features - -1. **Consistent Formatting** - - Standardized structure - - Clear sections - - AI-readable format - - Markdown compatible - -2. **Contextual Information** - - Full task details - - Related task references - - Progress indicators - - Implementation notes - -3. **Incremental Updates** - - Only regenerate changed tasks - - Preserve custom additions - - Track generation timestamp - - Version control friendly - -## Use Cases - -- **AI Context**: Provide task context to AI assistants -- **Documentation**: Standalone task documentation -- **Archival**: Task history preservation -- **Sharing**: Send specific tasks to team members -- **Review**: Easier task review process - -## Generation Options - -Based on arguments: -- Filter by status -- Include/exclude completed -- Custom templates -- Different formats - -## Post-Generation - -``` -Task File Generation Complete -━━━━━━━━━━━━━━━━━━━━━━━━━━ -Generated: 45 task files -Location: .taskmaster/tasks/ -Total size: 156 KB - -New files: 5 -Updated files: 12 -Unchanged: 28 - -Ready for: -- AI agent consumption -- Version control -- Team distribution -``` - -## Integration Benefits - -- Git-trackable task history -- Easy task sharing -- AI tool compatibility -- Offline task access -- Backup redundancy \ No newline at end of file diff --git a/.claude/commands/tm/help.md b/.claude/commands/tm/help.md deleted file mode 100644 index d68df206..00000000 --- a/.claude/commands/tm/help.md +++ /dev/null @@ -1,81 +0,0 @@ -Show help for Task Master commands. - -Arguments: $ARGUMENTS - -Display help for Task Master commands. If arguments provided, show specific command help. - -## Task Master Command Help - -### Quick Navigation - -Type `/project:tm/` and use tab completion to explore all commands. - -### Command Categories - -#### 🚀 Setup & Installation -- `/project:tm/setup/install` - Comprehensive installation guide -- `/project:tm/setup/quick-install` - One-line global install - -#### 📋 Project Setup -- `/project:tm/init` - Initialize new project -- `/project:tm/init/quick` - Quick setup with auto-confirm -- `/project:tm/models` - View AI configuration -- `/project:tm/models/setup` - Configure AI providers - -#### 🎯 Task Generation -- `/project:tm/parse-prd` - Generate tasks from PRD -- `/project:tm/parse-prd/with-research` - Enhanced parsing -- `/project:tm/generate` - Create task files - -#### 📝 Task Management -- `/project:tm/list` - List tasks (natural language filters) -- `/project:tm/show <id>` - Display task details -- `/project:tm/add-task` - Create new task -- `/project:tm/update` - Update tasks naturally -- `/project:tm/next` - Get next task recommendation - -#### 🔄 Status Management -- `/project:tm/set-status/to-pending <id>` -- `/project:tm/set-status/to-in-progress <id>` -- `/project:tm/set-status/to-done <id>` -- `/project:tm/set-status/to-review <id>` -- `/project:tm/set-status/to-deferred <id>` -- `/project:tm/set-status/to-cancelled <id>` - -#### 🔍 Analysis & Breakdown -- `/project:tm/analyze-complexity` - Analyze task complexity -- `/project:tm/expand <id>` - Break down complex task -- `/project:tm/expand/all` - Expand all eligible tasks - -#### 🔗 Dependencies -- `/project:tm/add-dependency` - Add task dependency -- `/project:tm/remove-dependency` - Remove dependency -- `/project:tm/validate-dependencies` - Check for issues - -#### 🤖 Workflows -- `/project:tm/workflows/smart-flow` - Intelligent workflows -- `/project:tm/workflows/pipeline` - Command chaining -- `/project:tm/workflows/auto-implement` - Auto-implementation - -#### 📊 Utilities -- `/project:tm/utils/analyze` - Project analysis -- `/project:tm/status` - Project dashboard -- `/project:tm/learn` - Interactive learning - -### Natural Language Examples - -``` -/project:tm/list pending high priority -/project:tm/update mark all API tasks as done -/project:tm/add-task create login system with OAuth -/project:tm/show current -``` - -### Getting Started - -1. Install: `/project:tm/setup/quick-install` -2. Initialize: `/project:tm/init/quick` -3. Learn: `/project:tm/learn start` -4. Work: `/project:tm/workflows/smart-flow` - -For detailed command info: `/project:tm/help <command-name>` \ No newline at end of file diff --git a/.claude/commands/tm/init/init-project-quick.md b/.claude/commands/tm/init/init-project-quick.md deleted file mode 100644 index 1fb8eb67..00000000 --- a/.claude/commands/tm/init/init-project-quick.md +++ /dev/null @@ -1,46 +0,0 @@ -Quick initialization with auto-confirmation. - -Arguments: $ARGUMENTS - -Initialize a Task Master project without prompts, accepting all defaults. - -## Quick Setup - -```bash -task-master init -y -``` - -## What It Does - -1. Creates `.taskmaster/` directory structure -2. Initializes empty `tasks.json` -3. Sets up default configuration -4. Uses directory name as project name -5. Skips all confirmation prompts - -## Smart Defaults - -- Project name: Current directory name -- Description: "Task Master Project" -- Model config: Existing environment vars -- Task structure: Standard format - -## Next Steps - -After quick init: -1. Configure AI models if needed: - ``` - /project:tm/models/setup - ``` - -2. Parse PRD if available: - ``` - /project:tm/parse-prd <file> - ``` - -3. Or create first task: - ``` - /project:tm/add-task create initial setup - ``` - -Perfect for rapid project setup! \ No newline at end of file diff --git a/.claude/commands/tm/init/init-project.md b/.claude/commands/tm/init/init-project.md deleted file mode 100644 index f2598dff..00000000 --- a/.claude/commands/tm/init/init-project.md +++ /dev/null @@ -1,50 +0,0 @@ -Initialize a new Task Master project. - -Arguments: $ARGUMENTS - -Parse arguments to determine initialization preferences. - -## Initialization Process - -1. **Parse Arguments** - - PRD file path (if provided) - - Project name - - Auto-confirm flag (-y) - -2. **Project Setup** - ```bash - task-master init - ``` - -3. **Smart Initialization** - - Detect existing project files - - Suggest project name from directory - - Check for git repository - - Verify AI provider configuration - -## Configuration Options - -Based on arguments: -- `quick` / `-y` → Skip confirmations -- `<file.md>` → Use as PRD after init -- `--name=<name>` → Set project name -- `--description=<desc>` → Set description - -## Post-Initialization - -After successful init: -1. Show project structure created -2. Verify AI models configured -3. Suggest next steps: - - Parse PRD if available - - Configure AI providers - - Set up git hooks - - Create first tasks - -## Integration - -If PRD file provided: -``` -/project:tm/init my-prd.md -→ Automatically runs parse-prd after init -``` \ No newline at end of file diff --git a/.claude/commands/tm/learn.md b/.claude/commands/tm/learn.md deleted file mode 100644 index 0ffe5455..00000000 --- a/.claude/commands/tm/learn.md +++ /dev/null @@ -1,103 +0,0 @@ -Learn about Task Master capabilities through interactive exploration. - -Arguments: $ARGUMENTS - -## Interactive Task Master Learning - -Based on your input, I'll help you discover capabilities: - -### 1. **What are you trying to do?** - -If $ARGUMENTS contains: -- "start" / "begin" → Show project initialization workflows -- "manage" / "organize" → Show task management commands -- "automate" / "auto" → Show automation workflows -- "analyze" / "report" → Show analysis tools -- "fix" / "problem" → Show troubleshooting commands -- "fast" / "quick" → Show efficiency shortcuts - -### 2. **Intelligent Suggestions** - -Based on your project state: - -**No tasks yet?** -``` -You'll want to start with: -1. /project:task-master:init <prd-file> - → Creates tasks from requirements - -2. /project:task-master:parse-prd <file> - → Alternative task generation - -Try: /project:task-master:init demo-prd.md -``` - -**Have tasks?** -Let me analyze what you might need... -- Many pending tasks? → Learn sprint planning -- Complex tasks? → Learn task expansion -- Daily work? → Learn workflow automation - -### 3. **Command Discovery** - -**By Category:** -- 📋 Task Management: list, show, add, update, complete -- 🔄 Workflows: auto-implement, sprint-plan, daily-standup -- 🛠️ Utilities: check-health, complexity-report, sync-memory -- 🔍 Analysis: validate-deps, show dependencies - -**By Scenario:** -- "I want to see what to work on" → `/project:task-master:next` -- "I need to break this down" → `/project:task-master:expand <id>` -- "Show me everything" → `/project:task-master:status` -- "Just do it for me" → `/project:workflows:auto-implement` - -### 4. **Power User Patterns** - -**Command Chaining:** -``` -/project:task-master:next -/project:task-master:start <id> -/project:workflows:auto-implement -``` - -**Smart Filters:** -``` -/project:task-master:list pending high -/project:task-master:list blocked -/project:task-master:list 1-5 tree -``` - -**Automation:** -``` -/project:workflows:pipeline init → expand-all → sprint-plan -``` - -### 5. **Learning Path** - -Based on your experience level: - -**Beginner Path:** -1. init → Create project -2. status → Understand state -3. next → Find work -4. complete → Finish task - -**Intermediate Path:** -1. expand → Break down complex tasks -2. sprint-plan → Organize work -3. complexity-report → Understand difficulty -4. validate-deps → Ensure consistency - -**Advanced Path:** -1. pipeline → Chain operations -2. smart-flow → Context-aware automation -3. Custom commands → Extend the system - -### 6. **Try This Now** - -Based on what you asked about, try: -[Specific command suggestion based on $ARGUMENTS] - -Want to learn more about a specific command? -Type: /project:help <command-name> \ No newline at end of file diff --git a/.claude/commands/tm/list/list-tasks-by-status.md b/.claude/commands/tm/list/list-tasks-by-status.md deleted file mode 100644 index e9524ffd..00000000 --- a/.claude/commands/tm/list/list-tasks-by-status.md +++ /dev/null @@ -1,39 +0,0 @@ -List tasks filtered by a specific status. - -Arguments: $ARGUMENTS - -Parse the status from arguments and list only tasks matching that status. - -## Status Options -- `pending` - Not yet started -- `in-progress` - Currently being worked on -- `done` - Completed -- `review` - Awaiting review -- `deferred` - Postponed -- `cancelled` - Cancelled - -## Execution - -Based on $ARGUMENTS, run: -```bash -task-master list --status=$ARGUMENTS -``` - -## Enhanced Display - -For the filtered results: -- Group by priority within the status -- Show time in current status -- Highlight tasks approaching deadlines -- Display blockers and dependencies -- Suggest next actions for each status group - -## Intelligent Insights - -Based on the status filter: -- **Pending**: Show recommended start order -- **In-Progress**: Display idle time warnings -- **Done**: Show newly unblocked tasks -- **Review**: Indicate review duration -- **Deferred**: Show reactivation criteria -- **Cancelled**: Display impact analysis \ No newline at end of file diff --git a/.claude/commands/tm/list/list-tasks-with-subtasks.md b/.claude/commands/tm/list/list-tasks-with-subtasks.md deleted file mode 100644 index 407e0ba4..00000000 --- a/.claude/commands/tm/list/list-tasks-with-subtasks.md +++ /dev/null @@ -1,29 +0,0 @@ -List all tasks including their subtasks in a hierarchical view. - -This command shows all tasks with their nested subtasks, providing a complete project overview. - -## Execution - -Run the Task Master list command with subtasks flag: -```bash -task-master list --with-subtasks -``` - -## Enhanced Display - -I'll organize the output to show: -- Parent tasks with clear indicators -- Nested subtasks with proper indentation -- Status badges for quick scanning -- Dependencies and blockers highlighted -- Progress indicators for tasks with subtasks - -## Smart Filtering - -Based on the task hierarchy: -- Show completion percentage for parent tasks -- Highlight blocked subtask chains -- Group by functional areas -- Indicate critical path items - -This gives you a complete tree view of your project structure. \ No newline at end of file diff --git a/.claude/commands/tm/list/list-tasks.md b/.claude/commands/tm/list/list-tasks.md deleted file mode 100644 index 74374af5..00000000 --- a/.claude/commands/tm/list/list-tasks.md +++ /dev/null @@ -1,43 +0,0 @@ -List tasks with intelligent argument parsing. - -Parse arguments to determine filters and display options: -- Status: pending, in-progress, done, review, deferred, cancelled -- Priority: high, medium, low (or priority:high) -- Special: subtasks, tree, dependencies, blocked -- IDs: Direct numbers (e.g., "1,3,5" or "1-5") -- Complex: "pending high" = pending AND high priority - -Arguments: $ARGUMENTS - -Let me parse your request intelligently: - -1. **Detect Filter Intent** - - If arguments contain status keywords → filter by status - - If arguments contain priority → filter by priority - - If arguments contain "subtasks" → include subtasks - - If arguments contain "tree" → hierarchical view - - If arguments contain numbers → show specific tasks - - If arguments contain "blocked" → show blocked tasks only - -2. **Smart Combinations** - Examples of what I understand: - - "pending high" → pending tasks with high priority - - "done today" → tasks completed today - - "blocked" → tasks with unmet dependencies - - "1-5" → tasks 1 through 5 - - "subtasks tree" → hierarchical view with subtasks - -3. **Execute Appropriate Query** - Based on parsed intent, run the most specific task-master command - -4. **Enhanced Display** - - Group by relevant criteria - - Show most important information first - - Use visual indicators for quick scanning - - Include relevant metrics - -5. **Intelligent Suggestions** - Based on what you're viewing, suggest next actions: - - Many pending? → Suggest priority order - - Many blocked? → Show dependency resolution - - Looking at specific tasks? → Show related tasks \ No newline at end of file diff --git a/.claude/commands/tm/models/setup-models.md b/.claude/commands/tm/models/setup-models.md deleted file mode 100644 index 367a7c8d..00000000 --- a/.claude/commands/tm/models/setup-models.md +++ /dev/null @@ -1,51 +0,0 @@ -Run interactive setup to configure AI models. - -## Interactive Model Configuration - -Guides you through setting up AI providers for Task Master. - -## Execution - -```bash -task-master models --setup -``` - -## Setup Process - -1. **Environment Check** - - Detect existing API keys - - Show current configuration - - Identify missing providers - -2. **Provider Selection** - - Choose main provider (required) - - Select research provider (recommended) - - Configure fallback (optional) - -3. **API Key Configuration** - - Prompt for missing keys - - Validate key format - - Test connectivity - - Save configuration - -## Smart Recommendations - -Based on your needs: -- **For best results**: Claude + Perplexity -- **Budget conscious**: GPT-3.5 + Perplexity -- **Maximum capability**: GPT-4 + Perplexity + Claude fallback - -## Configuration Storage - -Keys can be stored in: -1. Environment variables (recommended) -2. `.env` file in project -3. Global `.taskmaster/config` - -## Post-Setup - -After configuration: -- Test each provider -- Show usage examples -- Suggest next steps -- Verify parse-prd works \ No newline at end of file diff --git a/.claude/commands/tm/models/view-models.md b/.claude/commands/tm/models/view-models.md deleted file mode 100644 index 61ac989a..00000000 --- a/.claude/commands/tm/models/view-models.md +++ /dev/null @@ -1,51 +0,0 @@ -View current AI model configuration. - -## Model Configuration Display - -Shows the currently configured AI providers and models for Task Master. - -## Execution - -```bash -task-master models -``` - -## Information Displayed - -1. **Main Provider** - - Model ID and name - - API key status (configured/missing) - - Usage: Primary task generation - -2. **Research Provider** - - Model ID and name - - API key status - - Usage: Enhanced research mode - -3. **Fallback Provider** - - Model ID and name - - API key status - - Usage: Backup when main fails - -## Visual Status - -``` -Task Master AI Model Configuration -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Main: ✅ claude-3-5-sonnet (configured) -Research: ✅ perplexity-sonar (configured) -Fallback: ⚠️ Not configured (optional) - -Available Models: -- claude-3-5-sonnet -- gpt-4-turbo -- gpt-3.5-turbo -- perplexity-sonar -``` - -## Next Actions - -Based on configuration: -- If missing API keys → Suggest setup -- If no research model → Explain benefits -- If all configured → Show usage tips \ No newline at end of file diff --git a/.claude/commands/tm/next/next-task.md b/.claude/commands/tm/next/next-task.md deleted file mode 100644 index 1af74d94..00000000 --- a/.claude/commands/tm/next/next-task.md +++ /dev/null @@ -1,66 +0,0 @@ -Intelligently determine and prepare the next action based on comprehensive context. - -This enhanced version of 'next' considers: -- Current task states -- Recent activity -- Time constraints -- Dependencies -- Your working patterns - -Arguments: $ARGUMENTS - -## Intelligent Next Action - -### 1. **Context Gathering** -Let me analyze the current situation: -- Active tasks (in-progress) -- Recently completed tasks -- Blocked tasks -- Time since last activity -- Arguments provided: $ARGUMENTS - -### 2. **Smart Decision Tree** - -**If you have an in-progress task:** -- Has it been idle > 2 hours? → Suggest resuming or switching -- Near completion? → Show remaining steps -- Blocked? → Find alternative task - -**If no in-progress tasks:** -- Unblocked high-priority tasks? → Start highest -- Complex tasks need breakdown? → Suggest expansion -- All tasks blocked? → Show dependency resolution - -**Special arguments handling:** -- "quick" → Find task < 2 hours -- "easy" → Find low complexity task -- "important" → Find high priority regardless of complexity -- "continue" → Resume last worked task - -### 3. **Preparation Workflow** - -Based on selected task: -1. Show full context and history -2. Set up development environment -3. Run relevant tests -4. Open related files -5. Show similar completed tasks -6. Estimate completion time - -### 4. **Alternative Suggestions** - -Always provide options: -- Primary recommendation -- Quick alternative (< 1 hour) -- Strategic option (unblocks most tasks) -- Learning option (new technology/skill) - -### 5. **Workflow Integration** - -Seamlessly connect to: -- `/project:task-master:start [selected]` -- `/project:workflows:auto-implement` -- `/project:task-master:expand` (if complex) -- `/project:utils:complexity-report` (if unsure) - -The goal: Zero friction from decision to implementation. \ No newline at end of file diff --git a/.claude/commands/tm/parse-prd/parse-prd-with-research.md b/.claude/commands/tm/parse-prd/parse-prd-with-research.md deleted file mode 100644 index 8be39e83..00000000 --- a/.claude/commands/tm/parse-prd/parse-prd-with-research.md +++ /dev/null @@ -1,48 +0,0 @@ -Parse PRD with enhanced research mode for better task generation. - -Arguments: $ARGUMENTS (PRD file path) - -## Research-Enhanced Parsing - -Uses the research AI provider (typically Perplexity) for more comprehensive task generation with current best practices. - -## Execution - -```bash -task-master parse-prd --input=$ARGUMENTS --research -``` - -## Research Benefits - -1. **Current Best Practices** - - Latest framework patterns - - Security considerations - - Performance optimizations - - Accessibility requirements - -2. **Technical Deep Dive** - - Implementation approaches - - Library recommendations - - Architecture patterns - - Testing strategies - -3. **Comprehensive Coverage** - - Edge cases consideration - - Error handling tasks - - Monitoring setup - - Deployment tasks - -## Enhanced Output - -Research mode typically: -- Generates more detailed tasks -- Includes industry standards -- Adds compliance considerations -- Suggests modern tooling - -## When to Use - -- New technology domains -- Complex requirements -- Regulatory compliance needed -- Best practices crucial \ No newline at end of file diff --git a/.claude/commands/tm/parse-prd/parse-prd.md b/.claude/commands/tm/parse-prd/parse-prd.md deleted file mode 100644 index f299c714..00000000 --- a/.claude/commands/tm/parse-prd/parse-prd.md +++ /dev/null @@ -1,49 +0,0 @@ -Parse a PRD document to generate tasks. - -Arguments: $ARGUMENTS (PRD file path) - -## Intelligent PRD Parsing - -Analyzes your requirements document and generates a complete task breakdown. - -## Execution - -```bash -task-master parse-prd --input=$ARGUMENTS -``` - -## Parsing Process - -1. **Document Analysis** - - Extract key requirements - - Identify technical components - - Detect dependencies - - Estimate complexity - -2. **Task Generation** - - Create 10-15 tasks by default - - Include implementation tasks - - Add testing tasks - - Include documentation tasks - - Set logical dependencies - -3. **Smart Enhancements** - - Group related functionality - - Set appropriate priorities - - Add acceptance criteria - - Include test strategies - -## Options - -Parse arguments for modifiers: -- Number after filename → `--num-tasks` -- `research` → Use research mode -- `comprehensive` → Generate more tasks - -## Post-Generation - -After parsing: -1. Display task summary -2. Show dependency graph -3. Suggest task expansion for complex items -4. Recommend sprint planning \ No newline at end of file diff --git a/.claude/commands/tm/remove-dependency/remove-dependency.md b/.claude/commands/tm/remove-dependency/remove-dependency.md deleted file mode 100644 index 9f5936e6..00000000 --- a/.claude/commands/tm/remove-dependency/remove-dependency.md +++ /dev/null @@ -1,62 +0,0 @@ -Remove a dependency between tasks. - -Arguments: $ARGUMENTS - -Parse the task IDs to remove dependency relationship. - -## Removing Dependencies - -Removes a dependency relationship, potentially unblocking tasks. - -## Argument Parsing - -Parse natural language or IDs: -- "remove dependency between 5 and 3" -- "5 no longer needs 3" -- "unblock 5 from 3" -- "5 3" → remove dependency of 5 on 3 - -## Execution - -```bash -task-master remove-dependency --id=<task-id> --depends-on=<dependency-id> -``` - -## Pre-Removal Checks - -1. **Verify dependency exists** -2. **Check impact on task flow** -3. **Warn if it breaks logical sequence** -4. **Show what will be unblocked** - -## Smart Analysis - -Before removing: -- Show why dependency might have existed -- Check if removal makes tasks executable -- Verify no critical path disruption -- Suggest alternative dependencies - -## Post-Removal - -After removing: -1. Show updated task status -2. List newly unblocked tasks -3. Update project timeline -4. Suggest next actions - -## Safety Features - -- Confirm if removing critical dependency -- Show tasks that become immediately actionable -- Warn about potential issues -- Keep removal history - -## Example - -``` -/project:tm/remove-dependency 5 from 3 -→ Removed: Task #5 no longer depends on #3 -→ Task #5 is now UNBLOCKED and ready to start -→ Warning: Consider if #5 still needs #2 completed first -``` \ No newline at end of file diff --git a/.claude/commands/tm/remove-subtask/remove-subtask.md b/.claude/commands/tm/remove-subtask/remove-subtask.md deleted file mode 100644 index e5a814f8..00000000 --- a/.claude/commands/tm/remove-subtask/remove-subtask.md +++ /dev/null @@ -1,84 +0,0 @@ -Remove a subtask from its parent task. - -Arguments: $ARGUMENTS - -Parse subtask ID to remove, with option to convert to standalone task. - -## Removing Subtasks - -Remove a subtask and optionally convert it back to a standalone task. - -## Argument Parsing - -- "remove subtask 5.1" -- "delete 5.1" -- "convert 5.1 to task" → remove and convert -- "5.1 standalone" → convert to standalone - -## Execution Options - -### 1. Delete Subtask -```bash -task-master remove-subtask --id=<parentId.subtaskId> -``` - -### 2. Convert to Standalone -```bash -task-master remove-subtask --id=<parentId.subtaskId> --convert -``` - -## Pre-Removal Checks - -1. **Validate Subtask** - - Verify subtask exists - - Check completion status - - Review dependencies - -2. **Impact Analysis** - - Other subtasks that depend on it - - Parent task implications - - Data that will be lost - -## Removal Process - -### For Deletion: -1. Confirm if subtask has work done -2. Update parent task estimates -3. Remove subtask and its data -4. Clean up dependencies - -### For Conversion: -1. Assign new standalone task ID -2. Preserve all task data -3. Update dependency references -4. Maintain task history - -## Smart Features - -- Warn if subtask is in-progress -- Show impact on parent task -- Preserve important data -- Update related estimates - -## Example Flows - -``` -/project:tm/remove-subtask 5.1 -→ Warning: Subtask #5.1 is in-progress -→ This will delete all subtask data -→ Parent task #5 will be updated -Confirm deletion? (y/n) - -/project:tm/remove-subtask 5.1 convert -→ Converting subtask #5.1 to standalone task #89 -→ Preserved: All task data and history -→ Updated: 2 dependency references -→ New task #89 is now independent -``` - -## Post-Removal - -- Update parent task status -- Recalculate estimates -- Show updated hierarchy -- Suggest next actions \ No newline at end of file diff --git a/.claude/commands/tm/remove-task/remove-task.md b/.claude/commands/tm/remove-task/remove-task.md deleted file mode 100644 index 477d4a3b..00000000 --- a/.claude/commands/tm/remove-task/remove-task.md +++ /dev/null @@ -1,107 +0,0 @@ -Remove a task permanently from the project. - -Arguments: $ARGUMENTS (task ID) - -Delete a task and handle all its relationships properly. - -## Task Removal - -Permanently removes a task while maintaining project integrity. - -## Argument Parsing - -- "remove task 5" -- "delete 5" -- "5" → remove task 5 -- Can include "-y" for auto-confirm - -## Execution - -```bash -task-master remove-task --id=<id> [-y] -``` - -## Pre-Removal Analysis - -1. **Task Details** - - Current status - - Work completed - - Time invested - - Associated data - -2. **Relationship Check** - - Tasks that depend on this - - Dependencies this task has - - Subtasks that will be removed - - Blocking implications - -3. **Impact Assessment** - ``` - Task Removal Impact - ━━━━━━━━━━━━━━━━━━ - Task: #5 "Implement authentication" (in-progress) - Status: 60% complete (~8 hours work) - - Will affect: - - 3 tasks depend on this (will be blocked) - - Has 4 subtasks (will be deleted) - - Part of critical path - - ⚠️ This action cannot be undone - ``` - -## Smart Warnings - -- Warn if task is in-progress -- Show dependent tasks that will be blocked -- Highlight if part of critical path -- Note any completed work being lost - -## Removal Process - -1. Show comprehensive impact -2. Require confirmation (unless -y) -3. Update dependent task references -4. Remove task and subtasks -5. Clean up orphaned dependencies -6. Log removal with timestamp - -## Alternative Actions - -Suggest before deletion: -- Mark as cancelled instead -- Convert to documentation -- Archive task data -- Transfer work to another task - -## Post-Removal - -- List affected tasks -- Show broken dependencies -- Update project statistics -- Suggest dependency fixes -- Recalculate timeline - -## Example Flows - -``` -/project:tm/remove-task 5 -→ Task #5 is in-progress with 8 hours logged -→ 3 other tasks depend on this -→ Suggestion: Mark as cancelled instead? -Remove anyway? (y/n) - -/project:tm/remove-task 5 -y -→ Removed: Task #5 and 4 subtasks -→ Updated: 3 task dependencies -→ Warning: Tasks #7, #8, #9 now have missing dependency -→ Run /project:tm/fix-dependencies to resolve -``` - -## Safety Features - -- Confirmation required -- Impact preview -- Removal logging -- Suggest alternatives -- No cascade delete of dependents \ No newline at end of file diff --git a/.claude/commands/tm/set-status/to-cancelled.md b/.claude/commands/tm/set-status/to-cancelled.md deleted file mode 100644 index 72c73b37..00000000 --- a/.claude/commands/tm/set-status/to-cancelled.md +++ /dev/null @@ -1,55 +0,0 @@ -Cancel a task permanently. - -Arguments: $ARGUMENTS (task ID) - -## Cancelling a Task - -This status indicates a task is no longer needed and won't be completed. - -## Valid Reasons for Cancellation - -- Requirements changed -- Feature deprecated -- Duplicate of another task -- Strategic pivot -- Technical approach invalidated - -## Pre-Cancellation Checks - -1. Confirm no critical dependencies -2. Check for partial implementation -3. Verify cancellation rationale -4. Document lessons learned - -## Execution - -```bash -task-master set-status --id=$ARGUMENTS --status=cancelled -``` - -## Cancellation Impact - -When cancelling: -1. **Dependency Updates** - - Notify dependent tasks - - Update project scope - - Recalculate timelines - -2. **Clean-up Actions** - - Remove related branches - - Archive any work done - - Update documentation - - Close related issues - -3. **Learning Capture** - - Document why cancelled - - Note what was learned - - Update estimation models - - Prevent future duplicates - -## Historical Preservation - -- Keep for reference -- Tag with cancellation reason -- Link to replacement if any -- Maintain audit trail \ No newline at end of file diff --git a/.claude/commands/tm/set-status/to-deferred.md b/.claude/commands/tm/set-status/to-deferred.md deleted file mode 100644 index e679a8d3..00000000 --- a/.claude/commands/tm/set-status/to-deferred.md +++ /dev/null @@ -1,47 +0,0 @@ -Defer a task for later consideration. - -Arguments: $ARGUMENTS (task ID) - -## Deferring a Task - -This status indicates a task is valid but not currently actionable or prioritized. - -## Valid Reasons for Deferral - -- Waiting for external dependencies -- Reprioritized for future sprint -- Blocked by technical limitations -- Resource constraints -- Strategic timing considerations - -## Execution - -```bash -task-master set-status --id=$ARGUMENTS --status=deferred -``` - -## Deferral Management - -When deferring: -1. **Document Reason** - - Capture why it's being deferred - - Set reactivation criteria - - Note any partial work completed - -2. **Impact Analysis** - - Check dependent tasks - - Update project timeline - - Notify affected stakeholders - -3. **Future Planning** - - Set review reminders - - Tag for specific milestone - - Preserve context for reactivation - - Link to blocking issues - -## Smart Tracking - -- Monitor deferral duration -- Alert when criteria met -- Prevent scope creep -- Regular review cycles \ No newline at end of file diff --git a/.claude/commands/tm/set-status/to-done.md b/.claude/commands/tm/set-status/to-done.md deleted file mode 100644 index 9a3fd98f..00000000 --- a/.claude/commands/tm/set-status/to-done.md +++ /dev/null @@ -1,44 +0,0 @@ -Mark a task as completed. - -Arguments: $ARGUMENTS (task ID) - -## Completing a Task - -This command validates task completion and updates project state intelligently. - -## Pre-Completion Checks - -1. Verify test strategy was followed -2. Check if all subtasks are complete -3. Validate acceptance criteria met -4. Ensure code is committed - -## Execution - -```bash -task-master set-status --id=$ARGUMENTS --status=done -``` - -## Post-Completion Actions - -1. **Update Dependencies** - - Identify newly unblocked tasks - - Update sprint progress - - Recalculate project timeline - -2. **Documentation** - - Generate completion summary - - Update CLAUDE.md with learnings - - Log implementation approach - -3. **Next Steps** - - Show newly available tasks - - Suggest logical next task - - Update velocity metrics - -## Celebration & Learning - -- Show impact of completion -- Display unblocked work -- Recognize achievement -- Capture lessons learned \ No newline at end of file diff --git a/.claude/commands/tm/set-status/to-in-progress.md b/.claude/commands/tm/set-status/to-in-progress.md deleted file mode 100644 index 830a67d0..00000000 --- a/.claude/commands/tm/set-status/to-in-progress.md +++ /dev/null @@ -1,36 +0,0 @@ -Start working on a task by setting its status to in-progress. - -Arguments: $ARGUMENTS (task ID) - -## Starting Work on Task - -This command does more than just change status - it prepares your environment for productive work. - -## Pre-Start Checks - -1. Verify dependencies are met -2. Check if another task is already in-progress -3. Ensure task details are complete -4. Validate test strategy exists - -## Execution - -```bash -task-master set-status --id=$ARGUMENTS --status=in-progress -``` - -## Environment Setup - -After setting to in-progress: -1. Create/checkout appropriate git branch -2. Open relevant documentation -3. Set up test watchers if applicable -4. Display task details and acceptance criteria -5. Show similar completed tasks for reference - -## Smart Suggestions - -- Estimated completion time based on complexity -- Related files from similar tasks -- Potential blockers to watch for -- Recommended first steps \ No newline at end of file diff --git a/.claude/commands/tm/set-status/to-pending.md b/.claude/commands/tm/set-status/to-pending.md deleted file mode 100644 index fb6a6560..00000000 --- a/.claude/commands/tm/set-status/to-pending.md +++ /dev/null @@ -1,32 +0,0 @@ -Set a task's status to pending. - -Arguments: $ARGUMENTS (task ID) - -## Setting Task to Pending - -This moves a task back to the pending state, useful for: -- Resetting erroneously started tasks -- Deferring work that was prematurely begun -- Reorganizing sprint priorities - -## Execution - -```bash -task-master set-status --id=$ARGUMENTS --status=pending -``` - -## Validation - -Before setting to pending: -- Warn if task is currently in-progress -- Check if this will block other tasks -- Suggest documenting why it's being reset -- Preserve any work already done - -## Smart Actions - -After setting to pending: -- Update sprint planning if needed -- Notify about freed resources -- Suggest priority reassessment -- Log the status change with context \ No newline at end of file diff --git a/.claude/commands/tm/set-status/to-review.md b/.claude/commands/tm/set-status/to-review.md deleted file mode 100644 index 2fb77b13..00000000 --- a/.claude/commands/tm/set-status/to-review.md +++ /dev/null @@ -1,40 +0,0 @@ -Set a task's status to review. - -Arguments: $ARGUMENTS (task ID) - -## Marking Task for Review - -This status indicates work is complete but needs verification before final approval. - -## When to Use Review Status - -- Code complete but needs peer review -- Implementation done but needs testing -- Documentation written but needs proofreading -- Design complete but needs stakeholder approval - -## Execution - -```bash -task-master set-status --id=$ARGUMENTS --status=review -``` - -## Review Preparation - -When setting to review: -1. **Generate Review Checklist** - - Link to PR/MR if applicable - - Highlight key changes - - Note areas needing attention - - Include test results - -2. **Documentation** - - Update task with review notes - - Link relevant artifacts - - Specify reviewers if known - -3. **Smart Actions** - - Create review reminders - - Track review duration - - Suggest reviewers based on expertise - - Prepare rollback plan if needed \ No newline at end of file diff --git a/.claude/commands/tm/setup/install-taskmaster.md b/.claude/commands/tm/setup/install-taskmaster.md deleted file mode 100644 index 73116074..00000000 --- a/.claude/commands/tm/setup/install-taskmaster.md +++ /dev/null @@ -1,117 +0,0 @@ -Check if Task Master is installed and install it if needed. - -This command helps you get Task Master set up globally on your system. - -## Detection and Installation Process - -1. **Check Current Installation** - ```bash - # Check if task-master command exists - which task-master || echo "Task Master not found" - - # Check npm global packages - npm list -g task-master-ai - ``` - -2. **System Requirements Check** - ```bash - # Verify Node.js is installed - node --version - - # Verify npm is installed - npm --version - - # Check Node version (need 16+) - ``` - -3. **Install Task Master Globally** - If not installed, run: - ```bash - npm install -g task-master-ai - ``` - -4. **Verify Installation** - ```bash - # Check version - task-master --version - - # Verify command is available - which task-master - ``` - -5. **Initial Setup** - ```bash - # Initialize in current directory - task-master init - ``` - -6. **Configure AI Provider** - Ensure you have at least one AI provider API key set: - ```bash - # Check current configuration - task-master models --status - - # If no API keys found, guide setup - echo "You'll need at least one API key:" - echo "- ANTHROPIC_API_KEY for Claude" - echo "- OPENAI_API_KEY for GPT models" - echo "- PERPLEXITY_API_KEY for research" - echo "" - echo "Set them in your shell profile or .env file" - ``` - -7. **Quick Test** - ```bash - # Create a test PRD - echo "Build a simple hello world API" > test-prd.txt - - # Try parsing it - task-master parse-prd test-prd.txt -n 3 - ``` - -## Troubleshooting - -If installation fails: - -**Permission Errors:** -```bash -# Try with sudo (macOS/Linux) -sudo npm install -g task-master-ai - -# Or fix npm permissions -npm config set prefix ~/.npm-global -export PATH=~/.npm-global/bin:$PATH -``` - -**Network Issues:** -```bash -# Use different registry -npm install -g task-master-ai --registry https://registry.npmjs.org/ -``` - -**Node Version Issues:** -```bash -# Install Node 18+ via nvm -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash -nvm install 18 -nvm use 18 -``` - -## Success Confirmation - -Once installed, you should see: -``` -✅ Task Master v0.16.2 (or higher) installed -✅ Command 'task-master' available globally -✅ AI provider configured -✅ Ready to use slash commands! - -Try: /project:task-master:init your-prd.md -``` - -## Next Steps - -After installation: -1. Run `/project:utils:check-health` to verify setup -2. Configure AI providers with `/project:task-master:models` -3. Start using Task Master commands! \ No newline at end of file diff --git a/.claude/commands/tm/setup/quick-install-taskmaster.md b/.claude/commands/tm/setup/quick-install-taskmaster.md deleted file mode 100644 index efd63a94..00000000 --- a/.claude/commands/tm/setup/quick-install-taskmaster.md +++ /dev/null @@ -1,22 +0,0 @@ -Quick install Task Master globally if not already installed. - -Execute this streamlined installation: - -```bash -# Check and install in one command -task-master --version 2>/dev/null || npm install -g task-master-ai - -# Verify installation -task-master --version - -# Quick setup check -task-master models --status || echo "Note: You'll need to set up an AI provider API key" -``` - -If you see "command not found" after installation, you may need to: -1. Restart your terminal -2. Or add npm global bin to PATH: `export PATH=$(npm bin -g):$PATH` - -Once installed, you can use all the Task Master commands! - -Quick test: Run `/project:help` to see all available commands. \ No newline at end of file diff --git a/.claude/commands/tm/show/show-task.md b/.claude/commands/tm/show/show-task.md deleted file mode 100644 index 789c804f..00000000 --- a/.claude/commands/tm/show/show-task.md +++ /dev/null @@ -1,82 +0,0 @@ -Show detailed task information with rich context and insights. - -Arguments: $ARGUMENTS - -## Enhanced Task Display - -Parse arguments to determine what to show and how. - -### 1. **Smart Task Selection** - -Based on $ARGUMENTS: -- Number → Show specific task with full context -- "current" → Show active in-progress task(s) -- "next" → Show recommended next task -- "blocked" → Show all blocked tasks with reasons -- "critical" → Show critical path tasks -- Multiple IDs → Comparative view - -### 2. **Contextual Information** - -For each task, intelligently include: - -**Core Details** -- Full task information (id, title, description, details) -- Current status with history -- Test strategy and acceptance criteria -- Priority and complexity analysis - -**Relationships** -- Dependencies (what it needs) -- Dependents (what needs it) -- Parent/subtask hierarchy -- Related tasks (similar work) - -**Time Intelligence** -- Created/updated timestamps -- Time in current status -- Estimated vs actual time -- Historical completion patterns - -### 3. **Visual Enhancements** - -``` -📋 Task #45: Implement User Authentication -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Status: 🟡 in-progress (2 hours) -Priority: 🔴 High | Complexity: 73/100 - -Dependencies: ✅ #41, ✅ #42, ⏳ #43 (blocked) -Blocks: #46, #47, #52 - -Progress: ████████░░ 80% complete - -Recent Activity: -- 2h ago: Status changed to in-progress -- 4h ago: Dependency #42 completed -- Yesterday: Task expanded with 3 subtasks -``` - -### 4. **Intelligent Insights** - -Based on task analysis: -- **Risk Assessment**: Complexity vs time remaining -- **Bottleneck Analysis**: Is this blocking critical work? -- **Recommendation**: Suggested approach or concerns -- **Similar Tasks**: How others completed similar work - -### 5. **Action Suggestions** - -Context-aware next steps: -- If blocked → Show how to unblock -- If complex → Suggest expansion -- If in-progress → Show completion checklist -- If done → Show dependent tasks ready to start - -### 6. **Multi-Task View** - -When showing multiple tasks: -- Common dependencies -- Optimal completion order -- Parallel work opportunities -- Combined complexity analysis \ No newline at end of file diff --git a/.claude/commands/tm/status/project-status.md b/.claude/commands/tm/status/project-status.md deleted file mode 100644 index c62bcc24..00000000 --- a/.claude/commands/tm/status/project-status.md +++ /dev/null @@ -1,64 +0,0 @@ -Enhanced status command with comprehensive project insights. - -Arguments: $ARGUMENTS - -## Intelligent Status Overview - -### 1. **Executive Summary** -Quick dashboard view: -- 🏃 Active work (in-progress tasks) -- 📊 Progress metrics (% complete, velocity) -- 🚧 Blockers and risks -- ⏱️ Time analysis (estimated vs actual) -- 🎯 Sprint/milestone progress - -### 2. **Contextual Analysis** - -Based on $ARGUMENTS, focus on: -- "sprint" → Current sprint progress and burndown -- "blocked" → Dependency chains and resolution paths -- "team" → Task distribution and workload -- "timeline" → Schedule adherence and projections -- "risk" → High complexity or overdue items - -### 3. **Smart Insights** - -**Workflow Health:** -- Idle tasks (in-progress > 24h without updates) -- Bottlenecks (multiple tasks waiting on same dependency) -- Quick wins (low complexity, high impact) - -**Predictive Analytics:** -- Completion projections based on velocity -- Risk of missing deadlines -- Recommended task order for optimal flow - -### 4. **Visual Intelligence** - -Dynamic visualization based on data: -``` -Sprint Progress: ████████░░ 80% (16/20 tasks) -Velocity Trend: ↗️ +15% this week -Blocked Tasks: 🔴 3 critical path items - -Priority Distribution: -High: ████████ 8 tasks (2 blocked) -Medium: ████░░░░ 4 tasks -Low: ██░░░░░░ 2 tasks -``` - -### 5. **Actionable Recommendations** - -Based on analysis: -1. **Immediate actions** (unblock critical path) -2. **Today's focus** (optimal task sequence) -3. **Process improvements** (recurring patterns) -4. **Resource needs** (skills, time, dependencies) - -### 6. **Historical Context** - -Compare to previous periods: -- Velocity changes -- Pattern recognition -- Improvement areas -- Success patterns to repeat \ No newline at end of file diff --git a/.claude/commands/tm/sync-readme/sync-readme.md b/.claude/commands/tm/sync-readme/sync-readme.md deleted file mode 100644 index 7f319e25..00000000 --- a/.claude/commands/tm/sync-readme/sync-readme.md +++ /dev/null @@ -1,117 +0,0 @@ -Export tasks to README.md with professional formatting. - -Arguments: $ARGUMENTS - -Generate a well-formatted README with current task information. - -## README Synchronization - -Creates or updates README.md with beautifully formatted task information. - -## Argument Parsing - -Optional filters: -- "pending" → Only pending tasks -- "with-subtasks" → Include subtask details -- "by-priority" → Group by priority -- "sprint" → Current sprint only - -## Execution - -```bash -task-master sync-readme [--with-subtasks] [--status=<status>] -``` - -## README Generation - -### 1. **Project Header** -```markdown -# Project Name - -## 📋 Task Progress - -Last Updated: 2024-01-15 10:30 AM - -### Summary -- Total Tasks: 45 -- Completed: 15 (33%) -- In Progress: 5 (11%) -- Pending: 25 (56%) -``` - -### 2. **Task Sections** -Organized by status or priority: -- Progress indicators -- Task descriptions -- Dependencies noted -- Time estimates - -### 3. **Visual Elements** -- Progress bars -- Status badges -- Priority indicators -- Completion checkmarks - -## Smart Features - -1. **Intelligent Grouping** - - By feature area - - By sprint/milestone - - By assigned developer - - By priority - -2. **Progress Tracking** - - Overall completion - - Sprint velocity - - Burndown indication - - Time tracking - -3. **Formatting Options** - - GitHub-flavored markdown - - Task checkboxes - - Collapsible sections - - Table format available - -## Example Output - -```markdown -## 🚀 Current Sprint - -### In Progress -- [ ] 🔄 #5 **Implement user authentication** (60% complete) - - Dependencies: API design (#3 ✅) - - Subtasks: 4 (2 completed) - - Est: 8h / Spent: 5h - -### Pending (High Priority) -- [ ] ⚡ #8 **Create dashboard UI** - - Blocked by: #5 - - Complexity: High - - Est: 12h -``` - -## Customization - -Based on arguments: -- Include/exclude sections -- Detail level control -- Custom grouping -- Filter by criteria - -## Post-Sync - -After generation: -1. Show diff preview -2. Backup existing README -3. Write new content -4. Commit reminder -5. Update timestamp - -## Integration - -Works well with: -- Git workflows -- CI/CD pipelines -- Project documentation -- Team updates -- Client reports \ No newline at end of file diff --git a/.claude/commands/tm/tm-main.md b/.claude/commands/tm/tm-main.md deleted file mode 100644 index 92946364..00000000 --- a/.claude/commands/tm/tm-main.md +++ /dev/null @@ -1,146 +0,0 @@ -# Task Master Command Reference - -Comprehensive command structure for Task Master integration with Claude Code. - -## Command Organization - -Commands are organized hierarchically to match Task Master's CLI structure while providing enhanced Claude Code integration. - -## Project Setup & Configuration - -### `/project:tm/init` -- `init-project` - Initialize new project (handles PRD files intelligently) -- `init-project-quick` - Quick setup with auto-confirmation (-y flag) - -### `/project:tm/models` -- `view-models` - View current AI model configuration -- `setup-models` - Interactive model configuration -- `set-main` - Set primary generation model -- `set-research` - Set research model -- `set-fallback` - Set fallback model - -## Task Generation - -### `/project:tm/parse-prd` -- `parse-prd` - Generate tasks from PRD document -- `parse-prd-with-research` - Enhanced parsing with research mode - -### `/project:tm/generate` -- `generate-tasks` - Create individual task files from tasks.json - -## Task Management - -### `/project:tm/list` -- `list-tasks` - Smart listing with natural language filters -- `list-tasks-with-subtasks` - Include subtasks in hierarchical view -- `list-tasks-by-status` - Filter by specific status - -### `/project:tm/set-status` -- `to-pending` - Reset task to pending -- `to-in-progress` - Start working on task -- `to-done` - Mark task complete -- `to-review` - Submit for review -- `to-deferred` - Defer task -- `to-cancelled` - Cancel task - -### `/project:tm/sync-readme` -- `sync-readme` - Export tasks to README.md with formatting - -### `/project:tm/update` -- `update-task` - Update tasks with natural language -- `update-tasks-from-id` - Update multiple tasks from a starting point -- `update-single-task` - Update specific task - -### `/project:tm/add-task` -- `add-task` - Add new task with AI assistance - -### `/project:tm/remove-task` -- `remove-task` - Remove task with confirmation - -## Subtask Management - -### `/project:tm/add-subtask` -- `add-subtask` - Add new subtask to parent -- `convert-task-to-subtask` - Convert existing task to subtask - -### `/project:tm/remove-subtask` -- `remove-subtask` - Remove subtask (with optional conversion) - -### `/project:tm/clear-subtasks` -- `clear-subtasks` - Clear subtasks from specific task -- `clear-all-subtasks` - Clear all subtasks globally - -## Task Analysis & Breakdown - -### `/project:tm/analyze-complexity` -- `analyze-complexity` - Analyze and generate expansion recommendations - -### `/project:tm/complexity-report` -- `complexity-report` - Display complexity analysis report - -### `/project:tm/expand` -- `expand-task` - Break down specific task -- `expand-all-tasks` - Expand all eligible tasks -- `with-research` - Enhanced expansion - -## Task Navigation - -### `/project:tm/next` -- `next-task` - Intelligent next task recommendation - -### `/project:tm/show` -- `show-task` - Display detailed task information - -### `/project:tm/status` -- `project-status` - Comprehensive project dashboard - -## Dependency Management - -### `/project:tm/add-dependency` -- `add-dependency` - Add task dependency - -### `/project:tm/remove-dependency` -- `remove-dependency` - Remove task dependency - -### `/project:tm/validate-dependencies` -- `validate-dependencies` - Check for dependency issues - -### `/project:tm/fix-dependencies` -- `fix-dependencies` - Automatically fix dependency problems - -## Workflows & Automation - -### `/project:tm/workflows` -- `smart-workflow` - Context-aware intelligent workflow execution -- `command-pipeline` - Chain multiple commands together -- `auto-implement-tasks` - Advanced auto-implementation with code generation - -## Utilities - -### `/project:tm/utils` -- `analyze-project` - Deep project analysis and insights - -### `/project:tm/setup` -- `install-taskmaster` - Comprehensive installation guide -- `quick-install-taskmaster` - One-line global installation - -## Usage Patterns - -### Natural Language -Most commands accept natural language arguments: -``` -/project:tm/add-task create user authentication system -/project:tm/update mark all API tasks as high priority -/project:tm/list show blocked tasks -``` - -### ID-Based Commands -Commands requiring IDs intelligently parse from $ARGUMENTS: -``` -/project:tm/show 45 -/project:tm/expand 23 -/project:tm/set-status/to-done 67 -``` - -### Smart Defaults -Commands provide intelligent defaults and suggestions based on context. \ No newline at end of file diff --git a/.claude/commands/tm/update/update-single-task.md b/.claude/commands/tm/update/update-single-task.md deleted file mode 100644 index 9bab5fac..00000000 --- a/.claude/commands/tm/update/update-single-task.md +++ /dev/null @@ -1,119 +0,0 @@ -Update a single specific task with new information. - -Arguments: $ARGUMENTS - -Parse task ID and update details. - -## Single Task Update - -Precisely update one task with AI assistance to maintain consistency. - -## Argument Parsing - -Natural language updates: -- "5: add caching requirement" -- "update 5 to include error handling" -- "task 5 needs rate limiting" -- "5 change priority to high" - -## Execution - -```bash -task-master update-task --id=<id> --prompt="<context>" -``` - -## Update Types - -### 1. **Content Updates** -- Enhance description -- Add requirements -- Clarify details -- Update acceptance criteria - -### 2. **Metadata Updates** -- Change priority -- Adjust time estimates -- Update complexity -- Modify dependencies - -### 3. **Strategic Updates** -- Revise approach -- Change test strategy -- Update implementation notes -- Adjust subtask needs - -## AI-Powered Updates - -The AI: -1. **Understands Context** - - Reads current task state - - Identifies update intent - - Maintains consistency - - Preserves important info - -2. **Applies Changes** - - Updates relevant fields - - Keeps style consistent - - Adds without removing - - Enhances clarity - -3. **Validates Results** - - Checks coherence - - Verifies completeness - - Maintains relationships - - Suggests related updates - -## Example Updates - -``` -/project:tm/update/single 5: add rate limiting -→ Updating Task #5: "Implement API endpoints" - -Current: Basic CRUD endpoints -Adding: Rate limiting requirements - -Updated sections: -✓ Description: Added rate limiting mention -✓ Details: Added specific limits (100/min) -✓ Test Strategy: Added rate limit tests -✓ Complexity: Increased from 5 to 6 -✓ Time Estimate: Increased by 2 hours - -Suggestion: Also update task #6 (API Gateway) for consistency? -``` - -## Smart Features - -1. **Incremental Updates** - - Adds without overwriting - - Preserves work history - - Tracks what changed - - Shows diff view - -2. **Consistency Checks** - - Related task alignment - - Subtask compatibility - - Dependency validity - - Timeline impact - -3. **Update History** - - Timestamp changes - - Track who/what updated - - Reason for update - - Previous versions - -## Field-Specific Updates - -Quick syntax for specific fields: -- "5 priority:high" → Update priority only -- "5 add-time:4h" → Add to time estimate -- "5 status:review" → Change status -- "5 depends:3,4" → Add dependencies - -## Post-Update - -- Show updated task -- Highlight changes -- Check related tasks -- Update suggestions -- Timeline adjustments \ No newline at end of file diff --git a/.claude/commands/tm/update/update-task.md b/.claude/commands/tm/update/update-task.md deleted file mode 100644 index a654d5eb..00000000 --- a/.claude/commands/tm/update/update-task.md +++ /dev/null @@ -1,72 +0,0 @@ -Update tasks with intelligent field detection and bulk operations. - -Arguments: $ARGUMENTS - -## Intelligent Task Updates - -Parse arguments to determine update intent and execute smartly. - -### 1. **Natural Language Processing** - -Understand update requests like: -- "mark 23 as done" → Update status to done -- "increase priority of 45" → Set priority to high -- "add dependency on 12 to task 34" → Add dependency -- "tasks 20-25 need review" → Bulk status update -- "all API tasks high priority" → Pattern-based update - -### 2. **Smart Field Detection** - -Automatically detect what to update: -- Status keywords: done, complete, start, pause, review -- Priority changes: urgent, high, low, deprioritize -- Dependency updates: depends on, blocks, after -- Assignment: assign to, owner, responsible -- Time: estimate, spent, deadline - -### 3. **Bulk Operations** - -Support for multiple task updates: -``` -Examples: -- "complete tasks 12, 15, 18" -- "all pending auth tasks to in-progress" -- "increase priority for tasks blocking 45" -- "defer all documentation tasks" -``` - -### 4. **Contextual Validation** - -Before updating, check: -- Status transitions are valid -- Dependencies don't create cycles -- Priority changes make sense -- Bulk updates won't break project flow - -Show preview: -``` -Update Preview: -───────────────── -Tasks to update: #23, #24, #25 -Change: status → in-progress -Impact: Will unblock tasks #30, #31 -Warning: Task #24 has unmet dependencies -``` - -### 5. **Smart Suggestions** - -Based on update: -- Completing task? → Show newly unblocked tasks -- Changing priority? → Show impact on sprint -- Adding dependency? → Check for conflicts -- Bulk update? → Show summary of changes - -### 6. **Workflow Integration** - -After updates: -- Auto-update dependent task states -- Trigger status recalculation -- Update sprint/milestone progress -- Log changes with context - -Result: Flexible, intelligent task updates with safety checks. \ No newline at end of file diff --git a/.claude/commands/tm/update/update-tasks-from-id.md b/.claude/commands/tm/update/update-tasks-from-id.md deleted file mode 100644 index 1085352d..00000000 --- a/.claude/commands/tm/update/update-tasks-from-id.md +++ /dev/null @@ -1,108 +0,0 @@ -Update multiple tasks starting from a specific ID. - -Arguments: $ARGUMENTS - -Parse starting task ID and update context. - -## Bulk Task Updates - -Update multiple related tasks based on new requirements or context changes. - -## Argument Parsing - -- "from 5: add security requirements" -- "5 onwards: update API endpoints" -- "starting at 5: change to use new framework" - -## Execution - -```bash -task-master update --from=<id> --prompt="<context>" -``` - -## Update Process - -### 1. **Task Selection** -Starting from specified ID: -- Include the task itself -- Include all dependent tasks -- Include related subtasks -- Smart boundary detection - -### 2. **Context Application** -AI analyzes the update context and: -- Identifies what needs changing -- Maintains consistency -- Preserves completed work -- Updates related information - -### 3. **Intelligent Updates** -- Modify descriptions appropriately -- Update test strategies -- Adjust time estimates -- Revise dependencies if needed - -## Smart Features - -1. **Scope Detection** - - Find natural task groupings - - Identify related features - - Stop at logical boundaries - - Avoid over-updating - -2. **Consistency Maintenance** - - Keep naming conventions - - Preserve relationships - - Update cross-references - - Maintain task flow - -3. **Change Preview** - ``` - Bulk Update Preview - ━━━━━━━━━━━━━━━━━━ - Starting from: Task #5 - Tasks to update: 8 tasks + 12 subtasks - - Context: "add security requirements" - - Changes will include: - - Add security sections to descriptions - - Update test strategies for security - - Add security-related subtasks where needed - - Adjust time estimates (+20% average) - - Continue? (y/n) - ``` - -## Example Updates - -``` -/project:tm/update/from-id 5: change database to PostgreSQL -→ Analyzing impact starting from task #5 -→ Found 6 related tasks to update -→ Updates will maintain consistency -→ Preview changes? (y/n) - -Applied updates: -✓ Task #5: Updated connection logic references -✓ Task #6: Changed migration approach -✓ Task #7: Updated query syntax notes -✓ Task #8: Revised testing strategy -✓ Task #9: Updated deployment steps -✓ Task #12: Changed backup procedures -``` - -## Safety Features - -- Preview all changes -- Selective confirmation -- Rollback capability -- Change logging -- Validation checks - -## Post-Update - -- Summary of changes -- Consistency verification -- Suggest review tasks -- Update timeline if needed \ No newline at end of file diff --git a/.claude/commands/tm/utils/analyze-project.md b/.claude/commands/tm/utils/analyze-project.md deleted file mode 100644 index 92622044..00000000 --- a/.claude/commands/tm/utils/analyze-project.md +++ /dev/null @@ -1,97 +0,0 @@ -Advanced project analysis with actionable insights and recommendations. - -Arguments: $ARGUMENTS - -## Comprehensive Project Analysis - -Multi-dimensional analysis based on requested focus area. - -### 1. **Analysis Modes** - -Based on $ARGUMENTS: -- "velocity" → Sprint velocity and trends -- "quality" → Code quality metrics -- "risk" → Risk assessment and mitigation -- "dependencies" → Dependency graph analysis -- "team" → Workload and skill distribution -- "architecture" → System design coherence -- Default → Full spectrum analysis - -### 2. **Velocity Analytics** - -``` -📊 Velocity Analysis -━━━━━━━━━━━━━━━━━━━ -Current Sprint: 24 points/week ↗️ +20% -Rolling Average: 20 points/week -Efficiency: 85% (17/20 tasks on time) - -Bottlenecks Detected: -- Code review delays (avg 4h wait) -- Test environment availability -- Dependency on external team - -Recommendations: -1. Implement parallel review process -2. Add staging environment -3. Mock external dependencies -``` - -### 3. **Risk Assessment** - -**Technical Risks** -- High complexity tasks without backup assignee -- Single points of failure in architecture -- Insufficient test coverage in critical paths -- Technical debt accumulation rate - -**Project Risks** -- Critical path dependencies -- Resource availability gaps -- Deadline feasibility analysis -- Scope creep indicators - -### 4. **Dependency Intelligence** - -Visual dependency analysis: -``` -Critical Path: -#12 → #15 → #23 → #45 → #50 (20 days) - ↘ #24 → #46 ↗ - -Optimization: Parallelize #15 and #24 -Time Saved: 3 days -``` - -### 5. **Quality Metrics** - -**Code Quality** -- Test coverage trends -- Complexity scores -- Technical debt ratio -- Review feedback patterns - -**Process Quality** -- Rework frequency -- Bug introduction rate -- Time to resolution -- Knowledge distribution - -### 6. **Predictive Insights** - -Based on patterns: -- Completion probability by deadline -- Resource needs projection -- Risk materialization likelihood -- Suggested interventions - -### 7. **Executive Dashboard** - -High-level summary with: -- Health score (0-100) -- Top 3 risks -- Top 3 opportunities -- Recommended actions -- Success probability - -Result: Data-driven decisions with clear action paths. \ No newline at end of file diff --git a/.claude/commands/tm/validate-dependencies/validate-dependencies.md b/.claude/commands/tm/validate-dependencies/validate-dependencies.md deleted file mode 100644 index aaf4eb46..00000000 --- a/.claude/commands/tm/validate-dependencies/validate-dependencies.md +++ /dev/null @@ -1,71 +0,0 @@ -Validate all task dependencies for issues. - -## Dependency Validation - -Comprehensive check for dependency problems across the entire project. - -## Execution - -```bash -task-master validate-dependencies -``` - -## Validation Checks - -1. **Circular Dependencies** - - A depends on B, B depends on A - - Complex circular chains - - Self-dependencies - -2. **Missing Dependencies** - - References to non-existent tasks - - Deleted task references - - Invalid task IDs - -3. **Logical Issues** - - Completed tasks depending on pending - - Cancelled tasks in dependency chains - - Impossible sequences - -4. **Complexity Warnings** - - Over-complex dependency chains - - Too many dependencies per task - - Bottleneck tasks - -## Smart Analysis - -The validation provides: -- Visual dependency graph -- Critical path analysis -- Bottleneck identification -- Suggested optimizations - -## Report Format - -``` -Dependency Validation Report -━━━━━━━━━━━━━━━━━━━━━━━━━━ -✅ No circular dependencies found -⚠️ 2 warnings found: - - Task #23 has 7 dependencies (consider breaking down) - - Task #45 blocks 5 other tasks (potential bottleneck) -❌ 1 error found: - - Task #67 depends on deleted task #66 - -Critical Path: #1 → #5 → #23 → #45 → #50 (15 days) -``` - -## Actionable Output - -For each issue found: -- Clear description -- Impact assessment -- Suggested fix -- Command to resolve - -## Next Steps - -After validation: -- Run `/project:tm/fix-dependencies` to auto-fix -- Manually adjust problematic dependencies -- Rerun to verify fixes \ No newline at end of file diff --git a/.claude/commands/tm/workflows/auto-implement-tasks.md b/.claude/commands/tm/workflows/auto-implement-tasks.md deleted file mode 100644 index 20abc950..00000000 --- a/.claude/commands/tm/workflows/auto-implement-tasks.md +++ /dev/null @@ -1,97 +0,0 @@ -Enhanced auto-implementation with intelligent code generation and testing. - -Arguments: $ARGUMENTS - -## Intelligent Auto-Implementation - -Advanced implementation with context awareness and quality checks. - -### 1. **Pre-Implementation Analysis** - -Before starting: -- Analyze task complexity and requirements -- Check codebase patterns and conventions -- Identify similar completed tasks -- Assess test coverage needs -- Detect potential risks - -### 2. **Smart Implementation Strategy** - -Based on task type and context: - -**Feature Tasks** -1. Research existing patterns -2. Design component architecture -3. Implement with tests -4. Integrate with system -5. Update documentation - -**Bug Fix Tasks** -1. Reproduce issue -2. Identify root cause -3. Implement minimal fix -4. Add regression tests -5. Verify side effects - -**Refactoring Tasks** -1. Analyze current structure -2. Plan incremental changes -3. Maintain test coverage -4. Refactor step-by-step -5. Verify behavior unchanged - -### 3. **Code Intelligence** - -**Pattern Recognition** -- Learn from existing code -- Follow team conventions -- Use preferred libraries -- Match style guidelines - -**Test-Driven Approach** -- Write tests first when possible -- Ensure comprehensive coverage -- Include edge cases -- Performance considerations - -### 4. **Progressive Implementation** - -Step-by-step with validation: -``` -Step 1/5: Setting up component structure ✓ -Step 2/5: Implementing core logic ✓ -Step 3/5: Adding error handling ⚡ (in progress) -Step 4/5: Writing tests ⏳ -Step 5/5: Integration testing ⏳ - -Current: Adding try-catch blocks and validation... -``` - -### 5. **Quality Assurance** - -Automated checks: -- Linting and formatting -- Test execution -- Type checking -- Dependency validation -- Performance analysis - -### 6. **Smart Recovery** - -If issues arise: -- Diagnostic analysis -- Suggestion generation -- Fallback strategies -- Manual intervention points -- Learning from failures - -### 7. **Post-Implementation** - -After completion: -- Generate PR description -- Update documentation -- Log lessons learned -- Suggest follow-up tasks -- Update task relationships - -Result: High-quality, production-ready implementations. \ No newline at end of file diff --git a/.claude/commands/tm/workflows/command-pipeline.md b/.claude/commands/tm/workflows/command-pipeline.md deleted file mode 100644 index 83080018..00000000 --- a/.claude/commands/tm/workflows/command-pipeline.md +++ /dev/null @@ -1,77 +0,0 @@ -Execute a pipeline of commands based on a specification. - -Arguments: $ARGUMENTS - -## Command Pipeline Execution - -Parse pipeline specification from arguments. Supported formats: - -### Simple Pipeline -`init → expand-all → sprint-plan` - -### Conditional Pipeline -`status → if:pending>10 → sprint-plan → else → next` - -### Iterative Pipeline -`for:pending-tasks → expand → complexity-check` - -### Smart Pipeline Patterns - -**1. Project Setup Pipeline** -``` -init [prd] → -expand-all → -complexity-report → -sprint-plan → -show first-sprint -``` - -**2. Daily Work Pipeline** -``` -standup → -if:in-progress → continue → -else → next → start -``` - -**3. Task Completion Pipeline** -``` -complete [id] → -git-commit → -if:blocked-tasks-freed → show-freed → -next -``` - -**4. Quality Check Pipeline** -``` -list in-progress → -for:each → check-idle-time → -if:idle>1day → prompt-update -``` - -### Pipeline Features - -**Variables** -- Store results: `status → $count=pending-count` -- Use in conditions: `if:$count>10` -- Pass between commands: `expand $high-priority-tasks` - -**Error Handling** -- On failure: `try:complete → catch:show-blockers` -- Skip on error: `optional:test-run` -- Retry logic: `retry:3:commit` - -**Parallel Execution** -- Parallel branches: `[analyze | test | lint]` -- Join results: `parallel → join:report` - -### Execution Flow - -1. Parse pipeline specification -2. Validate command sequence -3. Execute with state passing -4. Handle conditions and loops -5. Aggregate results -6. Show summary - -This enables complex workflows like: -`parse-prd → expand-all → filter:complex>70 → assign:senior → sprint-plan:weighted` \ No newline at end of file diff --git a/.claude/commands/tm/workflows/smart-workflow.md b/.claude/commands/tm/workflows/smart-workflow.md deleted file mode 100644 index 56eb28d4..00000000 --- a/.claude/commands/tm/workflows/smart-workflow.md +++ /dev/null @@ -1,55 +0,0 @@ -Execute an intelligent workflow based on current project state and recent commands. - -This command analyzes: -1. Recent commands you've run -2. Current project state -3. Time of day / day of week -4. Your working patterns - -Arguments: $ARGUMENTS - -## Intelligent Workflow Selection - -Based on context, I'll determine the best workflow: - -### Context Analysis -- Previous command executed -- Current task states -- Unfinished work from last session -- Your typical patterns - -### Smart Execution - -If last command was: -- `status` → Likely starting work → Run daily standup -- `complete` → Task finished → Find next task -- `list pending` → Planning → Suggest sprint planning -- `expand` → Breaking down work → Show complexity analysis -- `init` → New project → Show onboarding workflow - -If no recent commands: -- Morning? → Daily standup workflow -- Many pending tasks? → Sprint planning -- Tasks blocked? → Dependency resolution -- Friday? → Weekly review - -### Workflow Composition - -I'll chain appropriate commands: -1. Analyze current state -2. Execute primary workflow -3. Suggest follow-up actions -4. Prepare environment for coding - -### Learning Mode - -This command learns from your patterns: -- Track command sequences -- Note time preferences -- Remember common workflows -- Adapt to your style - -Example flows detected: -- Morning: standup → next → start -- After lunch: status → continue task -- End of day: complete → commit → status \ No newline at end of file diff --git a/.cursor/mcp.json b/.cursor/mcp.json deleted file mode 100644 index b157908c..00000000 --- a/.cursor/mcp.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "mcpServers": { - "task-master-ai": { - "command": "npx", - "args": ["-y", "--package=task-master-ai", "task-master-ai"], - "env": { - "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE", - "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE", - "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE", - "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE", - "XAI_API_KEY": "YOUR_XAI_KEY_HERE", - "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE", - "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE", - "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE", - "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE" - } - } - } -} diff --git a/.cursor/rules/cursor_rules.mdc b/.cursor/rules/cursor_rules.mdc deleted file mode 100644 index 7dfae3de..00000000 --- a/.cursor/rules/cursor_rules.mdc +++ /dev/null @@ -1,53 +0,0 @@ ---- -description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness. -globs: .cursor/rules/*.mdc -alwaysApply: true ---- - -- **Required Rule Structure:** - ```markdown - --- - description: Clear, one-line description of what the rule enforces - globs: path/to/files/*.ext, other/path/**/* - alwaysApply: boolean - --- - - - **Main Points in Bold** - - Sub-points with details - - Examples and explanations - ``` - -- **File References:** - - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files - - Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references - - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references - -- **Code Examples:** - - Use language-specific code blocks - ```typescript - // ✅ DO: Show good examples - const goodExample = true; - - // ❌ DON'T: Show anti-patterns - const badExample = false; - ``` - -- **Rule Content Guidelines:** - - Start with high-level overview - - Include specific, actionable requirements - - Show examples of correct implementation - - Reference existing code when possible - - Keep rules DRY by referencing other rules - -- **Rule Maintenance:** - - Update rules when new patterns emerge - - Add examples from actual codebase - - Remove outdated patterns - - Cross-reference related rules - -- **Best Practices:** - - Use bullet points for clarity - - Keep descriptions concise - - Include both DO and DON'T examples - - Reference actual code over theoretical examples - - Use consistent formatting across rules \ No newline at end of file diff --git a/.cursor/rules/self_improve.mdc b/.cursor/rules/self_improve.mdc deleted file mode 100644 index 40b31b6e..00000000 --- a/.cursor/rules/self_improve.mdc +++ /dev/null @@ -1,72 +0,0 @@ ---- -description: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices. -globs: **/* -alwaysApply: true ---- - -- **Rule Improvement Triggers:** - - New code patterns not covered by existing rules - - Repeated similar implementations across files - - Common error patterns that could be prevented - - New libraries or tools being used consistently - - Emerging best practices in the codebase - -- **Analysis Process:** - - Compare new code with existing rules - - Identify patterns that should be standardized - - Look for references to external documentation - - Check for consistent error handling patterns - - Monitor test patterns and coverage - -- **Rule Updates:** - - **Add New Rules When:** - - A new technology/pattern is used in 3+ files - - Common bugs could be prevented by a rule - - Code reviews repeatedly mention the same feedback - - New security or performance patterns emerge - - - **Modify Existing Rules When:** - - Better examples exist in the codebase - - Additional edge cases are discovered - - Related rules have been updated - - Implementation details have changed - -- **Example Pattern Recognition:** - ```typescript - // If you see repeated patterns like: - const data = await prisma.user.findMany({ - select: { id: true, email: true }, - where: { status: 'ACTIVE' } - }); - - // Consider adding to [prisma.mdc](mdc:.cursor/rules/prisma.mdc): - // - Standard select fields - // - Common where conditions - // - Performance optimization patterns - ``` - -- **Rule Quality Checks:** - - Rules should be actionable and specific - - Examples should come from actual code - - References should be up to date - - Patterns should be consistently enforced - -- **Continuous Improvement:** - - Monitor code review comments - - Track common development questions - - Update rules after major refactors - - Add links to relevant documentation - - Cross-reference related rules - -- **Rule Deprecation:** - - Mark outdated patterns as deprecated - - Remove rules that no longer apply - - Update references to deprecated rules - - Document migration paths for old patterns - -- **Documentation Updates:** - - Keep examples synchronized with code - - Update references to external docs - - Maintain links between related rules - - Document breaking changes -Follow [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) for proper rule formatting and structure. diff --git a/.cursor/rules/taskmaster/dev_workflow.mdc b/.cursor/rules/taskmaster/dev_workflow.mdc deleted file mode 100644 index 84dd906f..00000000 --- a/.cursor/rules/taskmaster/dev_workflow.mdc +++ /dev/null @@ -1,424 +0,0 @@ ---- -description: Guide for using Taskmaster to manage task-driven development workflows -globs: **/* -alwaysApply: true ---- - -# Taskmaster Development Workflow - -This guide outlines the standard process for using Taskmaster to manage software development projects. It is written as a set of instructions for you, the AI agent. - -- **Your Default Stance**: For most projects, the user can work directly within the `master` task context. Your initial actions should operate on this default context unless a clear pattern for multi-context work emerges. -- **Your Goal**: Your role is to elevate the user's workflow by intelligently introducing advanced features like **Tagged Task Lists** when you detect the appropriate context. Do not force tags on the user; suggest them as a helpful solution to a specific need. - -## The Basic Loop -The fundamental development cycle you will facilitate is: -1. **`list`**: Show the user what needs to be done. -2. **`next`**: Help the user decide what to work on. -3. **`show <id>`**: Provide details for a specific task. -4. **`expand <id>`**: Break down a complex task into smaller, manageable subtasks. -5. **Implement**: The user writes the code and tests. -6. **`update-subtask`**: Log progress and findings on behalf of the user. -7. **`set-status`**: Mark tasks and subtasks as `done` as work is completed. -8. **Repeat**. - -All your standard command executions should operate on the user's current task context, which defaults to `master`. - ---- - -## Standard Development Workflow Process - -### Simple Workflow (Default Starting Point) - -For new projects or when users are getting started, operate within the `master` tag context: - -- Start new projects by running `initialize_project` tool / `task-master init` or `parse_prd` / `task-master parse-prd --input='<prd-file.txt>'` (see @`taskmaster.mdc`) to generate initial tasks.json with tagged structure -- Configure rule sets during initialization with `--rules` flag (e.g., `task-master init --rules cursor,windsurf`) or manage them later with `task-master rules add/remove` commands -- Begin coding sessions with `get_tasks` / `task-master list` (see @`taskmaster.mdc`) to see current tasks, status, and IDs -- Determine the next task to work on using `next_task` / `task-master next` (see @`taskmaster.mdc`) -- Analyze task complexity with `analyze_project_complexity` / `task-master analyze-complexity --research` (see @`taskmaster.mdc`) before breaking down tasks -- Review complexity report using `complexity_report` / `task-master complexity-report` (see @`taskmaster.mdc`) -- Select tasks based on dependencies (all marked 'done'), priority level, and ID order -- View specific task details using `get_task` / `task-master show <id>` (see @`taskmaster.mdc`) to understand implementation requirements -- Break down complex tasks using `expand_task` / `task-master expand --id=<id> --force --research` (see @`taskmaster.mdc`) with appropriate flags like `--force` (to replace existing subtasks) and `--research` -- Implement code following task details, dependencies, and project standards -- Mark completed tasks with `set_task_status` / `task-master set-status --id=<id> --status=done` (see @`taskmaster.mdc`) -- Update dependent tasks when implementation differs from original plan using `update` / `task-master update --from=<id> --prompt="..."` or `update_task` / `task-master update-task --id=<id> --prompt="..."` (see @`taskmaster.mdc`) - ---- - -## Leveling Up: Agent-Led Multi-Context Workflows - -While the basic workflow is powerful, your primary opportunity to add value is by identifying when to introduce **Tagged Task Lists**. These patterns are your tools for creating a more organized and efficient development environment for the user, especially if you detect agentic or parallel development happening across the same session. - -**Critical Principle**: Most users should never see a difference in their experience. Only introduce advanced workflows when you detect clear indicators that the project has evolved beyond simple task management. - -### When to Introduce Tags: Your Decision Patterns - -Here are the patterns to look for. When you detect one, you should propose the corresponding workflow to the user. - -#### Pattern 1: Simple Git Feature Branching -This is the most common and direct use case for tags. - -- **Trigger**: The user creates a new git branch (e.g., `git checkout -b feature/user-auth`). -- **Your Action**: Propose creating a new tag that mirrors the branch name to isolate the feature's tasks from `master`. -- **Your Suggested Prompt**: *"I see you've created a new branch named 'feature/user-auth'. To keep all related tasks neatly organized and separate from your main list, I can create a corresponding task tag for you. This helps prevent merge conflicts in your `tasks.json` file later. Shall I create the 'feature-user-auth' tag?"* -- **Tool to Use**: `task-master add-tag --from-branch` - -#### Pattern 2: Team Collaboration -- **Trigger**: The user mentions working with teammates (e.g., "My teammate Alice is handling the database schema," or "I need to review Bob's work on the API."). -- **Your Action**: Suggest creating a separate tag for the user's work to prevent conflicts with shared master context. -- **Your Suggested Prompt**: *"Since you're working with Alice, I can create a separate task context for your work to avoid conflicts. This way, Alice can continue working with the master list while you have your own isolated context. When you're ready to merge your work, we can coordinate the tasks back to master. Shall I create a tag for your current work?"* -- **Tool to Use**: `task-master add-tag my-work --copy-from-current --description="My tasks while collaborating with Alice"` - -#### Pattern 3: Experiments or Risky Refactors -- **Trigger**: The user wants to try something that might not be kept (e.g., "I want to experiment with switching our state management library," or "Let's refactor the old API module, but I want to keep the current tasks as a reference."). -- **Your Action**: Propose creating a sandboxed tag for the experimental work. -- **Your Suggested Prompt**: *"This sounds like a great experiment. To keep these new tasks separate from our main plan, I can create a temporary 'experiment-zustand' tag for this work. If we decide not to proceed, we can simply delete the tag without affecting the main task list. Sound good?"* -- **Tool to Use**: `task-master add-tag experiment-zustand --description="Exploring Zustand migration"` - -#### Pattern 4: Large Feature Initiatives (PRD-Driven) -This is a more structured approach for significant new features or epics. - -- **Trigger**: The user describes a large, multi-step feature that would benefit from a formal plan. -- **Your Action**: Propose a comprehensive, PRD-driven workflow. -- **Your Suggested Prompt**: *"This sounds like a significant new feature. To manage this effectively, I suggest we create a dedicated task context for it. Here's the plan: I'll create a new tag called 'feature-xyz', then we can draft a Product Requirements Document (PRD) together to scope the work. Once the PRD is ready, I'll automatically generate all the necessary tasks within that new tag. How does that sound?"* -- **Your Implementation Flow**: - 1. **Create an empty tag**: `task-master add-tag feature-xyz --description "Tasks for the new XYZ feature"`. You can also start by creating a git branch if applicable, and then create the tag from that branch. - 2. **Collaborate & Create PRD**: Work with the user to create a detailed PRD file (e.g., `.taskmaster/docs/feature-xyz-prd.txt`). - 3. **Parse PRD into the new tag**: `task-master parse-prd .taskmaster/docs/feature-xyz-prd.txt --tag feature-xyz` - 4. **Prepare the new task list**: Follow up by suggesting `analyze-complexity` and `expand-all` for the newly created tasks within the `feature-xyz` tag. - -#### Pattern 5: Version-Based Development -Tailor your approach based on the project maturity indicated by tag names. - -- **Prototype/MVP Tags** (`prototype`, `mvp`, `poc`, `v0.x`): - - **Your Approach**: Focus on speed and functionality over perfection - - **Task Generation**: Create tasks that emphasize "get it working" over "get it perfect" - - **Complexity Level**: Lower complexity, fewer subtasks, more direct implementation paths - - **Research Prompts**: Include context like "This is a prototype - prioritize speed and basic functionality over optimization" - - **Example Prompt Addition**: *"Since this is for the MVP, I'll focus on tasks that get core functionality working quickly rather than over-engineering."* - -- **Production/Mature Tags** (`v1.0+`, `production`, `stable`): - - **Your Approach**: Emphasize robustness, testing, and maintainability - - **Task Generation**: Include comprehensive error handling, testing, documentation, and optimization - - **Complexity Level**: Higher complexity, more detailed subtasks, thorough implementation paths - - **Research Prompts**: Include context like "This is for production - prioritize reliability, performance, and maintainability" - - **Example Prompt Addition**: *"Since this is for production, I'll ensure tasks include proper error handling, testing, and documentation."* - -### Advanced Workflow (Tag-Based & PRD-Driven) - -**When to Transition**: Recognize when the project has evolved (or has initiated a project which existing code) beyond simple task management. Look for these indicators: -- User mentions teammates or collaboration needs -- Project has grown to 15+ tasks with mixed priorities -- User creates feature branches or mentions major initiatives -- User initializes Taskmaster on an existing, complex codebase -- User describes large features that would benefit from dedicated planning - -**Your Role in Transition**: Guide the user to a more sophisticated workflow that leverages tags for organization and PRDs for comprehensive planning. - -#### Master List Strategy (High-Value Focus) -Once you transition to tag-based workflows, the `master` tag should ideally contain only: -- **High-level deliverables** that provide significant business value -- **Major milestones** and epic-level features -- **Critical infrastructure** work that affects the entire project -- **Release-blocking** items - -**What NOT to put in master**: -- Detailed implementation subtasks (these go in feature-specific tags' parent tasks) -- Refactoring work (create dedicated tags like `refactor-auth`) -- Experimental features (use `experiment-*` tags) -- Team member-specific tasks (use person-specific tags) - -#### PRD-Driven Feature Development - -**For New Major Features**: -1. **Identify the Initiative**: When user describes a significant feature -2. **Create Dedicated Tag**: `add_tag feature-[name] --description="[Feature description]"` -3. **Collaborative PRD Creation**: Work with user to create comprehensive PRD in `.taskmaster/docs/feature-[name]-prd.txt` -4. **Parse & Prepare**: - - `parse_prd .taskmaster/docs/feature-[name]-prd.txt --tag=feature-[name]` - - `analyze_project_complexity --tag=feature-[name] --research` - - `expand_all --tag=feature-[name] --research` -5. **Add Master Reference**: Create a high-level task in `master` that references the feature tag - -**For Existing Codebase Analysis**: -When users initialize Taskmaster on existing projects: -1. **Codebase Discovery**: Use your native tools for producing deep context about the code base. You may use `research` tool with `--tree` and `--files` to collect up to date information using the existing architecture as context. -2. **Collaborative Assessment**: Work with user to identify improvement areas, technical debt, or new features -3. **Strategic PRD Creation**: Co-author PRDs that include: - - Current state analysis (based on your codebase research) - - Proposed improvements or new features - - Implementation strategy considering existing code -4. **Tag-Based Organization**: Parse PRDs into appropriate tags (`refactor-api`, `feature-dashboard`, `tech-debt`, etc.) -5. **Master List Curation**: Keep only the most valuable initiatives in master - -The parse-prd's `--append` flag enables the user to parse multiple PRDs within tags or across tags. PRDs should be focused and the number of tasks they are parsed into should be strategically chosen relative to the PRD's complexity and level of detail. - -### Workflow Transition Examples - -**Example 1: Simple → Team-Based** -``` -User: "Alice is going to help with the API work" -Your Response: "Great! To avoid conflicts, I'll create a separate task context for your work. Alice can continue with the master list while you work in your own context. When you're ready to merge, we can coordinate the tasks back together." -Action: add_tag my-api-work --copy-from-current --description="My API tasks while collaborating with Alice" -``` - -**Example 2: Simple → PRD-Driven** -``` -User: "I want to add a complete user dashboard with analytics, user management, and reporting" -Your Response: "This sounds like a major feature that would benefit from detailed planning. Let me create a dedicated context for this work and we can draft a PRD together to ensure we capture all requirements." -Actions: -1. add_tag feature-dashboard --description="User dashboard with analytics and management" -2. Collaborate on PRD creation -3. parse_prd dashboard-prd.txt --tag=feature-dashboard -4. Add high-level "User Dashboard" task to master -``` - -**Example 3: Existing Project → Strategic Planning** -``` -User: "I just initialized Taskmaster on my existing React app. It's getting messy and I want to improve it." -Your Response: "Let me research your codebase to understand the current architecture, then we can create a strategic plan for improvements." -Actions: -1. research "Current React app architecture and improvement opportunities" --tree --files=src/ -2. Collaborate on improvement PRD based on findings -3. Create tags for different improvement areas (refactor-components, improve-state-management, etc.) -4. Keep only major improvement initiatives in master -``` - ---- - -## Primary Interaction: MCP Server vs. CLI - -Taskmaster offers two primary ways to interact: - -1. **MCP Server (Recommended for Integrated Tools)**: - - For AI agents and integrated development environments (like Cursor), interacting via the **MCP server is the preferred method**. - - The MCP server exposes Taskmaster functionality through a set of tools (e.g., `get_tasks`, `add_subtask`). - - This method offers better performance, structured data exchange, and richer error handling compared to CLI parsing. - - Refer to @`mcp.mdc` for details on the MCP architecture and available tools. - - A comprehensive list and description of MCP tools and their corresponding CLI commands can be found in @`taskmaster.mdc`. - - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change. - - **Note**: MCP tools fully support tagged task lists with complete tag management capabilities. - -2. **`task-master` CLI (For Users & Fallback)**: - - The global `task-master` command provides a user-friendly interface for direct terminal interaction. - - It can also serve as a fallback if the MCP server is inaccessible or a specific function isn't exposed via MCP. - - Install globally with `npm install -g task-master-ai` or use locally via `npx task-master-ai ...`. - - The CLI commands often mirror the MCP tools (e.g., `task-master list` corresponds to `get_tasks`). - - Refer to @`taskmaster.mdc` for a detailed command reference. - - **Tagged Task Lists**: CLI fully supports the new tagged system with seamless migration. - -## How the Tag System Works (For Your Reference) - -- **Data Structure**: Tasks are organized into separate contexts (tags) like "master", "feature-branch", or "v2.0". -- **Silent Migration**: Existing projects automatically migrate to use a "master" tag with zero disruption. -- **Context Isolation**: Tasks in different tags are completely separate. Changes in one tag do not affect any other tag. -- **Manual Control**: The user is always in control. There is no automatic switching. You facilitate switching by using `use-tag <name>`. -- **Full CLI & MCP Support**: All tag management commands are available through both the CLI and MCP tools for you to use. Refer to @`taskmaster.mdc` for a full command list. - ---- - -## Task Complexity Analysis - -- Run `analyze_project_complexity` / `task-master analyze-complexity --research` (see @`taskmaster.mdc`) for comprehensive analysis -- Review complexity report via `complexity_report` / `task-master complexity-report` (see @`taskmaster.mdc`) for a formatted, readable version. -- Focus on tasks with highest complexity scores (8-10) for detailed breakdown -- Use analysis results to determine appropriate subtask allocation -- Note that reports are automatically used by the `expand_task` tool/command - -## Task Breakdown Process - -- Use `expand_task` / `task-master expand --id=<id>`. It automatically uses the complexity report if found, otherwise generates default number of subtasks. -- Use `--num=<number>` to specify an explicit number of subtasks, overriding defaults or complexity report recommendations. -- Add `--research` flag to leverage Perplexity AI for research-backed expansion. -- Add `--force` flag to clear existing subtasks before generating new ones (default is to append). -- Use `--prompt="<context>"` to provide additional context when needed. -- Review and adjust generated subtasks as necessary. -- Use `expand_all` tool or `task-master expand --all` to expand multiple pending tasks at once, respecting flags like `--force` and `--research`. -- If subtasks need complete replacement (regardless of the `--force` flag on `expand`), clear them first with `clear_subtasks` / `task-master clear-subtasks --id=<id>`. - -## Implementation Drift Handling - -- When implementation differs significantly from planned approach -- When future tasks need modification due to current implementation choices -- When new dependencies or requirements emerge -- Use `update` / `task-master update --from=<futureTaskId> --prompt='<explanation>\nUpdate context...' --research` to update multiple future tasks. -- Use `update_task` / `task-master update-task --id=<taskId> --prompt='<explanation>\nUpdate context...' --research` to update a single specific task. - -## Task Status Management - -- Use 'pending' for tasks ready to be worked on -- Use 'done' for completed and verified tasks -- Use 'deferred' for postponed tasks -- Add custom status values as needed for project-specific workflows - -## Task Structure Fields - -- **id**: Unique identifier for the task (Example: `1`, `1.1`) -- **title**: Brief, descriptive title (Example: `"Initialize Repo"`) -- **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`) -- **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`) -- **dependencies**: IDs of prerequisite tasks (Example: `[1, 2.1]`) - - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending) - - This helps quickly identify which prerequisite tasks are blocking work -- **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`) -- **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`) -- **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`) -- **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`) -- Refer to task structure details (previously linked to `tasks.mdc`). - -## Configuration Management (Updated) - -Taskmaster configuration is managed through two main mechanisms: - -1. **`.taskmaster/config.json` File (Primary):** - * Located in the project root directory. - * Stores most configuration settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default subtasks/priority, project name, etc. - * **Tagged System Settings**: Includes `global.defaultTag` (defaults to "master") and `tags` section for tag management configuration. - * **Managed via `task-master models --setup` command.** Do not edit manually unless you know what you are doing. - * **View/Set specific models via `task-master models` command or `models` MCP tool.** - * Created automatically when you run `task-master models --setup` for the first time or during tagged system migration. - -2. **Environment Variables (`.env` / `mcp.json`):** - * Used **only** for sensitive API keys and specific endpoint URLs. - * Place API keys (one per provider) in a `.env` file in the project root for CLI usage. - * For MCP/Cursor integration, configure these keys in the `env` section of `.cursor/mcp.json`. - * Available keys/variables: See `assets/env.example` or the Configuration section in the command reference (previously linked to `taskmaster.mdc`). - -3. **`.taskmaster/state.json` File (Tagged System State):** - * Tracks current tag context and migration status. - * Automatically created during tagged system migration. - * Contains: `currentTag`, `lastSwitched`, `migrationNoticeShown`. - -**Important:** Non-API key settings (like model selections, `MAX_TOKENS`, `TASKMASTER_LOG_LEVEL`) are **no longer configured via environment variables**. Use the `task-master models` command (or `--setup` for interactive configuration) or the `models` MCP tool. -**If AI commands FAIL in MCP** verify that the API key for the selected provider is present in the `env` section of `.cursor/mcp.json`. -**If AI commands FAIL in CLI** verify that the API key for the selected provider is present in the `.env` file in the root of the project. - -## Rules Management - -Taskmaster supports multiple AI coding assistant rule sets that can be configured during project initialization or managed afterward: - -- **Available Profiles**: Claude Code, Cline, Codex, Cursor, Roo Code, Trae, Windsurf (claude, cline, codex, cursor, roo, trae, windsurf) -- **During Initialization**: Use `task-master init --rules cursor,windsurf` to specify which rule sets to include -- **After Initialization**: Use `task-master rules add <profiles>` or `task-master rules remove <profiles>` to manage rule sets -- **Interactive Setup**: Use `task-master rules setup` to launch an interactive prompt for selecting rule profiles -- **Default Behavior**: If no `--rules` flag is specified during initialization, all available rule profiles are included -- **Rule Structure**: Each profile creates its own directory (e.g., `.cursor/rules`, `.roo/rules`) with appropriate configuration files - -## Determining the Next Task - -- Run `next_task` / `task-master next` to show the next task to work on. -- The command identifies tasks with all dependencies satisfied -- Tasks are prioritized by priority level, dependency count, and ID -- The command shows comprehensive task information including: - - Basic task details and description - - Implementation details - - Subtasks (if they exist) - - Contextual suggested actions -- Recommended before starting any new development work -- Respects your project's dependency structure -- Ensures tasks are completed in the appropriate sequence -- Provides ready-to-use commands for common task actions - -## Viewing Specific Task Details - -- Run `get_task` / `task-master show <id>` to view a specific task. -- Use dot notation for subtasks: `task-master show 1.2` (shows subtask 2 of task 1) -- Displays comprehensive information similar to the next command, but for a specific task -- For parent tasks, shows all subtasks and their current status -- For subtasks, shows parent task information and relationship -- Provides contextual suggested actions appropriate for the specific task -- Useful for examining task details before implementation or checking status - -## Managing Task Dependencies - -- Use `add_dependency` / `task-master add-dependency --id=<id> --depends-on=<id>` to add a dependency. -- Use `remove_dependency` / `task-master remove-dependency --id=<id> --depends-on=<id>` to remove a dependency. -- The system prevents circular dependencies and duplicate dependency entries -- Dependencies are checked for existence before being added or removed -- Task files are automatically regenerated after dependency changes -- Dependencies are visualized with status indicators in task listings and files - -## Task Reorganization - -- Use `move_task` / `task-master move --from=<id> --to=<id>` to move tasks or subtasks within the hierarchy -- This command supports several use cases: - - Moving a standalone task to become a subtask (e.g., `--from=5 --to=7`) - - Moving a subtask to become a standalone task (e.g., `--from=5.2 --to=7`) - - Moving a subtask to a different parent (e.g., `--from=5.2 --to=7.3`) - - Reordering subtasks within the same parent (e.g., `--from=5.2 --to=5.4`) - - Moving a task to a new, non-existent ID position (e.g., `--from=5 --to=25`) - - Moving multiple tasks at once using comma-separated IDs (e.g., `--from=10,11,12 --to=16,17,18`) -- The system includes validation to prevent data loss: - - Allows moving to non-existent IDs by creating placeholder tasks - - Prevents moving to existing task IDs that have content (to avoid overwriting) - - Validates source tasks exist before attempting to move them -- The system maintains proper parent-child relationships and dependency integrity -- Task files are automatically regenerated after the move operation -- This provides greater flexibility in organizing and refining your task structure as project understanding evolves -- This is especially useful when dealing with potential merge conflicts arising from teams creating tasks on separate branches. Solve these conflicts very easily by moving your tasks and keeping theirs. - -## Iterative Subtask Implementation - -Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation: - -1. **Understand the Goal (Preparation):** - * Use `get_task` / `task-master show <subtaskId>` (see @`taskmaster.mdc`) to thoroughly understand the specific goals and requirements of the subtask. - -2. **Initial Exploration & Planning (Iteration 1):** - * This is the first attempt at creating a concrete implementation plan. - * Explore the codebase to identify the precise files, functions, and even specific lines of code that will need modification. - * Determine the intended code changes (diffs) and their locations. - * Gather *all* relevant details from this exploration phase. - -3. **Log the Plan:** - * Run `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<detailed plan>'`. - * Provide the *complete and detailed* findings from the exploration phase in the prompt. Include file paths, line numbers, proposed diffs, reasoning, and any potential challenges identified. Do not omit details. The goal is to create a rich, timestamped log within the subtask's `details`. - -4. **Verify the Plan:** - * Run `get_task` / `task-master show <subtaskId>` again to confirm that the detailed implementation plan has been successfully appended to the subtask's details. - -5. **Begin Implementation:** - * Set the subtask status using `set_task_status` / `task-master set-status --id=<subtaskId> --status=in-progress`. - * Start coding based on the logged plan. - -6. **Refine and Log Progress (Iteration 2+):** - * As implementation progresses, you will encounter challenges, discover nuances, or confirm successful approaches. - * **Before appending new information**: Briefly review the *existing* details logged in the subtask (using `get_task` or recalling from context) to ensure the update adds fresh insights and avoids redundancy. - * **Regularly** use `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<update details>\n- What worked...\n- What didn't work...'` to append new findings. - * **Crucially, log:** - * What worked ("fundamental truths" discovered). - * What didn't work and why (to avoid repeating mistakes). - * Specific code snippets or configurations that were successful. - * Decisions made, especially if confirmed with user input. - * Any deviations from the initial plan and the reasoning. - * The objective is to continuously enrich the subtask's details, creating a log of the implementation journey that helps the AI (and human developers) learn, adapt, and avoid repeating errors. - -7. **Review & Update Rules (Post-Implementation):** - * Once the implementation for the subtask is functionally complete, review all code changes and the relevant chat history. - * Identify any new or modified code patterns, conventions, or best practices established during the implementation. - * Create new or update existing rules following internal guidelines (previously linked to `cursor_rules.mdc` and `self_improve.mdc`). - -8. **Mark Task Complete:** - * After verifying the implementation and updating any necessary rules, mark the subtask as completed: `set_task_status` / `task-master set-status --id=<subtaskId> --status=done`. - -9. **Commit Changes (If using Git):** - * Stage the relevant code changes and any updated/new rule files (`git add .`). - * Craft a comprehensive Git commit message summarizing the work done for the subtask, including both code implementation and any rule adjustments. - * Execute the commit command directly in the terminal (e.g., `git commit -m 'feat(module): Implement feature X for subtask <subtaskId>\n\n- Details about changes...\n- Updated rule Y for pattern Z'`). - * Consider if a Changeset is needed according to internal versioning guidelines (previously linked to `changeset.mdc`). If so, run `npm run changeset`, stage the generated file, and amend the commit or create a new one. - -10. **Proceed to Next Subtask:** - * Identify the next subtask (e.g., using `next_task` / `task-master next`). - -## Code Analysis & Refactoring Techniques - -- **Top-Level Function Search**: - - Useful for understanding module structure or planning refactors. - - Use grep/ripgrep to find exported functions/constants: - `rg "export (async function|function|const) \w+"` or similar patterns. - - Can help compare functions between files during migrations or identify potential naming conflicts. - ---- -*This workflow provides a general guideline. Adapt it based on your specific project needs and team practices.* \ No newline at end of file diff --git a/.cursor/rules/taskmaster/taskmaster.mdc b/.cursor/rules/taskmaster/taskmaster.mdc deleted file mode 100644 index e9be2ae6..00000000 --- a/.cursor/rules/taskmaster/taskmaster.mdc +++ /dev/null @@ -1,558 +0,0 @@ ---- -description: Comprehensive reference for Taskmaster MCP tools and CLI commands. -globs: **/* -alwaysApply: true ---- - -# Taskmaster Tool & Command Reference - -This document provides a detailed reference for interacting with Taskmaster, covering both the recommended MCP tools, suitable for integrations like Cursor, and the corresponding `task-master` CLI commands, designed for direct user interaction or fallback. - -**Note:** For interacting with Taskmaster programmatically or via integrated tools, using the **MCP tools is strongly recommended** due to better performance, structured data, and error handling. The CLI commands serve as a user-friendly alternative and fallback. - -**Important:** Several MCP tools involve AI processing... The AI-powered tools include `parse_prd`, `analyze_project_complexity`, `update_subtask`, `update_task`, `update`, `expand_all`, `expand_task`, and `add_task`. - -**🏷️ Tagged Task Lists System:** Task Master now supports **tagged task lists** for multi-context task management. This allows you to maintain separate, isolated lists of tasks for different features, branches, or experiments. Existing projects are seamlessly migrated to use a default "master" tag. Most commands now support a `--tag <name>` flag to specify which context to operate on. If omitted, commands use the currently active tag. - ---- - -## Initialization & Setup - -### 1. Initialize Project (`init`) - -* **MCP Tool:** `initialize_project` -* **CLI Command:** `task-master init [options]` -* **Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project.` -* **Key CLI Options:** - * `--name <name>`: `Set the name for your project in Taskmaster's configuration.` - * `--description <text>`: `Provide a brief description for your project.` - * `--version <version>`: `Set the initial version for your project, e.g., '0.1.0'.` - * `-y, --yes`: `Initialize Taskmaster quickly using default settings without interactive prompts.` -* **Usage:** Run this once at the beginning of a new project. -* **MCP Variant Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project by running the 'task-master init' command.` -* **Key MCP Parameters/Options:** - * `projectName`: `Set the name for your project.` (CLI: `--name <name>`) - * `projectDescription`: `Provide a brief description for your project.` (CLI: `--description <text>`) - * `projectVersion`: `Set the initial version for your project, e.g., '0.1.0'.` (CLI: `--version <version>`) - * `authorName`: `Author name.` (CLI: `--author <author>`) - * `skipInstall`: `Skip installing dependencies. Default is false.` (CLI: `--skip-install`) - * `addAliases`: `Add shell aliases tm and taskmaster. Default is false.` (CLI: `--aliases`) - * `yes`: `Skip prompts and use defaults/provided arguments. Default is false.` (CLI: `-y, --yes`) -* **Usage:** Run this once at the beginning of a new project, typically via an integrated tool like Cursor. Operates on the current working directory of the MCP server. -* **Important:** Once complete, you *MUST* parse a prd in order to generate tasks. There will be no tasks files until then. The next step after initializing should be to create a PRD using the example PRD in .taskmaster/templates/example_prd.txt. -* **Tagging:** Use the `--tag` option to parse the PRD into a specific, non-default tag context. If the tag doesn't exist, it will be created automatically. Example: `task-master parse-prd spec.txt --tag=new-feature`. - -### 2. Parse PRD (`parse_prd`) - -* **MCP Tool:** `parse_prd` -* **CLI Command:** `task-master parse-prd [file] [options]` -* **Description:** `Parse a Product Requirements Document, PRD, or text file with Taskmaster to automatically generate an initial set of tasks in tasks.json.` -* **Key Parameters/Options:** - * `input`: `Path to your PRD or requirements text file that Taskmaster should parse for tasks.` (CLI: `[file]` positional or `-i, --input <file>`) - * `output`: `Specify where Taskmaster should save the generated 'tasks.json' file. Defaults to '.taskmaster/tasks/tasks.json'.` (CLI: `-o, --output <file>`) - * `numTasks`: `Approximate number of top-level tasks Taskmaster should aim to generate from the document.` (CLI: `-n, --num-tasks <number>`) - * `force`: `Use this to allow Taskmaster to overwrite an existing 'tasks.json' without asking for confirmation.` (CLI: `-f, --force`) -* **Usage:** Useful for bootstrapping a project from an existing requirements document. -* **Notes:** Task Master will strictly adhere to any specific requirements mentioned in the PRD, such as libraries, database schemas, frameworks, tech stacks, etc., while filling in any gaps where the PRD isn't fully specified. Tasks are designed to provide the most direct implementation path while avoiding over-engineering. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. If the user does not have a PRD, suggest discussing their idea and then use the example PRD in `.taskmaster/templates/example_prd.txt` as a template for creating the PRD based on their idea, for use with `parse-prd`. - ---- - -## AI Model Configuration - -### 2. Manage Models (`models`) -* **MCP Tool:** `models` -* **CLI Command:** `task-master models [options]` -* **Description:** `View the current AI model configuration or set specific models for different roles (main, research, fallback). Allows setting custom model IDs for Ollama and OpenRouter.` -* **Key MCP Parameters/Options:** - * `setMain <model_id>`: `Set the primary model ID for task generation/updates.` (CLI: `--set-main <model_id>`) - * `setResearch <model_id>`: `Set the model ID for research-backed operations.` (CLI: `--set-research <model_id>`) - * `setFallback <model_id>`: `Set the model ID to use if the primary fails.` (CLI: `--set-fallback <model_id>`) - * `ollama <boolean>`: `Indicates the set model ID is a custom Ollama model.` (CLI: `--ollama`) - * `openrouter <boolean>`: `Indicates the set model ID is a custom OpenRouter model.` (CLI: `--openrouter`) - * `listAvailableModels <boolean>`: `If true, lists available models not currently assigned to a role.` (CLI: No direct equivalent; CLI lists available automatically) - * `projectRoot <string>`: `Optional. Absolute path to the project root directory.` (CLI: Determined automatically) -* **Key CLI Options:** - * `--set-main <model_id>`: `Set the primary model.` - * `--set-research <model_id>`: `Set the research model.` - * `--set-fallback <model_id>`: `Set the fallback model.` - * `--ollama`: `Specify that the provided model ID is for Ollama (use with --set-*).` - * `--openrouter`: `Specify that the provided model ID is for OpenRouter (use with --set-*). Validates against OpenRouter API.` - * `--bedrock`: `Specify that the provided model ID is for AWS Bedrock (use with --set-*).` - * `--setup`: `Run interactive setup to configure models, including custom Ollama/OpenRouter IDs.` -* **Usage (MCP):** Call without set flags to get current config. Use `setMain`, `setResearch`, or `setFallback` with a valid model ID to update the configuration. Use `listAvailableModels: true` to get a list of unassigned models. To set a custom model, provide the model ID and set `ollama: true` or `openrouter: true`. -* **Usage (CLI):** Run without flags to view current configuration and available models. Use set flags to update specific roles. Use `--setup` for guided configuration, including custom models. To set a custom model via flags, use `--set-<role>=<model_id>` along with either `--ollama` or `--openrouter`. -* **Notes:** Configuration is stored in `.taskmaster/config.json` in the project root. This command/tool modifies that file. Use `listAvailableModels` or `task-master models` to see internally supported models. OpenRouter custom models are validated against their live API. Ollama custom models are not validated live. -* **API note:** API keys for selected AI providers (based on their model) need to exist in the mcp.json file to be accessible in MCP context. The API keys must be present in the local .env file for the CLI to be able to read them. -* **Model costs:** The costs in supported models are expressed in dollars. An input/output value of 3 is $3.00. A value of 0.8 is $0.80. -* **Warning:** DO NOT MANUALLY EDIT THE .taskmaster/config.json FILE. Use the included commands either in the MCP or CLI format as needed. Always prioritize MCP tools when available and use the CLI as a fallback. - ---- - -## Task Listing & Viewing - -### 3. Get Tasks (`get_tasks`) - -* **MCP Tool:** `get_tasks` -* **CLI Command:** `task-master list [options]` -* **Description:** `List your Taskmaster tasks, optionally filtering by status and showing subtasks.` -* **Key Parameters/Options:** - * `status`: `Show only Taskmaster tasks matching this status (or multiple statuses, comma-separated), e.g., 'pending' or 'done,in-progress'.` (CLI: `-s, --status <status>`) - * `withSubtasks`: `Include subtasks indented under their parent tasks in the list.` (CLI: `--with-subtasks`) - * `tag`: `Specify which tag context to list tasks from. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Get an overview of the project status, often used at the start of a work session. - -### 4. Get Next Task (`next_task`) - -* **MCP Tool:** `next_task` -* **CLI Command:** `task-master next [options]` -* **Description:** `Ask Taskmaster to show the next available task you can work on, based on status and completed dependencies.` -* **Key Parameters/Options:** - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) - * `tag`: `Specify which tag context to use. Defaults to the current active tag.` (CLI: `--tag <name>`) -* **Usage:** Identify what to work on next according to the plan. - -### 5. Get Task Details (`get_task`) - -* **MCP Tool:** `get_task` -* **CLI Command:** `task-master show [id] [options]` -* **Description:** `Display detailed information for one or more specific Taskmaster tasks or subtasks by ID.` -* **Key Parameters/Options:** - * `id`: `Required. The ID of the Taskmaster task (e.g., '15'), subtask (e.g., '15.2'), or a comma-separated list of IDs ('1,5,10.2') you want to view.` (CLI: `[id]` positional or `-i, --id <id>`) - * `tag`: `Specify which tag context to get the task(s) from. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Understand the full details for a specific task. When multiple IDs are provided, a summary table is shown. -* **CRITICAL INFORMATION** If you need to collect information from multiple tasks, use comma-separated IDs (i.e. 1,2,3) to receive an array of tasks. Do not needlessly get tasks one at a time if you need to get many as that is wasteful. - ---- - -## Task Creation & Modification - -### 6. Add Task (`add_task`) - -* **MCP Tool:** `add_task` -* **CLI Command:** `task-master add-task [options]` -* **Description:** `Add a new task to Taskmaster by describing it; AI will structure it.` -* **Key Parameters/Options:** - * `prompt`: `Required. Describe the new task you want Taskmaster to create, e.g., "Implement user authentication using JWT".` (CLI: `-p, --prompt <text>`) - * `dependencies`: `Specify the IDs of any Taskmaster tasks that must be completed before this new one can start, e.g., '12,14'.` (CLI: `-d, --dependencies <ids>`) - * `priority`: `Set the priority for the new task: 'high', 'medium', or 'low'. Default is 'medium'.` (CLI: `--priority <priority>`) - * `research`: `Enable Taskmaster to use the research role for potentially more informed task creation.` (CLI: `-r, --research`) - * `tag`: `Specify which tag context to add the task to. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Quickly add newly identified tasks during development. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 7. Add Subtask (`add_subtask`) - -* **MCP Tool:** `add_subtask` -* **CLI Command:** `task-master add-subtask [options]` -* **Description:** `Add a new subtask to a Taskmaster parent task, or convert an existing task into a subtask.` -* **Key Parameters/Options:** - * `id` / `parent`: `Required. The ID of the Taskmaster task that will be the parent.` (MCP: `id`, CLI: `-p, --parent <id>`) - * `taskId`: `Use this if you want to convert an existing top-level Taskmaster task into a subtask of the specified parent.` (CLI: `-i, --task-id <id>`) - * `title`: `Required if not using taskId. The title for the new subtask Taskmaster should create.` (CLI: `-t, --title <title>`) - * `description`: `A brief description for the new subtask.` (CLI: `-d, --description <text>`) - * `details`: `Provide implementation notes or details for the new subtask.` (CLI: `--details <text>`) - * `dependencies`: `Specify IDs of other tasks or subtasks, e.g., '15' or '16.1', that must be done before this new subtask.` (CLI: `--dependencies <ids>`) - * `status`: `Set the initial status for the new subtask. Default is 'pending'.` (CLI: `-s, --status <status>`) - * `generate`: `Enable Taskmaster to regenerate markdown task files after adding the subtask.` (CLI: `--generate`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Break down tasks manually or reorganize existing tasks. - -### 8. Update Tasks (`update`) - -* **MCP Tool:** `update` -* **CLI Command:** `task-master update [options]` -* **Description:** `Update multiple upcoming tasks in Taskmaster based on new context or changes, starting from a specific task ID.` -* **Key Parameters/Options:** - * `from`: `Required. The ID of the first task Taskmaster should update. All tasks with this ID or higher that are not 'done' will be considered.` (CLI: `--from <id>`) - * `prompt`: `Required. Explain the change or new context for Taskmaster to apply to the tasks, e.g., "We are now using React Query instead of Redux Toolkit for data fetching".` (CLI: `-p, --prompt <text>`) - * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Handle significant implementation changes or pivots that affect multiple future tasks. Example CLI: `task-master update --from='18' --prompt='Switching to React Query.\nNeed to refactor data fetching...'` -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 9. Update Task (`update_task`) - -* **MCP Tool:** `update_task` -* **CLI Command:** `task-master update-task [options]` -* **Description:** `Modify a specific Taskmaster task by ID, incorporating new information or changes. By default, this replaces the existing task details.` -* **Key Parameters/Options:** - * `id`: `Required. The specific ID of the Taskmaster task, e.g., '15', you want to update.` (CLI: `-i, --id <id>`) - * `prompt`: `Required. Explain the specific changes or provide the new information Taskmaster should incorporate into this task.` (CLI: `-p, --prompt <text>`) - * `append`: `If true, appends the prompt content to the task's details with a timestamp, rather than replacing them. Behaves like update-subtask.` (CLI: `--append`) - * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`) - * `tag`: `Specify which tag context the task belongs to. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Refine a specific task based on new understanding. Use `--append` to log progress without creating subtasks. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 10. Update Subtask (`update_subtask`) - -* **MCP Tool:** `update_subtask` -* **CLI Command:** `task-master update-subtask [options]` -* **Description:** `Append timestamped notes or details to a specific Taskmaster subtask without overwriting existing content. Intended for iterative implementation logging.` -* **Key Parameters/Options:** - * `id`: `Required. The ID of the Taskmaster subtask, e.g., '5.2', to update with new information.` (CLI: `-i, --id <id>`) - * `prompt`: `Required. The information, findings, or progress notes to append to the subtask's details with a timestamp.` (CLI: `-p, --prompt <text>`) - * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`) - * `tag`: `Specify which tag context the subtask belongs to. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Log implementation progress, findings, and discoveries during subtask development. Each update is timestamped and appended to preserve the implementation journey. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 11. Set Task Status (`set_task_status`) - -* **MCP Tool:** `set_task_status` -* **CLI Command:** `task-master set-status [options]` -* **Description:** `Update the status of one or more Taskmaster tasks or subtasks, e.g., 'pending', 'in-progress', 'done'.` -* **Key Parameters/Options:** - * `id`: `Required. The ID(s) of the Taskmaster task(s) or subtask(s), e.g., '15', '15.2', or '16,17.1', to update.` (CLI: `-i, --id <id>`) - * `status`: `Required. The new status to set, e.g., 'done', 'pending', 'in-progress', 'review', 'cancelled'.` (CLI: `-s, --status <status>`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Mark progress as tasks move through the development cycle. - -### 12. Remove Task (`remove_task`) - -* **MCP Tool:** `remove_task` -* **CLI Command:** `task-master remove-task [options]` -* **Description:** `Permanently remove a task or subtask from the Taskmaster tasks list.` -* **Key Parameters/Options:** - * `id`: `Required. The ID of the Taskmaster task, e.g., '5', or subtask, e.g., '5.2', to permanently remove.` (CLI: `-i, --id <id>`) - * `yes`: `Skip the confirmation prompt and immediately delete the task.` (CLI: `-y, --yes`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Permanently delete tasks or subtasks that are no longer needed in the project. -* **Notes:** Use with caution as this operation cannot be undone. Consider using 'blocked', 'cancelled', or 'deferred' status instead if you just want to exclude a task from active planning but keep it for reference. The command automatically cleans up dependency references in other tasks. - ---- - -## Task Structure & Breakdown - -### 13. Expand Task (`expand_task`) - -* **MCP Tool:** `expand_task` -* **CLI Command:** `task-master expand [options]` -* **Description:** `Use Taskmaster's AI to break down a complex task into smaller, manageable subtasks. Appends subtasks by default.` -* **Key Parameters/Options:** - * `id`: `The ID of the specific Taskmaster task you want to break down into subtasks.` (CLI: `-i, --id <id>`) - * `num`: `Optional: Suggests how many subtasks Taskmaster should aim to create. Uses complexity analysis/defaults otherwise.` (CLI: `-n, --num <number>`) - * `research`: `Enable Taskmaster to use the research role for more informed subtask generation. Requires appropriate API key.` (CLI: `-r, --research`) - * `prompt`: `Optional: Provide extra context or specific instructions to Taskmaster for generating the subtasks.` (CLI: `-p, --prompt <text>`) - * `force`: `Optional: If true, clear existing subtasks before generating new ones. Default is false (append).` (CLI: `--force`) - * `tag`: `Specify which tag context the task belongs to. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Generate a detailed implementation plan for a complex task before starting coding. Automatically uses complexity report recommendations if available and `num` is not specified. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 14. Expand All Tasks (`expand_all`) - -* **MCP Tool:** `expand_all` -* **CLI Command:** `task-master expand --all [options]` (Note: CLI uses the `expand` command with the `--all` flag) -* **Description:** `Tell Taskmaster to automatically expand all eligible pending/in-progress tasks based on complexity analysis or defaults. Appends subtasks by default.` -* **Key Parameters/Options:** - * `num`: `Optional: Suggests how many subtasks Taskmaster should aim to create per task.` (CLI: `-n, --num <number>`) - * `research`: `Enable research role for more informed subtask generation. Requires appropriate API key.` (CLI: `-r, --research`) - * `prompt`: `Optional: Provide extra context for Taskmaster to apply generally during expansion.` (CLI: `-p, --prompt <text>`) - * `force`: `Optional: If true, clear existing subtasks before generating new ones for each eligible task. Default is false (append).` (CLI: `--force`) - * `tag`: `Specify which tag context to expand. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Useful after initial task generation or complexity analysis to break down multiple tasks at once. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 15. Clear Subtasks (`clear_subtasks`) - -* **MCP Tool:** `clear_subtasks` -* **CLI Command:** `task-master clear-subtasks [options]` -* **Description:** `Remove all subtasks from one or more specified Taskmaster parent tasks.` -* **Key Parameters/Options:** - * `id`: `The ID(s) of the Taskmaster parent task(s) whose subtasks you want to remove, e.g., '15' or '16,18'. Required unless using 'all'.` (CLI: `-i, --id <ids>`) - * `all`: `Tell Taskmaster to remove subtasks from all parent tasks.` (CLI: `--all`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Used before regenerating subtasks with `expand_task` if the previous breakdown needs replacement. - -### 16. Remove Subtask (`remove_subtask`) - -* **MCP Tool:** `remove_subtask` -* **CLI Command:** `task-master remove-subtask [options]` -* **Description:** `Remove a subtask from its Taskmaster parent, optionally converting it into a standalone task.` -* **Key Parameters/Options:** - * `id`: `Required. The ID(s) of the Taskmaster subtask(s) to remove, e.g., '15.2' or '16.1,16.3'.` (CLI: `-i, --id <id>`) - * `convert`: `If used, Taskmaster will turn the subtask into a regular top-level task instead of deleting it.` (CLI: `-c, --convert`) - * `generate`: `Enable Taskmaster to regenerate markdown task files after removing the subtask.` (CLI: `--generate`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Delete unnecessary subtasks or promote a subtask to a top-level task. - -### 17. Move Task (`move_task`) - -* **MCP Tool:** `move_task` -* **CLI Command:** `task-master move [options]` -* **Description:** `Move a task or subtask to a new position within the task hierarchy.` -* **Key Parameters/Options:** - * `from`: `Required. ID of the task/subtask to move (e.g., "5" or "5.2"). Can be comma-separated for multiple tasks.` (CLI: `--from <id>`) - * `to`: `Required. ID of the destination (e.g., "7" or "7.3"). Must match the number of source IDs if comma-separated.` (CLI: `--to <id>`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Reorganize tasks by moving them within the hierarchy. Supports various scenarios like: - * Moving a task to become a subtask - * Moving a subtask to become a standalone task - * Moving a subtask to a different parent - * Reordering subtasks within the same parent - * Moving a task to a new, non-existent ID (automatically creates placeholders) - * Moving multiple tasks at once with comma-separated IDs -* **Validation Features:** - * Allows moving tasks to non-existent destination IDs (creates placeholder tasks) - * Prevents moving to existing task IDs that already have content (to avoid overwriting) - * Validates that source tasks exist before attempting to move them - * Maintains proper parent-child relationships -* **Example CLI:** `task-master move --from=5.2 --to=7.3` to move subtask 5.2 to become subtask 7.3. -* **Example Multi-Move:** `task-master move --from=10,11,12 --to=16,17,18` to move multiple tasks to new positions. -* **Common Use:** Resolving merge conflicts in tasks.json when multiple team members create tasks on different branches. - ---- - -## Dependency Management - -### 18. Add Dependency (`add_dependency`) - -* **MCP Tool:** `add_dependency` -* **CLI Command:** `task-master add-dependency [options]` -* **Description:** `Define a dependency in Taskmaster, making one task a prerequisite for another.` -* **Key Parameters/Options:** - * `id`: `Required. The ID of the Taskmaster task that will depend on another.` (CLI: `-i, --id <id>`) - * `dependsOn`: `Required. The ID of the Taskmaster task that must be completed first, the prerequisite.` (CLI: `-d, --depends-on <id>`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <path>`) -* **Usage:** Establish the correct order of execution between tasks. - -### 19. Remove Dependency (`remove_dependency`) - -* **MCP Tool:** `remove_dependency` -* **CLI Command:** `task-master remove-dependency [options]` -* **Description:** `Remove a dependency relationship between two Taskmaster tasks.` -* **Key Parameters/Options:** - * `id`: `Required. The ID of the Taskmaster task you want to remove a prerequisite from.` (CLI: `-i, --id <id>`) - * `dependsOn`: `Required. The ID of the Taskmaster task that should no longer be a prerequisite.` (CLI: `-d, --depends-on <id>`) - * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Update task relationships when the order of execution changes. - -### 20. Validate Dependencies (`validate_dependencies`) - -* **MCP Tool:** `validate_dependencies` -* **CLI Command:** `task-master validate-dependencies [options]` -* **Description:** `Check your Taskmaster tasks for dependency issues (like circular references or links to non-existent tasks) without making changes.` -* **Key Parameters/Options:** - * `tag`: `Specify which tag context to validate. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Audit the integrity of your task dependencies. - -### 21. Fix Dependencies (`fix_dependencies`) - -* **MCP Tool:** `fix_dependencies` -* **CLI Command:** `task-master fix-dependencies [options]` -* **Description:** `Automatically fix dependency issues (like circular references or links to non-existent tasks) in your Taskmaster tasks.` -* **Key Parameters/Options:** - * `tag`: `Specify which tag context to fix dependencies in. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Clean up dependency errors automatically. - ---- - -## Analysis & Reporting - -### 22. Analyze Project Complexity (`analyze_project_complexity`) - -* **MCP Tool:** `analyze_project_complexity` -* **CLI Command:** `task-master analyze-complexity [options]` -* **Description:** `Have Taskmaster analyze your tasks to determine their complexity and suggest which ones need to be broken down further.` -* **Key Parameters/Options:** - * `output`: `Where to save the complexity analysis report. Default is '.taskmaster/reports/task-complexity-report.json' (or '..._tagname.json' if a tag is used).` (CLI: `-o, --output <file>`) - * `threshold`: `The minimum complexity score (1-10) that should trigger a recommendation to expand a task.` (CLI: `-t, --threshold <number>`) - * `research`: `Enable research role for more accurate complexity analysis. Requires appropriate API key.` (CLI: `-r, --research`) - * `tag`: `Specify which tag context to analyze. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Used before breaking down tasks to identify which ones need the most attention. -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. - -### 23. View Complexity Report (`complexity_report`) - -* **MCP Tool:** `complexity_report` -* **CLI Command:** `task-master complexity-report [options]` -* **Description:** `Display the task complexity analysis report in a readable format.` -* **Key Parameters/Options:** - * `tag`: `Specify which tag context to show the report for. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to the complexity report (default: '.taskmaster/reports/task-complexity-report.json').` (CLI: `-f, --file <file>`) -* **Usage:** Review and understand the complexity analysis results after running analyze-complexity. - ---- - -## File Management - -### 24. Generate Task Files (`generate`) - -* **MCP Tool:** `generate` -* **CLI Command:** `task-master generate [options]` -* **Description:** `Create or update individual Markdown files for each task based on your tasks.json.` -* **Key Parameters/Options:** - * `output`: `The directory where Taskmaster should save the task files (default: in a 'tasks' directory).` (CLI: `-o, --output <directory>`) - * `tag`: `Specify which tag context to generate files for. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) -* **Usage:** Run this after making changes to tasks.json to keep individual task files up to date. This command is now manual and no longer runs automatically. - ---- - -## AI-Powered Research - -### 25. Research (`research`) - -* **MCP Tool:** `research` -* **CLI Command:** `task-master research [options]` -* **Description:** `Perform AI-powered research queries with project context to get fresh, up-to-date information beyond the AI's knowledge cutoff.` -* **Key Parameters/Options:** - * `query`: `Required. Research query/prompt (e.g., "What are the latest best practices for React Query v5?").` (CLI: `[query]` positional or `-q, --query <text>`) - * `taskIds`: `Comma-separated list of task/subtask IDs from the current tag context (e.g., "15,16.2,17").` (CLI: `-i, --id <ids>`) - * `filePaths`: `Comma-separated list of file paths for context (e.g., "src/api.js,docs/readme.md").` (CLI: `-f, --files <paths>`) - * `customContext`: `Additional custom context text to include in the research.` (CLI: `-c, --context <text>`) - * `includeProjectTree`: `Include project file tree structure in context (default: false).` (CLI: `--tree`) - * `detailLevel`: `Detail level for the research response: 'low', 'medium', 'high' (default: medium).` (CLI: `--detail <level>`) - * `saveTo`: `Task or subtask ID (e.g., "15", "15.2") to automatically save the research conversation to.` (CLI: `--save-to <id>`) - * `saveFile`: `If true, saves the research conversation to a markdown file in '.taskmaster/docs/research/'.` (CLI: `--save-file`) - * `noFollowup`: `Disables the interactive follow-up question menu in the CLI.` (CLI: `--no-followup`) - * `tag`: `Specify which tag context to use for task-based context gathering. Defaults to the current active tag.` (CLI: `--tag <name>`) - * `projectRoot`: `The directory of the project. Must be an absolute path.` (CLI: Determined automatically) -* **Usage:** **This is a POWERFUL tool that agents should use FREQUENTLY** to: - * Get fresh information beyond knowledge cutoff dates - * Research latest best practices, library updates, security patches - * Find implementation examples for specific technologies - * Validate approaches against current industry standards - * Get contextual advice based on project files and tasks -* **When to Consider Using Research:** - * **Before implementing any task** - Research current best practices - * **When encountering new technologies** - Get up-to-date implementation guidance (libraries, apis, etc) - * **For security-related tasks** - Find latest security recommendations - * **When updating dependencies** - Research breaking changes and migration guides - * **For performance optimization** - Get current performance best practices - * **When debugging complex issues** - Research known solutions and workarounds -* **Research + Action Pattern:** - * Use `research` to gather fresh information - * Use `update_subtask` to commit findings with timestamps - * Use `update_task` to incorporate research into task details - * Use `add_task` with research flag for informed task creation -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. The research provides FRESH data beyond the AI's training cutoff, making it invaluable for current best practices and recent developments. - ---- - -## Tag Management - -This new suite of commands allows you to manage different task contexts (tags). - -### 26. List Tags (`tags`) - -* **MCP Tool:** `list_tags` -* **CLI Command:** `task-master tags [options]` -* **Description:** `List all available tags with task counts, completion status, and other metadata.` -* **Key Parameters/Options:** - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) - * `--show-metadata`: `Include detailed metadata in the output (e.g., creation date, description).` (CLI: `--show-metadata`) - -### 27. Add Tag (`add_tag`) - -* **MCP Tool:** `add_tag` -* **CLI Command:** `task-master add-tag <tagName> [options]` -* **Description:** `Create a new, empty tag context, or copy tasks from another tag.` -* **Key Parameters/Options:** - * `tagName`: `Name of the new tag to create (alphanumeric, hyphens, underscores).` (CLI: `<tagName>` positional) - * `--from-branch`: `Creates a tag with a name derived from the current git branch, ignoring the <tagName> argument.` (CLI: `--from-branch`) - * `--copy-from-current`: `Copy tasks from the currently active tag to the new tag.` (CLI: `--copy-from-current`) - * `--copy-from <tag>`: `Copy tasks from a specific source tag to the new tag.` (CLI: `--copy-from <tag>`) - * `--description <text>`: `Provide an optional description for the new tag.` (CLI: `-d, --description <text>`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) - -### 28. Delete Tag (`delete_tag`) - -* **MCP Tool:** `delete_tag` -* **CLI Command:** `task-master delete-tag <tagName> [options]` -* **Description:** `Permanently delete a tag and all of its associated tasks.` -* **Key Parameters/Options:** - * `tagName`: `Name of the tag to delete.` (CLI: `<tagName>` positional) - * `--yes`: `Skip the confirmation prompt.` (CLI: `-y, --yes`) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) - -### 29. Use Tag (`use_tag`) - -* **MCP Tool:** `use_tag` -* **CLI Command:** `task-master use-tag <tagName>` -* **Description:** `Switch your active task context to a different tag.` -* **Key Parameters/Options:** - * `tagName`: `Name of the tag to switch to.` (CLI: `<tagName>` positional) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) - -### 30. Rename Tag (`rename_tag`) - -* **MCP Tool:** `rename_tag` -* **CLI Command:** `task-master rename-tag <oldName> <newName>` -* **Description:** `Rename an existing tag.` -* **Key Parameters/Options:** - * `oldName`: `The current name of the tag.` (CLI: `<oldName>` positional) - * `newName`: `The new name for the tag.` (CLI: `<newName>` positional) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <file>`) - -### 31. Copy Tag (`copy_tag`) - -* **MCP Tool:** `copy_tag` -* **CLI Command:** `task-master copy-tag <sourceName> <targetName> [options]` -* **Description:** `Copy an entire tag context, including all its tasks and metadata, to a new tag.` -* **Key Parameters/Options:** - * `sourceName`: `Name of the tag to copy from.` (CLI: `<sourceName>` positional) - * `targetName`: `Name of the new tag to create.` (CLI: `<targetName>` positional) - * `--description <text>`: `Optional description for the new tag.` (CLI: `-d, --description <text>`) - ---- - -## Miscellaneous - -### 32. Sync Readme (`sync-readme`) -- experimental - -* **MCP Tool:** N/A -* **CLI Command:** `task-master sync-readme [options]` -* **Description:** `Exports your task list to your project's README.md file, useful for showcasing progress.` -* **Key Parameters/Options:** - * `status`: `Filter tasks by status (e.g., 'pending', 'done').` (CLI: `-s, --status <status>`) - * `withSubtasks`: `Include subtasks in the export.` (CLI: `--with-subtasks`) - * `tag`: `Specify which tag context to export from. Defaults to the current active tag.` (CLI: `--tag <name>`) - ---- - -## Environment Variables Configuration (Updated) - -Taskmaster primarily uses the **`.taskmaster/config.json`** file (in project root) for configuration (models, parameters, logging level, etc.), managed via `task-master models --setup`. - -Environment variables are used **only** for sensitive API keys related to AI providers and specific overrides like the Ollama base URL: - -* **API Keys (Required for corresponding provider):** - * `ANTHROPIC_API_KEY` - * `PERPLEXITY_API_KEY` - * `OPENAI_API_KEY` - * `GOOGLE_API_KEY` - * `MISTRAL_API_KEY` - * `AZURE_OPENAI_API_KEY` (Requires `AZURE_OPENAI_ENDPOINT` too) - * `OPENROUTER_API_KEY` - * `XAI_API_KEY` - * `OLLAMA_API_KEY` (Requires `OLLAMA_BASE_URL` too) -* **Endpoints (Optional/Provider Specific inside .taskmaster/config.json):** - * `AZURE_OPENAI_ENDPOINT` - * `OLLAMA_BASE_URL` (Default: `http://localhost:11434/api`) - -**Set API keys** in your **`.env`** file in the project root (for CLI use) or within the `env` section of your **`.cursor/mcp.json`** file (for MCP/Cursor integration). All other settings (model choice, max tokens, temperature, log level, custom endpoints) are managed in `.taskmaster/config.json` via `task-master models` command or `models` MCP tool. - ---- - -For details on how these commands fit into the development process, see the [dev_workflow.mdc](mdc:.cursor/rules/taskmaster/dev_workflow.mdc). \ No newline at end of file diff --git a/.env.example b/.env.example deleted file mode 100644 index 60bd23e8..00000000 --- a/.env.example +++ /dev/null @@ -1,12 +0,0 @@ -# API Keys (Required to enable respective provider) -ANTHROPIC_API_KEY="your_anthropic_api_key_here" # Required: Format: sk-ant-api03-... -PERPLEXITY_API_KEY="your_perplexity_api_key_here" # Optional: Format: pplx-... -OPENAI_API_KEY="your_openai_api_key_here" # Optional, for OpenAI models. Format: sk-proj-... -GOOGLE_API_KEY="your_google_api_key_here" # Optional, for Google Gemini models. -MISTRAL_API_KEY="your_mistral_key_here" # Optional, for Mistral AI models. -XAI_API_KEY="YOUR_XAI_KEY_HERE" # Optional, for xAI AI models. -GROQ_API_KEY="YOUR_GROQ_KEY_HERE" # Optional, for Groq models. -OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY_HERE" # Optional, for OpenRouter models. -AZURE_OPENAI_API_KEY="your_azure_key_here" # Optional, for Azure OpenAI models (requires endpoint in .taskmaster/config.json). -OLLAMA_API_KEY="your_ollama_api_key_here" # Optional: For remote Ollama servers that require authentication. -GITHUB_API_KEY="your_github_api_key_here" # Optional: For GitHub import/export features. Format: ghp_... or github_pat_... \ No newline at end of file diff --git a/.github/workflows/SyntaxKit.yml b/.github/workflows/SyntaxKit.yml index ca966bde..79e05f86 100644 --- a/.github/workflows/SyntaxKit.yml +++ b/.github/workflows/SyntaxKit.yml @@ -11,9 +11,6 @@ on: - 'LICENSE' - '.github/ISSUE_TEMPLATE/**' pull_request: - branches: - - main - - 'v[0-9]*.[0-9]*.[0-9]*' paths-ignore: - '**.md' - 'Docs/**' diff --git a/.github/workflows/check-unsafe-flags.yml b/.github/workflows/check-unsafe-flags.yml index 348f4430..88428abb 100644 --- a/.github/workflows/check-unsafe-flags.yml +++ b/.github/workflows/check-unsafe-flags.yml @@ -4,7 +4,6 @@ on: push: branches: [ "main" ] pull_request: - branches: [ "main" ] jobs: dump-package-check: diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index aa09eaf8..3e0d8d56 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -21,8 +21,6 @@ on: - 'LICENSE' - '.github/ISSUE_TEMPLATE/**' pull_request: - # The branches below must be a subset of the branches above - branches: [ "main" ] paths-ignore: - '**.md' - 'Docs/**' diff --git a/.mcp.json b/.mcp.json deleted file mode 100644 index a033e370..00000000 --- a/.mcp.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "mcpServers": { - "task-master-ai": { - "type": "stdio", - "command": "npx", - "args": [ - "-y", - "--package=task-master-ai", - "task-master-ai" - ], - "env": { - "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE", - "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE", - "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE", - "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE", - "XAI_API_KEY": "YOUR_XAI_KEY_HERE", - "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE", - "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE", - "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE", - "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE" - } - } - } -} diff --git a/.swiftlint.yml b/.swiftlint.yml index 43ef0b6a..3bb24f5e 100644 --- a/.swiftlint.yml +++ b/.swiftlint.yml @@ -127,6 +127,7 @@ excluded: - Macros - Sources/SyntaxKit/Parser - Sources/SyntaxKit/Documentation.docc/Tutorials/Resources + - Sources/ClaudeKit/Generated indentation_width: indentation_width: 2 file_name: diff --git a/.taskmaster/CLAUDE.md b/.taskmaster/CLAUDE.md deleted file mode 100644 index 6f664815..00000000 --- a/.taskmaster/CLAUDE.md +++ /dev/null @@ -1,417 +0,0 @@ -# Task Master AI - Agent Integration Guide - -## Essential Commands - -### Core Workflow Commands - -```bash -# Project Setup -task-master init # Initialize Task Master in current project -task-master parse-prd .taskmaster/docs/prd.txt # Generate tasks from PRD document -task-master models --setup # Configure AI models interactively - -# Daily Development Workflow -task-master list # Show all tasks with status -task-master next # Get next available task to work on -task-master show <id> # View detailed task information (e.g., task-master show 1.2) -task-master set-status --id=<id> --status=done # Mark task complete - -# Task Management -task-master add-task --prompt="description" --research # Add new task with AI assistance -task-master expand --id=<id> --research --force # Break task into subtasks -task-master update-task --id=<id> --prompt="changes" # Update specific task -task-master update --from=<id> --prompt="changes" # Update multiple tasks from ID onwards -task-master update-subtask --id=<id> --prompt="notes" # Add implementation notes to subtask - -# Analysis & Planning -task-master analyze-complexity --research # Analyze task complexity -task-master complexity-report # View complexity analysis -task-master expand --all --research # Expand all eligible tasks - -# Dependencies & Organization -task-master add-dependency --id=<id> --depends-on=<id> # Add task dependency -task-master move --from=<id> --to=<id> # Reorganize task hierarchy -task-master validate-dependencies # Check for dependency issues -task-master generate # Update task markdown files (usually auto-called) -``` - -## Key Files & Project Structure - -### Core Files - -- `.taskmaster/tasks/tasks.json` - Main task data file (auto-managed) -- `.taskmaster/config.json` - AI model configuration (use `task-master models` to modify) -- `.taskmaster/docs/prd.txt` - Product Requirements Document for parsing -- `.taskmaster/tasks/*.txt` - Individual task files (auto-generated from tasks.json) -- `.env` - API keys for CLI usage - -### Claude Code Integration Files - -- `CLAUDE.md` - Auto-loaded context for Claude Code (this file) -- `.claude/settings.json` - Claude Code tool allowlist and preferences -- `.claude/commands/` - Custom slash commands for repeated workflows -- `.mcp.json` - MCP server configuration (project-specific) - -### Directory Structure - -``` -project/ -├── .taskmaster/ -│ ├── tasks/ # Task files directory -│ │ ├── tasks.json # Main task database -│ │ ├── task-1.md # Individual task files -│ │ └── task-2.md -│ ├── docs/ # Documentation directory -│ │ ├── prd.txt # Product requirements -│ ├── reports/ # Analysis reports directory -│ │ └── task-complexity-report.json -│ ├── templates/ # Template files -│ │ └── example_prd.txt # Example PRD template -│ └── config.json # AI models & settings -├── .claude/ -│ ├── settings.json # Claude Code configuration -│ └── commands/ # Custom slash commands -├── .env # API keys -├── .mcp.json # MCP configuration -└── CLAUDE.md # This file - auto-loaded by Claude Code -``` - -## MCP Integration - -Task Master provides an MCP server that Claude Code can connect to. Configure in `.mcp.json`: - -```json -{ - "mcpServers": { - "task-master-ai": { - "command": "npx", - "args": ["-y", "--package=task-master-ai", "task-master-ai"], - "env": { - "ANTHROPIC_API_KEY": "your_key_here", - "PERPLEXITY_API_KEY": "your_key_here", - "OPENAI_API_KEY": "OPENAI_API_KEY_HERE", - "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE", - "XAI_API_KEY": "XAI_API_KEY_HERE", - "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE", - "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE", - "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE", - "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE" - } - } - } -} -``` - -### Essential MCP Tools - -```javascript -help; // = shows available taskmaster commands -// Project setup -initialize_project; // = task-master init -parse_prd; // = task-master parse-prd - -// Daily workflow -get_tasks; // = task-master list -next_task; // = task-master next -get_task; // = task-master show <id> -set_task_status; // = task-master set-status - -// Task management -add_task; // = task-master add-task -expand_task; // = task-master expand -update_task; // = task-master update-task -update_subtask; // = task-master update-subtask -update; // = task-master update - -// Analysis -analyze_project_complexity; // = task-master analyze-complexity -complexity_report; // = task-master complexity-report -``` - -## Claude Code Workflow Integration - -### Standard Development Workflow - -#### 1. Project Initialization - -```bash -# Initialize Task Master -task-master init - -# Create or obtain PRD, then parse it -task-master parse-prd .taskmaster/docs/prd.txt - -# Analyze complexity and expand tasks -task-master analyze-complexity --research -task-master expand --all --research -``` - -If tasks already exist, another PRD can be parsed (with new information only!) using parse-prd with --append flag. This will add the generated tasks to the existing list of tasks.. - -#### 2. Daily Development Loop - -```bash -# Start each session -task-master next # Find next available task -task-master show <id> # Review task details - -# During implementation, check in code context into the tasks and subtasks -task-master update-subtask --id=<id> --prompt="implementation notes..." - -# Complete tasks -task-master set-status --id=<id> --status=done -``` - -#### 3. Multi-Claude Workflows - -For complex projects, use multiple Claude Code sessions: - -```bash -# Terminal 1: Main implementation -cd project && claude - -# Terminal 2: Testing and validation -cd project-test-worktree && claude - -# Terminal 3: Documentation updates -cd project-docs-worktree && claude -``` - -### Custom Slash Commands - -Create `.claude/commands/taskmaster-next.md`: - -```markdown -Find the next available Task Master task and show its details. - -Steps: - -1. Run `task-master next` to get the next task -2. If a task is available, run `task-master show <id>` for full details -3. Provide a summary of what needs to be implemented -4. Suggest the first implementation step -``` - -Create `.claude/commands/taskmaster-complete.md`: - -```markdown -Complete a Task Master task: $ARGUMENTS - -Steps: - -1. Review the current task with `task-master show $ARGUMENTS` -2. Verify all implementation is complete -3. Run any tests related to this task -4. Mark as complete: `task-master set-status --id=$ARGUMENTS --status=done` -5. Show the next available task with `task-master next` -``` - -## Tool Allowlist Recommendations - -Add to `.claude/settings.json`: - -```json -{ - "allowedTools": [ - "Edit", - "Bash(task-master *)", - "Bash(git commit:*)", - "Bash(git add:*)", - "Bash(npm run *)", - "mcp__task_master_ai__*" - ] -} -``` - -## Configuration & Setup - -### API Keys Required - -At least **one** of these API keys must be configured: - -- `ANTHROPIC_API_KEY` (Claude models) - **Recommended** -- `PERPLEXITY_API_KEY` (Research features) - **Highly recommended** -- `OPENAI_API_KEY` (GPT models) -- `GOOGLE_API_KEY` (Gemini models) -- `MISTRAL_API_KEY` (Mistral models) -- `OPENROUTER_API_KEY` (Multiple models) -- `XAI_API_KEY` (Grok models) - -An API key is required for any provider used across any of the 3 roles defined in the `models` command. - -### Model Configuration - -```bash -# Interactive setup (recommended) -task-master models --setup - -# Set specific models -task-master models --set-main claude-3-5-sonnet-20241022 -task-master models --set-research perplexity-llama-3.1-sonar-large-128k-online -task-master models --set-fallback gpt-4o-mini -``` - -## Task Structure & IDs - -### Task ID Format - -- Main tasks: `1`, `2`, `3`, etc. -- Subtasks: `1.1`, `1.2`, `2.1`, etc. -- Sub-subtasks: `1.1.1`, `1.1.2`, etc. - -### Task Status Values - -- `pending` - Ready to work on -- `in-progress` - Currently being worked on -- `done` - Completed and verified -- `deferred` - Postponed -- `cancelled` - No longer needed -- `blocked` - Waiting on external factors - -### Task Fields - -```json -{ - "id": "1.2", - "title": "Implement user authentication", - "description": "Set up JWT-based auth system", - "status": "pending", - "priority": "high", - "dependencies": ["1.1"], - "details": "Use bcrypt for hashing, JWT for tokens...", - "testStrategy": "Unit tests for auth functions, integration tests for login flow", - "subtasks": [] -} -``` - -## Claude Code Best Practices with Task Master - -### Context Management - -- Use `/clear` between different tasks to maintain focus -- This CLAUDE.md file is automatically loaded for context -- Use `task-master show <id>` to pull specific task context when needed - -### Iterative Implementation - -1. `task-master show <subtask-id>` - Understand requirements -2. Explore codebase and plan implementation -3. `task-master update-subtask --id=<id> --prompt="detailed plan"` - Log plan -4. `task-master set-status --id=<id> --status=in-progress` - Start work -5. Implement code following logged plan -6. `task-master update-subtask --id=<id> --prompt="what worked/didn't work"` - Log progress -7. `task-master set-status --id=<id> --status=done` - Complete task - -### Complex Workflows with Checklists - -For large migrations or multi-step processes: - -1. Create a markdown PRD file describing the new changes: `touch task-migration-checklist.md` (prds can be .txt or .md) -2. Use Taskmaster to parse the new prd with `task-master parse-prd --append` (also available in MCP) -3. Use Taskmaster to expand the newly generated tasks into subtasks. Consdier using `analyze-complexity` with the correct --to and --from IDs (the new ids) to identify the ideal subtask amounts for each task. Then expand them. -4. Work through items systematically, checking them off as completed -5. Use `task-master update-subtask` to log progress on each task/subtask and/or updating/researching them before/during implementation if getting stuck - -### Git Integration - -Task Master works well with `gh` CLI: - -```bash -# Create PR for completed task -gh pr create --title "Complete task 1.2: User authentication" --body "Implements JWT auth system as specified in task 1.2" - -# Reference task in commits -git commit -m "feat: implement JWT auth (task 1.2)" -``` - -### Parallel Development with Git Worktrees - -```bash -# Create worktrees for parallel task development -git worktree add ../project-auth feature/auth-system -git worktree add ../project-api feature/api-refactor - -# Run Claude Code in each worktree -cd ../project-auth && claude # Terminal 1: Auth work -cd ../project-api && claude # Terminal 2: API work -``` - -## Troubleshooting - -### AI Commands Failing - -```bash -# Check API keys are configured -cat .env # For CLI usage - -# Verify model configuration -task-master models - -# Test with different model -task-master models --set-fallback gpt-4o-mini -``` - -### MCP Connection Issues - -- Check `.mcp.json` configuration -- Verify Node.js installation -- Use `--mcp-debug` flag when starting Claude Code -- Use CLI as fallback if MCP unavailable - -### Task File Sync Issues - -```bash -# Regenerate task files from tasks.json -task-master generate - -# Fix dependency issues -task-master fix-dependencies -``` - -DO NOT RE-INITIALIZE. That will not do anything beyond re-adding the same Taskmaster core files. - -## Important Notes - -### AI-Powered Operations - -These commands make AI calls and may take up to a minute: - -- `parse_prd` / `task-master parse-prd` -- `analyze_project_complexity` / `task-master analyze-complexity` -- `expand_task` / `task-master expand` -- `expand_all` / `task-master expand --all` -- `add_task` / `task-master add-task` -- `update` / `task-master update` -- `update_task` / `task-master update-task` -- `update_subtask` / `task-master update-subtask` - -### File Management - -- Never manually edit `tasks.json` - use commands instead -- Never manually edit `.taskmaster/config.json` - use `task-master models` -- Task markdown files in `tasks/` are auto-generated -- Run `task-master generate` after manual changes to tasks.json - -### Claude Code Session Management - -- Use `/clear` frequently to maintain focused context -- Create custom slash commands for repeated Task Master workflows -- Configure tool allowlist to streamline permissions -- Use headless mode for automation: `claude -p "task-master next"` - -### Multi-Task Updates - -- Use `update --from=<id>` to update multiple future tasks -- Use `update-task --id=<id>` for single task updates -- Use `update-subtask --id=<id>` for implementation logging - -### Research Mode - -- Add `--research` flag for research-based AI enhancement -- Requires a research model API key like Perplexity (`PERPLEXITY_API_KEY`) in environment -- Provides more informed task creation and updates -- Recommended for complex technical tasks - ---- - -_This guide ensures Claude Code has immediate access to Task Master's essential functionality for agentic development workflows._ diff --git a/.taskmaster/config.json b/.taskmaster/config.json deleted file mode 100644 index 16a2062f..00000000 --- a/.taskmaster/config.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "models": { - "main": { - "provider": "claude-code", - "modelId": "sonnet", - "maxTokens": 64000, - "temperature": 0.2 - }, - "research": { - "provider": "claude-code", - "modelId": "opus", - "maxTokens": 32000, - "temperature": 0.1 - }, - "fallback": { - "provider": "claude-code", - "modelId": "sonnet", - "maxTokens": 64000, - "temperature": 0.2 - } - }, - "global": { - "logLevel": "info", - "debug": false, - "defaultNumTasks": 10, - "defaultSubtasks": 5, - "defaultPriority": "medium", - "projectName": "Taskmaster", - "ollamaBaseURL": "http://localhost:11434/api", - "bedrockBaseURL": "https://bedrock.us-east-1.amazonaws.com", - "responseLanguage": "English", - "defaultTag": "master", - "azureOpenaiBaseURL": "https://your-endpoint.openai.azure.com/", - "userId": "1234567890" - }, - "claudeCode": {} -} \ No newline at end of file diff --git a/.taskmaster/docs/DOCUMENTATION_MAINTENANCE.md b/.taskmaster/docs/DOCUMENTATION_MAINTENANCE.md deleted file mode 100644 index 85b68d8f..00000000 --- a/.taskmaster/docs/DOCUMENTATION_MAINTENANCE.md +++ /dev/null @@ -1,271 +0,0 @@ -# Documentation Maintenance Schedule and Ownership Model - -## Overview - -This document establishes a systematic approach to maintaining SyntaxKit's documentation quality through regular reviews, clear ownership responsibilities, and automated validation processes. - -## Documentation Inventory - -### Core Documentation Areas - -| Area | Location | Owner | Update Frequency | -|------|----------|-------|------------------| -| **API Documentation** | Inline `///` comments | Core maintainers | Per feature/change | -| **README.md** | Project root | Core maintainers | Monthly review | -| **Getting Started** | Documentation.docc/Documentation.md | Documentation team | Quarterly | -| **Tutorials** | Documentation.docc/Tutorials/ | Tutorial maintainers | Bi-monthly | -| **Articles** | Documentation.docc/Articles/ | Subject matter experts | Quarterly | -| **Examples** | Examples/ directories | Example maintainers | Per release | -| **CLAUDE.md** | Project root | AI integration team | As needed | -| **CONTRIBUTING-DOCS.md** | Project root | Documentation team | Quarterly | - -### Documentation Owners - -#### Primary Roles - -1. **Documentation Lead** - - Overall documentation strategy and quality - - Final approval for major documentation changes - - Coordination between different documentation areas - -2. **API Documentation Maintainers** - - Keep inline documentation current with code changes - - Ensure all public APIs have comprehensive documentation - - Review API documentation in pull requests - -3. **Tutorial Maintainers** - - Maintain step-by-step tutorials - - Update tutorials for new features and changes - - Test tutorial completability with each release - -4. **Example Maintainers** - - Keep code examples current and functional - - Create new examples for major features - - Validate examples compile and run correctly - -5. **DevOps/CI Maintainers** - - Maintain automated documentation validation - - Update CI/CD pipelines for documentation checks - - Monitor documentation build processes - -## Maintenance Schedule - -### Daily (Automated) -- **CI/CD Validation**: Run on every PR and push - - Link validation via `./Scripts/validate-docs.sh` - - Code example compilation checks - - API documentation coverage via `./Scripts/api-coverage.sh` - - DocC build validation - -### Weekly (Manual Review) -- **Active Development Review**: During active development periods - - Review new API documentation for completeness - - Validate new examples and code snippets - - Check for documentation debt accumulation - -### Monthly (Systematic Review) -- **README.md Health Check** - - Verify installation instructions work with latest versions - - Update badges and status indicators - - Review quick start examples for accuracy - - Check external links and references - -- **Example Validation** - - Run all examples in clean environments - - Update example dependencies and versions - - Verify examples follow current best practices - -### Quarterly (Comprehensive Review) -- **Full Documentation Audit** - - Complete review of all tutorials for accuracy - - Update articles for new features and changes - - Review documentation structure and navigation - - Assess user feedback and support questions for documentation gaps - -- **Performance Review** - - Analyze documentation metrics and user feedback - - Review time-to-productivity for new users - - Assess documentation contribution process efficiency - -### Per Release (Version-Specific Updates) -- **Version Compatibility Updates** - - Update version requirements across all documentation - - Review breaking changes and migration guides - - Update Swift version compatibility information - - Refresh platform support documentation - -- **Feature Documentation** - - Document new features with examples - - Update existing documentation for changed APIs - - Create migration guides for breaking changes - -## Quality Assurance Process - -### Automated Validation Pipeline - -```bash -# Daily CI/CD checks (run on every PR) -./Scripts/validate-docs.sh # Link validation and cross-references -./Scripts/api-coverage.sh # API documentation coverage (90% threshold) -swift package generate-documentation # DocC build validation -./Scripts/lint.sh # Code quality including documentation -``` - -### Review Checkpoints - -#### For Every Pull Request -- [ ] All new public APIs have documentation comments -- [ ] Code examples compile and run -- [ ] Internal links and cross-references work -- [ ] Changes don't break existing documentation - -#### Monthly Review Checklist -- [ ] External links are functional -- [ ] Installation instructions work with current versions -- [ ] Quick start examples run successfully -- [ ] API coverage meets 90% threshold -- [ ] No placeholder or TODO content remains - -#### Quarterly Review Checklist -- [ ] All tutorials can be completed as written -- [ ] Documentation structure serves user journey -- [ ] New user onboarding is smooth and complete -- [ ] Advanced topics are adequately covered -- [ ] Community feedback has been addressed - -## Ownership Responsibilities - -### Documentation Lead Responsibilities -- **Strategic Planning**: Define documentation roadmap and priorities -- **Quality Standards**: Enforce documentation quality standards -- **Process Improvement**: Continuously improve documentation processes -- **Stakeholder Communication**: Coordinate with development team and community - -### Area-Specific Owners - -#### API Documentation (Core Maintainers) -- **Coverage**: Ensure 90%+ API documentation coverage -- **Quality**: Maintain high-quality inline documentation -- **Consistency**: Enforce documentation style guidelines -- **Reviews**: Review all API documentation changes - -#### Tutorial Maintainers -- **User Experience**: Ensure tutorials provide smooth learning experience -- **Accuracy**: Keep tutorials current with latest features -- **Testing**: Regularly test tutorial completability -- **Feedback**: Incorporate user feedback and common questions - -#### Example Maintainers -- **Functionality**: Ensure all examples compile and run -- **Relevance**: Keep examples aligned with real-world use cases -- **Best Practices**: Demonstrate current best practices -- **Coverage**: Provide examples for major framework features - -## Documentation Debt Management - -### Identification Process -1. **Automated Detection** - - CI/CD flags missing documentation - - Link validation identifies broken references - - API coverage reports highlight gaps - -2. **Community Feedback** - - GitHub issues tagged with 'documentation' - - Support questions indicating unclear documentation - - User feedback on tutorial completion - -3. **Regular Audits** - - Monthly reviews identify outdated content - - Quarterly audits assess structural issues - - Release reviews catch version-specific problems - -### Prioritization Framework - -#### High Priority (Fix within 1 week) -- Broken links or compilation errors -- Missing documentation for new public APIs -- Critical user onboarding blockers -- Security-related documentation gaps - -#### Medium Priority (Fix within 1 month) -- Outdated examples or tutorials -- Minor inaccuracies in existing documentation -- Missing advanced usage examples -- Documentation style inconsistencies - -#### Low Priority (Fix within 1 quarter) -- Documentation structure improvements -- Additional examples for edge cases -- Enhanced troubleshooting guides -- Performance optimization documentation - -### Debt Resolution Process -1. **Triage**: Categorize and prioritize documentation debt -2. **Assignment**: Assign to appropriate owner based on area -3. **Timeline**: Set realistic resolution timeline based on priority -4. **Tracking**: Track progress through GitHub issues or task management -5. **Validation**: Verify fixes through review and testing process - -## Escalation Paths - -### Documentation Issues -1. **Area Owner**: First point of contact for area-specific issues -2. **Documentation Lead**: Escalation for cross-area or strategic issues -3. **Project Maintainers**: Final escalation for project-level decisions - -### Approval Authority -- **Minor Updates**: Area owners can approve within their domain -- **Major Changes**: Require documentation lead approval -- **Structural Changes**: Require project maintainer approval - -## Metrics and Monitoring - -### Key Performance Indicators -- **API Coverage**: Maintain 90%+ documentation coverage -- **Link Health**: Zero broken internal/external links -- **User Success**: Track tutorial completion rates and user feedback -- **Community Health**: Monitor documentation-related issues and questions - -### Monthly Reporting -- Documentation coverage trends -- Link validation results -- Community feedback summary -- Outstanding documentation debt - -### Success Criteria -- 90%+ API documentation coverage maintained -- All tutorials completable within stated timeframes -- Zero critical documentation debt items -- Positive community feedback on documentation quality - -## Tools and Automation - -### Current Validation Tools -- `./Scripts/validate-docs.sh` - Comprehensive link and reference validation -- `./Scripts/api-coverage.sh` - API documentation coverage analysis -- GitHub Actions CI/CD - Automated validation on every change - -### Recommended Enhancements -- **Documentation Analytics**: Track user engagement with different sections -- **Automated Outdated Content Detection**: Flag content that hasn't been updated recently -- **Tutorial Testing Automation**: Automated testing of tutorial steps -- **Community Feedback Integration**: Automated collection and analysis of user feedback - -## Implementation Timeline - -### Phase 1 (Week 1): Immediate Setup -- [ ] Assign documentation owners for each area -- [ ] Set up monthly review calendar -- [ ] Configure automated validation thresholds - -### Phase 2 (Week 2-4): Process Integration -- [ ] Integrate ownership model into PR review process -- [ ] Implement quarterly review procedures -- [ ] Set up documentation debt tracking system - -### Phase 3 (Month 2-3): Optimization -- [ ] Analyze initial metrics and feedback -- [ ] Refine processes based on early experience -- [ ] Implement enhanced automation tools - -This maintenance schedule ensures SyntaxKit's documentation remains accurate, comprehensive, and user-friendly while distributing responsibility appropriately across the development team. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 57cf92e1..5c74cabc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -307,7 +307,6 @@ When working with SyntaxKit, remember: - Consider using `SyntaxRewriter` for complex transformations - Use `SyntaxVisitor` for analysis and inspection tasks -## Task Master AI Instructions -**Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.** -@./.taskmaster/CLAUDE.md +## Notes + - We suggest using the Swift OpenAPI Generator diff --git a/Docs/skit-analyze-plan.md b/Docs/skit-analyze-plan.md index 0aa2502c..a34a0d38 100644 --- a/Docs/skit-analyze-plan.md +++ b/Docs/skit-analyze-plan.md @@ -741,15 +741,15 @@ User runs: skit analyze examples/subscript-feature Sources/SyntaxKit output/Synt ### 4. Package.swift Changes -Add the OpenAPI Generator dependencies, the two new targets, and wire `AiSTKit` -into the existing `skit` executable target: +Add the OpenAPI runtime dependencies, the two new targets, and wire `AiSTKit` +into the existing `skit` executable target. swift-openapi-generator is a +development tool, not a package dependency: it is managed by mise +(`"spm:apple/swift-openapi-generator"` in `mise.toml`), invoked via +`Scripts/generate-openapi.sh`, and the generated code is committed under +`Sources/ClaudeKit/Generated/`. ```swift // In dependencies: -.package( - url: "https://github.com/apple/swift-openapi-generator", - from: "1.0.0" -), .package( url: "https://github.com/apple/swift-openapi-runtime", from: "1.0.0" @@ -759,17 +759,16 @@ into the existing `skit` executable target: from: "1.0.0" ), -// New target: OpenAPI-generated Claude API client +// New target: OpenAPI-generated Claude API client (committed sources) .target( name: "ClaudeKit", dependencies: [ .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"), .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession") ], - plugins: [ - .plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator") - ], - swiftSettings: swiftSettings + // No shared swiftSettings: upcoming features like InternalImportsByDefault + // reject the generator's plain `import OpenAPIRuntime` in package-access API. + exclude: ["openapi.json", "openapi-generator-config.yaml"] ), // New target: SDK/bridge layer with the analyzer domain logic @@ -809,13 +808,23 @@ inside it. - types - client accessModifier: package + filter: + paths: + - /v1/messages ``` + The `filter` is required: the unofficial spec's `?beta=true` path variants + carry duplicate operationIds that fail generator validation, and + `/v1/messages` is the only endpoint the analyzer needs. -3. The OpenAPI Generator plugin will automatically generate type-safe client code during build +3. Run `Scripts/generate-openapi.sh` (mise provides `swift-openapi-generator`) + and commit the output under `Sources/ClaudeKit/Generated/` **Notes**: -- OpenAPI Generator runs as a build plugin and generates Swift code from the OpenAPI spec at build time +- The generator runs as a mise-managed CLI, not an SPM build plugin; regenerate + with `Scripts/generate-openapi.sh` after changing the spec or config - Generated code includes type-safe request/response models and client methods +- Generated code is excluded from SwiftLint (`.swiftlint.yml`) and Periphery + (`.periphery.yml`) reporting - Adding `AiSTKit` to `skit` pulls the OpenAPI runtime into the `skit` binary; this is acceptable for a developer tool ### 5. Configuration & Environment diff --git a/IMPLEMENTATION_STATUS.md b/IMPLEMENTATION_STATUS.md index 800a4f70..9f3516ab 100644 --- a/IMPLEMENTATION_STATUS.md +++ b/IMPLEMENTATION_STATUS.md @@ -24,16 +24,20 @@ All implementation tasks have been broken down into 18 GitHub issues organized i ## Implementation Phases -### Phase 1: Project Setup & Infrastructure ✓ Planned +### Phase 1: Project Setup & Infrastructure ✅ Complete **Issues**: #107, #108 -- [x] Issue #107: Setup OpenAPI Specification and Generator Configuration -- [x] Issue #108: Update Package.swift with Dependencies and Targets +- [x] Issue #107: Setup OpenAPI Specification and Generator Configuration — **Done** +- [x] Issue #108: Update Package.swift with Dependencies and Targets — **Done** - ~~Issue #109: Create ConfigKeyKit Target Structure~~ (closed — ConfigKeyKit dropped in favor of ArgumentParser) -**Status**: Ready to implement -**Estimated Effort**: 2-3 hours +**Status**: Complete (branch `107-108-openapi-setup`) +**Deviation from plan**: swift-openapi-generator is a mise-managed CLI tool +(`mise.toml`, `Scripts/generate-openapi.sh`), not an SPM build plugin; generated +code is committed under `Sources/ClaudeKit/Generated/`. The generator config +filters to `/v1/messages` because the unofficial spec's `?beta=true` path +variants carry duplicate operationIds that fail validation. **Critical Path**: Yes - blocks all other work ### Phase 2: Core Configuration & Command Infrastructure ⏳ Waiting @@ -43,7 +47,7 @@ All implementation tasks have been broken down into 18 GitHub issues organized i - [ ] Issue #110: Implement AnalyzerConfiguration and AnalyzerError - [ ] Issue #111: Implement skit analyze Subcommand (ArgumentParser) -**Status**: Blocked by Phase 1 +**Status**: Ready to implement (Phase 1 complete) **Estimated Effort**: 3-4 hours **Critical Path**: Yes @@ -111,15 +115,15 @@ All implementation tasks have been broken down into 18 GitHub issues organized i ### Overall Progress - **Issues Created**: 19 total ✓ (#109 since closed — ConfigKeyKit dropped; #168 added for the convergence loop) -- **Issues Completed**: 0/18 -- **Phases Completed**: 0/7 +- **Issues Completed**: 2/18 (#107, #108) +- **Phases Completed**: 1/7 - **Estimated Total Effort**: 27-35 hours ### Current Status -**Current Phase**: Phase 1 (Project Setup) -**Next Actionable Issue**: #107 -**Blocked Issues**: 15 (waiting on dependencies) +**Current Phase**: Phase 2 (Core Configuration & Command Infrastructure) +**Next Actionable Issue**: #110 (also unblocked: #117, #118, #119) +**Blocked Issues**: 12 (waiting on dependencies) ## Critical Path @@ -254,4 +258,4 @@ For questions or issues, please comment on the relevant GitHub issue or create a --- **Last Updated**: 2026-06-11 -**Status**: Planning Complete, Implementation Ready +**Status**: Phase 1 Complete (#107, #108), Phase 2 Ready diff --git a/Package.resolved b/Package.resolved index 99337efe..2a185081 100644 --- a/Package.resolved +++ b/Package.resolved @@ -1,5 +1,5 @@ { - "originHash" : "899b1fb6639e07a99f4d6f6c1e22b7c90948b2df293879cf18e8b0f87500bf16", + "originHash" : "bceb9fcd60ab254851be8ab5967c609d295a3f0b191c492566132d4079523e99", "pins" : [ { "identity" : "swift-argument-parser", @@ -10,6 +10,15 @@ "version" : "1.7.1" } }, + { + "identity" : "swift-collections", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-collections", + "state" : { + "revision" : "a0cb0954ecb21e4e31b0070e6ed5674e8556685a", + "version" : "1.6.0" + } + }, { "identity" : "swift-docc-plugin", "kind" : "remoteSourceControl", @@ -28,6 +37,33 @@ "version" : "1.0.0" } }, + { + "identity" : "swift-http-types", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-http-types", + "state" : { + "revision" : "db774a277f60063a32d854f2980299caf06da041", + "version" : "1.6.0" + } + }, + { + "identity" : "swift-openapi-runtime", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-openapi-runtime", + "state" : { + "revision" : "3d3a8457661daf7fb260ceeb9f0e24e5204ba5fb", + "version" : "1.12.0" + } + }, + { + "identity" : "swift-openapi-urlsession", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-openapi-urlsession", + "state" : { + "revision" : "576a65b4ffb8c12ddad4950dc21eea2ef071bec2", + "version" : "1.3.0" + } + }, { "identity" : "swift-subprocess", "kind" : "remoteSourceControl", diff --git a/Package.swift b/Package.swift index 4e02cd60..8bf8f29b 100644 --- a/Package.swift +++ b/Package.swift @@ -104,7 +104,9 @@ let package = Package( .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.4.0"), .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.3.0"), .package(url: "https://github.com/swiftlang/swift-subprocess.git", from: "0.4.0"), - .package(url: "https://github.com/apple/swift-system.git", from: "1.0.0") + .package(url: "https://github.com/apple/swift-system.git", from: "1.0.0"), + .package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.12.0"), + .package(url: "https://github.com/apple/swift-openapi-urlsession", from: "1.3.0") ], targets: [ .target( @@ -145,11 +147,30 @@ let package = Package( ], swiftSettings: swiftSettings ), + .target( + name: "ClaudeKit", + dependencies: [ + .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"), + .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession") + ], + // No shared swiftSettings: upcoming features like InternalImportsByDefault + // reject the generator's plain `import OpenAPIRuntime` in package-access API. + exclude: ["openapi.json", "openapi-generator-config.yaml"] + ), + .target( + name: "AiSTKit", + dependencies: [ + "ClaudeKit", + "SyntaxParser" + ], + swiftSettings: swiftSettings + ), .executableTarget( name: "skit", dependencies: [ "SyntaxKit", "SyntaxParser", + "AiSTKit", .product(name: "SwiftSyntax", package: "swift-syntax"), .product(name: "SwiftParser", package: "swift-syntax"), .product(name: "ArgumentParser", package: "swift-argument-parser"), diff --git a/Scripts/generate-openapi.sh b/Scripts/generate-openapi.sh new file mode 100755 index 00000000..1c0bf1d6 --- /dev/null +++ b/Scripts/generate-openapi.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +# Regenerates the ClaudeKit client from the Anthropic OpenAPI spec. +# swift-openapi-generator is managed by mise (see mise.toml); the generated +# code is committed under Sources/ClaudeKit/Generated. +# +# Sources/ClaudeKit/openapi.json is the unofficial Anthropic OpenAPI spec +# (hosted_spec.json, retrieved 2026-06-11) from +# https://github.com/laszukdawid/anthropic-openapi-spec — to refresh it: +# curl -o Sources/ClaudeKit/openapi.json \ +# https://raw.githubusercontent.com/laszukdawid/anthropic-openapi-spec/main/hosted_spec.json + +set -e + +# More portable way to get script directory +if [ -z "$SRCROOT" ]; then + SCRIPT_DIR=$(dirname "$(readlink -f "$0")") + PACKAGE_DIR="${SCRIPT_DIR}/.." +else + PACKAGE_DIR="${SRCROOT}" +fi + +# Ensure mise-managed tools are on PATH outside CI (CI uses jdx/mise-action) +if command -v mise >/dev/null 2>&1 && [ -z "$CI" ]; then + eval "$(mise -C "$PACKAGE_DIR" env -s bash)" +fi + +cd "$PACKAGE_DIR" + +mkdir -p Sources/ClaudeKit/Generated + +swift-openapi-generator generate \ + --config Sources/ClaudeKit/openapi-generator-config.yaml \ + --output-directory Sources/ClaudeKit/Generated \ + Sources/ClaudeKit/openapi.json + +# Generated files opt out of swift-format, Periphery, and the license header +# via the additionalFileComments in openapi-generator-config.yaml (header.sh +# skips files carrying swift-format-ignore-file); SwiftLint excludes the +# Generated directory in .swiftlint.yml. diff --git a/Scripts/header.sh b/Scripts/header.sh index 4ed74462..3da0c393 100755 --- a/Scripts/header.sh +++ b/Scripts/header.sh @@ -66,9 +66,16 @@ header_template="// # Loop through each Swift file in the specified directory and subdirectories find "$directory" -type f -name "*.swift" | while read -r file; do - # Check if the first line is the swift-format-ignore indicator - first_line=$(head -n 1 "$file") - if [[ "$first_line" == "// swift-format-ignore-file" ]]; then + # Skip files carrying `// swift-format-ignore-file` anywhere in the leading + # comment block. This is the opt-out used by generated files (e.g. + # swift-openapi-generator emits it via `additionalFileComments`) and lets + # them sit anywhere in the tree without needing a path-based exclusion. + if awk ' + /^\/\/[[:space:]]*swift-format-ignore-file[[:space:]]*$/ { found = 1; exit } + /^[[:space:]]*$/ || /^\/\// { next } + { exit } + END { exit !found } + ' "$file"; then echo "Skipping $file due to swift-format-ignore directive." continue fi diff --git a/Sources/AiSTKit/AiSTKit.swift b/Sources/AiSTKit/AiSTKit.swift new file mode 100644 index 00000000..a328235b --- /dev/null +++ b/Sources/AiSTKit/AiSTKit.swift @@ -0,0 +1,35 @@ +// +// AiSTKit.swift +// SyntaxKit +// +// Created by Leo Dion. +// Copyright © 2026 BrightDigit. +// +// 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. +// + +/// Namespace for the AiSTKit SDK layer. +/// +/// AiSTKit bridges the `skit analyze` subcommand and the OpenAPI-generated +/// Claude API client in ClaudeKit. Implementation arrives with issues +/// #110–#120; this placeholder keeps the target buildable until then. +package enum AiSTKit {} diff --git a/Sources/ClaudeKit/Generated/Client.swift b/Sources/ClaudeKit/Generated/Client.swift new file mode 100644 index 00000000..1ab1446c --- /dev/null +++ b/Sources/ClaudeKit/Generated/Client.swift @@ -0,0 +1,150 @@ +// Generated by swift-openapi-generator, do not modify. +// periphery:ignore:all +// swift-format-ignore-file +@_spi(Generated) import OpenAPIRuntime +#if os(Linux) +@preconcurrency import struct Foundation.URL +@preconcurrency import struct Foundation.Data +@preconcurrency import struct Foundation.Date +#else +import struct Foundation.URL +import struct Foundation.Data +import struct Foundation.Date +#endif +import HTTPTypes +package struct Client: APIProtocol { + /// The underlying HTTP client. + private let client: UniversalClient + /// Creates a new client. + /// - Parameters: + /// - serverURL: The server URL that the client connects to. Any server + /// URLs defined in the OpenAPI document are available as static methods + /// on the ``Servers`` type. + /// - configuration: A set of configuration values for the client. + /// - transport: A transport that performs HTTP operations. + /// - middlewares: A list of middlewares to call before the transport. + package init( + serverURL: Foundation.URL, + configuration: Configuration = .init(), + transport: any ClientTransport, + middlewares: [any ClientMiddleware] = [] + ) { + self.client = .init( + serverURL: serverURL, + configuration: configuration, + transport: transport, + middlewares: middlewares + ) + } + private var converter: Converter { + client.converter + } + /// Create a Message + /// + /// Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + /// + /// The Messages API can be used for either single queries or stateless multi-turn conversations. + /// + /// - Remark: HTTP `POST /v1/messages`. + /// - Remark: Generated from `#/paths//v1/messages/post(messages_post)`. + package func messages_post(_ input: Operations.messages_post.Input) async throws -> Operations.messages_post.Output { + try await client.send( + input: input, + forOperation: Operations.messages_post.id, + serializer: { input in + let path = try converter.renderedPath( + template: "/v1/messages", + parameters: [] + ) + var request: HTTPTypes.HTTPRequest = .init( + soar_path: path, + method: .post + ) + suppressMutabilityWarning(&request) + try converter.setHeaderFieldAsURI( + in: &request.headerFields, + name: "anthropic-version", + value: input.headers.anthropic_hyphen_version + ) + try converter.setHeaderFieldAsURI( + in: &request.headerFields, + name: "x-api-key", + value: input.headers.x_hyphen_api_hyphen_key + ) + converter.setAcceptHeader( + in: &request.headerFields, + contentTypes: input.headers.accept + ) + let body: OpenAPIRuntime.HTTPBody? + switch input.body { + case let .json(value): + body = try converter.setRequiredRequestBodyAsJSON( + value, + headerFields: &request.headerFields, + contentType: "application/json; charset=utf-8" + ) + } + return (request, body) + }, + deserializer: { response, responseBody in + switch response.status.code { + case 200: + let contentType = converter.extractContentTypeIfPresent(in: response.headerFields) + let body: Operations.messages_post.Output.Ok.Body + let chosenContentType = try converter.bestContentType( + received: contentType, + options: [ + "application/json" + ] + ) + switch chosenContentType { + case "application/json": + body = try await converter.getResponseBodyAsJSON( + Components.Schemas.Message.self, + from: responseBody, + transforming: { value in + .json(value) + } + ) + default: + preconditionFailure("bestContentType chose an invalid content type.") + } + return .ok(.init(body: body)) + case 400 ... 499: + let contentType = converter.extractContentTypeIfPresent(in: response.headerFields) + let body: Operations.messages_post.Output.ClientError.Body + let chosenContentType = try converter.bestContentType( + received: contentType, + options: [ + "application/json" + ] + ) + switch chosenContentType { + case "application/json": + body = try await converter.getResponseBodyAsJSON( + Components.Schemas.ErrorResponse.self, + from: responseBody, + transforming: { value in + .json(value) + } + ) + default: + preconditionFailure("bestContentType chose an invalid content type.") + } + return .clientError( + statusCode: response.status.code, + .init(body: body) + ) + default: + return .undocumented( + statusCode: response.status.code, + .init( + headerFields: response.headerFields, + body: responseBody + ) + ) + } + } + ) + } +} diff --git a/Sources/ClaudeKit/Generated/Types.swift b/Sources/ClaudeKit/Generated/Types.swift new file mode 100644 index 00000000..de6a4e42 --- /dev/null +++ b/Sources/ClaudeKit/Generated/Types.swift @@ -0,0 +1,2143 @@ +// Generated by swift-openapi-generator, do not modify. +// periphery:ignore:all +// swift-format-ignore-file +@_spi(Generated) import OpenAPIRuntime +#if os(Linux) +@preconcurrency import struct Foundation.URL +@preconcurrency import struct Foundation.Data +@preconcurrency import struct Foundation.Date +#else +import struct Foundation.URL +import struct Foundation.Data +import struct Foundation.Date +#endif +/// A type that performs HTTP operations defined by the OpenAPI document. +package protocol APIProtocol: Sendable { + /// Create a Message + /// + /// Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + /// + /// The Messages API can be used for either single queries or stateless multi-turn conversations. + /// + /// - Remark: HTTP `POST /v1/messages`. + /// - Remark: Generated from `#/paths//v1/messages/post(messages_post)`. + func messages_post(_ input: Operations.messages_post.Input) async throws -> Operations.messages_post.Output +} + +/// Convenience overloads for operation inputs. +extension APIProtocol { + /// Create a Message + /// + /// Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + /// + /// The Messages API can be used for either single queries or stateless multi-turn conversations. + /// + /// - Remark: HTTP `POST /v1/messages`. + /// - Remark: Generated from `#/paths//v1/messages/post(messages_post)`. + package func messages_post( + headers: Operations.messages_post.Input.Headers = .init(), + body: Operations.messages_post.Input.Body + ) async throws -> Operations.messages_post.Output { + try await messages_post(Operations.messages_post.Input( + headers: headers, + body: body + )) + } +} + +/// Server URLs defined in the OpenAPI document. +package enum Servers { + package enum Server1 { + package static func url() throws -> Foundation.URL { + try Foundation.URL( + validatingOpenAPIServerURL: "https://api.anthropic.com", + variables: [] + ) + } + } + @available(*, deprecated, renamed: "Servers.Server1.url") + package static func server1() throws -> Foundation.URL { + try Foundation.URL( + validatingOpenAPIServerURL: "https://api.anthropic.com", + variables: [] + ) + } +} + +/// Types generated from the components section of the OpenAPI document. +package enum Components { + /// Types generated from the `#/components/schemas` section of the OpenAPI document. + package enum Schemas { + /// - Remark: Generated from `#/components/schemas/APIError`. + package struct APIError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/APIError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case api_error = "api_error" + } + /// - Remark: Generated from `#/components/schemas/APIError/type`. + package var _type: Components.Schemas.APIError._typePayload + /// - Remark: Generated from `#/components/schemas/APIError/message`. + package var message: Swift.String + /// Creates a new `APIError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.APIError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/AuthenticationError`. + package struct AuthenticationError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/AuthenticationError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case authentication_error = "authentication_error" + } + /// - Remark: Generated from `#/components/schemas/AuthenticationError/type`. + package var _type: Components.Schemas.AuthenticationError._typePayload + /// - Remark: Generated from `#/components/schemas/AuthenticationError/message`. + package var message: Swift.String + /// Creates a new `AuthenticationError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.AuthenticationError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/Base64ImageSource`. + package struct Base64ImageSource: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/Base64ImageSource/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case base64 = "base64" + } + /// - Remark: Generated from `#/components/schemas/Base64ImageSource/type`. + package var _type: Components.Schemas.Base64ImageSource._typePayload + /// - Remark: Generated from `#/components/schemas/Base64ImageSource/media_type`. + @frozen package enum media_typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case image_sol_jpeg = "image/jpeg" + case image_sol_png = "image/png" + case image_sol_gif = "image/gif" + case image_sol_webp = "image/webp" + } + /// - Remark: Generated from `#/components/schemas/Base64ImageSource/media_type`. + package var media_type: Components.Schemas.Base64ImageSource.media_typePayload + /// - Remark: Generated from `#/components/schemas/Base64ImageSource/data`. + package var data: Swift.String + /// Creates a new `Base64ImageSource`. + /// + /// - Parameters: + /// - _type: + /// - media_type: + /// - data: + package init( + _type: Components.Schemas.Base64ImageSource._typePayload, + media_type: Components.Schemas.Base64ImageSource.media_typePayload, + data: Swift.String + ) { + self._type = _type + self.media_type = media_type + self.data = data + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case media_type + case data + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.Base64ImageSource._typePayload.self, + forKey: ._type + ) + self.media_type = try container.decode( + Components.Schemas.Base64ImageSource.media_typePayload.self, + forKey: .media_type + ) + self.data = try container.decode( + Swift.String.self, + forKey: .data + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "media_type", + "data" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/CreateMessageParams`. + package struct CreateMessageParams: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/model`. + package var model: Components.Schemas.Model + /// Input messages. + /// + /// Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + /// + /// Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + /// + /// If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + /// + /// Example with a single `user` message: + /// + /// ```json + /// [{"role": "user", "content": "Hello, Claude"}] + /// ``` + /// + /// Example with multiple conversational turns: + /// + /// ```json + /// [ + /// {"role": "user", "content": "Hello there."}, + /// {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + /// {"role": "user", "content": "Can you explain LLMs in plain English?"}, + /// ] + /// ``` + /// + /// Example with a partially-filled response from Claude: + /// + /// ```json + /// [ + /// {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + /// {"role": "assistant", "content": "The best answer is ("}, + /// ] + /// ``` + /// + /// Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + /// + /// ```json + /// {"role": "user", "content": "Hello, Claude"} + /// ``` + /// + /// ```json + /// {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + /// ``` + /// + /// Starting with Claude 3 models, you can also send image content blocks: + /// + /// ```json + /// {"role": "user", "content": [ + /// { + /// "type": "image", + /// "source": { + /// "type": "base64", + /// "media_type": "image/jpeg", + /// "data": "/9j/4AAQSkZJRg...", + /// } + /// }, + /// {"type": "text", "text": "What is in this image?"} + /// ]} + /// ``` + /// + /// We currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types. + /// + /// See [examples](https://docs.anthropic.com/en/api/messages-examples#vision) for more input examples. + /// + /// Note that if you want to include a [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/messages`. + package var messages: [Components.Schemas.InputMessage] + /// The maximum number of tokens to generate before stopping. + /// + /// Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + /// + /// Different models have different maximum values for this parameter. See [models](https://docs.anthropic.com/en/docs/models-overview) for details. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/max_tokens`. + package var max_tokens: Swift.Int + /// An object describing metadata about the request. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/metadata`. + package struct metadataPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/metadata/value1`. + package var value1: Components.Schemas.Metadata + /// Creates a new `metadataPayload`. + /// + /// - Parameters: + /// - value1: + package init(value1: Components.Schemas.Metadata) { + self.value1 = value1 + } + package init(from decoder: any Swift.Decoder) throws { + self.value1 = try .init(from: decoder) + } + package func encode(to encoder: any Swift.Encoder) throws { + try self.value1.encode(to: encoder) + } + } + /// An object describing metadata about the request. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/metadata`. + package var metadata: Components.Schemas.CreateMessageParams.metadataPayload? + /// Custom text sequences that will cause the model to stop generating. + /// + /// Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + /// + /// If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/stop_sequences`. + package var stop_sequences: [Swift.String]? + /// Whether to incrementally stream the response using server-sent events. + /// + /// See [streaming](https://docs.anthropic.com/en/api/messages-streaming) for details. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/stream`. + package var stream: Swift.Bool? + /// System prompt. + /// + /// A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts). + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/system`. + package struct systemPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/system/value1`. + package var value1: Swift.String? + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/system/value2`. + package var value2: [Components.Schemas.RequestTextBlock]? + /// Creates a new `systemPayload`. + /// + /// - Parameters: + /// - value1: + /// - value2: + package init( + value1: Swift.String? = nil, + value2: [Components.Schemas.RequestTextBlock]? = nil + ) { + self.value1 = value1 + self.value2 = value2 + } + package init(from decoder: any Swift.Decoder) throws { + var errors: [any Swift.Error] = [] + do { + self.value1 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + do { + self.value2 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + try Swift.DecodingError.verifyAtLeastOneSchemaIsNotNil( + [ + self.value1, + self.value2 + ], + type: Self.self, + codingPath: decoder.codingPath, + errors: errors + ) + } + package func encode(to encoder: any Swift.Encoder) throws { + try encoder.encodeFirstNonNilValueToSingleValueContainer([ + self.value1, + self.value2 + ]) + } + } + /// System prompt. + /// + /// A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts). + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/system`. + package var system: Components.Schemas.CreateMessageParams.systemPayload? + /// Amount of randomness injected into the response. + /// + /// Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + /// + /// Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/temperature`. + package var temperature: Swift.Double? + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/tool_choice`. + package var tool_choice: Components.Schemas.ToolChoice? + /// Definitions of tools that the model may use. + /// + /// If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + /// + /// Each tool definition includes: + /// + /// * `name`: Name of the tool. + /// * `description`: Optional, but strongly-recommended description of the tool. + /// * `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + /// + /// For example, if you defined `tools` as: + /// + /// ```json + /// [ + /// { + /// "name": "get_stock_price", + /// "description": "Get the current stock price for a given ticker symbol.", + /// "input_schema": { + /// "type": "object", + /// "properties": { + /// "ticker": { + /// "type": "string", + /// "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + /// } + /// }, + /// "required": ["ticker"] + /// } + /// } + /// ] + /// ``` + /// + /// And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + /// + /// ```json + /// [ + /// { + /// "type": "tool_use", + /// "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + /// "name": "get_stock_price", + /// "input": { "ticker": "^GSPC" } + /// } + /// ] + /// ``` + /// + /// You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + /// + /// ```json + /// [ + /// { + /// "type": "tool_result", + /// "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + /// "content": "259.75 USD" + /// } + /// ] + /// ``` + /// + /// Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + /// + /// See our [guide](https://docs.anthropic.com/en/docs/tool-use) for more details. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/tools`. + package var tools: [Components.Schemas.Tool]? + /// Only sample from the top K options for each subsequent token. + /// + /// Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + /// + /// Recommended for advanced use cases only. You usually only need to use `temperature`. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/top_k`. + package var top_k: Swift.Int? + /// Use nucleus sampling. + /// + /// In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + /// + /// Recommended for advanced use cases only. You usually only need to use `temperature`. + /// + /// - Remark: Generated from `#/components/schemas/CreateMessageParams/top_p`. + package var top_p: Swift.Double? + /// Creates a new `CreateMessageParams`. + /// + /// - Parameters: + /// - model: + /// - messages: Input messages. + /// - max_tokens: The maximum number of tokens to generate before stopping. + /// - metadata: An object describing metadata about the request. + /// - stop_sequences: Custom text sequences that will cause the model to stop generating. + /// - stream: Whether to incrementally stream the response using server-sent events. + /// - system: System prompt. + /// - temperature: Amount of randomness injected into the response. + /// - tool_choice: + /// - tools: Definitions of tools that the model may use. + /// - top_k: Only sample from the top K options for each subsequent token. + /// - top_p: Use nucleus sampling. + package init( + model: Components.Schemas.Model, + messages: [Components.Schemas.InputMessage], + max_tokens: Swift.Int, + metadata: Components.Schemas.CreateMessageParams.metadataPayload? = nil, + stop_sequences: [Swift.String]? = nil, + stream: Swift.Bool? = nil, + system: Components.Schemas.CreateMessageParams.systemPayload? = nil, + temperature: Swift.Double? = nil, + tool_choice: Components.Schemas.ToolChoice? = nil, + tools: [Components.Schemas.Tool]? = nil, + top_k: Swift.Int? = nil, + top_p: Swift.Double? = nil + ) { + self.model = model + self.messages = messages + self.max_tokens = max_tokens + self.metadata = metadata + self.stop_sequences = stop_sequences + self.stream = stream + self.system = system + self.temperature = temperature + self.tool_choice = tool_choice + self.tools = tools + self.top_k = top_k + self.top_p = top_p + } + package enum CodingKeys: String, CodingKey { + case model + case messages + case max_tokens + case metadata + case stop_sequences + case stream + case system + case temperature + case tool_choice + case tools + case top_k + case top_p + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self.model = try container.decode( + Components.Schemas.Model.self, + forKey: .model + ) + self.messages = try container.decode( + [Components.Schemas.InputMessage].self, + forKey: .messages + ) + self.max_tokens = try container.decode( + Swift.Int.self, + forKey: .max_tokens + ) + self.metadata = try container.decodeIfPresent( + Components.Schemas.CreateMessageParams.metadataPayload.self, + forKey: .metadata + ) + self.stop_sequences = try container.decodeIfPresent( + [Swift.String].self, + forKey: .stop_sequences + ) + self.stream = try container.decodeIfPresent( + Swift.Bool.self, + forKey: .stream + ) + self.system = try container.decodeIfPresent( + Components.Schemas.CreateMessageParams.systemPayload.self, + forKey: .system + ) + self.temperature = try container.decodeIfPresent( + Swift.Double.self, + forKey: .temperature + ) + self.tool_choice = try container.decodeIfPresent( + Components.Schemas.ToolChoice.self, + forKey: .tool_choice + ) + self.tools = try container.decodeIfPresent( + [Components.Schemas.Tool].self, + forKey: .tools + ) + self.top_k = try container.decodeIfPresent( + Swift.Int.self, + forKey: .top_k + ) + self.top_p = try container.decodeIfPresent( + Swift.Double.self, + forKey: .top_p + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "model", + "messages", + "max_tokens", + "metadata", + "stop_sequences", + "stream", + "system", + "temperature", + "tool_choice", + "tools", + "top_k", + "top_p" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/ErrorResponse`. + package struct ErrorResponse: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ErrorResponse/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case error = "error" + } + /// - Remark: Generated from `#/components/schemas/ErrorResponse/type`. + package var _type: Components.Schemas.ErrorResponse._typePayload + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error`. + @frozen package enum errorPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/APIError`. + case api_error(Components.Schemas.APIError) + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/AuthenticationError`. + case authentication_error(Components.Schemas.AuthenticationError) + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/InvalidRequestError`. + case invalid_request_error(Components.Schemas.InvalidRequestError) + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/NotFoundError`. + case not_found_error(Components.Schemas.NotFoundError) + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/OverloadedError`. + case overloaded_error(Components.Schemas.OverloadedError) + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/PermissionError`. + case permission_error(Components.Schemas.PermissionError) + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error/RateLimitError`. + case rate_limit_error(Components.Schemas.RateLimitError) + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + let discriminator = try container.decode( + Swift.String.self, + forKey: ._type + ) + switch discriminator { + case "api_error": + self = .api_error(try .init(from: decoder)) + case "authentication_error": + self = .authentication_error(try .init(from: decoder)) + case "invalid_request_error": + self = .invalid_request_error(try .init(from: decoder)) + case "not_found_error": + self = .not_found_error(try .init(from: decoder)) + case "overloaded_error": + self = .overloaded_error(try .init(from: decoder)) + case "permission_error": + self = .permission_error(try .init(from: decoder)) + case "rate_limit_error": + self = .rate_limit_error(try .init(from: decoder)) + default: + throw Swift.DecodingError.unknownOneOfDiscriminator( + discriminatorKey: CodingKeys._type, + discriminatorValue: discriminator, + codingPath: decoder.codingPath + ) + } + } + package func encode(to encoder: any Swift.Encoder) throws { + switch self { + case let .api_error(value): + try value.encode(to: encoder) + case let .authentication_error(value): + try value.encode(to: encoder) + case let .invalid_request_error(value): + try value.encode(to: encoder) + case let .not_found_error(value): + try value.encode(to: encoder) + case let .overloaded_error(value): + try value.encode(to: encoder) + case let .permission_error(value): + try value.encode(to: encoder) + case let .rate_limit_error(value): + try value.encode(to: encoder) + } + } + } + /// - Remark: Generated from `#/components/schemas/ErrorResponse/error`. + package var error: Components.Schemas.ErrorResponse.errorPayload + /// Creates a new `ErrorResponse`. + /// + /// - Parameters: + /// - _type: + /// - error: + package init( + _type: Components.Schemas.ErrorResponse._typePayload, + error: Components.Schemas.ErrorResponse.errorPayload + ) { + self._type = _type + self.error = error + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case error + } + } + /// - Remark: Generated from `#/components/schemas/InputMessage`. + package struct InputMessage: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/InputMessage/role`. + @frozen package enum rolePayload: String, Codable, Hashable, Sendable, CaseIterable { + case user = "user" + case assistant = "assistant" + } + /// - Remark: Generated from `#/components/schemas/InputMessage/role`. + package var role: Components.Schemas.InputMessage.rolePayload + /// - Remark: Generated from `#/components/schemas/InputMessage/content`. + package struct contentPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/InputMessage/content/value1`. + package var value1: Swift.String? + /// - Remark: Generated from `#/components/schemas/InputMessage/content/Value2Payload`. + @frozen package enum Value2PayloadPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/InputMessage/content/Value2Payload/RequestImageBlock`. + case image(Components.Schemas.RequestImageBlock) + /// - Remark: Generated from `#/components/schemas/InputMessage/content/Value2Payload/RequestTextBlock`. + case text(Components.Schemas.RequestTextBlock) + /// - Remark: Generated from `#/components/schemas/InputMessage/content/Value2Payload/RequestToolResultBlock`. + case tool_result(Components.Schemas.RequestToolResultBlock) + /// - Remark: Generated from `#/components/schemas/InputMessage/content/Value2Payload/RequestToolUseBlock`. + case tool_use(Components.Schemas.RequestToolUseBlock) + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + let discriminator = try container.decode( + Swift.String.self, + forKey: ._type + ) + switch discriminator { + case "image": + self = .image(try .init(from: decoder)) + case "text": + self = .text(try .init(from: decoder)) + case "tool_result": + self = .tool_result(try .init(from: decoder)) + case "tool_use": + self = .tool_use(try .init(from: decoder)) + default: + throw Swift.DecodingError.unknownOneOfDiscriminator( + discriminatorKey: CodingKeys._type, + discriminatorValue: discriminator, + codingPath: decoder.codingPath + ) + } + } + package func encode(to encoder: any Swift.Encoder) throws { + switch self { + case let .image(value): + try value.encode(to: encoder) + case let .text(value): + try value.encode(to: encoder) + case let .tool_result(value): + try value.encode(to: encoder) + case let .tool_use(value): + try value.encode(to: encoder) + } + } + } + /// - Remark: Generated from `#/components/schemas/InputMessage/content/value2`. + package typealias Value2Payload = [Components.Schemas.InputMessage.contentPayload.Value2PayloadPayload] + /// - Remark: Generated from `#/components/schemas/InputMessage/content/value2`. + package var value2: Components.Schemas.InputMessage.contentPayload.Value2Payload? + /// Creates a new `contentPayload`. + /// + /// - Parameters: + /// - value1: + /// - value2: + package init( + value1: Swift.String? = nil, + value2: Components.Schemas.InputMessage.contentPayload.Value2Payload? = nil + ) { + self.value1 = value1 + self.value2 = value2 + } + package init(from decoder: any Swift.Decoder) throws { + var errors: [any Swift.Error] = [] + do { + self.value1 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + do { + self.value2 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + try Swift.DecodingError.verifyAtLeastOneSchemaIsNotNil( + [ + self.value1, + self.value2 + ], + type: Self.self, + codingPath: decoder.codingPath, + errors: errors + ) + } + package func encode(to encoder: any Swift.Encoder) throws { + try encoder.encodeFirstNonNilValueToSingleValueContainer([ + self.value1, + self.value2 + ]) + } + } + /// - Remark: Generated from `#/components/schemas/InputMessage/content`. + package var content: Components.Schemas.InputMessage.contentPayload + /// Creates a new `InputMessage`. + /// + /// - Parameters: + /// - role: + /// - content: + package init( + role: Components.Schemas.InputMessage.rolePayload, + content: Components.Schemas.InputMessage.contentPayload + ) { + self.role = role + self.content = content + } + package enum CodingKeys: String, CodingKey { + case role + case content + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self.role = try container.decode( + Components.Schemas.InputMessage.rolePayload.self, + forKey: .role + ) + self.content = try container.decode( + Components.Schemas.InputMessage.contentPayload.self, + forKey: .content + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "role", + "content" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/InputSchema`. + package struct InputSchema: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/InputSchema/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case object = "object" + } + /// - Remark: Generated from `#/components/schemas/InputSchema/type`. + package var _type: Components.Schemas.InputSchema._typePayload + /// A container of undocumented properties. + package var additionalProperties: OpenAPIRuntime.OpenAPIObjectContainer + /// Creates a new `InputSchema`. + /// + /// - Parameters: + /// - _type: + /// - additionalProperties: A container of undocumented properties. + package init( + _type: Components.Schemas.InputSchema._typePayload, + additionalProperties: OpenAPIRuntime.OpenAPIObjectContainer = .init() + ) { + self._type = _type + self.additionalProperties = additionalProperties + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.InputSchema._typePayload.self, + forKey: ._type + ) + additionalProperties = try decoder.decodeAdditionalProperties(knownKeys: [ + "type" + ]) + } + package func encode(to encoder: any Swift.Encoder) throws { + var container = encoder.container(keyedBy: CodingKeys.self) + try container.encode( + self._type, + forKey: ._type + ) + try encoder.encodeAdditionalProperties(additionalProperties) + } + } + /// - Remark: Generated from `#/components/schemas/InvalidRequestError`. + package struct InvalidRequestError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/InvalidRequestError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case invalid_request_error = "invalid_request_error" + } + /// - Remark: Generated from `#/components/schemas/InvalidRequestError/type`. + package var _type: Components.Schemas.InvalidRequestError._typePayload + /// - Remark: Generated from `#/components/schemas/InvalidRequestError/message`. + package var message: Swift.String + /// Creates a new `InvalidRequestError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.InvalidRequestError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/Message`. + package struct Message: Codable, Hashable, Sendable { + /// Unique object identifier. + /// + /// The format and length of IDs may change over time. + /// + /// - Remark: Generated from `#/components/schemas/Message/id`. + package var id: Swift.String + /// Object type. + /// + /// For Messages, this is always `"message"`. + /// + /// - Remark: Generated from `#/components/schemas/Message/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case message = "message" + } + /// Object type. + /// + /// For Messages, this is always `"message"`. + /// + /// - Remark: Generated from `#/components/schemas/Message/type`. + package var _type: Components.Schemas.Message._typePayload + /// Conversational role of the generated message. + /// + /// This will always be `"assistant"`. + /// + /// - Remark: Generated from `#/components/schemas/Message/role`. + @frozen package enum rolePayload: String, Codable, Hashable, Sendable, CaseIterable { + case assistant = "assistant" + } + /// Conversational role of the generated message. + /// + /// This will always be `"assistant"`. + /// + /// - Remark: Generated from `#/components/schemas/Message/role`. + package var role: Components.Schemas.Message.rolePayload + /// Content generated by the model. + /// + /// This is an array of content blocks, each of which has a `type` that determines its shape. + /// + /// Example: + /// + /// ```json + /// [{"type": "text", "text": "Hi, I'm Claude."}] + /// ``` + /// + /// If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + /// + /// For example, if the input `messages` were: + /// ```json + /// [ + /// {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + /// {"role": "assistant", "content": "The best answer is ("} + /// ] + /// ``` + /// + /// Then the response `content` might be: + /// + /// ```json + /// [{"type": "text", "text": "B)"}] + /// ``` + /// + /// - Remark: Generated from `#/components/schemas/Message/content`. + package var content: [Components.Schemas.ContentBlock] + /// - Remark: Generated from `#/components/schemas/Message/model`. + package var model: Components.Schemas.Model + /// Billing and rate-limit usage. + /// + /// Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + /// + /// Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + /// + /// For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + /// + /// - Remark: Generated from `#/components/schemas/Message/usage`. + package struct usagePayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/Message/usage/value1`. + package var value1: Components.Schemas.Usage + /// Creates a new `usagePayload`. + /// + /// - Parameters: + /// - value1: + package init(value1: Components.Schemas.Usage) { + self.value1 = value1 + } + package init(from decoder: any Swift.Decoder) throws { + self.value1 = try .init(from: decoder) + } + package func encode(to encoder: any Swift.Encoder) throws { + try self.value1.encode(to: encoder) + } + } + /// Billing and rate-limit usage. + /// + /// Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + /// + /// Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + /// + /// For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + /// + /// - Remark: Generated from `#/components/schemas/Message/usage`. + package var usage: Components.Schemas.Message.usagePayload + /// Creates a new `Message`. + /// + /// - Parameters: + /// - id: Unique object identifier. + /// - _type: Object type. + /// - role: Conversational role of the generated message. + /// - content: Content generated by the model. + /// - model: + /// - usage: Billing and rate-limit usage. + package init( + id: Swift.String, + _type: Components.Schemas.Message._typePayload, + role: Components.Schemas.Message.rolePayload, + content: [Components.Schemas.ContentBlock], + model: Components.Schemas.Model, + usage: Components.Schemas.Message.usagePayload + ) { + self.id = id + self._type = _type + self.role = role + self.content = content + self.model = model + self.usage = usage + } + package enum CodingKeys: String, CodingKey { + case id + case _type = "type" + case role + case content + case model + case usage + } + } + /// - Remark: Generated from `#/components/schemas/Metadata`. + package struct Metadata: Codable, Hashable, Sendable { + /// Creates a new `Metadata`. + package init() {} + package init(from decoder: any Swift.Decoder) throws { + try decoder.ensureNoAdditionalProperties(knownKeys: []) + } + } + /// - Remark: Generated from `#/components/schemas/NotFoundError`. + package struct NotFoundError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/NotFoundError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case not_found_error = "not_found_error" + } + /// - Remark: Generated from `#/components/schemas/NotFoundError/type`. + package var _type: Components.Schemas.NotFoundError._typePayload + /// - Remark: Generated from `#/components/schemas/NotFoundError/message`. + package var message: Swift.String + /// Creates a new `NotFoundError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.NotFoundError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/OverloadedError`. + package struct OverloadedError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/OverloadedError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case overloaded_error = "overloaded_error" + } + /// - Remark: Generated from `#/components/schemas/OverloadedError/type`. + package var _type: Components.Schemas.OverloadedError._typePayload + /// - Remark: Generated from `#/components/schemas/OverloadedError/message`. + package var message: Swift.String + /// Creates a new `OverloadedError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.OverloadedError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/PermissionError`. + package struct PermissionError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/PermissionError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case permission_error = "permission_error" + } + /// - Remark: Generated from `#/components/schemas/PermissionError/type`. + package var _type: Components.Schemas.PermissionError._typePayload + /// - Remark: Generated from `#/components/schemas/PermissionError/message`. + package var message: Swift.String + /// Creates a new `PermissionError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.PermissionError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/RateLimitError`. + package struct RateLimitError: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RateLimitError/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case rate_limit_error = "rate_limit_error" + } + /// - Remark: Generated from `#/components/schemas/RateLimitError/type`. + package var _type: Components.Schemas.RateLimitError._typePayload + /// - Remark: Generated from `#/components/schemas/RateLimitError/message`. + package var message: Swift.String + /// Creates a new `RateLimitError`. + /// + /// - Parameters: + /// - _type: + /// - message: + package init( + _type: Components.Schemas.RateLimitError._typePayload, + message: Swift.String + ) { + self._type = _type + self.message = message + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case message + } + } + /// - Remark: Generated from `#/components/schemas/RequestImageBlock`. + package struct RequestImageBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestImageBlock/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case image = "image" + } + /// - Remark: Generated from `#/components/schemas/RequestImageBlock/type`. + package var _type: Components.Schemas.RequestImageBlock._typePayload + /// - Remark: Generated from `#/components/schemas/RequestImageBlock/source`. + @frozen package enum sourcePayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestImageBlock/source/Base64ImageSource`. + case base64(Components.Schemas.Base64ImageSource) + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + let discriminator = try container.decode( + Swift.String.self, + forKey: ._type + ) + switch discriminator { + case "base64": + self = .base64(try .init(from: decoder)) + default: + throw Swift.DecodingError.unknownOneOfDiscriminator( + discriminatorKey: CodingKeys._type, + discriminatorValue: discriminator, + codingPath: decoder.codingPath + ) + } + } + package func encode(to encoder: any Swift.Encoder) throws { + switch self { + case let .base64(value): + try value.encode(to: encoder) + } + } + } + /// - Remark: Generated from `#/components/schemas/RequestImageBlock/source`. + package var source: Components.Schemas.RequestImageBlock.sourcePayload + /// Creates a new `RequestImageBlock`. + /// + /// - Parameters: + /// - _type: + /// - source: + package init( + _type: Components.Schemas.RequestImageBlock._typePayload, + source: Components.Schemas.RequestImageBlock.sourcePayload + ) { + self._type = _type + self.source = source + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case source + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.RequestImageBlock._typePayload.self, + forKey: ._type + ) + self.source = try container.decode( + Components.Schemas.RequestImageBlock.sourcePayload.self, + forKey: .source + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "source" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/RequestTextBlock`. + package struct RequestTextBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestTextBlock/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case text = "text" + } + /// - Remark: Generated from `#/components/schemas/RequestTextBlock/type`. + package var _type: Components.Schemas.RequestTextBlock._typePayload + /// - Remark: Generated from `#/components/schemas/RequestTextBlock/text`. + package var text: Swift.String + /// Creates a new `RequestTextBlock`. + /// + /// - Parameters: + /// - _type: + /// - text: + package init( + _type: Components.Schemas.RequestTextBlock._typePayload, + text: Swift.String + ) { + self._type = _type + self.text = text + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case text + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.RequestTextBlock._typePayload.self, + forKey: ._type + ) + self.text = try container.decode( + Swift.String.self, + forKey: .text + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "text" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock`. + package struct RequestToolResultBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case tool_result = "tool_result" + } + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/type`. + package var _type: Components.Schemas.RequestToolResultBlock._typePayload + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/tool_use_id`. + package var tool_use_id: Swift.String + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/is_error`. + package var is_error: Swift.Bool? + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content`. + package struct contentPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content/value1`. + package var value1: Swift.String? + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content/Value2Payload`. + @frozen package enum Value2PayloadPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content/Value2Payload/RequestImageBlock`. + case image(Components.Schemas.RequestImageBlock) + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content/Value2Payload/RequestTextBlock`. + case text(Components.Schemas.RequestTextBlock) + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + let discriminator = try container.decode( + Swift.String.self, + forKey: ._type + ) + switch discriminator { + case "image": + self = .image(try .init(from: decoder)) + case "text": + self = .text(try .init(from: decoder)) + default: + throw Swift.DecodingError.unknownOneOfDiscriminator( + discriminatorKey: CodingKeys._type, + discriminatorValue: discriminator, + codingPath: decoder.codingPath + ) + } + } + package func encode(to encoder: any Swift.Encoder) throws { + switch self { + case let .image(value): + try value.encode(to: encoder) + case let .text(value): + try value.encode(to: encoder) + } + } + } + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content/value2`. + package typealias Value2Payload = [Components.Schemas.RequestToolResultBlock.contentPayload.Value2PayloadPayload] + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content/value2`. + package var value2: Components.Schemas.RequestToolResultBlock.contentPayload.Value2Payload? + /// Creates a new `contentPayload`. + /// + /// - Parameters: + /// - value1: + /// - value2: + package init( + value1: Swift.String? = nil, + value2: Components.Schemas.RequestToolResultBlock.contentPayload.Value2Payload? = nil + ) { + self.value1 = value1 + self.value2 = value2 + } + package init(from decoder: any Swift.Decoder) throws { + var errors: [any Swift.Error] = [] + do { + self.value1 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + do { + self.value2 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + try Swift.DecodingError.verifyAtLeastOneSchemaIsNotNil( + [ + self.value1, + self.value2 + ], + type: Self.self, + codingPath: decoder.codingPath, + errors: errors + ) + } + package func encode(to encoder: any Swift.Encoder) throws { + try encoder.encodeFirstNonNilValueToSingleValueContainer([ + self.value1, + self.value2 + ]) + } + } + /// - Remark: Generated from `#/components/schemas/RequestToolResultBlock/content`. + package var content: Components.Schemas.RequestToolResultBlock.contentPayload? + /// Creates a new `RequestToolResultBlock`. + /// + /// - Parameters: + /// - _type: + /// - tool_use_id: + /// - is_error: + /// - content: + package init( + _type: Components.Schemas.RequestToolResultBlock._typePayload, + tool_use_id: Swift.String, + is_error: Swift.Bool? = nil, + content: Components.Schemas.RequestToolResultBlock.contentPayload? = nil + ) { + self._type = _type + self.tool_use_id = tool_use_id + self.is_error = is_error + self.content = content + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case tool_use_id + case is_error + case content + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.RequestToolResultBlock._typePayload.self, + forKey: ._type + ) + self.tool_use_id = try container.decode( + Swift.String.self, + forKey: .tool_use_id + ) + self.is_error = try container.decodeIfPresent( + Swift.Bool.self, + forKey: .is_error + ) + self.content = try container.decodeIfPresent( + Components.Schemas.RequestToolResultBlock.contentPayload.self, + forKey: .content + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "tool_use_id", + "is_error", + "content" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/RequestToolUseBlock`. + package struct RequestToolUseBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/RequestToolUseBlock/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case tool_use = "tool_use" + } + /// - Remark: Generated from `#/components/schemas/RequestToolUseBlock/type`. + package var _type: Components.Schemas.RequestToolUseBlock._typePayload + /// - Remark: Generated from `#/components/schemas/RequestToolUseBlock/id`. + package var id: Swift.String + /// - Remark: Generated from `#/components/schemas/RequestToolUseBlock/name`. + package var name: Swift.String + /// - Remark: Generated from `#/components/schemas/RequestToolUseBlock/input`. + package var input: OpenAPIRuntime.OpenAPIObjectContainer + /// Creates a new `RequestToolUseBlock`. + /// + /// - Parameters: + /// - _type: + /// - id: + /// - name: + /// - input: + package init( + _type: Components.Schemas.RequestToolUseBlock._typePayload, + id: Swift.String, + name: Swift.String, + input: OpenAPIRuntime.OpenAPIObjectContainer + ) { + self._type = _type + self.id = id + self.name = name + self.input = input + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case id + case name + case input + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.RequestToolUseBlock._typePayload.self, + forKey: ._type + ) + self.id = try container.decode( + Swift.String.self, + forKey: .id + ) + self.name = try container.decode( + Swift.String.self, + forKey: .name + ) + self.input = try container.decode( + OpenAPIRuntime.OpenAPIObjectContainer.self, + forKey: .input + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "id", + "name", + "input" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/ResponseTextBlock`. + package struct ResponseTextBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ResponseTextBlock/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case text = "text" + } + /// - Remark: Generated from `#/components/schemas/ResponseTextBlock/type`. + package var _type: Components.Schemas.ResponseTextBlock._typePayload + /// - Remark: Generated from `#/components/schemas/ResponseTextBlock/text`. + package var text: Swift.String + /// Creates a new `ResponseTextBlock`. + /// + /// - Parameters: + /// - _type: + /// - text: + package init( + _type: Components.Schemas.ResponseTextBlock._typePayload, + text: Swift.String + ) { + self._type = _type + self.text = text + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case text + } + } + /// - Remark: Generated from `#/components/schemas/ResponseToolUseBlock`. + package struct ResponseToolUseBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ResponseToolUseBlock/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case tool_use = "tool_use" + } + /// - Remark: Generated from `#/components/schemas/ResponseToolUseBlock/type`. + package var _type: Components.Schemas.ResponseToolUseBlock._typePayload + /// - Remark: Generated from `#/components/schemas/ResponseToolUseBlock/id`. + package var id: Swift.String + /// - Remark: Generated from `#/components/schemas/ResponseToolUseBlock/name`. + package var name: Swift.String + /// - Remark: Generated from `#/components/schemas/ResponseToolUseBlock/input`. + package var input: OpenAPIRuntime.OpenAPIObjectContainer + /// Creates a new `ResponseToolUseBlock`. + /// + /// - Parameters: + /// - _type: + /// - id: + /// - name: + /// - input: + package init( + _type: Components.Schemas.ResponseToolUseBlock._typePayload, + id: Swift.String, + name: Swift.String, + input: OpenAPIRuntime.OpenAPIObjectContainer + ) { + self._type = _type + self.id = id + self.name = name + self.input = input + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case id + case name + case input + } + } + /// - Remark: Generated from `#/components/schemas/Tool`. + package struct Tool: Codable, Hashable, Sendable { + /// Description of what this tool does. + /// + /// Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + /// + /// - Remark: Generated from `#/components/schemas/Tool/description`. + package var description: Swift.String? + /// Name of the tool. + /// + /// This is how the tool will be called by the model and in tool_use blocks. + /// + /// - Remark: Generated from `#/components/schemas/Tool/name`. + package var name: Swift.String + /// [JSON schema](https://json-schema.org/) for this tool's input. + /// + /// This defines the shape of the `input` that your tool accepts and that the model will produce. + /// + /// - Remark: Generated from `#/components/schemas/Tool/input_schema`. + package struct input_schemaPayload: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/Tool/input_schema/value1`. + package var value1: Components.Schemas.InputSchema + /// Creates a new `input_schemaPayload`. + /// + /// - Parameters: + /// - value1: + package init(value1: Components.Schemas.InputSchema) { + self.value1 = value1 + } + package init(from decoder: any Swift.Decoder) throws { + self.value1 = try .init(from: decoder) + } + package func encode(to encoder: any Swift.Encoder) throws { + try self.value1.encode(to: encoder) + } + } + /// [JSON schema](https://json-schema.org/) for this tool's input. + /// + /// This defines the shape of the `input` that your tool accepts and that the model will produce. + /// + /// - Remark: Generated from `#/components/schemas/Tool/input_schema`. + package var input_schema: Components.Schemas.Tool.input_schemaPayload + /// Creates a new `Tool`. + /// + /// - Parameters: + /// - description: Description of what this tool does. + /// - name: Name of the tool. + /// - input_schema: [JSON schema](https://json-schema.org/) for this tool's input. + package init( + description: Swift.String? = nil, + name: Swift.String, + input_schema: Components.Schemas.Tool.input_schemaPayload + ) { + self.description = description + self.name = name + self.input_schema = input_schema + } + package enum CodingKeys: String, CodingKey { + case description + case name + case input_schema + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self.description = try container.decodeIfPresent( + Swift.String.self, + forKey: .description + ) + self.name = try container.decode( + Swift.String.self, + forKey: .name + ) + self.input_schema = try container.decode( + Components.Schemas.Tool.input_schemaPayload.self, + forKey: .input_schema + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "description", + "name", + "input_schema" + ]) + } + } + /// The model will use any available tools. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceAny`. + package struct ToolChoiceAny: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ToolChoiceAny/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case any = "any" + } + /// - Remark: Generated from `#/components/schemas/ToolChoiceAny/type`. + package var _type: Components.Schemas.ToolChoiceAny._typePayload + /// Whether to disable parallel tool use. + /// + /// Defaults to `false`. If set to `true`, the model will output exactly one tool use. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceAny/disable_parallel_tool_use`. + package var disable_parallel_tool_use: Swift.Bool? + /// Creates a new `ToolChoiceAny`. + /// + /// - Parameters: + /// - _type: + /// - disable_parallel_tool_use: Whether to disable parallel tool use. + package init( + _type: Components.Schemas.ToolChoiceAny._typePayload, + disable_parallel_tool_use: Swift.Bool? = nil + ) { + self._type = _type + self.disable_parallel_tool_use = disable_parallel_tool_use + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case disable_parallel_tool_use + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.ToolChoiceAny._typePayload.self, + forKey: ._type + ) + self.disable_parallel_tool_use = try container.decodeIfPresent( + Swift.Bool.self, + forKey: .disable_parallel_tool_use + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "disable_parallel_tool_use" + ]) + } + } + /// The model will automatically decide whether to use tools. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceAuto`. + package struct ToolChoiceAuto: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ToolChoiceAuto/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case auto = "auto" + } + /// - Remark: Generated from `#/components/schemas/ToolChoiceAuto/type`. + package var _type: Components.Schemas.ToolChoiceAuto._typePayload + /// Whether to disable parallel tool use. + /// + /// Defaults to `false`. If set to `true`, the model will output at most one tool use. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceAuto/disable_parallel_tool_use`. + package var disable_parallel_tool_use: Swift.Bool? + /// Creates a new `ToolChoiceAuto`. + /// + /// - Parameters: + /// - _type: + /// - disable_parallel_tool_use: Whether to disable parallel tool use. + package init( + _type: Components.Schemas.ToolChoiceAuto._typePayload, + disable_parallel_tool_use: Swift.Bool? = nil + ) { + self._type = _type + self.disable_parallel_tool_use = disable_parallel_tool_use + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case disable_parallel_tool_use + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.ToolChoiceAuto._typePayload.self, + forKey: ._type + ) + self.disable_parallel_tool_use = try container.decodeIfPresent( + Swift.Bool.self, + forKey: .disable_parallel_tool_use + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "disable_parallel_tool_use" + ]) + } + } + /// The model will use the specified tool with `tool_choice.name`. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceTool`. + package struct ToolChoiceTool: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ToolChoiceTool/type`. + @frozen package enum _typePayload: String, Codable, Hashable, Sendable, CaseIterable { + case tool = "tool" + } + /// - Remark: Generated from `#/components/schemas/ToolChoiceTool/type`. + package var _type: Components.Schemas.ToolChoiceTool._typePayload + /// The name of the tool to use. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceTool/name`. + package var name: Swift.String + /// Whether to disable parallel tool use. + /// + /// Defaults to `false`. If set to `true`, the model will output exactly one tool use. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoiceTool/disable_parallel_tool_use`. + package var disable_parallel_tool_use: Swift.Bool? + /// Creates a new `ToolChoiceTool`. + /// + /// - Parameters: + /// - _type: + /// - name: The name of the tool to use. + /// - disable_parallel_tool_use: Whether to disable parallel tool use. + package init( + _type: Components.Schemas.ToolChoiceTool._typePayload, + name: Swift.String, + disable_parallel_tool_use: Swift.Bool? = nil + ) { + self._type = _type + self.name = name + self.disable_parallel_tool_use = disable_parallel_tool_use + } + package enum CodingKeys: String, CodingKey { + case _type = "type" + case name + case disable_parallel_tool_use + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self._type = try container.decode( + Components.Schemas.ToolChoiceTool._typePayload.self, + forKey: ._type + ) + self.name = try container.decode( + Swift.String.self, + forKey: .name + ) + self.disable_parallel_tool_use = try container.decodeIfPresent( + Swift.Bool.self, + forKey: .disable_parallel_tool_use + ) + try decoder.ensureNoAdditionalProperties(knownKeys: [ + "type", + "name", + "disable_parallel_tool_use" + ]) + } + } + /// - Remark: Generated from `#/components/schemas/Usage`. + package struct Usage: Codable, Hashable, Sendable { + /// The number of input tokens which were used. + /// + /// - Remark: Generated from `#/components/schemas/Usage/input_tokens`. + package var input_tokens: Swift.Int + /// The number of output tokens which were used. + /// + /// - Remark: Generated from `#/components/schemas/Usage/output_tokens`. + package var output_tokens: Swift.Int + /// Creates a new `Usage`. + /// + /// - Parameters: + /// - input_tokens: The number of input tokens which were used. + /// - output_tokens: The number of output tokens which were used. + package init( + input_tokens: Swift.Int, + output_tokens: Swift.Int + ) { + self.input_tokens = input_tokens + self.output_tokens = output_tokens + } + package enum CodingKeys: String, CodingKey { + case input_tokens + case output_tokens + } + } + /// How the model should use the provided tools. The model can use a specific tool, any available tool, or decide by itself. + /// + /// - Remark: Generated from `#/components/schemas/ToolChoice`. + @frozen package enum ToolChoice: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ToolChoice/ToolChoiceAny`. + case any(Components.Schemas.ToolChoiceAny) + /// - Remark: Generated from `#/components/schemas/ToolChoice/ToolChoiceAuto`. + case auto(Components.Schemas.ToolChoiceAuto) + /// - Remark: Generated from `#/components/schemas/ToolChoice/ToolChoiceTool`. + case tool(Components.Schemas.ToolChoiceTool) + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + let discriminator = try container.decode( + Swift.String.self, + forKey: ._type + ) + switch discriminator { + case "any": + self = .any(try .init(from: decoder)) + case "auto": + self = .auto(try .init(from: decoder)) + case "tool": + self = .tool(try .init(from: decoder)) + default: + throw Swift.DecodingError.unknownOneOfDiscriminator( + discriminatorKey: CodingKeys._type, + discriminatorValue: discriminator, + codingPath: decoder.codingPath + ) + } + } + package func encode(to encoder: any Swift.Encoder) throws { + switch self { + case let .any(value): + try value.encode(to: encoder) + case let .auto(value): + try value.encode(to: encoder) + case let .tool(value): + try value.encode(to: encoder) + } + } + } + /// - Remark: Generated from `#/components/schemas/ContentBlock`. + @frozen package enum ContentBlock: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ContentBlock/ResponseTextBlock`. + case text(Components.Schemas.ResponseTextBlock) + /// - Remark: Generated from `#/components/schemas/ContentBlock/ResponseToolUseBlock`. + case tool_use(Components.Schemas.ResponseToolUseBlock) + package enum CodingKeys: String, CodingKey { + case _type = "type" + } + package init(from decoder: any Swift.Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + let discriminator = try container.decode( + Swift.String.self, + forKey: ._type + ) + switch discriminator { + case "text": + self = .text(try .init(from: decoder)) + case "tool_use": + self = .tool_use(try .init(from: decoder)) + default: + throw Swift.DecodingError.unknownOneOfDiscriminator( + discriminatorKey: CodingKeys._type, + discriminatorValue: discriminator, + codingPath: decoder.codingPath + ) + } + } + package func encode(to encoder: any Swift.Encoder) throws { + switch self { + case let .text(value): + try value.encode(to: encoder) + case let .tool_use(value): + try value.encode(to: encoder) + } + } + } + /// The model that will complete your prompt.\n\nSee [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + /// + /// - Remark: Generated from `#/components/schemas/Model`. + package struct Model: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/Model/value1`. + package var value1: Swift.String? + /// - Remark: Generated from `#/components/schemas/Model/value2`. + @frozen package enum Value2Payload: String, Codable, Hashable, Sendable, CaseIterable { + case claude_hyphen_3_hyphen_5_hyphen_sonnet_hyphen_latest = "claude-3-5-sonnet-latest" + case claude_hyphen_3_hyphen_5_hyphen_sonnet_hyphen_20241022 = "claude-3-5-sonnet-20241022" + case claude_hyphen_3_hyphen_5_hyphen_sonnet_hyphen_20240620 = "claude-3-5-sonnet-20240620" + case claude_hyphen_3_hyphen_opus_hyphen_latest = "claude-3-opus-latest" + case claude_hyphen_3_hyphen_opus_hyphen_20240229 = "claude-3-opus-20240229" + case claude_hyphen_3_hyphen_sonnet_hyphen_20240229 = "claude-3-sonnet-20240229" + case claude_hyphen_3_hyphen_haiku_hyphen_20240307 = "claude-3-haiku-20240307" + case claude_hyphen_2_period_1 = "claude-2.1" + case claude_hyphen_2_period_0 = "claude-2.0" + case claude_hyphen_instant_hyphen_1_period_2 = "claude-instant-1.2" + } + /// - Remark: Generated from `#/components/schemas/Model/value2`. + package var value2: Components.Schemas.Model.Value2Payload? + /// Creates a new `Model`. + /// + /// - Parameters: + /// - value1: + /// - value2: + package init( + value1: Swift.String? = nil, + value2: Components.Schemas.Model.Value2Payload? = nil + ) { + self.value1 = value1 + self.value2 = value2 + } + package init(from decoder: any Swift.Decoder) throws { + var errors: [any Swift.Error] = [] + do { + self.value1 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + do { + self.value2 = try decoder.decodeFromSingleValueContainer() + } catch { + errors.append(error) + } + try Swift.DecodingError.verifyAtLeastOneSchemaIsNotNil( + [ + self.value1, + self.value2 + ], + type: Self.self, + codingPath: decoder.codingPath, + errors: errors + ) + } + package func encode(to encoder: any Swift.Encoder) throws { + try encoder.encodeFirstNonNilValueToSingleValueContainer([ + self.value1, + self.value2 + ]) + } + } + } + /// Types generated from the `#/components/parameters` section of the OpenAPI document. + package enum Parameters {} + /// Types generated from the `#/components/requestBodies` section of the OpenAPI document. + package enum RequestBodies {} + /// Types generated from the `#/components/responses` section of the OpenAPI document. + package enum Responses {} + /// Types generated from the `#/components/headers` section of the OpenAPI document. + package enum Headers {} +} + +/// API operations, with input and output types, generated from `#/paths` in the OpenAPI document. +package enum Operations { + /// Create a Message + /// + /// Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + /// + /// The Messages API can be used for either single queries or stateless multi-turn conversations. + /// + /// - Remark: HTTP `POST /v1/messages`. + /// - Remark: Generated from `#/paths//v1/messages/post(messages_post)`. + package enum messages_post { + package static let id: Swift.String = "messages_post" + package struct Input: Sendable, Hashable { + /// - Remark: Generated from `#/paths/v1/messages/POST/header`. + package struct Headers: Sendable, Hashable { + /// The version of the Anthropic API you want to use. + /// + /// Read more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning). + /// + /// - Remark: Generated from `#/paths/v1/messages/POST/header/anthropic-version`. + package var anthropic_hyphen_version: Swift.String? + /// Your unique API key for authentication. + /// + /// This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace. + /// + /// - Remark: Generated from `#/paths/v1/messages/POST/header/x-api-key`. + package var x_hyphen_api_hyphen_key: Swift.String? + package var accept: [OpenAPIRuntime.AcceptHeaderContentType<Operations.messages_post.AcceptableContentType>] + /// Creates a new `Headers`. + /// + /// - Parameters: + /// - anthropic_hyphen_version: The version of the Anthropic API you want to use. + /// - x_hyphen_api_hyphen_key: Your unique API key for authentication. + /// - accept: + package init( + anthropic_hyphen_version: Swift.String? = nil, + x_hyphen_api_hyphen_key: Swift.String? = nil, + accept: [OpenAPIRuntime.AcceptHeaderContentType<Operations.messages_post.AcceptableContentType>] = .defaultValues() + ) { + self.anthropic_hyphen_version = anthropic_hyphen_version + self.x_hyphen_api_hyphen_key = x_hyphen_api_hyphen_key + self.accept = accept + } + } + package var headers: Operations.messages_post.Input.Headers + /// - Remark: Generated from `#/paths/v1/messages/POST/requestBody`. + @frozen package enum Body: Sendable, Hashable { + /// - Remark: Generated from `#/paths/v1/messages/POST/requestBody/content/application\/json`. + case json(Components.Schemas.CreateMessageParams) + } + package var body: Operations.messages_post.Input.Body + /// Creates a new `Input`. + /// + /// - Parameters: + /// - headers: + /// - body: + package init( + headers: Operations.messages_post.Input.Headers = .init(), + body: Operations.messages_post.Input.Body + ) { + self.headers = headers + self.body = body + } + } + @frozen package enum Output: Sendable, Hashable { + package struct Ok: Sendable, Hashable { + /// - Remark: Generated from `#/paths/v1/messages/POST/responses/200/content`. + @frozen package enum Body: Sendable, Hashable { + /// - Remark: Generated from `#/paths/v1/messages/POST/responses/200/content/application\/json`. + case json(Components.Schemas.Message) + /// The associated value of the enum case if `self` is `.json`. + /// + /// - Throws: An error if `self` is not `.json`. + /// - SeeAlso: `.json`. + package var json: Components.Schemas.Message { + get throws { + switch self { + case let .json(body): + return body + } + } + } + } + /// Received HTTP response body + package var body: Operations.messages_post.Output.Ok.Body + /// Creates a new `Ok`. + /// + /// - Parameters: + /// - body: Received HTTP response body + package init(body: Operations.messages_post.Output.Ok.Body) { + self.body = body + } + } + /// Message object. + /// + /// - Remark: Generated from `#/paths//v1/messages/post(messages_post)/responses/200`. + /// + /// HTTP response code: `200 ok`. + case ok(Operations.messages_post.Output.Ok) + /// The associated value of the enum case if `self` is `.ok`. + /// + /// - Throws: An error if `self` is not `.ok`. + /// - SeeAlso: `.ok`. + package var ok: Operations.messages_post.Output.Ok { + get throws { + switch self { + case let .ok(response): + return response + default: + try throwUnexpectedResponseStatus( + expectedStatus: "ok", + response: self + ) + } + } + } + package struct ClientError: Sendable, Hashable { + /// - Remark: Generated from `#/paths/v1/messages/POST/responses/4XX/content`. + @frozen package enum Body: Sendable, Hashable { + /// - Remark: Generated from `#/paths/v1/messages/POST/responses/4XX/content/application\/json`. + case json(Components.Schemas.ErrorResponse) + /// The associated value of the enum case if `self` is `.json`. + /// + /// - Throws: An error if `self` is not `.json`. + /// - SeeAlso: `.json`. + package var json: Components.Schemas.ErrorResponse { + get throws { + switch self { + case let .json(body): + return body + } + } + } + } + /// Received HTTP response body + package var body: Operations.messages_post.Output.ClientError.Body + /// Creates a new `ClientError`. + /// + /// - Parameters: + /// - body: Received HTTP response body + package init(body: Operations.messages_post.Output.ClientError.Body) { + self.body = body + } + } + /// Error response. + /// + /// See our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details. + /// + /// - Remark: Generated from `#/paths//v1/messages/post(messages_post)/responses/4XX`. + /// + /// HTTP response code: `400...499 clientError`. + case clientError(statusCode: Swift.Int, Operations.messages_post.Output.ClientError) + /// The associated value of the enum case if `self` is `.clientError`. + /// + /// - Throws: An error if `self` is not `.clientError`. + /// - SeeAlso: `.clientError`. + package var clientError: Operations.messages_post.Output.ClientError { + get throws { + switch self { + case let .clientError(_, response): + return response + default: + try throwUnexpectedResponseStatus( + expectedStatus: "clientError", + response: self + ) + } + } + } + /// Undocumented response. + /// + /// A response with a code that is not documented in the OpenAPI document. + case undocumented(statusCode: Swift.Int, OpenAPIRuntime.UndocumentedPayload) + } + @frozen package enum AcceptableContentType: AcceptableProtocol { + case json + case other(Swift.String) + package init?(rawValue: Swift.String) { + switch rawValue.lowercased() { + case "application/json": + self = .json + default: + self = .other(rawValue) + } + } + package var rawValue: Swift.String { + switch self { + case let .other(string): + return string + case .json: + return "application/json" + } + } + package static var allCases: [Self] { + [ + .json + ] + } + } + } +} diff --git a/Sources/ClaudeKit/openapi-generator-config.yaml b/Sources/ClaudeKit/openapi-generator-config.yaml new file mode 100644 index 00000000..ed190eac --- /dev/null +++ b/Sources/ClaudeKit/openapi-generator-config.yaml @@ -0,0 +1,10 @@ +generate: + - types + - client +accessModifier: package +additionalFileComments: + - periphery:ignore:all + - swift-format-ignore-file +filter: + paths: + - /v1/messages diff --git a/Sources/ClaudeKit/openapi.json b/Sources/ClaudeKit/openapi.json new file mode 100644 index 00000000..ac231f3b --- /dev/null +++ b/Sources/ClaudeKit/openapi.json @@ -0,0 +1,6428 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Anthropic API", + "version": "0.0.0" + }, + "paths": { + "/v1/messages": { + "post": { + "tags": [ + "Messages" + ], + "summary": "Create a Message", + "description": "Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.\n\nThe Messages API can be used for either single queries or stateless multi-turn conversations.", + "operationId": "messages_post", + "parameters": [ + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Message object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Message" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateMessageParams" + } + } + }, + "required": true + } + } + }, + "/v1/complete": { + "post": { + "tags": [ + "Text Completions" + ], + "summary": "Create a Text Completion", + "description": "[Legacy] Create a Text Completion.\n\nThe Text Completions API is a legacy API. We recommend using the [Messages API](https://docs.anthropic.com/en/api/messages) going forward.\n\nFuture models and features will not be compatible with Text Completions. See our [migration guide](https://docs.anthropic.com/en/api/migrating-from-text-completions-to-messages) for guidance in migrating from Text Completions to Messages.", + "operationId": "complete_post", + "parameters": [ + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Text Completion object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionResponse" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionRequest" + } + } + }, + "required": true + } + } + }, + "/v1/messages?beta=true": { + "post": { + "tags": [ + "Messages" + ], + "summary": "Create a Message", + "description": "Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.\n\nThe Messages API can be used for either single queries or stateless multi-turn conversations.", + "operationId": "beta_messages_post", + "parameters": [ + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Message object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessage" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCreateMessageParams" + } + } + }, + "required": true + } + } + }, + "/v1/messages/batches?beta=true": { + "post": { + "tags": [ + "Message Batches" + ], + "summary": "Create a Message Batch", + "description": "Send a batch of Message creation requests.\n\nThe Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.", + "operationId": "beta_message_batches_post", + "parameters": [ + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessageBatch" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCreateMessageBatchParams" + } + } + }, + "required": true + } + }, + "get": { + "tags": [ + "Message Batches" + ], + "summary": "List Message Batches", + "description": "List all Message Batches within a Workspace. Most recently created batches are returned first.", + "operationId": "beta_message_batches_list", + "parameters": [ + { + "name": "before_id", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.", + "title": "Before Id" + }, + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object." + }, + { + "name": "after_id", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.", + "title": "After Id" + }, + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "description": "Number of items to return per page.\n\nDefaults to `20`. Ranges from `1` to `100`.", + "default": 20, + "title": "Limit" + }, + "description": "Number of items to return per page.\n\nDefaults to `20`. Ranges from `1` to `100`." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaListResponse_MessageBatch_" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/batches/{message_batch_id}?beta=true": { + "get": { + "tags": [ + "Message Batches" + ], + "summary": "Retrieve a Message Batch", + "description": "This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response.", + "operationId": "beta_message_batches_retrieve", + "parameters": [ + { + "name": "message_batch_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "ID of the Message Batch.", + "title": "Message Batch Id" + }, + "description": "ID of the Message Batch." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessageBatch" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/batches/{message_batch_id}/cancel?beta=true": { + "post": { + "tags": [ + "Message Batches" + ], + "summary": "Cancel a Message Batch", + "description": "Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.\n\nThe number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.", + "operationId": "beta_message_batches_cancel", + "parameters": [ + { + "name": "message_batch_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "ID of the Message Batch.", + "title": "Message Batch Id" + }, + "description": "ID of the Message Batch." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessageBatch" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/batches/{message_batch_id}/results?beta=true": { + "get": { + "tags": [ + "Message Batches" + ], + "summary": "Retrieve Message Batch results", + "description": "Streams the results of a Message Batch as a `.jsonl` file.\n\nEach line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.", + "operationId": "beta_message_batches_results", + "parameters": [ + { + "name": "message_batch_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "ID of the Message Batch.", + "title": "Message Batch Id" + }, + "description": "ID of the Message Batch." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/x-jsonl": { + "schema": { + "type": "string", + "format": "binary", + "x-line-schema": { + "$ref": "#/components/schemas/BetaMessageBatchIndividualResponse" + } + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/count_tokens?beta=true": { + "post": { + "tags": [ + "Messages" + ], + "summary": "Count tokens in a Message", + "description": "Count the number of tokens in a Message.\n\nThe Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.", + "operationId": "beta_messages_count_tokens_post", + "parameters": [ + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCountMessageTokensResponse" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCountMessageTokensParams" + } + } + }, + "required": true + } + } + }, + "/v1/messages?beta=prompt_caching": { + "post": { + "tags": [ + "Messages" + ], + "summary": "Create a Message", + "description": "Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.\n\nThe Messages API can be used for either single queries or stateless multi-turn conversations.", + "operationId": "prompt_caching_beta_messages_post", + "parameters": [ + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Message object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PromptCachingBetaMessage" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PromptCachingBetaCreateMessageParams" + } + } + }, + "required": true + } + } + }, + "/v1/messages/batches": { + "post": { + "tags": [ + "Message Batches" + ], + "summary": "Create a Message Batch", + "description": "Send a batch of Message creation requests.\n\nThe Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.", + "operationId": "beta_message_batches_post", + "parameters": [ + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessageBatch" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCreateMessageBatchParams" + } + } + }, + "required": true + } + }, + "get": { + "tags": [ + "Message Batches" + ], + "summary": "List Message Batches", + "description": "List all Message Batches within a Workspace. Most recently created batches are returned first.", + "operationId": "beta_message_batches_list", + "parameters": [ + { + "name": "before_id", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.", + "title": "Before Id" + }, + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object." + }, + { + "name": "after_id", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.", + "title": "After Id" + }, + "description": "ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "description": "Number of items to return per page.\n\nDefaults to `20`. Ranges from `1` to `100`.", + "default": 20, + "title": "Limit" + }, + "description": "Number of items to return per page.\n\nDefaults to `20`. Ranges from `1` to `100`." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaListResponse_MessageBatch_" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/batches/{message_batch_id}": { + "get": { + "tags": [ + "Message Batches" + ], + "summary": "Retrieve a Message Batch", + "description": "This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response.", + "operationId": "beta_message_batches_retrieve", + "parameters": [ + { + "name": "message_batch_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "ID of the Message Batch.", + "title": "Message Batch Id" + }, + "description": "ID of the Message Batch." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessageBatch" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/batches/{message_batch_id}/cancel": { + "post": { + "tags": [ + "Message Batches" + ], + "summary": "Cancel a Message Batch", + "description": "Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.\n\nThe number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.", + "operationId": "beta_message_batches_cancel", + "parameters": [ + { + "name": "message_batch_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "ID of the Message Batch.", + "title": "Message Batch Id" + }, + "description": "ID of the Message Batch." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaMessageBatch" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/batches/{message_batch_id}/results": { + "get": { + "tags": [ + "Message Batches" + ], + "summary": "Retrieve Message Batch results", + "description": "Streams the results of a Message Batch as a `.jsonl` file.\n\nEach line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.", + "operationId": "beta_message_batches_results", + "parameters": [ + { + "name": "message_batch_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "ID of the Message Batch.", + "title": "Message Batch Id" + }, + "description": "ID of the Message Batch." + }, + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/x-jsonl": { + "schema": { + "type": "string", + "format": "binary", + "x-line-schema": { + "$ref": "#/components/schemas/BetaMessageBatchIndividualResponse" + } + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + } + } + }, + "/v1/messages/count_tokens": { + "post": { + "tags": [ + "Messages" + ], + "summary": "Count tokens in a Message", + "description": "Count the number of tokens in a Message.\n\nThe Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.", + "operationId": "beta_messages_count_tokens_post", + "parameters": [ + { + "name": "anthropic-beta", + "in": "header", + "required": false, + "schema": { + "type": "string", + "items": { + "type": "string" + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.", + "title": "Anthropic-Beta", + "x-stainless-override-schema": { + "x-stainless-param": "betas", + "x-stainless-extend-default": true, + "type": "array", + "description": "Optional header to specify the beta version(s) you want to use.", + "items": { + "$ref": "#/components/schemas/AnthropicBeta" + } + } + }, + "description": "Optional header to specify the beta version(s) you want to use.\n\nTo use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta." + }, + { + "name": "anthropic-version", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning).", + "title": "Anthropic-Version" + }, + "description": "The version of the Anthropic API you want to use.\n\nRead more about versioning and our version history [here](https://docs.anthropic.com/en/api/versioning)." + }, + { + "name": "x-api-key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.", + "title": "X-Api-Key" + }, + "description": "Your unique API key for authentication. \n\nThis key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCountMessageTokensResponse" + } + } + } + }, + "4XX": { + "description": "Error response.\n\nSee our [errors documentation](https://docs.anthropic.com/en/api/errors) for more details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BetaCountMessageTokensParams" + } + } + }, + "required": true + } + } + } + }, + "components": { + "schemas": { + "APIError": { + "properties": { + "type": { + "const": "api_error", + "default": "api_error", + "enum": [ + "api_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Internal server error", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "APIError", + "type": "object" + }, + "AuthenticationError": { + "properties": { + "type": { + "const": "authentication_error", + "default": "authentication_error", + "enum": [ + "authentication_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Authentication error", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "AuthenticationError", + "type": "object" + }, + "Base64ImageSource": { + "additionalProperties": false, + "properties": { + "type": { + "const": "base64", + "enum": [ + "base64" + ], + "title": "Type", + "type": "string" + }, + "media_type": { + "enum": [ + "image/jpeg", + "image/png", + "image/gif", + "image/webp" + ], + "title": "Media Type", + "type": "string" + }, + "data": { + "format": "byte", + "title": "Data", + "type": "string" + } + }, + "required": [ + "type", + "media_type", + "data" + ], + "title": "Base64ImageSource", + "type": "object" + }, + "BetaAPIError": { + "properties": { + "type": { + "const": "api_error", + "default": "api_error", + "enum": [ + "api_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Internal server error", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "APIError", + "type": "object" + }, + "BetaAuthenticationError": { + "properties": { + "type": { + "const": "authentication_error", + "default": "authentication_error", + "enum": [ + "authentication_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Authentication error", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "AuthenticationError", + "type": "object" + }, + "BetaBase64ImageSource": { + "additionalProperties": false, + "properties": { + "type": { + "const": "base64", + "enum": [ + "base64" + ], + "title": "Type", + "type": "string" + }, + "media_type": { + "enum": [ + "image/jpeg", + "image/png", + "image/gif", + "image/webp" + ], + "title": "Media Type", + "type": "string" + }, + "data": { + "format": "byte", + "title": "Data", + "type": "string" + } + }, + "required": [ + "type", + "media_type", + "data" + ], + "title": "Base64ImageSource", + "type": "object" + }, + "BetaBase64PDFSource": { + "additionalProperties": false, + "properties": { + "type": { + "const": "base64", + "enum": [ + "base64" + ], + "title": "Type", + "type": "string" + }, + "media_type": { + "const": "application/pdf", + "enum": [ + "application/pdf" + ], + "title": "Media Type", + "type": "string" + }, + "data": { + "format": "byte", + "title": "Data", + "type": "string" + } + }, + "required": [ + "type", + "media_type", + "data" + ], + "title": "Base64PDFSource", + "type": "object" + }, + "BetaBashTool_20241022": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "bash_20241022", + "enum": [ + "bash_20241022" + ], + "title": "Type", + "type": "string" + }, + "name": { + "const": "bash", + "description": "Name of the tool.\n\nThis is how the tool will be called by the model and in tool_use blocks.", + "enum": [ + "bash" + ], + "title": "Name", + "type": "string" + } + }, + "required": [ + "type", + "name" + ], + "title": "BashTool_20241022", + "type": "object" + }, + "BetaCacheControlEphemeral": { + "additionalProperties": false, + "properties": { + "type": { + "const": "ephemeral", + "enum": [ + "ephemeral" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type" + ], + "title": "CacheControlEphemeral", + "type": "object" + }, + "BetaCanceledResult": { + "properties": { + "type": { + "const": "canceled", + "default": "canceled", + "enum": [ + "canceled" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type" + ], + "title": "CanceledResult", + "type": "object" + }, + "BetaComputerUseTool_20241022": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "computer_20241022", + "enum": [ + "computer_20241022" + ], + "title": "Type", + "type": "string" + }, + "name": { + "const": "computer", + "description": "Name of the tool.\n\nThis is how the tool will be called by the model and in tool_use blocks.", + "enum": [ + "computer" + ], + "title": "Name", + "type": "string" + }, + "display_height_px": { + "description": "The height of the display in pixels.", + "minimum": 1, + "title": "Display Height Px", + "type": "integer" + }, + "display_width_px": { + "description": "The width of the display in pixels.", + "minimum": 1, + "title": "Display Width Px", + "type": "integer" + }, + "display_number": { + "anyOf": [ + { + "minimum": 0, + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "The X11 display number (e.g. 0, 1) for the display.", + "title": "Display Number" + } + }, + "required": [ + "type", + "name", + "display_height_px", + "display_width_px" + ], + "title": "ComputerUseTool_20241022", + "type": "object" + }, + "BetaContentBlockDeltaEvent": { + "properties": { + "type": { + "const": "content_block_delta", + "default": "content_block_delta", + "enum": [ + "content_block_delta" + ], + "title": "Type", + "type": "string" + }, + "index": { + "title": "Index", + "type": "integer" + }, + "delta": { + "discriminator": { + "mapping": { + "input_json_delta": "#/components/schemas/BetaInputJsonContentBlockDelta", + "text_delta": "#/components/schemas/BetaTextContentBlockDelta" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaTextContentBlockDelta" + }, + { + "$ref": "#/components/schemas/BetaInputJsonContentBlockDelta" + } + ], + "title": "Delta" + } + }, + "required": [ + "type", + "index", + "delta" + ], + "title": "ContentBlockDeltaEvent", + "type": "object" + }, + "BetaContentBlockStartEvent": { + "properties": { + "type": { + "const": "content_block_start", + "default": "content_block_start", + "enum": [ + "content_block_start" + ], + "title": "Type", + "type": "string" + }, + "index": { + "title": "Index", + "type": "integer" + }, + "content_block": { + "discriminator": { + "mapping": { + "text": "#/components/schemas/BetaResponseTextBlock", + "tool_use": "#/components/schemas/BetaResponseToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaResponseTextBlock" + }, + { + "$ref": "#/components/schemas/BetaResponseToolUseBlock" + } + ], + "title": "Content Block" + } + }, + "required": [ + "type", + "index", + "content_block" + ], + "title": "ContentBlockStartEvent", + "type": "object" + }, + "BetaContentBlockStopEvent": { + "properties": { + "type": { + "const": "content_block_stop", + "default": "content_block_stop", + "enum": [ + "content_block_stop" + ], + "title": "Type", + "type": "string" + }, + "index": { + "title": "Index", + "type": "integer" + } + }, + "required": [ + "type", + "index" + ], + "title": "ContentBlockStopEvent", + "type": "object" + }, + "BetaCountMessageTokensParams": { + "additionalProperties": false, + "examples": [ + { + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-3-5-sonnet-20241022" + } + ], + "properties": { + "tool_choice": { + "$ref": "#/components/schemas/BetaToolChoice" + }, + "tools": { + "description": "Definitions of tools that the model may use.\n\nIf you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.\n\nEach tool definition includes:\n\n* `name`: Name of the tool.\n* `description`: Optional, but strongly-recommended description of the tool.\n* `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks.\n\nFor example, if you defined `tools` as:\n\n```json\n[\n {\n \"name\": \"get_stock_price\",\n \"description\": \"Get the current stock price for a given ticker symbol.\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"ticker\": {\n \"type\": \"string\",\n \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\"\n }\n },\n \"required\": [\"ticker\"]\n }\n }\n]\n```\n\nAnd then asked the model \"What's the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this:\n\n```json\n[\n {\n \"type\": \"tool_use\",\n \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"name\": \"get_stock_price\",\n \"input\": { \"ticker\": \"^GSPC\" }\n }\n]\n```\n\nYou might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message:\n\n```json\n[\n {\n \"type\": \"tool_result\",\n \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"content\": \"259.75 USD\"\n }\n]\n```\n\nTools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.\n\nSee our [guide](https://docs.anthropic.com/en/docs/tool-use) for more details.", + "examples": [ + { + "description": "Get the current weather in a given location", + "input_schema": { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + }, + "name": "get_weather" + } + ], + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/BetaTool" + }, + { + "$ref": "#/components/schemas/BetaComputerUseTool_20241022" + }, + { + "$ref": "#/components/schemas/BetaBashTool_20241022" + }, + { + "$ref": "#/components/schemas/BetaTextEditor_20241022" + } + ] + }, + "title": "Tools", + "type": "array" + }, + "messages": { + "description": "Input messages.\n\nOur models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.\n\nEach input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.\n\nIf the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.\n\nExample with a single `user` message:\n\n```json\n[{\"role\": \"user\", \"content\": \"Hello, Claude\"}]\n```\n\nExample with multiple conversational turns:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"Hello there.\"},\n {\"role\": \"assistant\", \"content\": \"Hi, I'm Claude. How can I help you?\"},\n {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"},\n]\n```\n\nExample with a partially-filled response from Claude:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"},\n]\n```\n\nEach input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent:\n\n```json\n{\"role\": \"user\", \"content\": \"Hello, Claude\"}\n```\n\n```json\n{\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]}\n```\n\nStarting with Claude 3 models, you can also send image content blocks:\n\n```json\n{\"role\": \"user\", \"content\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"media_type\": \"image/jpeg\",\n \"data\": \"/9j/4AAQSkZJRg...\",\n }\n },\n {\"type\": \"text\", \"text\": \"What is in this image?\"}\n]}\n```\n\nWe currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types.\n\nSee [examples](https://docs.anthropic.com/en/api/messages-examples#vision) for more input examples.\n\nNote that if you want to include a [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use the top-level `system` parameter \u2014 there is no `\"system\"` role for input messages in the Messages API.", + "items": { + "$ref": "#/components/schemas/BetaInputMessage" + }, + "title": "Messages", + "type": "array" + }, + "system": { + "anyOf": [ + { + "type": "string" + }, + { + "items": { + "$ref": "#/components/schemas/BetaRequestTextBlock" + }, + "type": "array" + } + ], + "description": "System prompt.\n\nA system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts).", + "examples": [ + [ + { + "text": "Today's date is 2024-06-01.", + "type": "text" + } + ], + "Today's date is 2023-01-01." + ], + "title": "System" + }, + "model": { + "$ref": "#/components/schemas/Model" + } + }, + "required": [ + "messages", + "model" + ], + "title": "CountMessageTokensParams", + "type": "object" + }, + "BetaCountMessageTokensResponse": { + "properties": { + "input_tokens": { + "type": "integer", + "title": "Input Tokens", + "description": "The total number of tokens across the provided list of messages, system prompt, and tools.", + "examples": [ + 2095 + ] + } + }, + "type": "object", + "required": [ + "input_tokens" + ], + "title": "CountMessageTokensResponse", + "examples": [ + { + "input_tokens": 2095 + } + ] + }, + "BetaCreateMessageBatchParams": { + "additionalProperties": false, + "properties": { + "requests": { + "description": "List of requests for prompt completion. Each is an individual request to create a Message.", + "items": { + "$ref": "#/components/schemas/BetaMessageBatchIndividualRequestParams" + }, + "title": "Requests", + "type": "array" + } + }, + "required": [ + "requests" + ], + "title": "CreateMessageBatchParams", + "type": "object" + }, + "BetaCreateMessageParams": { + "additionalProperties": false, + "example": { + "max_tokens": 1024, + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-3-5-sonnet-20241022" + }, + "properties": { + "model": { + "$ref": "#/components/schemas/Model" + }, + "messages": { + "description": "Input messages.\n\nOur models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.\n\nEach input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.\n\nIf the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.\n\nExample with a single `user` message:\n\n```json\n[{\"role\": \"user\", \"content\": \"Hello, Claude\"}]\n```\n\nExample with multiple conversational turns:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"Hello there.\"},\n {\"role\": \"assistant\", \"content\": \"Hi, I'm Claude. How can I help you?\"},\n {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"},\n]\n```\n\nExample with a partially-filled response from Claude:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"},\n]\n```\n\nEach input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent:\n\n```json\n{\"role\": \"user\", \"content\": \"Hello, Claude\"}\n```\n\n```json\n{\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]}\n```\n\nStarting with Claude 3 models, you can also send image content blocks:\n\n```json\n{\"role\": \"user\", \"content\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"media_type\": \"image/jpeg\",\n \"data\": \"/9j/4AAQSkZJRg...\",\n }\n },\n {\"type\": \"text\", \"text\": \"What is in this image?\"}\n]}\n```\n\nWe currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types.\n\nSee [examples](https://docs.anthropic.com/en/api/messages-examples#vision) for more input examples.\n\nNote that if you want to include a [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use the top-level `system` parameter \u2014 there is no `\"system\"` role for input messages in the Messages API.", + "items": { + "$ref": "#/components/schemas/BetaInputMessage" + }, + "title": "Messages", + "type": "array" + }, + "max_tokens": { + "description": "The maximum number of tokens to generate before stopping.\n\nNote that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.\n\nDifferent models have different maximum values for this parameter. See [models](https://docs.anthropic.com/en/docs/models-overview) for details.", + "examples": [ + 1024 + ], + "minimum": 1, + "title": "Max Tokens", + "type": "integer" + }, + "metadata": { + "allOf": [ + { + "$ref": "#/components/schemas/BetaMetadata" + } + ], + "description": "An object describing metadata about the request." + }, + "stop_sequences": { + "description": "Custom text sequences that will cause the model to stop generating.\n\nOur models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `\"end_turn\"`.\n\nIf you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `\"stop_sequence\"` and the response `stop_sequence` value will contain the matched stop sequence.", + "items": { + "type": "string" + }, + "title": "Stop Sequences", + "type": "array" + }, + "stream": { + "description": "Whether to incrementally stream the response using server-sent events.\n\nSee [streaming](https://docs.anthropic.com/en/api/messages-streaming) for details.", + "title": "Stream", + "type": "boolean" + }, + "system": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "$ref": "#/components/schemas/BetaRequestTextBlock" + }, + "type": "array" + } + ], + "description": "System prompt.\n\nA system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts).", + "examples": [ + [ + { + "text": "Today's date is 2024-06-01.", + "type": "text" + } + ], + "Today's date is 2023-01-01." + ], + "title": "System" + }, + "temperature": { + "description": "Amount of randomness injected into the response.\n\nDefaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.\n\nNote that even with `temperature` of `0.0`, the results will not be fully deterministic.", + "examples": [ + 1 + ], + "maximum": 1, + "minimum": 0, + "title": "Temperature", + "type": "number" + }, + "tool_choice": { + "$ref": "#/components/schemas/BetaToolChoice" + }, + "tools": { + "description": "Definitions of tools that the model may use.\n\nIf you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.\n\nEach tool definition includes:\n\n* `name`: Name of the tool.\n* `description`: Optional, but strongly-recommended description of the tool.\n* `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks.\n\nFor example, if you defined `tools` as:\n\n```json\n[\n {\n \"name\": \"get_stock_price\",\n \"description\": \"Get the current stock price for a given ticker symbol.\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"ticker\": {\n \"type\": \"string\",\n \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\"\n }\n },\n \"required\": [\"ticker\"]\n }\n }\n]\n```\n\nAnd then asked the model \"What's the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this:\n\n```json\n[\n {\n \"type\": \"tool_use\",\n \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"name\": \"get_stock_price\",\n \"input\": { \"ticker\": \"^GSPC\" }\n }\n]\n```\n\nYou might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message:\n\n```json\n[\n {\n \"type\": \"tool_result\",\n \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"content\": \"259.75 USD\"\n }\n]\n```\n\nTools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.\n\nSee our [guide](https://docs.anthropic.com/en/docs/tool-use) for more details.", + "examples": [ + { + "description": "Get the current weather in a given location", + "input_schema": { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + }, + "name": "get_weather" + } + ], + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/BetaTool" + }, + { + "$ref": "#/components/schemas/BetaComputerUseTool_20241022" + }, + { + "$ref": "#/components/schemas/BetaBashTool_20241022" + }, + { + "$ref": "#/components/schemas/BetaTextEditor_20241022" + } + ] + }, + "title": "Tools", + "type": "array" + }, + "top_k": { + "description": "Only sample from the top K options for each subsequent token.\n\nUsed to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 5 + ], + "minimum": 0, + "title": "Top K", + "type": "integer" + }, + "top_p": { + "description": "Use nucleus sampling.\n\nIn nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both.\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 0.7 + ], + "maximum": 1, + "minimum": 0, + "title": "Top P", + "type": "number" + } + }, + "required": [ + "model", + "messages", + "max_tokens" + ], + "title": "CreateMessageParams", + "type": "object" + }, + "BetaErrorResponse": { + "properties": { + "type": { + "const": "error", + "default": "error", + "enum": [ + "error" + ], + "title": "Type", + "type": "string" + }, + "error": { + "discriminator": { + "mapping": { + "api_error": "#/components/schemas/BetaAPIError", + "authentication_error": "#/components/schemas/BetaAuthenticationError", + "invalid_request_error": "#/components/schemas/BetaInvalidRequestError", + "not_found_error": "#/components/schemas/BetaNotFoundError", + "overloaded_error": "#/components/schemas/BetaOverloadedError", + "permission_error": "#/components/schemas/BetaPermissionError", + "rate_limit_error": "#/components/schemas/BetaRateLimitError" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaInvalidRequestError" + }, + { + "$ref": "#/components/schemas/BetaAuthenticationError" + }, + { + "$ref": "#/components/schemas/BetaPermissionError" + }, + { + "$ref": "#/components/schemas/BetaNotFoundError" + }, + { + "$ref": "#/components/schemas/BetaRateLimitError" + }, + { + "$ref": "#/components/schemas/BetaAPIError" + }, + { + "$ref": "#/components/schemas/BetaOverloadedError" + } + ], + "title": "Error" + } + }, + "required": [ + "type", + "error" + ], + "title": "ErrorResponse", + "type": "object" + }, + "BetaErroredResult": { + "properties": { + "type": { + "const": "errored", + "default": "errored", + "enum": [ + "errored" + ], + "title": "Type", + "type": "string" + }, + "error": { + "$ref": "#/components/schemas/BetaErrorResponse" + } + }, + "required": [ + "type", + "error" + ], + "title": "ErroredResult", + "type": "object" + }, + "BetaExpiredResult": { + "properties": { + "type": { + "const": "expired", + "default": "expired", + "enum": [ + "expired" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type" + ], + "title": "ExpiredResult", + "type": "object" + }, + "BetaInputJsonContentBlockDelta": { + "properties": { + "type": { + "const": "input_json_delta", + "default": "input_json_delta", + "enum": [ + "input_json_delta" + ], + "title": "Type", + "type": "string" + }, + "partial_json": { + "title": "Partial Json", + "type": "string" + } + }, + "required": [ + "type", + "partial_json" + ], + "title": "InputJsonContentBlockDelta", + "type": "object" + }, + "BetaInputMessage": { + "additionalProperties": false, + "properties": { + "role": { + "enum": [ + "user", + "assistant" + ], + "title": "Role", + "type": "string" + }, + "content": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "$ref": "#/components/schemas/BetaInputContentBlock" + }, + "type": "array", + "example": [ + { + "type": "text", + "text": "What is a quaternion?" + } + ] + } + ], + "title": "Content" + } + }, + "required": [ + "role", + "content" + ], + "title": "InputMessage", + "type": "object" + }, + "BetaInputSchema": { + "additionalProperties": true, + "properties": { + "type": { + "const": "object", + "enum": [ + "object" + ], + "title": "Type", + "type": "string" + }, + "properties": { + "anyOf": [ + { + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Properties" + } + }, + "required": [ + "type" + ], + "title": "InputSchema", + "type": "object" + }, + "BetaInvalidRequestError": { + "properties": { + "type": { + "const": "invalid_request_error", + "default": "invalid_request_error", + "enum": [ + "invalid_request_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Invalid request", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "InvalidRequestError", + "type": "object" + }, + "BetaListResponse_MessageBatch_": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/BetaMessageBatch" + }, + "type": "array", + "title": "Data" + }, + "has_more": { + "type": "boolean", + "title": "Has More", + "description": "Indicates if there are more results in the requested page direction." + }, + "first_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "First Id", + "description": "First ID in the `data` list. Can be used as the `before_id` for the previous page.", + "examples": [ + "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF" + ] + }, + "last_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Id", + "description": "Last ID in the `data` list. Can be used as the `after_id` for the next page.", + "examples": [ + "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" + ] + } + }, + "type": "object", + "required": [ + "data", + "has_more", + "first_id", + "last_id" + ], + "title": "ListResponse[MessageBatch]" + }, + "BetaMessage": { + "examples": [ + { + "content": [ + { + "text": "Hi! My name is Claude.", + "type": "text" + } + ], + "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", + "model": "claude-3-5-sonnet-20241022", + "role": "assistant", + "stop_reason": "end_turn", + "stop_sequence": null, + "type": "message", + "usage": { + "input_tokens": 2095, + "output_tokens": 503 + } + } + ], + "properties": { + "id": { + "description": "Unique object identifier.\n\nThe format and length of IDs may change over time.", + "examples": [ + "msg_013Zva2CMHLNnXjNJJKqJ2EF" + ], + "title": "Id", + "type": "string" + }, + "type": { + "const": "message", + "default": "message", + "description": "Object type.\n\nFor Messages, this is always `\"message\"`.", + "enum": [ + "message" + ], + "title": "Type", + "type": "string" + }, + "role": { + "const": "assistant", + "default": "assistant", + "description": "Conversational role of the generated message.\n\nThis will always be `\"assistant\"`.", + "enum": [ + "assistant" + ], + "title": "Role", + "type": "string" + }, + "content": { + "description": "Content generated by the model.\n\nThis is an array of content blocks, each of which has a `type` that determines its shape.\n\nExample:\n\n```json\n[{\"type\": \"text\", \"text\": \"Hi, I'm Claude.\"}]\n```\n\nIf the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.\n\nFor example, if the input `messages` were:\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"}\n]\n```\n\nThen the response `content` might be:\n\n```json\n[{\"type\": \"text\", \"text\": \"B)\"}]\n```", + "examples": [ + [ + { + "text": "Hi! My name is Claude.", + "type": "text" + } + ] + ], + "items": { + "$ref": "#/components/schemas/BetaContentBlock" + }, + "title": "Content", + "type": "array" + }, + "model": { + "$ref": "#/components/schemas/Model" + }, + "stop_reason": { + "anyOf": [ + { + "enum": [ + "end_turn", + "max_tokens", + "stop_sequence", + "tool_use" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The reason that we stopped.\n\nThis may be one the following values:\n* `\"end_turn\"`: the model reached a natural stopping point\n* `\"max_tokens\"`: we exceeded the requested `max_tokens` or the model's maximum\n* `\"stop_sequence\"`: one of your provided custom `stop_sequences` was generated\n* `\"tool_use\"`: the model invoked one or more tools\n\nIn non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise.", + "title": "Stop Reason" + }, + "stop_sequence": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Which custom stop sequence was generated, if any.\n\nThis value will be a non-null string if one of your custom stop sequences was generated.", + "title": "Stop Sequence" + }, + "usage": { + "allOf": [ + { + "$ref": "#/components/schemas/BetaUsage" + } + ], + "description": "Billing and rate-limit usage.\n\nAnthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.\n\nUnder the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response.\n\nFor example, `output_tokens` will be non-zero, even for an empty string response from Claude.", + "examples": [ + { + "input_tokens": 2095, + "output_tokens": 503 + } + ] + } + }, + "required": [ + "id", + "type", + "role", + "content", + "model", + "stop_reason", + "stop_sequence", + "usage" + ], + "title": "Message", + "type": "object", + "x-stainless-python-custom-imports": [ + "from .beta_content_block import BetaContentBlock as BetaContentBlock" + ] + }, + "BetaMessageBatch": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique object identifier.\n\nThe format and length of IDs may change over time.", + "examples": [ + "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF" + ] + }, + "type": { + "type": "string", + "enum": [ + "message_batch" + ], + "const": "message_batch", + "title": "Type", + "description": "Object type.\n\nFor Message Batches, this is always `\"message_batch\"`.", + "default": "message_batch" + }, + "processing_status": { + "type": "string", + "enum": [ + "in_progress", + "canceling", + "ended" + ], + "title": "Processing Status", + "description": "Processing status of the Message Batch." + }, + "request_counts": { + "allOf": [ + { + "$ref": "#/components/schemas/BetaRequestCounts" + } + ], + "description": "Tallies requests within the Message Batch, categorized by their status.\n\nRequests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch." + }, + "ended_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Ended At", + "description": "RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.\n\nProcessing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.", + "examples": [ + "2024-08-20T18:37:24.100435Z" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "Created At", + "description": "RFC 3339 datetime string representing the time at which the Message Batch was created.", + "examples": [ + "2024-08-20T18:37:24.100435Z" + ] + }, + "expires_at": { + "type": "string", + "format": "date-time", + "title": "Expires At", + "description": "RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.", + "examples": [ + "2024-08-20T18:37:24.100435Z" + ] + }, + "archived_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Archived At", + "description": "RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.", + "examples": [ + "2024-08-20T18:37:24.100435Z" + ] + }, + "cancel_initiated_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Cancel Initiated At", + "description": "RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.", + "examples": [ + "2024-08-20T18:37:24.100435Z" + ] + }, + "results_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Results Url", + "description": "URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.\n\nResults in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.", + "examples": [ + "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results" + ] + } + }, + "type": "object", + "required": [ + "id", + "type", + "processing_status", + "request_counts", + "ended_at", + "created_at", + "expires_at", + "archived_at", + "cancel_initiated_at", + "results_url" + ], + "title": "MessageBatch" + }, + "BetaMessageBatchIndividualRequestParams": { + "additionalProperties": false, + "properties": { + "custom_id": { + "description": "Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.\n\nMust be unique for each request within the Message Batch.", + "examples": [ + "my-custom-id-1" + ], + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Custom Id", + "type": "string" + }, + "params": { + "allOf": [ + { + "$ref": "#/components/schemas/BetaCreateMessageParams" + } + ], + "description": "Messages API creation parameters for the individual request. \n\nSee the [Messages API reference](/en/api/messages) for full documentation on available parameters." + } + }, + "required": [ + "custom_id", + "params" + ], + "title": "MessageBatchIndividualRequestParams", + "type": "object" + }, + "BetaMessageBatchIndividualResponse": { + "properties": { + "custom_id": { + "description": "Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.\n\nMust be unique for each request within the Message Batch.", + "examples": [ + "my-custom-id-1" + ], + "title": "Custom Id", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BetaMessageBatchResult" + } + }, + "required": [ + "custom_id", + "result" + ], + "title": "MessageBatchIndividualResponse", + "type": "object" + }, + "BetaMessageDelta": { + "properties": { + "stop_reason": { + "anyOf": [ + { + "enum": [ + "end_turn", + "max_tokens", + "stop_sequence", + "tool_use" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Stop Reason" + }, + "stop_sequence": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Stop Sequence" + } + }, + "required": [ + "stop_reason", + "stop_sequence" + ], + "title": "MessageDelta", + "type": "object" + }, + "BetaMessageDeltaEvent": { + "properties": { + "type": { + "const": "message_delta", + "default": "message_delta", + "enum": [ + "message_delta" + ], + "title": "Type", + "type": "string" + }, + "delta": { + "$ref": "#/components/schemas/BetaMessageDelta" + }, + "usage": { + "allOf": [ + { + "$ref": "#/components/schemas/BetaMessageDeltaUsage" + } + ], + "description": "Billing and rate-limit usage.\n\nAnthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.\n\nUnder the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response.\n\nFor example, `output_tokens` will be non-zero, even for an empty string response from Claude.", + "examples": [ + { + "output_tokens": 503 + } + ] + } + }, + "required": [ + "type", + "delta", + "usage" + ], + "title": "MessageDeltaEvent", + "type": "object" + }, + "BetaMessageDeltaUsage": { + "properties": { + "output_tokens": { + "description": "The cumulative number of output tokens which were used.", + "examples": [ + 503 + ], + "title": "Output Tokens", + "type": "integer" + } + }, + "required": [ + "output_tokens" + ], + "title": "MessageDeltaUsage", + "type": "object" + }, + "BetaMessageStartEvent": { + "properties": { + "type": { + "const": "message_start", + "default": "message_start", + "enum": [ + "message_start" + ], + "title": "Type", + "type": "string" + }, + "message": { + "$ref": "#/components/schemas/BetaMessage" + } + }, + "required": [ + "type", + "message" + ], + "title": "MessageStartEvent", + "type": "object" + }, + "BetaMessageStopEvent": { + "properties": { + "type": { + "const": "message_stop", + "default": "message_stop", + "enum": [ + "message_stop" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type" + ], + "title": "MessageStopEvent", + "type": "object" + }, + "BetaMessageStreamEvent": { + "discriminator": { + "mapping": { + "content_block_delta": "#/components/schemas/BetaContentBlockDeltaEvent", + "content_block_start": "#/components/schemas/BetaContentBlockStartEvent", + "content_block_stop": "#/components/schemas/BetaContentBlockStopEvent", + "message_delta": "#/components/schemas/BetaMessageDeltaEvent", + "message_start": "#/components/schemas/BetaMessageStartEvent", + "message_stop": "#/components/schemas/BetaMessageStopEvent" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaMessageStartEvent" + }, + { + "$ref": "#/components/schemas/BetaMessageDeltaEvent" + }, + { + "$ref": "#/components/schemas/BetaMessageStopEvent" + }, + { + "$ref": "#/components/schemas/BetaContentBlockStartEvent" + }, + { + "$ref": "#/components/schemas/BetaContentBlockDeltaEvent" + }, + { + "$ref": "#/components/schemas/BetaContentBlockStopEvent" + } + ], + "title": "MessageStreamEvent" + }, + "BetaMetadata": { + "additionalProperties": false, + "properties": { + "user_id": { + "anyOf": [ + { + "maxLength": 256, + "type": "string" + }, + { + "type": "null" + } + ], + "description": "An external identifier for the user who is associated with the request.\n\nThis should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.", + "examples": [ + "13803d75-b4b5-4c3e-b2a2-6f21399b021b" + ], + "title": "User Id" + } + }, + "title": "Metadata", + "type": "object" + }, + "BetaNotFoundError": { + "properties": { + "type": { + "const": "not_found_error", + "default": "not_found_error", + "enum": [ + "not_found_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Not found", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "NotFoundError", + "type": "object" + }, + "BetaOverloadedError": { + "properties": { + "type": { + "const": "overloaded_error", + "default": "overloaded_error", + "enum": [ + "overloaded_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Overloaded", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "OverloadedError", + "type": "object" + }, + "BetaPermissionError": { + "properties": { + "type": { + "const": "permission_error", + "default": "permission_error", + "enum": [ + "permission_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Permission denied", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "PermissionError", + "type": "object" + }, + "BetaRateLimitError": { + "properties": { + "type": { + "const": "rate_limit_error", + "default": "rate_limit_error", + "enum": [ + "rate_limit_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Rate limited", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "RateLimitError", + "type": "object" + }, + "BetaRequestCounts": { + "properties": { + "processing": { + "type": "integer", + "title": "Processing", + "description": "Number of requests in the Message Batch that are processing.", + "default": 0, + "examples": [ + 100 + ] + }, + "succeeded": { + "type": "integer", + "title": "Succeeded", + "description": "Number of requests in the Message Batch that have completed successfully.\n\nThis is zero until processing of the entire Message Batch has ended.", + "default": 0, + "examples": [ + 50 + ] + }, + "errored": { + "type": "integer", + "title": "Errored", + "description": "Number of requests in the Message Batch that encountered an error.\n\nThis is zero until processing of the entire Message Batch has ended.", + "default": 0, + "examples": [ + 30 + ] + }, + "canceled": { + "type": "integer", + "title": "Canceled", + "description": "Number of requests in the Message Batch that have been canceled.\n\nThis is zero until processing of the entire Message Batch has ended.", + "default": 0, + "examples": [ + 10 + ] + }, + "expired": { + "type": "integer", + "title": "Expired", + "description": "Number of requests in the Message Batch that have expired.\n\nThis is zero until processing of the entire Message Batch has ended.", + "default": 0, + "examples": [ + 10 + ] + } + }, + "type": "object", + "required": [ + "processing", + "succeeded", + "errored", + "canceled", + "expired" + ], + "title": "RequestCounts" + }, + "BetaRequestImageBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "image", + "enum": [ + "image" + ], + "title": "Type", + "type": "string" + }, + "source": { + "discriminator": { + "mapping": { + "base64": "#/components/schemas/BetaBase64ImageSource" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaBase64ImageSource" + } + ], + "title": "Source" + } + }, + "required": [ + "type", + "source" + ], + "title": "RequestImageBlock", + "type": "object" + }, + "BetaRequestPDFBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "document", + "enum": [ + "document" + ], + "title": "Type", + "type": "string" + }, + "source": { + "$ref": "#/components/schemas/BetaBase64PDFSource" + } + }, + "required": [ + "type", + "source" + ], + "title": "RequestPDFBlock", + "type": "object" + }, + "BetaRequestTextBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "text", + "enum": [ + "text" + ], + "title": "Type", + "type": "string" + }, + "text": { + "minLength": 1, + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "RequestTextBlock", + "type": "object" + }, + "BetaRequestToolResultBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "tool_result", + "enum": [ + "tool_result" + ], + "title": "Type", + "type": "string" + }, + "tool_use_id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Tool Use Id", + "type": "string" + }, + "is_error": { + "title": "Is Error", + "type": "boolean" + }, + "content": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "discriminator": { + "mapping": { + "image": "#/components/schemas/BetaRequestImageBlock", + "text": "#/components/schemas/BetaRequestTextBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaRequestTextBlock" + }, + { + "$ref": "#/components/schemas/BetaRequestImageBlock" + } + ], + "title": "Block" + }, + "type": "array", + "x-stainless-naming": { + "python": { + "type_name": "Content" + } + } + } + ], + "title": "Content" + } + }, + "required": [ + "type", + "tool_use_id" + ], + "title": "RequestToolResultBlock", + "type": "object" + }, + "BetaRequestToolUseBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "tool_use", + "enum": [ + "tool_use" + ], + "title": "Type", + "type": "string" + }, + "id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Id", + "type": "string" + }, + "name": { + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Name", + "type": "string" + }, + "input": { + "title": "Input", + "type": "object" + } + }, + "required": [ + "type", + "id", + "name", + "input" + ], + "title": "RequestToolUseBlock", + "type": "object" + }, + "BetaResponseTextBlock": { + "properties": { + "type": { + "const": "text", + "default": "text", + "enum": [ + "text" + ], + "title": "Type", + "type": "string" + }, + "text": { + "maxLength": 5000000, + "minLength": 0, + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "ResponseTextBlock", + "type": "object" + }, + "BetaResponseToolUseBlock": { + "properties": { + "type": { + "const": "tool_use", + "default": "tool_use", + "enum": [ + "tool_use" + ], + "title": "Type", + "type": "string" + }, + "id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Id", + "type": "string" + }, + "name": { + "minLength": 1, + "title": "Name", + "type": "string" + }, + "input": { + "title": "Input", + "type": "object" + } + }, + "required": [ + "type", + "id", + "name", + "input" + ], + "title": "ResponseToolUseBlock", + "type": "object" + }, + "BetaSucceededResult": { + "properties": { + "type": { + "const": "succeeded", + "default": "succeeded", + "enum": [ + "succeeded" + ], + "title": "Type", + "type": "string" + }, + "message": { + "$ref": "#/components/schemas/BetaMessage" + } + }, + "required": [ + "type", + "message" + ], + "title": "SucceededResult", + "type": "object" + }, + "BetaTextContentBlockDelta": { + "properties": { + "type": { + "const": "text_delta", + "default": "text_delta", + "enum": [ + "text_delta" + ], + "title": "Type", + "type": "string" + }, + "text": { + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "TextContentBlockDelta", + "type": "object" + }, + "BetaTextEditor_20241022": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "text_editor_20241022", + "enum": [ + "text_editor_20241022" + ], + "title": "Type", + "type": "string" + }, + "name": { + "const": "str_replace_editor", + "description": "Name of the tool.\n\nThis is how the tool will be called by the model and in tool_use blocks.", + "enum": [ + "str_replace_editor" + ], + "title": "Name", + "type": "string" + } + }, + "required": [ + "type", + "name" + ], + "title": "TextEditor_20241022", + "type": "object" + }, + "BetaTool": { + "additionalProperties": false, + "properties": { + "type": { + "anyOf": [ + { + "type": "null" + }, + { + "const": "custom", + "enum": [ + "custom" + ], + "type": "string" + } + ], + "title": "Type" + }, + "description": { + "description": "Description of what this tool does.\n\nTool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema.", + "examples": [ + "Get the current weather in a given location" + ], + "title": "Description", + "type": "string" + }, + "name": { + "description": "Name of the tool.\n\nThis is how the tool will be called by the model and in tool_use blocks.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Name", + "type": "string" + }, + "input_schema": { + "allOf": [ + { + "$ref": "#/components/schemas/BetaInputSchema" + } + ], + "description": "[JSON schema](https://json-schema.org/) for this tool's input.\n\nThis defines the shape of the `input` that your tool accepts and that the model will produce.", + "examples": [ + { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + } + ] + }, + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/BetaCacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaCacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + } + }, + "required": [ + "name", + "input_schema" + ], + "title": "Tool", + "type": "object" + }, + "BetaToolChoiceAny": { + "additionalProperties": false, + "description": "The model will use any available tools.", + "properties": { + "type": { + "const": "any", + "enum": [ + "any" + ], + "title": "Type", + "type": "string" + }, + "disable_parallel_tool_use": { + "description": "Whether to disable parallel tool use.\n\nDefaults to `false`. If set to `true`, the model will output exactly one tool use.", + "title": "Disable Parallel Tool Use", + "type": "boolean" + } + }, + "required": [ + "type" + ], + "title": "ToolChoiceAny", + "type": "object" + }, + "BetaToolChoiceAuto": { + "additionalProperties": false, + "description": "The model will automatically decide whether to use tools.", + "properties": { + "type": { + "const": "auto", + "enum": [ + "auto" + ], + "title": "Type", + "type": "string" + }, + "disable_parallel_tool_use": { + "description": "Whether to disable parallel tool use.\n\nDefaults to `false`. If set to `true`, the model will output at most one tool use.", + "title": "Disable Parallel Tool Use", + "type": "boolean" + } + }, + "required": [ + "type" + ], + "title": "ToolChoiceAuto", + "type": "object" + }, + "BetaToolChoiceTool": { + "additionalProperties": false, + "description": "The model will use the specified tool with `tool_choice.name`.", + "properties": { + "type": { + "const": "tool", + "enum": [ + "tool" + ], + "title": "Type", + "type": "string" + }, + "name": { + "description": "The name of the tool to use.", + "title": "Name", + "type": "string" + }, + "disable_parallel_tool_use": { + "description": "Whether to disable parallel tool use.\n\nDefaults to `false`. If set to `true`, the model will output exactly one tool use.", + "title": "Disable Parallel Tool Use", + "type": "boolean" + } + }, + "required": [ + "type", + "name" + ], + "title": "ToolChoiceTool", + "type": "object" + }, + "BetaUsage": { + "properties": { + "input_tokens": { + "description": "The number of input tokens which were used.", + "examples": [ + 2095 + ], + "title": "Input Tokens", + "type": "integer" + }, + "cache_creation_input_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "description": "The number of input tokens used to create the cache entry.", + "examples": [ + 2051 + ], + "title": "Cache Creation Input Tokens" + }, + "cache_read_input_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "description": "The number of input tokens read from the cache.", + "examples": [ + 2051 + ], + "title": "Cache Read Input Tokens" + }, + "output_tokens": { + "description": "The number of output tokens which were used.", + "examples": [ + 503 + ], + "title": "Output Tokens", + "type": "integer" + } + }, + "required": [ + "input_tokens", + "cache_creation_input_tokens", + "cache_read_input_tokens", + "output_tokens" + ], + "title": "Usage", + "type": "object" + }, + "CacheControlEphemeral": { + "additionalProperties": false, + "properties": { + "type": { + "const": "ephemeral", + "enum": [ + "ephemeral" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type" + ], + "title": "CacheControlEphemeral", + "type": "object" + }, + "CompletionRequest": { + "additionalProperties": false, + "examples": [ + { + "model": "claude-2.1", + "prompt": "\n\nHuman: Hello, world!\n\nAssistant:", + "max_tokens_to_sample": 256 + } + ], + "properties": { + "model": { + "$ref": "#/components/schemas/Model" + }, + "prompt": { + "description": "The prompt that you want Claude to complete.\n\nFor proper response generation you will need to format your prompt using alternating `\\n\\nHuman:` and `\\n\\nAssistant:` conversational turns. For example:\n\n```\n\"\\n\\nHuman: {userQuestion}\\n\\nAssistant:\"\n```\n\nSee [prompt validation](https://docs.anthropic.com/en/api/prompt-validation) and our guide to [prompt design](https://docs.anthropic.com/en/docs/intro-to-prompting) for more details.", + "examples": [ + "\n\nHuman: Hello, world!\n\nAssistant:" + ], + "minLength": 1, + "title": "Prompt", + "type": "string" + }, + "max_tokens_to_sample": { + "description": "The maximum number of tokens to generate before stopping.\n\nNote that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.", + "examples": [ + 256 + ], + "minimum": 1, + "title": "Max Tokens To Sample", + "type": "integer" + }, + "stop_sequences": { + "description": "Sequences that will cause the model to stop generating.\n\nOur models stop on `\"\\n\\nHuman:\"`, and may include additional built-in stop sequences in the future. By providing the stop_sequences parameter, you may include additional strings that will cause the model to stop generating.", + "items": { + "type": "string" + }, + "title": "Stop Sequences", + "type": "array" + }, + "temperature": { + "description": "Amount of randomness injected into the response.\n\nDefaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.\n\nNote that even with `temperature` of `0.0`, the results will not be fully deterministic.", + "examples": [ + 1 + ], + "maximum": 1, + "minimum": 0, + "title": "Temperature", + "type": "number" + }, + "top_p": { + "description": "Use nucleus sampling.\n\nIn nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both.\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 0.7 + ], + "maximum": 1, + "minimum": 0, + "title": "Top P", + "type": "number" + }, + "top_k": { + "description": "Only sample from the top K options for each subsequent token.\n\nUsed to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 5 + ], + "minimum": 0, + "title": "Top K", + "type": "integer" + }, + "metadata": { + "allOf": [ + { + "$ref": "#/components/schemas/Metadata" + } + ], + "description": "An object describing metadata about the request." + }, + "stream": { + "description": "Whether to incrementally stream the response using server-sent events.\n\nSee [streaming](https://docs.anthropic.com/en/api/streaming) for details.", + "title": "Stream", + "type": "boolean" + } + }, + "required": [ + "prompt", + "max_tokens_to_sample", + "model" + ], + "title": "CompletionRequest", + "type": "object" + }, + "CompletionResponse": { + "properties": { + "type": { + "type": "string", + "enum": [ + "completion" + ], + "const": "completion", + "title": "Type", + "description": "Object type.\n\nFor Text Completions, this is always `\"completion\"`.", + "default": "completion" + }, + "id": { + "type": "string", + "title": "Id", + "description": "Unique object identifier.\n\nThe format and length of IDs may change over time." + }, + "completion": { + "type": "string", + "title": "Completion", + "description": "The resulting completion up to and excluding the stop sequences.", + "examples": [ + " Hello! My name is Claude." + ] + }, + "stop_reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Stop Reason", + "description": "The reason that we stopped.\n\nThis may be one the following values:\n* `\"stop_sequence\"`: we reached a stop sequence \u2014 either provided by you via the `stop_sequences` parameter, or a stop sequence built into the model\n* `\"max_tokens\"`: we exceeded `max_tokens_to_sample` or the model's maximum", + "examples": [ + "stop_sequence" + ] + }, + "model": { + "$ref": "#/components/schemas/Model" + } + }, + "type": "object", + "required": [ + "type", + "id", + "completion", + "stop_reason", + "model" + ], + "title": "CompletionResponse", + "example": { + "completion": " Hello! My name is Claude.", + "id": "compl_018CKm6gsux7P8yMcwZbeCPw", + "model": "claude-2.1", + "stop_reason": "stop_sequence", + "type": "completion" + } + }, + "ContentBlockDeltaEvent": { + "properties": { + "type": { + "const": "content_block_delta", + "default": "content_block_delta", + "enum": [ + "content_block_delta" + ], + "title": "Type", + "type": "string" + }, + "index": { + "title": "Index", + "type": "integer" + }, + "delta": { + "discriminator": { + "mapping": { + "input_json_delta": "#/components/schemas/InputJsonContentBlockDelta", + "text_delta": "#/components/schemas/TextContentBlockDelta" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/TextContentBlockDelta" + }, + { + "$ref": "#/components/schemas/InputJsonContentBlockDelta" + } + ], + "title": "Delta" + } + }, + "required": [ + "type", + "index", + "delta" + ], + "title": "ContentBlockDeltaEvent", + "type": "object", + "x-stainless-naming": { + "go": { + "model_name": "ContentBlockDeltaEvent" + } + } + }, + "ContentBlockStartEvent": { + "properties": { + "type": { + "const": "content_block_start", + "default": "content_block_start", + "enum": [ + "content_block_start" + ], + "title": "Type", + "type": "string" + }, + "index": { + "title": "Index", + "type": "integer" + }, + "content_block": { + "discriminator": { + "mapping": { + "text": "#/components/schemas/ResponseTextBlock", + "tool_use": "#/components/schemas/ResponseToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/ResponseTextBlock" + }, + { + "$ref": "#/components/schemas/ResponseToolUseBlock" + } + ], + "title": "Content Block" + } + }, + "required": [ + "type", + "index", + "content_block" + ], + "title": "ContentBlockStartEvent", + "type": "object", + "x-stainless-naming": { + "go": { + "model_name": "ContentBlockStartEvent" + } + } + }, + "ContentBlockStopEvent": { + "properties": { + "type": { + "const": "content_block_stop", + "default": "content_block_stop", + "enum": [ + "content_block_stop" + ], + "title": "Type", + "type": "string" + }, + "index": { + "title": "Index", + "type": "integer" + } + }, + "required": [ + "type", + "index" + ], + "title": "ContentBlockStopEvent", + "type": "object", + "x-stainless-naming": { + "go": { + "model_name": "ContentBlockStopEvent" + } + } + }, + "CreateMessageParams": { + "additionalProperties": false, + "example": { + "max_tokens": 1024, + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-3-5-sonnet-20241022" + }, + "properties": { + "model": { + "$ref": "#/components/schemas/Model" + }, + "messages": { + "description": "Input messages.\n\nOur models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.\n\nEach input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.\n\nIf the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.\n\nExample with a single `user` message:\n\n```json\n[{\"role\": \"user\", \"content\": \"Hello, Claude\"}]\n```\n\nExample with multiple conversational turns:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"Hello there.\"},\n {\"role\": \"assistant\", \"content\": \"Hi, I'm Claude. How can I help you?\"},\n {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"},\n]\n```\n\nExample with a partially-filled response from Claude:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"},\n]\n```\n\nEach input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent:\n\n```json\n{\"role\": \"user\", \"content\": \"Hello, Claude\"}\n```\n\n```json\n{\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]}\n```\n\nStarting with Claude 3 models, you can also send image content blocks:\n\n```json\n{\"role\": \"user\", \"content\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"media_type\": \"image/jpeg\",\n \"data\": \"/9j/4AAQSkZJRg...\",\n }\n },\n {\"type\": \"text\", \"text\": \"What is in this image?\"}\n]}\n```\n\nWe currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types.\n\nSee [examples](https://docs.anthropic.com/en/api/messages-examples#vision) for more input examples.\n\nNote that if you want to include a [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use the top-level `system` parameter \u2014 there is no `\"system\"` role for input messages in the Messages API.", + "items": { + "$ref": "#/components/schemas/InputMessage" + }, + "title": "Messages", + "type": "array" + }, + "max_tokens": { + "description": "The maximum number of tokens to generate before stopping.\n\nNote that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.\n\nDifferent models have different maximum values for this parameter. See [models](https://docs.anthropic.com/en/docs/models-overview) for details.", + "examples": [ + 1024 + ], + "minimum": 1, + "title": "Max Tokens", + "type": "integer" + }, + "metadata": { + "allOf": [ + { + "$ref": "#/components/schemas/Metadata" + } + ], + "description": "An object describing metadata about the request." + }, + "stop_sequences": { + "description": "Custom text sequences that will cause the model to stop generating.\n\nOur models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `\"end_turn\"`.\n\nIf you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `\"stop_sequence\"` and the response `stop_sequence` value will contain the matched stop sequence.", + "items": { + "type": "string" + }, + "title": "Stop Sequences", + "type": "array" + }, + "stream": { + "description": "Whether to incrementally stream the response using server-sent events.\n\nSee [streaming](https://docs.anthropic.com/en/api/messages-streaming) for details.", + "title": "Stream", + "type": "boolean" + }, + "system": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "$ref": "#/components/schemas/RequestTextBlock" + }, + "type": "array" + } + ], + "description": "System prompt.\n\nA system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts).", + "examples": [ + [ + { + "text": "Today's date is 2024-06-01.", + "type": "text" + } + ], + "Today's date is 2023-01-01." + ], + "title": "System" + }, + "temperature": { + "description": "Amount of randomness injected into the response.\n\nDefaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.\n\nNote that even with `temperature` of `0.0`, the results will not be fully deterministic.", + "examples": [ + 1 + ], + "maximum": 1, + "minimum": 0, + "title": "Temperature", + "type": "number" + }, + "tool_choice": { + "$ref": "#/components/schemas/ToolChoice" + }, + "tools": { + "description": "Definitions of tools that the model may use.\n\nIf you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.\n\nEach tool definition includes:\n\n* `name`: Name of the tool.\n* `description`: Optional, but strongly-recommended description of the tool.\n* `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks.\n\nFor example, if you defined `tools` as:\n\n```json\n[\n {\n \"name\": \"get_stock_price\",\n \"description\": \"Get the current stock price for a given ticker symbol.\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"ticker\": {\n \"type\": \"string\",\n \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\"\n }\n },\n \"required\": [\"ticker\"]\n }\n }\n]\n```\n\nAnd then asked the model \"What's the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this:\n\n```json\n[\n {\n \"type\": \"tool_use\",\n \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"name\": \"get_stock_price\",\n \"input\": { \"ticker\": \"^GSPC\" }\n }\n]\n```\n\nYou might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message:\n\n```json\n[\n {\n \"type\": \"tool_result\",\n \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"content\": \"259.75 USD\"\n }\n]\n```\n\nTools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.\n\nSee our [guide](https://docs.anthropic.com/en/docs/tool-use) for more details.", + "examples": [ + { + "description": "Get the current weather in a given location", + "input_schema": { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + }, + "name": "get_weather" + } + ], + "items": { + "$ref": "#/components/schemas/Tool" + }, + "title": "Tools", + "type": "array" + }, + "top_k": { + "description": "Only sample from the top K options for each subsequent token.\n\nUsed to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 5 + ], + "minimum": 0, + "title": "Top K", + "type": "integer" + }, + "top_p": { + "description": "Use nucleus sampling.\n\nIn nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both.\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 0.7 + ], + "maximum": 1, + "minimum": 0, + "title": "Top P", + "type": "number" + } + }, + "required": [ + "model", + "messages", + "max_tokens" + ], + "title": "CreateMessageParams", + "type": "object" + }, + "ErrorResponse": { + "properties": { + "type": { + "const": "error", + "default": "error", + "enum": [ + "error" + ], + "title": "Type", + "type": "string" + }, + "error": { + "discriminator": { + "mapping": { + "api_error": "#/components/schemas/APIError", + "authentication_error": "#/components/schemas/AuthenticationError", + "invalid_request_error": "#/components/schemas/InvalidRequestError", + "not_found_error": "#/components/schemas/NotFoundError", + "overloaded_error": "#/components/schemas/OverloadedError", + "permission_error": "#/components/schemas/PermissionError", + "rate_limit_error": "#/components/schemas/RateLimitError" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/InvalidRequestError" + }, + { + "$ref": "#/components/schemas/AuthenticationError" + }, + { + "$ref": "#/components/schemas/PermissionError" + }, + { + "$ref": "#/components/schemas/NotFoundError" + }, + { + "$ref": "#/components/schemas/RateLimitError" + }, + { + "$ref": "#/components/schemas/APIError" + }, + { + "$ref": "#/components/schemas/OverloadedError" + } + ], + "title": "Error" + } + }, + "required": [ + "type", + "error" + ], + "title": "ErrorResponse", + "type": "object" + }, + "InputJsonContentBlockDelta": { + "properties": { + "type": { + "const": "input_json_delta", + "default": "input_json_delta", + "enum": [ + "input_json_delta" + ], + "title": "Type", + "type": "string" + }, + "partial_json": { + "title": "Partial Json", + "type": "string" + } + }, + "required": [ + "type", + "partial_json" + ], + "title": "InputJsonContentBlockDelta", + "type": "object" + }, + "InputMessage": { + "additionalProperties": false, + "properties": { + "role": { + "enum": [ + "user", + "assistant" + ], + "title": "Role", + "type": "string" + }, + "content": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "discriminator": { + "mapping": { + "image": "#/components/schemas/RequestImageBlock", + "text": "#/components/schemas/RequestTextBlock", + "tool_result": "#/components/schemas/RequestToolResultBlock", + "tool_use": "#/components/schemas/RequestToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/RequestTextBlock" + }, + { + "$ref": "#/components/schemas/RequestImageBlock" + }, + { + "$ref": "#/components/schemas/RequestToolUseBlock" + }, + { + "$ref": "#/components/schemas/RequestToolResultBlock" + } + ], + "x-stainless-python-extend-union": [ + "ContentBlock" + ], + "x-stainless-python-extend-union-imports": [ + "from .content_block import ContentBlock" + ], + "title": "Block" + }, + "type": "array", + "example": [ + { + "type": "text", + "text": "What is a quaternion?" + } + ] + } + ], + "title": "Content" + } + }, + "required": [ + "role", + "content" + ], + "title": "InputMessage", + "type": "object" + }, + "InputSchema": { + "additionalProperties": true, + "properties": { + "type": { + "const": "object", + "enum": [ + "object" + ], + "title": "Type", + "type": "string" + }, + "properties": { + "anyOf": [ + { + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Properties" + } + }, + "required": [ + "type" + ], + "title": "InputSchema", + "type": "object" + }, + "InvalidRequestError": { + "properties": { + "type": { + "const": "invalid_request_error", + "default": "invalid_request_error", + "enum": [ + "invalid_request_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Invalid request", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "InvalidRequestError", + "type": "object" + }, + "Message": { + "examples": [ + { + "content": [ + { + "text": "Hi! My name is Claude.", + "type": "text" + } + ], + "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", + "model": "claude-3-5-sonnet-20241022", + "role": "assistant", + "stop_reason": "end_turn", + "stop_sequence": null, + "type": "message", + "usage": { + "input_tokens": 2095, + "output_tokens": 503 + } + } + ], + "properties": { + "id": { + "description": "Unique object identifier.\n\nThe format and length of IDs may change over time.", + "examples": [ + "msg_013Zva2CMHLNnXjNJJKqJ2EF" + ], + "title": "Id", + "type": "string" + }, + "type": { + "const": "message", + "default": "message", + "description": "Object type.\n\nFor Messages, this is always `\"message\"`.", + "enum": [ + "message" + ], + "title": "Type", + "type": "string" + }, + "role": { + "const": "assistant", + "default": "assistant", + "description": "Conversational role of the generated message.\n\nThis will always be `\"assistant\"`.", + "enum": [ + "assistant" + ], + "title": "Role", + "type": "string" + }, + "content": { + "description": "Content generated by the model.\n\nThis is an array of content blocks, each of which has a `type` that determines its shape.\n\nExample:\n\n```json\n[{\"type\": \"text\", \"text\": \"Hi, I'm Claude.\"}]\n```\n\nIf the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.\n\nFor example, if the input `messages` were:\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"}\n]\n```\n\nThen the response `content` might be:\n\n```json\n[{\"type\": \"text\", \"text\": \"B)\"}]\n```", + "examples": [ + [ + { + "text": "Hi! My name is Claude.", + "type": "text" + } + ] + ], + "items": { + "$ref": "#/components/schemas/ContentBlock" + }, + "title": "Content", + "type": "array" + }, + "model": { + "$ref": "#/components/schemas/Model" + }, + "stop_reason": { + "anyOf": [ + { + "enum": [ + "end_turn", + "max_tokens", + "stop_sequence", + "tool_use" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The reason that we stopped.\n\nThis may be one the following values:\n* `\"end_turn\"`: the model reached a natural stopping point\n* `\"max_tokens\"`: we exceeded the requested `max_tokens` or the model's maximum\n* `\"stop_sequence\"`: one of your provided custom `stop_sequences` was generated\n* `\"tool_use\"`: the model invoked one or more tools\n\nIn non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise.", + "title": "Stop Reason" + }, + "stop_sequence": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Which custom stop sequence was generated, if any.\n\nThis value will be a non-null string if one of your custom stop sequences was generated.", + "title": "Stop Sequence" + }, + "usage": { + "allOf": [ + { + "$ref": "#/components/schemas/Usage" + } + ], + "description": "Billing and rate-limit usage.\n\nAnthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.\n\nUnder the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response.\n\nFor example, `output_tokens` will be non-zero, even for an empty string response from Claude.", + "examples": [ + { + "input_tokens": 2095, + "output_tokens": 503 + } + ] + } + }, + "required": [ + "id", + "type", + "role", + "content", + "model", + "stop_reason", + "stop_sequence", + "usage" + ], + "title": "Message", + "type": "object", + "x-stainless-python-custom-imports": [ + "from .content_block import ContentBlock as ContentBlock" + ] + }, + "MessageDelta": { + "properties": { + "stop_reason": { + "anyOf": [ + { + "enum": [ + "end_turn", + "max_tokens", + "stop_sequence", + "tool_use" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Stop Reason" + }, + "stop_sequence": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Stop Sequence" + } + }, + "required": [ + "stop_reason", + "stop_sequence" + ], + "title": "MessageDelta", + "type": "object" + }, + "MessageDeltaEvent": { + "properties": { + "type": { + "const": "message_delta", + "default": "message_delta", + "enum": [ + "message_delta" + ], + "title": "Type", + "type": "string" + }, + "delta": { + "$ref": "#/components/schemas/MessageDelta" + }, + "usage": { + "allOf": [ + { + "$ref": "#/components/schemas/MessageDeltaUsage" + } + ], + "description": "Billing and rate-limit usage.\n\nAnthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.\n\nUnder the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response.\n\nFor example, `output_tokens` will be non-zero, even for an empty string response from Claude.", + "examples": [ + { + "output_tokens": 503 + } + ] + } + }, + "required": [ + "type", + "delta", + "usage" + ], + "title": "MessageDeltaEvent", + "type": "object", + "x-stainless-naming": { + "go": { + "model_name": "MessageDeltaEvent" + } + } + }, + "MessageDeltaUsage": { + "properties": { + "output_tokens": { + "description": "The cumulative number of output tokens which were used.", + "examples": [ + 503 + ], + "title": "Output Tokens", + "type": "integer" + } + }, + "required": [ + "output_tokens" + ], + "title": "MessageDeltaUsage", + "type": "object" + }, + "MessageStartEvent": { + "properties": { + "type": { + "const": "message_start", + "default": "message_start", + "enum": [ + "message_start" + ], + "title": "Type", + "type": "string" + }, + "message": { + "$ref": "#/components/schemas/Message" + } + }, + "required": [ + "type", + "message" + ], + "title": "MessageStartEvent", + "type": "object", + "x-stainless-naming": { + "go": { + "model_name": "MessageStartEvent" + } + } + }, + "MessageStopEvent": { + "properties": { + "type": { + "const": "message_stop", + "default": "message_stop", + "enum": [ + "message_stop" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type" + ], + "title": "MessageStopEvent", + "type": "object", + "x-stainless-naming": { + "go": { + "model_name": "MessageStopEvent" + } + } + }, + "MessageStreamEvent": { + "discriminator": { + "mapping": { + "content_block_delta": "#/components/schemas/ContentBlockDeltaEvent", + "content_block_start": "#/components/schemas/ContentBlockStartEvent", + "content_block_stop": "#/components/schemas/ContentBlockStopEvent", + "message_delta": "#/components/schemas/MessageDeltaEvent", + "message_start": "#/components/schemas/MessageStartEvent", + "message_stop": "#/components/schemas/MessageStopEvent" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/MessageStartEvent" + }, + { + "$ref": "#/components/schemas/MessageDeltaEvent" + }, + { + "$ref": "#/components/schemas/MessageStopEvent" + }, + { + "$ref": "#/components/schemas/ContentBlockStartEvent" + }, + { + "$ref": "#/components/schemas/ContentBlockDeltaEvent" + }, + { + "$ref": "#/components/schemas/ContentBlockStopEvent" + } + ], + "title": "MessageStreamEvent", + "x-stainless-naming": { + "go": { + "model_name": "MessageStreamEvent" + } + } + }, + "Metadata": { + "additionalProperties": false, + "properties": { + "user_id": { + "anyOf": [ + { + "maxLength": 256, + "type": "string" + }, + { + "type": "null" + } + ], + "description": "An external identifier for the user who is associated with the request.\n\nThis should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.", + "examples": [ + "13803d75-b4b5-4c3e-b2a2-6f21399b021b" + ], + "title": "User Id" + } + }, + "title": "Metadata", + "type": "object" + }, + "NotFoundError": { + "properties": { + "type": { + "const": "not_found_error", + "default": "not_found_error", + "enum": [ + "not_found_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Not found", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "NotFoundError", + "type": "object" + }, + "OverloadedError": { + "properties": { + "type": { + "const": "overloaded_error", + "default": "overloaded_error", + "enum": [ + "overloaded_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Overloaded", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "OverloadedError", + "type": "object" + }, + "PermissionError": { + "properties": { + "type": { + "const": "permission_error", + "default": "permission_error", + "enum": [ + "permission_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Permission denied", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "PermissionError", + "type": "object" + }, + "PromptCachingBetaCreateMessageParams": { + "additionalProperties": false, + "example": { + "max_tokens": 1024, + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-3-5-sonnet-20241022" + }, + "properties": { + "model": { + "$ref": "#/components/schemas/Model" + }, + "messages": { + "description": "Input messages.\n\nOur models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.\n\nEach input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.\n\nIf the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.\n\nExample with a single `user` message:\n\n```json\n[{\"role\": \"user\", \"content\": \"Hello, Claude\"}]\n```\n\nExample with multiple conversational turns:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"Hello there.\"},\n {\"role\": \"assistant\", \"content\": \"Hi, I'm Claude. How can I help you?\"},\n {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"},\n]\n```\n\nExample with a partially-filled response from Claude:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"},\n]\n```\n\nEach input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent:\n\n```json\n{\"role\": \"user\", \"content\": \"Hello, Claude\"}\n```\n\n```json\n{\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]}\n```\n\nStarting with Claude 3 models, you can also send image content blocks:\n\n```json\n{\"role\": \"user\", \"content\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"media_type\": \"image/jpeg\",\n \"data\": \"/9j/4AAQSkZJRg...\",\n }\n },\n {\"type\": \"text\", \"text\": \"What is in this image?\"}\n]}\n```\n\nWe currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types.\n\nSee [examples](https://docs.anthropic.com/en/api/messages-examples#vision) for more input examples.\n\nNote that if you want to include a [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use the top-level `system` parameter \u2014 there is no `\"system\"` role for input messages in the Messages API.", + "items": { + "$ref": "#/components/schemas/PromptCachingBetaInputMessage" + }, + "title": "Messages", + "type": "array" + }, + "max_tokens": { + "description": "The maximum number of tokens to generate before stopping.\n\nNote that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.\n\nDifferent models have different maximum values for this parameter. See [models](https://docs.anthropic.com/en/docs/models-overview) for details.", + "examples": [ + 1024 + ], + "minimum": 1, + "title": "Max Tokens", + "type": "integer" + }, + "metadata": { + "allOf": [ + { + "$ref": "#/components/schemas/Metadata" + } + ], + "description": "An object describing metadata about the request." + }, + "stop_sequences": { + "description": "Custom text sequences that will cause the model to stop generating.\n\nOur models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `\"end_turn\"`.\n\nIf you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `\"stop_sequence\"` and the response `stop_sequence` value will contain the matched stop sequence.", + "items": { + "type": "string" + }, + "title": "Stop Sequences", + "type": "array" + }, + "stream": { + "description": "Whether to incrementally stream the response using server-sent events.\n\nSee [streaming](https://docs.anthropic.com/en/api/messages-streaming) for details.", + "title": "Stream", + "type": "boolean" + }, + "system": { + "anyOf": [ + { + "type": "string" + }, + { + "items": { + "$ref": "#/components/schemas/PromptCachingBetaRequestTextBlock" + }, + "type": "array" + } + ], + "description": "System prompt.\n\nA system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts).", + "examples": [ + [ + { + "text": "Today's date is 2024-06-01.", + "type": "text" + } + ], + "Today's date is 2023-01-01." + ], + "title": "System" + }, + "temperature": { + "description": "Amount of randomness injected into the response.\n\nDefaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.\n\nNote that even with `temperature` of `0.0`, the results will not be fully deterministic.", + "examples": [ + 1 + ], + "maximum": 1, + "minimum": 0, + "title": "Temperature", + "type": "number" + }, + "tool_choice": { + "$ref": "#/components/schemas/ToolChoice" + }, + "tools": { + "description": "Definitions of tools that the model may use.\n\nIf you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.\n\nEach tool definition includes:\n\n* `name`: Name of the tool.\n* `description`: Optional, but strongly-recommended description of the tool.\n* `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks.\n\nFor example, if you defined `tools` as:\n\n```json\n[\n {\n \"name\": \"get_stock_price\",\n \"description\": \"Get the current stock price for a given ticker symbol.\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"ticker\": {\n \"type\": \"string\",\n \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\"\n }\n },\n \"required\": [\"ticker\"]\n }\n }\n]\n```\n\nAnd then asked the model \"What's the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this:\n\n```json\n[\n {\n \"type\": \"tool_use\",\n \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"name\": \"get_stock_price\",\n \"input\": { \"ticker\": \"^GSPC\" }\n }\n]\n```\n\nYou might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message:\n\n```json\n[\n {\n \"type\": \"tool_result\",\n \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"content\": \"259.75 USD\"\n }\n]\n```\n\nTools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.\n\nSee our [guide](https://docs.anthropic.com/en/docs/tool-use) for more details.", + "examples": [ + { + "description": "Get the current weather in a given location", + "input_schema": { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + }, + "name": "get_weather" + } + ], + "items": { + "$ref": "#/components/schemas/PromptCachingBetaTool" + }, + "title": "Tools", + "type": "array" + }, + "top_k": { + "description": "Only sample from the top K options for each subsequent token.\n\nUsed to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 5 + ], + "minimum": 0, + "title": "Top K", + "type": "integer" + }, + "top_p": { + "description": "Use nucleus sampling.\n\nIn nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both.\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 0.7 + ], + "maximum": 1, + "minimum": 0, + "title": "Top P", + "type": "number" + } + }, + "required": [ + "model", + "messages", + "max_tokens" + ], + "title": "CreateMessageParams", + "type": "object" + }, + "PromptCachingBetaInputMessage": { + "additionalProperties": false, + "properties": { + "role": { + "enum": [ + "user", + "assistant" + ], + "title": "Role", + "type": "string" + }, + "content": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "discriminator": { + "mapping": { + "image": "#/components/schemas/PromptCachingBetaRequestImageBlock", + "text": "#/components/schemas/PromptCachingBetaRequestTextBlock", + "tool_result": "#/components/schemas/PromptCachingBetaRequestToolResultBlock", + "tool_use": "#/components/schemas/PromptCachingBetaRequestToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/PromptCachingBetaRequestTextBlock" + }, + { + "$ref": "#/components/schemas/PromptCachingBetaRequestImageBlock" + }, + { + "$ref": "#/components/schemas/PromptCachingBetaRequestToolUseBlock" + }, + { + "$ref": "#/components/schemas/PromptCachingBetaRequestToolResultBlock" + } + ], + "x-stainless-python-extend-union": [ + "ContentBlock" + ], + "x-stainless-python-extend-union-imports": [ + "from ...content_block import ContentBlock" + ], + "title": "Block" + }, + "type": "array", + "example": [ + { + "type": "text", + "text": "What is a quaternion?" + } + ] + } + ], + "title": "Content" + } + }, + "required": [ + "role", + "content" + ], + "title": "InputMessage", + "type": "object" + }, + "PromptCachingBetaMessage": { + "examples": [ + { + "content": [ + { + "text": "Hi! My name is Claude.", + "type": "text" + } + ], + "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", + "model": "claude-3-5-sonnet-20241022", + "role": "assistant", + "stop_reason": "end_turn", + "stop_sequence": null, + "type": "message", + "usage": { + "input_tokens": 2095, + "output_tokens": 503 + } + } + ], + "properties": { + "id": { + "description": "Unique object identifier.\n\nThe format and length of IDs may change over time.", + "examples": [ + "msg_013Zva2CMHLNnXjNJJKqJ2EF" + ], + "title": "Id", + "type": "string" + }, + "type": { + "const": "message", + "default": "message", + "description": "Object type.\n\nFor Messages, this is always `\"message\"`.", + "enum": [ + "message" + ], + "title": "Type", + "type": "string" + }, + "role": { + "const": "assistant", + "default": "assistant", + "description": "Conversational role of the generated message.\n\nThis will always be `\"assistant\"`.", + "enum": [ + "assistant" + ], + "title": "Role", + "type": "string" + }, + "content": { + "description": "Content generated by the model.\n\nThis is an array of content blocks, each of which has a `type` that determines its shape.\n\nExample:\n\n```json\n[{\"type\": \"text\", \"text\": \"Hi, I'm Claude.\"}]\n```\n\nIf the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.\n\nFor example, if the input `messages` were:\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"}\n]\n```\n\nThen the response `content` might be:\n\n```json\n[{\"type\": \"text\", \"text\": \"B)\"}]\n```", + "examples": [ + [ + { + "text": "Hi! My name is Claude.", + "type": "text" + } + ] + ], + "items": { + "$ref": "#/components/schemas/ContentBlock" + }, + "title": "Content", + "type": "array" + }, + "model": { + "$ref": "#/components/schemas/Model" + }, + "stop_reason": { + "anyOf": [ + { + "enum": [ + "end_turn", + "max_tokens", + "stop_sequence", + "tool_use" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The reason that we stopped.\n\nThis may be one the following values:\n* `\"end_turn\"`: the model reached a natural stopping point\n* `\"max_tokens\"`: we exceeded the requested `max_tokens` or the model's maximum\n* `\"stop_sequence\"`: one of your provided custom `stop_sequences` was generated\n* `\"tool_use\"`: the model invoked one or more tools\n\nIn non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise.", + "title": "Stop Reason" + }, + "stop_sequence": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Which custom stop sequence was generated, if any.\n\nThis value will be a non-null string if one of your custom stop sequences was generated.", + "title": "Stop Sequence" + }, + "usage": { + "allOf": [ + { + "$ref": "#/components/schemas/PromptCachingBetaUsage" + } + ], + "description": "Billing and rate-limit usage.\n\nAnthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.\n\nUnder the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response.\n\nFor example, `output_tokens` will be non-zero, even for an empty string response from Claude.", + "examples": [ + { + "input_tokens": 2095, + "output_tokens": 503 + } + ] + } + }, + "required": [ + "id", + "type", + "role", + "content", + "model", + "stop_reason", + "stop_sequence", + "usage" + ], + "title": "Message", + "type": "object" + }, + "PromptCachingBetaMessageStartEvent": { + "properties": { + "type": { + "const": "message_start", + "default": "message_start", + "enum": [ + "message_start" + ], + "title": "Type", + "type": "string" + }, + "message": { + "$ref": "#/components/schemas/PromptCachingBetaMessage" + } + }, + "required": [ + "type", + "message" + ], + "title": "MessageStartEvent", + "type": "object" + }, + "PromptCachingBetaMessageStreamEvent": { + "discriminator": { + "mapping": { + "content_block_delta": "#/components/schemas/ContentBlockDeltaEvent", + "content_block_start": "#/components/schemas/ContentBlockStartEvent", + "content_block_stop": "#/components/schemas/ContentBlockStopEvent", + "message_delta": "#/components/schemas/MessageDeltaEvent", + "message_start": "#/components/schemas/PromptCachingBetaMessageStartEvent", + "message_stop": "#/components/schemas/MessageStopEvent" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/PromptCachingBetaMessageStartEvent" + }, + { + "$ref": "#/components/schemas/MessageDeltaEvent" + }, + { + "$ref": "#/components/schemas/MessageStopEvent" + }, + { + "$ref": "#/components/schemas/ContentBlockStartEvent" + }, + { + "$ref": "#/components/schemas/ContentBlockDeltaEvent" + }, + { + "$ref": "#/components/schemas/ContentBlockStopEvent" + } + ], + "title": "MessageStreamEvent" + }, + "PromptCachingBetaRequestImageBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/CacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/CacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "image", + "enum": [ + "image" + ], + "title": "Type", + "type": "string" + }, + "source": { + "discriminator": { + "mapping": { + "base64": "#/components/schemas/Base64ImageSource" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/Base64ImageSource" + } + ], + "title": "Source" + } + }, + "required": [ + "type", + "source" + ], + "title": "RequestImageBlock", + "type": "object" + }, + "PromptCachingBetaRequestTextBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/CacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/CacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "text", + "enum": [ + "text" + ], + "title": "Type", + "type": "string" + }, + "text": { + "minLength": 1, + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "RequestTextBlock", + "type": "object" + }, + "PromptCachingBetaRequestToolResultBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/CacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/CacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "tool_result", + "enum": [ + "tool_result" + ], + "title": "Type", + "type": "string" + }, + "tool_use_id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Tool Use Id", + "type": "string" + }, + "is_error": { + "title": "Is Error", + "type": "boolean" + }, + "content": { + "anyOf": [ + { + "type": "string" + }, + { + "items": { + "discriminator": { + "mapping": { + "image": "#/components/schemas/PromptCachingBetaRequestImageBlock", + "text": "#/components/schemas/PromptCachingBetaRequestTextBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/PromptCachingBetaRequestTextBlock" + }, + { + "$ref": "#/components/schemas/PromptCachingBetaRequestImageBlock" + } + ], + "title": "Block" + }, + "type": "array", + "x-stainless-naming": { + "python": { + "type_name": "Content" + } + } + } + ], + "title": "Content" + } + }, + "required": [ + "type", + "tool_use_id" + ], + "title": "RequestToolResultBlock", + "type": "object" + }, + "PromptCachingBetaRequestToolUseBlock": { + "additionalProperties": false, + "properties": { + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/CacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/CacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + }, + "type": { + "const": "tool_use", + "enum": [ + "tool_use" + ], + "title": "Type", + "type": "string" + }, + "id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Id", + "type": "string" + }, + "name": { + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Name", + "type": "string" + }, + "input": { + "title": "Input", + "type": "object" + } + }, + "required": [ + "type", + "id", + "name", + "input" + ], + "title": "RequestToolUseBlock", + "type": "object" + }, + "PromptCachingBetaTool": { + "additionalProperties": false, + "properties": { + "description": { + "description": "Description of what this tool does.\n\nTool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema.", + "examples": [ + "Get the current weather in a given location" + ], + "title": "Description", + "type": "string" + }, + "name": { + "description": "Name of the tool.\n\nThis is how the tool will be called by the model and in tool_use blocks.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Name", + "type": "string" + }, + "input_schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InputSchema" + } + ], + "description": "[JSON schema](https://json-schema.org/) for this tool's input.\n\nThis defines the shape of the `input` that your tool accepts and that the model will produce.", + "examples": [ + { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + } + ] + }, + "cache_control": { + "anyOf": [ + { + "discriminator": { + "mapping": { + "ephemeral": "#/components/schemas/CacheControlEphemeral" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/CacheControlEphemeral" + } + ] + }, + { + "type": "null" + } + ], + "title": "Cache Control" + } + }, + "required": [ + "name", + "input_schema" + ], + "title": "Tool", + "type": "object" + }, + "PromptCachingBetaUsage": { + "properties": { + "input_tokens": { + "description": "The number of input tokens which were used.", + "examples": [ + 2095 + ], + "title": "Input Tokens", + "type": "integer" + }, + "cache_creation_input_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "description": "The number of input tokens used to create the cache entry.", + "examples": [ + 2051 + ], + "title": "Cache Creation Input Tokens" + }, + "cache_read_input_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "description": "The number of input tokens read from the cache.", + "examples": [ + 2051 + ], + "title": "Cache Read Input Tokens" + }, + "output_tokens": { + "description": "The number of output tokens which were used.", + "examples": [ + 503 + ], + "title": "Output Tokens", + "type": "integer" + } + }, + "required": [ + "input_tokens", + "cache_creation_input_tokens", + "cache_read_input_tokens", + "output_tokens" + ], + "title": "Usage", + "type": "object" + }, + "RateLimitError": { + "properties": { + "type": { + "const": "rate_limit_error", + "default": "rate_limit_error", + "enum": [ + "rate_limit_error" + ], + "title": "Type", + "type": "string" + }, + "message": { + "default": "Rate limited", + "title": "Message", + "type": "string" + } + }, + "required": [ + "type", + "message" + ], + "title": "RateLimitError", + "type": "object" + }, + "RequestImageBlock": { + "additionalProperties": false, + "properties": { + "type": { + "const": "image", + "enum": [ + "image" + ], + "title": "Type", + "type": "string" + }, + "source": { + "discriminator": { + "mapping": { + "base64": "#/components/schemas/Base64ImageSource" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/Base64ImageSource" + } + ], + "title": "Source" + } + }, + "required": [ + "type", + "source" + ], + "title": "RequestImageBlock", + "type": "object" + }, + "RequestTextBlock": { + "additionalProperties": false, + "properties": { + "type": { + "const": "text", + "enum": [ + "text" + ], + "title": "Type", + "type": "string" + }, + "text": { + "minLength": 1, + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "RequestTextBlock", + "type": "object" + }, + "RequestToolResultBlock": { + "additionalProperties": false, + "properties": { + "type": { + "const": "tool_result", + "enum": [ + "tool_result" + ], + "title": "Type", + "type": "string" + }, + "tool_use_id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Tool Use Id", + "type": "string" + }, + "is_error": { + "title": "Is Error", + "type": "boolean" + }, + "content": { + "anyOf": [ + { + "type": "string", + "x-stainless-skip": [ + "go" + ] + }, + { + "items": { + "discriminator": { + "mapping": { + "image": "#/components/schemas/RequestImageBlock", + "text": "#/components/schemas/RequestTextBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/RequestTextBlock" + }, + { + "$ref": "#/components/schemas/RequestImageBlock" + } + ], + "title": "Block" + }, + "type": "array", + "x-stainless-naming": { + "python": { + "type_name": "Content" + } + } + } + ], + "title": "Content" + } + }, + "required": [ + "type", + "tool_use_id" + ], + "title": "RequestToolResultBlock", + "type": "object" + }, + "RequestToolUseBlock": { + "additionalProperties": false, + "properties": { + "type": { + "const": "tool_use", + "enum": [ + "tool_use" + ], + "title": "Type", + "type": "string" + }, + "id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Id", + "type": "string" + }, + "name": { + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Name", + "type": "string" + }, + "input": { + "title": "Input", + "type": "object" + } + }, + "required": [ + "type", + "id", + "name", + "input" + ], + "title": "RequestToolUseBlock", + "type": "object" + }, + "ResponseTextBlock": { + "properties": { + "type": { + "const": "text", + "default": "text", + "enum": [ + "text" + ], + "title": "Type", + "type": "string" + }, + "text": { + "maxLength": 5000000, + "minLength": 0, + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "ResponseTextBlock", + "type": "object" + }, + "ResponseToolUseBlock": { + "properties": { + "type": { + "const": "tool_use", + "default": "tool_use", + "enum": [ + "tool_use" + ], + "title": "Type", + "type": "string" + }, + "id": { + "pattern": "^[a-zA-Z0-9_-]+$", + "title": "Id", + "type": "string" + }, + "name": { + "minLength": 1, + "title": "Name", + "type": "string" + }, + "input": { + "title": "Input", + "type": "object" + } + }, + "required": [ + "type", + "id", + "name", + "input" + ], + "title": "ResponseToolUseBlock", + "type": "object" + }, + "TextContentBlockDelta": { + "properties": { + "type": { + "const": "text_delta", + "default": "text_delta", + "enum": [ + "text_delta" + ], + "title": "Type", + "type": "string" + }, + "text": { + "title": "Text", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "TextContentBlockDelta", + "type": "object" + }, + "Tool": { + "additionalProperties": false, + "properties": { + "description": { + "description": "Description of what this tool does.\n\nTool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema.", + "examples": [ + "Get the current weather in a given location" + ], + "title": "Description", + "type": "string" + }, + "name": { + "description": "Name of the tool.\n\nThis is how the tool will be called by the model and in tool_use blocks.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z0-9_-]{1,64}$", + "title": "Name", + "type": "string" + }, + "input_schema": { + "allOf": [ + { + "$ref": "#/components/schemas/InputSchema" + } + ], + "description": "[JSON schema](https://json-schema.org/) for this tool's input.\n\nThis defines the shape of the `input` that your tool accepts and that the model will produce.", + "examples": [ + { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + } + ] + } + }, + "required": [ + "name", + "input_schema" + ], + "title": "Tool", + "type": "object" + }, + "ToolChoiceAny": { + "additionalProperties": false, + "description": "The model will use any available tools.", + "properties": { + "type": { + "const": "any", + "enum": [ + "any" + ], + "title": "Type", + "type": "string" + }, + "disable_parallel_tool_use": { + "description": "Whether to disable parallel tool use.\n\nDefaults to `false`. If set to `true`, the model will output exactly one tool use.", + "title": "Disable Parallel Tool Use", + "type": "boolean" + } + }, + "required": [ + "type" + ], + "title": "ToolChoiceAny", + "type": "object" + }, + "ToolChoiceAuto": { + "additionalProperties": false, + "description": "The model will automatically decide whether to use tools.", + "properties": { + "type": { + "const": "auto", + "enum": [ + "auto" + ], + "title": "Type", + "type": "string" + }, + "disable_parallel_tool_use": { + "description": "Whether to disable parallel tool use.\n\nDefaults to `false`. If set to `true`, the model will output at most one tool use.", + "title": "Disable Parallel Tool Use", + "type": "boolean" + } + }, + "required": [ + "type" + ], + "title": "ToolChoiceAuto", + "type": "object" + }, + "ToolChoiceTool": { + "additionalProperties": false, + "description": "The model will use the specified tool with `tool_choice.name`.", + "properties": { + "type": { + "const": "tool", + "enum": [ + "tool" + ], + "title": "Type", + "type": "string" + }, + "name": { + "description": "The name of the tool to use.", + "title": "Name", + "type": "string" + }, + "disable_parallel_tool_use": { + "description": "Whether to disable parallel tool use.\n\nDefaults to `false`. If set to `true`, the model will output exactly one tool use.", + "title": "Disable Parallel Tool Use", + "type": "boolean" + } + }, + "required": [ + "type", + "name" + ], + "title": "ToolChoiceTool", + "type": "object" + }, + "Usage": { + "properties": { + "input_tokens": { + "description": "The number of input tokens which were used.", + "examples": [ + 2095 + ], + "title": "Input Tokens", + "type": "integer" + }, + "output_tokens": { + "description": "The number of output tokens which were used.", + "examples": [ + 503 + ], + "title": "Output Tokens", + "type": "integer" + } + }, + "required": [ + "input_tokens", + "output_tokens" + ], + "title": "Usage", + "type": "object" + }, + "BetaMessageBatchResult": { + "description": "Processing result for this request.\n\nContains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.", + "discriminator": { + "mapping": { + "canceled": "#/components/schemas/BetaCanceledResult", + "errored": "#/components/schemas/BetaErroredResult", + "expired": "#/components/schemas/BetaExpiredResult", + "succeeded": "#/components/schemas/BetaSucceededResult" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaSucceededResult" + }, + { + "$ref": "#/components/schemas/BetaErroredResult" + }, + { + "$ref": "#/components/schemas/BetaCanceledResult" + }, + { + "$ref": "#/components/schemas/BetaExpiredResult" + } + ], + "title": "Result" + }, + "CreateMessageParamsWithoutStream": { + "additionalProperties": false, + "example": { + "max_tokens": 1024, + "messages": [ + { + "content": "Hello, world", + "role": "user" + } + ], + "model": "claude-3-5-sonnet-20241022" + }, + "properties": { + "model": { + "$ref": "#/components/schemas/Model" + }, + "messages": { + "description": "Input messages.\n\nOur models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.\n\nEach input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.\n\nIf the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.\n\nExample with a single `user` message:\n\n```json\n[{\"role\": \"user\", \"content\": \"Hello, Claude\"}]\n```\n\nExample with multiple conversational turns:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"Hello there.\"},\n {\"role\": \"assistant\", \"content\": \"Hi, I'm Claude. How can I help you?\"},\n {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"},\n]\n```\n\nExample with a partially-filled response from Claude:\n\n```json\n[\n {\"role\": \"user\", \"content\": \"What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"},\n {\"role\": \"assistant\", \"content\": \"The best answer is (\"},\n]\n```\n\nEach input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent:\n\n```json\n{\"role\": \"user\", \"content\": \"Hello, Claude\"}\n```\n\n```json\n{\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]}\n```\n\nStarting with Claude 3 models, you can also send image content blocks:\n\n```json\n{\"role\": \"user\", \"content\": [\n {\n \"type\": \"image\",\n \"source\": {\n \"type\": \"base64\",\n \"media_type\": \"image/jpeg\",\n \"data\": \"/9j/4AAQSkZJRg...\",\n }\n },\n {\"type\": \"text\", \"text\": \"What is in this image?\"}\n]}\n```\n\nWe currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types.\n\nSee [examples](https://docs.anthropic.com/en/api/messages-examples#vision) for more input examples.\n\nNote that if you want to include a [system prompt](https://docs.anthropic.com/en/docs/system-prompts), you can use the top-level `system` parameter \u2014 there is no `\"system\"` role for input messages in the Messages API.", + "items": { + "$ref": "#/components/schemas/InputMessage" + }, + "title": "Messages", + "type": "array" + }, + "max_tokens": { + "description": "The maximum number of tokens to generate before stopping.\n\nNote that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.\n\nDifferent models have different maximum values for this parameter. See [models](https://docs.anthropic.com/en/docs/models-overview) for details.", + "examples": [ + 1024 + ], + "minimum": 1, + "title": "Max Tokens", + "type": "integer" + }, + "metadata": { + "allOf": [ + { + "$ref": "#/components/schemas/Metadata" + } + ], + "description": "An object describing metadata about the request." + }, + "stop_sequences": { + "description": "Custom text sequences that will cause the model to stop generating.\n\nOur models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `\"end_turn\"`.\n\nIf you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `\"stop_sequence\"` and the response `stop_sequence` value will contain the matched stop sequence.", + "items": { + "type": "string" + }, + "title": "Stop Sequences", + "type": "array" + }, + "system": { + "anyOf": [ + { + "type": "string" + }, + { + "items": { + "$ref": "#/components/schemas/RequestTextBlock" + }, + "type": "array" + } + ], + "description": "System prompt.\n\nA system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.anthropic.com/en/docs/system-prompts).", + "examples": [ + [ + { + "text": "Today's date is 2024-06-01.", + "type": "text" + } + ], + "Today's date is 2023-01-01." + ], + "title": "System" + }, + "temperature": { + "description": "Amount of randomness injected into the response.\n\nDefaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.\n\nNote that even with `temperature` of `0.0`, the results will not be fully deterministic.", + "examples": [ + 1 + ], + "maximum": 1, + "minimum": 0, + "title": "Temperature", + "type": "number" + }, + "tool_choice": { + "$ref": "#/components/schemas/ToolChoice" + }, + "tools": { + "description": "Definitions of tools that the model may use.\n\nIf you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.\n\nEach tool definition includes:\n\n* `name`: Name of the tool.\n* `description`: Optional, but strongly-recommended description of the tool.\n* `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks.\n\nFor example, if you defined `tools` as:\n\n```json\n[\n {\n \"name\": \"get_stock_price\",\n \"description\": \"Get the current stock price for a given ticker symbol.\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"ticker\": {\n \"type\": \"string\",\n \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\"\n }\n },\n \"required\": [\"ticker\"]\n }\n }\n]\n```\n\nAnd then asked the model \"What's the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this:\n\n```json\n[\n {\n \"type\": \"tool_use\",\n \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"name\": \"get_stock_price\",\n \"input\": { \"ticker\": \"^GSPC\" }\n }\n]\n```\n\nYou might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message:\n\n```json\n[\n {\n \"type\": \"tool_result\",\n \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\",\n \"content\": \"259.75 USD\"\n }\n]\n```\n\nTools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.\n\nSee our [guide](https://docs.anthropic.com/en/docs/tool-use) for more details.", + "examples": [ + { + "description": "Get the current weather in a given location", + "input_schema": { + "properties": { + "location": { + "description": "The city and state, e.g. San Francisco, CA", + "type": "string" + }, + "unit": { + "description": "Unit for the output - one of (celsius, fahrenheit)", + "type": "string" + } + }, + "required": [ + "location" + ], + "type": "object" + }, + "name": "get_weather" + } + ], + "items": { + "$ref": "#/components/schemas/Tool" + }, + "title": "Tools", + "type": "array" + }, + "top_k": { + "description": "Only sample from the top K options for each subsequent token.\n\nUsed to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 5 + ], + "minimum": 0, + "title": "Top K", + "type": "integer" + }, + "top_p": { + "description": "Use nucleus sampling.\n\nIn nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both.\n\nRecommended for advanced use cases only. You usually only need to use `temperature`.", + "examples": [ + 0.7 + ], + "maximum": 1, + "minimum": 0, + "title": "Top P", + "type": "number" + } + }, + "required": [ + "model", + "messages", + "max_tokens" + ], + "title": "CreateMessageParams", + "type": "object" + }, + "AnthropicBeta": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "enum": [ + "message-batches-2024-09-24", + "prompt-caching-2024-07-31", + "computer-use-2024-10-22", + "pdfs-2024-09-25" + ], + "x-stainless-nominal": false, + "title": "Preset" + } + ] + }, + "ToolChoice": { + "description": "How the model should use the provided tools. The model can use a specific tool, any available tool, or decide by itself.", + "discriminator": { + "mapping": { + "any": "#/components/schemas/ToolChoiceAny", + "auto": "#/components/schemas/ToolChoiceAuto", + "tool": "#/components/schemas/ToolChoiceTool" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/ToolChoiceAuto" + }, + { + "$ref": "#/components/schemas/ToolChoiceAny" + }, + { + "$ref": "#/components/schemas/ToolChoiceTool" + } + ], + "title": "Tool Choice" + }, + "BetaToolChoice": { + "description": "How the model should use the provided tools. The model can use a specific tool, any available tool, or decide by itself.", + "discriminator": { + "mapping": { + "any": "#/components/schemas/BetaToolChoiceAny", + "auto": "#/components/schemas/BetaToolChoiceAuto", + "tool": "#/components/schemas/BetaToolChoiceTool" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaToolChoiceAuto" + }, + { + "$ref": "#/components/schemas/BetaToolChoiceAny" + }, + { + "$ref": "#/components/schemas/BetaToolChoiceTool" + } + ], + "title": "Tool Choice" + }, + "ContentBlock": { + "discriminator": { + "mapping": { + "text": "#/components/schemas/ResponseTextBlock", + "tool_use": "#/components/schemas/ResponseToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/ResponseTextBlock" + }, + { + "$ref": "#/components/schemas/ResponseToolUseBlock" + } + ] + }, + "BetaContentBlock": { + "discriminator": { + "mapping": { + "text": "#/components/schemas/BetaResponseTextBlock", + "tool_use": "#/components/schemas/BetaResponseToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaResponseTextBlock" + }, + { + "$ref": "#/components/schemas/BetaResponseToolUseBlock" + } + ] + }, + "BetaInputContentBlock": { + "discriminator": { + "mapping": { + "document": "#/components/schemas/BetaRequestPDFBlock", + "image": "#/components/schemas/BetaRequestImageBlock", + "text": "#/components/schemas/BetaRequestTextBlock", + "tool_result": "#/components/schemas/BetaRequestToolResultBlock", + "tool_use": "#/components/schemas/BetaRequestToolUseBlock" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/BetaRequestTextBlock" + }, + { + "$ref": "#/components/schemas/BetaRequestImageBlock" + }, + { + "$ref": "#/components/schemas/BetaRequestToolUseBlock" + }, + { + "$ref": "#/components/schemas/BetaRequestToolResultBlock" + }, + { + "$ref": "#/components/schemas/BetaRequestPDFBlock" + } + ] + }, + "Model": { + "type": null, + "title": "Model", + "description": "The model that will complete your prompt.\\n\\nSee [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.", + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "title": "Preset", + "enum": [ + "claude-3-5-sonnet-latest", + "claude-3-5-sonnet-20241022", + "claude-3-5-sonnet-20240620", + "claude-3-opus-latest", + "claude-3-opus-20240229", + "claude-3-sonnet-20240229", + "claude-3-haiku-20240307", + "claude-2.1", + "claude-2.0", + "claude-instant-1.2" + ], + "x-enum-descriptions": [ + "Our most intelligent model", + "Our most intelligent model", + "Our previous most intelligent model", + "Excels at writing and complex tasks", + "Excels at writing and complex tasks", + "Balance of speed and intelligence", + "Fast and cost-effective", + null, + null, + null + ], + "x-stainless-nominal": false + } + ] + } + } + }, + "servers": [ + { + "url": "https://api.anthropic.com" + } + ] +} \ No newline at end of file diff --git a/mise.toml b/mise.toml index 6df20abb..55b00650 100644 --- a/mise.toml +++ b/mise.toml @@ -2,6 +2,7 @@ experimental = true [tools] +"spm:apple/swift-openapi-generator" = "1.12.2" "spm:swiftlang/swift-format" = "602.0.0" "aqua:realm/SwiftLint" = "0.62.2" "spm:peripheryapp/periphery" = "3.7.4"