### Configure SharePoint Framework Project Welcome Experience in VS Code

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

This section describes the welcome experience of the SharePoint Framework Toolkit extension for Visual Studio Code. It guides users through creating new projects from scratch or samples, opening existing projects, and validating the local development environment. The walkthrough provides a step-by-step guide for getting started with SPFx development.

```APIDOC
Conceptual API for Welcome Experience:

interface WelcomeExperience {
  actions: {
    createNewProject: (options: { from: 'scratch' | 'sample' }) => void;
    openExistingProject: (path: string) => void;
    validateLocalEnvironment: () => ValidationResult;
  };
  walkthrough: {
    start: () => void;
    steps: string[];
  };
}

// Example of validating environment
const validationResult = WelcomeExperience.actions.validateLocalEnvironment();
console.log(validationResult);
```

--------------------------------

### Set up SharePoint Framework Toolkit Extension Development Environment

Source: https://github.com/pnp/vscode-viva/blob/main/contributing.md

This guide outlines the essential steps to configure your local development environment for contributing to the SharePoint Framework Toolkit extension. It covers cloning necessary repositories, installing Node.js dependencies, building a CommonJS fork of the CLI for Microsoft 365, and linking it to the extension's `node_modules` folder. Ensure Node.js 18.17.X or higher is used.

```npm
npm install
```

```npm
npm install
npm run clean
npm run build
```

```plaintext
root:
  - cli-microsoft365
  - vscode-viva
```

```PowerShell
.\scripts\cli-for-microsoft365-copy-local-version.ps1 -workspacePath <YOUR_WORKSPACE_ROOT_PATH>
```

```npm
npm run watch
```

--------------------------------

### Install SharePoint Framework Development Dependencies with npm

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/validate-local-setup.md

This command globally installs the core dependencies required for SharePoint Framework (SPFx) development. It includes gulp-cli for task automation, yo (Yeoman) for project scaffolding, and @microsoft/generator-sharepoint, the Yeoman generator specifically for SPFx projects. These tools are fundamental for creating, building, and deploying SPFx solutions.

```sh
npm install gulp-cli yo @microsoft/generator-sharepoint --global
```

--------------------------------

### PnP VSCode Viva Extension Testing Procedures

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/contributing-guidance.mdx

This section provides instructions for running and debugging tests for the PnP VSCode Viva extension. It outlines the necessary setup steps and commands to execute tests locally.

```Shell
# 1. Install VSCode Extension Test Runner
#    https://marketplace.visualstudio.com/items?itemName=ms-vscode.extension-test-runner
# 2. Package and compile tests
npm run package && npm run compile-tests
# 3. Run 'Extension Tests' in debug mode from VSCode
```

```Shell
# 1. Package and compile tests
npm run package && npm run compile-tests
# 2. Run tests and check results in terminal
npm run test
```

--------------------------------

### Validate SPFx Project Setup with CLI for Microsoft 365

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This action generates a validation Markdown report and/or code tour guidance for the open SPFx project. It automatically detects the SPFx version and validates the project's setup. This helps ensure the project is configured correctly.

```APIDOC
CLI for Microsoft 365 Command:
`spfx project doctor [options]`

Purpose: Validates the setup and configuration of the current SPFx project.
```

--------------------------------

### Configure SPFx Development Environment with /setup Command

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

The `/setup` command provides detailed information and guidance on how to configure your local workspace for SharePoint Framework development. This command streamlines the initial setup process for new and existing projects.

```GitHub Copilot Chat
/setup
```

--------------------------------

### m365 spo tenant applicationcustomizer get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets an application customizer that is installed tenant-wide in SharePoint Online. This command helps in identifying global extensions.

```CLI
m365 spo tenant applicationcustomizer get
```

--------------------------------

### Scaffold New SPFx Projects with VS Code Viva Extension

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

The VS Code Viva extension simplifies new project creation through a dedicated scaffolding form that supports all types of SPFx projects. This wizard allows users to easily install additional dependencies like PnP reusable controls, PnPjs, and configure Fast Serve or Node Version Manager settings. This streamlined process ensures a quick and customized setup for new SPFx solutions.

```Documentation
Creating a new project was never easier. Just use the create a new project action, and the extension will guide you through the process with a dedicated scaffolding form.

It's possible to scaffold any kind of SPFx project.

Install additional dependencies with a single click straight from the scaffolding form. Currently we support installing PnP reusable property pane controls, PnP reusable React controls, PnPjs. Add and preconfigure SPFx Fast Serve and add a Node Version Manager configuration file either for NVM or NVS.
```

--------------------------------

### Start New Projects from ACE Scenarios in VS Code Viva

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

The VS Code Viva extension offers pre-configured ACE scenarios to begin new solutions with ready-to-use code. These scenarios include detailed guidance provided via Code Tour, helping developers understand the structure and available options. This method accelerates development by providing a foundational codebase for common Adaptive Card Extension use cases.

```Documentation
Start your solution based on the provided set of ACE scenarios with ready-to-use code to showcase what's possible. Scenarios are provided with detailed guidance using the Code Tour to provide you with more details on the structure and options.
```

--------------------------------

### Create New SPFx Solutions or Find Samples with /new Command

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

The `/new` command assists in creating new SharePoint Framework solutions or helps in finding and reusing existing samples from the PnP SPFx sample gallery. It simplifies the process of starting new projects or leveraging community contributions.

```GitHub Copilot Chat
/new
```

--------------------------------

### m365 spo folder get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets information about the specified folder in SharePoint. This command retrieves details and properties of a particular folder.

```CLI
m365 spo folder get
```

--------------------------------

### m365 spo theme get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets custom theme information for a SharePoint site. This command retrieves details about applied custom branding.

```CLI
m365 spo theme get
```

--------------------------------

### Validate and Install SharePoint Framework Development Dependencies

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

This capability allows users to validate their local development environment for SharePoint Framework solutions. It checks for required dependencies such as Node.js version 22 and specific NPM packages (gulp, yo, @microsoft/generator-sharepoint). The tool provides an option to install missing or incorrect dependencies with a single action.

```APIDOC
Conceptual API for Environment Setup:

interface DevelopmentEnvironmentValidator {
  requiredDependencies: {
    nodeVersion: string; // e.g., "22"
    npmPackages: string[]; // e.g., ["gulp", "yo", "@microsoft/generator-sharepoint"]
  };
  validate: () => ValidationReport;
  installMissingDependencies: () => InstallationResult;
}

interface ValidationReport {
  isValid: boolean;
  details: {
    node: { version: string; status: 'ok' | 'incorrect' | 'missing' };
    npm: { package: string; status: 'ok' | 'incorrect' | 'missing' }[];
  };
}

// Example usage:
const validator = new DevelopmentEnvironmentValidator();
const report = validator.validate();

if (!report.isValid) {
  console.log("Dependencies are not met. Installing...");
  validator.installMissingDependencies();
}
```

--------------------------------

### m365 spo file list

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets all files within the specified folder and site in SharePoint. This command helps in inventorying content within a specific location.

```CLI
m365 spo file list
```

--------------------------------

### Manage SharePoint App Catalog Solutions (APIDOC)

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/tenant-details.md

Details the various operations available for managing solutions within SharePoint tenant-level and site-level app catalogs through the VS Code extension. This includes actions like deploying, retracting, removing, enabling, disabling, upgrading, installing, and uninstalling apps, along with their respective purposes and required parameters.

```APIDOC
{
  "resource": "AppCatalogSolution",
  "description": "Operations for managing solutions within SharePoint App Catalogs (tenant-level and site-level).",
  "methods": [
    {
      "name": "Deploy",
      "description": "Makes the solution available for installation in sites but does not automatically install it.",
      "parameters": [{"name": "solutionId", "type": "string", "description": "ID of the solution to deploy."}]
    },
    {
      "name": "Retract",
      "description": "Reverses the deployment, preventing the solution from being installed in sites.",
      "parameters": [{"name": "solutionId", "type": "string", "description": "ID of the solution to retract."}]
    },
    {
      "name": "Remove",
      "description": "Removes the app from the app catalog.",
      "parameters": [{"name": "solutionId", "type": "string", "description": "ID of the solution to remove."}]
    },
    {
      "name": "Enable",
      "description": "Allows end users to add the solution to their SharePoint sites.",
      "parameters": [{"name": "solutionId", "type": "string", "description": "ID of the solution to enable."}]
    },
    {
      "name": "Disable",
      "description": "Hides the solution from end users, preventing them from adding it to sites.",
      "parameters": [{"name": "solutionId", "type": "string", "description": "ID of the solution to disable."}]
    },
    {
      "name": "Upgrade",
      "description": "Upgrades the solution to the latest version available in the app catalog for the specified site.",
      "parameters": [
        {"name": "solutionId", "type": "string", "description": "ID of the solution to upgrade."},
        {"name": "siteUrl", "type": "string", "description": "URL of the site where the solution is installed."}
      ]
    },
    {
      "name": "Install",
      "description": "Installs the solution from tenant or site collection app catalog to a site.",
      "parameters": [
        {"name": "solutionId", "type": "string", "description": "ID of the solution to install."},
        {"name": "siteUrl", "type": "string", "description": "URL of the site where the solution should be installed."}
      ]
    },
    {
      "name": "Uninstall",
      "description": "Uninstalls the solution from a site.",
      "parameters": [
        {"name": "solutionId", "type": "string", "description": "ID of the solution to uninstall."},
        {"name": "siteUrl", "type": "string", "description": "URL of the site from which the solution should be uninstalled."}
      ]
    }
  ]
}
```

--------------------------------

### m365 spo sitedesign task get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets information about a specified site design task that is scheduled for execution. This helps in monitoring the progress of site provisioning.

```CLI
m365 spo sitedesign task get
```

--------------------------------

### m365 spo sitescript get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets information about the specified site script in SharePoint Online. This command retrieves details of a particular site script.

```CLI
m365 spo sitescript get
```

--------------------------------

### m365 spo list webhook get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets information about a specific webhook configured for a SharePoint list. This command retrieves details for a particular list webhook.

```CLI
m365 spo list webhook get
```

--------------------------------

### m365 spo roledefinition list

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets a list of role definitions for the specified SharePoint site. This command helps in understanding permission levels.

```CLI
m365 spo roledefinition list
```

--------------------------------

### Serve SPFx Client-Side Solution Locally with Gulp

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/tasks.md

This Gulp task starts a local web server to serve the client-side solution project and its assets. It's primarily used for local development and testing without requiring deployment to a SharePoint environment.

```Shell
gulp serve
```

--------------------------------

### m365 spo customaction get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets information about a user custom action for a specified site or site collection. This command retrieves details about existing custom actions.

```CLI
m365 spo customaction get
```

--------------------------------

### m365 spo term set get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Gets information about the specified taxonomy term set in SharePoint. This command helps in managing and understanding managed metadata.

```CLI
m365 spo term set get
```

--------------------------------

### m365 spo cdn get

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

Views the current status of the specified Microsoft 365 CDN. This command provides insights into the content delivery network's configuration.

```CLI
m365 spo cdn get
```

--------------------------------

### Authenticate and Retrieve Microsoft 365 Tenant Details with VS Code Viva

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

This feature allows users to sign in to their Microsoft 365 tenant using CLI for Microsoft 365, supporting both new and existing Entra App Registrations. Upon successful authentication, the extension retrieves essential tenant URLs (SharePoint main, admin, web API permissions) and current tenant service health incidents. It also presents a comprehensive view of tenant and site-level app catalogs, enabling various app management actions like deploy, retract, remove, enable, disable, install, uninstall, and upgrade, along with visibility into tenant-wide extensions.

```APIDOC
Authentication & Tenant Details API:

Methods:
  - signIn(options: {
      useExistingAppRegistration: boolean,
      clientId?: string,
      tenantId?: string
    }): Promise<TenantDetails>

Interfaces:
  interface TenantDetails {
    sharePointMainSiteUrl: string;
    sharePointAdminSiteUrl: string;
    sharePointWebAPIPermissionManagementPageUrl: string;
    tenantServiceHealthIncidents: HealthIncident[];
    appCatalogs: AppCatalog[];
    tenantWideExtensions: Extension[];
  }

  interface AppCatalog {
    type: "tenant" | "site";
    url: string;
    apps: App[];
  }

  interface App {
    id: string;
    name: string;
    actions: {
      deploy(): Promise<void>;
      retract(): Promise<void>;
      remove(): Promise<void>;
      enable(): Promise<void>;
      disable(): Promise<void>;
      install(siteUrl: string): Promise<void>;
      uninstall(siteUrl: string): Promise<void>;
      upgrade(siteUrl: string): Promise<void>;
    }
  }

  interface HealthIncident {
    id: string;
    status: string;
    title: string;
    // ... other incident details
  }

  interface Extension {
    id: string;
    name: string;
    // ... other extension details
  }

Settings:
  - showAppCatalogList: boolean
  - showTenantHealthIncidents: boolean

```

--------------------------------

### Get SharePoint Online Application Customizer

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves information about a specific SharePoint Framework (SPFx) Application Customizer added to a site. It helps in managing client-side extensions. The command requires the URL of the site and the ID of the customizer.

```CLI
m365 spo applicationcustomizer get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/web/UserCustomActions
Description: Gets an application customizer that is added to a site.
Parameters:
  - webUrl (string, required): The URL of the SharePoint web.
  - id (string, required): The ID of the application customizer.
Returns:
  - UserCustomAction: An object representing the application customizer, including 'Id', 'Title', and 'ClientSideComponentId'.
```

--------------------------------

### Get SharePoint Online Tenant App Catalog URL

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves the URL of the tenant-scoped app catalog in SharePoint Online. The app catalog is where custom applications and solutions are deployed. No specific parameters are required.

```CLI
m365 spo tenant appcatalogurl get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/SP_TenantSettings_Site/Current/GetTenantAppCatalogUrl
Description: Gets the URL of the tenant app catalog.
Returns:
  - string: The URL of the tenant app catalog.
```

--------------------------------

### Set SharePoint List Form Customizer with SPFx

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This action updates the New, Edit, or View forms of any SharePoint List. It applies a specified SPFx Form Customizer based on its provided GUID. This allows for custom rendering of list forms.

```APIDOC
Action: Set Form Customizer

Parameters:
- `listId`: string (GUID of the SharePoint List)
- `formCustomizerId`: string (GUID of the SPFx Form Customizer)
- `formType`: 'New' | 'Edit' | 'View'

Purpose: Updates SharePoint List forms with a given SPFx Form Customizer.
```

--------------------------------

### Get SharePoint Online Hide Default Themes Setting

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves the current value of the 'HideDefaultThemes' setting for the SharePoint Online tenant. This setting controls whether default themes are visible to users. No specific parameters are required.

```CLI
m365 spo hidedefaultthemes get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/tenant/GetHideDefaultThemes
Description: Gets the current value of the HideDefaultThemes setting for the tenant.
Returns:
  - boolean: True if default themes are hidden, false otherwise.
```

--------------------------------

### Get SharePoint Online Hub Site Data

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves hub site data for a specified SharePoint site. It provides information about whether a site is a hub site or associated with one. The command requires the URL of the target SharePoint site.

```CLI
m365 spo hubsite data get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/site/GetHubSiteData
Description: Get hub site data for the specified site.
Parameters:
  - webUrl (string, required): The URL of the SharePoint site.
Returns:
  - HubSiteData: An object containing hub site properties like 'IsHubSite', 'HubSiteId', and 'HubSiteUrl'.
```

--------------------------------

### Get SharePoint Online Navigation Node

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves information about a specific navigation node within a SharePoint site's navigation. It can be used to inspect or manage navigation links. The command requires the URL of the site and the ID of the navigation node.

```CLI
m365 spo navigation node get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/web/navigation/{nodeType}/GetById('{nodeId}')
Description: Gets information about a specific navigation node.
Parameters:
  - webUrl (string, required): The URL of the SharePoint web.
  - nodeType (string, required): 'QuickLaunch' or 'TopNavigationBar'.
  - nodeId (string, required): The ID of the navigation node.
Returns:
  - NavigationNode: An object representing the navigation node, including 'Id', 'Title', and 'Url'.
```

--------------------------------

### Get SharePoint Online Site Design Information

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves detailed information about a specified SharePoint site design. Site designs are used to apply a consistent look and feel or configuration to new or existing sites. The command requires the ID of the site design.

```CLI
m365 spo sitedesign get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteDesignMetadata('{siteDesignId}')
Description: Gets information about the specified site design.
Parameters:
  - siteDesignId (string, required): The ID of the site design.
Returns:
  - SiteDesign: An object representing the site design, including 'Id', 'Title', and 'Description'.
```

--------------------------------

### Get SharePoint Online Page Column Information

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves information about a specific column within a modern SharePoint page. Modern pages are composed of sections and columns. The command requires the page URL, section ID, and column ID.

```CLI
m365 spo page column get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/web/GetFileByServerRelativeUrl('{pageUrl}')/ListItemAllFields
Description: Get information about a specific column of a modern page. Requires parsing the 'CanvasContent1' or 'ClientSideApplicationId' field of the page's list item.
Parameters:
  - pageUrl (string, required): Server relative URL of the modern page.
  - sectionId (string, required): The ID of the section containing the column.
  - columnId (string, required): The ID of the column.
Returns:
  - PageColumn: An object representing the page column, including 'Id', 'Order', and 'Width'.
```

--------------------------------

### Get SharePoint Online User Profile Properties

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves SharePoint user profile properties for a specified user. It is useful for accessing detailed information about a user's profile. The command requires the user's account name or email.

```CLI
m365 spo userprofile get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/SP.UserProfiles.PeopleManager/GetPropertiesFor(accountName=@v)?@v='{accountName}'
Description: Get SharePoint user profile properties for the specified user.
Parameters:
  - accountName (string, required): The account name or email of the user.
Returns:
  - UserProfileProperties: An object containing user profile properties like 'DisplayName', 'Email', and 'UserProfileProperties' array.
```

--------------------------------

### Get SharePoint Online File Sharing Link Details

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves detailed information about a specific sharing link for a SharePoint Online file. It is useful for auditing or managing access granted via sharing links. The command requires the file URL and the sharing link ID.

```CLI
m365 spo file sharinglink get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/web/GetFileByServerRelativeUrl('{fileUrl}')/GetSharingLinkById('{linkId}')
Description: Gets details about a specific sharing link of a file.
Parameters:
  - fileUrl (string, required): Server relative URL of the file.
  - linkId (string, required): The ID of the sharing link.
Returns:
  - SharingLink: An object containing sharing link properties like 'Url', 'Type', and 'Expiration'.
```

--------------------------------

### Get SharePoint Online List Item Attachment

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command retrieves a specific attachment from a SharePoint list item. It is useful for accessing files directly associated with list entries. The command requires the list title, item ID, and attachment file name.

```CLI
m365 spo listitem attachment get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/web/lists/GetByTitle('{listTitle}')/items({itemId})/AttachmentFiles/GetByFileName('{fileName}')
Description: Gets an attachment from a list item.
Parameters:
  - listTitle (string, required): The title of the list.
  - itemId (number, required): The ID of the list item.
  - fileName (string, required): The name of the attachment file.
Returns:
  - File: An object representing the attachment file, including 'Name', 'ServerRelativeUrl', and 'Length'.
```

--------------------------------

### Get SharePoint Online Content Type Hub URL

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

This command returns the URL of the SharePoint Content Type Hub for the current tenant. The Content Type Hub is a central location for managing and publishing content types across site collections. No specific parameters are required.

```CLI
m365 spo contenttypehub get [options]
```

```APIDOC
Method: GET
Endpoint: /_api/site/ContentTypeHub
Description: Returns the URL of the SharePoint Content Type Hub of the Tenant.
Returns:
  - string: The URL of the Content Type Hub.
```

--------------------------------

### Deploy SPFx Project to App Catalog with CLI for Microsoft 365

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This action deploys the SPFx project's `.sppkg` file to the selected tenant or site app catalog. It requires the user to be logged into the tenant and the `.sppkg` file to be present. This automates the deployment process.

```APIDOC
CLI for Microsoft 365 Commands:
`spo app add --path <pathToFile> [--scope <scope>]`
`spo app deploy --id <appId> [--skipFeatureDeployment]`

Purpose: Adds an SPFx package to the app catalog and deploys it.
```

--------------------------------

### SharePoint Framework Extensibility Model Overview

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/spfx-intro.md

This documentation outlines the core components and capabilities of the SharePoint Framework (SPFx) extensibility model. It details the types of solutions developers can create, including client-side web parts, various extensions, library components, and Adaptive Card Extensions, along with their primary purposes and features.

```APIDOC
SharePoint Framework (SPFx) Extensibility Model:

  Purpose: Build productive experiences and apps for SharePoint, Microsoft Teams, Microsoft Viva Connections, Outlook, and Microsoft365.com using modern web technologies.

  Key Features:
    - Runs in browser context, no iFrames.
    - Controls rendered in normal page DOM, responsive, and accessible.
    - Developer access to lifecycle (render, load, serialize, deserialize, config changes).
    - Framework-agnostic (React, Handlebars, Knockout, Angular, Vue.js).
    - Toolchain: NPM, TypeScript, Yeoman, webpack, and gulp.
    - Reliable performance.
    - Solutions approved by tenant administrators.
    - Web parts usable on classic and modern pages.
    - Extends Microsoft Teams, Viva Connections, Outlook, and Office 365 app.

  Extensibility Types:

    1. Client-side Web Parts:
       - Description: Controls appearing inside a SharePoint page, executing client-side in the browser. Building blocks of pages. Deployable to modern and classic pages.

    2. Extensions:
       - Description: Extend SharePoint user experience in modern pages and document libraries using SPFx tools.
       - Types:
         a. Application Customizers:
            - Purpose: Add scripts to the page, access and extend HTML element placeholders with custom renderings.
         b. Field Customizers:
            - Purpose: Provide modified views to data for fields within a list.
         c. Command Sets:
            - Purpose: Extend SharePoint command surfaces to add new actions, provide client-side code for behaviors.
         d. Form Customizer:
            - Purpose: Associate and override default new, edit, and view form experiences of lists and libraries with custom forms by associating component to content type.

    3. Library Components:
       - Description: Independently versioned and deployed code served automatically for SPFx components via app catalog. Alternative for shared code across tenant components.

    4. Adaptive Cards Extensions (ACEs):
       - Description: Extend Viva Connections dashboard with custom functionalities and visualizations.
```

--------------------------------

### PnP VSCode Viva CI/CD Pipelines Overview

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/contributing-guidance.mdx

This section details the four continuous integration and deployment pipelines used in the PnP VSCode Viva project. Each pipeline serves a specific purpose, from pre-release and main releases to updating sample data and creating local VSIX packages.

```APIDOC
Pipeline Name: Pre-Release
GitHub Workflow: .github/workflows/release-beta.yml
Branch: dev
Trigger: Manual only
Purpose: Release VSCode extension as a Pre-Release (--pre-release option) for testing and feedback on latest features.
Prerequisites:
  - package.json version increased in patch section (e.g., x.y.1)
```

```APIDOC
Pipeline Name: Main Release
GitHub Workflow: .github/workflows/release.yml
Branch: main
Trigger: Manual or new GitHub release (tag creation)
Purpose: Deliver new major or minor version of the extension.
Prerequisites:
  - package.json version increased in major or minor parts (e.g., 1.1.x)
  - changelog file updated with release details
  - all new features documented in wiki and added to readme file
  - vsce package created for inclusion in release
```

```APIDOC
Pipeline Name: Update samples data
GitHub Workflow: .github/workflows/update-samples.yml
Branch: Any (does not work with source files)
Trigger: Manual or scheduled (once a week on Saturday)
Purpose: Recheck PnP SPFx web parts, extensions, ACE's sample repos; create local JSON files in data folder with sample info. Creates a PR for review and manual merge to main. Used by SharePoint Framework Toolkit for sample gallery views, keeping samples up to date without new extension release.
Prerequisites: None
```

```APIDOC
Pipeline Name: Create .vsix package
GitHub Workflow: .github/workflows/release-local.yml
Branch: Not specified (implies any)
Trigger: Not specified (implies manual or on demand)
Purpose: Create .vsix package for local download from artifacts and testing.
Prerequisites: None
```

--------------------------------

### Azure DevOps Pipeline for SPFx Solution Deployment

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This YAML pipeline defines the steps to build, package, and deploy a SharePoint Framework solution to a SharePoint app catalog. It leverages Node.js, npm, Gulp, and the CLI for Microsoft 365. The pipeline requires variables for authentication (certificate-based Entra app) and SharePoint target URLs.

```YAML
name: Deploy Solution demo-1
trigger:
  branches:
    include:
      - main
pool:
  vmImage: ubuntu-latest
variables:
  - name: CertificateBase64Encoded
    value: ""
  - name: CertificateSecureFileId
    value: ""
  - name: CertificatePassword
    value: ""
  - name: EntraAppId
    value: ""
  - name: TenantId
    value: ""
  - name: SharePointBaseUrl
    value: ""
  - name: PackageName
    value: demo-1.sppkg
  - name: SiteAppCatalogUrl
    value: https://tenanttocheck.sharepoint.com/sites/CLIDemo1/AppCatalog
stages:
  - stage: Build_and_Deploy
    jobs:
      - job: Build_and_Deploy
        steps:
          - task: NodeTool@0
            displayName: Use Node.js
            inputs:
              versionSpec: 18.x
          - task: Npm@1
            displayName: Run npm install
            inputs:
              command: install
          - task: Gulp@0
            displayName: Gulp bundle
            inputs:
              gulpFile: ./gulpfile.js
              targets: bundle
              arguments: --ship
          - task: Gulp@0
            displayName: Gulp package
            inputs:
              targets: package-solution
              arguments: --ship
          - task: Npm@1
            displayName: Install CLI for Microsoft 365
            inputs:
              command: custom
              verbose: false
              customCommand: install -g @pnp/cli-microsoft365
          - script: >
              
              m365 login --authType certificate --certificateBase64Encoded '$(CertificateBase64Encoded)' --password '$(CertificatePassword)' --appId '$(EntraAppId)' --tenant '$(TenantId)' 

              m365 spo set --url '$(SharePointBaseUrl)' 

              m365 spo app add --filePath '$(Build.SourcesDirectory)/sharepoint/solution/$(PackageName)' --appCatalogScope sitecollection --appCatalogUrl '$(SiteAppCatalogUrl)' --overwrite 

              m365 spo app deploy --skipFeatureDeployment --name '$(PackageName)' --appCatalogScope sitecollection --appCatalogUrl '$(SiteAppCatalogUrl)'
            displayName: CLI for Microsoft 365 Deploy App

```

--------------------------------

### GitHub Actions Workflow for SPFx Solution Deployment

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This YAML defines a GitHub Actions workflow to build, package, and deploy an SPFx solution. It triggers on pushes to the 'main' branch or manually, using Node.js 16.x, 'gulp' for bundling, and CLI for Microsoft 365 GitHub Actions for authentication and deployment. Ensure 'CERTIFICATE_ENCODED', 'CERTIFICATE_PASSWORD', and 'TENANT_ID' secrets are configured.

```YAML
name: Deploy Solution test-solution
on:
  push:
    branches:
      - main
  workflow_dispatch: null
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3.5.3
      - name: Use Node.js 16.x
        uses: actions/setup-node@v3.7.0
        with:
          node-version: 16.x
      - name: Run npm ci
        run: npm ci
      - name: Bundle & Package
        run: |
          gulp bundle --ship
          gulp package-solution --ship
      - name: CLI for Microsoft 365 Login
        uses: pnp/action-cli-login@v2.2.2
        with:
          CERTIFICATE_ENCODED: ${{ secrets.CERTIFICATE_ENCODED }}
          CERTIFICATE_PASSWORD: ${{ secrets.CERTIFICATE_PASSWORD }}
          TENANT: ${{ secrets.TENANT_ID }}
      - name: CLI for Microsoft 365 Deploy App
        uses: pnp/action-cli-deploy@v3.0.1
        with:
          APP_FILE_PATH: sharepoint/solution/test-solution.sppkg
          SKIP_FEATURE_DEPLOYMENT: true
          OVERWRITE: true
```

--------------------------------

### GitHub Action: Deploy SPFx App to Site Collection App Catalog

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This configuration snippet for the 'CLI for Microsoft 365 Deploy App' action specifies deployment to a site collection app catalog. It sets the 'SCOPE' to 'sitecollection' and requires 'SITE_COLLECTION_URL' to be provided. This allows targeted deployment of SPFx solutions.

```YAML
SCOPE: sitecollection
SITE_COLLECTION_URL: https://sharepoint.tenant.com/appcatalog
```

--------------------------------

### VS Code Extension Project Structure Overview

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/contributing-guidance.mdx

This snippet illustrates the directory structure of the VS Code extension. It outlines the purpose of key folders like assets, data, scripts, src (containing core logic), syntaxes, and webpack, providing a high-level overview of the project's organization.

```Plaintext
├── assets // Keeps all the graphical files connected to the project (either used in the extension or in docs)
│   └── images // Keeps images used in readme file
├── data // Keeps .json files which store info about all the samples or scenarios of a given PnP sample gallery repo
├── scripts // Keeps all the scripts used for maintenance or in pipelines
├── src 
│   ├── chat // GitHub Copilot participant related files
│   ├── constants // Types, dictionary data, or static strings
│   ├── models // Models/interfaces used as method inputs or outputs
│   ├── panels // Panels are the sections you see in the action pane. Here we decide if we show welcome experience or the SPFx project panels and what is their behavior
│   ├── providers
│   ├── services // Groups functionalities dedicated to a specific feature or service (like Scaffolder)
|   ├── tests
│   ├── utils // Groups all small helper methods
│   ├── webview // Groups all webviews used in this extension 
│   └── extension.ts // Main point of the extension that runs on start and registers all other components
├── syntaxes
├──  webpack
├── .eslintrc.json
├── .vscodeignore
├── postcss.config.js
├── tailwind.config.js
└──  tsconfig.json
```

--------------------------------

### Utilize SPFx Toolkit Language Model Tools in GitHub Copilot Agent Mode

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

SPFx Toolkit Language Model Tools extend GitHub Copilot's capabilities in agent mode, assisting with SharePoint Framework development and SharePoint Online tenant management. These tools enable operations like site management, app catalog interactions, and page creation, either through explicit hashtag mentions or implicit prompt interpretation.

```AI/Copilot Agent
#hashtag mention - Explicitly invoke a tool.
Implicit invocation - GitHub Copilot may automatically use the appropriate tool based on a well-defined prompt.

Example Operations:
- Get information about a specific site
- Create a site
- Remove a site
- List apps from your tenant app catalog
- Install an app
- Create a page
```

--------------------------------

### Reuse SPFx/ACE Samples in VS Code Viva Extension

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

The VS Code Viva extension provides a sample gallery to kick-start development with existing SPFx web parts, extensions, or ACE samples from PnP repositories. Users can filter samples by author, title, SPFx version, and component type, and view details directly within VS Code. This feature simplifies project creation by allowing direct scaffolding from chosen samples.

```Documentation
You may kick-start your development with a new project based on an existing ACE or SPFx web part or extension with a click of a button. All of the provided samples are powered by PnP Samples repositories.

The extension provides a set of filters to help you find the right sample for your needs. You may search by: author, title, description, SPFx version, and component type. It is also possible browse sample details view directly from VS Code checking all sample details before you create a new project.

Switch between the list and grid view and don't worry about the size of your VS Code as it is fully responsive.
```

--------------------------------

### Upgrade SPFx Project with CLI for Microsoft 365

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This action uses CLI for Microsoft 365 to generate upgrade guidance for SPFx projects. It creates a Markdown report and/or a code tour, detailing required and optional steps to upgrade to the latest supported SPFx version. The guidance includes a summary script and manual steps.

```APIDOC
CLI for Microsoft 365 Command:
`spfx project upgrade [options]`

Purpose: Creates upgrade guidance for SPFx projects to the latest supported version.
```

--------------------------------

### Reference SPFx Toolkit Chat Commands for SPFx Development

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

The @spfx AI Copilot offers predefined commands to streamline SharePoint Framework development tasks. These commands provide specific guidance, from setting up your workspace to coding assistance and retrieving tenant information, enhancing developer productivity.

```AI/Copilot Chat
/setup - Provides information on how to set up your local workspace for SharePoint Framework development.
/new - May be used to get guidance on how to create a new solution or find and reuse an existing sample from the PnP SPFx sample gallery.
/code [beta] - Fine-tuned to provide help in coding your SharePoint Framework project and provides additional boosters like validating the correctness of your SPFx project, scaffolding a CI/CD workflow, or renaming your project.
/info - Allows asking and retrieving any kind of data from your SharePoint Online tenant. This command will only work if you are signed in to your tenant. It uses CLI for Microsoft 365 commands under the hood to retrieve and explain data and assets from your SharePoint Online tenant.
```

--------------------------------

### SharePoint App Catalog Management Actions

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/login-tenant.mdx

This section details the available operations for managing SharePoint solutions within the tenant or site-level app catalogs, accessible via the VSCode extension. These actions allow for lifecycle management of SharePoint Framework (SPFx) solutions.

```APIDOC
interface AppCatalogManager {
  /**
   * Makes the solution available for installation in sites but does not automatically install it.
   */
  deploy(): void;

  /**
   * Reverses the deployment, preventing the solution from being installed in sites.
   */
  retract(): void;

  /**
   * Removes the app from the app catalog.
   */
  remove(): void;

  /**
   * Allows end users to add the solution to their SharePoint sites.
   */
  enable(): void;

  /**
   * Hides the solution from end users, preventing them from adding it to sites.
   */
  disable(): void;

  /**
   * Installs the solution from tenant or site collection app catalog to a specified site.
   * @param siteUrl The URL of the site where the solution should be installed.
   */
  install(siteUrl: string): void;

  /**
   * Uninstalls the solution from a specified site.
   * @param siteUrl The URL of the site from which the solution should be uninstalled.
   */
  uninstall(siteUrl: string): void;

  /**
   * Upgrades the solution to the latest version available in the app catalog for the specified site.
   * @param siteUrl The URL of the site where the solution should be upgraded.
   */
  upgrade(siteUrl: string): void;
}
```

--------------------------------

### Authenticate and Retrieve Tenant Environment Details (APIDOC)

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/tenant-details.md

Describes the process of authenticating to a Microsoft 365 tenant using the VS Code extension, including options for Entra App Registration management. It details the parameters for sign-in and the structured data returned, such as SharePoint site URLs and tenant health incidents.

```APIDOC
{
  "operation": "SignInToTenant",
  "description": "Authenticates the user to a Microsoft 365 tenant using an Entra App Registration, optionally creating one.",
  "parameters": [
    {
      "name": "clientId",
      "type": "string",
      "description": "Client ID of an existing Entra App Registration (optional, if creating new)."
    },
    {
      "name": "tenantId",
      "type": "string",
      "description": "Tenant ID of an existing Entra App Registration (optional, if creating new)."
    },
    {
      "name": "createAppRegistration",
      "type": "boolean",
      "description": "Set to true to automatically create a new Entra App Registration if none is provided."
    }
  ],
  "returns": {
    "type": "object",
    "description": "Tenant environment details and health status upon successful sign-in.",
    "properties": {
      "sharePointMainSiteUrl": {"type": "string", "description": "URL to the main SharePoint site."},
      "sharePointAdminSiteUrl": {"type": "string", "description": "URL to the SharePoint admin center."},
      "sharePointWebApiPermissionManagementPageUrl": {"type": "string", "description": "URL to the SharePoint web API permission management page."},
      "tenantServiceHealthIncidents": {"type": "array", "description": "List of current tenant service health incidents."}
    }
  }
}
```

--------------------------------

### Scaffolding Form Configuration for Azure DevOps Pipeline Generation

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This section details the configurable parameters and options available in the scaffolding form used to generate the Azure DevOps YAML pipeline for SPFx deployment. It covers pipeline naming, branch triggers, various authentication methods, and app catalog deployment scopes.

```APIDOC
{
  "form_name": "Azure DevOps Pipeline Scaffolding",
  "description": "Configuration options for generating the Azure DevOps YAML pipeline for SPFx deployment.",
  "steps": [
    {
      "step_number": 1,
      "name": "Pipeline and Branch Configuration",
      "description": "Specify the name of the pipeline and the branch name that will trigger the pipeline on every code push.",
      "parameters": [
        {
          "name": "Pipeline Name",
          "type": "string",
          "description": "The name of the Azure DevOps pipeline."
        },
        {
          "name": "Trigger Branch Name",
          "type": "string",
          "description": "The branch name (e.g., 'main') that will trigger the pipeline on code pushes."
        }
      ]
    },
    {
      "step_number": 2,
      "name": "Authentication Method Selection",
      "description": "Choose the authentication method the pipeline will use to log in to your tenant and deploy the app. Different methods require different variables and scripts in the YAML.",
      "parameters": [
        {
          "name": "Authentication Method",
          "type": "enum",
          "description": "Select how the pipeline will authenticate to Microsoft 365.",
          "options": [
            {
              "value": "User Login",
              "description": "Suitable for testing, but not recommended for production. Does not support multi-factor authentication."
            },
            {
              "value": "Application Login",
              "description": "Ideal for production pipelines. Requires defining Entra application variables (CertificateBase64Encoded, CertificateSecureFileId, CertificatePassword, EntraAppId, TenantId). Recommended to use a dedicated variable group in Azure DevOps Library."
            },
            {
              "value": "Generate Certificate and App Registration",
              "description": "Option to generate a certificate and create a new Entra ID app registration directly within the form. Requires a certificate password and app registration name. The form will create the file and app, providing generated values for pipeline variables."
            }
          ]
        }
      ]
    },
    {
      "step_number": 3,
      "name": "App Catalog Deployment Scope",
      "description": "Specify whether the app will be deployed to a tenant-level or site-level app catalog.",
      "parameters": [
        {
          "name": "Deployment Scope",
          "type": "enum",
          "description": "Choose the target app catalog for deployment.",
          "options": [
            {
              "value": "Tenant App Catalog",
              "description": "Deploy to the tenant-wide app catalog."
            },
            {
              "value": "Site App Catalog",
              "description": "Deploy to a specific site collection app catalog. Requires an additional URL field."
            }
          ]
        },
        {
          "name": "Site App Catalog URL",
          "type": "string",
          "description": "Required if 'Site App Catalog' is selected. The URL of the site collection app catalog (e.g., https://tenant.sharepoint.com/sites/MySite/AppCatalog).",
          "required_if": {"Deployment Scope": "Site App Catalog"}
        }
      ]
    }
  ]
}
```

--------------------------------

### Enhance SPFx Project Development with /code (Beta) Command

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/guides/ai-capabilities.mdx

The `/code` command, currently in beta, is fine-tuned to provide advanced assistance for coding SharePoint Framework projects. It offers boosters like validating project correctness, scaffolding CI/CD workflows, and renaming projects, among other functionalities.

```GitHub Copilot Chat
/code
```

--------------------------------

### Configure SPFx Toolkit as GitHub Copilot Chat Participant

Source: https://github.com/pnp/vscode-viva/blob/main/README.md

To leverage SPFx Toolkit as an AI assistant within GitHub Copilot chat, simply mention @spfx in your chat. This activates a dedicated Copilot fine-tuned for SharePoint Framework development, providing tailored guidance and support.

```AI/Copilot Chat
@spfx
```

--------------------------------

### Grant SPFx Project API Permissions with CLI for Microsoft 365

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This action grants all API permissions specified in the project's `package-solution.json` file. It streamlines the debugging process by eliminating the need to bundle, package, deploy, and manually consent permissions in the SharePoint admin portal, allowing for quick workbench debugging.

```APIDOC
CLI for Microsoft 365 Command:
`spfx project permissions grant [options]`

Purpose: Grants API permissions specified in package-solution.json for debugging.
```

--------------------------------

### GitHub Action: CLI for Microsoft 365 Application Login Step

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This snippet demonstrates the application-based authentication step for the CLI for Microsoft 365 GitHub Action. It uses encoded certificate and tenant ID secrets for secure, non-interactive login, suitable for production environments. Required secrets include 'CERTIFICATE_ENCODED', 'CERTIFICATE_PASSWORD', 'APP_ID', and 'TENANT_ID'.

```YAML
- name: CLI for Microsoft 365 Login
        uses: pnp/action-cli-login@v2.2.2
        with:
          CERTIFICATE_ENCODED: ${{ secrets.CERTIFICATE_ENCODED }}
          CERTIFICATE_PASSWORD: ${{ secrets.CERTIFICATE_PASSWORD }}
          APP_ID: ${{ secrets.APP_ID }}
          TENANT: ${{ secrets.TENANT_ID }}
```

--------------------------------

### GitHub Action: CLI for Microsoft 365 User Login Step

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This snippet illustrates the user-based authentication step for the CLI for Microsoft 365 GitHub Action. It requires 'ADMIN_USERNAME' and 'ADMIN_PASSWORD' secrets. This method is primarily for testing and does not support accounts with Multi-Factor Authentication (MFA) enabled.

```YAML
- name: CLI for Microsoft 365 Login
        uses: pnp/action-cli-login@v2.2.2
        with:
          ADMIN_USERNAME: ${{ secrets.ADMIN_USERNAME }}
          ADMIN_PASSWORD: ${{ secrets.ADMIN_PASSWORD }}
```

--------------------------------

### Bundle SPFx Client-Side Solution with Gulp

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/tasks.md

This Gulp task aggregates the client-side solution's entry point and all its dependencies into a single JavaScript file. It optimizes the solution for deployment by reducing the number of requests and improving load times.

```Shell
gulp bundle
```

--------------------------------

### Add New SPFx Component to Existing Project

Source: https://github.com/pnp/vscode-viva/blob/main/docs/src/content/docs/features/actions.mdx

This action allows scaffolding a new SPFx project as a component within the currently open project. It abstracts the SharePoint Yeoman generator's UI, asking for the same information to extend the existing project with a new SPFx component.

```APIDOC
Underlying Tool: SharePoint Yeoman Generator
`yo @microsoft/sharepoint`

Purpose: Scaffolds new SPFx components within an existing project.
```

--------------------------------

### Build SPFx Client-Side Solution with Gulp

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/tasks.md

This Gulp task compiles the client-side solution project, transforming source code into deployable artifacts. It's essential for preparing the project for bundling and packaging by generating the necessary output files.

```Shell
gulp build
```

--------------------------------

### Package SPFx Client-Side Solution for SharePoint with Gulp

Source: https://github.com/pnp/vscode-viva/blob/main/assets/walkthrough/tasks.md

This Gulp task packages the client-side solution into a SharePoint package (.sppkg file). This package is then uploaded to the SharePoint App Catalog for deployment and distribution within SharePoint.

```Shell
gulp package-solution
```