feat(windows): capabilities

[regnete]

This pull request adresses issue #9436.

It adds the optional config property capabilities to AppxOptions. Docs, schema and template are modified according to that.

Should be easy to take this over into the next release.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e0b77de

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[mmaietta]

Please also generate a changeset for the CHANGELOG and CI/CD to pick it up. You can use pnpm generate-changeset for CLI

[mmaietta]

Is this backwards compatible?

[regnete]

Backward compatible to what?

I could possibly implement a routine that adds the namespace declarations when needed by a capability. Would that be acceptable?

Idea: new replacement token ${namespaces} for manifest parsing

<Package
   xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
   xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
   xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
   xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
   ${namespaces} >

[mmaietta]

Backward compatible to what?

My apologies. Is there any side effects in adding each new line of xmlns to the manifest? (I'm not familiar with appx tbh)

[mmaietta]

This seems wildly overcomplicated/over-engineered to me. Instead of classes for each object that only are using super. Why not just use a Map<CompatibilityType, string>?

Here's the rewritten code of what I'm thinking is more optimized and it dramatically reduces the number of classes/super being used.

export interface Capability {
  readonly nsAlias: string | null;
  readonly nsURI: string | null;
  readonly name: string;
  toXMLString(): string;
}

type CapabilityConfig = {
  nsAlias: string | null;
  nsURI: string | null;
  elementName: string;
};

class AppxCapability implements Capability {
  constructor(
    public readonly nsAlias: string | null,
    public readonly nsURI: string | null,
    private readonly elementName: string,
    public readonly name: string
  ) {}

  toXMLString(): string {
    const tagName = this.nsAlias ? `${this.nsAlias}:${this.elementName}` : this.elementName;
    return `<${tagName} Name="${this.name}"/>`;
  }
}

// Capability type configurations
const CAPABILITY_TYPES = {
  common: {
    nsAlias: null,
    nsURI: "http://schemas.microsoft.com/appx/manifest/foundation/windows10",
    elementName: "Capability",
  },
  device: {
    nsAlias: null,
    nsURI: "http://schemas.microsoft.com/appx/manifest/foundation/windows10",
    elementName: "DeviceCapability",
  },
  uap: {
    nsAlias: "uap",
    nsURI: "http://schemas.microsoft.com/appx/manifest/uap/windows10",
    elementName: "Capability",
  },
  uap6: {
    nsAlias: "uap6",
    nsURI: "http://schemas.microsoft.com/appx/manifest/uap/windows10/6",
    elementName: "Capability",
  },
  uap7: {
    nsAlias: "uap7",
    nsURI: "http://schemas.microsoft.com/appx/manifest/uap/windows10/7",
    elementName: "Capability",
  },
  uap11: {
    nsAlias: "uap11",
    nsURI: "http://schemas.microsoft.com/appx/manifest/uap/windows10/11",
    elementName: "Capability",
  },
  mobile: {
    nsAlias: "mobile",
    nsURI: "http://schemas.microsoft.com/appx/manifest/mobile/windows10",
    elementName: "Capability",
  },
  rescap: {
    nsAlias: "rescap",
    nsURI: "http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities",
    elementName: "Capability",
  },
} as const;

type CapabilityType = keyof typeof CAPABILITY_TYPES;

// Map of capability types to their capability names (grouped by type)
const CAPABILITY_MAP = new Map<CapabilityType, string[]>([
  // Common capabilities
  ["common", [
    "internetClient",
    "internetClientServer",
    "privateNetworkClientServer",
    "codeGeneration",
    "allJoyn",
    "backgroundMediaPlayback",
    "remoteSystem",
    "spatialPerception",
    "userDataTasks",
    "userNotificationListener",
  ]],

  // UAP capabilities
  ["uap", [
    "musicLibrary",
    "picturesLibrary",
    "videosLibrary",
    "removableStorage",
    "appointments",
    "contacts",
    "phoneCall",
    "phoneCallHistoryPublic",
    "userAccountInformation",
    "voipCall",
    "objects3D",
    "chat",
    "blockedChatMessages",
    "enterpriseAuthentication",
    "sharedUserCertificates",
    "documentsLibrary",
  ]],

  // Device capabilities
  ["device", [
    "location",
    "microphone",
    "webcam",
    "proximity",
    "pointOfService",
    "wiFiControl",
    "radios",
    "optical",
    "activity",
    "humanPresence",
    "serialcommunication",
    "gazeInput",
    "lowLevel",
    "packageQuery",
  ]],

  // Mobile capabilities
  ["mobile", [
    "recordedCallsFolder",
  ]],

  // Restricted capabilities
  ["rescap", [
    "enterpriseDataPolicy",
    "appCaptureSettings",
    "cellularDeviceControl",
    "cellularDeviceIdentity",
    "cellularMessaging",
    "deviceUnlock",
    "dualSimTiles",
    "enterpriseDeviceLockdown",
    "inputInjectionBrokered",
    "inputObservation",
    "inputSuppression",
    "networkingVpnProvider",
    "packageManagement",
    "screenDuplication",
    "userPrincipalName",
    "walletSystem",
    "locationHistory",
    "confirmAppClose",
    "phoneCallHistory",
    "appointmentsSystem",
    "chatSystem",
    "contactsSystem",
    "email",
    "emailSystem",
    "phoneCallHistorySystem",
    "smsSend",
    "userDataSystem",
    "previewStore",
    "firstSignInSettings",
    "teamEditionExperience",
    "remotePassportAuthentication",
    "previewUiComposition",
    "secureAssessment",
    "networkConnectionManagerProvisioning",
    "networkDataPlanProvisioning",
    "slapiQueryLicenseValue",
    "extendedBackgroundTaskTime",
    "extendedExecutionBackgroundAudio",
    "extendedExecutionCritical",
    "extendedExecutionUnconstrained",
    "deviceManagementDmAccount",
    "deviceManagementFoundation",
    "deviceManagementWapSecurityPolicies",
    "deviceManagementEmailAccount",
    "packagePolicySystem",
    "gameList",
    "xboxAccessoryManagement",
    "cortanaSpeechAccessory",
    "accessoryManager",
    "interopServices",
    "inputForegroundObservation",
    "oemDeployment",
    "oemPublicDirectory",
    "appLicensing",
    "locationSystem",
    "userDataAccountsProvider",
    "previewPenWorkspace",
    "secondaryAuthenticationFactor",
    "storeLicenseManagement",
    "userSystemId",
    "targetedContent",
    "uiAutomation",
    "gameBarServices",
    "appCaptureServices",
    "appBroadcastServices",
    "audioDeviceConfiguration",
    "backgroundMediaRecording",
    "previewInkWorkspace",
    "startScreenManagement",
    "cortanaPermissions",
    "allAppMods",
    "expandedResources",
    "protectedApp",
    "gameMonitor",
    "appDiagnostics",
    "devicePortalProvider",
    "enterpriseCloudSSO",
    "backgroundVoIP",
    "oneProcessVoIP",
    "developmentModeNetwork",
    "broadFileSystemAccess",
    "smbios",
    "runFullTrust",
    "allowElevation",
    "teamEditionDeviceCredential",
    "teamEditionView",
    "cameraProcessingExtension",
    "networkDataUsageManagement",
    "phoneLineTransportManagement",
    "unvirtualizedResources",
    "modifiableApp",
    "packageWriteRedirectionCompatibilityShim",
    "customInstallActions",
    "packagedServices",
    "localSystemServices",
    "backgroundSpatialPerception",
    "uiAccess",
  ]],

  // UAP6 capabilities
  ["uap6", [
    "graphicsCapture",
  ]],

  // UAP7 capabilities
  ["uap7", [
    "globalMediaControl",
  ]],

  // UAP11 capabilities
  ["uap11", [
    "graphicsCaptureWithoutBorder",
    "graphicsCaptureProgrammatic",
  ]],
]);

// Factory function to create capabilities
function createCapability(type: CapabilityType, name: string): Capability {
  const config = CAPABILITY_TYPES[type];
  return new AppxCapability(config.nsAlias, config.nsURI, config.elementName, name);
}

// Export ordered list of all capabilities (order matters per Microsoft docs)
export const CAPABILITIES: Capability[] = Array.from(CAPABILITY_MAP.entries()).flatMap(
  ([type, names]) => names.map(name => createCapability(type, name))
);

[regnete]

Great. Sorry for the complex code I suggested. I had several iterations and ended up with that construct. Your approach is much cleaner.

[mmaietta]

This isn't an optimized flow and can be simplified / made more performant.

export function getCapabilitiesXML(): string {
  const caps = asArray(this.options.capabilities) 
  
  // Ensure runFullTrust is always included
  const capSet = new Set(caps);
  capSet.add("runFullTrust");
  
  // Filter and map in one pass
  const capabilityStrings = CAPABILITIES
    .filter(cap => capSet.has(cap.name))
    .map(cap => `  ${cap.toXMLString()}`);
  
  return `<Capabilities>\n${capabilityStrings.join('\n')}\n</Capabilities>`;
}

Key optimizations:

• Set instead of array - capSet.has(cap.name) is O(1) vs caps.indexOf(cap.name) which is O(n)
• Single pass - Combined filter and map with chaining instead of building string in loop
• Template literal - Cleaner string construction with join()
• Flexible input - Handles both string array and single string (matching asArray pattern)
• Immutable - Doesn't modify input array, creates new Set

[regnete]

I just used the code from getExtensions and modified it a little. Didn't want to break any coding conventions. But your aproach is of course much better.

[mmaietta]

Looks like pnpm generate-all needs to be run again.

[regnete]

Soryy, didn't think about that.

[regnete]

Thanks for the quick response to this pr. I will continue to work on this in the next week.