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

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.
@@ -0,0 +1,140 @@
1
+ export function fontHttpsUrl(value) {
2
+ let url;
3
+ try {
4
+ url = new URL(value);
5
+ }
6
+ catch {
7
+ throw new Error("Font source must be an absolute HTTPS URL");
8
+ }
9
+ if (url.protocol !== "https:" || url.username || url.password || url.hash) {
10
+ throw new Error("Font sources require HTTPS without credentials or fragments");
11
+ }
12
+ return url.href;
13
+ }
14
+ export function validateFontSources(sources) {
15
+ if (!Array.isArray(sources) || sources.length === 0)
16
+ throw new Error("windows.fonts requires nonempty sources");
17
+ for (const source of sources) {
18
+ if (typeof source === "string") {
19
+ if (!source.trim() || /[\0\r\n]/.test(source) || !/\.(ttf|otf)$/i.test(source) || /^https?:/i.test(source)) {
20
+ throw new Error("Local font sources must be TTF/OTF file paths; use { url } for downloads");
21
+ }
22
+ }
23
+ else if (source && typeof source === "object" && "url" in source) {
24
+ fontHttpsUrl(source.url);
25
+ if (source.sha256 !== undefined && !/^[a-f0-9]{64}$/i.test(source.sha256)) {
26
+ throw new Error("Font sha256 must contain 64 hexadecimal characters");
27
+ }
28
+ if (source.files !== undefined && (!Array.isArray(source.files) || source.files.length === 0 ||
29
+ source.files.some((file) => typeof file !== "string" ||
30
+ (!/^\*\*\/\*\.(ttf|otf)$/i.test(file) &&
31
+ (!/^[^:*?\\\0]+?\.(ttf|otf)$/i.test(file) || file.startsWith("/") ||
32
+ file.split("/").some((part) => !part || part === "." || part === "..")))))) {
33
+ throw new Error("Font files must be safe ZIP member names or **/*.ttf / **/*.otf selectors");
34
+ }
35
+ if (!/\.(zip|ttf|otf)$/i.test(new URL(source.url).pathname)) {
36
+ throw new Error("Remote fonts must be a .zip, .ttf or .otf URL");
37
+ }
38
+ if (source.files !== undefined && !/\.zip$/i.test(new URL(source.url).pathname)) {
39
+ throw new Error("Font file selectors are only supported for ZIP sources");
40
+ }
41
+ }
42
+ else if (source && typeof source === "object" && "provider" in source &&
43
+ source.provider === "nerd-fonts") {
44
+ if (!/^[a-z0-9][a-z0-9_-]*$/i.test(source.family) ||
45
+ (source.version !== undefined && !/^v\d+\.\d+\.\d+$/.test(source.version))) {
46
+ throw new Error("Nerd Fonts requires a catalog family ID and an optional vX.Y.Z release tag");
47
+ }
48
+ }
49
+ else {
50
+ throw new Error("Unsupported font source/provider");
51
+ }
52
+ }
53
+ }
54
+ export function validateWallpaper(wallpaper) {
55
+ if (!wallpaper || typeof wallpaper !== "object")
56
+ throw new Error("windows.wallpaper requires an object");
57
+ const source = wallpaper.source;
58
+ if (typeof source === "string") {
59
+ if (!source.trim() || /[\0\r\n]/.test(source) || /^https?:/i.test(source)) {
60
+ throw new Error("Wallpaper requires a local image path");
61
+ }
62
+ }
63
+ else if (!source || source.kind !== "knownFolder" ||
64
+ !["documents", "desktop", "localAppData", "appData", "userProfile"].includes(source.folder) ||
65
+ typeof source.path !== "string" || /[\0\r\n]/.test(source.path) ||
66
+ /^[\\/]|^[a-z]:/i.test(source.path) || source.path.split(/[\\/]/).includes("..")) {
67
+ throw new Error("Wallpaper requires a valid known-folder or local image path");
68
+ }
69
+ if (wallpaper.style !== undefined &&
70
+ !["Fill", "Fit", "Stretch", "Tile", "Center", "Span"].includes(wallpaper.style)) {
71
+ throw new Error("Unsupported wallpaper style");
72
+ }
73
+ }
74
+ export function personalizationValues(options) {
75
+ if (!options || typeof options !== "object" || Array.isArray(options)) {
76
+ throw new Error("windows.personalization requires an object");
77
+ }
78
+ const values = [];
79
+ const advanced = "Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced";
80
+ const add = (path, name, value) => values.push({ path, name, value });
81
+ for (const key of Object.keys(options)) {
82
+ if (!["accentColor", "explorer", "taskbar"].includes(key))
83
+ throw new Error(`Unknown personalization option ${key}`);
84
+ }
85
+ if (options.accentColor !== undefined) {
86
+ if (!/^#[a-f0-9]{6}$/i.test(options.accentColor))
87
+ throw new Error("accentColor must be #RRGGBB");
88
+ const rgb = options.accentColor.slice(1);
89
+ const bgr = parseInt(`${rgb.slice(4)}${rgb.slice(2, 4)}${rgb.slice(0, 2)}`, 16);
90
+ add("Software\\Microsoft\\Windows\\DWM", "AccentColor", (0xff000000 + bgr) >>> 0);
91
+ add("Software\\Microsoft\\Windows\\DWM", "ColorizationColor", (0xff000000 + parseInt(rgb, 16)) >>> 0);
92
+ add("Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Accent", "AccentColorMenu", (0xff000000 + bgr) >>> 0);
93
+ add("Control Panel\\Desktop", "AutoColorization", 0);
94
+ }
95
+ if (options.explorer !== undefined) {
96
+ if (!options.explorer || typeof options.explorer !== "object" || Array.isArray(options.explorer)) {
97
+ throw new Error("explorer personalization must be an object");
98
+ }
99
+ for (const [key, value] of Object.entries(options.explorer)) {
100
+ if (key === "openTo") {
101
+ if (value !== "ThisPC" && value !== "Home")
102
+ throw new Error("explorer.openTo must be ThisPC or Home");
103
+ add(advanced, "LaunchTo", value === "ThisPC" ? 1 : 2);
104
+ }
105
+ else {
106
+ if (!["showExtensions", "showHiddenFiles"].includes(key) || typeof value !== "boolean") {
107
+ throw new Error(`Invalid explorer personalization ${key}`);
108
+ }
109
+ add(advanced, key === "showExtensions" ? "HideFileExt" : "Hidden", key === "showExtensions" ? (value ? 0 : 1) : (value ? 1 : 2));
110
+ }
111
+ }
112
+ }
113
+ if (options.taskbar !== undefined) {
114
+ if (!options.taskbar || typeof options.taskbar !== "object" || Array.isArray(options.taskbar)) {
115
+ throw new Error("taskbar personalization must be an object");
116
+ }
117
+ for (const [key, value] of Object.entries(options.taskbar)) {
118
+ if (key === "autoHide") {
119
+ if (typeof value !== "boolean")
120
+ throw new Error("taskbar.autoHide must be boolean");
121
+ continue;
122
+ }
123
+ if (key === "search") {
124
+ const modes = ["Hidden", "Icon", "Box", "IconAndLabel"];
125
+ if (typeof value !== "string" || !modes.includes(value))
126
+ throw new Error("Invalid taskbar.search mode");
127
+ add("Software\\Microsoft\\Windows\\CurrentVersion\\Search", "SearchboxTaskbarMode", modes.indexOf(value));
128
+ }
129
+ else {
130
+ if (!["taskView", "widgets"].includes(key) || typeof value !== "boolean") {
131
+ throw new Error(`Invalid taskbar personalization ${key}`);
132
+ }
133
+ add(advanced, key === "taskView" ? "ShowTaskViewButton" : "TaskbarDa", value ? 1 : 0);
134
+ }
135
+ }
136
+ }
137
+ if (!values.length && options.taskbar?.autoHide === undefined)
138
+ throw new Error("windows.personalization requires at least one setting");
139
+ return values;
140
+ }
@@ -1,5 +1,5 @@
1
1
  import type { Fragment, ResourceHandle } from "../core/types.js";
2
- import type { WinDscProperties, WinDscResource, WinPackageSource, WinSettings, WinFilePath, WinKnownFolder, WinKnownFolderName, WinStartupCommand, WinWslConfig, WinWslDistro, WinWslSetup, WinPowerShellRepositoryPolicy } from "../types/index.js";
2
+ import type { WinDscProperties, WinDscResource, WinPackageSource, WinSettings, WinFilePath, WinKnownFolder, WinKnownFolderName, WinStartupCommand, WinWslConfig, WinWslDistro, WinWslSetup, WinPowerShellRepositoryPolicy, WinFontSource, WinWallpaper, WinPersonalization } from "../types/index.js";
3
3
  /**
4
4
  * Accepted call shapes for `windows.package(...)`.
5
5
  *
@@ -99,6 +99,7 @@ export interface WinFileOpts {
99
99
  }
100
100
  /** Rebuild scripts after the emitter supplies the config directory. */
101
101
  export declare function resolveWindowsFileProperties(resource: WinDscResource, configDir?: string, sourcePath?: (path: string) => string): WinDscProperties | undefined;
102
+ export declare function resolveWindowsSource(original: string, configDir?: string, sourcePath?: (path: string) => string): string;
102
103
  export declare function filePathPrelude(): string[];
103
104
  export interface WinEnvNamespace {
104
105
  set(name: string, value: string, opts?: WinEnvOpts): ResourceHandle;
@@ -115,6 +116,14 @@ export interface WinFileNamespace {
115
116
  remove(target: WinFilePath, opts?: WinFileOpts): ResourceHandle;
116
117
  }
117
118
  export interface WindowsHelper {
119
+ fonts(spec: {
120
+ sources: WinFontSource[];
121
+ dependsOn?: ResourceHandle | ResourceHandle[];
122
+ }): ResourceHandle;
123
+ wallpaper(spec: WinWallpaper & {
124
+ dependsOn?: ResourceHandle | ResourceHandle[];
125
+ }): ResourceHandle;
126
+ personalization(options: WinPersonalization, opts?: WinSettingOpts): ResourceHandle;
118
127
  optionalFeature(name: string, opts?: WinOptionalFeatureOpts): ResourceHandle;
119
128
  wsl: WinWslNamespace;
120
129
  /** Manage named current-user Startup shortcuts without running the commands during apply. */
@@ -7,6 +7,8 @@ import { resolve, win32, posix } from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
8
  import { powerShellLiteral as psSingleQuoted } from "./utils.js";
9
9
  import { validatePowerShellRepositoryPolicy } from "./windows-repositories.js";
10
+ import { validateFontSources, validateWallpaper, personalizationValues } from "./windows-personalization.js";
11
+ import { personalizationProperties } from "../backends/windows/personalization.js";
10
12
  const KNOWN_FOLDERS = {
11
13
  documents: "MyDocuments",
12
14
  desktop: "Desktop",
@@ -502,7 +504,16 @@ export function resolveWindowsFileProperties(resource, configDir, sourcePath = (
502
504
  const file = resource.winix;
503
505
  if (file?.kind !== "file")
504
506
  return resource.properties;
505
- let source = file.source;
507
+ const source = file.source === undefined ? undefined : resolveWindowsSource(file.source, configDir, sourcePath);
508
+ switch (file.action) {
509
+ case "text": return buildFileTextScriptProperties({ ...file, content: file.content });
510
+ case "remove": return buildFileRemoveScriptProperties(file);
511
+ case "symlink": return buildFileSymlinkScriptProperties({ ...file, source: source });
512
+ case "copy": return buildFileCopyScriptProperties({ ...file, source: source });
513
+ }
514
+ }
515
+ export function resolveWindowsSource(original, configDir, sourcePath = (path) => path) {
516
+ let source = original;
506
517
  if (source !== undefined && !/%[^%]+%/.test(source) &&
507
518
  !win32.isAbsolute(source) && !posix.isAbsolute(source)) {
508
519
  if (!configDir)
@@ -517,12 +528,7 @@ export function resolveWindowsFileProperties(resource, configDir, sourcePath = (
517
528
  }
518
529
  if (source !== undefined && !/%[^%]+%/.test(source))
519
530
  source = sourcePath(source);
520
- switch (file.action) {
521
- case "text": return buildFileTextScriptProperties({ ...file, content: file.content });
522
- case "remove": return buildFileRemoveScriptProperties(file);
523
- case "symlink": return buildFileSymlinkScriptProperties({ ...file, source: source });
524
- case "copy": return buildFileCopyScriptProperties({ ...file, source: source });
525
- }
531
+ return source;
526
532
  }
527
533
  function buildPathScriptProperties(opts) {
528
534
  const registryPath = envRegistryPath(opts.scope);
@@ -1064,6 +1070,25 @@ export const windows = {
1064
1070
  return asHandle(fragment, { kind: "dsc", token: resource.token });
1065
1071
  },
1066
1072
  setting: (settings, opts) => dscHandle(normalizeSetting(settings, opts)),
1073
+ fonts: (spec) => {
1074
+ validateFontSources(spec?.sources);
1075
+ return dscHandle(withDscMetadata(withDscToken({
1076
+ resourceType: POWERSHELL_SCRIPT_RESOURCE, name: "Windows fonts",
1077
+ dependsOn: resolveDependsOn(spec.dependsOn),
1078
+ }), { kind: "fonts", sources: spec.sources }));
1079
+ },
1080
+ wallpaper: (spec) => {
1081
+ validateWallpaper(spec);
1082
+ return dscHandle(withDscMetadata(withDscToken({
1083
+ resourceType: POWERSHELL_SCRIPT_RESOURCE, name: "Windows wallpaper",
1084
+ dependsOn: resolveDependsOn(spec.dependsOn),
1085
+ }), { kind: "wallpaper", wallpaper: { source: spec.source, style: spec.style } }));
1086
+ },
1087
+ personalization: (options, opts) => dscHandle(withDscToken({
1088
+ resourceType: POWERSHELL_SCRIPT_RESOURCE, name: "Windows personalization",
1089
+ properties: personalizationProperties(personalizationValues(options), options.taskbar?.autoHide),
1090
+ dependsOn: resolveDependsOn(opts?.dependsOn),
1091
+ })),
1067
1092
  env: {
1068
1093
  set: (name, value, opts) => dscHandle(normalizeEnv(name, "Present", value, opts)),
1069
1094
  remove: (name, opts) => dscHandle(normalizeEnv(name, "Absent", undefined, opts)),
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, 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, 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,33 @@ 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.wallpaper({ source: "../wallpapers/desktop.jpg", style: "Fill" })\`
261
+ manages the current-user desktop image; source is a local/config-relative or
262
+ known-folder path. Styles: Fill, Fit, Stretch, Tile, Center, Span. Source
263
+ hashes detect changed images; remote wallpapers and per-monitor assignments
264
+ are not supported.
265
+ - \`windows.personalization({ accentColor: "#336699", explorer: {
266
+ showExtensions: true, showHiddenFiles: false, openTo: "ThisPC" }, taskbar: {
267
+ autoHide: false, search: "Hidden", taskView: true, widgets: false } })\`
268
+ changes only declared current-user values. Accent disables automatic coloring;
269
+ do not contradict it with windows.setting AutoColorization. Explorer openTo is
270
+ ThisPC/Home; search is Hidden/Icon/IconAndLabel/Box. Some preferences require
271
+ signing out and depend on Windows version/policy; never restart Explorer.
272
+ - \`windows.fonts({ sources: ["../fonts/font.ttf", {
273
+ url: "https://example.com/fonts.zip", files: ["**/*.ttf"] }, {
274
+ provider: "nerd-fonts", family: "JetBrainsMono" }] })\` installs current-user
275
+ TTF/OTF fonts. URL sources require HTTPS without credentials, optionally sha256;
276
+ files selects exact ZIP members or **/*.ttf / **/*.otf. Nerd Fonts is the only
277
+ provider, with optional exact version vX.Y.Z. Discover IDs with
278
+ \`winix fonts search [query] --provider nerd-fonts\`; IDs are not installed family
279
+ names. Remote sources lock URL/version/checksum; first resolution trusts upstream
280
+ unless an independent sha256 is supplied. \`winix update --windows fonts\`
281
+ refreshes only font pins. Apply reuses pins; dry runs don't write/install.
282
+ Installation verifies hashes, bounds/safely extracts ZIPs, reports actual font
283
+ families and rejects differing existing files/registry entries. Identical
284
+ files are reused; no font removal or automatic app font selection. Native
285
+ desktop/font activation remains unverified; don't rehearse on a shared machine.
286
+
260
287
  - \`windows.package()\` installs a winget or Microsoft Store package. A string
261
288
  means a floating winget package ID. The object form accepts \`id\`,
262
289
  \`source\`, \`version\`, and dependency options.
@@ -388,8 +415,19 @@ are automatically uninstalled after successful activation; always preview
388
415
  with \`winix switch --dry\`. Other recorded owners prevent removal.
389
416
  Switches with package/startup removals prompt before activation; declining cancels
390
417
  the entire switch. Use \`--yes\`/\`-y\` for automation; noninteractive runs with
391
- removals require it. Dry runs and switches without removals do not prompt.
392
- External shortcut edits/package-version drift block reconciliation.
418
+ removals require it. Dry runs do not prompt.
419
+ Native Windows switch treats floating package locks as minimum versions/fresh
420
+ install targets: install missing, upgrade older, keep newer without downgrading.
421
+ Owned external upgrades retain ownership and refresh observed snapshots after
422
+ successful activation; pre-installed packages remain unowned. An inline version
423
+ is exact: existing mismatches fail explicitly before activation.
424
+ Unequal non-dotted-numeric versions cannot be ordered and require explicit
425
+ resolution. Interactive successful switches offer a separate [y/N] lock update
426
+ for newer floating packages. Declining continues; dry/noninteractive runs do not
427
+ update observed-version pins, and --yes does not accept lock-update prompts.
428
+ Plain apply/direct DSC scripts keep lock-based generation.
429
+ External shortcut edits, package downgrades and exact-pin drift still block
430
+ reconciliation; externally modified removals remain protected.
393
431
  \`winix state forget startup <name>\` or
394
432
  \`winix state forget package <winget|msstore> <id>\` releases removal ownership
395
433
  without deleting the resource; --dry previews. Do not copy applied state to a
@@ -6,6 +6,35 @@ export interface WinKnownFolder {
6
6
  path: string;
7
7
  }
8
8
  export type WinFilePath = string | WinKnownFolder;
9
+ export type WinFontSource = string | {
10
+ url: string;
11
+ sha256?: string;
12
+ /** ZIP member names or recursive extension selectors; defaults to all TTF/OTF files. */
13
+ files?: string[];
14
+ } | {
15
+ provider: "nerd-fonts";
16
+ family: string;
17
+ /** Official release tag; omitted tags resolve latest once, then remain locked. */
18
+ version?: string;
19
+ };
20
+ export interface WinWallpaper {
21
+ source: WinFilePath;
22
+ style?: "Fill" | "Fit" | "Stretch" | "Tile" | "Center" | "Span";
23
+ }
24
+ export interface WinPersonalization {
25
+ accentColor?: string;
26
+ explorer?: {
27
+ showExtensions?: boolean;
28
+ showHiddenFiles?: boolean;
29
+ openTo?: "ThisPC" | "Home";
30
+ };
31
+ taskbar?: {
32
+ autoHide?: boolean;
33
+ search?: "Hidden" | "Icon" | "IconAndLabel" | "Box";
34
+ taskView?: boolean;
35
+ widgets?: boolean;
36
+ };
37
+ }
9
38
  export type WinStartupWindowStyle = "normal" | "minimized" | "maximized";
10
39
  export interface WinStartupCommand {
11
40
  /** Absolute/environment-variable path, known-folder path, or application name on PATH. */
@@ -186,6 +215,12 @@ export interface WinDscResource {
186
215
  dependsOn?: ResourceRef[];
187
216
  }
188
217
  export type WinDscMetadata = {
218
+ kind: "fonts";
219
+ sources: WinFontSource[];
220
+ } | {
221
+ kind: "wallpaper";
222
+ wallpaper: WinWallpaper;
223
+ } | {
189
224
  kind: "optional-features";
190
225
  names: string[];
191
226
  enabled: boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adrifer/winix",
3
- "version": "0.3.0-preview.4",
3
+ "version": "0.3.0-preview.6",
4
4
  "description": "TypeScript-first system configuration for NixOS, nix-darwin, and Home Manager",
5
5
  "license": "MIT",
6
6
  "author": "Adrian Fernandez",