@adrifer/winix 0.2.1 → 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 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:
@@ -333,6 +343,53 @@ licenses that aren't a simple `pkgs.lib.licenses.<id>` lookup. See
333
343
  [`spec/proposals/binary-release.md`](spec/proposals/binary-release.md)
334
344
  for the full reference.
335
345
 
346
+ Release assets can also be raw executables. Set `format: "raw"` explicitly;
347
+ Winix never guesses that an extensionless file is executable. The format is
348
+ per-platform, so raw and archive assets can be mixed in one release:
349
+
350
+ ```ts
351
+ home.packages(
352
+ nix.binaryRelease({
353
+ name: "herdr",
354
+ version: "0.8.2",
355
+ binary: "herdr",
356
+ urlTemplate:
357
+ "https://github.com/herdrdev/herdr/releases/download/v{version}/{file}",
358
+ platforms: {
359
+ "x86_64-linux": {
360
+ file: "herdr-linux-x86_64",
361
+ hash: "sha256-...",
362
+ format: "raw",
363
+ },
364
+ "aarch64-linux": {
365
+ file: "herdr-linux-aarch64",
366
+ hash: "sha256-...",
367
+ format: "raw",
368
+ },
369
+ "x86_64-darwin": {
370
+ file: "herdr-macos-x86_64",
371
+ hash: "sha256-...",
372
+ format: "raw",
373
+ },
374
+ "aarch64-darwin": {
375
+ file: "herdr-macos-aarch64",
376
+ hash: "sha256-...",
377
+ format: "raw",
378
+ },
379
+ },
380
+ meta: {
381
+ description: "The runtime your coding agents live on",
382
+ homepage: "https://github.com/herdrdev/herdr",
383
+ license: "asl20",
384
+ },
385
+ }),
386
+ );
387
+ ```
388
+
389
+ When `format` is omitted, `.zip`, `.tar.gz`, and `.tgz` filenames retain the
390
+ legacy extension-based archive behavior. Other extensions are rejected unless
391
+ a supported format (`"raw"`, `"zip"`, `"tar.gz"`, or `"tgz"`) is explicit.
392
+
336
393
  For bigger migrations, import existing Nix modules:
337
394
 
338
395
  ```ts
@@ -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, {
@@ -3,7 +3,7 @@ export type { AccountGroupFactory, AccountGroupMember, AccountGroupOpts, Account
3
3
  export { platforms } from "./platforms.js";
4
4
  export type { DarwinPlatformOpts, NixosPlatformOpts, WindowsPlatformOpts, PlatformsHelper } from "./platforms.js";
5
5
  export { nix } from "./nix.js";
6
- export type { BinaryReleaseArch, BinaryReleaseCompletions, BinaryReleaseMeta, BinaryReleaseOpts, BinaryReleasePlatform, NixNamespace, PkgHelper, ScriptHelper, } from "./nix.js";
6
+ export type { BinaryReleaseArch, BinaryReleaseCompletions, BinaryReleaseFormat, BinaryReleaseMeta, BinaryReleaseOpts, BinaryReleasePlatform, NixNamespace, PkgHelper, ScriptHelper, } from "./nix.js";
7
7
  export { overlay } from "./overlay.js";
8
8
  export type { OverlayHelper } from "./overlay.js";
9
9
  export { home } from "./home.js";
@@ -30,8 +30,9 @@ export interface NixNamespace {
30
30
  *
31
31
  * Picks the right `(file, hash)` per `pkgs.stdenv.hostPlatform.system`,
32
32
  * substitutes `{version}`, `{file}`, and (optionally) `{platform}` into
33
- * `urlTemplate`, fetches with `pkgs.fetchurl`, unpacks tarballs/zips,
34
- * and `install -Dm755`s the binary into `$out/bin/<binary>`.
33
+ * `urlTemplate`, fetches with `pkgs.fetchurl`, unpacks tarballs/zips (or
34
+ * directly installs raw executables), and `install -Dm755`s the binary
35
+ * into `$out/bin/<binary>`.
35
36
  *
36
37
  * Optional extensions:
37
38
  * - `completions` — emits `installShellCompletion` for `bash`/`fish`/`zsh`.
@@ -79,11 +80,15 @@ export interface NixNamespace {
79
80
  }
80
81
  /** Supported `(os, arch)` strings for `nix.binaryRelease`. */
81
82
  export type BinaryReleaseArch = "x86_64-linux" | "aarch64-linux" | "x86_64-darwin" | "aarch64-darwin";
83
+ export type BinaryReleaseFormat = "raw" | "zip" | "tar.gz" | "tgz";
82
84
  export interface BinaryReleasePlatform {
83
85
  /** Filename to download (substituted into `urlTemplate`'s `{file}`). */
84
86
  file: string;
85
- /** SRI hash (`sha256-...`) of the downloaded archive. */
87
+ /** SRI hash (`sha256-...`) of the downloaded file. */
86
88
  hash: string;
89
+ /** Download format. When omitted, archive format is inferred from `file`.
90
+ * Raw executables must explicitly set `"raw"`. */
91
+ format?: BinaryReleaseFormat;
87
92
  /** Optional: name of the extracted binary, if it differs from the outer `binary`. */
88
93
  binary?: string;
89
94
  /** Optional: vendor-specific platform tag substituted into `urlTemplate`'s `{platform}`
@@ -73,6 +73,12 @@ const KNOWN_BINARY_RELEASE_ARCHES = [
73
73
  "x86_64-darwin",
74
74
  "aarch64-darwin",
75
75
  ];
76
+ const KNOWN_BINARY_RELEASE_FORMATS = [
77
+ "raw",
78
+ "zip",
79
+ "tar.gz",
80
+ "tgz",
81
+ ];
76
82
  function binaryRelease(opts) {
77
83
  if (!opts || typeof opts !== "object") {
78
84
  throw new Error("nix.binaryRelease: `opts` is required");
@@ -118,6 +124,7 @@ function binaryRelease(opts) {
118
124
  if (!platform.hash) {
119
125
  throw new Error(`nix.binaryRelease: platforms.${arch}.hash is required`);
120
126
  }
127
+ resolveBinaryReleaseFormat(arch, platform);
121
128
  }
122
129
  const usesPlatformPlaceholder = opts.urlTemplate.includes("{platform}");
123
130
  if (usesPlatformPlaceholder) {
@@ -133,6 +140,7 @@ function binaryRelease(opts) {
133
140
  `file = ${nixStringLiteral(platform.file)};`,
134
141
  `hash = ${nixStringLiteral(platform.hash)};`,
135
142
  `binary = ${nixStringLiteral(platform.binary ?? opts.binary)};`,
143
+ `format = ${nixStringLiteral(resolveBinaryReleaseFormat(arch, platform))};`,
136
144
  ];
137
145
  if (usesPlatformPlaceholder) {
138
146
  const platformName = platform.platform;
@@ -208,14 +216,16 @@ in pkgs.stdenvNoCC.mkDerivation {
208
216
 
209
217
  nativeBuildInputs = ${nativeBuildInputsExpr};${linuxBuildInputs}${dontStripLine}
210
218
 
219
+ dontUnpack = source.format == "raw";
220
+
211
221
  unpackPhase = ''
212
222
  runHook preUnpack
213
223
  mkdir source
214
- case "$src" in
215
- *.zip) unzip -q "$src" -d source ;;
216
- *.tar.gz) tar -xzf "$src" -C source ;;
217
- *.tgz) tar -xzf "$src" -C source ;;
218
- *) echo "nix.binaryRelease: unsupported archive extension for $src" >&2; exit 1 ;;
224
+ case "\${source.format}" in
225
+ zip) unzip -q "$src" -d source ;;
226
+ tar.gz) tar -xzf "$src" -C source ;;
227
+ tgz) tar -xzf "$src" -C source ;;
228
+ *) echo "nix.binaryRelease: unsupported archive format \${source.format}" >&2; exit 1 ;;
219
229
  esac
220
230
  sourceRoot=source
221
231
  runHook postUnpack
@@ -223,7 +233,11 @@ in pkgs.stdenvNoCC.mkDerivation {
223
233
 
224
234
  installPhase = ''
225
235
  runHook preInstall
226
- install -Dm755 "\${source.binary}" "$out/bin/${opts.binary}"${extraInstallBlock}
236
+ installSource="$src"
237
+ if [ "\${source.format}" != raw ]; then
238
+ installSource="\${source.binary}"
239
+ fi
240
+ install -Dm755 "$installSource" "$out/bin/${opts.binary}"${extraInstallBlock}
227
241
  runHook postInstall
228
242
  '';${completionsBlock}
229
243
 
@@ -233,6 +247,21 @@ ${metaLines.join("\n")}
233
247
  })`;
234
248
  return expr(text);
235
249
  }
250
+ function resolveBinaryReleaseFormat(arch, platform) {
251
+ if (platform.format !== undefined) {
252
+ if (!KNOWN_BINARY_RELEASE_FORMATS.includes(platform.format)) {
253
+ throw new Error(`nix.binaryRelease: platforms.${arch}.format must be one of "raw", "zip", "tar.gz", or "tgz"`);
254
+ }
255
+ return platform.format;
256
+ }
257
+ if (platform.file.endsWith(".tar.gz"))
258
+ return "tar.gz";
259
+ if (platform.file.endsWith(".tgz"))
260
+ return "tgz";
261
+ if (platform.file.endsWith(".zip"))
262
+ return "zip";
263
+ throw new Error(`nix.binaryRelease: platforms.${arch}.file has an unsupported archive extension; set \`format\` explicitly`);
264
+ }
236
265
  function renderBuildInput(value) {
237
266
  if (isNixExpr(value))
238
267
  return value.expr;
package/dist/index.d.ts CHANGED
@@ -9,4 +9,4 @@ export type { NixOutput } from "./backends/nix/index.js";
9
9
  export { generateWindows, isWindowsHost } from "./backends/windows/index.js";
10
10
  export type { WindowsOutput, WindowsHostOutput } from "./backends/windows/index.js";
11
11
  export { account, darwin, home, nix, nixos, overlay, platforms, windows } from "./helpers/index.js";
12
- export type { AccountGroupFactory, AccountGroupMember, AccountGroupOpts, AccountNamespace, AccountOpts, AccountUserFactory, AccountUserRef, ActivationOpts, BinaryReleaseArch, BinaryReleaseCompletions, BinaryReleaseMeta, BinaryReleaseOpts, BinaryReleasePlatform, DarwinHelper, DarwinPlatformOpts, DarwinProgramOptions, DarwinServiceOptions, HomeHelper, HomeProgramOptions, HomeServiceOptions, LaunchdHelper, NixNamespace, NixosHelper, NixosPlatformOpts, NixosProgramOptions, NixosServiceOptions, OverlayHelper, PkgHelper, PlatformsHelper, ScriptHelper, SysctlSettings, SystemdHelper, VirtualisationHelper, WindowsHelper, WindowsPlatformOpts, WinEnvNamespace, WinEnvOpts, WinEnvScope, WinFileEncoding, WinFileNamespace, WinFileOpts, WinPackageArg, WinPackageSpec, WinPathNamespace, WinRawCommandArg, WinRawCommandSpec, WinSettingOpts } from "./helpers/index.js";
12
+ export type { AccountGroupFactory, AccountGroupMember, AccountGroupOpts, AccountNamespace, AccountOpts, AccountUserFactory, AccountUserRef, ActivationOpts, BinaryReleaseArch, BinaryReleaseCompletions, BinaryReleaseFormat, BinaryReleaseMeta, BinaryReleaseOpts, BinaryReleasePlatform, DarwinHelper, DarwinPlatformOpts, DarwinProgramOptions, DarwinServiceOptions, HomeHelper, HomeProgramOptions, HomeServiceOptions, LaunchdHelper, NixNamespace, NixosHelper, NixosPlatformOpts, NixosProgramOptions, NixosServiceOptions, OverlayHelper, PkgHelper, PlatformsHelper, ScriptHelper, SysctlSettings, SystemdHelper, VirtualisationHelper, WindowsHelper, WindowsPlatformOpts, WinEnvNamespace, WinEnvOpts, WinEnvScope, WinFileEncoding, WinFileNamespace, WinFileOpts, WinPackageArg, WinPackageSpec, WinPathNamespace, WinRawCommandArg, WinRawCommandSpec, WinSettingOpts } from "./helpers/index.js";
@@ -0,0 +1,2 @@
1
+ export declare function renderSkill(): string;
2
+ export declare function authoringApiPaths(): string[];
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
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adrifer/winix",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "TypeScript-first system configuration for NixOS, nix-darwin, and Home Manager",
5
5
  "license": "MIT",
6
6
  "author": "Adrian Fernandez",