@adrifer/winix 0.3.0-preview.6 → 0.3.0-preview.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -960,6 +960,41 @@ as `.lnk.bak` and refuses backup collisions, while `force: true` opts into
960
960
  replacement without a backup. A new shortcut is staged and verified before
961
961
  replacing the old one. Keep names unique per host.
962
962
 
963
+ ### Windows npm registries
964
+
965
+ Configure npm's current-user default and scoped registries independently from
966
+ PowerShell repositories:
967
+
968
+ ```ts
969
+ windows.npm.registries({
970
+ registries: {
971
+ npmjs: { uri: "https://registry.npmjs.org/" },
972
+ work: { uri: "https://packages.example.com/npm/" },
973
+ },
974
+ default: "work",
975
+ scopes: { "@my-company": "work", "@adrifer": "npmjs" },
976
+ });
977
+ ```
978
+
979
+ The host's merged policy emits one idempotent DSC resource managing only
980
+ `registry` and the declared `@scope:registry` entries in the current user's
981
+ `.npmrc` (or absolute `NPM_CONFIG_USERCONFIG` when set during activation).
982
+ Existing authentication, comments and unrelated scopes/options are preserved.
983
+ Managed keys are explicitly replaced; symlinked userconfigs and concurrent
984
+ edits fail rather than overwriting their targets. Removing declarations leaves
985
+ their previous settings in place; cleanup is not tracked.
986
+
987
+ Registries require HTTPS URLs without embedded credentials, queries or
988
+ fragments. Authentication stays external (for example `npm login` or existing
989
+ environment-token references); Winix never logs or declares tokens. npm itself
990
+ need not be installed to generate or apply this file resource.
991
+
992
+ Unlike PowerShell module policy, this does not enforce an `allowed` list:
993
+ project `.npmrc`, environment variables and npm command-line options can
994
+ override user settings, and package locks may contain independent download
995
+ URLs. It does not redirect Winix bootstrap/SDK downloads, WSL setup npm, or
996
+ install packages. `check`/`apply --dry` do not modify the userconfig.
997
+
963
998
  ### Windows personalization and fonts
964
999
 
965
1000
  These helpers manage the current Windows user without requiring elevation:
@@ -37,6 +37,8 @@ import { windowsSourcePath } from "./paths.js";
37
37
  import { optionalFeatureProperties, wslDistroProperties } from "./wsl.js";
38
38
  import { fontsProperties } from "./fonts.js";
39
39
  import { wallpaperProperties } from "./personalization.js";
40
+ import { npmRegistryProperties } from "./npm.js";
41
+ import { npmRegistryEntries } from "../../helpers/windows-npm.js";
40
42
  export { isWindowsHost } from "./host.js";
41
43
  const DSC_SCHEMA = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json";
42
44
  const WINGET_PACKAGE_TYPE = "Microsoft.WinGet/Package";
@@ -85,7 +87,12 @@ function generateConfiguration(hostName, win, lock, configDir) {
85
87
  const developerModeRefs = (win.dsc ?? [])
86
88
  .filter((resource) => resource.winix?.kind === "setting" && resource.properties?.DeveloperMode === true)
87
89
  .map((resource) => ({ kind: "dsc", token: resource.token }));
88
- const resources = (win.dsc ?? []).map((resource) => {
90
+ const npmResource = win.npm?.registries ? [{
91
+ resourceType: "Microsoft.DSC.Transitional/PowerShellScript",
92
+ name: "npm registries",
93
+ properties: npmRegistryProperties(npmRegistryEntries(win.npm.registries)),
94
+ }] : [];
95
+ const resources = [...(win.dsc ?? []), ...npmResource].map((resource) => {
89
96
  const metadata = resource.winix;
90
97
  if (metadata?.kind === "fonts") {
91
98
  return cloneDscResource(resource, fontsProperties(metadata.sources, lock, configDir));
@@ -0,0 +1,2 @@
1
+ import type { WinDscProperties } from "../../types/windows.js";
2
+ export declare function npmRegistryProperties(entries: Record<string, string>): WinDscProperties;
@@ -0,0 +1,60 @@
1
+ import { powerShellLiteral } from "../../helpers/utils.js";
2
+ export function npmRegistryProperties(entries) {
3
+ const prelude = `
4
+ $ErrorActionPreference = 'Stop'
5
+ $entries = ConvertFrom-Json -AsHashtable ${powerShellLiteral(JSON.stringify(entries))}
6
+ $path = if ($env:NPM_CONFIG_USERCONFIG) {
7
+ [Environment]::ExpandEnvironmentVariables($env:NPM_CONFIG_USERCONFIG)
8
+ } else { Join-Path ([Environment]::GetFolderPath('UserProfile')) '.npmrc' }
9
+ if (-not [IO.Path]::IsPathFullyQualified($path)) { throw 'npm userconfig must be an absolute path' }
10
+ if (Test-Path -LiteralPath $path) {
11
+ if ((Get-Item -LiteralPath $path -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) {
12
+ throw 'npm userconfig is a symlink; configure its source file explicitly instead'
13
+ }
14
+ }
15
+ function Read-WinixNpmConfig {
16
+ if (-not (Test-Path -LiteralPath $path)) { return '' }
17
+ return [IO.File]::ReadAllText($path, [Text.UTF8Encoding]::new($false, $true))
18
+ }
19
+ function Get-WinixNpmKey([string]$line) {
20
+ if ($line -match '^\\s*([^#;=\\s]+)\\s*=') { return $Matches[1] }
21
+ return ''
22
+ }
23
+ function Test-WinixNpmConfig([string]$text) {
24
+ foreach ($key in $entries.Keys) {
25
+ $matching = @($text -split '\\r?\\n' | Where-Object { (Get-WinixNpmKey $_) -ceq $key })
26
+ if ($matching.Count -ne 1) { return $false }
27
+ if (($matching[0] -split '=', 2)[1].Trim() -cne $entries[$key]) { return $false }
28
+ }
29
+ return $true
30
+ }`;
31
+ return {
32
+ getScript: `${prelude}\n@{ InDesiredState = (Test-WinixNpmConfig (Read-WinixNpmConfig)) }`,
33
+ testScript: `${prelude}\nTest-WinixNpmConfig (Read-WinixNpmConfig)`,
34
+ setScript: `${prelude}
35
+ $original = Read-WinixNpmConfig
36
+ if (Test-WinixNpmConfig $original) { return }
37
+ $newline = if ($original.Contains("\`r\`n")) { "\`r\`n" } else { "\`n" }
38
+ $lines = [Collections.Generic.List[string]]::new()
39
+ foreach ($line in ($original -split '\\r?\\n')) {
40
+ if (-not $entries.ContainsKey((Get-WinixNpmKey $line))) { $lines.Add($line) }
41
+ }
42
+ if ($lines.Count -gt 0 -and $lines[$lines.Count - 1] -eq '') { $lines.RemoveAt($lines.Count - 1) }
43
+ foreach ($key in ($entries.Keys | Sort-Object)) { $lines.Add("$key=$($entries[$key])") }
44
+ $next = ($lines -join $newline) + $newline
45
+ $parent = [IO.Path]::GetDirectoryName($path)
46
+ [IO.Directory]::CreateDirectory($parent) | Out-Null
47
+ $temporary = Join-Path $parent ('.winix-npm-' + [guid]::NewGuid().ToString() + '.tmp')
48
+ try {
49
+ [IO.File]::WriteAllText($temporary, $next, [Text.UTF8Encoding]::new($false))
50
+ if ((Read-WinixNpmConfig) -cne $original) { throw 'npm userconfig changed during activation; rerun' }
51
+ if (Test-Path -LiteralPath $path) {
52
+ if ((Get-Item -LiteralPath $path -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'npm userconfig became a link' }
53
+ [IO.File]::Replace($temporary, $path, [NullString]::Value)
54
+ } else { [IO.File]::Move($temporary, $path, $false) }
55
+ } finally {
56
+ if (Test-Path -LiteralPath $temporary) { Remove-Item -LiteralPath $temporary -Force }
57
+ }
58
+ if (-not (Test-WinixNpmConfig (Read-WinixNpmConfig))) { throw 'npm registry configuration verification failed' }`,
59
+ };
60
+ }
@@ -0,0 +1,3 @@
1
+ import type { WinNpmRegistryPolicy } from "../types/windows.js";
2
+ export declare function npmRegistryUri(value: string): string;
3
+ export declare function npmRegistryEntries(policy: WinNpmRegistryPolicy): Record<string, string>;
@@ -0,0 +1,52 @@
1
+ export function npmRegistryUri(value) {
2
+ let url;
3
+ try {
4
+ url = new URL(value);
5
+ }
6
+ catch {
7
+ throw new Error("npm registry URI must be an HTTPS URL");
8
+ }
9
+ if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash ||
10
+ /[\0\r\n]/.test(value)) {
11
+ throw new Error("npm registry URI must be HTTPS without credentials, query or fragment");
12
+ }
13
+ return url.href.replace(/\/+$/, "") + "/";
14
+ }
15
+ export function npmRegistryEntries(policy) {
16
+ if (!policy || typeof policy !== "object" || Array.isArray(policy) ||
17
+ !policy.registries || typeof policy.registries !== "object" || Array.isArray(policy.registries) ||
18
+ typeof policy.default !== "string") {
19
+ throw new Error("npm registry policy requires registries and a default registry name");
20
+ }
21
+ for (const key of Object.keys(policy)) {
22
+ if (!["registries", "default", "scopes"].includes(key))
23
+ throw new Error(`Unknown npm registry policy option: ${key}`);
24
+ }
25
+ const registries = new Map();
26
+ for (const [name, entry] of Object.entries(policy.registries)) {
27
+ if (!/^[a-z0-9][a-z0-9._-]*$/i.test(name) || registries.has(name.toLowerCase())) {
28
+ throw new Error(`Invalid or duplicate npm registry name: ${name}`);
29
+ }
30
+ if (!entry || typeof entry.uri !== "string")
31
+ throw new Error(`npm registry "${name}" requires a URI`);
32
+ registries.set(name.toLowerCase(), npmRegistryUri(entry.uri));
33
+ }
34
+ const resolve = (name) => {
35
+ const uri = typeof name === "string" ? registries.get(name.toLowerCase()) : undefined;
36
+ if (!uri)
37
+ throw new Error(`npm registry "${String(name)}" is not declared`);
38
+ return uri;
39
+ };
40
+ const entries = { registry: resolve(policy.default) };
41
+ if (policy.scopes !== undefined) {
42
+ if (!policy.scopes || typeof policy.scopes !== "object" || Array.isArray(policy.scopes)) {
43
+ throw new Error("npm registry scopes must be an object");
44
+ }
45
+ for (const [scope, registry] of Object.entries(policy.scopes)) {
46
+ if (!/^@[a-z0-9][a-z0-9._-]*$/.test(scope))
47
+ throw new Error(`Invalid npm scope: ${scope}`);
48
+ entries[`${scope}:registry`] = resolve(registry);
49
+ }
50
+ }
51
+ return entries;
52
+ }
@@ -1,5 +1,6 @@
1
1
  import type { Fragment, ResourceHandle } from "../core/types.js";
2
2
  import type { WinDscProperties, WinDscResource, WinPackageSource, WinSettings, WinFilePath, WinKnownFolder, WinKnownFolderName, WinStartupCommand, WinWslConfig, WinWslDistro, WinWslSetup, WinPowerShellRepositoryPolicy, WinFontSource, WinWallpaper, WinPersonalization } from "../types/index.js";
3
+ import type { WinNpmRegistryPolicy } from "../types/windows.js";
3
4
  /**
4
5
  * Accepted call shapes for `windows.package(...)`.
5
6
  *
@@ -116,6 +117,9 @@ export interface WinFileNamespace {
116
117
  remove(target: WinFilePath, opts?: WinFileOpts): ResourceHandle;
117
118
  }
118
119
  export interface WindowsHelper {
120
+ npm: {
121
+ registries(policy: WinNpmRegistryPolicy): Fragment;
122
+ };
119
123
  fonts(spec: {
120
124
  sources: WinFontSource[];
121
125
  dependsOn?: ResourceHandle | ResourceHandle[];
@@ -9,6 +9,7 @@ import { powerShellLiteral as psSingleQuoted } from "./utils.js";
9
9
  import { validatePowerShellRepositoryPolicy } from "./windows-repositories.js";
10
10
  import { validateFontSources, validateWallpaper, personalizationValues } from "./windows-personalization.js";
11
11
  import { personalizationProperties } from "../backends/windows/personalization.js";
12
+ import { npmRegistryEntries } from "./windows-npm.js";
12
13
  const KNOWN_FOLDERS = {
13
14
  documents: "MyDocuments",
14
15
  desktop: "Desktop",
@@ -1054,6 +1055,12 @@ export const windows = {
1054
1055
  return dscHandle(resource);
1055
1056
  },
1056
1057
  },
1058
+ npm: {
1059
+ registries: (policy) => {
1060
+ npmRegistryEntries(policy);
1061
+ return { windows: { npm: { registries: policy } } };
1062
+ },
1063
+ },
1057
1064
  package: (arg) => {
1058
1065
  const pkg = normalizePackage(arg);
1059
1066
  const fragment = { windows: { packages: { [pkg.id]: pkg } } };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export type { Fragment, ResourceHandle, FragmentFactory, PlatformFactory, ProfileFactory, LazyFragment, PlatformLazyFragment, FragmentEntry, FragmentResult, NixExpr, RawModuleRef, ImportRef, InputDef, InputWithOptions, WorkspaceDef, HostDef, EvalContext } from "./core/types.js";
2
- export type { Attrs, BootOptions, DarwinNetworking, DarwinOptions, DarwinSecurity, DarwinDefaults, DarwinSystem, EnvironmentOptions, FirewallOptions, FontsOptions, FzfOptions, GitInclude, GitOptions, HomeActivation, HomebrewOptions, HomeConfig, HomeFile, HomeOptions, I18nOptions, LaunchdAgentOptions, LaunchdOptions, NeovimOptions, NetworkingOptions, NixConfig, NixGcOptions, NixHomebrewOptions, NixOptions, NixpkgsOptions, NixosSecurityOptions, NixosSystemOptions, NixPrimitive, NixSettings, NixValue, NixosOptions, OciContainerOptions, PackageRef, Script, ServicesOptions, StarshipOptions, SystemdOptions, SystemdService, SystemdTimer, TimeOptions, TmuxOptions, UserOptions, UsersOptions, VirtualisationOptions, WslOptions, XdgFile, XdgOptions, ZoxideOptions, ZshOptions, WindowsOptions, WinPackage, WinPackageSource, WinRawCommand, WinSettings, WinFontSource, WinWallpaper, WinPersonalization, WinColorMode, WinStartFolder, WinTaskbarAlignment, WinTaskbarGroupingMode, WinTaskbarMultiMonMode, WinKnownFolder, WinKnownFolderName, WinFilePath, WinPowerShellModule, WinPowerShellRepositoryPolicy, WinStartupCommand, WinStartupWindowStyle, } from "./types/index.js";
2
+ export type { Attrs, BootOptions, DarwinNetworking, DarwinOptions, DarwinSecurity, DarwinDefaults, DarwinSystem, EnvironmentOptions, FirewallOptions, FontsOptions, FzfOptions, GitInclude, GitOptions, HomeActivation, HomebrewOptions, HomeConfig, HomeFile, HomeOptions, I18nOptions, LaunchdAgentOptions, LaunchdOptions, NeovimOptions, NetworkingOptions, NixConfig, NixGcOptions, NixHomebrewOptions, NixOptions, NixpkgsOptions, NixosSecurityOptions, NixosSystemOptions, NixPrimitive, NixSettings, NixValue, NixosOptions, OciContainerOptions, PackageRef, Script, ServicesOptions, StarshipOptions, SystemdOptions, SystemdService, SystemdTimer, TimeOptions, TmuxOptions, UserOptions, UsersOptions, VirtualisationOptions, WslOptions, XdgFile, XdgOptions, ZoxideOptions, ZshOptions, WindowsOptions, WinPackage, WinPackageSource, WinRawCommand, WinSettings, WinFontSource, WinWallpaper, WinPersonalization, WinColorMode, WinStartFolder, WinTaskbarAlignment, WinTaskbarGroupingMode, WinTaskbarMultiMonMode, WinKnownFolder, WinKnownFolderName, WinFilePath, WinPowerShellModule, WinPowerShellRepositoryPolicy, WinNpmRegistryPolicy, WinStartupCommand, WinStartupWindowStyle, } from "./types/index.js";
3
3
  export { platform, feature, profile, host, workspace, input, defineInputs, rawModule, withContext } from "./sdk/index.js";
4
4
  export type { WinixContext } from "./sdk/context.js";
5
5
  export { evaluate } from "./evaluator/index.js";
package/dist/skill.js CHANGED
@@ -257,6 +257,17 @@ Available helpers:
257
257
  Windows hosts generate a DSC v3 configuration for \`winget configure\`.
258
258
  Resources return handles that can be passed through \`dependsOn\`.
259
259
 
260
+ - \`windows.npm.registries({ registries: { work: {
261
+ uri: "https://packages.example.com/npm/" } }, default: "work",
262
+ scopes: { "@company": "work" } })\` configures current-user npm default/scoped
263
+ registries after host merging. HTTPS only, no credentials/query/fragments.
264
+ Manages only registry and declared @scope:registry keys in .npmrc or absolute
265
+ NPM_CONFIG_USERCONFIG; preserves auth/comments/unrelated settings, rejects
266
+ symlinked files and concurrent edits. Removing declarations doesn't clean up.
267
+ No npm installation, token management or package installation. No allowed-list
268
+ enforcement: project config/env/CLI can override it. Does not alter Winix
269
+ SDK/bootstrap downloads or Linux WSL setup. Dry generation never writes .npmrc.
270
+
260
271
  - \`windows.wallpaper({ source: "../wallpapers/desktop.jpg", style: "Fill" })\`
261
272
  manages the current-user desktop image; source is a local/config-relative or
262
273
  known-folder path. Styles: Fill, Fit, Stretch, Tile, Center, Span. Source
@@ -61,6 +61,14 @@ export interface WinPowerShellRepositoryPolicy {
61
61
  /** When specified, reject other repositories instead of falling back. */
62
62
  allowed?: string[];
63
63
  }
64
+ export interface WinNpmRegistryPolicy {
65
+ registries: Record<string, {
66
+ uri: string;
67
+ }>;
68
+ default: string;
69
+ /** npm scope (including @) mapped to a declared registry name. */
70
+ scopes?: Record<string, string>;
71
+ }
64
72
  export interface WinWslDistro {
65
73
  name: string;
66
74
  source: "nixos-wsl";
@@ -310,6 +318,9 @@ export type WinDscProperties = {
310
318
  * order controls apply order.
311
319
  */
312
320
  export interface WindowsOptions extends Record<string, unknown> {
321
+ npm?: {
322
+ registries?: WinNpmRegistryPolicy;
323
+ };
313
324
  powershell?: {
314
325
  repositories?: WinPowerShellRepositoryPolicy;
315
326
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adrifer/winix",
3
- "version": "0.3.0-preview.6",
3
+ "version": "0.3.0-preview.8",
4
4
  "description": "TypeScript-first system configuration for NixOS, nix-darwin, and Home Manager",
5
5
  "license": "MIT",
6
6
  "author": "Adrian Fernandez",