Skip to content

Commit

Permalink
hc CLI documentation fixes and updates (holochain#2100)
Browse files Browse the repository at this point in the history 
* update documentation for `hc` and subcommands

Fixed inconsistencies/outdated information, punctuation.
Added more information to explain certain commands and arguments.

* READMEs
* Code comments incl Rustdoc
* Outputted help text
* Error messages

* update CHANGELOGs

* further edits to help text on hc bundle  flag

* fix small spelling mistake

* update source 'rust-overlay' on branch 'develop' (holochain#2103)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* fixes for the release workflow (holochain#2095)

* fix(github/release): changed variables

* fix(github/release): string substitution for gh cmd

* chore: re-enable the weekly release schedule (holochain#2104)

* refactor(zome-call): optimize cap grant verification (holochain#2097)

* refactor(zome-call): cap grant verification

* refactor: simplify cap grant validation flow

* update changelog

* simplify assigned cap access arm

* add PR reference to changelog

* add comment to test

* Apply suggestions from code review

Co-authored-by: Michael Dougherty <[email protected]>

* refactor: use high level db query fn

* replace hardcoded cap access variant by method

---------

Co-authored-by: Michael Dougherty <[email protected]>

* further punctuation/spacing/formatting edits to hc

* 2023 03 17 switch to clap (holochain#2125)

* upgrade from structopt to clap 3.0

* update from structopt 0.3 to clap 3.0

* resolve deprecated warnings for clap 3 upgrade

* hc binary: upgrade to clap 4.0

* update changelog for hc scaffold

* updated a couple more changelogs

* fix error with hc s call

* hc cli: move runner impl to subcommand enum

* update source 'nixpkgs' on branch 'develop' (holochain#2158)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* update source 'rust-overlay' on branch 'develop' (holochain#2159)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* fix(release-automation): consider dependency state of all matched crates (holochain#2160)

fix(release-automation): consider dependency state of all matched crates (holochain#2149)

* fix(release-automation): consider dependency state of all matched crates

the change filter could lead to dependency changes not
including the changed dependency in the release, if the selected crate
itself didn't have any changed.

the blocked filter was removed because it adds unnecessary obfuscation.

* chore(release-automation): remove duplicate test

* test(relase-automation): cover the fixed case

* chore: add FIXME comment for a bug in the dependencies_in_workspace_filter function

* test(release-automation): extend dependency bump test to cover the transitive case

* refactor(release-automation/crate_selection): clarify transitive change detection

* update source 'nixpkgs' on branch 'develop' (holochain#2161)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* Improve HoloHash::from_raw_32 and use it (holochain#2162)

* Update from_raw_32 to only allow 32

* Use 32 byte hash for a test where it matters

* Fix fixturator

* Fix one more test

* hc: code reorganisation, make clap types more consistent

* update source 'rust-overlay' on branch 'develop' (holochain#2163)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* update source 'rust-overlay' on branch 'develop' (holochain#2164)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* update source 'rust-overlay' on branch 'develop' (holochain#2165)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* fix(github/release*): merge release into target branch before pushing (holochain#2151)

* update source 'nixpkgs' on branch 'develop' (holochain#2169)

[create-pull-request] automated change

Co-authored-by: steveeJ <[email protected]>

* hc: re-add support for --version

* hc: fix hc sandbox list

* revert some overly eager search/replace

* bump deps

* clean up whitespace in hc codebase

* fix fmt and clippy issues in hc

---------

Co-authored-by: Holochain Release Automation <[email protected]>
Co-authored-by: steveeJ <[email protected]>
Co-authored-by: Stefan Junker <[email protected]>
Co-authored-by: Michael Dougherty <[email protected]>

* fix wonky merge on Cargo.lock and one source file

* update hc signal-src and hc dna bundle --dylib ios to clap 4

* improve top-level hc README

* final polish on hc help text/readme improvements

* update changelogs for hc doc changes

* fix some uncaught merge problems

---------

Co-authored-by: Holochain Release Automation <[email protected]>
Co-authored-by: steveeJ <[email protected]>
Co-authored-by: Stefan Junker <[email protected]>
Co-authored-by: Jost Schulte <[email protected]>
Co-authored-by: Michael Dougherty <[email protected]>
  • Loading branch information
@pdaoust @holochain-release-automation2
@steveej @jost-s @maackle
6 people authored May 11, 2023
1 parent afb8bf5 commit c249335
Show file tree
Hide file tree
Showing 36 changed files with 708 additions and 597 deletions.
10 changes: 6 additions & 4 deletions Cargo.lock
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions crates/hc/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## Unreleased

- Improved documentation in README, code comments, help text, and error messages.
- Updated from structopt 0.3 to clap 4. [#2125](https://github.com/holochain/holochain/pull/2125)
- `hc signal-srv` is now `hc run-local-services` and runs both a webrtc signaling server, and the holochain bootstrap server locally. [\#2353](https://github.com/holochain/holochain/pull/2353)

## 0.2.0
Expand Down
3 changes: 2 additions & 1 deletion crates/hc/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,11 @@ path = "src/lib.rs"

[dependencies]
anyhow = "1.0"
clap = { version = "4.0", features = [ "derive", "cargo" ] }
futures = "0.3"
lazy_static = "1.4"
holochain_cli_bundle = { path = "../hc_bundle", version = "^0.2.0"}
holochain_cli_sandbox = { path = "../hc_sandbox", version = "^0.2.0"}
holochain_cli_run_local_services = { path = "../hc_run_local_services", version = "^0.2.0"}
holochain_trace = { version = "^0.2.0", path = "../holochain_trace" }
structopt = "0.3"
tokio = { version = "1.27", features = ["full"] }
40 changes: 13 additions & 27 deletions crates/hc/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,44 +2,30 @@

Provides the `hc` binary, a helpful CLI tool for working with Holochain.

```shell
$ hc -h

holochain_cli 0.1.0
Holochain CLI

Work with DNA and hApp bundle files, set up sandbox environments for testing and development purposes, make direct admin
calls to running conductors, and more.
## Docs

USAGE:
hc <SUBCOMMAND>
This command gives you a suite of tools for developing, inspecting, executing, and testing your Holochain apps. Some top-level subcommands are implemented as separate crates, and others are separate binaries -- commands whose names start with `hc-` and are automatically made available as subcommands if they exist in your shell's path. Here is a list of all available subcommands:

FLAGS:
-h, --help Prints help information
-V, --version Prints version information
- `hc dna`, `hc app`, and `hc web-app` scaffold, bundle, and unbundle DNAs, hApps and web hApps respectively. See [holochain_cli_bundle](https://github.com/holochain/holochain/tree/develop/crates/hc_bundle) for more info.
- `hc sandbox` creates and executes temporary or persistent conductor configurations for you to run test instances of your hApp with. See [holochain_cli_sandbox](https://github.com/holochain/holochain/tree/develop/crates/hc_sandbox) for more info.
- `hc signal-srv` runs a local WebRTC signal server for peers to establish connections with each other. See [holochain_cli_signal_srv](https://github.com/holochain/holochain/tree/develop/crates/hc_signal_srv) for more info.
- `hc scaffold` generates integrity, coordinator, UI, and test code for hApps using interactive prompts. See [holochain/scaffolding](https://github.com/holochain/scaffolding).
- `hc launch` runs sandboxed hApp instances with live-reloading UI windows. See [hc_launch in holochain/launcher](https://github.com/holochain/launcher/tree/main/crates/hc_launch) for more info.

SUBCOMMANDS:
app Work with hApp bundles
dna Work with DNA bundles
help Prints this message or the help of the given subcommand(s)
sandbox Work with sandboxed environments for testing and development
```

## Docs
## Installation

Each top-level subcommand is implemented as a separate crate. See:
### Quick install

- [holochain_cli_bundle](https://github.com/holochain/holochain/tree/develop/crates/hc_bundle) for more info on the `hc app` and `hc dna` commands
- [holochain_cli_sandbox](https://github.com/holochain/holochain/tree/develop/crates/hc_sandbox) for more info on the `hc sandbox` command
Follow the [quick start guide](https://developer.holochain.org/quick-start/) on the Holochain Developer Portal to get set up with all the Holochain development tools, including the `hc` CLI and official extensions.

## Installation
### Build from source

### Requirements
#### Requirements

- [Rust](https://rustup.rs/)
- [Holochain](https://github.com/holochain/holochain) binary on the path

### Building
#### Building

From github:

Expand Down
6 changes: 3 additions & 3 deletions crates/hc/src/bin/hc.rs
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
use clap::Parser;
use holochain_cli as hc;
use structopt::StructOpt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
if std::env::var_os("RUST_LOG").is_some() {
holochain_trace::init_fmt(holochain_trace::Output::Log).ok();
}
let opt = hc::Opt::from_args();
opt.run().await
let cli = hc::Cli::parse();
cli.subcommand.run().await
}
2 changes: 1 addition & 1 deletion crates/hc/src/external_subcommands.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ use std::{

use crate::builtin_commands;

/// List all runnable commands
/// List all runnable commands.
pub fn list_external_subcommands() -> Vec<String> {
let prefix = "hc-";
let suffix = env::consts::EXE_SUFFIX;
Expand Down
165 changes: 45 additions & 120 deletions crates/hc/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,136 +1,53 @@
#![warn(missing_docs)]

//! A library and CLI to help create, run and interact with holochain conductor setups.
//! A library and CLI to help create, run, and interact with Holochain conductor setups.
//! **Warning this is still WIP and subject to change**
//! There's probably a few bugs. If you find one please open an [issue](https://github.com/holochain/holochain/issues)
//! or make a PR.
//!
//! ## CLI
//! The `hc` CLI makes it easy to run a dna that you are working on
//! or someone has sent you.
//!
//! The `hc` CLI makes it easy to create, modify, and run hApps that
//! you are working on or someone has sent you.
//! It has been designed to use sensible defaults but still give you
//! the configurability when that's required.
//!
//! Setups are stored in tmp directories by default and the paths are
//! persisted in a `.hc` file which is created wherever you are using
//! the CLI.
//! ### Install
//! #### Requirements
//! - [Rust](https://rustup.rs/)
//! - [Holochain](https://github.com/holochain/holochain) binary on the path
//! #### Building
//! From github:
//! ```shell
//! cargo install holochain_cli --git https://github.com/holochain/holochain
//! ```
//! From the holochain repo:
//! ```shell
//! cargo install --path crates/hc
//! ```
//! ### Common usage
//! The best place to start is:
//! ```shell
//! hc -h
//! ```
//! This will be more up to date then this readme.
//! #### Run
//! This command can be used to generate and run conductor setups.
//! ```shell
//! hc run -h
//! # or shorter
//! hc r -h
//! ```
//! In a folder with where your `my-dna.dna` is you can generate and run
//! a new setup with:
//! ```shell
//! hc r
//! ```
//! If you have already created a setup previously then it will be reused
//! (usually cleared on reboots).
//! #### Generate
//! Generates new conductor setups and installs apps / dnas.
//! ```shell
//! hc generate
//! # or shorter
//! hc g
//! ```
//! For example this will generate 5 setups with app ids set to `my-app`
//! using the `elemental-chat.dna` from the current directory with a quic
//! network setup to localhost.
//! _You don't need to specify dnas when they are in the directory._
//! ```shell
//! hc gen -a "my-app" -n 5 ./elemental-chat.dna network quic
//! ```
//! You can also generate and run in the same command:
//! (Notice the number of conductors and dna path must come before the gen sub-command).
//! ```shell
//! hc r -n 5 ./elemental-chat.dna gen -a "my-app" network quic
//! ```
//! #### Call
//! Allows calling the [`AdminRequest`](https://docs.rs/holochain_conductor_api/latest/holochain_conductor_api/enum.AdminRequest.html) api.
//! If the conductors are not already running they
//! will be run to make the call.
//!
//! ```shell
//! hc call list-cells
//! ```
//! #### List and Clean
//! These commands allow you to list the persisted setups
//! in the current directory (from the`.hc`) file.
//! You can use the index from:
//! ```shell
//! hc list
//! ```
//! Output:
//! ```shell
//! hc-sandbox:
//! Setups contained in `.hc`
//! 0: /tmp/KOXgKVLBVvoxe8iKD4iSS
//! 1: /tmp/m8VHwwt93Uh-nF-vr6nf6
//! 2: /tmp/t6adQomMLI5risj8K2Tsd
//! ```
//! To then call or run an individual setup (or subset):
//!
//! ```shell
//! hc r -i=0,2
//! ```
//! You can clean up these setups with:
//! ```shell
//! hc clean 0 2
//! # Or clean all
//! hc clean
//! ```
//! ## Library
//! This crate can also be used as a library so you can create more
//! complex setups / admin calls.
//! See the docs:
//! ```shell
//! cargo doc --open
//! ```
//! and the examples.

use std::process::Command;

// Useful to have this public when using this as a library.
use clap::{crate_version, Parser, Subcommand};
pub use holochain_cli_bundle as hc_bundle;
use holochain_cli_run_local_services as hc_run_local_services;
use holochain_cli_sandbox as hc_sandbox;
use structopt::{lazy_static::lazy_static, StructOpt};
use lazy_static::lazy_static;

mod external_subcommands;

// TODO: change this so it inherits clap's formatting.
// Clap 3 and 4 format helptext using colours and bold/underline respectively.
// https://github.com/clap-rs/clap/pull/4765 introduces the ability to style your own help text
// using a library like `color_print`.
// https://github.com/clap-rs/clap/issues/4786 requests that the styler's built-in helper methods
// be exposed to consumers, thereby allowing us to durably make our styling consistent
// with whatever clap's happens to be at the moment.
// I'd prefer the latter approach, if it lands.
lazy_static! {
static ref HELP: &'static str = {
let extensions = external_subcommands::list_external_subcommands()
.into_iter()
.map(|s| format!(" hc {}\t Run \"hc {} help\" to see its help", s, s))
.map(|s| format!(" {}\t Run \"hc {} help\" to see its help", s, s))
.collect::<Vec<String>>()
.join("\n");

let extensions_str = match extensions.len() {
0 => String::from(""),
_ => format!(
r#"
EXTENSIONS:
Extensions:
{extensions}"#
),
};
Expand All @@ -152,37 +69,45 @@ fn builtin_commands() -> Vec<String> {
.collect()
}

/// Describes all the possible CLI arguments for `hc`, including external subcommands like `hc-scaffold`
/// The main entry-point for the command.
#[allow(clippy::large_enum_variant)]
#[derive(Debug, StructOpt)]
#[structopt(setting = structopt::clap::AppSettings::InferSubcommands)]
#[structopt(long_about = *HELP)]
pub enum Opt {
/// Work with DNA bundles
#[derive(Debug, Parser)]
#[command(about = *HELP, infer_subcommands = true, allow_external_subcommands = true, version = crate_version!())]
pub struct Cli {
/// The `hc` subcommand to run.
#[command(subcommand)]
pub subcommand: CliSubcommand,
}

/// Describes all the possible CLI arguments for `hc`, including external subcommands like `hc-scaffold`.
#[derive(Debug, Subcommand)]
#[warn(clippy::large_enum_variant)]
pub enum CliSubcommand {
/// Work with DNA bundles.
Dna(hc_bundle::HcDnaBundle),
/// Work with hApp bundles
/// Work with hApp bundles.
App(hc_bundle::HcAppBundle),
/// Work with Web-hApp bundles
/// Work with web-hApp bundles.
WebApp(hc_bundle::HcWebAppBundle),
/// Work with sandboxed environments for testing and development
/// Work with sandboxed environments for testing and development.
Sandbox(hc_sandbox::HcSandbox),
/// Run local services
/// Run a local bootstrap and WebRTC signalling server.
RunLocalServices(hc_run_local_services::HcRunLocalServices),
/// Allow redirect of external subcommands (like hc-scaffold and hc-launch)
#[structopt(external_subcommand)]
/// Allow redirect of external subcommands (like `hc-scaffold` and `hc-launch`).
#[command(external_subcommand)]
External(Vec<String>),
}

impl Opt {
/// Run this command
impl CliSubcommand {
/// Run this command.
pub async fn run(self) -> anyhow::Result<()> {
match self {
Self::Dna(cmd) => cmd.run().await?,
Self::App(cmd) => cmd.run().await?,
Self::WebApp(cmd) => cmd.run().await?,
Self::Sandbox(cmd) => cmd.run().await?,
Self::RunLocalServices(cmd) => cmd.run().await,
Self::External(args) => {
CliSubcommand::App(cmd) => cmd.run().await?,
CliSubcommand::Dna(cmd) => cmd.run().await?,
CliSubcommand::WebApp(cmd) => cmd.run().await?,
CliSubcommand::Sandbox(cmd) => cmd.run().await?,
CliSubcommand::RunLocalServices(cmd) => cmd.run().await,
CliSubcommand::External(args) => {
let command_suffix = args.first().expect("Missing subcommand name");
Command::new(format!("hc-{}", command_suffix))
.args(&args[1..])
Expand Down
Loading

0 comments on commit c249335

Please sign in to comment.