@adrifer/winix 0.2.2 → 0.2.3
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 +10 -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/index.js +32 -1
- package/dist/skill.d.ts +2 -0
- package/dist/skill.js +394 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -111,6 +111,15 @@ npm install @adrifer/winix
|
|
|
111
111
|
|
|
112
112
|
The `init` command creates a starter `winix.config.ts`, `tsconfig.json`, `.gitignore`, and package scripts. After `npm install`, the `winix` binary comes from your local `node_modules`, so commands are reproducible through `package-lock.json`.
|
|
113
113
|
|
|
114
|
+
It also installs `.agents/skills/winix/SKILL.md`, a small agent skill wrapper.
|
|
115
|
+
The wrapper tells agents to run `winix --skill`, so the full instructions always
|
|
116
|
+
come from the same installed package version as the executable. Existing
|
|
117
|
+
projects can install it with:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
winix install skill
|
|
121
|
+
```
|
|
122
|
+
|
|
114
123
|
You can also install it globally, but local project installs are recommended:
|
|
115
124
|
|
|
116
125
|
```bash
|
|
@@ -129,6 +138,7 @@ npx @adrifer/winix apply --diff # show changes against current .winix/
|
|
|
129
138
|
npx @adrifer/winix switch --host my-host # generate and run nixos-rebuild/darwin-rebuild
|
|
130
139
|
npx @adrifer/winix update # update generated flake.lock and copy it back
|
|
131
140
|
npx @adrifer/winix inspect # inspect host composition and fragments
|
|
141
|
+
npx @adrifer/winix --skill # print version-matched agent instructions
|
|
132
142
|
```
|
|
133
143
|
|
|
134
144
|
If you add scripts to your `package.json`, you can use shorter commands:
|
|
@@ -2,6 +2,7 @@ import { join } from "node:path";
|
|
|
2
2
|
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
3
3
|
import { existsSync } from "node:fs";
|
|
4
4
|
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { installSkill } from "./install.js";
|
|
5
6
|
export async function init(cwd, opts) {
|
|
6
7
|
await mkdir(cwd, { recursive: true });
|
|
7
8
|
const versionRange = await resolveWinixVersionRange();
|
|
@@ -10,6 +11,7 @@ export async function init(cwd, opts) {
|
|
|
10
11
|
await writeIfAllowed(join(cwd, "tsconfig.json"), TSCONFIG, opts.force);
|
|
11
12
|
await writeIfAllowed(join(cwd, "package.json"), packageJson, opts.force);
|
|
12
13
|
await writeIfAllowed(join(cwd, ".gitignore"), GITIGNORE, opts.force);
|
|
14
|
+
await installSkill(cwd, { force: opts.force });
|
|
13
15
|
console.log("✓ Initialized Winix project");
|
|
14
16
|
console.log("");
|
|
15
17
|
console.log("Next steps:");
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export declare const SKILL_WRAPPER_PATH: string;
|
|
2
|
+
interface InstallSkillOptions {
|
|
3
|
+
force: boolean;
|
|
4
|
+
}
|
|
5
|
+
export declare function installSkill(cwd: string, opts: InstallSkillOptions): Promise<"installed" | "current">;
|
|
6
|
+
export declare const SKILL_WRAPPER = "---\nname: winix\ndescription: Use Winix to create, change, validate, generate, or activate typed system configuration for NixOS, nix-darwin, Home Manager, and Windows. Invoke when the user mentions Winix or asks to work on a Winix configuration.\n---\n\n# Winix\n\nThe installed Winix binary is the authoritative source for its current agent\ninstructions. Before answering a Winix question or editing a Winix project,\nload the version-matched skill:\n\n```bash\nwinix --skill\n```\n\nFollow the returned instructions for the rest of the task. Do not rely on a\npreviously cached or remembered copy. Winix commands, helpers, configuration\nstructure, platform support, and safety requirements may change between\ninstalled versions.\n\nRunning `winix --skill` only prints instructions. It does not evaluate a\nconfiguration, generate files, activate a host, or modify the project.\n";
|
|
7
|
+
export {};
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
export const SKILL_WRAPPER_PATH = join(".agents", "skills", "winix", "SKILL.md");
|
|
5
|
+
export async function installSkill(cwd, opts) {
|
|
6
|
+
const path = join(cwd, SKILL_WRAPPER_PATH);
|
|
7
|
+
if (existsSync(path)) {
|
|
8
|
+
const current = await readFile(path, "utf-8");
|
|
9
|
+
if (current === SKILL_WRAPPER)
|
|
10
|
+
return "current";
|
|
11
|
+
if (!opts.force) {
|
|
12
|
+
throw new Error(`${path} already exists. Re-run with --force to overwrite.`);
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
await mkdir(join(cwd, ".agents", "skills", "winix"), { recursive: true });
|
|
16
|
+
await writeFile(path, SKILL_WRAPPER);
|
|
17
|
+
return "installed";
|
|
18
|
+
}
|
|
19
|
+
export const SKILL_WRAPPER = `---
|
|
20
|
+
name: winix
|
|
21
|
+
description: Use Winix to create, change, validate, generate, or activate typed system configuration for NixOS, nix-darwin, Home Manager, and Windows. Invoke when the user mentions Winix or asks to work on a Winix configuration.
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
# Winix
|
|
25
|
+
|
|
26
|
+
The installed Winix binary is the authoritative source for its current agent
|
|
27
|
+
instructions. Before answering a Winix question or editing a Winix project,
|
|
28
|
+
load the version-matched skill:
|
|
29
|
+
|
|
30
|
+
\`\`\`bash
|
|
31
|
+
winix --skill
|
|
32
|
+
\`\`\`
|
|
33
|
+
|
|
34
|
+
Follow the returned instructions for the rest of the task. Do not rely on a
|
|
35
|
+
previously cached or remembered copy. Winix commands, helpers, configuration
|
|
36
|
+
structure, platform support, and safety requirements may change between
|
|
37
|
+
installed versions.
|
|
38
|
+
|
|
39
|
+
Running \`winix --skill\` only prints instructions. It does not evaluate a
|
|
40
|
+
configuration, generate files, activate a host, or modify the project.
|
|
41
|
+
`;
|
package/dist/cli/index.js
CHANGED
|
@@ -4,9 +4,11 @@ import { parseArgs } from "node:util";
|
|
|
4
4
|
import { apply } from "./commands/apply.js";
|
|
5
5
|
import { check } from "./commands/check.js";
|
|
6
6
|
import { init } from "./commands/init.js";
|
|
7
|
+
import { installSkill } from "./commands/install.js";
|
|
7
8
|
import { inspect } from "./commands/inspect.js";
|
|
8
9
|
import { switchCommand } from "./commands/switch.js";
|
|
9
10
|
import { update } from "./commands/update.js";
|
|
11
|
+
import { renderSkill } from "../skill.js";
|
|
10
12
|
const { positionals, values } = parseArgs({
|
|
11
13
|
allowPositionals: true,
|
|
12
14
|
options: {
|
|
@@ -16,17 +18,27 @@ const { positionals, values } = parseArgs({
|
|
|
16
18
|
windows: { type: "boolean", default: false },
|
|
17
19
|
strict: { type: "boolean", default: false },
|
|
18
20
|
force: { type: "boolean", default: false },
|
|
21
|
+
skill: { type: "boolean", default: false },
|
|
19
22
|
"escape-report": { type: "boolean", default: false },
|
|
20
23
|
help: { type: "boolean", short: "h", default: false },
|
|
21
24
|
},
|
|
22
25
|
});
|
|
23
26
|
const command = positionals[0];
|
|
27
|
+
if (values.skill) {
|
|
28
|
+
if (command) {
|
|
29
|
+
console.error("The --skill option does not accept a command.");
|
|
30
|
+
process.exit(2);
|
|
31
|
+
}
|
|
32
|
+
process.stdout.write(renderSkill());
|
|
33
|
+
process.exit(0);
|
|
34
|
+
}
|
|
24
35
|
if (values.help || !command) {
|
|
25
36
|
console.log(`
|
|
26
37
|
winix - TypeScript-first system configuration
|
|
27
38
|
|
|
28
39
|
Commands:
|
|
29
40
|
init Scaffold a Winix project
|
|
41
|
+
install skill Install the agent skill wrapper
|
|
30
42
|
apply Generate backend output in .winix/out/
|
|
31
43
|
check Validate configuration
|
|
32
44
|
switch Generate output and run the host activation command
|
|
@@ -40,11 +52,14 @@ Options:
|
|
|
40
52
|
--windows Resolve Windows package lockfile (update)
|
|
41
53
|
--strict Treat conflicts as errors (check)
|
|
42
54
|
--escape-report Show escape hatch usage (check)
|
|
43
|
-
--force Overwrite files (init)
|
|
55
|
+
--force Overwrite files (init, install skill)
|
|
56
|
+
--skill Print version-matched agent instructions
|
|
44
57
|
-h, --help Show this help
|
|
45
58
|
|
|
46
59
|
Examples:
|
|
47
60
|
winix init
|
|
61
|
+
winix install skill
|
|
62
|
+
winix --skill
|
|
48
63
|
winix apply
|
|
49
64
|
winix apply --dry
|
|
50
65
|
winix apply --host wsl-work
|
|
@@ -66,6 +81,22 @@ switch (command) {
|
|
|
66
81
|
process.exit(1);
|
|
67
82
|
}
|
|
68
83
|
break;
|
|
84
|
+
case "install":
|
|
85
|
+
if (positionals[1] !== "skill" || positionals.length !== 2) {
|
|
86
|
+
console.error("Usage: winix install skill [--force]");
|
|
87
|
+
process.exit(2);
|
|
88
|
+
}
|
|
89
|
+
try {
|
|
90
|
+
const result = await installSkill(cwd, { force: values.force });
|
|
91
|
+
console.log(result === "current"
|
|
92
|
+
? "✓ Winix skill wrapper is already current"
|
|
93
|
+
: "✓ Installed Winix skill wrapper");
|
|
94
|
+
}
|
|
95
|
+
catch (err) {
|
|
96
|
+
console.error(`\u2717 Error: ${err.message}`);
|
|
97
|
+
process.exit(1);
|
|
98
|
+
}
|
|
99
|
+
break;
|
|
69
100
|
case "apply":
|
|
70
101
|
try {
|
|
71
102
|
await apply(cwd, {
|
package/dist/skill.d.ts
ADDED
package/dist/skill.js
ADDED
|
@@ -0,0 +1,394 @@
|
|
|
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.dsc()\` declares an arbitrary DSC resource.
|
|
270
|
+
- \`windows.raw()\` runs a command on every apply. It is not idempotent, so use
|
|
271
|
+
a typed helper or \`windows.dsc()\` when possible.
|
|
272
|
+
|
|
273
|
+
Floating Windows packages are resolved into \`winix-windows.lock\`. Keep that
|
|
274
|
+
file in version control for deterministic, offline applies.
|
|
275
|
+
|
|
276
|
+
## Nix values and escape hatches
|
|
277
|
+
|
|
278
|
+
Import \`nix\` at file scope. It builds values and does not declare fragments:
|
|
279
|
+
|
|
280
|
+
- \`nix.expr()\` emits a raw Nix expression.
|
|
281
|
+
- \`nix.pkg()\` and \`nix.pkg.stable()\` reference packages.
|
|
282
|
+
- \`nix.bin()\`, \`nix.homePath()\`, and \`nix.pkgPath()\` build executable
|
|
283
|
+
and path expressions.
|
|
284
|
+
- \`nix.str\`, \`nix.script\`, and \`nix.script.raw\` are template helpers.
|
|
285
|
+
- \`nix.concat()\`, \`nix.withPkgs()\`, \`nix.optionalAttrs()\`, and
|
|
286
|
+
\`nix.optionalString()\` build common expressions.
|
|
287
|
+
- \`nix.isDarwin\` and \`nix.isLinux\` are Nix-side conditions.
|
|
288
|
+
- \`nix.binaryRelease()\` builds a package for a prebuilt CLI release.
|
|
289
|
+
- \`nix.lib.mkDefault()\`, \`nix.lib.mkForce()\`, \`nix.lib.mkBefore()\`,
|
|
290
|
+
\`nix.lib.mkAfter()\`, \`nix.lib.optionalAttrs()\`, and
|
|
291
|
+
\`nix.lib.optionalString()\` expose common library operations.
|
|
292
|
+
|
|
293
|
+
Prefer typed helpers. Use \`nix.expr()\`, platform \`.raw()\` helpers, and
|
|
294
|
+
\`rawModule()\` only when the typed model cannot express the configuration.
|
|
295
|
+
|
|
296
|
+
\`rawModule("./legacy/system.nix")\` imports a workspace-relative NixOS module.
|
|
297
|
+
Use \`rawModule.homeManager()\` or \`rawModule.darwin()\` for those scopes.
|
|
298
|
+
Paths must be relative POSIX paths ending in \`.nix\`.
|
|
299
|
+
|
|
300
|
+
## Overlays
|
|
301
|
+
|
|
302
|
+
Use \`overlay.stable(inputName)\` to expose a stable package set and
|
|
303
|
+
\`overlay.custom(expression)\` for a custom overlay. The
|
|
304
|
+
\`overlay.darwin.stable()\` and \`overlay.darwin.custom()\` forms target
|
|
305
|
+
nix-darwin only. Overlays are direct fragments, so place them in a host or
|
|
306
|
+
profile array or return them from a feature.
|
|
307
|
+
|
|
308
|
+
## Project structure
|
|
309
|
+
|
|
310
|
+
Keep \`winix.config.ts\` as the workspace entrypoint. Small projects can stay
|
|
311
|
+
in one file. For larger projects, a predictable layout works well:
|
|
312
|
+
|
|
313
|
+
\`\`\`text
|
|
314
|
+
winix.config.ts
|
|
315
|
+
inputs.ts
|
|
316
|
+
features/
|
|
317
|
+
shell.ts
|
|
318
|
+
git.ts
|
|
319
|
+
profiles/
|
|
320
|
+
developer.ts
|
|
321
|
+
hosts/
|
|
322
|
+
workstation.ts
|
|
323
|
+
\`\`\`
|
|
324
|
+
|
|
325
|
+
Export feature and profile factories, not already-instantiated fragments, when
|
|
326
|
+
callers may need arguments or \`.isActive\`.
|
|
327
|
+
|
|
328
|
+
## Commands
|
|
329
|
+
|
|
330
|
+
- \`winix init\` creates a project and installs the Winix skill wrapper.
|
|
331
|
+
- \`winix install skill\` installs or refreshes the wrapper in an existing
|
|
332
|
+
project. Use \`--force\` if a different file already occupies its path.
|
|
333
|
+
- \`winix --skill\` prints these version-matched instructions. It has no side
|
|
334
|
+
effects.
|
|
335
|
+
- \`winix check [--strict] [--escape-report]\` validates the project.
|
|
336
|
+
- \`winix apply [--host NAME] [--dry] [--diff]\` generates backend output.
|
|
337
|
+
- \`winix switch [--host NAME] [--dry]\` generates and activates one host.
|
|
338
|
+
- \`winix update [INPUTS...] [--dry] [--windows]\` updates Nix inputs or
|
|
339
|
+
Windows package locks.
|
|
340
|
+
- \`winix inspect\` prints host composition and fragment information.
|
|
341
|
+
|
|
342
|
+
On native Windows, real NixOS and nix-darwin activation is unsupported. Dry
|
|
343
|
+
runs still print commands with forward-slash flake references. Windows hosts
|
|
344
|
+
activate through \`winget configure\`.
|
|
345
|
+
|
|
346
|
+
## Editing rules for agents
|
|
347
|
+
|
|
348
|
+
- Make narrow structural edits. Add or change a feature, profile entry, host,
|
|
349
|
+
or input instead of rewriting the workspace.
|
|
350
|
+
- Reuse existing features before creating duplicates.
|
|
351
|
+
- Keep filesystem paths separate from generated Nix paths. Generated Nix paths
|
|
352
|
+
and flake references always use forward slashes.
|
|
353
|
+
- Do not add classes, inheritance, global registries, or runtime dependencies
|
|
354
|
+
to model configuration. Winix uses plain functions and fragment objects.
|
|
355
|
+
- Do not claim an option or helper exists because it is familiar from Nix.
|
|
356
|
+
Check the installed TypeScript types. Plain fragments remain available when
|
|
357
|
+
there is no curated helper.
|
|
358
|
+
- Treat \`winix check\` and \`winix apply --dry\` output as authoritative for
|
|
359
|
+
the installed version.
|
|
360
|
+
`;
|
|
361
|
+
export function renderSkill() {
|
|
362
|
+
return `${SKILL.trim()}\n`;
|
|
363
|
+
}
|
|
364
|
+
export function authoringApiPaths() {
|
|
365
|
+
return [
|
|
366
|
+
...CORE_AUTHORING_API,
|
|
367
|
+
...collectApiPaths("rawModule", rawModule),
|
|
368
|
+
...collectApiPaths("account", account),
|
|
369
|
+
...collectApiPaths("platforms", platforms),
|
|
370
|
+
...collectApiPaths("nix", nix),
|
|
371
|
+
...collectApiPaths("overlay", overlay),
|
|
372
|
+
...collectApiPaths("home", home),
|
|
373
|
+
...collectApiPaths("nixos", nixos),
|
|
374
|
+
...collectApiPaths("darwin", darwin),
|
|
375
|
+
...collectApiPaths("windows", windows),
|
|
376
|
+
];
|
|
377
|
+
}
|
|
378
|
+
function collectApiPaths(prefix, value) {
|
|
379
|
+
const paths = [prefix];
|
|
380
|
+
for (const [key, child] of Object.entries(value)) {
|
|
381
|
+
const path = `${prefix}.${key}`;
|
|
382
|
+
paths.push(path);
|
|
383
|
+
if (((typeof child === "object" && child !== null) || typeof child === "function") &&
|
|
384
|
+
!isNixExpr(child)) {
|
|
385
|
+
paths.push(...collectApiPaths(path, child).slice(1));
|
|
386
|
+
}
|
|
387
|
+
}
|
|
388
|
+
return paths;
|
|
389
|
+
}
|
|
390
|
+
function isNixExpr(value) {
|
|
391
|
+
return (typeof value === "object" &&
|
|
392
|
+
value !== null &&
|
|
393
|
+
"__winixNixExpr" in value);
|
|
394
|
+
}
|