cleanup docs, align API

Sources/Formic/Documentation.docc/Documentation.md

@@ -17,10 +17,7 @@ Quite a is inspired by [Ansible](https://github.com/ansible/ansible), with a goa
 
 ### Running Playbooks
 
-- ``Playbook``
 - ``Engine``
-- ``PlaybookStatus``
-- ``PlaybookState``
 - ``CommandExecutionResult``
 - ``Verbosity``
 
@@ -41,7 +38,7 @@ Quite a is inspired by [Ansible](https://github.com/ansible/ansible), with a goa
 ### Resources
 
 - ``OperatingSystem``
-- ``DebianPackage``
+- ``Dpkg``
 
 - ``Resource``
 - ``StatefulResource``
@@ -52,5 +49,4 @@ Quite a is inspired by [Ansible](https://github.com/ansible/ansible), with a goa
 
 ### Collections of Resources
 
-- ``CollectionQueryableResource``
-- ``NamedResource``
+- ``CollectionResource``

Sources/Formic/Documentation.docc/Engine/CommandExecutionResult.md

@@ -6,7 +6,6 @@
 
 - ``command``
 - ``host``
-- ``playbookId``
 - ``output``
 - ``duration``
 - ``retries``

Sources/Formic/Documentation.docc/Engine/Engine.md

@@ -8,20 +8,14 @@
 
 ### Running Playbooks
 
-- ``schedule(_:delay:startRunner:)``
-- ``step(for:)``
-- ``cancel(_:)``
+- ``run(host:commands:displayProgress:verbosity:)``
+- ``run(hosts:commands:displayProgress:verbosity:)``
 
-### Receiving Updates from the Engine
-
-- ``commandUpdates``
-- ``playbookUpdates``
-- ``status(_:)``
+### Running an individual command
 
-### Inspecting the Engine
+- ``run(host:command:)``
 
-- ``runnerOperating(for:)``
+### Receiving Updates from the Engine
 
-### Controlling the Engine
+- ``commandUpdates``
 
-- ``cancelRunner(for:)``

Sources/Formic/Engine/CommandExecutionResult.swift

@@ -17,7 +17,6 @@ public struct CommandExecutionResult: Sendable {
     /// - Parameters:
     ///   - command: The command.
     ///   - host: The host for the command.
-    ///   - playbookId: The ID of the playbook the command is part of, it any.
     ///   - output: The output from the command
     ///   - duration: The duration of execution of the command.
     ///   - retries: The number of retries needed for the command.

Sources/Formic/Engine/Engine.swift

@@ -30,7 +30,7 @@ public actor Engine {
     ) async throws -> [CommandExecutionResult] {
         var results: [CommandExecutionResult] = []
         for command in commands {
-            let result = try await run(command: command, host: host)
+            let result = try await run(host: host, command: command)
             results.append(result)
             if displayProgress {
                 print(result.consoleOutput(verbosity: verbosity))
@@ -67,13 +67,12 @@ public actor Engine {
         return hostResults
     }
 
-    /// Directly runs a single command against a single host.
+    /// Directly runs a single command against a single host, applying the retry and timeout policies of the command.
     /// - Parameters:
-    ///   - command: The command to run.
     ///   - host: The host on which to run the command.
-    ///   - playbookId: The ID of the playbook the command is part of.
+    ///   - command: The command to run.
     /// - Returns: The result of the command execution.
-    public nonisolated func run(command: (any Command), host: Host) async throws
+    public nonisolated func run(host: Host, command: (any Command)) async throws
         -> CommandExecutionResult
     {
         // `nonisolated` + `async` means run on a cooperative thread pool and return the result

Sources/Formic/ResourceTypes/Dpkg.swift

@@ -113,6 +113,8 @@ public struct Dpkg: Sendable, Hashable, Resource {
         /// - Parameters:
         ///   - name: The name of the package.
         ///   - state: The desired state of the package.
+        ///   - retry: The retry settings for resolving the resource.
+        ///   - resolveTimeout: The execution timeout to allow the resource to resolve.
         public init(
             name: String, state: DesiredPackageState, retry: Backoff = .never, resolveTimeout: Duration = .seconds(60)
         ) {

Tests/formicTests/EngineTests.swift

@@ -18,7 +18,7 @@ func testEngineRun() async throws {
         dependencyValues.commandInvoker = TestCommandInvoker()
             .addSuccess(command: ["uname"], presentOutput: "Darwin\n")
     } operation: {
-        try await engine.run(command: cmd, host: .localhost)
+        try await engine.run(host: .localhost, command: cmd)
     }
 
     #expect(cmdExecOut.command.id == cmd.id)
@@ -172,7 +172,7 @@ func testCommandTimeout() async throws {
                 dependencyValues.localSystemAccess = TestFileSystemAccess()
                 dependencyValues.commandInvoker = mockCmdInvoker
             } operation: {
-                return try await engine.run(command: cmd1, host: fakeHost)
+                return try await engine.run(host: fakeHost, command: cmd1)
             }
         })
 }
@@ -197,7 +197,7 @@ func testCommandRetry() async throws {
         dependencyValues.localSystemAccess = TestFileSystemAccess()
         dependencyValues.commandInvoker = mockCmdInvoker
     } operation: {
-        return try await engine.run(command: cmd1, host: fakeHost)
+        return try await engine.run(host: fakeHost, command: cmd1)
     }
 
     #expect(result.command.id == cmd1.id)