@adrifer/winix 0.1.2-preview.3 → 0.1.2

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
@@ -1,5 +1,11 @@
1
1
  # Winix
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/%40adrifer%2Fwinix?label=npm&logo=npm)](https://www.npmjs.com/package/@adrifer/winix)
4
+ [![npm preview](https://img.shields.io/npm/v/%40adrifer%2Fwinix/preview?label=preview&logo=npm&color=orange)](https://www.npmjs.com/package/@adrifer/winix?activeTab=versions)
5
+ [![CI](https://github.com/adrifer/winix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/adrifer/winix/actions/workflows/ci.yml)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
7
+ [![TypeScript](https://img.shields.io/badge/types-TypeScript-blue?logo=typescript&logoColor=white)](./types)
8
+
3
9
  **TypeScript-first system configuration for NixOS, nix-darwin, and Home Manager.**
4
10
 
5
11
  Winix lets you write system configuration as typed, composable TypeScript fragments and generates a normal Nix flake that `nixos-rebuild`, `darwin-rebuild`, and Home Manager can consume.
@@ -267,6 +273,42 @@ nix.script`
267
273
  nix.lib.mkForce(["https://cache.nixos.org/"])
268
274
  ```
269
275
 
276
+ For prebuilt single-binary CLI releases (the `azd`, `gh`, `kubectl`,
277
+ `1password` family), use `nix.binaryRelease()` instead of hand-rolling
278
+ the `stdenvNoCC.mkDerivation` boilerplate:
279
+
280
+ ```ts
281
+ home.packages(
282
+ nix.binaryRelease({
283
+ name: "azure-dev-cli",
284
+ version: "1.25.5",
285
+ binary: "azd",
286
+ urlTemplate:
287
+ "https://github.com/Azure/azure-dev/releases/download/azure-dev-cli_{version}/{file}",
288
+ platforms: {
289
+ "x86_64-linux": { file: "azd-linux-amd64.tar.gz", hash: "sha256-..." },
290
+ "aarch64-linux": { file: "azd-linux-arm64.tar.gz", hash: "sha256-..." },
291
+ "x86_64-darwin": { file: "azd-darwin-amd64.zip", hash: "sha256-..." },
292
+ "aarch64-darwin":{ file: "azd-darwin-arm64.zip", hash: "sha256-..." },
293
+ },
294
+ meta: {
295
+ description: "Azure Developer CLI",
296
+ homepage: "https://github.com/Azure/azure-dev",
297
+ license: "mit",
298
+ },
299
+ }),
300
+ );
301
+ ```
302
+
303
+ Supports per-platform `{platform}` URL placeholders (for vendors whose
304
+ URLs aren't just `${file}`), shell completions via `installShellFiles`,
305
+ optional `autoPatchelfHook` on Linux, and a validated `meta.license`
306
+ (rejects SPDX-style ids like `MIT`/`Apache-2.0` at TS-eval time so misuse
307
+ surfaces immediately, not at Nix build time). Pass `nix.expr(...)` for
308
+ licenses that aren't a simple `pkgs.lib.licenses.<id>` lookup. See
309
+ [`spec/proposals/binary-release.md`](spec/proposals/binary-release.md)
310
+ for the full reference.
311
+
270
312
  For bigger migrations, import existing Nix modules:
271
313
 
272
314
  ```ts
@@ -14,6 +14,49 @@ export interface NixNamespace {
14
14
  optionalString(condition: NixCondition, value: NixStringPart): NixExpr;
15
15
  isDarwin: NixExpr;
16
16
  isLinux: NixExpr;
17
+ /**
18
+ * Build a `stdenvNoCC.mkDerivation` for a prebuilt single-binary CLI
19
+ * release (the `azd`, `gh`, `kubectl`, `1password` family).
20
+ *
21
+ * Picks the right `(file, hash)` per `pkgs.stdenv.hostPlatform.system`,
22
+ * substitutes `{version}`, `{file}`, and (optionally) `{platform}` into
23
+ * `urlTemplate`, fetches with `pkgs.fetchurl`, unpacks tarballs/zips,
24
+ * and `install -Dm755`s the binary into `$out/bin/<binary>`.
25
+ *
26
+ * Optional extensions:
27
+ * - `completions` — emits `installShellCompletion` for `bash`/`fish`/`zsh`.
28
+ * - `linuxPatchelf` — enables `autoPatchelfHook` on Linux only.
29
+ * - `linuxBuildInputs` — extra runtime libs the auto-patchelf hook needs.
30
+ * - `dontStripDarwin` — keep the binary's Mach-O signature intact (default `true`).
31
+ *
32
+ * `meta.license` accepts a nixpkgs `pkgs.lib.licenses` attribute name
33
+ * (e.g. `"mit"`, `"asl20"`, `"unfree"`) or a `NixExpr`. SPDX-style ids
34
+ * like `"MIT"` or `"Apache-2.0"` are rejected at TS-eval time.
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * nix.binaryRelease({
39
+ * name: "azure-dev-cli",
40
+ * version: "1.25.5",
41
+ * binary: "azd",
42
+ * urlTemplate:
43
+ * "https://github.com/Azure/azure-dev/releases/download/azure-dev-cli_{version}/{file}",
44
+ * platforms: {
45
+ * "x86_64-linux": { file: "azd-linux-amd64.tar.gz", hash: "sha256-..." },
46
+ * "aarch64-linux": { file: "azd-linux-arm64.tar.gz", hash: "sha256-..." },
47
+ * "x86_64-darwin": { file: "azd-darwin-amd64.zip", hash: "sha256-..." },
48
+ * "aarch64-darwin":{ file: "azd-darwin-arm64.zip", hash: "sha256-..." },
49
+ * },
50
+ * meta: {
51
+ * description: "Azure Developer CLI",
52
+ * homepage: "https://github.com/Azure/azure-dev",
53
+ * license: "mit",
54
+ * },
55
+ * });
56
+ * ```
57
+ *
58
+ * @see {@link BinaryReleaseOpts} for the full options interface
59
+ */
17
60
  binaryRelease(opts: BinaryReleaseOpts): NixExpr;
18
61
  lib: {
19
62
  mkDefault(value: NixValue): NixExpr;
@@ -40,7 +83,10 @@ export interface BinaryReleasePlatform {
40
83
  export interface BinaryReleaseMeta {
41
84
  description: string;
42
85
  homepage?: string;
43
- /** SPDX-style license id (e.g. `"mit"`, `"asl20"`) or a raw `NixExpr`. */
86
+ /** nixpkgs `lib.licenses` attribute name (e.g. `"mit"`, `"asl20"`,
87
+ * `"unfree"`). **Not** an SPDX identifier: `"MIT"` and `"Apache-2.0"`
88
+ * will be rejected. Pass a `NixExpr` (e.g. `nix.expr("pkgs.lib.licenses.unfree")`)
89
+ * for licenses that aren't a simple attribute lookup. */
44
90
  license?: string | NixExpr;
45
91
  /** Defaults to the outer `binary`. */
46
92
  mainProgram?: string;
@@ -67,6 +67,9 @@ const KNOWN_BINARY_RELEASE_ARCHES = [
67
67
  "aarch64-darwin",
68
68
  ];
69
69
  function binaryRelease(opts) {
70
+ if (!opts || typeof opts !== "object") {
71
+ throw new Error("nix.binaryRelease: `opts` is required");
72
+ }
70
73
  if (!opts.name)
71
74
  throw new Error("nix.binaryRelease: `name` is required");
72
75
  if (!opts.version)
@@ -81,15 +84,33 @@ function binaryRelease(opts) {
81
84
  if (!opts.meta || !opts.meta.description) {
82
85
  throw new Error("nix.binaryRelease: `meta.description` is required");
83
86
  }
87
+ if (opts.platforms === undefined || opts.platforms === null) {
88
+ throw new Error("nix.binaryRelease: `platforms` is required");
89
+ }
90
+ if (!isPlainObject(opts.platforms)) {
91
+ throw new Error("nix.binaryRelease: `platforms` must be an object");
92
+ }
93
+ if (opts.meta.license !== undefined &&
94
+ typeof opts.meta.license === "string" &&
95
+ !isNixAttrName(opts.meta.license)) {
96
+ throw new Error(`nix.binaryRelease: \`meta.license\` string "${opts.meta.license}" is not a valid nixpkgs attribute name. ` +
97
+ `Use a \`pkgs.lib.licenses\` attr name like "mit" or "asl20", or pass \`nix.expr("...")\` for custom expressions.`);
98
+ }
84
99
  const entries = Object.entries(opts.platforms);
85
100
  const filtered = entries.filter((entry) => entry[1] !== undefined);
86
101
  if (filtered.length === 0) {
87
102
  throw new Error("nix.binaryRelease: at least one platform is required");
88
103
  }
89
- for (const [arch] of filtered) {
104
+ for (const [arch, platform] of filtered) {
90
105
  if (!KNOWN_BINARY_RELEASE_ARCHES.includes(arch)) {
91
106
  throw new Error(`nix.binaryRelease: unknown platform key "${arch}"`);
92
107
  }
108
+ if (!platform.file) {
109
+ throw new Error(`nix.binaryRelease: platforms.${arch}.file is required`);
110
+ }
111
+ if (!platform.hash) {
112
+ throw new Error(`nix.binaryRelease: platforms.${arch}.hash is required`);
113
+ }
93
114
  }
94
115
  const usesPlatformPlaceholder = opts.urlTemplate.includes("{platform}");
95
116
  if (usesPlatformPlaceholder) {
@@ -145,7 +166,10 @@ function binaryRelease(opts) {
145
166
  if (opts.completions && Object.values(opts.completions).some(Boolean)) {
146
167
  nativeInputs.push("[ pkgs.installShellFiles ]");
147
168
  }
148
- nativeInputs.push("pkgs.lib.optionals pkgs.stdenv.hostPlatform.isDarwin [ pkgs.unzip ]");
169
+ // `unzip` is needed for `.zip` archives on every platform, not just
170
+ // darwin (e.g. a Linux release that ships a single .zip). Adding it
171
+ // unconditionally is cheap and avoids a runtime failure in `unpackPhase`.
172
+ nativeInputs.push("[ pkgs.unzip ]");
149
173
  const nativeBuildInputsExpr = nativeInputs.length === 1
150
174
  ? nativeInputs[0]
151
175
  : nativeInputs.join("\n ++ ");
@@ -180,6 +204,7 @@ in pkgs.stdenvNoCC.mkDerivation {
180
204
  *.zip) unzip -q "$src" -d source ;;
181
205
  *.tar.gz) tar -xzf "$src" -C source ;;
182
206
  *.tgz) tar -xzf "$src" -C source ;;
207
+ *) echo "nix.binaryRelease: unsupported archive extension for $src" >&2; exit 1 ;;
183
208
  esac
184
209
  sourceRoot=source
185
210
  runHook postUnpack
@@ -344,6 +369,15 @@ function isNixExpr(value) {
344
369
  function isPlainObject(value) {
345
370
  return typeof value === "object" && value !== null && !Array.isArray(value);
346
371
  }
372
+ // A valid `pkgs.lib.licenses.<id>` attribute name. nixpkgs convention
373
+ // is lowercase-first (e.g. `mit`, `asl20`, `gpl3Only`, `unfree`). This
374
+ // deliberately rejects SPDX-style ids like `MIT` or `Apache-2.0` so the
375
+ // helper surfaces the error at TS-eval time with a clear message rather
376
+ // than producing invalid Nix or a confusing attribute lookup error.
377
+ const NIX_LICENSE_ATTR_NAME = /^[a-z][A-Za-z0-9_]*$/;
378
+ function isNixAttrName(value) {
379
+ return NIX_LICENSE_ATTR_NAME.test(value);
380
+ }
347
381
  const NIX_KEYWORDS = new Set([
348
382
  "assert",
349
383
  "else",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adrifer/winix",
3
- "version": "0.1.2-preview.3",
3
+ "version": "0.1.2",
4
4
  "description": "TypeScript-first system configuration for NixOS, nix-darwin, and Home Manager",
5
5
  "license": "MIT",
6
6
  "author": "Adrian Fernandez",