Merge remote-tracking branch 'repoconf-rust-public-lib-template/main'

# Conflicts:
#	AGENTS.md
#	Cargo.lock
#	README.md
#	README.ts
#	src/lib.rs

Author: DenisGorbachev

.agents/cli-for-type.md

@@ -0,0 +1,243 @@
+# Concepts for CLI-for-type
+
+## Target type
+
+The type whose methods are exposed through a CLI and invoked by child commands.
+
+Examples:
+
+- Rust example.
+  - ```rust
+    //! In this example, all types are in the same file. In real code, the types must be in their own files according to project guidelines.
+
+    use std::io::stdout;
+    use clap::{Parser, Subcommand};
+    use derive_new::new;
+    use errgonomic::handle;
+    use secrecy::SecretString;
+    use subtype::{subtype, subtype_string, subtype_u64};
+    use thiserror::Error;
+
+    use FooSubcommand::*;
+
+    subtype! {
+        #[derive(Clone, Debug)]
+        pub struct FooApiKey(SecretString)
+    }
+
+    impl core::str::FromStr for FooApiKey {
+        type Err = core::convert::Infallible;
+
+        fn from_str(s: &str) -> Result<Self, Self::Err> {
+            Ok(FooApiKey::new(SecretString::from(s.to_owned())))
+        }
+    }
+
+    subtype_u64! {
+        pub struct UserId(u64)
+    }
+
+    impl core::str::FromStr for UserId {
+        type Err = core::num::ParseIntError;
+
+        fn from_str(s: &str) -> Result<Self, Self::Err> {
+            s.parse::<u64>().map(Self::new)
+        }
+    }
+
+    subtype_u64! {
+        pub struct UsersPage(u64)
+    }
+
+    impl core::str::FromStr for UsersPage {
+        type Err = core::num::ParseIntError;
+
+        fn from_str(s: &str) -> Result<Self, Self::Err> {
+            s.parse::<u64>().map(Self::new)
+        }
+    }
+
+    subtype_string! {
+        pub struct UserName(String)
+    }
+
+    impl core::str::FromStr for UserName {
+        type Err = core::convert::Infallible;
+
+        fn from_str(s: &str) -> Result<Self, Self::Err> {
+            Ok(Self::new(s))
+        }
+    }
+
+    #[derive(Clone, Debug)]
+    pub struct User {
+        pub id: UserId,
+        pub name: UserName,
+    }
+
+    #[derive(new)]
+    pub struct FooClient {
+        api_key: FooApiKey,
+    }
+
+    impl FooClient {
+        pub fn users(&self, _page: UsersPage) -> Result<Vec<User>, FooClientUsersError> {
+            use FooClientUsersError::*;
+            let _ = NotImplemented {};
+            todo!()
+        }
+
+        pub fn set_user_name(&self, _id: UserId, _name: &UserName) -> Result<(), FooClientSetUserNameError> {
+            use FooClientSetUserNameError::*;
+            let _ = NotImplemented {};
+            todo!()
+        }
+    }
+
+
+    #[derive(Error, Debug)]
+    pub enum FooClientUsersError {
+        #[error("foo client users operation is not implemented")]
+        NotImplemented {},
+    }
+
+    #[derive(Error, Debug)]
+    pub enum FooClientSetUserNameError {
+        #[error("foo client set user name operation is not implemented")]
+        NotImplemented {},
+    }
+
+    #[derive(Parser, Debug)]
+    #[command(author, version, about, propagate_version = true)]
+    pub struct FooCommand {
+        #[arg(long, env = "FOO_API_KEY")]
+        api_key: FooApiKey,
+
+        #[command(subcommand)]
+        subcommand: FooSubcommand,
+    }
+
+    #[derive(Subcommand, Clone, Debug)]
+    pub enum FooSubcommand {
+        Users(FooUsersCommand),
+        SetUserName(FooSetUserNameCommand),
+    }
+
+    impl FooCommand {
+        pub async fn run(self) -> Result<(), FooCommandRunError> {
+            use FooCommandRunError::*;
+            let Self {
+                api_key,
+                subcommand,
+            } = self;
+            let client = FooClient::new(api_key);
+            match subcommand {
+                Users(command) => map_err!(command.run(&client).await, UsersCommandRunFailed),
+                SetUserName(command) => map_err!(command.run(&client).await, SetUserNameCommandRunFailed),
+            }
+        }
+    }
+
+    #[derive(Error, Debug)]
+    pub enum FooCommandRunError {
+        #[error("failed to run users command")]
+        UsersCommandRunFailed { source: FooUsersCommandRunError },
+    
+        #[error("failed to run set user name command")]
+        SetUserNameCommandRunFailed { source: FooSetUserNameCommandRunError },
+    }
+
+    #[derive(Parser, Debug)]
+    pub struct FooUsersCommand {
+        #[arg(long)]
+        page: UsersPage,
+    }
+
+    impl FooUsersCommand {
+        pub async fn run(self, client: &FooClient) -> Result<(), FooUsersCommandRunError> {
+            use FooUsersCommandRunError::*;
+            let Self {
+                page,
+            } = self;
+            let mut stdout = stdout();
+            let users = handle!(client.users(page), UsersFailed, page);
+            handle!(serde_json::to_writer_pretty(&mut stdout, &users), ToWriterPrettyFailed, users);
+            Ok(())
+        }
+    }
+
+    #[derive(Error, Debug)]
+    pub enum FooUsersCommandRunError {
+        #[error("failed to fetch users for page '{page}'")]
+        UsersFailed { source: FooClientUsersError, page: UsersPage },
+        #[error("failed to write users to stdout")]
+        ToWriterPrettyFailed { source: serde_json::Error, users: Vec<User> },
+    }
+
+    #[derive(Parser, Debug)]
+    pub struct FooSetUserNameCommand {
+        #[arg(long)]
+        user_id: UserId,
+
+        #[arg(long)]
+        name: UserName,
+    }
+
+    impl FooSetUserNameCommand {
+        pub async fn run(self, client: &FooClient) -> Result<Vec<User>, FooSetUserNameCommandRunError> {
+            use FooSetUserNameCommandRunError::*;
+            let Self {
+                user_id,
+                name,
+            } = self;
+            handle!(client.set_user_name(user_id, &name), SetUserNameFailed, user_id, name);
+            Ok(())
+        }
+    }
+
+    #[derive(Error, Debug)]
+    pub enum FooSetUserNameCommandRunError {
+        #[error("failed to set user name '{name}' for user '{user_id}'")]
+        SetUserNameFailed { source: FooClientSetUserNameError, user_id: UserId, name: UserName },
+    }
+    ```
+
+Requirements:
+
+- Must be constructible by the parent command.
+- Must expose at least one public method that can be invoked by a child command.
+
+Notes:
+
+- The target type should not parse CLI arguments itself.
+
+## Parent command
+
+The command that constructs the target type and delegates execution to the selected child command.
+
+Requirements:
+
+- Must have fields for all inputs needed to construct the target type.
+- Must construct an instance of the target type.
+- Must pass the constructed instance of the target type to the selected child command.
+
+Notes:
+
+- The parent command isolates CLI parsing from domain logic.
+
+## Child command
+
+A subcommand that wraps one target-type method and maps CLI arguments to that method.
+
+Requirements:
+
+- Must have a field for each argument of the wrapped method.
+- Must call the wrapped method in its run implementation.
+- Must return an error type that wraps the method error and the relevant argument values.
+- Must write the results to stdout in an efficient way:
+  - Must serialize the results using `serde_json`
+  - Must use `serde_json::to_writer_pretty`
+
+Notes:
+
+- Child commands should not construct the target type themselves.

.agents/cli.md

@@ -0,0 +1,128 @@
+# CLI guidelines
+
+## Dependencies
+
+- `clap` (features: at least "derive", "env")
+- `tokio` (features: at least "macros", "rt", "rt-multi-thread")
+- `errgonomic`
+- `thiserror`
+
+## File layout and required items
+
+### File `src/main.rs`
+
+- Must define a `main` entrypoint
+- Must define a `verify_cli` test for the top-level command exactly as in the example below (with `debug_assert`)
+
+Example:
+
+```rust
+use clap::Parser;
+use errgonomic::exit_result;
+use my_crate_name::Command;
+use std::process::ExitCode;
+
+#[tokio::main]
+async fn main() -> ExitCode {
+    let args = Command::parse();
+    let result = args.run().await;
+    exit_result(result)
+}
+
+#[test]
+fn verify_cli() {
+    use clap::CommandFactory;
+    Command::command().debug_assert();
+}
+```
+
+### File `src/command.rs`
+
+- Must define a [command-like struct](#command-like-struct) named `Command`
+- Must define a [subcommand-like enum](#subcommand-like-enum) named `Subcommand`
+
+Example:
+
+```rust
+use std::process::ExitCode;
+use Subcommand::*;
+use errgonomic::map_err;
+use thiserror::Error;
+
+#[derive(clap::Parser, Debug)]
+#[command(author, version, about, propagate_version = true)]
+pub struct Command {
+    #[command(subcommand)]
+    subcommand: Subcommand,
+}
+
+#[derive(clap::Subcommand, Clone, Debug)]
+pub enum Subcommand {
+    Print(PrintCommand),
+}
+
+impl Command {
+    pub async fn run(self) -> Result<ExitCode, CommandRunError> {
+        use CommandRunError::*;
+        let Self {
+            subcommand,
+        } = self;
+        match subcommand {
+            Print(command) => map_err!(command.run().await, PrintCommandRunFailed),
+        }
+    }
+}
+
+#[derive(Error, Debug)]
+pub enum CommandRunError {
+    #[error("failed to run print command")]
+    PrintCommandRunFailed { source: PrintCommandRunError },
+}
+
+mod print_command;
+
+pub use print_command::*;
+```
+
+## Definitions
+
+### Command-like struct
+
+A struct that contains fields for CLI arguments.
+
+- Must have a name that is a concatenation of all command names leading up to and including this command name, and ends with `Command` (see example above)
+- Must derive `clap::Parser`
+- Must be attached to a parent module: if it's a top-level command: `src/lib.rs`, else: `src/command.rs`
+- May contain a `subcommand` field annotated with `#[command(subcommand)]`
+- Must have a `pub async fn run`
+  - Must return a `Result` with `ExitCode`
+  - If it contains a `subcommand` field: must match on `subcommand` and call `run` of each command
+
+Command example:
+
+- Name: `DbDownloadYcombinatorStartupsCommand`
+- File: `src/command/db_download_ycombinator_startups_command.rs` (attached to `src/command.rs`)
+- Shell command: `cargo run -- db download ycombinator-startups`
+
+### Subcommand-like enum
+
+An enum that contains variants for CLI subcommands.
+
+- Must have a name that is a concatenation of all command names leading up to and including this command name, and ends with `Subcommand` (see example above)
+- Must derive `clap::Subcommand`
+- Must be located in the same file as its parent command struct
+- Each variant must be a tuple variant containing exactly one command
+
+Subcommand example:
+
+- Name: `DbDownloadSubcommand`
+- File: `src/cli/db_command/db_download_command.rs` (same file as its parent `DbDownloadCommand`)
+
+### Proxy command-like struct
+
+A [command-like struct](#command-like-struct) that has a `subcommand` field and calls `run` on each subcommand.
+
+Proxy command example:
+
+- Name: `DbCommand`
+- File: `src/command/db_command.rs` (attached to `src/command.rs`)