Merge branch 'master' into update-frontend-templates

dfinity · Nov 29, 2024 · 75db25f · 75db25f
2 parents c62e88b + 3405dc6
commit 75db25f
Show file tree

Hide file tree

Showing 34 changed files with 730 additions and 101 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 # UNRELEASED
 
+### feat: `dfx start --pocketic` supports `--force` and shared networks.
+
+`dfx start --pocketic` is now compatible with `--force` and shared networks.
+
 ### feat: error when using insecure identity on mainnet
 
 This used to be a warning. A hard error can abort the command so that no insecure state will be on the mainnet.
@@ -10,6 +14,40 @@ Users can surpress this error by setting `export DFX_WARNING=-mainnet_plaintext_
 
 The warning won't display when executing commands like `dfx deploy --playground`.
 
+### feat: support `--replica` in `dfx start`
+
+Added a flag `--replica` to `dfx start`. This flag currently has no effect.
+Once PocketIC becomes the default for `dfx start` this flag will start the replica instead.
+You can use the `--replica` flag already to write scripts that anticipate that change.
+
+### feat: extensions can define project templates
+
+An extension can define one or more project templates for `dfx new` to use.
+These can be new templates or replace the built-in project templates.
+
+### fix: all commands with --all parameter skip remote canisters
+
+This affects the following commands:
+- `dfx canister delete`
+- `dfx canister deposit-cycles`
+- `dfx canister start`
+- `dfx canister status`
+- `dfx canister stop`
+- `dfx canister uninstall-code`
+- `dfx canister update-settings`
+- `dfx ledger fabricate-cycles`
+
+### chore: improve `dfx deploy` messages.
+
+If users run `dfx deploy` without enough cycles, show additional messages to indicate what to do next.
+```
+Error explanation:
+Insufficient cycles balance to create the canister.
+How to resolve the error:
+Please top up your cycles balance by converting ICP to cycles like below:
+'dfx cycles convert --amount=0.123'.
+```
+
 # 0.24.3
 
 ### feat: Bitcoin support in PocketIC
@@ -41,9 +79,9 @@ Allow setting permissions lists in init arguments just like in upgrade arguments
 - Module hash: f45db224b40fac516c877e3108dc809d4b22fa42d05ee8dfa5002536a3a3daed
 - Bump agent-js to fix error code
 
-### chore!: improve the messages for the subcommands of `dfx cycles`.
+### chore!: improve the messages for the subcommands of `dfx cycles` and `dfx ledger`.
 
-If users run subcommands of `dfx cycles` without the `--ic` flag, show below messages to indicate what to do next.
+If users run subcommands of `dfx cycles` or `dfx ledger` without the `--ic` flag, show below messages to indicate what to do next.
 ```
 Error explanation:
 Cycles ledger with canister ID 'um5iw-rqaaa-aaaaq-qaaba-cai' is not installed.

diff --git a/docs/cli-reference/dfx-start.mdx b/docs/cli-reference/dfx-start.mdx
@@ -25,6 +25,7 @@ You can use the following optional flags with the `dfx start` command.
 | `--enable-bitcoin`       | Enables bitcoin integration.                                                                                                                                                                                                                            |
 | `--enable-canister-http` | Enables canister HTTP requests. (deprecated: now enabled by default)                                                                                                                                                                                    |
 | `--pocketic`             | Runs [PocketIC](https://github.com/dfinity/pocketic) instead of the replica.                                                                                                                                                                            |
+| `--replica`              | Runs the replica instead of [PocketIC](https://github.com/dfinity/pocketic).                                                                                                                                                                            |
 
 ## Options
 

diff --git a/docs/concepts/extension-defined-project-templates.md b/docs/concepts/extension-defined-project-templates.md
@@ -0,0 +1,66 @@
+# Extension-Defined Project Templates
+
+## Overview
+
+An extension can define one or more project templates for `dfx new` to use.
+
+A project template is a set of files that `dfx new` copies or patches into a new project.
+
+For examples of project template files, see the [project_templates] directory in the SDK repository.
+
+# Specification
+
+The `project_templates` field in an extension's `extension.json` defines the project templates
+included in the extension.  It is an object field mapping `project template name -> project template properties`.
+These are the properties of a project template:
+
+| Field                        | Type                      | Description                                                                                          |
+|------------------------------|---------------------------|------------------------------------------------------------------------------------------------------|
+| `display`                    | String                    | Display name of the project template                                                                 |
+| `category`                   | String                    | Category for inclusion in `--backend` and `--frontend` CLI options, as well as interactive selection |
+| `requirements`               | Array of String           | Required project templates                                                                           |
+| `post_create`                | String or Array of String | Command(s) to run after adding the canister to the project                                           |
+| `post_create_spinner_message` | String                    | Message to display while running the post_create command                                            |
+| `post_create_failure_warning` | String                    | Warning to display if the post_create command fails                                                 |
+
+Within the files distributed with the extension, the project template files are
+located in the `project_templates/{project template name}` directory.
+
+## The `display` field
+
+The `display` field is a string that describes the project template.
+`dfx new` will use this value for interactive selection of project templates.
+
+## The `category` field
+
+The `category` field is an array of strings that categorize the project template.
+`dfx new` uses this field to determine whether to include this project template
+as an option for the `--backend` and `-frontend` flags, as well as in interactive setup.
+
+Valid values for the field:
+- `frontend`
+- `backend`
+- `extra`
+- `frontend-test`
+- `support`
+
+## The `requirements` field
+
+The `requirements` field lists any project templates that `dfx new` must apply before this project template.
+For example, many of the frontend templates depend on the `dfx_js_base` template, which adds
+package.json and tsconfig.json to the project.
+
+## The `post_create` field
+
+The `post_create` field specifies a command or commands to run after adding the project template files to the project.
+For example, the rust project template runs `cargo update` after adding the files.
+
+## The `post_create_spinner_message` field
+
+If this field is set, `dfx new` will display a spinner with this message while running the `post_create` command.
+
+## The `post_create_failure_warning` field
+
+If this field is present and the `post_create` command fails, `dfx new` will display this warning but won't stop creating the project.
+
+[project_templates]: https://github.com/dfinity/sdk/tree/master/src/dfx/assets/project_templates
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -2,3 +2,5 @@
 
 - [Asset Canister Interface](../design/asset-canister-interface.md)
 - [Canister metadata](./canister-metadata.md)
+- [Extension-Defined Canister Types](./extension-defined-canister-types.md)
+- [Extension-Defined Project Templates](./extension-defined-project-templates.md)
diff --git a/docs/extension-manifest-schema.json b/docs/extension-manifest-schema.json
@@ -70,6 +70,15 @@
     "name": {
       "type": "string"
     },
+    "project_templates": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": {
+        "$ref": "#/definitions/ExtensionProjectTemplate"
+      }
+    },
     "subcommands": {
       "anyOf": [
         {
@@ -155,6 +164,58 @@
         }
       ]
     },
+    "ExtensionProjectTemplate": {
+      "type": "object",
+      "required": [
+        "category",
+        "display",
+        "post_create",
+        "requirements"
+      ],
+      "properties": {
+        "category": {
+          "description": "Used to determine which CLI group (`--type`, `--backend`, `--frontend`) as well as for interactive selection",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ProjectTemplateCategory"
+            }
+          ]
+        },
+        "display": {
+          "description": "The name used for display and sorting",
+          "type": "string"
+        },
+        "post_create": {
+          "description": "Run a command after adding the canister to dfx.json",
+          "allOf": [
+            {
+              "$ref": "#/definitions/SerdeVec_for_String"
+            }
+          ]
+        },
+        "post_create_failure_warning": {
+          "description": "If the post-create command fails, display this warning but don't fail",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "post_create_spinner_message": {
+          "description": "If set, display a spinner while this command runs",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "requirements": {
+          "description": "Other project templates to patch in alongside this one",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "ExtensionSubcommandArgOpts": {
       "type": "object",
       "properties": {
@@ -231,6 +292,16 @@
         "$ref": "#/definitions/ExtensionSubcommandOpts"
       }
     },
+    "ProjectTemplateCategory": {
+      "type": "string",
+      "enum": [
+        "backend",
+        "frontend",
+        "frontend-test",
+        "extra",
+        "support"
+      ]
+    },
     "Range_of_uint": {
       "type": "object",
       "required": [
@@ -249,6 +320,19 @@
           "minimum": 0.0
         }
       }
+    },
+    "SerdeVec_for_String": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
     }
   }
 }
diff --git a/e2e/tests-dfx/cycles-ledger.bash b/e2e/tests-dfx/cycles-ledger.bash
@@ -458,6 +458,13 @@ current_time_nanoseconds() {
   assert_eq "2399699700000 cycles."
   assert_command dfx canister status e2e_project_backend
   assert_contains "Balance: 3_100_002_100_000 Cycles"
+
+  # deposit-cycles --all skips remote canisters
+  jq '.canisters.remote.remote.id.local="rdmx6-jaaaa-aaaaa-aaadq-cai"' dfx.json | sponge dfx.json
+  assert_command dfx canister deposit-cycles 10000 --all --identity bob
+  assert_contains "Skipping canister 'remote' because it is remote for network 'local'"
+  assert_contains "Depositing 10000 cycles onto e2e_project_backend"
+  assert_not_contains "Depositing 10000 cycles onto remote"
 }
 
 @test "top-up deduplication" {
@@ -584,9 +591,22 @@ current_time_nanoseconds() {
 
   assert_command dfx deploy
 
+  # Test canister creation failure before topping up cycles.
+  cd ..
+  dfx_new canister_creation_failed
+
+  # shellcheck disable=SC2030,SC2031
+  export DFX_DISABLE_AUTO_WALLET=1
+  assert_command_fail dfx canister create canister_creation_failed_backend --with-cycles 1T --identity alice
+  assert_contains "Insufficient cycles balance to create the canister."
+
+  ## Back to top up cycles.
+  cd ../temporary
+
   assert_command dfx canister call depositor deposit "(record {to = record{owner = principal \"$ALICE\";};cycles = 13_400_000_000_000;})" --identity cycle-giver
   assert_command dfx canister call depositor deposit "(record {to = record{owner = principal \"$ALICE\"; subaccount = opt blob \"$ALICE_SUBACCT1_CANDID\"};cycles = 2_600_000_000_000;})" --identity cycle-giver
 
+  # shellcheck disable=SC2103
   cd ..
   dfx_new
   # setup done