@adrifer/winix 0.2.2 → 0.2.4-preview.0
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 +374 -2
- package/dist/backends/windows/index.d.ts +3 -1
- package/dist/backends/windows/index.js +99 -7
- package/dist/backends/windows/lockfile.d.ts +36 -1
- package/dist/backends/windows/lockfile.js +168 -0
- package/dist/backends/windows/paths.d.ts +2 -0
- package/dist/backends/windows/paths.js +17 -0
- package/dist/backends/windows/powershell.d.ts +6 -0
- package/dist/backends/windows/powershell.js +51 -0
- package/dist/backends/windows/wsl-setup-runtime.d.ts +32 -0
- package/dist/backends/windows/wsl-setup-runtime.js +387 -0
- package/dist/backends/windows/wsl-setup.d.ts +12 -0
- package/dist/backends/windows/wsl-setup.js +108 -0
- package/dist/backends/windows/wsl.d.ts +9 -0
- package/dist/backends/windows/wsl.js +194 -0
- package/dist/cli/commands/apply.d.ts +7 -1
- package/dist/cli/commands/apply.js +39 -15
- package/dist/cli/commands/check.js +3 -0
- package/dist/cli/commands/init.js +2 -0
- package/dist/cli/commands/install.d.ts +7 -0
- package/dist/cli/commands/install.js +41 -0
- package/dist/cli/commands/switch.d.ts +6 -0
- package/dist/cli/commands/switch.js +53 -13
- package/dist/cli/commands/update.d.ts +6 -1
- package/dist/cli/commands/update.js +41 -10
- package/dist/cli/index.js +65 -3
- package/dist/cli/windows-state.d.ts +56 -0
- package/dist/cli/windows-state.js +341 -0
- package/dist/helpers/index.d.ts +1 -1
- package/dist/helpers/utils.d.ts +1 -0
- package/dist/helpers/utils.js +8 -0
- package/dist/helpers/windows.d.ts +53 -7
- package/dist/helpers/windows.js +351 -28
- package/dist/index.d.ts +4 -2
- package/dist/skill.d.ts +2 -0
- package/dist/skill.js +503 -0
- package/dist/types/windows.d.ts +82 -1
- package/package.json +3 -1
- package/scripts/bootstrap-nixos.sh +51 -0
- package/scripts/bootstrap-windows.ps1 +216 -0
package/dist/skill.js
ADDED
|
@@ -0,0 +1,503 @@
|
|
|
1
|
+
import { account, darwin, home, nix, nixos, overlay, platforms, windows, } from "./helpers/index.js";
|
|
2
|
+
import { rawModule } from "./sdk/index.js";
|
|
3
|
+
const CORE_AUTHORING_API = [
|
|
4
|
+
"workspace",
|
|
5
|
+
"host",
|
|
6
|
+
"feature",
|
|
7
|
+
"profile",
|
|
8
|
+
"input",
|
|
9
|
+
"defineInputs",
|
|
10
|
+
];
|
|
11
|
+
const SKILL = `# Winix
|
|
12
|
+
|
|
13
|
+
Use these instructions when creating, changing, reviewing, or debugging a Winix
|
|
14
|
+
configuration. They match the installed Winix binary that printed them.
|
|
15
|
+
|
|
16
|
+
## Start here
|
|
17
|
+
|
|
18
|
+
Winix turns composable TypeScript fragments into NixOS, nix-darwin, Home
|
|
19
|
+
Manager, and Windows DSC configuration.
|
|
20
|
+
|
|
21
|
+
Before editing:
|
|
22
|
+
|
|
23
|
+
1. Read \`winix.config.ts\`, then follow its imports into the relevant features,
|
|
24
|
+
profiles, hosts, and input definitions.
|
|
25
|
+
2. Read \`package.json\` to see which Winix commands the project exposes.
|
|
26
|
+
3. Do not edit \`.winix/out/\`. It is generated by \`winix apply\`.
|
|
27
|
+
4. Prefer the project's existing organization and helpers over introducing a
|
|
28
|
+
new pattern.
|
|
29
|
+
|
|
30
|
+
After editing, run the narrowest useful checks:
|
|
31
|
+
|
|
32
|
+
\`\`\`bash
|
|
33
|
+
winix check
|
|
34
|
+
winix apply --dry
|
|
35
|
+
\`\`\`
|
|
36
|
+
|
|
37
|
+
Use the project package runner, such as \`npm exec winix -- check\`, when the
|
|
38
|
+
binary is not directly on PATH.
|
|
39
|
+
|
|
40
|
+
## Configuration model
|
|
41
|
+
|
|
42
|
+
A workspace contains inputs and hosts:
|
|
43
|
+
|
|
44
|
+
\`\`\`ts
|
|
45
|
+
import {
|
|
46
|
+
defineInputs,
|
|
47
|
+
feature,
|
|
48
|
+
home,
|
|
49
|
+
host,
|
|
50
|
+
input,
|
|
51
|
+
platforms,
|
|
52
|
+
profile,
|
|
53
|
+
workspace,
|
|
54
|
+
} from "@adrifer/winix";
|
|
55
|
+
|
|
56
|
+
const inputs = defineInputs({
|
|
57
|
+
nixpkgs: "nixos-unstable",
|
|
58
|
+
homeManager: input("github:nix-community/home-manager", {
|
|
59
|
+
follows: { nixpkgs: "nixpkgs" },
|
|
60
|
+
}),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
const shell = feature("shell", ({ home }) => {
|
|
64
|
+
home.program("zsh", { enableCompletion: true });
|
|
65
|
+
home.packages("ripgrep", "fd");
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
const developer = profile("developer", [shell()]);
|
|
69
|
+
|
|
70
|
+
export default workspace({
|
|
71
|
+
inputs,
|
|
72
|
+
hosts: [
|
|
73
|
+
host("workstation", platforms.nixos({ stateVersion: "25.05" }), [
|
|
74
|
+
developer(),
|
|
75
|
+
]),
|
|
76
|
+
],
|
|
77
|
+
});
|
|
78
|
+
\`\`\`
|
|
79
|
+
|
|
80
|
+
The main constructors have distinct jobs:
|
|
81
|
+
|
|
82
|
+
- \`feature(id, callback)\` declares configuration. The callback receives an
|
|
83
|
+
injected context and may declare by effect, return fragments, or do both.
|
|
84
|
+
A feature factory has \`.isActive\`.
|
|
85
|
+
- \`profile(id, entries)\` groups an array of instantiated features, profiles,
|
|
86
|
+
or bare fragments. It never accepts a callback. A profile has \`.isActive\`.
|
|
87
|
+
- \`host(name, platform, entries)\` creates a target host. The third argument
|
|
88
|
+
may also be a callback. A host does not have \`.isActive\`.
|
|
89
|
+
- \`workspace({ inputs, hosts })\` is the default export of
|
|
90
|
+
\`winix.config.ts\`.
|
|
91
|
+
- \`input(url, options)\` defines an input with options such as \`follows\`.
|
|
92
|
+
\`defineInputs()\` preserves exact input typing.
|
|
93
|
+
|
|
94
|
+
Input names use camelCase in TypeScript and become kebab-case in generated Nix.
|
|
95
|
+
For example, \`nixosWsl\` becomes \`nixos-wsl\`.
|
|
96
|
+
|
|
97
|
+
## Effects, returns, and composition
|
|
98
|
+
|
|
99
|
+
\`feature\` and callback-form \`host\` bodies receive exactly
|
|
100
|
+
\`{ home, nixos, darwin, windows, platforms }\`.
|
|
101
|
+
|
|
102
|
+
Calls through these injected namespaces register by effect:
|
|
103
|
+
|
|
104
|
+
\`\`\`ts
|
|
105
|
+
const git = feature("git", ({ home }) => {
|
|
106
|
+
home.program("git", { userName: "Ada" });
|
|
107
|
+
});
|
|
108
|
+
\`\`\`
|
|
109
|
+
|
|
110
|
+
Imported global helpers still return ordinary fragments. Return those
|
|
111
|
+
fragments so they are included:
|
|
112
|
+
|
|
113
|
+
\`\`\`ts
|
|
114
|
+
const git = feature("git", () =>
|
|
115
|
+
home.program("git", { userName: "Ada" })
|
|
116
|
+
);
|
|
117
|
+
\`\`\`
|
|
118
|
+
|
|
119
|
+
Calling another feature or profile factory returns a lazy fragment. It is not
|
|
120
|
+
registered by effect, so return it when composing:
|
|
121
|
+
|
|
122
|
+
\`\`\`ts
|
|
123
|
+
const workstation = feature("workstation", ({ home }) => {
|
|
124
|
+
home.packages("jq");
|
|
125
|
+
return [developer(), editors()];
|
|
126
|
+
});
|
|
127
|
+
\`\`\`
|
|
128
|
+
|
|
129
|
+
Do not pass a callback to \`profile\`. Put conditional or effectful logic in a
|
|
130
|
+
\`feature\`, then add that feature to the profile's array.
|
|
131
|
+
|
|
132
|
+
Use \`.isActive\` inside evaluation:
|
|
133
|
+
|
|
134
|
+
\`\`\`ts
|
|
135
|
+
const shell = feature("shell", ({ home, platforms }) => {
|
|
136
|
+
home.program("zsh", {
|
|
137
|
+
shellAliases: {
|
|
138
|
+
...(platforms.nixos.isActive && { rebuild: "winix switch" }),
|
|
139
|
+
},
|
|
140
|
+
});
|
|
141
|
+
});
|
|
142
|
+
\`\`\`
|
|
143
|
+
|
|
144
|
+
Feature activity does not depend on declaration order.
|
|
145
|
+
|
|
146
|
+
## Platforms
|
|
147
|
+
|
|
148
|
+
Use one platform factory as the second argument to each host:
|
|
149
|
+
|
|
150
|
+
- \`platforms.nixos({ system, stateVersion, allowUnfree, homeManager, hostname })\`
|
|
151
|
+
- \`platforms.darwin({ system, stateVersion, allowUnfree, homeManager, homebrew, hostname })\`
|
|
152
|
+
- \`platforms.windows({ hostname })\`
|
|
153
|
+
|
|
154
|
+
The platform factories also expose \`.isActive\` during evaluation.
|
|
155
|
+
|
|
156
|
+
## Fragment and merge rules
|
|
157
|
+
|
|
158
|
+
Everything composes as a fragment or an array of fragments. Plain objects are
|
|
159
|
+
valid when no curated helper fits:
|
|
160
|
+
|
|
161
|
+
\`\`\`ts
|
|
162
|
+
const limits = feature("limits", () => ({
|
|
163
|
+
nixos: {
|
|
164
|
+
boot: {
|
|
165
|
+
kernel: {
|
|
166
|
+
sysctl: { "fs.inotify.max_user_watches": 1048576 },
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
},
|
|
170
|
+
}));
|
|
171
|
+
\`\`\`
|
|
172
|
+
|
|
173
|
+
Winix merges objects recursively, appends arrays, and uses the last value for
|
|
174
|
+
scalar conflicts. Keep fragment ordering intentional.
|
|
175
|
+
|
|
176
|
+
Nix option keys pass through unchanged. Write the real Nix key, such as
|
|
177
|
+
\`"experimental-features"\`, when an option uses punctuation. Winix does not
|
|
178
|
+
convert option keys from camelCase.
|
|
179
|
+
|
|
180
|
+
## Accounts
|
|
181
|
+
|
|
182
|
+
Define accounts at file scope and instantiate them in hosts or profiles:
|
|
183
|
+
|
|
184
|
+
\`\`\`ts
|
|
185
|
+
const ada = account.user("ada", () => ({
|
|
186
|
+
admin: true,
|
|
187
|
+
shell: "zsh",
|
|
188
|
+
stateVersion: "25.05",
|
|
189
|
+
groups: ["docker"],
|
|
190
|
+
wslDefault: true,
|
|
191
|
+
}));
|
|
192
|
+
|
|
193
|
+
const media = account.group("media", () => ({
|
|
194
|
+
members: [ada, "jellyfin"],
|
|
195
|
+
}));
|
|
196
|
+
\`\`\`
|
|
197
|
+
|
|
198
|
+
\`account.user()\` can set Home Manager state, packages, groups, SSH keys,
|
|
199
|
+
password-file references, UID/GID data, and platform user options. Use
|
|
200
|
+
\`account.group()\` for named groups. Never put secret values directly in the
|
|
201
|
+
configuration. Reference managed secret files instead.
|
|
202
|
+
|
|
203
|
+
## NixOS helpers
|
|
204
|
+
|
|
205
|
+
The \`nixos\` namespace is callable with a typed NixOS option object. Its
|
|
206
|
+
curated helpers are:
|
|
207
|
+
|
|
208
|
+
- \`nixos.imports()\`, \`nixos.program()\`, \`nixos.service()\`, and
|
|
209
|
+
\`nixos.packages()\`
|
|
210
|
+
- \`nixos.nix()\`, \`nixos.boot()\`, \`nixos.networking()\`,
|
|
211
|
+
\`nixos.environment()\`, \`nixos.users()\`, \`nixos.system()\`,
|
|
212
|
+
\`nixos.fonts()\`, \`nixos.security()\`, \`nixos.i18n()\`, and
|
|
213
|
+
\`nixos.time()\`
|
|
214
|
+
- \`nixos.virtualisation()\` and
|
|
215
|
+
\`nixos.virtualisation.ociContainer(name, options)\`
|
|
216
|
+
- \`nixos.sysctl()\`
|
|
217
|
+
- \`nixos.systemd()\`, \`nixos.systemd.service()\`,
|
|
218
|
+
\`nixos.systemd.userService()\`, \`nixos.systemd.timer()\`, and
|
|
219
|
+
\`nixos.systemd.tmpfiles()\`
|
|
220
|
+
- \`nixos.raw()\` as a last-resort raw Nix escape hatch
|
|
221
|
+
|
|
222
|
+
Mirror Nix's parent namespace rather than inventing aliases. For example, use
|
|
223
|
+
\`nixos.networking({ firewall: ... })\`, not a root firewall shortcut.
|
|
224
|
+
|
|
225
|
+
## Home Manager helpers
|
|
226
|
+
|
|
227
|
+
The \`home\` namespace is callable with a typed Home Manager option object.
|
|
228
|
+
Available helpers:
|
|
229
|
+
|
|
230
|
+
- \`home.imports()\`, \`home.program()\`, \`home.service()\`,
|
|
231
|
+
\`home.packages()\`
|
|
232
|
+
- \`home.env()\` for \`home.sessionVariables\`
|
|
233
|
+
- \`home.path()\` for \`home.sessionPath\`
|
|
234
|
+
- \`home.files()\`, \`home.configFile()\`, and \`home.configFiles()\`
|
|
235
|
+
- \`home.symlink()\` for out-of-store symlink file values
|
|
236
|
+
- \`home.activation(name, { after, script })\`
|
|
237
|
+
- \`home.raw()\` as a last-resort raw Nix escape hatch
|
|
238
|
+
|
|
239
|
+
\`program\` and \`service\` helpers set \`enable: true\` unless the supplied
|
|
240
|
+
options explicitly override it.
|
|
241
|
+
|
|
242
|
+
## nix-darwin helpers
|
|
243
|
+
|
|
244
|
+
The \`darwin\` namespace is callable with a typed nix-darwin option object.
|
|
245
|
+
Available helpers:
|
|
246
|
+
|
|
247
|
+
- \`darwin.imports()\`, \`darwin.program()\`, \`darwin.service()\`, and
|
|
248
|
+
\`darwin.packages()\`
|
|
249
|
+
- \`darwin.nix()\`, \`darwin.security()\`, \`darwin.homebrew()\`, and
|
|
250
|
+
\`darwin.defaults()\`
|
|
251
|
+
- \`darwin.launchd()\`, \`darwin.launchd.agent()\`, and
|
|
252
|
+
\`darwin.launchd.daemon()\`
|
|
253
|
+
- \`darwin.raw()\` as a last-resort raw Nix escape hatch
|
|
254
|
+
|
|
255
|
+
## Windows helpers
|
|
256
|
+
|
|
257
|
+
Windows hosts generate a DSC v3 configuration for \`winget configure\`.
|
|
258
|
+
Resources return handles that can be passed through \`dependsOn\`.
|
|
259
|
+
|
|
260
|
+
- \`windows.package()\` installs a winget or Microsoft Store package. A string
|
|
261
|
+
means a floating winget package ID. The object form accepts \`id\`,
|
|
262
|
+
\`source\`, \`version\`, and dependency options.
|
|
263
|
+
- \`windows.setting()\` manages supported Windows settings.
|
|
264
|
+
- \`windows.env.set()\` and \`windows.env.remove()\` manage environment
|
|
265
|
+
variables.
|
|
266
|
+
- \`windows.path.add()\` and \`windows.path.remove()\` manage PATH entries.
|
|
267
|
+
- \`windows.file.text()\`, \`windows.file.symlink()\`,
|
|
268
|
+
\`windows.file.copy()\`, and \`windows.file.remove()\` manage files.
|
|
269
|
+
- \`windows.startup.command(name, spec)\` manages a named current-user Startup
|
|
270
|
+
shortcut, without running it during apply. Supply executable and optional argv
|
|
271
|
+
arguments, workingDirectory, windowStyle (normal/minimized/maximized),
|
|
272
|
+
dependsOn, backup, and force. Executables may be application names on PATH or
|
|
273
|
+
absolute/environment/known-folder paths. Arguments are literal strings or
|
|
274
|
+
known-folder paths; the default working directory is the user profile.
|
|
275
|
+
Executable and working directory must exist during activation. Replacement
|
|
276
|
+
requires backup or force; backup collisions fail. This is sign-in startup,
|
|
277
|
+
not a service, scheduled task, elevated launch, or all-users startup.
|
|
278
|
+
Native Windows switch tracks created/replaced shortcut ownership and removes
|
|
279
|
+
unchanged owned entries when declarations disappear. Matching pre-existing
|
|
280
|
+
shortcuts remain externally owned.
|
|
281
|
+
- \`windows.knownFolder.documents()\`, \`windows.knownFolder.desktop()\`,
|
|
282
|
+
\`windows.knownFolder.localAppData()\`, \`windows.knownFolder.appData()\`, and
|
|
283
|
+
\`windows.knownFolder.userProfile()\` build typed file targets resolved during
|
|
284
|
+
activation. Each accepts an optional relative child path. File copy/symlink
|
|
285
|
+
sources resolve relative to the directory containing winix.config.ts;
|
|
286
|
+
absolute paths, environment-variable paths, and file URLs are also supported.
|
|
287
|
+
- \`windows.powershell.module()\` declares a current-user PowerShell 7 module
|
|
288
|
+
by name, with optional repository (default PSGallery) and dependsOn.
|
|
289
|
+
Versions are recorded in the modules section of winix-windows.lock, not
|
|
290
|
+
handwritten declarations. PowerShell 7 with PSResourceGet is required for
|
|
291
|
+
resolution and installation.
|
|
292
|
+
- \`windows.dsc()\` declares an arbitrary DSC resource.
|
|
293
|
+
- \`windows.optionalFeature()\` enables/disables a named Windows optional feature;
|
|
294
|
+
enabled defaults to true. Changes require elevation, never reboot automatically.
|
|
295
|
+
- \`windows.wsl()\` enables the WSL and Virtual Machine Platform features.
|
|
296
|
+
Options are config, backup, force, and dependsOn. The optional config manages
|
|
297
|
+
the full current-user .wslconfig with file overwrite protections; omitting it
|
|
298
|
+
leaves the file untouched. The returned handle covers the complete setup.
|
|
299
|
+
If a reboot is needed, restart Windows manually and rerun switch.
|
|
300
|
+
It never shuts down WSL; restart WSL manually when configuration changes.
|
|
301
|
+
- \`windows.wsl.distro()\` registers a named distro with source "nixos-wsl",
|
|
302
|
+
installLocation, optional default and dependsOn. Declare windows.wsl() and the
|
|
303
|
+
Microsoft.WSL package in the same host; features, config, and runtime become
|
|
304
|
+
automatic dependencies.
|
|
305
|
+
Images for x64/ARM64 are verified against winix-windows.lock wslImages pins.
|
|
306
|
+
Update with winix update --windows nixos-wsl. Updates never reinstall an
|
|
307
|
+
existing distro. Conflicting/unrecorded distros are refused, not adopted.
|
|
308
|
+
Removing a declaration never unregisters a distro or deletes its data.
|
|
309
|
+
Optional setup opts into trusted first-run Linux provisioning:
|
|
310
|
+
{ repository: "https://github.com/example/dotfiles.git", ref: "main",
|
|
311
|
+
configDirectory: "winix", host: "wsl-work", user: "alice",
|
|
312
|
+
checkout: "/home/alice/dotfiles" }.
|
|
313
|
+
Repository URLs must be HTTPS without credentials; authentication must already
|
|
314
|
+
work inside Linux. Commit package.json, package-lock.json and flake.lock in
|
|
315
|
+
configDirectory and use a released SDK supporting setup. The Linux host must
|
|
316
|
+
explicitly enable/import NixOS-WSL, declare system.stateVersion, and match the
|
|
317
|
+
distro architecture. user selects a declared normal account (inferred from
|
|
318
|
+
Home Manager or the sole normal account when omitted); checkout defaults to
|
|
319
|
+
its home/dotfiles and must remain inside that home. Home Manager identity/home
|
|
320
|
+
must agree. Git/npm/config evaluation run unprivileged; root activates the
|
|
321
|
+
account-only bootstrap, assigns checkout ownership, then activates the full
|
|
322
|
+
Linux host, which must set wsl.defaultUser to that account. No password or
|
|
323
|
+
sudo policy is supplied. Missing external account secrets fail explicitly.
|
|
324
|
+
wslRepositories locks repository commits; refresh with
|
|
325
|
+
winix update --windows wsl-setup. Completed setup is never reapplied or updated;
|
|
326
|
+
in-progress setup retains its original commit. Failures are resumable; dirty
|
|
327
|
+
or occupied checkouts/changed settings are refused, never reset or adopted.
|
|
328
|
+
State lives at /var/lib/winix/wsl-setup. Inspect stale run.lock and its PID
|
|
329
|
+
before manual recovery; never remove a live coordinator's lock.
|
|
330
|
+
No shutdown/reboot is automatic. Fresh-image activation remains unverified.
|
|
331
|
+
Omit setup to retain separate manual Linux activation.
|
|
332
|
+
- \`windows.raw()\` runs a command on every apply. It is not idempotent, so use
|
|
333
|
+
a typed helper or \`windows.dsc()\` when possible. String commands default to
|
|
334
|
+
PowerShell 7 (\`pwsh\`); explicit executables are preserved.
|
|
335
|
+
|
|
336
|
+
File, PATH, startup, and module scripts use Microsoft.DSC.Transitional/PowerShellScript,
|
|
337
|
+
not Windows PowerShell 5.1. Install PowerShell 7 and put pwsh on PATH before DSC
|
|
338
|
+
resource discovery; declaring its package dependency is not sufficient for
|
|
339
|
+
bootstrap. Set scripts guard their own changes independently of test scripts.
|
|
340
|
+
|
|
341
|
+
Floating Windows packages, PowerShell modules, NixOS-WSL images and setup commits are resolved into
|
|
342
|
+
\`winix-windows.lock\` on first apply; existing pins are reused without a
|
|
343
|
+
resolution query. \`winix update --windows [names...]\` refreshes selected
|
|
344
|
+
package/module/image/repository pins (all when omitted, nixos-wsl for images,
|
|
345
|
+
wsl-setup for setup commits); --dry reports without writing.
|
|
346
|
+
Keep the lock in version control. Installation still requires network access
|
|
347
|
+
when the locked package/module is not installed.
|
|
348
|
+
|
|
349
|
+
Native Windows \`winix switch\` keeps a separate per-user/machine applied-state
|
|
350
|
+
inventory in LocalAppData/Winix, shared across recorded workspace/host activations.
|
|
351
|
+
Only packages absent before a successful activation become uninstall-owned.
|
|
352
|
+
Pre-existing packages are never automatically adopted. Unused owned packages
|
|
353
|
+
are automatically uninstalled after successful activation; always preview
|
|
354
|
+
with \`winix switch --dry\`. Other recorded owners prevent removal.
|
|
355
|
+
Switches with package/startup removals prompt before activation; declining cancels
|
|
356
|
+
the entire switch. Use \`--yes\`/\`-y\` for automation; noninteractive runs with
|
|
357
|
+
removals require it. Dry runs and switches without removals do not prompt.
|
|
358
|
+
External shortcut edits/package-version drift block reconciliation.
|
|
359
|
+
\`winix state forget startup <name>\` or
|
|
360
|
+
\`winix state forget package <winget|msstore> <id>\` releases removal ownership
|
|
361
|
+
without deleting the resource; --dry previews. Do not copy applied state to a
|
|
362
|
+
new machine or infer ownership from version locks. Direct DSC/script activation
|
|
363
|
+
bypasses this tracking. Files, modules, env and PATH cleanup are not tracked.
|
|
364
|
+
|
|
365
|
+
For fresh Windows prerequisites, \`scripts/bootstrap-windows.ps1\` runs in built-in
|
|
366
|
+
Windows PowerShell 5.1 or PowerShell 7. App Installer/WinGet is the initial
|
|
367
|
+
prerequisite. \`-Check\` is read-only; install mode confirms missing/outdated
|
|
368
|
+
Git/Node/PowerShell/DSC installation and enables WinGet configuration support.
|
|
369
|
+
\`-UseNvm\` chooses NVM for Windows instead of standalone Node; \`-Yes\` accepts
|
|
370
|
+
bootstrap changes. It never installs Winix globally, activates a host, provisions
|
|
371
|
+
WSL, reboots, or changes execution policy persistently. Prepare the config and
|
|
372
|
+
compatible SDK separately, then review \`switch --dry\` before activation.
|
|
373
|
+
|
|
374
|
+
On existing NixOS/NixOS-WSL, \`bash bootstrap-nixos.sh\` (from
|
|
375
|
+
\`scripts/bootstrap-nixos.sh\` or a reviewed release asset) opens a temporary
|
|
376
|
+
Git/Node.js 24/npm/Bash environment using pinned nixpkgs. Nix must already be
|
|
377
|
+
available. Flakes are enabled only in the child session; the script never edits
|
|
378
|
+
profiles/system configuration, clones repos, installs npm dependencies/Winix,
|
|
379
|
+
or activates hosts. Nix may download store paths. Users handle their configs
|
|
380
|
+
and declare permanent tools/settings themselves; \`exit\` leaves the environment.
|
|
381
|
+
|
|
382
|
+
## Nix values and escape hatches
|
|
383
|
+
|
|
384
|
+
Import \`nix\` at file scope. It builds values and does not declare fragments:
|
|
385
|
+
|
|
386
|
+
- \`nix.expr()\` emits a raw Nix expression.
|
|
387
|
+
- \`nix.pkg()\` and \`nix.pkg.stable()\` reference packages.
|
|
388
|
+
- \`nix.bin()\`, \`nix.homePath()\`, and \`nix.pkgPath()\` build executable
|
|
389
|
+
and path expressions.
|
|
390
|
+
- \`nix.str\`, \`nix.script\`, and \`nix.script.raw\` are template helpers.
|
|
391
|
+
- \`nix.concat()\`, \`nix.withPkgs()\`, \`nix.optionalAttrs()\`, and
|
|
392
|
+
\`nix.optionalString()\` build common expressions.
|
|
393
|
+
- \`nix.isDarwin\` and \`nix.isLinux\` are Nix-side conditions.
|
|
394
|
+
- \`nix.binaryRelease()\` builds a package for a prebuilt CLI release.
|
|
395
|
+
- \`nix.lib.mkDefault()\`, \`nix.lib.mkForce()\`, \`nix.lib.mkBefore()\`,
|
|
396
|
+
\`nix.lib.mkAfter()\`, \`nix.lib.optionalAttrs()\`, and
|
|
397
|
+
\`nix.lib.optionalString()\` expose common library operations.
|
|
398
|
+
|
|
399
|
+
Prefer typed helpers. Use \`nix.expr()\`, platform \`.raw()\` helpers, and
|
|
400
|
+
\`rawModule()\` only when the typed model cannot express the configuration.
|
|
401
|
+
|
|
402
|
+
\`rawModule("./legacy/system.nix")\` imports a workspace-relative NixOS module.
|
|
403
|
+
Use \`rawModule.homeManager()\` or \`rawModule.darwin()\` for those scopes.
|
|
404
|
+
Paths must be relative POSIX paths ending in \`.nix\`.
|
|
405
|
+
|
|
406
|
+
## Overlays
|
|
407
|
+
|
|
408
|
+
Use \`overlay.stable(inputName)\` to expose a stable package set and
|
|
409
|
+
\`overlay.custom(expression)\` for a custom overlay. The
|
|
410
|
+
\`overlay.darwin.stable()\` and \`overlay.darwin.custom()\` forms target
|
|
411
|
+
nix-darwin only. Overlays are direct fragments, so place them in a host or
|
|
412
|
+
profile array or return them from a feature.
|
|
413
|
+
|
|
414
|
+
## Project structure
|
|
415
|
+
|
|
416
|
+
Keep \`winix.config.ts\` as the workspace entrypoint. Small projects can stay
|
|
417
|
+
in one file. For larger projects, a predictable layout works well:
|
|
418
|
+
|
|
419
|
+
\`\`\`text
|
|
420
|
+
winix.config.ts
|
|
421
|
+
inputs.ts
|
|
422
|
+
features/
|
|
423
|
+
shell.ts
|
|
424
|
+
git.ts
|
|
425
|
+
profiles/
|
|
426
|
+
developer.ts
|
|
427
|
+
hosts/
|
|
428
|
+
workstation.ts
|
|
429
|
+
\`\`\`
|
|
430
|
+
|
|
431
|
+
Export feature and profile factories, not already-instantiated fragments, when
|
|
432
|
+
callers may need arguments or \`.isActive\`.
|
|
433
|
+
|
|
434
|
+
## Commands
|
|
435
|
+
|
|
436
|
+
- \`winix init\` creates a project and installs the Winix skill wrapper.
|
|
437
|
+
- \`winix install skill\` installs or refreshes the wrapper in an existing
|
|
438
|
+
project. Use \`--force\` if a different file already occupies its path.
|
|
439
|
+
- \`winix --skill\` prints these version-matched instructions. It has no side
|
|
440
|
+
effects.
|
|
441
|
+
- \`winix check [--strict] [--escape-report]\` validates the project.
|
|
442
|
+
- \`winix apply [--host NAME] [--dry] [--diff]\` generates backend output.
|
|
443
|
+
- \`winix switch [--host NAME] [--dry] [--yes]\` generates and activates one host, automatically cleaning up unused owned Windows packages and startup commands.
|
|
444
|
+
Prune is Windows-only and uninstalls unused Winix-owned packages.
|
|
445
|
+
- \`winix state forget startup <name>\` / \`winix state forget package <source> <id>\`
|
|
446
|
+
releases Windows removal ownership without deleting anything; accepts --dry.
|
|
447
|
+
- \`winix update [INPUTS...] [--dry] [--windows]\` updates Nix inputs or
|
|
448
|
+
Windows package locks.
|
|
449
|
+
- \`winix inspect\` prints host composition and fragment information.
|
|
450
|
+
|
|
451
|
+
On native Windows, real NixOS and nix-darwin activation is unsupported. Dry
|
|
452
|
+
runs still print commands with forward-slash flake references. Windows hosts
|
|
453
|
+
activate through \`winget configure\`.
|
|
454
|
+
|
|
455
|
+
## Editing rules for agents
|
|
456
|
+
|
|
457
|
+
- Make narrow structural edits. Add or change a feature, profile entry, host,
|
|
458
|
+
or input instead of rewriting the workspace.
|
|
459
|
+
- Reuse existing features before creating duplicates.
|
|
460
|
+
- Keep filesystem paths separate from generated Nix paths. Generated Nix paths
|
|
461
|
+
and flake references always use forward slashes.
|
|
462
|
+
- Do not add classes, inheritance, global registries, or runtime dependencies
|
|
463
|
+
to model configuration. Winix uses plain functions and fragment objects.
|
|
464
|
+
- Do not claim an option or helper exists because it is familiar from Nix.
|
|
465
|
+
Check the installed TypeScript types. Plain fragments remain available when
|
|
466
|
+
there is no curated helper.
|
|
467
|
+
- Treat \`winix check\` and \`winix apply --dry\` output as authoritative for
|
|
468
|
+
the installed version.
|
|
469
|
+
`;
|
|
470
|
+
export function renderSkill() {
|
|
471
|
+
return `${SKILL.trim()}\n`;
|
|
472
|
+
}
|
|
473
|
+
export function authoringApiPaths() {
|
|
474
|
+
return [
|
|
475
|
+
...CORE_AUTHORING_API,
|
|
476
|
+
...collectApiPaths("rawModule", rawModule),
|
|
477
|
+
...collectApiPaths("account", account),
|
|
478
|
+
...collectApiPaths("platforms", platforms),
|
|
479
|
+
...collectApiPaths("nix", nix),
|
|
480
|
+
...collectApiPaths("overlay", overlay),
|
|
481
|
+
...collectApiPaths("home", home),
|
|
482
|
+
...collectApiPaths("nixos", nixos),
|
|
483
|
+
...collectApiPaths("darwin", darwin),
|
|
484
|
+
...collectApiPaths("windows", windows),
|
|
485
|
+
];
|
|
486
|
+
}
|
|
487
|
+
function collectApiPaths(prefix, value) {
|
|
488
|
+
const paths = [prefix];
|
|
489
|
+
for (const [key, child] of Object.entries(value)) {
|
|
490
|
+
const path = `${prefix}.${key}`;
|
|
491
|
+
paths.push(path);
|
|
492
|
+
if (((typeof child === "object" && child !== null) || typeof child === "function") &&
|
|
493
|
+
!isNixExpr(child)) {
|
|
494
|
+
paths.push(...collectApiPaths(path, child).slice(1));
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
return paths;
|
|
498
|
+
}
|
|
499
|
+
function isNixExpr(value) {
|
|
500
|
+
return (typeof value === "object" &&
|
|
501
|
+
value !== null &&
|
|
502
|
+
"__winixNixExpr" in value);
|
|
503
|
+
}
|
package/dist/types/windows.d.ts
CHANGED
|
@@ -1,4 +1,61 @@
|
|
|
1
1
|
import type { ResourceRef } from "../core/types.js";
|
|
2
|
+
export type WinKnownFolderName = "documents" | "desktop" | "localAppData" | "appData" | "userProfile";
|
|
3
|
+
export interface WinKnownFolder {
|
|
4
|
+
kind: "knownFolder";
|
|
5
|
+
folder: WinKnownFolderName;
|
|
6
|
+
path: string;
|
|
7
|
+
}
|
|
8
|
+
export type WinFilePath = string | WinKnownFolder;
|
|
9
|
+
export type WinStartupWindowStyle = "normal" | "minimized" | "maximized";
|
|
10
|
+
export interface WinStartupCommand {
|
|
11
|
+
/** Absolute/environment-variable path, known-folder path, or application name on PATH. */
|
|
12
|
+
executable: WinFilePath;
|
|
13
|
+
/** Literal arguments; known-folder arguments are resolved during activation. */
|
|
14
|
+
arguments?: WinFilePath[];
|
|
15
|
+
/** Defaults to the current user's home directory. Must exist during activation. */
|
|
16
|
+
workingDirectory?: WinFilePath;
|
|
17
|
+
windowStyle?: WinStartupWindowStyle;
|
|
18
|
+
}
|
|
19
|
+
export interface WinPowerShellModule {
|
|
20
|
+
name: string;
|
|
21
|
+
repository: string;
|
|
22
|
+
}
|
|
23
|
+
export interface WinWslDistro {
|
|
24
|
+
name: string;
|
|
25
|
+
source: "nixos-wsl";
|
|
26
|
+
installLocation: WinFilePath;
|
|
27
|
+
default: boolean;
|
|
28
|
+
setup?: WinWslSetup;
|
|
29
|
+
}
|
|
30
|
+
export interface WinWslSetup {
|
|
31
|
+
/** Opts into executing trusted repository/npm code inside the distro. HTTPS only; never embed credentials. */
|
|
32
|
+
repository: string;
|
|
33
|
+
/** Branch, tag, full ref, or immutable commit; resolved into winix-windows.lock. Defaults to HEAD. */
|
|
34
|
+
ref?: string;
|
|
35
|
+
configDirectory: string;
|
|
36
|
+
host: string;
|
|
37
|
+
/** Absolute path inside the selected account's home. Defaults to <home>/dotfiles. */
|
|
38
|
+
checkout?: string;
|
|
39
|
+
/** Selects a normal account declared by the Linux host; inferred when unambiguous. */
|
|
40
|
+
user?: string;
|
|
41
|
+
}
|
|
42
|
+
export interface WinWslConfig {
|
|
43
|
+
wsl2?: {
|
|
44
|
+
memory?: string;
|
|
45
|
+
processors?: number;
|
|
46
|
+
swap?: string;
|
|
47
|
+
localhostForwarding?: boolean;
|
|
48
|
+
networkingMode?: "nat" | "mirrored" | "none" | "virtioproxy";
|
|
49
|
+
dnsTunneling?: boolean;
|
|
50
|
+
firewall?: boolean;
|
|
51
|
+
autoProxy?: boolean;
|
|
52
|
+
guiApplications?: boolean;
|
|
53
|
+
};
|
|
54
|
+
experimental?: {
|
|
55
|
+
autoMemoryReclaim?: "disabled" | "gradual" | "dropCache";
|
|
56
|
+
sparseVhd?: boolean;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
2
59
|
/**
|
|
3
60
|
* A winget package source. MVP supports the two first-party catalogues.
|
|
4
61
|
* Additional sources (chocolatey, scoop) can plug in later without changing
|
|
@@ -68,7 +125,7 @@ export interface WinRawCommand {
|
|
|
68
125
|
*
|
|
69
126
|
* Typed helpers (env/path) construct native DSC resources internally:
|
|
70
127
|
* `Microsoft.Windows/Registry` for env and
|
|
71
|
-
* `Microsoft.DSC.Transitional/
|
|
128
|
+
* `Microsoft.DSC.Transitional/PowerShellScript` for PATH/files/modules.
|
|
72
129
|
*/
|
|
73
130
|
export interface WinDscResource {
|
|
74
131
|
/**
|
|
@@ -112,6 +169,16 @@ export interface WinDscResource {
|
|
|
112
169
|
dependsOn?: ResourceRef[];
|
|
113
170
|
}
|
|
114
171
|
export type WinDscMetadata = {
|
|
172
|
+
kind: "optional-features";
|
|
173
|
+
names: string[];
|
|
174
|
+
enabled: boolean;
|
|
175
|
+
} | {
|
|
176
|
+
kind: "wsl-distro";
|
|
177
|
+
distro: WinWslDistro;
|
|
178
|
+
} | {
|
|
179
|
+
kind: "startup";
|
|
180
|
+
name: string;
|
|
181
|
+
} | {
|
|
115
182
|
kind: "env";
|
|
116
183
|
action: "set" | "remove";
|
|
117
184
|
name: string;
|
|
@@ -124,6 +191,20 @@ export type WinDscMetadata = {
|
|
|
124
191
|
scope: "user" | "machine";
|
|
125
192
|
} | {
|
|
126
193
|
kind: "setting";
|
|
194
|
+
} | {
|
|
195
|
+
kind: "powershell-module";
|
|
196
|
+
module: WinPowerShellModule;
|
|
197
|
+
} | {
|
|
198
|
+
kind: "file";
|
|
199
|
+
action: "text" | "symlink" | "copy" | "remove";
|
|
200
|
+
target: WinFilePath;
|
|
201
|
+
source?: string;
|
|
202
|
+
content?: string;
|
|
203
|
+
encoding: "utf8" | "utf8bom" | "ascii";
|
|
204
|
+
force: boolean;
|
|
205
|
+
backup: boolean;
|
|
206
|
+
recursive: boolean;
|
|
207
|
+
wslConfig?: boolean;
|
|
127
208
|
};
|
|
128
209
|
export type WinColorMode = "Light" | "Dark";
|
|
129
210
|
export type WinTaskbarAlignment = "Left" | "Center";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adrifer/winix",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4-preview.0",
|
|
4
4
|
"description": "TypeScript-first system configuration for NixOS, nix-darwin, and Home Manager",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Adrian Fernandez",
|
|
@@ -43,6 +43,8 @@
|
|
|
43
43
|
"winix": "dist/cli/index.js"
|
|
44
44
|
},
|
|
45
45
|
"files": [
|
|
46
|
+
"scripts/bootstrap-windows.ps1",
|
|
47
|
+
"scripts/bootstrap-nixos.sh",
|
|
46
48
|
"dist",
|
|
47
49
|
"types",
|
|
48
50
|
"index.d.ts",
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
set -euo pipefail
|
|
3
|
+
|
|
4
|
+
winix_require_nixos() {
|
|
5
|
+
if [[ ! -r /etc/os-release ]] || ! (source /etc/os-release; [[ "${ID:-}" == nixos ]]); then
|
|
6
|
+
printf '%s\n' 'Winix bootstrap requires an existing NixOS installation (including NixOS-WSL).' >&2
|
|
7
|
+
return 1
|
|
8
|
+
fi
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
winix_bootstrap_nixos() {
|
|
12
|
+
if [[ $# -gt 0 ]]; then
|
|
13
|
+
if [[ $# -eq 1 && ( "$1" == --help || "$1" == -h ) ]]; then
|
|
14
|
+
printf '%s\n' \
|
|
15
|
+
'Usage: bash bootstrap-nixos.sh' \
|
|
16
|
+
'Open a temporary Git, Node.js 24/npm, and Bash environment on NixOS.' \
|
|
17
|
+
'Nix downloads may populate the store; no profile or system configuration is changed.' \
|
|
18
|
+
'Clone your configuration, install its npm dependencies, and run Winix yourself.' \
|
|
19
|
+
'Type exit to leave the environment. No Winix installation or activation is performed.'
|
|
20
|
+
return
|
|
21
|
+
fi
|
|
22
|
+
printf '%s\n' 'Usage: bash bootstrap-nixos.sh [--help]' >&2
|
|
23
|
+
return 2
|
|
24
|
+
fi
|
|
25
|
+
|
|
26
|
+
winix_require_nixos || return
|
|
27
|
+
if ! command -v nix >/dev/null 2>&1; then
|
|
28
|
+
printf '%s\n' 'Nix is unavailable. Restore the NixOS Nix installation/PATH before running this bootstrap.' >&2
|
|
29
|
+
return 1
|
|
30
|
+
fi
|
|
31
|
+
|
|
32
|
+
# Keep the bootstrap independent of mutable registries and user channels.
|
|
33
|
+
local nixpkgs='github:NixOS/nixpkgs/0bb2eedc20e4739f29e8045034f2828ad7054f8f'
|
|
34
|
+
export NIX_CONFIG="${NIX_CONFIG:+$NIX_CONFIG$'\n'}extra-experimental-features = nix-command flakes"
|
|
35
|
+
printf '%s\n' \
|
|
36
|
+
'Opening the Winix prerequisite shell (Git, Node.js 24/npm, Bash).' \
|
|
37
|
+
'The first run may download packages to the Nix store.' \
|
|
38
|
+
'No repositories are cloned, npm dependencies installed, or hosts activated.' \
|
|
39
|
+
'Clone your config into a permanent location and run npm install and Winix yourself.' \
|
|
40
|
+
'Type exit to leave. Declare permanent tools/Nix settings in your own configuration.'
|
|
41
|
+
|
|
42
|
+
exec nix shell --no-write-lock-file \
|
|
43
|
+
"$nixpkgs#git" \
|
|
44
|
+
"$nixpkgs#nodejs_24" \
|
|
45
|
+
"$nixpkgs#bashInteractive" \
|
|
46
|
+
--command bash --noprofile --norc -i
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
|
|
50
|
+
winix_bootstrap_nixos "$@"
|
|
51
|
+
fi
|