Operations

Extension Installation Module

Extension installation operations.

Handles installing extensions from GitHub, URLs, and local sources.

Interfaces

InstallOptions

Defined in: packages/core/src/operations/install.ts:76

Options for extension installation.

Extends

RegistryOptions

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
`auth?`	`AuthConfig`	Authentication configuration.	`RegistryOptions`.`auth`	-	packages/core/src/operations/install.ts:80
`cacheDir?`	`string`	Cache directory (uses platform default if not provided).	-	`RegistryOptions`.`cacheDir`	packages/core/src/registry/fetcher.ts:30
`cacheTtl?`	`number`	Cache TTL in milliseconds (default: 24 hours).	-	`RegistryOptions`.`cacheTtl`	packages/core/src/registry/fetcher.ts:34
`confirmOverwrite?`	`ConfirmOverwriteCallback`	Callback for confirming overwrite when extension already exists. Only called when force is true. If not provided, overwrites silently. Return true to overwrite, false to cancel.	-	-	packages/core/src/operations/install.ts:101
`dryRun?`	`boolean`	Dry run mode - resolve without installing.	-	-	packages/core/src/operations/install.ts:88
`force?`	`boolean`	Force reinstall if already installed.	-	-	packages/core/src/operations/install.ts:84
`forceRefresh?`	`boolean`	Force refresh, ignoring cache.	-	`RegistryOptions`.`forceRefresh`	packages/core/src/registry/fetcher.ts:32
`keepSourceDir?`	`boolean`	Keep source directory after installation (for template copying).	-	-	packages/core/src/operations/install.ts:86
`onProgress?`	`InstallProgressCallback`	Progress callback.	-	-	packages/core/src/operations/install.ts:82
`projectDir`	`string`	Project directory.	-	-	packages/core/src/operations/install.ts:78
`registryUrl?`	`string`	Custom registry URL.	-	`RegistryOptions`.`registryUrl`	packages/core/src/registry/fetcher.ts:28
`selectExtension?`	`ExtensionSelectionCallback`	Callback for selecting extensions when source contains multiple. If not provided and source contains multiple extensions, the first one is installed (legacy behaviour).	-	-	packages/core/src/operations/install.ts:95
`sourceDisplay?`	`string`	Display source to record in manifest (for relative paths that were resolved).	-	-	packages/core/src/operations/install.ts:90
`timeout?`	`number`	Request timeout in milliseconds.	-	`RegistryOptions`.`timeout`	packages/core/src/registry/fetcher.ts:38
`validateQuartoVersion?`	`ValidateQuartoVersionCallback`	Callback for validating Quarto version requirement. Called when the manifest specifies a quartoRequired field. Return true to proceed, false to cancel.	-	-	packages/core/src/operations/install.ts:107

InstallResult

Defined in: packages/core/src/operations/install.ts:113

Result of installation.

Properties

Property	Type	Description	Defined in
`additionalInstalls?`	`InstallResult[]`	Additional extensions installed when multiple were selected (only set when using selectExtension callback).	packages/core/src/operations/install.ts:131
`alreadyExists?`	`boolean`	Whether the extension already exists (only relevant in dry run mode).	packages/core/src/operations/install.ts:129
`cancelled?`	`boolean`	Whether the installation was cancelled by user (via callbacks).	packages/core/src/operations/install.ts:133
`dryRun?`	`boolean`	Whether this was a dry run (no files were actually created).	packages/core/src/operations/install.ts:125
`extension`	`InstalledExtension`	Installed extension details.	packages/core/src/operations/install.ts:117
`filesCreated`	`string[]`	Files created during installation.	packages/core/src/operations/install.ts:119
`source`	`string`	Source string for the manifest.	packages/core/src/operations/install.ts:121
`sourceRoot?`	`string`	Path to extracted source root (only set if keepSourceDir was true).	packages/core/src/operations/install.ts:123
`success`	`boolean`	Whether installation succeeded.	packages/core/src/operations/install.ts:115
`wouldCreate?`	`string[]`	Files that would be created (only set in dry run mode).	packages/core/src/operations/install.ts:127

Type Aliases

ConfirmOverwriteCallback()

TypeScript

type ConfirmOverwriteCallback = (extension) => Promise<boolean>;

Defined in: packages/core/src/operations/install.ts:62

Callback for confirming overwrite when extension already exists.

Parameters

Parameter	Type	Description
`extension`	`DiscoveredExtension`	The extension that already exists

Returns

Promise<boolean>

True to overwrite, false to skip/cancel

ExtensionSelectionCallback()

TypeScript

type ExtensionSelectionCallback = (extensions) => Promise<DiscoveredExtension[] | null>;

Defined in: packages/core/src/operations/install.ts:54

Callback for selecting which extension(s) to install from a multi-extension source. Called when a repository contains multiple extensions.

Parameters

Parameter	Type	Description
`extensions`	`DiscoveredExtension[]`	Array of discovered extensions in the source

Returns

Promise<<code><a href="archive.qmd#discoveredextension" style="text-decoration-line: underline; text-decoration-style: dashed; text-decoration-thickness: 1px; text-decoration-color: currentColor;">DiscoveredExtension</a>[]</code>{=html} | null>

Selected extensions to install, or null to cancel

InstallPhase

TypeScript

type InstallPhase = "resolving" | "downloading" | "extracting" | "installing" | "finalizing";

Defined in: packages/core/src/operations/install.ts:40

Progress phases for installation.

InstallProgressCallback()

TypeScript

type InstallProgressCallback = (progress) => void;

Defined in: packages/core/src/operations/install.ts:45

Progress callback for installation.

Parameters

Parameter	Type
`progress`	{ `message`: `string`; `percentage?`: `number`; `phase`: `InstallPhase`; }
`progress.message`	`string`
`progress.percentage?`	`number`
`progress.phase`	`InstallPhase`

Returns

void

InstallSource

TypeScript

type InstallSource =
  | {
  owner: string;
  repo: string;
  type: "github";
  version: VersionSpec;
}
  | {
  type: "url";
  url: string;
}
  | {
  path: string;
  type: "local";
};

Defined in: packages/core/src/operations/install.ts:32

Source for extension installation.

ValidateQuartoVersionCallback()

TypeScript

type ValidateQuartoVersionCallback = (required, manifest) => Promise<boolean>;

Defined in: packages/core/src/operations/install.ts:71

Callback for validating Quarto version requirement.

Parameters

Parameter	Type	Description
`required`	`string`	The required Quarto version string from the manifest
`manifest`	`ExtensionManifest`	The extension manifest

Returns

Promise<boolean>

True to proceed with installation, false to cancel

Functions

formatInstallSource()

TypeScript

function formatInstallSource(source): string;

Defined in: packages/core/src/operations/install.ts:227

Format an install source as a string.

Parameters

Parameter	Type
`source`	`InstallSource`

Returns

string

install()

TypeScript

function install(source, options): Promise<InstallResult>;

Defined in: packages/core/src/operations/install.ts:276

Install an extension from a source.

Parameters

Parameter	Type	Description
`source`	`InstallSource`	Installation source
`options`	`InstallOptions`	Installation options

Returns

Promise<InstallResult>

Installation result

Example

TypeScript

// Install from GitHub
const source = parseInstallSource("quarto-ext/fontawesome");
const result = await install(source, { projectDir: "." });
console.log(`Installed ${result.extension.id.name}`);

// Install with progress tracking
await install(source, {
  projectDir: ".",
  onProgress: ({ phase, message }) => console.log(`[${phase}] ${message}`),
});

installSingleExtension()

TypeScript

function installSingleExtension(
   extension,
   projectDir,
   sourceString,
   force,
   onProgress?,
confirmOverwrite?): Promise<InstallResult>;

Defined in: packages/core/src/operations/install.ts:650

Install a single extension from an already-extracted directory. Used for installing additional extensions when multiple are selected, or when installing extensions directly with pre-computed IDs (e.g., from twoPhaseUse).

Parameters

Parameter	Type	Description
`extension`	`DiscoveredExtension`	Discovered extension with path and pre-computed ID
`projectDir`	`string`	Project directory to install to
`sourceString`	`string`	Source string to record in manifest
`force`	`boolean`	Whether to force reinstall
`onProgress?`	`InstallProgressCallback`	Progress callback
`confirmOverwrite?`	`ConfirmOverwriteCallback`	Callback to confirm overwrite when extension exists

Returns

Promise<InstallResult>

Installation result

parseInstallSource()

TypeScript

function parseInstallSource(input): InstallSource;

Defined in: packages/core/src/operations/install.ts:161

Parse an install source string.

Parameters

Parameter	Type	Description
`input`	`string`	Source string (GitHub ref, URL, or local path)

Returns

InstallSource

Parsed InstallSource

Example

TypeScript

// GitHub reference
parseInstallSource("quarto-ext/fontawesome");
// { type: "github", owner: "quarto-ext", repo: "fontawesome", version: { type: "latest" } }

// GitHub with version
parseInstallSource("quarto-ext/lightbox@v1.0.0");
// { type: "github", ..., version: { type: "tag", tag: "v1.0.0" } }

// URL
parseInstallSource("https://example.com/ext.zip");
// { type: "url", url: "https://example.com/ext.zip" }

// Local path
parseInstallSource("./my-extension");
// { type: "local", path: "./my-extension" }

Extension Removal Module

Extension removal operations.

Handles removing installed extensions from a project.

Interfaces

RemoveOptions

Defined in: packages/core/src/operations/remove.ts:21

Options for removal.

Properties

Property	Type	Description	Defined in
`cleanupEmpty?`	`boolean`	Clean up empty parent directories.	packages/core/src/operations/remove.ts:25
`projectDir`	`string`	Project directory.	packages/core/src/operations/remove.ts:23

RemoveResult

Defined in: packages/core/src/operations/remove.ts:31

Result of removal.

Properties

Property	Type	Description	Defined in
`directoriesRemoved`	`string[]`	Directories cleaned up.	packages/core/src/operations/remove.ts:39
`extension`	`InstalledExtension`	Removed extension details.	packages/core/src/operations/remove.ts:35
`filesRemoved`	`string[]`	Files removed.	packages/core/src/operations/remove.ts:37
`success`	`boolean`	Whether removal succeeded.	packages/core/src/operations/remove.ts:33

Functions

remove()

TypeScript

function remove(extensionId, options): Promise<RemoveResult>;

Defined in: packages/core/src/operations/remove.ts:58

Remove an installed extension.

Parameters

Parameter	Type	Description
`extensionId`	`ExtensionId`	Extension to remove
`options`	`RemoveOptions`	Removal options

Returns

Promise<RemoveResult>

Removal result

Example

TypeScript

const result = await remove(
  { owner: "quarto-ext", name: "fontawesome" },
  { projectDir: ".", cleanupEmpty: true }
);
console.log(`Removed ${result.filesRemoved.length} files`);

removeMultiple()

TypeScript

function removeMultiple(extensionIds, options): Promise<(
  | RemoveResult
  | {
  error: string;
  extensionId: ExtensionId;
})[]>;

Defined in: packages/core/src/operations/remove.ts:97

Remove multiple extensions.

Parameters

Parameter	Type	Description
`extensionIds`	`ExtensionId[]`	Extensions to remove
`options`	`RemoveOptions`	Removal options

Returns

Promise<( | RemoveResult | { error: string; extensionId: ExtensionId; })[]>

Array of removal results

Extension Update Module

Extension update operations.

Handles checking for and applying updates to installed extensions.

Interfaces

UpdateCheckOptions

Defined in: packages/core/src/operations/update.ts:41

Options for checking updates.

Extends

RegistryOptions

Extended by

UpdateOptions

Properties

Property	Type	Description	Inherited from	Defined in
`auth?`	`AuthConfig`	Authentication configuration.	`RegistryOptions`.`auth`	packages/core/src/registry/fetcher.ts:36
`cacheDir?`	`string`	Cache directory (uses platform default if not provided).	`RegistryOptions`.`cacheDir`	packages/core/src/registry/fetcher.ts:30
`cacheTtl?`	`number`	Cache TTL in milliseconds (default: 24 hours).	`RegistryOptions`.`cacheTtl`	packages/core/src/registry/fetcher.ts:34
`extension?`	`ExtensionId`	Specific extension to check (all if omitted).	-	packages/core/src/operations/update.ts:45
`forceRefresh?`	`boolean`	Force refresh, ignoring cache.	`RegistryOptions`.`forceRefresh`	packages/core/src/registry/fetcher.ts:32
`projectDir`	`string`	Project directory.	-	packages/core/src/operations/update.ts:43
`registryUrl?`	`string`	Custom registry URL.	`RegistryOptions`.`registryUrl`	packages/core/src/registry/fetcher.ts:28
`timeout?`	`number`	Request timeout in milliseconds.	`RegistryOptions`.`timeout`	packages/core/src/registry/fetcher.ts:38

UpdateInfo

Defined in: packages/core/src/operations/update.ts:25

Information about an available update.

Properties

Property	Type	Description	Defined in
`currentVersion`	`string`	Current installed version.	packages/core/src/operations/update.ts:29
`extension`	`InstalledExtension`	Extension with update available.	packages/core/src/operations/update.ts:27
`latestVersion`	`string`	Latest available version.	packages/core/src/operations/update.ts:31
`releaseUrl`	`string` \| `null`	URL to the release.	packages/core/src/operations/update.ts:33
`source`	`string`	Source reference for updating.	packages/core/src/operations/update.ts:35

UpdateOptions

Defined in: packages/core/src/operations/update.ts:51

Options for applying updates.

Extends

UpdateCheckOptions

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
`auth?`	`AuthConfig`	Authentication configuration.	`UpdateCheckOptions`.`auth`	-	packages/core/src/operations/update.ts:53
`cacheDir?`	`string`	Cache directory (uses platform default if not provided).	-	`UpdateCheckOptions`.`cacheDir`	packages/core/src/registry/fetcher.ts:30
`cacheTtl?`	`number`	Cache TTL in milliseconds (default: 24 hours).	-	`UpdateCheckOptions`.`cacheTtl`	packages/core/src/registry/fetcher.ts:34
`extension?`	`ExtensionId`	Specific extension to check (all if omitted).	-	`UpdateCheckOptions`.`extension`	packages/core/src/operations/update.ts:45
`forceRefresh?`	`boolean`	Force refresh, ignoring cache.	-	`UpdateCheckOptions`.`forceRefresh`	packages/core/src/registry/fetcher.ts:32
`onProgress?`	(`info`) => `void`	Progress callback.	-	-	packages/core/src/operations/update.ts:55
`projectDir`	`string`	Project directory.	-	`UpdateCheckOptions`.`projectDir`	packages/core/src/operations/update.ts:43
`registryUrl?`	`string`	Custom registry URL.	-	`UpdateCheckOptions`.`registryUrl`	packages/core/src/registry/fetcher.ts:28
`timeout?`	`number`	Request timeout in milliseconds.	-	`UpdateCheckOptions`.`timeout`	packages/core/src/registry/fetcher.ts:38

UpdateResult

Defined in: packages/core/src/operations/update.ts:61

Result of update operation.

Properties

Property	Type	Description	Defined in
`failed`	`object[]`	Failed updates with errors.	packages/core/src/operations/update.ts:74
`skipped`	`object[]`	Skipped extensions with reasons.	packages/core/src/operations/update.ts:69
`updated`	`object[]`	Successfully updated extensions.	packages/core/src/operations/update.ts:63

Functions

applyUpdates()

TypeScript

function applyUpdates(updates, options): Promise<UpdateResult>;

Defined in: packages/core/src/operations/update.ts:179

Apply updates to extensions.

Parameters

Parameter	Type	Description
`updates`	`UpdateInfo[]`	Updates to apply
`options`	`UpdateOptions`	Update options

Returns

Promise<UpdateResult>

Update result

checkForUpdates()

TypeScript

function checkForUpdates(options): Promise<UpdateInfo[]>;

Defined in: packages/core/src/operations/update.ts:86

Check for available updates.

Parameters

Parameter	Type	Description
`options`	`UpdateCheckOptions`	Check options

Returns

Promise<<code><a href="#updateinfo" style="text-decoration-line: underline; text-decoration-style: dashed; text-decoration-thickness: 1px; text-decoration-color: currentColor;">UpdateInfo</a>[]</code>{=html}>

Array of available updates

update()

TypeScript

function update(options): Promise<UpdateResult>;

Defined in: packages/core/src/operations/update.ts:235

Check and apply updates in one operation.

Parameters

Parameter	Type	Description
`options`	`UpdateOptions`	Update options

Returns

Promise<UpdateResult>

Update result

Template Use Module

Use extension operation for installing and copying template files.

Combines installation with template file copying for starter templates.

Interfaces

FileSelectionResult

Defined in: packages/core/src/operations/use.ts:150

Result of file selection callback.

Properties

Property	Type	Description	Defined in
`overwriteExisting`	`boolean`	Whether to overwrite existing files without prompting.	packages/core/src/operations/use.ts:154
`selectedFiles`	`string[]`	Files selected for copying.	packages/core/src/operations/use.ts:152

UseOptions

Defined in: packages/core/src/operations/use.ts:180

Options for “use extension” operation.

Properties

Property	Type	Description	Defined in
`auth?`	`AuthConfig`	Authentication configuration.	packages/core/src/operations/use.ts:184
`confirmExtensionOverwrite?`	(`extensions`) => `Promise<<code><a href="archive.qmd#discoveredextension" style="text-decoration-line: underline; text-decoration-style: dashed; text-decoration-thickness: 1px; text-decoration-color: currentColor;">DiscoveredExtension</a>[]</code>{=html} \| null>`	Callback to confirm overwriting existing extensions. Called with extensions that already exist in the project. Returns the extensions to overwrite, or null to cancel.	packages/core/src/operations/use.ts:219
`confirmOverwrite?`	`OverwriteCallback`	Callback to confirm overwrites (per-file). Takes precedence if confirmOverwriteBatch is not provided.	packages/core/src/operations/use.ts:192
`confirmOverwriteBatch?`	`OverwriteBatchCallback`	Callback to confirm overwrites in batch. Receives all conflicting files upfront. Takes precedence over confirmOverwrite.	packages/core/src/operations/use.ts:194
`dryRun?`	`boolean`	Dry run mode - resolve and validate without copying files.	packages/core/src/operations/use.ts:206
`exclude?`	`string[]`	Additional patterns to exclude.	packages/core/src/operations/use.ts:190
`include?`	`string[]`	File patterns to include (overrides defaults).	packages/core/src/operations/use.ts:188
`noTemplate?`	`boolean`	Skip template copying.	packages/core/src/operations/use.ts:186
`onProgress?`	(`info`) => `void`	Progress callback.	packages/core/src/operations/use.ts:204
`projectDir`	`string`	Project directory.	packages/core/src/operations/use.ts:182
`selectExtension?`	`ExtensionSelectionCallback`	Callback for selecting extensions when source contains multiple. If not provided and source contains multiple extensions, the first one is installed.	packages/core/src/operations/use.ts:213
`selectFiles?`	`FileSelectionCallback`	Callback for interactive file selection. Takes precedence over include/exclude/confirmOverwrite.	packages/core/src/operations/use.ts:196
`selectFilesFirst?`	`boolean`	Show file selection before installing extension (default: false). When true, the extension is only installed if the user confirms file selection. When false, the extension is installed immediately and then files are selected.	packages/core/src/operations/use.ts:202
`selectTargetSubdir?`	`SelectTargetSubdirCallback`	Callback for interactive target subdirectory selection. Called before file selection in two-phase flow. Returns subdirectory path, or null/empty string for project root.	packages/core/src/operations/use.ts:231
`sourceDisplay?`	`string`	Display source to record in manifest (for relative paths that were resolved).	packages/core/src/operations/use.ts:208
`targetSubdir?`	`string`	Subdirectory within projectDir where template files should be copied. If selectTargetSubdir callback is provided and selectFilesFirst is true, the callback takes precedence.	packages/core/src/operations/use.ts:225

UseResult

Defined in: packages/core/src/operations/use.ts:237

Result of “use extension” operation.

Properties

Property	Type	Description	Defined in
`cancelled?`	`boolean`	Whether the user cancelled the file selection (only set when selectFilesFirst is true).	packages/core/src/operations/use.ts:251
`dryRun?`	`boolean`	Whether this was a dry run (no files were actually copied).	packages/core/src/operations/use.ts:245
`install`	`InstallResult`	Installation result.	packages/core/src/operations/use.ts:239
`skippedFiles`	`string[]`	Files skipped due to existing.	packages/core/src/operations/use.ts:243
`templateFiles`	`string[]`	Template files copied.	packages/core/src/operations/use.ts:241
`wouldConflict?`	`string[]`	Files that would conflict with existing files (only set in dry run mode).	packages/core/src/operations/use.ts:249
`wouldCopy?`	`string[]`	Template files that would be copied (only set in dry run mode).	packages/core/src/operations/use.ts:247

Type Aliases

FileSelectionCallback()

TypeScript

type FileSelectionCallback = (availableFiles, existingFiles, defaultExcludePatterns) => Promise<FileSelectionResult | null>;

Defined in: packages/core/src/operations/use.ts:162

Callback for interactive file selection. Receives all available template files and which ones already exist. Returns which files to copy and whether to overwrite existing.

Parameters

Parameter	Type
`availableFiles`	`string[]`
`existingFiles`	`string[]`
`defaultExcludePatterns`	`string[]`

Returns

Promise<FileSelectionResult | null>

OverwriteBatchCallback()

TypeScript

type OverwriteBatchCallback = (files) => Promise<OverwriteBatchResult>;

Defined in: packages/core/src/operations/use.ts:145

Callback for confirming file overwrites in batch. Receives all conflicting files upfront and returns which ones to overwrite.

Parameters

Parameter	Type
`files`	`string[]`

Returns

Promise<OverwriteBatchResult>

OverwriteBatchResult

TypeScript

type OverwriteBatchResult = "all" | "none" | string[];

Defined in: packages/core/src/operations/use.ts:139

Result of batch overwrite confirmation.

‘all’: Overwrite all files.
‘none’: Skip all files.
string[]: List of specific files to overwrite.

OverwriteCallback()

TypeScript

type OverwriteCallback = (file) => Promise<boolean>;

Defined in: packages/core/src/operations/use.ts:131

Callback for confirming file overwrites (per-file).

Parameters

Parameter	Type
`file`	`string`

Returns

Promise<boolean>

SelectTargetSubdirCallback()

TypeScript

type SelectTargetSubdirCallback = () => Promise<string | null | undefined>;

Defined in: packages/core/src/operations/use.ts:175

Callback for selecting target subdirectory. Returns:

undefined: user cancelled (stop operation)
null: user selected project root
string: user entered a subdirectory path

Returns

Promise<string | null | undefined>

Functions

getTemplateFiles()

TypeScript

function getTemplateFiles(sourceRoot, exclude): Promise<string[]>;

Defined in: packages/core/src/operations/use.ts:807

Get list of template files that would be copied from repo root.

Parameters

Parameter	Type	Default value	Description
`sourceRoot`	`string`	`undefined`	Repository root directory
`exclude`	`string[]`	`DEFAULT_EXCLUDE_PATTERNS`	Patterns to exclude

Returns

Promise<string[]>

List of template file paths

use()

TypeScript

function use(source, options): Promise<UseResult>;

Defined in: packages/core/src/operations/use.ts:531

Install an extension and optionally copy template files.

Parameters

Parameter	Type	Description
`source`	`string` \| `InstallSource`	Extension source (string or InstallSource)
`options`	`UseOptions`	Use options

Returns

Promise<UseResult>

Use result