docs: refactor readme + guidelines

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,49 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/issue-templates/forms/platform-dependent/bug-report.yml
+# See: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
+
+name: Bug report
+description: Report a problem with the code or documentation in this repository.
+labels:
+  - "type: imperfection"
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the problem
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: To reproduce
+      description: Provide the specific set of steps we can follow to reproduce the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What would you expect to happen after following those instructions?
+    validations:
+      required: true
+  - type: input
+    id: project-version
+    attributes:
+      label: Arduino App CLI version
+      description: |
+        Which version of Arduino App CLI are you using? (output of `arduino-app-cli version`)
+        _This should be the most recent version available._
+    validations:
+      required: true
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Issue checklist
+      description: Please double-check that you have done each of the following things before submitting the issue.
+      options:
+        - label: I searched for previous reports in [the issue tracker](https://github.com/arduino/arduino-app-cli/issues?q=)
+          required: true
+        - label: I verified the problem still occurs when using the latest version
+          required: true
+        - label: My report contains all necessary details
+          required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,44 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/issue-templates/forms/platform-dependent/bug-report.yml
+# See: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
+
+name: Feature request
+description: Suggest an enhancement to this project.
+labels:
+  - "type: enhancement"
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the request
+    validations:
+      required: true
+  - type: textarea
+    id: current
+    attributes:
+      label: Describe the current behavior
+      description: |
+        What is the current behavior of Arduino App CLI in relation to your request? (output of `arduino-app-cli version`)
+        How can we reproduce that behavior?
+    validations:
+      required: true
+  - type: input
+    id: project-version
+    attributes:
+      label: Arduino App CLI version
+      description: |
+        Which version of Arduino App CLI are you using? (output of `arduino-app-cli version`)
+        _This should be the most recent version available._
+    validations:
+      required: true
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Issue checklist
+      description: Please double-check that you have done each of the following things before submitting the issue.
+      options:
+        - label: I searched for previous requests in [the issue tracker](https://github.com/arduino/arduino-app-cli/issues?q=)
+          required: true
+        - label: I verified the feature was still missing when using the latest version
+          required: true
+        - label: My request contains all necessary details
+          required: true

README.md

@@ -1,64 +1,43 @@
 # Arduino App CLI
 
-`arduino-app-cli` is a command line tool and a service running on Arduino UNO Q boards, that:
+`arduino-app-cli` is a command line tool running on the [Arduino UNO Q](https://docs.arduino.cc/hardware/uno-q/) boards, that manages and runs Arduino Apps (both Linux and microcontroller parts), provides a HTTP daemon mode to expose RestFul APIs, and auto-updates itself and other components.
 
-- manages and runs Arduino Apps on the board (both Linux and microcontroller parts)
-- provides multiple APIs to perform actions and fetch data, used by the front-end (ArduinoAppsLab)
-- auto-updates itself and other components
+[![Test Go status](https://github.com/arduino/arduino-app-cli/actions/workflows/go-test.yml/badge.svg)](https://github.com/arduino/arduino-app-cli/actions/workflows/go-test.yml)
 
-## Environment Variables
+## Docs
 
-The following environment variables are used to configure `arduino-app-cli`:
+For guidance on installation and development, see the [User documentation].
 
-### Application Directories
+## Quickstart
 
-- **`ARDUINO_APP_CLI__APPS_DIR`** Path to the directory where Arduino Apps created by the user are stored.\
-  **Default:** `/home/arduino/ArduinoApps`
+// TODO
 
-- **`ARDUINO_APP_CLI__DATA_DIR`** Path to the directory where internal data is stored.\
-  **Default:** `/home/arduino/.local/share/arduino-app-cli`\
-  This folder contains:
-  - **`examples/`** default example Apps (_e.g._ `/home/arduino/.local/share/arduino-app-cli/examples`)
-  - **`assets/`** contains a subfolder for each asset version (_e.g._ `/home/arduino/.local/share/arduino-app-cli/assets/0.4.5`)
-    - Each asset folder includes:
-      - `bricks-list.yaml`
-      - `models-list.yaml`
-  - **other data** such as `properties.msgpack` containing variable values
+## How to contribute
 
-- **`ARDUINO_APP_BRICKS__CUSTOM_MODEL_DIR`** Path to the directory where custom models are stored.\
-  **Default:** `$HOME/.arduino-bricks/ei-models`\
-  (_e.g._ `/home/arduino/.arduino-bricks/ei-models`)
+Contributions are welcome!
 
----
+Please read the [Contributor Guide] document, which will show you how to build the source code, run the tests, and
+contribute your changes to the project.
 
-### Execution Settings
+:sparkles: Thanks to all our [contributors]! :sparkles:
 
-- **`ARDUINO_APP_CLI__ALLOW_ROOT`** Allow running `arduino-app-cli` as root.\
-  **Default:** `false` **Not recommended to set to true.**
+## Security
 
----
+If you think you found a vulnerability or other security-related bug in the Arduino CLI, please read our [security
+policy] and report the bug to our Security Team 🛡️ Thank you!
 
-### External Services
+e-mail contact: security@arduino.cc
 
-- **`LIBRARIES_API_URL`** URL of the external service used to search libraries.\
-  **Default:** `https://api2.arduino.cc/libraries/v1/libraries`
+## License
 
----
+Arduino App CLI is licensed under the GPL-3.0 license.
 
-### Docker Settings
+You can be released from the requirements of the above license by purchasing a commercial license. Buying such a license
+is mandatory if you want to modify or otherwise use the software for commercial activities involving the Arduino
+software without disclosing the source code of your own applications. To purchase a commercial license, send an email to
+license@arduino.cc
 
-- **`DOCKER_REGISTRY_BASE`** Docker registry used to pull images.\
-  **Default:** `ghcr.io/arduino/`
-
-- **`DOCKER_PYTHON_BASE_IMAGE`** Tag of the Docker image for the Python runner.\
-  **Default:** `app-bricks/python-apps-base:<RUNNER_VERSION>`
-
-### App folder and persistent data
-
-When running an app, persistent files will be saved in the `data` folder inside the app folder; other supporting files, including the Python venv are saved in the `.cache` folder inside the app folder.
-
-### Docker images registry
-
-Arduino Apps bricks might required a docker image, in that case the orchestrator will pull those from the registry configured with the `DOCKER_REGISTRY_BASE` environment variable. By default this points to an Arduino GitHub Container Registry (ghcr.io/arduino).
-
-The only image that needs to be referenced directly is the base Python image (`DOCKER_PYTHON_BASE_IMAGE`), all other containers can be downloaded automatically by the orchestrator depending on the bricks specified as dependencies in the app.yml file.
+[user documentation]: https://github.com/arduino/arduino-app-cli/docs/user-documentation.md
+[contributor guide]: https://arduino.github.io/arduino-app-cli/latest/CONTRIBUTING/
+[security policy]: https://github.com/arduino/arduino-app-cli/security/policy
+[contributors]: https://github.com/arduino/arduino-cli/graphs/contributors

Taskfile.yml

@@ -123,11 +123,17 @@ tasks:
           echo "Examples successfully cloned."
     silent: false
 
-  arduino-app-cli:build:local:
+  build:
     desc: "Build the arduino-app-cli locally"
     cmds:
       - go build -v -o ./build/arduino-app-cli ./cmd/arduino-app-cli
 
+  start:
+    desc: "build and launch the arduino-app-cli in daemon mode"
+    cmds:
+      - task build
+      - ./build/arduino-app-cli daemon  --port 8800
+
   arduino-app-cli:release:
     desc: Create a tag on the current commit and push it to the remote to create the release
     cmds:
@@ -139,12 +145,6 @@ tasks:
       - git tag -a "{{.CLI_ARGS}}" -m "Release {{.CLI_ARGS}}"
       - git push origin "{{.CLI_ARGS}}"
 
-  arduino-app-cli:start:
-    desc: "build and launch the arduino-app-cli in daemon mode"
-    cmds:
-      - task arduino-app-cli:build:local
-      - ./build/arduino-app-cli daemon  --port 6060
-
   # To to forward a port, using ssh, you can use this command:
   # ssh -L 8800:localhost:8800 arduino@<BOARD_IP>
   arduino-app-cli:pprof:

cmd/arduino-app-cli/config/config.go

@@ -29,7 +29,7 @@ import (
 func NewConfigCmd(cfg config.Configuration) *cobra.Command {
 	appCmd := &cobra.Command{
 		Use:   "config",
-		Short: "Manage arduino-app-cli config",
+		Short: "Manage Arduino App CLI config",
 	}
 
 	appCmd.AddCommand(newConfigGetCmd(cfg))

cmd/arduino-app-cli/daemon/daemon.go

@@ -38,7 +38,7 @@ import (
 func NewDaemonCmd(cfg config.Configuration, version string) *cobra.Command {
 	daemonCmd := &cobra.Command{
 		Use:   "daemon",
-		Short: "Run an HTTP server to expose arduino-app-cli functionality through REST API",
+		Short: "Run the Arduino App CLI as an HTTP daemon",
 		Run: func(cmd *cobra.Command, args []string) {
 			daemonPort, _ := cmd.Flags().GetString("port")
 

cmd/arduino-app-cli/main.go

@@ -48,7 +48,7 @@ func run(configuration cfg.Configuration) error {
 	defer func() { _ = servicelocator.CloseDockerClient() }()
 	rootCmd := &cobra.Command{
 		Use:   "arduino-app-cli",
-		Short: "A CLI to manage the Python app",
+		Short: "A CLI to manage Arduino Apps",
 		PersistentPreRun: func(cmd *cobra.Command, args []string) {
 			format, ok := feedback.ParseOutputFormat(format)
 			if !ok {

cmd/arduino-app-cli/system/system.go

@@ -37,7 +37,8 @@ import (
 
 func NewSystemCmd(cfg config.Configuration) *cobra.Command {
 	cmd := &cobra.Command{
-		Use: "system",
+		Use:   "system",
+		Short: "Manage the board’s system configuration",
 	}
 
 	cmd.AddCommand(newDownloadImageCmd(cfg))

cmd/arduino-app-cli/version/version.go

@@ -16,34 +16,95 @@
 package version
 
 import (
+	"encoding/json"
 	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"time"
 
 	"github.com/spf13/cobra"
 
 	"github.com/arduino/arduino-app-cli/cmd/feedback"
 )
 
-func NewVersionCmd(version string) *cobra.Command {
+// The actual listening address for the daemon
+// is defined in the installation package
+const (
+	DefaultHostname = "localhost"
+	DefaultPort     = "8800"
+	ProgramName     = "Arduino App CLI"
+)
+
+func NewVersionCmd(clientVersion string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "version",
 		Short: "Print the version number of Arduino App CLI",
 		Run: func(cmd *cobra.Command, args []string) {
-			feedback.PrintResult(versionResult{
-				AppName: "Arduino App CLI",
-				Version: version,
-			})
+			port, _ := cmd.Flags().GetString("port")
+
+			daemonVersion, err := getDaemonVersion(http.Client{}, port)
+			if err != nil {
+				feedback.Warnf("Warning: cannot get the running daemon version on %s:%s\n", DefaultHostname, port)
+			}
+
+			result := versionResult{
+				Name:          ProgramName,
+				Version:       clientVersion,
+				DaemonVersion: daemonVersion,
+			}
+
+			feedback.PrintResult(result)
 		},
 	}
+	cmd.Flags().String("port", DefaultPort, "The daemon network port")
 	return cmd
 }
 
+func getDaemonVersion(httpClient http.Client, port string) (string, error) {
+
+	httpClient.Timeout = time.Second
+
+	url := url.URL{
+		Scheme: "http",
+		Host:   net.JoinHostPort(DefaultHostname, port),
+		Path:   "/v1/version",
+	}
+
+	resp, err := httpClient.Get(url.String())
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("unexpected status code received")
+	}
+
+	var daemonResponse struct {
+		Version string `json:"version"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&daemonResponse); err != nil {
+		return "", err
+	}
+
+	return daemonResponse.Version, nil
+}
+
 type versionResult struct {
-	AppName string `json:"appName"`
-	Version string `json:"version"`
+	Name          string `json:"name"`
+	Version       string `json:"version"`
+	DaemonVersion string `json:"daemon_version,omitempty"`
 }
 
 func (r versionResult) String() string {
-	return fmt.Sprintf("%s v%s", r.AppName, r.Version)
+	resultMessage := fmt.Sprintf("%s version %s", ProgramName, r.Version)
+
+	if r.DaemonVersion != "" {
+		resultMessage = fmt.Sprintf("%s\ndaemon version: %s",
+			resultMessage, r.DaemonVersion)
+	}
+	return resultMessage
 }
 
 func (r versionResult) Data() interface{} {