From ae3f5ca4f32303a5cf14dca5bfdf05dd34f1a0a9 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Fri, 30 Oct 2026 02:35:42 +0000 Subject: [PATCH 1/5] Document aspire template source add trust confirmation --- .../commands/aspire-template-source-add.mdx | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx new file mode 100644 index 0000000000..1696b86121 --- /dev/null +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx @@ -0,0 +1,84 @@ +--- +title: aspire template source add command +description: Learn about the aspire template source add command and its usage. This command adds a named template source to global configuration after confirming you trust it. +--- + +import Include from '@components/Include.astro'; + +## Name + +`aspire template source add` - Add a named template source to global configuration after confirming you trust it. + +## Synopsis + +```bash title="Aspire CLI" +aspire template source add [options] +``` + +## Description + +The `aspire template source add` command adds a named template source to global Aspire configuration. A template source is identified by a repository URL (`--repository`) or a local path (`--path`). + +Templates can run code, so the command asks you to trust the source before it changes any configuration. The prompt shows the source name and its repository URL or local path, and defaults to **No**: + +```text +Templates can run code. Do you trust template source 'company' (https://example.com/templates)? [y/N]: +``` + +If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass `--yes`. + +Non-interactive invocations, including invocations where interactive input isn't available, fail unless you pass `--yes`. + +## Arguments + +The following arguments are available: + +- **`name`** + + The name of the template source. + +## Options + +The following options are available: + +- **`--path`** + + The local path of the template source. + +- **`--repository`** + + The repository URL of the template source. + +- **`--ref`** + + The Git reference of the template source repository. + +- **`-y, --yes`** + + Trust the template source and skip confirmation. + +- + +- + +- + +- + +- + +- + +## Examples + +- Add a template source and confirm trust interactively: + + ```bash title="Aspire CLI" + aspire template source add company --repository https://example.com/templates + ``` + +- Add a template source in automation by explicitly trusting it: + + ```bash title="Aspire CLI" + aspire template source add company --repository https://example.com/templates --non-interactive --yes + ``` From d3f28ca1ce5c7047ddbb6a8702c765fd8aa338f2 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Sun, 1 Nov 2026 06:33:31 +0000 Subject: [PATCH 2/5] Add aspire template source add to the CLI reference sidebar The new command page had no sidebar entry, so the sidebar-topics plugin could not resolve its topic and the production build failed. Add the entry and a unit test that every CLI command page is listed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../config/sidebar/reference.topics.ts | 4 ++ .../unit/cli-command-sidebar.vitest.test.ts | 45 +++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index e93e30c950..5496852e6d 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -580,6 +580,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = { slug: 'reference/cli/commands/aspire-start', }, { label: 'aspire stop', slug: 'reference/cli/commands/aspire-stop' }, + { + label: 'aspire template source add', + slug: 'reference/cli/commands/aspire-template-source-add', + }, { label: 'aspire terminal', collapsed: true, diff --git a/src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts b/src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts new file mode 100644 index 0000000000..ece0fb949f --- /dev/null +++ b/src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts @@ -0,0 +1,45 @@ +import { readdirSync } from 'node:fs'; +import { join } from 'node:path'; + +import { describe, expect, it } from 'vitest'; + +import { referenceTopics } from '../../config/sidebar/reference.topics'; + +const commandsDir = join(process.cwd(), 'src/content/docs/reference/cli/commands'); + +function collectSlugs(items: unknown, slugs: Set): Set { + if (!Array.isArray(items)) { + return slugs; + } + + for (const item of items) { + if (typeof item === 'string') { + slugs.add(item); + } else if (item && typeof item === 'object') { + const { slug, items: children } = item as { slug?: unknown; items?: unknown }; + if (typeof slug === 'string') { + slugs.add(slug); + } + collectSlugs(children, slugs); + } + } + + return slugs; +} + +describe('CLI command reference sidebar', () => { + it('lists every CLI command page so the page resolves to the Reference topic', () => { + const slugs = collectSlugs(referenceTopics.items, new Set()); + const missing = readdirSync(commandsDir) + .filter((file) => /\.mdx?$/.test(file)) + .map((file) => `reference/cli/commands/${file.replace(/\.mdx?$/, '')}`) + .filter((slug) => !slugs.has(slug)); + + expect(missing).toEqual([]); + }); + + it('includes the aspire template source add command', () => { + const slugs = collectSlugs(referenceTopics.items, new Set()); + expect(slugs.has('reference/cli/commands/aspire-template-source-add')).toBe(true); + }); +}); From 0ef4eefe8053f100d5d10e09447bde36debad7a0 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Sun, 1 Nov 2026 08:29:39 +0000 Subject: [PATCH 3/5] Document both --path modes for aspire template source add Without --repository, --path must be an absolute local directory. With --repository, it is a repository-relative directory that defaults to the root. Also align --repository and --ref descriptions with the CLI help text and add subdirectory/ref and local-directory examples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../commands/aspire-template-source-add.mdx | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx index 1696b86121..c44e236e1b 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx @@ -17,7 +17,7 @@ aspire template source add [options] ## Description -The `aspire template source add` command adds a named template source to global Aspire configuration. A template source is identified by a repository URL (`--repository`) or a local path (`--path`). +The `aspire template source add` command adds a named template source to global Aspire configuration. A template source is either a Git repository (`--repository`, optionally with `--path` and `--ref`) or an absolute local directory (`--path` without `--repository`). Templates can run code, so the command asks you to trust the source before it changes any configuration. The prompt shows the source name and its repository URL or local path, and defaults to **No**: @@ -43,15 +43,18 @@ The following options are available: - **`--path`** - The local path of the template source. + The template directory. Its meaning depends on whether `--repository` is specified: + + - Without `--repository`, `--path` must be an absolute local directory that contains templates. + - With `--repository`, `--path` is a directory relative to the repository root. It defaults to the repository root (`.`). - **`--repository`** - The repository URL of the template source. + An HTTPS or SSH Git repository URL that contains templates. - **`--ref`** - The Git reference of the template source repository. + A Git branch, tag, or full commit SHA. Requires `--repository` and defaults to `HEAD`. - **`-y, --yes`** @@ -77,6 +80,18 @@ The following options are available: aspire template source add company --repository https://example.com/templates ``` +- Add a template source from a subdirectory of a repository at a specific tag: + + ```bash title="Aspire CLI" + aspire template source add company --repository https://example.com/templates --path templates/web --ref v1.0.0 + ``` + +- Add a template source from an absolute local directory: + + ```bash title="Aspire CLI" + aspire template source add local --path /home/user/templates + ``` + - Add a template source in automation by explicitly trusting it: ```bash title="Aspire CLI" From 6fee39132e93e97b7452211e5b049a6c486ac046 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Tue, 3 Nov 2026 11:41:19 +0000 Subject: [PATCH 4/5] Match template source add trust prompt and name rules to aspire main Source: microsoft/aspire main @020bf8c8 (TemplateManagementCommand.cs, TemplateSourceConfiguration.cs, TemplateSourceStore.cs; #21329, #21418). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../reference/cli/commands/aspire-template-source-add.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx index c44e236e1b..e3d5596a33 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx @@ -19,10 +19,10 @@ aspire template source add [options] The `aspire template source add` command adds a named template source to global Aspire configuration. A template source is either a Git repository (`--repository`, optionally with `--path` and `--ref`) or an absolute local directory (`--path` without `--repository`). -Templates can run code, so the command asks you to trust the source before it changes any configuration. The prompt shows the source name and its repository URL or local path, and defaults to **No**: +Templates can run code, so the command asks you to trust the source before it changes any configuration. It first displays the warning "Only use sources you trust. Content from these sources can run code on your machine." Then it prompts for confirmation. The prompt shows the source name and its repository URL or local path, and defaults to **No**: ```text -Templates can run code. Do you trust template source 'company' (https://example.com/templates)? [y/N]: +Do you trust template source 'company' (https://example.com/templates)? [y/N]: ``` If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass `--yes`. @@ -35,7 +35,7 @@ The following arguments are available: - **`name`** - The name of the template source. + The name of the template source. The name can't be empty or whitespace, or contain `.`, `:`, or control characters. Names are case-insensitive, and the command fails if a template source with the same name already exists. ## Options From e061986d260a59374d7f652baf454e8468d975a1 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Thu, 5 Nov 2026 11:31:30 +0000 Subject: [PATCH 5/5] Align template source add name and path rules with aspire main Source names now allow dots and must be 1-64 ASCII letters, digits, dots, hyphens, or underscores starting with a letter or digit (SourceNameValidator). Repository-relative --path can't be absolute or escape with '..'. The trust warning is written to stderr after name/location validation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../reference/cli/commands/aspire-template-source-add.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx index e3d5596a33..46e676fb14 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx @@ -19,7 +19,7 @@ aspire template source add [options] The `aspire template source add` command adds a named template source to global Aspire configuration. A template source is either a Git repository (`--repository`, optionally with `--path` and `--ref`) or an absolute local directory (`--path` without `--repository`). -Templates can run code, so the command asks you to trust the source before it changes any configuration. It first displays the warning "Only use sources you trust. Content from these sources can run code on your machine." Then it prompts for confirmation. The prompt shows the source name and its repository URL or local path, and defaults to **No**: +Templates can run code, so the command asks you to trust the source before it changes any configuration. After it validates the name and location, it writes the warning "Only use sources you trust. Content from these sources can run code on your machine." to standard error. Then it prompts for confirmation. The prompt shows the source name and its repository URL or local path, and defaults to **No**: ```text Do you trust template source 'company' (https://example.com/templates)? [y/N]: @@ -35,7 +35,7 @@ The following arguments are available: - **`name`** - The name of the template source. The name can't be empty or whitespace, or contain `.`, `:`, or control characters. Names are case-insensitive, and the command fails if a template source with the same name already exists. + The name of the template source. The name must be 1-64 ASCII letters, digits, dots (`.`), hyphens (`-`), or underscores (`_`), and must start with a letter or digit. Names are case-insensitive, and the command fails if a template source with the same name already exists. ## Options @@ -46,7 +46,7 @@ The following options are available: The template directory. Its meaning depends on whether `--repository` is specified: - Without `--repository`, `--path` must be an absolute local directory that contains templates. - - With `--repository`, `--path` is a directory relative to the repository root. It defaults to the repository root (`.`). + - With `--repository`, `--path` is a directory relative to the repository root. It can't be an absolute path or use `..` to point outside the repository. It defaults to the repository root (`.`). - **`--repository`**